API Reference

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

DiscoveryOptions #

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

Properties

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

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»

getDeviceAddress #

Return a device address for the given constraints.

Parameters

• usage Array<Usage> The list for wich the address will be used.

Returns Promise<Buffer> address - A buffer containing the address.

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 (application messages):

• 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.

MQTT connection events:

• error: An error occured / the initial connection failed.
• connect: A connection to the MQTT broker was established.
• disconnect: The connection to the MQTT broker was lost.
• reconnect: A reconnect to the MQTT broker is attempted.
• close: A connection (attempt) failed.

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