Ping-Pong 示例 FAQ

本文档汇总了使用和移植 ping_pong 示例时最常见的问题与解答。

1. 编译与烧录

Q: STM32F103CB + Ra-20 推荐的编译命令是什么？

rm -Rf build/ ; \
cmake -L -S examples \
      -B build \
      -DCMAKE_BUILD_TYPE=MinSizeRel \
      -DLEGACY_EVK_LR20XX=true \
      -DBOARD=STM32F103CB \
      -DRAC_RADIO=lr2021 \
      -G Ninja ; \
cmake --build build --target ping_pong

若使用 Ra-11，请设置 -DRAC_RADIO=lr1121（不需要加 LEGACY_EVK_LR20XX）。

Q: 如何烧录固件？

直接使用 st-flash 或 STM32_Programmer_CLI。

2. 运行示例

Q: 一块板子只监听（subordinate），另一块启动发送（manager），如何配置？

A: 默认情况下示例以 manager（主控端）启动，会立即发送第一个 PING。

构建 subordinate（从属端）板子：

cmake ... -DPING_PONG_START_AS_SUBORDINATE=1

Q: 正常运行时串口日志应该是什么样的？

A: 应该持续看到成功的往返通信，并伴随递增的计数器：

INFO: starting ping-pong as manager
INFO: sending (value=0, delay=0ms)
INFO: usp/rac: transaction is starting
INFO: usp/rac: new event: transaction (transmission) has ended (success)
INFO: receiving...
INFO: usp/rac: new event: transaction (reception) has ended (success)
INFO: payload is correct, continuing
INFO: sending (value=1, delay=250ms)
...

如果反复出现 "starting ping-pong as manager" 消息，说明板子正在复位（见第 3 节）。

3. 常见运行问题

Q: 板子不断复位 / 反复打印 `smtc_rac_init`？

A: 这几乎总是由以下两个问题之一导致：

DIO 引脚过早开启中断
在 hal_mcu_init() 中，RADIO_DIOX 必须配置为普通输入（IRQ_MODE_OFF）。只有 smtc_modem_hal_irq_config_radio_irq() 才应开启上升沿中断并注册回调。
主循环中存在长延时
原代码曾使用 hal_mcu_set_sleep_for_ms(1000)，这会饿死 radio planner。当前版本使用紧循环：
```
while (true) {
    hal_watchdog_reload();
    smtc_rac_run_engine();
}
```

Q: TX 完成但没有 "transmission has ended (success)" 消息，radio_planner 不断 abort？

A: 这是因为 ping_pong target 定义了 ENABLE_PERIODIC_UPLINK，导致与 ping-pong manager 事务冲突。检查 CMakeLists.txt 是否移除该定义。

Q: 从属端（subordinate）板子从不回复？

A: 请确认编译时使用了 -DPING_PONG_START_AS_SUBORDINATE=1。同时检查两块板子是否使用了相同的频率、SF、BW 和 sync word（定义在 app_ping_pong.h 中）。

4. 驱动移植与平台适配

Q: 移植到新 MCU 时需要修改哪些文件？

A: 完整列表请参考 driver_manual.md。简而言之：

必须实现新的 smtc_hal_<your_mcu>/ 目录（GPIO、SPI、UART、定时器、看门狗）。
必须更新 modem_pinout.h 中的引脚映射。
应保持整个 smtc_rac_lib/ 和 smtc_modem_hal/ 不变。

Q: 为什么 DIO 引脚在初始化时需要特殊处理？

A: 如果在 smtc_modem_hal_irq_config_radio_irq() 注册回调之前就开启了 RADIO_DIOX 的外部中断，引脚上的任何边沿都会调用 NULL 函数指针 → 导致硬故障或看门狗复位。

正确顺序：

hal_mcu_init() → IRQ_MODE_OFF（普通输入）
smtc_rac_init() → 调用 smtc_modem_hal_irq_config_radio_irq() → 此时再安全地开启上升沿并注册回调

Q: 在新平台的主循环中可以使用 1000ms（或任何长）延时吗？

A: 不可以。radio planner 依赖频繁调用 smtc_rac_run_engine()。长时间阻塞延时会导致已调度的任务错过截止时间，planner 会中止它们。

Q: 如何移植到 BL602？

A: 请参考 driver_manual.md 中“移植到 BL602（Bouffalo SDK）”章节。要点：

使用 Bouffalo SDK 的 GPIO（bflb_gpio_*）和中断 API
先将 DIO 引脚初始化为普通输入，再在 smtc_modem_hal_irq_config_radio_irq 中开启上升沿中断
使用 bflb_mtimer_get_time_us() 获取毫秒时间
主循环中绝不能插入长阻塞延时
整体结构与其他 RISC-V 平台非常相似

5. 调试与监视

Q: 日志显示乱码或行中间被截断？

A: 这通常是因为串口工具 \r\n 的规范化处理不当，或 MCU 输出的是不完整的行。