Troubleshooting Guide
This page sums up the most frequently encountered issues for different wireless modules and protocols.
| 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. |
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!
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.
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.
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.
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.