API Documentation

Class TheThingsNetwork

TheThingsNetwork()

Construct a new The Things Network device instance.

~TheThingsNetwork()

Destroy the The Things Network device instance.

void reset()

Reset the LoRaWAN radio.

Does not clear provisioned keys.

void configurePins(spi_host_device_t spi_host, uint8_t nss, uint8_t rxtx, uint8_t rst, uint8_t dio0, uint8_t dio1)

Configures the pins used to communicate with the LoRaWAN radio chip.

The SPI bus must be first configured using spi_bus_initialize(). Then it is passed as the first parameter.

Additionally, gpio_install_isr_service() must be called to initialize the GPIO ISR handler service.

Parameters

• spi_host: The SPI bus/peripherial to use (SPI_HOST, HSPI_HOST or VSPI_HOST).
• nss: The GPIO pin number connected to the radio chip's NSS pin (serving as the SPI chip select)
• rxtx: The GPIO pin number connected to the radio chip's RXTX pin (TTN_NOT_CONNECTED if not connected)
• rst: The GPIO pin number connected to the radio chip's RST pin (TTN_NOT_CONNECTED if not connected)
• dio0: The GPIO pin number connected to the radio chip's DIO0 pin
• dio1: The GPIO pin number connected to the radio chip's DIO1 pin

bool provision(const char* devEui, const char* appEui, const char* appKey)

Sets the information needed to activate the device via OTAA, without actually activating.

The provided device EUI, app EUI and app key are saved in non-volatile memory. Before this function is called, nvs_flash_init() must have been called once. Call join() without arguments to activate.

Call join() without arguments to activate.

Parameters and return values

• devEui: Device EUI (16 character string with hexadecimal data)
• appEui: Application EUI of the device (16 character string with hexadecimal data)
• appKey: App Key of the device (32 character string with hexadecimal data)
• returns true if the provisioning was successful
• returns false if the provisioning failed

bool provisionWithMAC(const char* appEui, const char* appKey)

Sets the information needed to activate the device via OTAA, using the MAC address to generate the device EUI and without actually activating.

The generated device EUI, the provided app EUI and app key are saved in non-volatile memory. Before this function is called, nvs_flash_init() must have been called once. Call join() without arguments to activate.

The device EUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a device EUI by adding FFFE in the middle. So the MAC address A0:B1:C2:01:02:03 becomes the EUI A0B1C2FFFE010203. This hexadecimal value has to be entered into the Device EUI field when registering or modifying a device in the TTN console. This generated hardware EUI can queried with the AT command AT+HWEUI? – even before provisioning the device.

Generating the device EUI from the MAC address allows to flash the same app EUI and app key to a batch of devices. However, using the same app key for multiple devices is insecure. Only use this approach if it is okay for that the LoRa communication of your application can easily be intercepted and that forged data can be injected.

Call join() without arguments to activate.

Parameters and return values

• appEui: Application EUI of the device (16 character string with hexadecimal data)
• appKey: App Key of the device (32 character string with hexadecimal data)
• returns true if the provisioning was successful
• returns false if the provisioning failed

void startProvisioningTask()

Start task that listens on configured UART for provisioning commands.

Run make menuconfig to configure it.

The commands and the task configuration are described in AT Commands.

void waitForProvisioning()

Wait until the device EUI, app EUI and app key have been provisioned via the provisioning task.

If device is already provisioned (stored data in NVS, call to provision() or call to join(const char*, const char*, const char*), this function immediately returns.

bool join()

Activate the device using OTAA (over-the-air activation).

The app EUI, app key and dev EUI must already have been provisioned by a call to provision(). Before this function is called nvs_flash_init() must have been called once.

The function blocks until the activation has completed or failed.

Return values

• returns true if the activation was succeful
• returns false if the activation failed

bool join(const char* devEui, const char* appEui, const char* appKey)

Set the device EUI, app EUI and app key and activate the device via OTAA.

The device EUI, app EUI and app key are NOT saved in non-volatile memory.

The function blocks until the activation has completed or failed.

Parameters and return values

• devEui: Device EUI (16 character string with hexadecimal data)
• appEui: Application EUI of the device (16 character string with hexadecimal data)
• appKey: App Key of the device (32 character string with hexadecimal data)
• returns true if the activation was succeful
• returns false if the activation failed

TTNResponseCode transmitMessage(const uint8_t* payload, size_t length, port_t port = 1, bool confirm = false);

Transmit a message.

The function blocks until the message could be transmitted and a message has been received in the subsequent receive window (or the window expires). Additionally, the function will first wait until the duty cycle allows a transmission (enforcing the duty cycle limits).

Parameters and return values

• payload: bytes to be transmitted
• length: number of bytes to be transmitted
• port: port (default to 1)
• confirm: flag indicating if a confirmation should be requested. Defaults to false
• returns TkTTNSuccessfulTransmission if transmission was successful
• returns kTTNErrorTransmissionFailed if transmission failed
• returns TkTTNErrorUnexpected if an unexpected error occurred

void onMessage(TTNMessageCallback callback)

Set the function to be called when a message is received.

When a message is received, the specified function is called. The message, its length and the port number are provided as parameters. The values are only valid during the duration of the callback. So they must be immediately processed or copied.

Messages are received as a result of transmitMessage() or poll(). The callback is called in the task that called any of these functions and it occurs before these functions return control to the caller.

Parameters

• callback: the callback function

Also see

• TTNMessageCallback

bool isProvisioned()

Checks if device EUI, app EUI and app key have been stored in non-volatile storage or have been provided as by a call to join(const char*, const char*, const char*).

Return values

• returns true if they are stored, complete and of the correct size
• returns false otherwise

Required headers

#include "TheThingsNetwork.h"

Type TTNMessageCallback

Callback for received messages

Definition

typedef void (* TTNMessageCallback)(const uint8_t* payload, size_t length, port_t port)

• payload: pointer to the received bytes
• length: number of received bytes
• port: port the message was received on