Skip to content
This repository has been archived by the owner on Oct 21, 2020. It is now read-only.

Latest commit

 

History

History
670 lines (397 loc) · 28.3 KB

DOCUMENTATION.md

File metadata and controls

670 lines (397 loc) · 28.3 KB
Raw

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