TTN device. More...

#include <TheThingsNetwork.h>

Public Member Functions
	TheThingsNetwork ()
	Constructs a new The Things Network device instance.

	~TheThingsNetwork ()
	Destroys the The Things Network device instance.

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

void	setSubband (int band)
	Sets the frequency sub-band to be used. More...

bool	provision (const char devEui, const char appEui, const char *appKey)
	Sets the keys needed to activate the device via OTAA, without activating it. More...

bool	provisionTransiently (const char devEui, const char appEui, const char *appKey)
	Sets the keys needed to activate the device via OTAA, without activating it. More...

bool	provisionWithMAC (const char appEui, const char appKey)
	Sets the information needed to activate the device via OTAA, using the MAC to generate the DevEUI and without activating it. More...

void	startProvisioningTask ()
	Starts task listening on configured UART for AT commands. More...

void	waitForProvisioning ()
	Waits until the DevEUI, AppEUI/JoinEUI and AppKey have been provisioned by the provisioning task. More...

bool	join ()
	Activates the device via OTAA using previously provisioned keys. More...

bool	join (const char devEui, const char appEui, const char *appKey)
	Activates the device via OTAA using the provided keys. More...

bool	resumeAfterDeepSleep ()
	Resumes TTN communication after deep sleep. More...

bool	resumeAfterPowerOff (int off_duration)
	Resumes TTN communication after power off. More...

void	prepareForDeepSleep ()
	Stops all activies and prepares for deep sleep. More...

void	prepareForPowerOff ()
	Stops all activies and prepares for power off. More...

void	waitForIdle ()
	Waits until the TTN device is idle. More...

TickType_t	busyDuration ()
	Returns the minimum duration the TTN device is busy. More...

void	shutdown ()
	Stops all activies. More...

TTNResponseCode	transmitMessage (const uint8_t *payload, size_t length, ttn_port_t port=1, bool confirm=false)
	Transmits a message. More...

void	onMessage (TTNMessageCallback callback)
	Sets the function to be called when a message is received. More...

bool	isProvisioned ()
	Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage or have been provided by a call to join(const char, const char, const char) or to provisionTransiently(const char, const char, const char). More...

void	setRSSICal (int8_t rssiCal)
	Sets the RSSI calibration value for LBT (Listen Before Talk). More...

bool	adrEnabled ()

void	setAdrEnabled (bool enabled)
	Enables or disabled Adaptive Data Rate (ADR). More...

void	setDataRate (TTNDataRate data_rate)
	Sets the transmission data rate (i.e. the data rate for uplink messages). More...

void	setMaxTxPower (int tx_pow)
	Sets the maximum power for transmission. More...

TTNRxTxWindow	rxTxWindow ()
	Gets current RX/TX window. More...

TTNRFSettings	getRFSettings (TTNRxTxWindow window)
	Gets the RF settings for the specified window. More...

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

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

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

int	rssi ()
	Gets the received signal strength indicator (RSSI). More...

Detailed Description

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.

Member Function Documentation

◆ adrEnabled()

bool TheThingsNetwork::adrEnabled ( )

Returns whether Adaptive Data Rate (ADR) is enabled.

Returns: true if enabled, false if disabled

◆ busyDuration()

TickType_t TheThingsNetwork::busyDuration ( )

Returns the minimum duration the TTN device is busy.

This function can be called to check whether the TTN device is still involved in communication or ready to go to deep sleep or to be powered off.

If it returns 0, the TTN communication is idle and the device can go to deep sleep or can be powered off.

If it returns a value different from 0, the value indicates the duration the device will be certainly busy. After that time, this function must be called again. It might still return a value different from 0.

Returns: busy duration (in FreeRTOS ticks)

◆ configurePins()

void TheThingsNetwork::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

◆ getRFSettings()

TTNRFSettings TheThingsNetwork::getRFSettings ( TTNRxTxWindow window )

Gets the RF settings for the specified window.

Parameters

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

◆ isProvisioned()

bool TheThingsNetwork::isProvisioned ( )

Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage or have been provided by a call to join(const char*, const char*, const char*) or to provisionTransiently(const char*, const char*, const char*).

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

◆ join() [1/2]

bool TheThingsNetwork::join ( )

Activates the device via OTAA using previously provisioned keys.

