Classes
struct	ttn_rf_settings_t
	RF settings for TX or RX. More...

Macros
#define	TTN_NOT_CONNECTED 0xff
	Constant for indicating that a pin is not connected.

Typedefs
typedef uint8_t	ttn_port_t
	Integer data type for specifiying the port of an uplink or downlink message.

typedef void(*	ttn_message_cb) (const uint8_t *payload, size_t length, ttn_port_t port)
	Callback for recieved messages.

Enumerations
enum	ttn_response_code_t { TTN_ERROR_TRANSMISSION_FAILED = -1 , TTN_ERROR_UNEXPECTED = -10 , TTN_SUCCESSFUL_TRANSMISSION = 1 , TTN_SUCCESSFUL_RECEIVE = 2 }
	Response codes. More...

enum	ttn_rx_tx_window_t { TTN_WINDOW_IDLE = 0 , TTN_WINDOW_TX = 1 , TTN_WINDOW_RX1 = 2 , TTN_WINDOW_RX2 = 3 }
	RX/TX window. More...

enum	ttn_spreading_factor_t { TTN_SF_NONE = 0 , TTN_FSK = 1 , TTN_SF7 = 2 , TTN_SF8 = 3 , TTN_SF9 = 4 , TTN_SF10 = 5 , TTN_SF11 = 6 , TTN_SF12 = 7 }
	Spreading Factor. More...

enum	ttn_bandwidth_t { TTN_BW_NONE = 0 , TTN_BW_125 = 1 , TTN_BW_250 = 2 , TTN_BW_500 = 3 }
	Bandwidth. More...

enum	ttn_data_rate_t { TTN_DR_AS923_SF12 = 0 , TTN_DR_AS923_SF11 = 1 , TTN_DR_AS923_SF10 = 2 , TTN_DR_AS923_SF9 = 3 , TTN_DR_AS923_SF8 = 4 , TTN_DR_AS923_SF7_BW125 = 5 , TTN_DR_AS923_SF7_BW250 = 6 , TTN_DR_AS923_FSK = 7 , TTN_DR_AU915_SF12 = 0 , TTN_DR_AU915_SF11 = 1 , TTN_DR_AU915_SF10 = 2 , TTN_DR_AU915_SF9 = 3 , TTN_DR_AU915_SF8 = 4 , TTN_DR_AU915_SF7 = 5 , TTN_DR_AU915_SF8_BW500 = 6 , TTN_DR_AU915_SF12_BW500 = 8 , TTN_DR_AU915_SF11_BW500 = 9 , TTN_DR_AU915_SF10_BW500 = 10 , TTN_DR_AU915_SF9_BW500 = 11 , TTN_DR_AU915_SF8_BW500_DR12 = 12 , TTN_DR_AU915_SF7_BW500 = 13 , TTN_DR_EU868_SF12 = 0 , TTN_DR_EU868_SF11 = 1 , TTN_DR_EU868_SF10 = 2 , TTN_DR_EU868_SF9 = 3 , TTN_DR_EU868_SF8 = 4 , TTN_DR_EU868_SF7_BW125 = 5 , TTN_DR_EU868_SF7_BW250 = 6 , TTN_DR_EU868_FSK = 7 , TTN_DR_IN866_SF12 = 0 , TTN_DR_IN866_SF11 = 1 , TTN_DR_IN866_SF10 = 2 , TTN_DR_IN866_SF9 = 3 , TTN_DR_IN866_SF8 = 4 , TTN_DR_IN866_SF7 = 5 , TTN_DR_IN866_FSK = 7 , TTN_DR_KR920_SF12 = 0 , TTN_DR_KR920_SF11 = 1 , TTN_DR_KR920_SF10 = 2 , TTN_DR_KR920_SF9 = 3 , TTN_DR_KR920_SF8 = 4 , TTN_DR_KR920_SF7 = 5 , TTN_DR_US915_SF10 = 0 , TTN_DR_US915_SF9 = 1 , TTN_DR_US915_SF8 = 2 , TTN_DR_US915_SF7 = 3 , TTN_DR_US915_SF8_BW500 = 4 , TTN_DR_US915_SF12_BW500 = 8 , TTN_DR_US915_SF11_BW500 = 9 , TTN_DR_US915_SF10_BW500 = 10 , TTN_DR_US915_SF9_BW500 = 11 , TTN_DR_US915_SF8_BW500_DR12 = 12 , TTN_DR_US915_SF7_BW500 = 13 , TTN_DR_JOIN_DEFAULT = 255 }
	Data Rate. More...

