Skip to content
Manuel Bl edited this page Aug 2, 2020 · 6 revisions

The ttn-esp32 library is based on IBM's LMIC library. It adds a simpler high-level API and focuses on The Things Network. Plain LoRa is not supported.

The LMIC code is a based on MCCI's Arduino LMIC library. It seems to be the most actively maintained LMIC library. The ESP32 (and ESP-IDF) specific hardware abstraction layer (HAL) is a completely independent work. The high-level API (i.e. the TheThingsNetwork class) was inspired by the official The Things Network library.

API Design

As FreeRTOS (part of ESP-IDF) provides multi-tasking (unlike the Arduino ecosystem), it makes sense that all TTN functions block until they have completed the operation even if the operation takes several seconds or minutes. It greatly simplifies the use of the library. Other tasks continue to run.

For ease of use, it was also decided to use a C++ class (instead of a bunch of C structures and functions). It better encapsulates the related operations and leads to shorter code. As a result, the callers of the library must also be written in C++.

Background task

The LMIC code mostly runs in a background task that is created when the TheThingsNetwork instance is initialized. It usually runs LMIC code when the DIO lines indicate an event or when a scheduled job is ready to be run.

Interrupt handler communicate with the background task using task notifications. So do timers. So the background task either executes LMIC code or it waits for the next notification.

Communication

In the figure, the term caller task is used for the task that calls the ttn-esp32 library. If there is work to do, the caller task will use a task notification to wake up the background task and have it do LoRA work. The caller will wait until the background task has completed the work. As part of the work, the background task might also wait for events (e.g. waiting until the RX window has expired or data is received).

Once the background task has completed the operation, it will post the status to a queue (the caller queue in the above figure). The caller task implements the waiting as the waiting for the next element in the caller queue.

AES encryption

For AES encryption, the ESP32's dedicated hardware unit is used. Given the small amount of data transferred, the speed gain is negligible. However, the code size shrinks by about 5 kBytes.

DIOx pins

The Arduino LMIC library can optionally poll the SX127x status register in the run loop, i.e. many times a second. Even though this is not optimal, it can work without wiring the DIOx pins. The ttn-esp32 library does not implement polling and requires the DIO0 and DIO1 pins to be connected to the ESP32.

Clone this wiki locally