Ra-11 / Ra-11H 开发 FAQ

面向安信可 Ra-11 / Ra-11H（射频芯片 LR1121）的驱动、CMake 开发环境与射频通信问题排查。

推荐编译参数：

-DBOARD=STM32F103CB -DRAC_RADIO=lr1121

仓库：git@github.com:Ai-Thinker-Open/ra11-ra20.git

1. 芯片与驱动

Q1.1 Ra-11 对应哪个驱动 / 该用哪个 `RAC_RADIO`？

模组	芯片	CMake 参数
Ra-11 / Ra-11H	LR1121（LR11xx）	`-DRAC_RADIO=lr1121`

驱动位置：

smtc_rac_lib/radio_drivers/ — 寄存器级驱动
smtc_rac_lib/smtc_ral/ — Radio Abstraction Layer（RAL）
smtc_rac_lib/smtc_rac/ — Radio Access Controller（RAC / USP）

Q1.2 能不能用 `lr2021` / `sx1262` 来编 Ra-11？

不能。固件里的驱动与引脚逻辑必须和实际芯片一致。Ra-11 请固定使用 lr1121。用错芯片会出现 SPI 通信失败、无法进收发、或看似编译通过但射频无反应。

Q1.3 LR1121 支持 RTToF 测距吗？

不支持。LR11xx 系列中 RTToF 能力主要面向 LR1110 / LR1120；LR1121 无测距。请勿用 rttof_manager / rttof_subordinate 验证 Ra-11。可用 ping_pong、tx_cw、periodical_uplink 等做通信验证。

Q1.4 天线切换 / LNA 需要自己在应用里写吗？

一般不需要。选用 -DRAC_RADIO=lr1121 后，板级 HAL 会按 LR11xx 配置处理天线开关与 LNA（如 RADIO_LNA_CTRL 等）。应用侧重点保证频率、SF、BW、功率与天线匹配即可。

Q1.5 更换芯片或板型后行为怪异、仍像旧驱动？

CMake 会缓存 BOARD / RAC_RADIO。请：

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

2. 开发环境与编译烧录

Q2.1 工程从哪里获取？

git clone git@github.com:Ai-Thinker-Open/ra11-ra20.git
# 或
git clone https://github.com/Ai-Thinker-AIoT/ra11-ra20.git
cd ra11-ra20

后续 cmake 命令均在仓库根目录执行。

Q2.2 Linux / WSL 最少要装哪些工具？

sudo apt update
sudo apt install -y gcc-arm-none-eabi binutils-arm-none-eabi \
  cmake ninja-build git stlink-tools

建议：CMake ≥ 3.25，Ninja ≥ 1.11。验证：

arm-none-eabi-gcc --version
cmake --version
ninja --version

Q2.3 Windows 怎么编译？

优先 WSL2 + Ubuntu，命令与 Linux 相同。原生 Windows 需自行安装 ARM GNU Toolchain、CMake、Ninja，并把 arm-none-eabi-gcc 加入 PATH。

Q2.4 cmake 报 “You have to define a -DBOARD=…”？

必须显式传板型。Ra-11 推荐：

-DBOARD=STM32F103CB

Q2.5 cmake 报 “You must select the radio with -DRAC_RADIO=”？

Ra-11 必须传：

-DRAC_RADIO=lr1121

Q2.6 用 `-DBOARD=NUCLEO_L476` 编译失败？

Ai-Thinker Ra-11 板请用 STM32F103CB。NUCLEO_L476 走另一套 HAL；当前仓库引脚配置下，L4 可能因 HW_MODEM_* 等宏未定义而编译失败。这不是 ping_pong 语法问题，而是板型不匹配。

Q2.7 推荐的 Ra-11 编译命令？

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

产物：build/ping_pong.bin、build/ping_pong.hex、ELF。

Q2.8 只有 ELF、没有 hex/bin？

确认编译的是 add_example 注册的目标（如 ping_pong），POST_BUILD 会调 arm-none-eabi-objcopy。检查日志是否有 Creating ping_pong.hex... / .bin...，并确认 PATH 中有 arm-none-eabi-objcopy。

Q2.9 如何烧录？

# st-flash
st-flash --connect-under-reset write build/ping_pong.bin 0x8000000

# 或 CMake flash 目标
cmake --build build --target flash_ping_pong

也可用 STM32CubeProgrammer 打开 .hex / .bin，SWD，地址 0x08000000。

Q2.10 编译报找不到 `axk_cmd_example/...`？

该可选示例可能不在当前树中。工程已在源码缺失时跳过；执行 rm -rf build 后重新 configure 即可。

