DOCUMENTATION.md

Table of Contents

• Application
• key
• is-token
• setup
• PayloadFunctions
• open
• AccountClient
  • getAllApplications
  • getApplication
  • createApplication
  • deleteApplication
  • addCollaborator
  • deleteCollaborator
  • addEUI
  • deleteEUI
• HandlerClient
  • open
  • data
  • application
• ApplicationClient
  • constructor
  • get
  • setPayloadFormat
  • setCustomPayloadFunctions
  • setRegisterOnJoinAccessKey
  • unregister
  • devices
  • registerDevice
  • device
  • updateDevice
  • deleteDevice
  • getEUIs
• DiscoveryOptions
• ApplicationSettings
• DataClient
  • constructor
  • close
  • end
  • on
  • off
  • send
• Service
• application
• app
• Announcement
• data
• account
• Discovery
  • constructor
  • getAll
  • get
  • getByAppID
• AppAccessRights
• services
  • Handler
  • Router
  • Broker
• MinimalAccApplication
• AccountApplication

Application

Application is an application on the network.

Type: {appId: string, payloadFormat: PayloadFormat, decoder: string?, converter: string?, validator: string?, encoder: string?, registerOnJoinAccessKey: string?}

Properties

• appId string
• payloadFormat PayloadFormat
• decoder string?
• converter string?
• validator string?
• encoder string?
• registerOnJoinAccessKey string?

key

Generates a new key to be used for Lora

Parameters

• length number (optional, default 16)

is-token

Returns true if the passed in string is a json web token, and false otherwise. It does NOT validate the token signature.

Parameters

• str string

Returns boolean

A token that can register ApplicationSettings

setup

Setup function that prepares the environment with the required application and devices for testing.

PayloadFunctions

PayloadFunctions is an object that bundles the payload functions of an application.

Type: {decoder: string?, converter: string?, validator: string?, encoder: string?}

Properties

• decoder string?
• converter string?
• validator string?
• encoder string?

open

open creates and opens a HandlerClient for the application with the specified ID.

Parameters

• appID string The ID of the application you want to manage.
• accessKerOrToken string
• opts DiscoveryOptions? Optional options to pass to the Discovery client.
• tokenOrKey The Access Token or Access Key used to authenticate.

Returns Promise<HandlerClient>

AccountClient

Account is a client for The Things Network account server API. It can be used to manage applications and their EUIs, as well as gateways. Either a Bearer Token or an Application Access Key can be used for authentication. The latter method allows to use the getApplication() function only.

Example:

const account = new Account("accesKeyOrToken", "https://customserveradress.org")

Parameters

• accessKeyOrToken string
• serverAddress string (optional, default "https://account.thethingsnetwork.org")

getAllApplications

Gets metadata about all applications that are accessible with the given accessToken

Returns Promise<Array<AccountApplication>>

getApplication

Gets the information that is stored about a given application. This includes the EUIs, name access keys, collaborators. The properties that can be retrieved depend on the rights of the used authorization mechanism.

Parameters

• appID string

Returns Promise<AccountApplication>

createApplication

Creates a new application on the account server.

Parameters

• app MinimalAccApplication

Returns Promise<any>

deleteApplication

Removes an application from the account server.

Parameters

• appID string

Returns Promise<any>

addCollaborator

Adds a collaborator with a set of access rights to the given application.

Parameters

• appID string
• collaborator string
• rights Array<AppAccessRights>

Returns Promise<any>

deleteCollaborator

Removes a collaborator by her username from an application

Parameters

• appID string
• collaborator string

Returns Promise<any>

addEUI

Adds an EUI to the given application. Must be hexadecimal with a length of 16.

Parameters

• appID string
• eui string

Returns Promise<any>

deleteEUI

Removes an EUI from the given application.

Parameters

• appID string
• eui string

Returns Promise<any>

HandlerClient

Handler is a client for The Things Network handler APIs. It can be used to get data from an application or to manage devices.

