Troubleshooting guide for driver, the CMake development environment, and RF communication issues related to Ai-Thinker Ra-11 / Ra-11H modules (LR1121 RF chip).
Recommended build parameters:
-DBOARD=STM32F103CB -DRAC_RADIO=lr1121
Repository: git@github.com:Ai-Thinker-Open/ra11-ra20.git
RAC_RADIO should be used?| Module | Chip | CMake Parameter |
|---|---|---|
| Ra-11 / Ra-11H | LR1121 (LR11xx) | -DRAC_RADIO=lr1121 |
Driver locations:
smtc_rac_lib/radio_drivers/ — Register-level drivers smtc_rac_lib/smtc_ral/ — Radio Abstraction Layer (RAL) smtc_rac_lib/smtc_rac/ — Radio Access Controller (RAC / USP)lr2021 or sx1262 be used to build firmware for Ra-11?No. The firmware driver and pin configuration must match the actual chip. Always use lr1121 for Ra-11. Selecting the wrong chip may cause SPI communication failures, prevent the module from entering transmit or receive mode, or result in firmware that compiles successfully but produces no RF activity.
No. Within the LR11xx series, RTToF capability is primarily available on the LR1110 / LR1120; the LR1121 does not support ranging. Do not use rttof_manager / rttof_subordinate to test Ra-11. Use ping_pong, tx_cw, or periodical_uplink for communication verification.
Usually, no. When you select -DRAC_RADIO=lr1121, the board-level HAL handles antenna switching and LNA control according to the LR11xx configuration (for example, RADIO_LNA_CTRL). In the application, focus on ensuring matching of frequency, SF, BW, output power and antenna.
CMake caches the BOARD / RAC_RADIO settings. Please follow:
rm -rf build
cmake -S examples -B build -G Ninja \
-DCMAKE_BUILD_TYPE=MinSizeRel \
-DBOARD=STM32F103CB \
-DRAC_RADIO=lr1121
cmake --build build --target ping_pong
git clone git@github.com:Ai-Thinker-Open/ra11-ra20.git
# or
git clone https://github.com/Ai-Thinker-AIoT/ra11-ra20.git
cd ra11-ra20
All subsequent cmake commands should be run from the repository root.
sudo apt update
sudo apt install -y gcc-arm-none-eabi binutils-arm-none-eabi \
cmake ninja-build git stlink-tools
Recommended versions: CMake ≥ 3.25 and Ninja ≥ 1.11. Verify:
arm-none-eabi-gcc --version
cmake --version
ninja --version
The preferred approach is WSL2 with Ubuntu, using the same commands as on Linux. For native Windows builds, install the ARM GNU Toolchain, CMake, and Ninja, and make sure that arm-none-eabi-gcc is available in PATH.
You must explicitly specify the board type. For Ra-11, use:
-DBOARD=STM32F103CB
Ra-11 requires the following:
-DRAC_RADIO=lr1121
-DBOARD=NUCLEO_L476?For Ai-Thinker Ra-11 boards, use STM32F103CB. NUCLEO_L476 uses a different HAL. With the current repository pin configuration, the L4 target may fail because macros such as HW_MODEM_* are not defined. This is a board configuration mismatch, not a syntax issue in ping_pong.
rm -rf build
cmake -S examples -B build \
-G Ninja \
-DCMAKE_BUILD_TYPE=MinSizeRel \
-DBOARD=STM32F103CB \
-DRAC_RADIO=lr1121
cmake --build build --target ping_pong
Outputs: build/ping_pong.bin, build/ping_pong.hex, and the ELF file.
Make sure that you built an add_example target (e.g. ping_pong). The POST_BUILD invokes arm-none-eabi-objcopy. Check the log for messages such as Creating ping_pong.hex... / Creating ping_pong.bin..., and verify that arm-none-eabi-objcopy is available in PATH.
# st-flash
st-flash --connect-under-reset write build/ping_pong.bin 0x8000000
# or CMake flash target
cmake --build build --target flash_ping_pong
You can also use STM32CubeProgrammer with a .hex or .bin file, the SWD interface, and address 0x08000000.
axk_cmd_example/...?This optional example may not be present in the current source tree. The project is configured to skip it when its source files are missing. Run rm -rf build, then perform configure again.
undefined reference to main_xxx?Check:
examples/main.h#elif MAKEFILE_APP == ... branch in examples/main.c add_example(... "YOUR_APP" ...) must match the macro nameunexpected payload. Why?The most common cause is that both boards are configured as the default Manager. (both send PING and wait for PONG).
Correct configuration:
| Device | Configuration |
|---|---|
| Device A (Manager) | Default, without PING_PONG_START_AS_SUBORDINATE |
| Device B (Subordinate) | Add -DPING_PONG_START_AS_SUBORDINATE=ON, followed by reconfiguration and rebuilding |
Recommended power-on sequence: power on the Subordinate first, then the Manager.
In the log, prefix_received='80' (decimal) usually corresponds to ASCII 'P' (the first byte of PING/PONG). This indicates that a frame from the other device was received, but there is a mismatch in role configuration or payload parsing.
rm -rf build
cmake -S examples -B build \
-G Ninja \
-DCMAKE_BUILD_TYPE=MinSizeRel \
-DBOARD=STM32F103CB \
-DRAC_RADIO=lr1121 \
-DPING_PONG_START_AS_SUBORDINATE=ON
cmake --build build --target ping_pong
The following parameters must be identical on both devices (see in examples/main_examples/ping_pong_example/main_ping_pong.h):
RF_FREQ_IN_HZ (The example default is often 868100000. Adjust it according to the local regulations and module frequency band.) After changing these macros on either side, rebuild and re-program both boards.
The debug UART is typically configured for 115200 baud, 8N1 (pins are commonly PA9/PA10; refer to the board schematic for the actual pin assignments). You can use minicom, screen, PuTTY, or a serial assistant to view the logs.
Typical Manager logs follow this sequence: starting ping-pong as manager → sending → TX success → receiving → RX success → payload is correct, with the counter increasing.
Check in sequence:
smtc_rac_run_engine() -DRAC_RADIO=lr1121 matches the hardware ENABLE_PERIODIC_UPLINK may conflict with ping-pong transactions.)Typical connections to the STM32F103CBT6 are listed below (refer to the repository’s HAL / modem_pinout):
| MCU | RF Side | Function |
|---|---|---|
| PA4 | NSS | SPI chip select |
| PA5 | SCK | SPI clock |
| PA6 | MISO | SPI MISO |
| PA7 | MOSI | SPI MOSI |
| PB14 | NRST | RF reset |
| PB1 | DIO1 | Interrupt |
| PA0 | BUSY | Busy signal |
The LR1121 driver handles antenna switching / LNA control according to the board-level definitions. Do not apply the Ra-20 LEGACY_EVK_LR20XX configuration approach to the LR1121.
This is almost always caused by omitting the following call from the main loop:
smtc_rac_run_engine( );
RAC / radio_planner relies on this function to drive the state machine.
| Symptom | Troubleshooting Direction |
|---|---|
rp_hook_init panic |
smtc_rac_open_radio() may be called repeatedly at the same priority |
radio_access_id is out of range |
The radio ID is invalid or has been closed |
smtc_rac_submit_radio_transaction panic |
Misconfigured context (e.g., RX buffer smaller than max_rx_size) |
HARDFAULT_Handler |
NULL callback pointer (e.g., callback_post_radio_transaction). |
Use the function names and line numbers in the logs to inspect smtc_rac and radio_planner.
-DBOARD=STM32F103CB -DRAC_RADIO=lr1121 rm -rf build and then re-run configure after changing the configuration.smtc_rac_run_engine() in the main loop. This document covers only Ra-11 / Ra-11H with LR1121. For Ra-20, refer to FAQ_ra20_cn.md.