Functions
void	ttn_init (void)
	Initializes The Things Network device instance.

void	ttn_configure_pins (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.

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

bool	ttn_provision (const char dev_eui, const char app_eui, const char *app_key)
	Sets the keys needed to activate the device via OTAA, without activating it.

bool	ttn_provision_transiently (const char dev_eui, const char app_eui, const char *app_key)
	Sets the keys needed to activate the device via OTAA, without activating it.

bool	ttn_provision_with_mac (const char app_eui, const char app_key)
	Sets the information needed to activate the device via OTAA, using the MAC to generate the DevEUI and without activating it.

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

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

bool	ttn_join (void)
	Activates the device via OTAA using previously provisioned keys.

bool	ttn_join_with_keys (const char dev_eui, const char app_eui, const char *app_key)
	Activates the device via OTAA using the provided keys.

bool	ttn_resume_after_deep_sleep (void)
	Resumes TTN communication after deep sleep.

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

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

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

void	ttn_wait_for_idle (void)
	Waits until the TTN device is idle.

TickType_t	ttn_busy_duration (void)
	Returns the minimum duration the TTN device will be busy.

void	ttn_shutdown (void)
	Stops all activies.

ttn_response_code_t	ttn_transmit_message (const uint8_t *payload, size_t length, ttn_port_t port, bool confirm)
	Transmits a message.

void	ttn_on_message (ttn_message_cb callback)
	Sets the function to be called when a message is received.

bool	ttn_is_provisioned (void)
	Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage or have been provided by a call to ttn_join_with_keys() or to ttn_provision_transiently().

void	ttn_set_rssi_cal (int8_t rssi_cal)
	Sets the RSSI calibration value for LBT (Listen Before Talk).

bool	ttn_adr_enabled (void)

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

void	ttn_set_data_rate (ttn_data_rate_t data_rate)
	Sets the transmission data rate (i.e. the data rate for uplink messages).

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

ttn_rx_tx_window_t	ttn_rx_tx_window (void)
	Gets current RX/TX window.

ttn_rf_settings_t	ttn_get_rf_settings (ttn_rx_tx_window_t window)
	Gets the RF settings for the specified window.

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

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

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

int	ttn_rssi ()
	Gets the received signal strength indicator (RSSI).

Detailed Description

Typedef Documentation

◆ ttn_message_cb

typedef void(* ttn_message_cb) (const uint8_t *payload, size_t length, ttn_port_t port)

Callback for recieved messages.

Parameters

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

Enumeration Type Documentation

◆ ttn_bandwidth_t

enum ttn_bandwidth_t

Bandwidth.

Enumerator
TTN_BW_NONE	Undefined/unused bandwidth.
TTN_BW_125	Bandwidth of 125 kHz.
TTN_BW_250	Bandwidth of 250 kHz.
TTN_BW_500	Bandwidth of 500 kHz.

◆ ttn_data_rate_t

enum ttn_data_rate_t

Data Rate.

Note that the spreading factor, bandwidth, bit rate and maximum message size associated with each data rate depends on the region.

Enumerator
TTN_DR_AS923_SF12	Data rate for region AS923 using SF12 and 125 kHz bandwidth.
TTN_DR_AS923_SF11	Data rate for region AS923 using SF11 and 125 kHz bandwidth.
TTN_DR_AS923_SF10	Data rate for region AS923 using SF10 and 125 kHz bandwidth.
TTN_DR_AS923_SF9	Data rate for region AS923 using SF9 and 125 kHz bandwidth.
TTN_DR_AS923_SF8	Data rate for region AS923 using SF8 and 125 kHz bandwidth.
TTN_DR_AS923_SF7_BW125	Data rate for region AS923 using SF7 and 125 kHz bandwidth.
TTN_DR_AS923_SF7_BW250	Data rate for region AS923 using SF7 and 250 kHz bandwidth.
TTN_DR_AS923_FSK	Data rate for region AS923 using FSK and 50 kpbs.
TTN_DR_AU915_SF12	Data rate for region AU915 using SF12 and 125 kHz bandwidth.
TTN_DR_AU915_SF11	Data rate for region AU915 using SF11 and 125 kHz bandwidth.
TTN_DR_AU915_SF10	Data rate for region AU915 using SF10 and 125 kHz bandwidth.
TTN_DR_AU915_SF9	Data rate for region AU915 using SF9 and 125 kHz bandwidth.
TTN_DR_AU915_SF8	Data rate for region AU915 using SF8 and 125 kHz bandwidth.
TTN_DR_AU915_SF7	Data rate for region AU915 using SF7 and 125 kHz bandwidth.
TTN_DR_AU915_SF8_BW500	Data rate for region AU915 using SF8 and 500 kHz bandwidth.
TTN_DR_AU915_SF12_BW500	Data rate for region AU915 using SF12 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_AU915_SF11_BW500	Data rate for region AU915 using SF11 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_AU915_SF10_BW500	Data rate for region AU915 using SF10 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_AU915_SF9_BW500	Data rate for region AU915 using SF9 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_AU915_SF8_BW500_DR12	Data rate for region AU915 using SF8 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_AU915_SF7_BW500	Data rate for region AU915 using SF7 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_EU868_SF12	Data rate for region EU868 using SF12 and 125 kHz bandwidth.
TTN_DR_EU868_SF11	Data rate for region EU868 using SF11 and 125 kHz bandwidth.
TTN_DR_EU868_SF10	Data rate for region EU868 using SF10 and 125 kHz bandwidth.
TTN_DR_EU868_SF9	Data rate for region EU868 using SF9 and 125 kHz bandwidth.
TTN_DR_EU868_SF8	Data rate for region EU868 using SF8 and 125 kHz bandwidth.
TTN_DR_EU868_SF7_BW125	Data rate for region EU868 using SF7 and 125 kHz bandwidth.
TTN_DR_EU868_SF7_BW250	Data rate for region EU868 using SF7 and 250 kHz bandwidth.
TTN_DR_EU868_FSK	Data rate for region EU868 using FSK and 50 kpbs.
TTN_DR_IN866_SF12	Data rate for region IN866 using SF12 and 125 kHz bandwidth.
TTN_DR_IN866_SF11	Data rate for region IN866 using SF11 and 125 kHz bandwidth.
TTN_DR_IN866_SF10	Data rate for region IN866 using SF10 and 125 kHz bandwidth.
TTN_DR_IN866_SF9	Data rate for region IN866 using SF9 and 125 kHz bandwidth.
TTN_DR_IN866_SF8	Data rate for region IN866 using SF8 and 125 kHz bandwidth.
TTN_DR_IN866_SF7	Data rate for region IN866 using SF7 and 125 kHz bandwidth.
TTN_DR_IN866_FSK	Data rate for region IN866 using FSK and 50 kpbs.
TTN_DR_KR920_SF12	Data rate for region KR920 using SF12 and 125 kHz bandwidth.
TTN_DR_KR920_SF11	Data rate for region KR920 using SF11 and 125 kHz bandwidth.
TTN_DR_KR920_SF10	Data rate for region KR920 using SF10 and 125 kHz bandwidth.
TTN_DR_KR920_SF9	Data rate for region KR920 using SF9 and 125 kHz bandwidth.
TTN_DR_KR920_SF8	Data rate for region KR920 using SF8 and 125 kHz bandwidth.
TTN_DR_KR920_SF7	Data rate for region KR920 using SF7 and 125 kHz bandwidth.
TTN_DR_US915_SF10	Data rate for region US915 using SF10 and 125 kHz bandwidth.
TTN_DR_US915_SF9	Data rate for region US915 using SF9 and 125 kHz bandwidth.
TTN_DR_US915_SF8	Data rate for region US915 using SF8 and 125 kHz bandwidth.
TTN_DR_US915_SF7	Data rate for region US915 using SF7 and 125 kHz bandwidth.
TTN_DR_US915_SF8_BW500	Data rate for region US915 using SF8 and 500 kHz bandwidth.
TTN_DR_US915_SF12_BW500	Data rate for region US915 using SF12 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_US915_SF11_BW500	Data rate for region US915 using SF11 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_US915_SF10_BW500	Data rate for region US915 using SF10 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_US915_SF9_BW500	Data rate for region US915 using SF9 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_US915_SF8_BW500_DR12	Data rate for region US915 using SF8 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_US915_SF7_BW500	Data rate for region US915 using SF7 and 500 kHz bandwidth. Reserved for future applications.
TTN_DR_JOIN_DEFAULT	Default data rate for joining.

◆ ttn_response_code_t

enum ttn_response_code_t

Response codes.

Enumerator
TTN_ERROR_TRANSMISSION_FAILED	Transmission failed error.
TTN_ERROR_UNEXPECTED	Unexpected or internal error.
TTN_SUCCESSFUL_TRANSMISSION	Successful transmission of an uplink message.
TTN_SUCCESSFUL_RECEIVE	Successful receipt of a downlink message.

◆ ttn_rx_tx_window_t

enum ttn_rx_tx_window_t

RX/TX window.

Enumerator
TTN_WINDOW_IDLE	Outside RX/TX window.
TTN_WINDOW_TX	Transmission window (up to RX1 window)
TTN_WINDOW_RX1	Reception window 1 (up to RX2 window)
TTN_WINDOW_RX2	Reception window 2.

◆ ttn_spreading_factor_t

enum ttn_spreading_factor_t

Spreading Factor.

Enumerator
TTN_SF_NONE	Unused / undefined spreading factor.
TTN_FSK	Frequency Shift Keying (FSK)
TTN_SF7	Spreading Factor 7 (SF7)
TTN_SF8	Spreading Factor 8 (SF8)
TTN_SF9	Spreading Factor 9 (SF9)
TTN_SF10	Spreading Factor 10 (SF10)
TTN_SF11	Spreading Factor 11 (SF11)
TTN_SF12	Spreading Factor 12 (SF12)

Function Documentation

◆ ttn_adr_enabled()

bool ttn_adr_enabled ( void )

Returns whether Adaptive Data Rate (ADR) is enabled.

Returns: true if enabled, false if disabled

◆ ttn_busy_duration()

TickType_t ttn_busy_duration ( void )

Returns the minimum duration the TTN device will be 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)