Example:

const handler = new Handler("my-app-id", "my-app-access-key")

Parameters

• appID string
• appAccessKey string
• opts DiscoveryOptions?

open

open opens the client to the handler.

Returns Promise<HandlerClient>

data

Open a data client that can be used to receive live application data

Returns DataClient

application

Open a application manager that can be used to manage the settings and devices of the application.

Returns ApplicationClient

ApplicationClient

A client that manages devices on the handler.

Parameters

• appID string
• tokenOrKey string
• netAddress string
• certificate (Buffer | string)?

constructor

Create and open an application manager client that can be used for retreiving and updating an application and its devices.

Parameters

• appID string The ID of the application you want to manage
• tokenOrKey string The Access Token or Access Key used to authenticate
• netAddress string The gRPC address of the handler where the application is registered
• certificate (Buffer | string)? An optional certificate used to connect to the handler securely

Returns void

get

Get the application

Returns Promise<Application>

setPayloadFormat

Change the payload format of the application.

Parameters

• format PayloadFormat

Returns Promise<void>

setCustomPayloadFunctions

Set the custom payload functions of the application and set the format to custom.

Parameters

• fns PayloadFunctions (optional, default {})

Returns Promise<void>

setRegisterOnJoinAccessKey

Set the registerOnJoinAccessKey or remove it.

Parameters

• to string

Returns Promise<void>

unregister

Unregister the application from the handler.

Returns Promise<void>

devices

List the devices of the application

Returns Promise<Array<Device>>

registerDevice

Register a device in the application.

Parameters

• devID string
• device DeviceUpdates

Returns Promise<void>

device

Get the device specified by the devID

Parameters

• devID string

Returns Promise<Device>

updateDevice

Update the device specified by the devID with the specified updates

Parameters

• devID string
• updates DeviceUpdates

Returns Promise<void>

deleteDevice

Delete the specified device.

Parameters

• devID string

Returns Promise<void>

getEUIs

Returns the EUI(s) for this application from the account server.

Returns Promise<Array<string>>

DiscoveryOptions

Type: {address: string?, insecure: boolean?, certificate: (Buffer | string)?}

Properties

• address string?
• insecure boolean?
• certificate (Buffer | string)?

ApplicationSettings

ApplicationSettings hold the settings of an application.

Type: {payloadFormat: PayloadFormat?, registerOnJoinAccessKey: string?}

Properties

• payloadFormat PayloadFormat?
• registerOnJoinAccessKey string?

DataClient

DataClient is a client for The Things Network data API.

Parameters

• appID string
• appAccessKey string
• mqttAddress string

constructor

Creates a new DataClient and opens the MQTT connection.

Parameters

• appID string
• appAccessKey string
• mqttAddress string

Returns void

close

Close the mqtt connection

Parameters

• force boolean? passing it to true will close the client right away, without waiting for the in-flight messages to be acked
• callback Function? will be called when the client is closed

end

Same as close (for backwards compatibility).

Parameters

• force boolean?
• callback Function?

on

Starts listening to events.

Possible events are:

• uplink (or message): Messages sent by the devices to the appliction.
• activation: An alias for the activations (see event)
• event (or device): Events that happen to devices. You can filter on the events by adding more parameters. For instance:
  • downlink/scheduled
  • downlink/sent
  • activations
  • create
  • update
  • delete
  • down/acks
  • up/errors
  • down/errors
  • activations/errors

See The MQTT API Reference for more information about these events and what their payloads look like.

Parameters

• event string The name of the event to listen to.
• args ...Array<any>
• devID An optional devID. If not passed will subscribe to the event for all devices.
• callback The callback to call when the event occurs.

Examples

// listens to all uplinks from all devices
client.on("uplink", function (devID, message) {})

// listens to all uplinks from the device with id `foo`
client.on("uplink", "foo", function (devID, message) {})

