wangfq/mobile_comm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8911b04df273d949d29a3b30cf63300081e2685d
mobile_comm/luatos/air780epm/docs/rfa/2026-06-15-ec718hm-pm-rfa-at-plan.md
T
wangfq 173dd6874f init: Air780EPM 官方 LuatOS 项目代码基线 
- 来源: 合宙 LuatOS 官方仓库 air780epm 模块完整代码
- 路径: luatos/air780epm/module/Air780EPM/demo 含官方 demo(含 mqtt/mqtts/socket/uart 等)
- 后续: 基于 demo 开发 UART<->MQTT 数据上报功能
2026-08-31 08:53:49 +08:00

303 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# EC718HM/EC718PM 系列模组 LuatOS AT 射频校准实施计划
> 基于 LuatOS rfa（Radio Factory Agent）框架，在 EC718HM/EC718PM 系列模组的 LuatOS 固件上实现产线 AT 指令射频校准功能。
> 计划日期：2026-06-15
---
## 1. 目标与范围
### 1.1 总体目标
在 LuatOS 固件中新增一个基于 rfa.lua 的 AT 服务器，通过指定 UART 接收产线校准/综测工具下发的 AT 指令，调用 mobile.rfTest* 系列 C API 与底层 RF 校准原语交互，最终使 EC718HM/EC718PM 系列模组能够用 LuatOS 固件完成产线射频校准与非信令综测。
### 1.2 覆盖命令（按 EC CAT1产线校准综测相关AT命令.xlsx）
| No. | AT Command | 属性 | 处理方式 | 备注 |
|-----|------------|------|----------|------|
| 1 | AT | 3GPP | rfa.lua 内置派发 | 握手 |
| 2 | ATE0/ATE1 | 3GPP | rfa.lua 内置派发 | 回显 |
| 3 | AT+CFUN=0 | 3GPP | rfa.lua 内置 + mobile.flymode | 进飞行模式 |
| 4 | AT+CPIN? | 3GPP | rfa.lua 内置 | 返回 CME ERROR: 303 |
| 5 | AT+CGSN | 3GPP | rfa.lua 内置 + mobile.rfTestImei | 读 IMEI |
| 6 | AT+ECPMUCFG | EigenComm | 新增 rfa.lua 处理或 C 层 mobile.rfTestParam 扩展 | PMU 模式 |
| 7 | AT+ECRST | EigenComm | 新增 rfa.lua 处理 | 软复位 |
| 8 | AT+ECCGSN | EigenComm | 新增 rfa.lua 处理 + mobile.rfTestImeiSet | 写 IMEI/SN |
| 9 | AT+ECNPICFG | EigenComm | rfa.lua 内置 + mobile.rfTestParam | 校准/综测标志位 |
| 10 | AT+ECGMDATA | EigenComm | 新增 rfa.lua 处理 + C 层扩展 | 金机数据读写 |
| 11 | AT+ECCHIPVER? | EigenComm | 新增 rfa.lua 处理或 C 层扩展 | 读芯片版本 |
| 12 | AT+ECRFNST | EigenComm | rfa.lua 私有协议派发 + mobile.rfTestInput | 校准/非信令指令 |
| 13 | AT+ECBAND=? | EigenComm | 新增 rfa.lua 处理或 C 层扩展 | 查支持 Band |
| 14 | AT+ECICCID | EigenComm | 新增 rfa.lua 处理 + mobile.* ICCID 接口 | 读 ICCID |
| 15 | AT+ECFACCHK=1 | EigenComm | 新增 rfa.lua 处理 + C 层扩展 | 查 NV 头 |
注：ECRFNST 的私有协议 cmdId 模板按产线工具需求通过 rfa.registerRfnst() 扩展；rfa.lua 默认输出占位响应。
### 1.3 不涉及范围（Non-goals）
- 不修改 ec7xx-at 现有 AT 固件实现。
- 不改动 PLAT 闭源预编译库中的 RfAtNstCmdPreHandle / RfAtTestCmd 内部逻辑。
- 不实现 ec7xx-at 中的扩展命令如 AT+ECRFTEST、AT+ECRFSTAT、AT+ECVERSION、AT+ECDIEXY 等（如需后续另开 PR）。
- 不替换现有产线工具，只保证 AT 协议层行为一致。
---
## 2. 现状分析
### 2.1 LuatOS 侧（框架已就绪）
- script/libs/rfa.lua：已有 7 阶段状态机、内置 AT 派发、扩展点 register / registerRfnst、UART 绑定。
- components/mobile/luat_mobile.h：已声明 6 个 luat_mobile_rf_test_* C API。
- components/mobile/luat_lib_mobile.c：已绑定 5 个 Lua API（mobile.rfTestMode/Input/Param/Imei/ImeiSet）。
- bsp/pc/port/luat_mobile_pc.c：PC 仿真后端完整实现，单元测试 testcase/utest/drv/mobile_rfa_basic/ 13 case 全过。
### 2.2 luatos-soc-2024 侧（真机后端待补齐）
- interface/src/luat_mobile_ec7xx.c 已存在：
- luat_mobile_rf_test_input()：转发到 soc_mobile_rf_test_input()，并做 toupper()。
- luat_mobile_rf_test_mode()：转发到 soc_mobile_rf_test_mode()。
- 尚未实现：
- luat_mobile_rf_test_param()：需映射到 npi_config.h 的 NPI 接口。
- luat_mobile_rf_test_imei_get()：需调用 appGetImeiNumSync()。
- luat_mobile_rf_test_imei_set()：需调用 appSetImeiNumSync()。
- luat_mobile_rf_test_set_rx_cb()：按头文件注释，真机无需实现，返回 0 或 -1 即可。
### 2.3 ec7xx-at 侧（参考实现）
- PLAT/middleware/developed/at/atps/src/atec_rf.c：AT+ECRFNST 调用 RfAtNstCmdPreHandle()。
- PLAT/middleware/developed/at/atcust/src/atec_product.c：AT+ECNPICFG、AT+ECGMDATA、AT+ECRFSTAT 等。
- PLAT/middleware/developed/at/atcust/src/atec_plat_dev.c：AT+ECPMUCFG。
- PLAT/middleware/developed/open_am/driver/src/am_service.c：soc_mobile_rf_test_mode/input 的实现入口，在闭源 libcore_airm2m.a 中。
- 关键底层头文件：
- PLAT/middleware/developed/common/inc/npi_config.h
- PLAT/middleware/developed/ecapi/psapi/inc/ps_lib_api.h
- PLAT/driver/hal/ec7xx/ap/inc/hal_rfCali.h
---
## 3. 架构设计
### 3.1 分层架构
```
产线工具 (UART)
|
v
+-----------------------------+
| script/libs/rfa.lua | <- Fat Lua：AT 解析、状态机、响应生成、扩展钩子
| - AT 命令派发 |
| - ECRFNST 私有协议模板 |
| - 状态机 / NPI / IMEI 管理 |
+-----------------------------+
| mobile.rfTestMode/Input/Param/Imei/ImeiSet
v
+-----------------------------+
| components/mobile/ | <- Lua<-C 绑定
| luat_lib_mobile.c |
+-----------------------------+
| luat_mobile_rf_test_*
v
+-----------------------------+
| luatos-soc-2024/interface/src/ | <- 真机 C 适配
| luat_mobile_ec7xx.c |
| - mode/input -> soc_mobile_* |
| - param -> npi_config |
| - imei -> appGet/SetImeiNumSync |
+-----------------------------+
| soc_mobile_* / RfAtNstCmdPreHandle
v
+-----------------------------+
| PLAT 闭源库 / CP / PHY | <- RF 底层
+-----------------------------+
```
### 3.2 关键设计决策
1. 沿用 Thin C / Fat Lua：已有 rfa.lua 承担全部 AT 协议逻辑，C 端只做字节透传与 NPI/IMEI 读写，避免在 C 端重复实现 AT 状态机。
2. 真机端补齐 4 个 C API：param、imei_get、imei_set、set_rx_cb，其中 set_rx_cb 为无操作桩。
3. AT+ECRFNST 透传路径：
- rfa.lua 收到 AT+ECRFNST=<hex> 后，对已知 cmdId 模板生成同步响应；
- 对未知/需要底层执行的 cmdId，通过 mobile.rfTestInput() 将 hex 字节流转发给 soc_mobile_rf_test_input()，由闭源库处理并异步返回。
- 当前 rfa.lua 默认全部生成同步占位响应；若产线工具需要真响应，需按 cmdId 扩展 registerRfnst 回调。
4. PMU/Golden/ChipVer/Band/ICCID/FACCHK：
- 先尝试在 rfa.lua 中通过现有 mobile.* API（如 mobile.imei()、mobile.flymode()）实现；
- 缺少的接口优先扩展 mobile.rfTestParam 的 key 集合，由 C 层调用对应 PLAT API；
- 若 PLAT 无公开 API，则通过 mobile.rfTestInput() 走 soc_mobile_rf_test_input() 的私有通道。
5. EC718HM/EC718PM 共用同一接口文件：luat_mobile_ec7xx.c 不拆分；构建系统按 --chip_target 自动选择 PLAT/libs/ec718pm* 或 ec718hm* 预编译库。
---
## 4. 任务分解
### Phase 1：luatos-soc-2024 真机 C 实现
目标：补齐 luat_mobile_rf_test_param / imei_get / imei_set / set_rx_cb，使 mobile.rfTest* 在 EC718HM/PM 真机上可用。
文件：luatos-soc-2024/interface/src/luat_mobile_ec7xx.c
1. 包含必要头文件：
- PLAT/middleware/developed/common/inc/npi_config.h
- PLAT/middleware/developed/ecapi/psapi/inc/ps_lib_api.h
2. 实现 luat_mobile_rf_test_param(const char *key, int *value, int is_set)：
- key "rfCaliDone" -> NPI_PROCESS_STATUS_ITEM_RFCALI
- key "rfNSTDone" -> NPI_PROCESS_STATUS_ITEM_RFNST
- key "rfCTDone" -> NPI_PROCESS_STATUS_ITEM_RFCT
- key "state" / "erfMode" -> 本地静态变量（非持久化）
- key "save" -> 调用 npiSaveConfigToAPNV2()（确认接口名）
- 不支持的 key 返回 -1
3. 实现 luat_mobile_rf_test_imei_get(char *out, uint32_t len)：
- 调用 appGetImeiNumSync(out)，确保字符串结束。
4. 实现 luat_mobile_rf_test_imei_set(const char *imei)：
- 校验长度 15，调用 appSetImeiNumSync((char*)imei)。
5. 实现 luat_mobile_rf_test_set_rx_cb(...)：
- 真机无需，直接返回 0。
6. 编译验证：
cd luatos-soc-2024/project/example_mobile
xmake f --chip_target=ec718pm
xmake
同样对 ec718hm 做一次编译验证。
### Phase 2：LuatOS rfa.lua 扩展
目标：支持 Excel 中的 16 条核心产线命令，并保留扩展点。
文件：LuatOS/script/libs/rfa.lua
1. 在 _builtin_dispatch 中新增：
- AT+ECRST -> 调用 mobile.restart() 或 mobile.rfTestInput 私有通道；返回 OK 后触发复位。
- AT+ECCGSN=<type>,<sn/imei> -> 校验类型与长度，调用 mobile.rfTestImeiSet()。
- AT+ECGMDATA? -> 返回 Golden Unit 数据（先返回 OK 占位，后续接 Phase 4）。
- AT+ECGMDATA=<data> -> 写入 Golden Unit 数据。
- AT+ECCHIPVER? -> 返回芯片版本字符串。
- AT+ECBAND=? -> 返回支持的 Band 列表。
- AT+ECICCID -> 调用 mobile.iccid() 或等效 API。
- AT+ECPMUCFG=<enable>[,<mode>] -> 设置 PMU 模式。
- AT+ECPMUCFG? -> 查询 PMU 模式。
- AT+ECFACCHK=1 -> 返回 NV 头校验结果。
2. 对 AT+ECRFNST 处理增强：
- 保留默认占位响应；
- 增加常见 cmdId（如 0x0D、0x0A、0x51-0x5A）的模板响应；
- 提供 rfa.registerRfnst() 让项目级 Lua 代码注入更多模板。
3. 添加 rfa.atServerStart(id, baud) 别名（与 rfa.start 等价），便于产线工具文档对齐。
### Phase 3：LuatOS C 绑定修正（如需要）
文件：LuatOS/components/mobile/luat_lib_mobile.c
1. 检查 l_mobile_rf_test_param 的 is_set 参数处理：当前 lua_toboolean(L, 4) 对整数 0 判断为 true，需确认 rfa.lua 已用 nil/false 表示读；如需更健壮，可改为显式判断 lua_isnil/lua_isboolean。
2. 检查 LUAT_USE_MOBILE_RFA 宏在目标 BSP（如 bsp/ec7xx）中是否已打开；未打开则添加。
### Phase 4：Golden / PMU / ChipVer / Band / ICCID / FACCHK 的 C 后端（按需）
目标：若 rfa.lua 缺少对应 mobile.* API，则通过扩展 mobile.rfTestParam 或新增 C API 实现。
文件：
- LuatOS/components/mobile/luat_mobile.h（仅当新增 API 时）
- LuatOS/components/mobile/luat_lib_mobile.c
- luatos-soc-2024/interface/src/luat_mobile_ec7xx.c
1. AT+ECGMDATA：
- 方案 A：通过 mobile.rfTestParam 新增 key "gmData"（读写 int 数组或字符串长度受限）。
- 方案 B：新增 mobile.rfTestGmData(buf) / mobile.rfTestGmDataSet(buf) 字符串 API。
- 推荐方案 B，因为 Golden 数据可能较长。
2. AT+ECPMUCFG：
- 新增 mobile.rfTestParam key "pmuMode" / "pmuEnable"，C 层调用 apmuSetDeepestSleepMode() 或 PMU_SetSleepMode()。
3. AT+ECCHIPVER?：
- 新增 mobile.rfTestParam key "chipVer"，C 层调用现有 chipver API。
4. AT+ECBAND=?：
- 新增 mobile.rfTestParam key "bandList"，C 层返回支持的 Band 位图。
5. AT+ECICCID：
- 优先复用 mobile.iccid()；若不可用，新增 mobile.rfTestIccid()。
6. AT+ECFACCHK=1：
- 新增 mobile.rfTestParam key "facChk"，C 层调用 NV 头校验接口。
Phase 4 的具体命令可在进入开发后根据产线工具实际交互日志裁剪；本计划按“全部实现”排期。
### Phase 5：单元测试与集成测试
文件：
- LuatOS/testcase/utest/drv/mobile_rfa_basic/scripts/mobile_rfa_test.lua
- LuatOS/tools/rfa_com0com/test_rfa_com0com.py
- 新增：testcase/utest/drv/mobile_rfa_basic/scripts/ec718_rfa_test.lua（真机行为 mock）
1. PC 端单元测试：
- 扩展 mobile_rfa_test.lua，覆盖新增命令（ECRST、ECCGSN、ECGMDATA、ECPMUCFG、ECBAND、ECICCID、ECFACCHK、ECCHIPVER）。
- 验证状态机推进、IMEI 读写、NPI 保存。
2. PC 端 com0com 回归：
- 扩展 test_rfa_com0com.py，覆盖 Excel 中的核心命令。
3. 真机测试：
- 在 EC718HM/PM 开发板上烧录 LuatOS 固件。
- 使用 USB/UART 连接产线工具或串口助手，验证：
- 握手与回显
- CFUN=0 进入飞行模式
- CGSN 读 IMEI
- ECCGSN 写 IMEI
- ECGMDATA 读写
- ECRFNST 私有协议响应
- ECNPICFG 标志位读写与掉电保持
- ECRST 复位
4. 产线工具对齐：
- 用实际产线工具跑一遍校准/综测流程，对比 ec7xx-at 输出行为差异并修复。
### Phase 6：文档与落档
文件：
- LuatOS/components/mobile/README_rfa.md（更新，补充 EC718HM/PM 真机适配说明）
- LuatOS/docs/superpowers/specs/2026-06-15-ec718hm-pm-rfa-at-design.md（新增设计规格）
- LuatOS/docs/superpowers/plans/2026-06-15-ec718hm-pm-rfa-at-plan.md（本计划落档）
- LuatOS/docs/rfa/ 下同步 mirror
---
## 5. 时间线与里程碑
| 阶段 | 内容 | 预期输出 | 验收标准 |
|------|------|----------|----------|
| W1 | Phase 1：C 后端补齐 | PR 到 luatos-soc-2024 | ec718pm / ec718hm 编译通过；mobile.rfTestParam/Imei 真机可用 |
| W1-W2 | Phase 2：rfa.lua 扩展 | PR 到 LuatOS | PC 端 13+ 新增 case 全过 |
| W2 | Phase 3：C 绑定修正 | PR 到 LuatOS | 绑定参数行为与 rfa.lua 一致 |
| W2-W3 | Phase 4：扩展命令 C 后端 | PR 到 luatos-soc-2024 + LuatOS | 所有 Excel 命令在 PC/真机有响应 |
| W3 | Phase 5：测试与真机验证 | 测试报告 | com0com 回归通过；真机校准流程跑通 |
| W3-W4 | Phase 6：文档与落档 | 文档 PR | README + spec + plan 合并 |
---
## 6. 风险与应对
| 风险 | 影响 | 应对 |
|------|------|------|
| npi_config.h / appGetImeiNumSync 在 ec718hm 与 ec718pm 上行为不一致 | 中 | 在两个目标上分别编译并真机验证；若 API 有差异，用宏隔离 |
| soc_mobile_rf_test_input 对长 hex 字符串（>8000 字符）有长度限制 | 中 | 与 ec7xx-at 中 ATC_ECRFNST_0_STR_MAX_LEN 对齐；超长时分片或报错 |
| AT+ECGMDATA 需要文件系统（LittleFS）支持，LuatOS 真机文件路径不同 | 中 | 复用 LuatOS io/fs API 而非直接写 /rfTestFile；PC 端用内存缓冲 |
| 产线工具对 AT+ECRFNST 响应时序敏感 | 高 | 使用逻辑分析仪/串口抓包对比 ec7xx-at 与 LuatOS 输出；必要时调整 rfa.lua 响应延迟 |
| mobile.rfTestParam 的 is_set 参数语义在 Lua/C 边界易出错 | 中 | 在 luat_lib_mobile.c 中显式判断 lua_isboolean 或 lua_isnil，拒绝整数 0/1 |
| 部分命令（ECCHIPVER、ECFACCHK、ECPMUCFG）可能依赖未公开的 PLAT API | 高 | 先在 ec7xx-at 中确认这些命令的底层调用；若无法直接调用，通过 soc_mobile_rf_test_input 私有通道透传 |
---
## 7. 验证清单
- [ ] ec718pm 目标 xmake 0 错误 0 警告。
- [ ] ec718hm 目标 xmake 0 错误 0 警告。
- [ ] PC 端 mobile_rfa_basic utest OVERALL_PASS。
- [ ] PC 端 com0com 回归覆盖 Excel 16 条命令。
- [ ] 真机 AT+CGSN=1 返回正确 IMEI。
- [ ] 真机 AT+ECCGSN=1,<imei> 写入并持久化 IMEI。
- [ ] 真机 AT+ECNPICFG? 与 AT+ECNPICFG=rfCaliDone,1 读写正常，掉电保持。
- [ ] 真机 AT+ECRFNST=<hex> 与产线工具交互无 ERROR/CRCERROR。
- [ ] 真机校准/综测流程与 ec7xx-at 行为一致。
---
## 8. 仓库与分支建议
| 仓库 | 分支 | 说明 |
|------|------|------|
| LuatOS | feature/ec718-rfa-at | rfa.lua 扩展、C 绑定修正、测试与文档 |
| luatos-soc-2024 | feature/ec718-rfa-cbackend | 真机 C 后端实现 |
| ec7xx-at | 不修改 | 仅作为参考实现和对比基准 |
---
## 9. 后续可扩展
1. 支持 AT+ECRFTEST 等 ec7xx-at 扩展命令。
2. 将 rfa.lua 状态机与 LuatOS fdb/kv 持久化对接，替代本地静态变量。
3. 多 UART 同时校准（多 DUT 并行）支持。
4. 与产线 MES 系统对接，上传校准结果。
Reference in New Issue View Git Blame Copy Permalink