◆ ttn_configure_pins()

void ttn_configure_pins	(	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.

Call this function after ttn_init() and before all other TTN functions.

Parameters

spi_host	The SPI bus/peripherial to use (`SPI1_HOST`, `SPI2_HOST`, `SPI3_HOST`, `FSPI_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

◆ ttn_get_rf_settings()

ttn_rf_settings_t ttn_get_rf_settings ( ttn_rx_tx_window_t window )

Gets the RF settings for the specified window.

Parameters

window RX/TX window (valid values are TTN_WINDOW_TX, TTN_WINDOW_RX1 and TTN_WINDOW_RX2

◆ ttn_init()

void ttn_init ( void )

Initializes The Things Network device instance.

Call this function once at the start of the program and before all other TTN functions.

◆ ttn_is_provisioned()

bool ttn_is_provisioned ( void )

Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage or have been provided by a call to ttn_join_with_keys() or to ttn_provision_transiently().

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

◆ ttn_join()

bool ttn_join ( void )

Activates the device via OTAA using previously provisioned keys.

The DevEUI, AppEUI/JoinEUI and AppKey must have already been provisioned by a call to ttn_provision() or ttn_provision_with_mac(). 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

◆ ttn_join_with_keys()

bool ttn_join_with_keys	(	const char *	dev_eui,
		const char *	app_eui,
		const char *	app_key )

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

dev_eui	DevEUI (16 character string with hexadecimal data)
app_eui	AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
app_key	AppKey of the device (32 character string with hexadecimal data)

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

◆ ttn_on_message()

void ttn_on_message ( ttn_message_cb 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 ttn_transmit_message(). 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

◆ ttn_prepare_for_deep_sleep()

void ttn_prepare_for_deep_sleep ( void )

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 ttn_busy_duration() to check that the TTN device is idle and ready to go to deep sleep.

To restart communication, ttn_resume_after_deep_sleep() must be called.

◆ ttn_prepare_for_power_off()

void ttn_prepare_for_power_off ( void )

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 ttn_busy_duration() to check that the TTN device is idle and ready to be powered off.

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

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

◆ ttn_provision()

bool ttn_provision	(	const char *	dev_eui,
		const char *	app_eui,
		const char *	app_key )

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

Parameters

dev_eui	DevEUI (16 character string with hexadecimal data)
app_eui	AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
app_key	AppKey of the device (32 character string with hexadecimal data)

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

◆ ttn_provision_transiently()

bool ttn_provision_transiently	(	const char *	dev_eui,
		const char *	app_eui,
		const char *	app_key )

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

Parameters

dev_eui	DevEUI (16 character string with hexadecimal data)
app_eui	AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
app_key	AppKey of the device (32 character string with hexadecimal data)

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

◆ ttn_provision_with_mac()

bool ttn_provision_with_mac	(	const char *	app_eui,
		const char *	app_key )

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

Parameters

app_eui	AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
app_key	AppKey of the device (32 character string with hexadecimal data)

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

◆ ttn_resume_after_deep_sleep()

bool ttn_resume_after_deep_sleep ( void )

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 ttn_join_with_keys() or ttn_join() to continue with the established communication and to avoid a further join procedure.

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

◆ ttn_resume_after_power_off()

bool ttn_resume_after_power_off ( 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 ttn_join_with_keys() or ttn_join() 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 ttn_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.

◆ ttn_rssi()

int ttn_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

◆ ttn_rx1_settings()

ttn_rf_settings_t ttn_rx1_settings ( void )

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

Returns: RF settings

◆ ttn_rx2_settings()

ttn_rf_settings_t ttn_rx2_settings ( void )

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

Returns: RF settings

◆ ttn_rx_tx_window()

ttn_rx_tx_window_t ttn_rx_tx_window ( void )

Gets current RX/TX window.

Returns: window

◆ ttn_set_adr_enabled()

void ttn_set_adr_enabled ( 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

◆ ttn_set_data_rate()

void ttn_set_data_rate ( ttn_data_rate_t 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 ttn_data_rate_t)

◆ ttn_set_max_tx_pow()

void ttn_set_max_tx_pow ( 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

◆ ttn_set_rssi_cal()

void ttn_set_rssi_cal ( int8_t rssi_cal )

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

rssi_cal RSSI calibration value, in dB

◆ ttn_set_subband()

void ttn_set_subband ( 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)

◆ ttn_shutdown()

void ttn_shutdown ( void )

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, ttn_join_with_keys() and ttn_join() must be called.

◆ ttn_start_provisioning_task()

void ttn_start_provisioning_task ( void )

Starts task listening on configured UART for AT commands.

Run make menuconfig to configure it.

◆ ttn_transmit_message()

ttn_response_code_t ttn_transmit_message	(	const uint8_t *	payload,
		size_t	length,
		ttn_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 (use 1 as default)
confirm	flag indicating if a confirmation should be requested (use `false` as default)

Returns: TTN_SUCCESSFUL_TRANSMISSION for successful transmission, TTN_ERROR_TRANSMISSION_FAILED for failed transmission, TTN_ERROR_UNEXPECTED for unexpected error

◆ ttn_tx_settings()

ttn_rf_settings_t ttn_tx_settings ( void )

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

Returns: RF settings

◆ ttn_wait_for_idle()

void ttn_wait_for_idle ( void )

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.

◆ ttn_wait_for_provisioning()

void ttn_wait_for_provisioning ( void )

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 ttn_join_with_keys(), this function immediately returns.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ttn_message_cb

Enumeration Type Documentation

◆ ttn_bandwidth_t

◆ ttn_data_rate_t

◆ ttn_response_code_t

◆ ttn_rx_tx_window_t

◆ ttn_spreading_factor_t

Function Documentation

◆ ttn_adr_enabled()

◆ ttn_busy_duration()

◆ ttn_configure_pins()

◆ ttn_get_rf_settings()

◆ ttn_init()

◆ ttn_is_provisioned()

◆ ttn_join()

◆ ttn_join_with_keys()

◆ ttn_on_message()

◆ ttn_prepare_for_deep_sleep()

◆ ttn_prepare_for_power_off()

◆ ttn_provision()

◆ ttn_provision_transiently()

◆ ttn_provision_with_mac()

◆ ttn_resume_after_deep_sleep()

◆ ttn_resume_after_power_off()

◆ ttn_rssi()

◆ ttn_rx1_settings()

◆ ttn_rx2_settings()

◆ ttn_rx_tx_window()

◆ ttn_set_adr_enabled()

◆ ttn_set_data_rate()

◆ ttn_set_max_tx_pow()

◆ ttn_set_rssi_cal()

◆ ttn_set_subband()

◆ ttn_shutdown()

◆ ttn_start_provisioning_task()

◆ ttn_transmit_message()

◆ ttn_tx_settings()

◆ ttn_wait_for_idle()

◆ ttn_wait_for_provisioning()