API Documentation

Summary

Members	Descriptions
class TheThingsNetwork	TTN device.
struct TTNRFSettings	RF settings for TX or RX.

class TheThingsNetwork

TTN device.

This class enables ESP32 devices with SX1272/73/76/77/78/79 LoRaWAN chips to communicate via The Things Network.

Only one instance of this class may be created.

Summary

Members	Descriptions
public TheThingsNetwork()	Constructs a new The Things Network device instance.
public ~TheThingsNetwork()	Destroys the The Things Network device instance.
public void reset()	Resets the LoRaWAN radio.
public 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.
public bool provision(const char * devEui,const char * appEui,const char * appKey)	Sets the credentials needed to activate the device via OTAA, without activating it.
public bool provisionWithMAC(const char * appEui,const char * appKey)	Sets the information needed to activate the device via OTAA, using the MAC to generate the device EUI and without activating it.
public void startProvisioningTask()	Starts task listening on configured UART for AT commands.
public void waitForProvisioning()	Waits until the device EUI, app EUI and app key have been provisioned by the provisioning task.
public bool join()	Activates the device via OTAA.
public bool join(const char * devEui,const char * appEui,const char * appKey)	Sets the device EUI, app EUI and app key and activate the device via OTAA.
public TTNResponseCode transmitMessage(const uint8_t * payload,size_t length,port_t port,bool confirm)	Transmits a message.
public void onMessage(TTNMessageCallback callback)	Sets the function to be called when a message is received.
public 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*).
public void setRSSICal(int8_t rssiCal)	Sets the RSSI calibration value for LBT (Listen Before Talk).
public bool adrEnabled()	Returns whether Adaptive Data Rate (ADR) is enabled.
public void setAdrEnabled(bool enabled)	Enables or disabled Adaptive Data Rate (ADR).
public void shutdown()	Stops all activies and shuts down the RF module and the background tasks.
public void startup()	Restarts the background tasks and RF module.
public TTNRxTxWindow rxTxWindow()	Gets current RX/TX window.
public TTNRFSettings getRFSettings(TTNRxTxWindow window)	Gets the RF settings for the specified window.
public TTNRFSettings txSettings()	Gets the RF settings of the last (or ongoing) transmission.
public TTNRFSettings rx1Settings()	Gets the RF settings of the last (or ongoing) reception of RX window 1.
public TTNRFSettings rx2Settings()	Gets the RF settings of the last (or ongoing) reception of RX window 2.
public int rssi()	Gets the received signal strength indicator (RSSI).

Members

public TheThingsNetwork()

Constructs a new The Things Network device instance.

public ~TheThingsNetwork()

Destroys the The Things Network device instance.

public void reset()

Resets the LoRaWAN radio.

To restart communication, join() must be called. It neither clears the provisioned keys nor the configured pins.

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

Before calling this member function, the SPI bus needs to be configured using spi_bus_initialize(). Additionally, gpio_install_isr_service() must have been 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

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

Sets the credentials needed to activate the device via OTAA, without activating it.

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() to activate the device.

Parameters

• 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, false if the provisioning failed

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

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

The generated device EUI and 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.

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 data can be entered into the Device EUI field in the TTN console.

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() to activate.

Parameters

• 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, false if the provisioning failed

public void startProvisioningTask()

Starts task listening on configured UART for AT commands.

Run make menuconfig to configure it.

public void waitForProvisioning()

Waits until the device EUI, app EUI and app key have been provisioned by the provisioning task.

If the device has already been provisioned (stored data in NVS, call of provision() or call of join(const char*, const char*, const char*), this function immediately returns.

public bool join()

Activates the device via OTAA.

The app EUI, app key and dev EUI must have already 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.

Returns

true if the activation was succesful, false if the activation failed

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

Sets 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

• 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 succesful, false if the activation failed

public TTNResponseCode transmitMessage(const uint8_t * payload,size_t length,port_t port,bool confirm)

Transmits 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

• payload bytes to be transmitted

• length number of bytes to be transmitted

• port port (defaults to 1)

• confirm flag indicating if a confirmation should be requested. Defaults to false

Returns

kTTNSuccessfulTransmission for successful transmission, kTTNErrorTransmissionFailed for failed transmission, kTTNErrorUnexpected for unexpected error

public void onMessage(TTNMessageCallback callback)

Sets 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(). 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

public 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*).

Returns

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

public void setRSSICal(int8_t rssiCal)

Sets the RSSI calibration value for LBT (Listen Before Talk).

This value is added to RSSI measured prior to decision. It must include the guardband. Ignored in US, EU, IN and other countries where LBT is not required. Defaults to 10 dB.

Parameters

• rssiCal RSSI calibration value, in dB

public bool adrEnabled()

Returns whether Adaptive Data Rate (ADR) is enabled.

Returns

true if enabled, false if disabled

public void setAdrEnabled(bool enabled)

Enables or disabled Adaptive Data Rate (ADR).

ADR is enabled by default. It optimizes data rate, airtime and energy consumption for devices with stable RF conditions. It should be turned off for mobile devices.

Parameters

• enabled true to enable, false to disable

public void shutdown()

Stops all activies and shuts down the RF module and the background tasks.

To restart communication, startup() and join() must be called. it neither clears the provisioned keys nor the configured pins.

public void startup()

Restarts the background tasks and RF module.

This member function must only be called after a call to shutdowna().

public TTNRFSettings rxTxWindow()

Gets current RX/TX window.

Returns

window

public TTNRFSettings getRFSettings(TTNRxTxWindow window)

Gets the RF settings for the specified window.

Parameters

• window RX/TX windows (valid values are kTTNTxWindow, kTTNRx1Window and kTTNRx2Window)

public TTNRFSettings txSettings()

Gets the RF settings of the last (or ongoing) transmission.

Returns

RF settings

public TTNRFSettings rx1Settings()

Gets the RF settings of the last (or ongoing) reception of RX window 1.

Returns

RF settings

public TTNRFSettings rx2Settings()

Gets the RF settings of the last (or ongoing) reception of RX window 2.

Returns

RF settings

public int rssi()

Gets the received signal strength indicator (RSSI).

RSSI is the measured signal strength of the last recevied message (incl. join responses).

Returns

RSSI, in dBm

struct TTNRFSettings

RF settings for TX or RX.

Summary

Members	Descriptions
public TTNSpreadingFactor spreadingFactor	Spreading Factor (SF)
public TTNBandwidth bandwidth	Bandwidth (BW)
public uint32_t frequency	Frequency, in Hz.

Members

public TTNSpreadingFactor spreadingFactor

Spreading Factor (SF)

public TTNBandwidth bandwidth

Bandwidth (BW)

public uint32_t frequency

Frequency, in Hz.