The DevEUI, AppEUI/JoinEUI and AppKey must have already been provisioned by a call to provision() or provisionWithMAC(). Before this function is called, nvs_flash_init() must have been called once.

The RF module is initialized and the TTN background task is started.

The function blocks until the activation has completed or failed.

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

◆ join() [2/2]

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

Activates the device via OTAA using the provided keys.

For the activation, the provided DevEUI, AppEUI/JoinEUI and AppKey are used. They are NOT saved in non-volatile memory.

The RF module is initialized and the TTN background task is started.

The function blocks until the activation has completed or failed.

Parameters

devEui	DevEUI (16 character string with hexadecimal data)
appEui	AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
appKey	AppKey of the device (32 character string with hexadecimal data)

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

◆ onMessage()

void TheThingsNetwork::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 a call to transmitMessage(). The callback is called in the task that called this function and it occurs before this function returns control to the caller.

Parameters

callback the callback function

◆ prepareForDeepSleep()

void TheThingsNetwork::prepareForDeepSleep ( )

Stops all activies and prepares for deep sleep.

This function is called before entering deep sleep. It saves the current communication state in RTC memory and shuts down the RF module and the TTN background task.

It neither clears the provisioned keys nor the configured pins but they will be lost if the device goes into deep sleep.

Before calling this function, use busyDuration() to check that the TTN device is idle and ready to go to deep sleep.

To restart communication, resumeAfterDeepSleep() must be called.

◆ prepareForPowerOff()

void TheThingsNetwork::prepareForPowerOff ( )

Stops all activies and prepares for power off.

This function is called before powering off the device. It saves the current communication state in NVS (non-volatile storage) and shuts down the RF module and the TTN background task.

It neither clears the provisioned keys nor the configured pins but they will be lost if the device is powered off.

Before calling this function, use busyDuration() to check that the TTN device is idle and ready to be powered off.

To restart communication, resumeAfterPowerOff(int) must be called.

Before this function is called, nvs_flash_init() must have been called once.

◆ provision()

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

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

The provided DevEUI, AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before this function is called, nvs_flash_init() must have been called once.

In order to reduce flash wear, this function detects if the keys have not changed and will not write them again.

Call join() to activate the device.

Parameters

devEui	DevEUI (16 character string with hexadecimal data)
appEui	AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
appKey	AppKey of the device (32 character string with hexadecimal data)

Returns: true if the provisioning was successful, false if the provisioning failed

◆ provisionTransiently()

bool TheThingsNetwork::provisionTransiently	(	const char *	devEui,
		const char *	appEui,
		const char *	appKey
	)

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

The provided DevEUI, AppEUI/JoinEUI and AppKey are only stored in RAM and will be lost when the device is powered off or put in deep sleep.

Call join() to activate the device.

Parameters

devEui	DevEUI (16 character string with hexadecimal data)
appEui	AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
appKey	AppKey of the device (32 character string with hexadecimal data)

Returns: true if the provisioning was successful, false if the provisioning failed

◆ provisionWithMAC()

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

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

The generated DevEUI and the provided AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before this function is called, nvs_flash_init must have been called once.

In order to reduce flash wear, this function detects if the keys have not changed and will not write them again.

The DevEUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a DevEUI 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 DevEUI field in the TTN console.

Generating the DevEUI from the MAC address allows to flash the same AppEUI/JoinEUI and AppKey to a batch of devices. However, using the same AppKey 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	AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
appKey	AppKey of the device (32 character string with hexadecimal data)

Returns: true if the provisioning was successful, false if the provisioning failed

◆ resumeAfterDeepSleep()

bool TheThingsNetwork::resumeAfterDeepSleep ( )

Resumes TTN communication after deep sleep.

The communcation state is restored from data previously saved in RTC memory. The RF module and the TTN background task are started.

This function is called instead of join() or join(const char*, const char*, const char*) to continue with the established communication and to avoid a further join procedure.

Returns: true if the device was able to resume, false otherwise.

◆ resumeAfterPowerOff()

bool TheThingsNetwork::resumeAfterPowerOff ( int off_duration )

Resumes TTN communication after power off.

The communcation state is restored from data previously saved in NVS (non-volatile storage). The RF module and the TTN background task are started.

This function is called instead of join() or join(const char*, const char*, const char*) to continue with the established communication and to avoid a further join procedure.