// listens to all device events for all devices
client.on("event", function (devID, message) {})

// listens to all device events for device with id `foo`
client.on("event", "foo", function (devID, message) {})

// listens to the `downlink/scheduled` events for device with id `foo`
client.on("event", "foo", "downlink/scheduled", function (devID, message) {})

// listens to the `downlink/scheduled` events for all devices
client.on("event", "+", "downlink/scheduled", function (devID, message) {})

Returns void

off

Stop listening to events. The argument structure is the same as for on().

Parameters

• event string
• args ...Array<any>

Returns void

send

Send a downlink message to the device with the specified device ID.

Parameters

• devID DeviceID The device ID of the device to send the downlink to.
• payload (PayloadArray | PayloadRaw | String | PayloadFields) The raw payload as a Buffer, an Array of numbers, a hex string or an object of payload fields.
• port number The port to send the message on.
• confirmed boolean Set to true for confirmed downlink.
• schedule Schedule Set to the scheduling you want to use (first, last or replace).

Service

Service is an enum of the possible services types to get from the discovery server.

Type: ("router" | "broker" | "handler")

application

application creates and opens an ApplicationClient for the application with the specified ID.

Parameters

• appID string The ID of the application you want to manage
• accessKeyOrToken string The Access Token or Access Key used to authenticate
• opts DiscoveryOptions?

Returns Promise<ApplicationClient>

app

The app used for testing

Settings for the discovery server

Announcement

Announcement is an announcement on the discovery server.

Type: {id: string, serviceName: Service, serviceVersion: string, description: string, pb_public: boolean, url: string, netAddress: string, mqttAddress: string, apiAddress: string, publicKey: string?, certificate: string?, metadataList: Array<any>?}

Properties

• id string
• serviceName Service
• serviceVersion string
• description string
• pb_public boolean
• url string
• netAddress string
• mqttAddress string
• apiAddress string
• publicKey string?
• certificate string?
• metadataList Array<any>?

data

data creates and opens an DataClient for the application with the specified ID.

Parameters

• appID string The ID of the application you want to manage
• accessKeyOrToken string The Access Token or Access Key used to authenticate
• opts DiscoveryOptions?

Returns Promise<DataClient>

Settings for the handler

account

account creates an AccountClient for the user associated to the specified key or token.

Parameters

• accessKeyOrToken string The Access Token or Access Key used to authenticate
• serverAddress string The URL to the account server to use. Defaults to "https://account.thethingsnetwork.org"

Returns AccountClient

Discovery

Discovery is a client for The Things Network discovery API

Parameters

• opts DiscoveryOptions (optional, default {})

constructor

Create a new Discovery client.

Parameters

• opts DiscoveryOptions (optional, default {})

Returns void

getAll

getAll returns announcements for all services known to the discovery server that match the service name.

Parameters

• serviceName Service The name of the services to look for, eg. "handler"

Returns Promise<Array<Announcement>>

get

get returns the announcement for the service with the specified service name and id.

Parameters

• serviceName Service The name of the services to look for, eg. "handler"
• id string The id of the service to look for, eg. "ttn-handler-eu"

Returns Promise<Announcement>

getByAppID

getByAppID gets a handler announcement by application ID. It looks up the handler the application is registered to.

Parameters

• appID string

Returns Promise<Announcement>

AppAccessRights

AppAccessRights

Type: ("settings" | "delete" | "collaborators" | "devices" | "messages:up:r" | "messages:up:w" | "messages:down:w")

services

services is a map with the known service names for the discovery server.

Type: {}

Handler

Handler is a Handler service

Router

Router is a Router service

Broker

Broker is a Broker service

MinimalAccApplication

The minimal payload for to the POST /applications route of the account server

Type: {id: string, name: string}

Properties

• id string
• name string

AccountApplication

AccountApplication contains the metadata of an application returned by the account server. Presence of optional fields depends on the access rights of the used accessKey / -token.

Type: any