Ra-20 / Ra-20H 开发 FAQ

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

推荐编译参数：

-DBOARD=STM32F103CB -DRAC_RADIO=lr2021 -DLEGACY_EVK_LR20XX=ON

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

1. 芯片与驱动

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

模组	芯片	CMake 参数
Ra-20 / Ra-20H	LR2021（LR20xx）	`-DRAC_RADIO=lr2021`

Ai-Thinker / 老款 EVK 引脚兼容时，通常还需：

-DLEGACY_EVK_LR20XX=ON

驱动位置：

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

Q1.2 为什么一定要加 `LEGACY_EVK_LR20XX`？

该选项选择 LR20xx 的 legacy EVK 引脚定义（例如 DIOX 等与老板一致）。安信可 Ra-20 类板卡多数按此配置工作。

Ai-Thinker / legacy EVK：-DLEGACY_EVK_LR20XX=ON（或 true）
WIO 等新板型：可按原理图尝试 OFF

引脚模式与硬件不一致时，常见表现是中断不来、TX/RX 无回调、SPI 看似正常但业务卡死。

Q1.3 能不能用 `lr1121` / `sx1262` 来编 Ra-20？

不能。必须与实际芯片一致。Ra-20 请固定 lr2021，并按板型配置 LEGACY_EVK_LR20XX。

Q1.4 LR2021 支持哪些能力？和 Ra-11 有何差异？

LR2021（LR20xx）能力更全，例如：

LoRa / FSK / FLRC 等（以驱动与示例开放列表为准）
RTToF 测距（可用 rttof_manager / rttof_subordinate）
部分示例如 direct_driver_access、cad 主要面向 LR20xx

Ra-11（LR1121）不支持 RTToF。验证 Ra-20 测距请使用 LR2021 专用示例，不要照搬 Ra-11 的 ping-pong 参数假设去测距。

Q1.5 更换芯片、板型或 `LEGACY_EVK_LR20XX` 后行为怪异？

务必清缓存后重配：

rm -rf build
cmake -S examples -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=MinSizeRel \
  -DBOARD=STM32F103CB \
  -DRAC_RADIO=lr2021 \
  -DLEGACY_EVK_LR20XX=ON
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-20 推荐：

-DBOARD=STM32F103CB

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

Ra-20 必须传：

-DRAC_RADIO=lr2021

并按板型加上 -DLEGACY_EVK_LR20XX=ON（Ai-Thinker 常用）。

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

Ai-Thinker Ra-20 板请用 STM32F103CB。NUCLEO_L476 走另一套 HAL；当前仓库引脚配置下，L4 可能因 HW_MODEM_* 等宏未定义而失败。请勿用 NUCLEO 命令行去验证安信可板。

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

rm -rf build
cmake -S examples -B build \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=MinSizeRel \
  -DBOARD=STM32F103CB \
  -DRAC_RADIO=lr2021 \
  -DLEGACY_EVK_LR20XX=ON
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 会生成 hex/bin。检查日志中的 Creating ping_pong.hex... / .bin...，以及 arm-none-eabi-objcopy 是否在 PATH。

Q2.9 如何烧录？

st-flash --connect-under-reset write build/ping_pong.bin 0x8000000
# 或
cmake --build build --target flash_ping_pong

也可用 STM32CubeProgrammer 选择 .hex / .bin，接口 SWD，地址 0x08000000。

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

可选示例目录可能不在树中。清 build/ 后重新 configure；工程会在源码缺失时跳过该目标。

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

检查 main.h 宏与声明、main.c 的 MAKEFILE_APP 分支、以及 add_example 第二参数是否与宏名一致。

3. 射频通信与 ping-pong

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

最常见原因：两块都是默认 Manager。

设备	配置
设备 A（Manager）	默认（不要开 Subordinate）
设备 B（Subordinate）	`-DPING_PONG_START_AS_SUBORDINATE=ON`，并重新 configure 编译

