RadioLib Documentation

RadioLib is a universal wireless communication library for embedded devices designed to integrate various wireless communication modules, protocols, and digital modes into a single consistent system. It provides a hardware abstraction layer that allows it to run in both Arduino and non-Arduino environments.

Key resources:

• Wiki: General usage information.
• FAQ: Frequently asked questions.
• API Reference: Full automatically generated API documentation.
• Status Code Decoder: Decodes status codes returned by methods.
• Debug Log Decoder: Decodes SPI debug logs.

RadioLib supports both Over-the-Air Activation (OTAA) and Activation by Personalization (ABP).

• OTAA (Recommended): The standard and preferred method for most use cases.
• ABP: Use the LoRaWAN_ABP example if you specifically require ABP.

Warning: When using ABP, the full session must persist through resets and power loss to comply with the LoRaWAN specification. You will need to implement proper Non-Volatile Memory (NVM) handling to manage this.

LoRaWAN is designed for low-power, infrequent transmissions.

• Uplink Interval: Aim for intervals between 15 minutes and once per day to maximize battery life (2-5 years on AA batteries).
• Duty Cycle: Be aware of legal limits on transmission time (often 1% or 0.1% depending on the region).
• Fair Use Policy (FUP): On TTN Sandbox, limit airtime to 30 seconds per day and approximately 10 downlinks per day. A common recommendation is 1 downlink per fortnight for configuration updates.
• Payload Efficiency: Avoid sending text/strings. Send data as a sequence of bytes to minimize airtime and improve reliability. For example, split a 16-bit integer into two bytes using highByte() and lowByte() before transmission.

RadioLib provides support for advanced LoRaWAN device classes and communication patterns:

• Class C: Useful for continuously-powered devices (e.g., mains-powered lights) that need to receive data at any time. This is implemented on top of Class A using the LoRaWAN_Class_C example.
• Multicast: If you are deploying groups of similar devices (e.g., a series of street lights), use Multicast over Class C instead of individual Class C implementations. See the LoRaWAN_Multicast example for implementation details.

For new users, the LoRaWAN_Starter example is the recommended entry point. It is highly recommended to read the accompanying notes.md file within that example directory to understand LoRaWAN fundamentals and specific RadioLib implementation details before proceeding.

Note: These examples are intended for rapid development. For production-ready devices, you must implement persistence (e.g., using NVM) to ensure session data survives resets and power loss. See the radiolib-persistence repository for guidance.

RadioLib can be integrated into the Tock embedded operating system using libtock-c. This allows RadioLib to run as a concurrent application on Cortex-M or RISC-V based platforms.

To build the application, you must clone the RadioLib repository and a specific version of libtock-c. You can skip the RISC-V RadioLib build by setting the SKIP_RISCV environment variable.

Note: This specific example has been tested on the SparkFun LoRa Thing Plus - expLoRaBLE board, but it is compatible with any LoRa-capable Tock board.

$ git clone https://github.com/jgromes/RadioLib.git
$ cd RadioLib/examples/NonArduino/Tock/
$ git clone https://github.com/tock/libtock-c.git
$ cd libtock-c; git checkout c0202f9ab78da4a6e95f136cf5250701e3778f63; cd ../
$ LIBTOCK_C_DIRECTORY="$(pwd)/libtock-c" ./build.sh

While RadioLib natively supports Arduino, it can be ported to non-Arduino environments using its internal hardware abstraction layer.

For guidance on porting, refer to the Porting to non-Arduino Platforms Wiki page and examine the NonArduino examples.

The RadioLib HAL requires a high-resolution delay() to ensure accurate radio timings (e.g., LoRaWAN RX1/RX2 windows).

Recommended Setup: Set the FreeRTOS tick rate to 1000 Hz by adding CONFIG_FREERTOS_HZ=1000 to your sdkconfig.defaults. This ensures the HAL builds successfully and timings are precise.

Low Tick Rate Workaround: If you cannot change the tick rate, you can bypass the build check by defining RADIOLIB_RELAX_RTOS_TICK=1 during compilation.

Warning: In this mode, delay() uses a combination of sleeping and busy-waiting (esp_rom_delay_us()). The busy-wait portion can be as long as one tick period (e.g., 10 ms at 100 Hz), which increases CPU and power consumption.

To avoid waiting for long LoRaWAN join cycles and uplink intervals while debugging sensor logic, use this workflow:

1. Write a separate sketch that reads your sensors.
2. Output the resulting byte array to the Serial console.
3. Copy the hex array from the Serial monitor.
4. Paste the hex array into the TTN Console Payload Formatters section to verify your decoding logic works correctly.