When something isn't working as expected, it might be useful to take a peek "under the hood", to find out what exactly is RadioLib doing, and where it might be failing. For that purpose, there's a couple of debugging options that can be used.
Enabling debug
To enable debug, you can go to the BuildOptUser.h file, and uncomment any of these lines:
//#define RADIOLIB_DEBUG_BASIC (1) // basic debugging (e.g. reporting GPIO timeouts or module not being found)
//#define RADIOLIB_DEBUG_PROTOCOL (1) // protocol information (e.g. LoRaWAN internal information)
//#define RADIOLIB_DEBUG_SPI (1) // verbose transcription of all SPI communication - produces large debug logs!
Any combination of debug levels may be enabled, information from different levels are distinguished by a prefix.
The default debug port is set to Serial, on most Arduino boards, this should correspond to the Serial port connected to USB. If you want to use a different port, simply change the value of RADIOLIB_DEBUG_PORT macro to e.g. Serial2, or whichever Serial port you want to use. SoftwareSerial ports are supported as well.
NOTE: RadioLib DOES NOT automatically initialize the debug port with Serial.begin(). This is done to prevent collisions when user already calls the begin() method from Arduino sketch. For that reason, debug interface initialization MUST be done prior to RadioLib module initialization (e.g. radio.begin(), otherwise there will be no debug output from the begin() method.
On non-Arduino platforms, RADIOLIB_DEBUG_PORT defaults to stdout.
Debug levels
RADIOLIB_DEBUG_BASIC ("RLB_DBG")
Enabling this macro will only print out basic debug info - for example, timeouts when waiting for GPIO signals or radio module not being found due to version register mismatch.
RADIOLIB_DEBUG_PROTOCOL ("RLB_PRO")
Enabling this macro will print information important for debugging protocols. This is very useful when debugging LoRaWAN.
RADIOLIB_DEBUG_SPI ("RLB_SPI")
Enabling this macro will print out full transcript of all SPI communication. It should be noted that this outputs A LOT of information in the debug log. This can make debugging higher levels (e.g. protocols) cumbersome, so it should only be used when investigating issues with the radio module itself.
Assertions
During runtime, RadioLib performs checks to make sure any error is caught as quickly as possible. This is done using a simple assertion macro that will return when the result of a previous operation was a not-OK status code. Therefore, any given public API method returns immediately after encountering an error. However, that error may be propagated through multiple layers of the library before reaching the user. To make tracing such failures easier, RadioLib provides the macro RADIOLIB_VERBOSE_ASSERT. If set to 1, this macro will print a trace of the failure (including source file and line information) using the RADIOLIB_DEBUG_BASIC debug level. Enabling this macro will also enable RADIOLIB_DEBUG_BASIC. Keep in mind that as with any debugging, this will increase the size of the binary! An example output is shown below, with the last two lines showing the file and line information of the failed assertions.
19:22:18.593 -> RLB_DBG: RadioLib Info
19:22:18.593 -> Version: "6.6.0.0"
19:22:18.593 -> Platform: "Adafruit nRF52"
19:22:18.593 -> Compiled: "Aug 4 2024" "16:26:06"
19:22:18.870 -> RLB_DBG: LR11x0 not found! (1 of 10 tries) RADIOLIB_LR11X0_CMD_GET_VERSION = 0x01
19:22:18.870 -> RLB_DBG: Expected: 0x03
(...)
19:22:21.785 -> RLB_DBG: LR11x0 not found! (10 of 10 tries) RADIOLIB_LR11X0_CMD_GET_VERSION = 0x01
19:22:21.785 -> RLB_DBG: Expected: 0x03
19:22:21.785 -> RLB_DBG: No LR11x0 found!
19:22:21.785 -> RLB_DBG: RADIOLIB_ASSERT -2 at C:\Users\user\Documents\Arduino\libraries\RadioLib\src\modules\LR11x0\LR11x0.cpp:19
19:22:21.785 -> RLB_DBG: RADIOLIB_ASSERT -2 at C:\Users\user\Documents\Arduino\libraries\RadioLib\src\modules\LR11x0\LR1120.cpp:11