建议上电顺序：先 Subordinate，再 Manager。

prefix_received='80'（十进制）多对应 ASCII 'P'，表示收到了以 P 开头的载荷，但角色/期望帧类型不对。

Q3.2 Subordinate 固件怎么编？

rm -rf build
cmake -S examples -B build \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=MinSizeRel \
  -DBOARD=STM32F103CB \
  -DRAC_RADIO=lr2021 \
  -DLEGACY_EVK_LR20XX=ON \
  -DPING_PONG_START_AS_SUBORDINATE=ON
cmake --build build --target ping_pong

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

两端必须一致（见 main_ping_pong.h）：

RF_FREQ_IN_HZ（示例默认常为 868100000，请按 Ra-20 实际频段与当地法规修改）
SF / BW / CR
Preamble、CRC、IQ

改宏后两块板都要重编重烧。

Q3.4 串口怎么看日志？

调试 UART 一般为 115200 8N1。正常 Manager 流程：starting ping-pong as manager → 发送成功 → 接收成功 → payload is correct，计数递增；TX/RX LED 随轮次闪烁。

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

主循环是否调用 smtc_rac_run_engine()
是否为 lr2021 + 正确的 LEGACY_EVK_LR20XX
SPI / NRST / BUSY / DIOX 接线
天线与频率频段
3.3V 供电与去耦

若 SPI 能读到芯片、但中断从不触发，优先怀疑 DIO 引脚与 LEGACY_EVK_LR20XX 不匹配。

Q3.6 TX done 不来 / 反复复位？

避免与冲突宏同时启用（如部分场景下的 ENABLE_PERIODIC_UPLINK）
主循环勿长时间阻塞
核对 DIO 中断初始化是否在回调注册之后、引脚是否与 legacy 模式一致

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

公共 SPI/控制（STM32F103CBT6，以仓库为准）：

MCU	射频侧	功能
PA4	NSS	SPI 片选
PA5	SCK	SPI 时钟
PA6	MISO	SPI MISO
PA7	MOSI	SPI MOSI
PB14	NRST	射频复位
PB1	DIOX	中断（legacy 模式常用）
PA0	BUSY	忙信号

编译必须带 -DLEGACY_EVK_LR20XX=ON（Ai-Thinker / legacy EVK）。不要按 Ra-11 的 LR11xx LNA 逻辑去改 Ra-20，除非原理图明确要求。

Q3.8 测距示例怎么编？注意什么？

使用 rttof_manager / rttof_subordinate，且 -DRAC_RADIO=lr2021。两端测距角色、信道与 RTToF 相关宏需成对配置。测距与普通 ping-pong 不是同一套业务状态机，请分开验证。

Q3.9 近距离仍易丢包？

核对两端 SF/BW/功率与频段
合规前提下可适当调整功率或 SF
检查天线、供电噪声、同频干扰
确认未误用 LEGACY_EVK_LR20XX=OFF 导致中断偶发丢失

Q3.10 新建应用回调不执行？

主循环必须周期调用：

smtc_rac_run_engine( );

Q3.11 Modem panic / HardFault？

现象	排查方向
`rp_hook_init` panic	同一优先级重复 `smtc_rac_open_radio()`
`radio_access_id is out of range`	无效或已关闭的 radio id
`smtc_rac_submit_radio_transaction` panic	RX 缓冲过小等上下文错误
`HARDFAULT_Handler`	空回调（如 post-transaction 回调未设置）

对照日志中的函数名与行号检查 smtc_rac / radio_planner。

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

-DBOARD=STM32F103CB
-DRAC_RADIO=lr2021
-DLEGACY_EVK_LR20XX=ON（Ai-Thinker / legacy EVK）
更换配置后已清空 build/ 再 configure
ping-pong 双板一主一从
两端频率 / SF / BW 一致，天线已接
主循环调用 smtc_rac_run_engine()
串口 115200 有初始化与收发日志

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