Warning:
This section contains documentation written for The Things Network V2, which is no longer maintained. See documentation for The Things Stack V3.

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

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

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

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

Returns Promise<AccountApplication>

createApplication #

Creates a new application on the account server.

Parameters

Returns Promise<any>

deleteApplication #

Removes an application from the account server.

Parameters

Returns Promise<any>

addCollaborator #

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

Parameters

Returns Promise<any>

deleteCollaborator #

Removes a collaborator by her username from an application

Parameters

Returns Promise<any>

addEUI #

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

Parameters

Returns Promise<any>

deleteEUI #

Removes an EUI from the given application.

Parameters

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

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

ApplicationClient #

A client that manages devices on the handler.

Parameters

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

Returns Promise<void>

setRegisterOnJoinAccessKey #

Set the registerOnJoinAccessKey or remove it.

Parameters

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

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

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

constructor #

Creates a new DataClient and opens the MQTT connection.

Parameters

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

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

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

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

Returns AccountClient

Discovery #

Discovery is a client for The Things Network discovery API

Parameters

constructor #

Create a new Discovery client.

Parameters

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

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

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