RadioLib: an SX1278 LoRa radio with status codes for every call
RadioLib, by Jan Gromes, drives dozens of radio chips through one style of API: SX127x and SX126x LoRa radios, CC1101, RF69, nRF24 and more. Every call returns an int status, RADIOLIB_ERR_NONE (0) on success and a negative code naming the problem otherwise, which makes failures far easier to diagnose than a bare true or false.
Built in on Mokxi: #include <RadioLib.h> and it builds, with nothing to install. Free, and no account needed.
What RadioLib does
You describe the wiring with a Module: chip select, the interrupt pin (DIO0 on an SX127x), reset, and a second interrupt pin (DIO1). The radio object takes that Module, and begin() with no arguments picks RadioLib鈥檚 defaults for the chip, which on an SX1278 are 434 MHz, 125 kHz bandwidth, spreading factor 9 and coding rate 4/7.
transmit() and receive() block until the packet has gone or arrived. For a receiver that does other work, call startReceive() once, register a function with setPacketReceivedAction(), set a flag in it, and call readData() from loop() when the flag is up.
| Library Manager name | RadioLib |
|---|---|
| Author | Jan Gromes |
| Include | #include <RadioLib.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Runs, with a gap the note below names. |
| Parts it drives | LoRa module, SX1278 (Ra-02) |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <RadioLib.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "RadioLib" by Jan Gromes from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add RadioLib to lib_deps in PlatformIO. Mokxi follows the calls of release 7.1.2, so a sketch written here builds there too.
What to know in the simulator: Only the SX127x radios in LoRa mode: SX126x, SX128x, CC1101 and RadioLib鈥檚 other modules are not declared, and beginFSK is not here.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
SX1278 radio = new Module(10, 2, 9, 3)
Creates an SX1278 on NSS 10, DIO0 2, RESET 9 and DIO1 3. SX1276 and RFM95 are the same class family with their own names.
int state = radio.begin()
Starts the radio with RadioLib鈥檚 defaults, or with frequency, bandwidth and spreading factor given as arguments. Compare the result with RADIOLIB_ERR_NONE.
int state = radio.begin(433.0);
if (state != RADIOLIB_ERR_NONE) {
Serial.print("failed, code ");
Serial.println(state);
while (true);
}radio.transmit("Hello World!")
Sends a string or a byte array and waits until it is out. Returns RADIOLIB_ERR_PACKET_TOO_LONG for more than 255 bytes.
radio.receive(str)
Waits for a packet and fills a String or buffer. Returns RADIOLIB_ERR_RX_TIMEOUT when nothing came in time.
radio.setPacketReceivedAction(setFlag)
Calls your function from the DIO0 interrupt when a packet arrives. Mark it ICACHE_RAM_ATTR on ESP boards and only set a flag inside it.
radio.startReceive()
Puts the radio in continuous receive mode for interrupt-driven sketches.
radio.readData(str)
Reads the packet that arrived, after the flag says one did.
radio.getRSSI()
The last packet鈥檚 signal strength in dBm. getSNR() gives the signal to noise ratio.
radio.setSpreadingFactor(10)
Changes the spreading factor (6 to 12) after begin(). Like the other modem settings, it must match on both radios.
Example: Transmit with an SX1278
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <RadioLib.h>
// NSS, DIO0, RESET, DIO1
SX1278 radio = new Module(10, 2, 9, 3);
void setup() {
Serial.begin(9600);
Serial.print(F("[SX1278] Initializing ... "));
int state = radio.begin();
if (state == RADIOLIB_ERR_NONE) {
Serial.println(F("success!"));
} else {
Serial.print(F("failed, code "));
Serial.println(state);
while (true);
}
}
void loop() {
Serial.print(F("[SX1278] Transmitting packet ... "));
int state = radio.transmit("Hello World!");
if (state == RADIOLIB_ERR_NONE) {
Serial.println(F("success!"));
} else {
Serial.print(F("failed, code "));
Serial.println(state);
}
delay(300);
}Wiring
- Arduino Uno R3 13 to LoRa module, SX1278 (Ra-02) SCK
- Arduino Uno R3 11 to LoRa module, SX1278 (Ra-02) MOSI
- Arduino Uno R3 12 to LoRa module, SX1278 (Ra-02) MISO
- Arduino Uno R3 10 to LoRa module, SX1278 (Ra-02) NSS
- Arduino Uno R3 9 to LoRa module, SX1278 (Ra-02) RST
- Arduino Uno R3 2 to LoRa module, SX1278 (Ra-02) DIO0
- Arduino Uno R3 3 to LoRa module, SX1278 (Ra-02) DIO1
- Arduino Uno R3 3V3 to LoRa module, SX1278 (Ra-02) 3.3V
- Arduino Uno R3 GND to LoRa module, SX1278 (Ra-02) GND
Common errors and how to fix them
failed, code -2
RADIOLIB_ERR_CHIP_NOT_FOUND: no SX127x answered on SPI. Check NSS and RESET in the Module match the wiring, the SPI pins, and the 3.3 V supply. A wrong class (SX1262 code on an SX1278 module) gives the same code.
receive() returns -6 every time
That is a timeout: nothing arrived with matching settings. Make frequency, bandwidth, spreading factor, coding rate and sync word the same on both radios, and attach both antennas.
'SX1262' was not declared in this scope in Mokxi
Mokxi simulates RadioLib鈥檚 SX127x LoRa classes only, so other radios are not declared and beginFSK() is not there. Run SX1276, SX1278 or RFM95 sketches, or try the sx1278 part with the LoRa library.
Keep going
More communication libraries
Try RadioLib without installing anything
Open the example, change the sketch, and keep your version in a free account.