In order to advance the clock, the estimated duration the device was powered off has to be specified. As the exact duration is probably not known, an estimation of the shortest duration between power-off and next power-on can be used instead.

If the device has access to the real time, set the system time (using settimeofday()) before calling this function (and before join()) and pass 0 for off_duration.

Before this function is called, nvs_flash_init() must have been called once.

Parameters

off_duration duration the device was powered off (in minutes)

Returns: true if the device was able to resume, false otherwise.

◆ rssi()

int TheThingsNetwork::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

◆ rx1Settings()

TTNRFSettings TheThingsNetwork::rx1Settings ( )

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

Returns: RF settings

◆ rx2Settings()

TTNRFSettings TheThingsNetwork::rx2Settings ( )

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

Returns: RF settings

◆ rxTxWindow()

TTNRxTxWindow TheThingsNetwork::rxTxWindow ( )

Gets current RX/TX window.

Returns: window

◆ setAdrEnabled()

void TheThingsNetwork::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

◆ setDataRate()

void TheThingsNetwork::setDataRate ( TTNDataRate data_rate )

Sets the transmission data rate (i.e. the data rate for uplink messages).

If ADR is enabled, it's is used as the initial data rate and later adjusted depending on the RF conditions. If ADR is disabled, it is used for all uplink messages.

Parameters

data_rate data rate (use constants of enum TTNDataRate)

◆ setMaxTxPower()

void TheThingsNetwork::setMaxTxPower ( int tx_pow )

Sets the maximum power for transmission.

The power is specified in dBm and sets the power emitted by the radio. If the antenna has a gain, it must be substracted from the specified value to achieve the correct transmission power.

Parameters

tx_pow power, in dBm

◆ setRSSICal()

void TheThingsNetwork::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

◆ setSubband()

void TheThingsNetwork::setSubband ( int band )

Sets the frequency sub-band to be used.

For regions with sub-bands (USA, Australia), sets the sub-band to be used for uplink communication. For other regions, this function has no effect.

The sub-band must be set before joining or sending the first message.

If not set, it defaults to sub-band 2 as defined by TTN.

Parameters

band	band (0 for all bands, or value between 1 and 8)

◆ shutdown()

void TheThingsNetwork::shutdown ( )

Stops all activies.

This function shuts down the RF module and the TTN background task. It neither clears the provisioned keys nor the configured pins. The currentat device state (and activation) are lost.

To restart communication, join() or join(const char*, const char*, const char*) must be called.

◆ startProvisioningTask()

void TheThingsNetwork::startProvisioningTask ( )

Starts task listening on configured UART for AT commands.

Run make menuconfig to configure it.

◆ transmitMessage()

TTNResponseCode TheThingsNetwork::transmitMessage	(	const uint8_t *	payload,
		size_t	length,
		ttn_port_t	port = `1`,
		bool	confirm = `false`
	)

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

◆ txSettings()

TTNRFSettings TheThingsNetwork::txSettings ( )

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

Returns: RF settings

◆ waitForIdle()

void TheThingsNetwork::waitForIdle ( )

Waits until the TTN device is idle.

If the TTN device is idle, the ESP32 can go into deep sleep mode or be powered off without disrupting an on-going communication.

◆ waitForProvisioning()

void TheThingsNetwork::waitForProvisioning ( )

Waits until the DevEUI, AppEUI/JoinEUI and AppKey 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.

The documentation for this class was generated from the following file:

TheThingsNetwork.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ adrEnabled()

◆ busyDuration()

◆ configurePins()

◆ getRFSettings()

◆ isProvisioned()

◆ join() [1/2]

◆ join() [2/2]

◆ onMessage()

◆ prepareForDeepSleep()

◆ prepareForPowerOff()

◆ provision()

◆ provisionTransiently()

◆ provisionWithMAC()

◆ resumeAfterDeepSleep()

◆ resumeAfterPowerOff()

◆ rssi()

◆ rx1Settings()

◆ rx2Settings()

◆ rxTxWindow()

◆ setAdrEnabled()

◆ setDataRate()

◆ setMaxTxPower()

◆ setRSSICal()

◆ setSubband()

◆ shutdown()

◆ startProvisioningTask()

◆ transmitMessage()

◆ txSettings()

◆ waitForIdle()

◆ waitForProvisioning()