Q2.11 新建示例链接报 `undefined reference to main_xxx`？

检查：

examples/main.h 中 APP 宏与声明
examples/main.c 中 #elif MAKEFILE_APP == ... 分支
add_example(... "YOUR_APP" ...) 字符串与宏名一致

3. 射频通信与 ping-pong

Q3.1 两块板都上电，但一直不通 / `unexpected payload`？

最常见原因：两块都烧了默认 Manager 固件（双方都发 PING、都等 PONG）。

正确做法：

设备	配置
设备 A（Manager）	默认，不加 `PING_PONG_START_AS_SUBORDINATE`
设备 B（Subordinate）	加 `-DPING_PONG_START_AS_SUBORDINATE=ON` 后重新 configure 再编译

建议先上电 Subordinate，再上电 Manager。

日志里 prefix_received='80'（十进制）通常对应 ASCII 'P'（PING/PONG 首字节），说明收到了对方发来的帧，但角色/载荷解析不匹配。

Q3.2 Subordinate 固件怎么编？

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

Q3.3 两端射频参数要对齐哪些？

两端必须一致（见 examples/main_examples/ping_pong_example/main_ping_pong.h）：

频率 RF_FREQ_IN_HZ（示例默认常为 868100000，按当地法规与模组频段修改）
SF / BW / Coding Rate
Preamble、CRC、IQ
Sync word（若应用有改）

任一侧改了宏，两块板都要重新编译烧录。

Q3.4 串口波特率是多少？怎么看日志？

调试 UART 一般为 115200 8N1（引脚常见 PA9/PA10，以板级原理图为准）。可用 minicom / screen / PuTTY / 串口助手。

正常 Manager 日志大致包含：starting ping-pong as manager → sending → TX success → receiving → RX success → payload is correct，计数递增。

Q3.5 编译通过但射频完全无反应？

按序检查：

主循环是否周期调用 smtc_rac_run_engine()
-DRAC_RADIO=lr1121 是否与硬件一致
SPI / NRST / BUSY / DIO 接线是否正确
天线是否接好；频率是否落在模组支持频段
供电 3.3V 是否稳定（靠近射频 VDD 放置去耦）

Q3.6 TX done 回调不来 / 通信卡死？

确认未与冲突示例宏同时打开（如部分工程中的 ENABLE_PERIODIC_UPLINK 会与 ping-pong 事务冲突）
主循环中避免长时间阻塞延时，以免 radio planner 无法及时处理
看门狗反复复位时，检查中断/DIO 初始化时序与 HAL 配置

Q3.7 Ra-11 关键引脚要注意什么？

与 STM32F103CBT6 常见对接（以仓库 HAL / modem_pinout 为准）：

MCU	射频侧	功能
PA4	NSS	SPI 片选
PA5	SCK	SPI 时钟
PA6	MISO	SPI MISO
PA7	MOSI	SPI MOSI
PB14	NRST	射频复位
PB1	DIO1	中断
PA0	BUSY	忙信号

LR1121 的天线开关 / LNA 由驱动侧按板级定义处理，勿与 Ra-20 的 LEGACY_EVK_LR20XX 混用思路。

Q3.8 距离近却经常丢包？

确认两端 SF/BW/功率一致
降低周围同频干扰；必要时降速率（更大 SF）或略提高功率（合规前提下）
检查天线匹配与接地；USB 线/供电噪声有时也会影响近场表现

Q3.9 新建应用编译过，但收发回调不跑？

几乎都是主循环里漏了：

smtc_rac_run_engine( );

RAC / radio_planner 依赖该函数驱动状态机。

Q3.10 Modem panic / HardFault 常见原因？

现象	排查方向
`rp_hook_init` panic	同一优先级重复 `smtc_rac_open_radio()`
`radio_access_id is out of range`	使用了无效或已 close 的 radio id
`smtc_rac_submit_radio_transaction` panic	RX 缓冲小于 `max_rx_size` 等上下文填错
`HARDFAULT_Handler`	回调指针为 NULL（如 `callback_post_radio_transaction`）

按日志中的函数名与行号到 smtc_rac / radio_planner 源码对照。

4. 快速检查清单（Ra-11）

-DBOARD=STM32F103CB
-DRAC_RADIO=lr1121
更换配置后已 rm -rf build 再 configure
ping-pong 双板角色一主一从
两端频率 / SF / BW 一致，天线已接
主循环调用 smtc_rac_run_engine()
串口 115200 能看到 USP/RAC 初始化与收发日志

本文仅覆盖 Ra-11 / Ra-11H（LR1121）。Ra-20 请参阅 FAQ_ra20_cn.md。