This page sums up the most frequently encountered issues for different wireless modules and protocols. All RadioLib status codes can be found here.
We also have an online Status Code Decoder to help identifying different status codes.
Troubleshooting summary
| Symptom | Error code | Cause |
|---|---|---|
| Erratic radio module behavior, instability | any | Hardware issues |
| Radio or MCU reset on transmit | N/A | Insufficient power supply |
| Unable to initialize radio | -2 or -16 | Incorrect SPI interface, bad pinout, bad/unreliable connections |
| Transmit timeout | -5 | End of transmission is signalled by an interrupt signal, and this error means that signal did not arrive in the expected time window. Check your pinout and/or wiring. |
| Receiver timeout (no LoRaWAN) | -6 | Blocking receive mode |
| SX126x/8x failed to initialize | -706 or -707 | Incorrect oscillator selected |
| ESP32/ESP8266 interrupts do not work | N/A | Missing IRAM_ATTR from user-provided interrupt service routine. This is a property of the ESP32/ESP8266 architectures when using Arduino and has nothing to do with RadioLib, see espressif's documentation. |
| No downlink after LoRaWAN uplink | -1116 | Not all uplinks to LoRaWAN server result in a downlink. This is not a problem, but rather a common behavior in LoRaWAN. |
| Output power lower than configured | N/A | Overcurrent protection is likely set to the default value (change it by radio.setCurrentLimit()). This can also be caused by insufficient power supply. |
Hardware issues
Bad logic level voltage
Some Arduino boards (especially the older ones based on ATmega MCUs, such as Arduino Uno or Arduino Nano) have a 5V logic level. This means that on digital pins such as SPI, logic 1 is represented by a voltage level of 5V. However, most commonly used radio modules DO NOT tolerate 5V logic! In these cases, you have to use a logic level converter, such as this one.
If you ignore this, your radio module might appear to be working, but can behave erratically and eventually, it will most likely stop working altogether. Note that the logic level voltage is something else than the power supply voltage!
Insufficient power supply
Most Arduino boards include a voltage regulator that outputs regulated voltage. Usually, it is not a good idea to use this regulator to power your wireless module, as on higher output power settings, the regulator might not be able to provide enough power for both the Arduino as well as the radio module. Typical symptoms of insufficient power are the Arduino/MCU resetting when trying to transmit.
Use a dedicated, properly filtered linear (not switched!) regulator to power the radio.
Configuration issues
Incorrect SPI interface
Some platforms support multiple SPI interfaces. If you do not use the correct one, RadioLib will not be able to initialize the module (typically ending in a -2 or -16 error code). See this wiki page for details on how to select the correct SPI interface.
Usage issues
Receiver timeout
The receive method is a blocking method - this means that it will block executuion until an event occurs. In case of RadioLib, this is either packet being received, or a timeout. If the method finishes with a timeout, it will report a -6 error code. However, this can be expected if there were no packets received during the receive window.
SX126x/SX128x incorrect oscillator
The SX126x/8x LoRa modules support two different oscillator types - temperature-compensated crystal oscillator (TCXO) or a crystal oscillator (XTAL). The type of oscillator used in any given SX126x/8x module is up to the module manufacturer. By default, RadioLib assumes TCXO to be used (since it seems to be the more common choice). However, if your module contains an XTAL, it will fail to initialize with the default settings, usually reutrning error code -707 or -706. To let RadioLib know your module is using XTAL instead of TCXO, either set SX126x::XTAL to true before calling begin, or set tcxoVoltage argument of begin to 0.