# EC718HM/EC718PM LuatOS AT 射频校准设计规格

> 日期：2026-06-15
> 关联计划：`docs/superpowers/plans/2026-06-15-ec718hm-pm-rfa-at-plan.md`

---

## 1. 背景与目标

在 LuatOS 固件中提供一套产线 AT 指令射频校准能力，使 EC718HM/EC718PM 系列模组能够直接通过 UART 接收产线工具下发的 AT 指令完成：
- 射频校准（RFCALI）
- 非信令综测（RFNST）
- 相关产线辅助操作（IMEI 读写、NPI 标志、Golden 数据、PMU 等）

设计沿用已有的 `rfa`（Radio Factory Agent）Thin C / Fat Lua 架构，C 端只做字节搬运和状态存储，所有 AT 协议逻辑由 `script/libs/rfa.lua` 完成。

---

## 2. 架构

```
产线工具 (UART)
      |
      v
+-----------------------------+
|  script/libs/rfa.lua        |  Fat Lua
|  - AT 解析 / 响应生成        |
|  - 7 阶段状态机              |
|  - ECRFNST 私有协议模板      |
|  - 扩展 register/registerRfnst|
+-----------------------------+
      | mobile.rfTestMode/Input/Param/Imei/ImeiSet/GmData/GmDataSet
      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 |
|  - gmdata -> luat_fs_*        |
+-----------------------------+
      | soc_mobile_* / RfAtNstCmdPreHandle
      v
+-----------------------------+
|  PLAT 闭源库 / CP / PHY     |  RF 底层
+-----------------------------+
```

---

## 3. C 端接口

所有函数沿用 `luat_mobile_rf_test_*` 前缀，声明在 `components/mobile/luat_mobile.h`。

| 函数 | 签名 | 用途 |
|------|------|------|
| `luat_mobile_rf_test_mode` | `void(uint8_t uart_id, uint8_t on_off)` | 进入/退出 RF 测试模式，绑定 UART |
| `luat_mobile_rf_test_input` | `void(char *data, uint32_t data_len)` | 喂入字节；`data=NULL/0` 触发 flush |
| `luat_mobile_rf_test_param` | `int(const char *key, int *value, int is_set)` | 读写 NPI / state / 扩展参数 |
| `luat_mobile_rf_test_imei_get` | `int(char *out, uint32_t len)` | 读 15 位 IMEI |
| `luat_mobile_rf_test_imei_set` | `int(const char *imei)` | 写 15 位 IMEI |
| `luat_mobile_rf_test_gmdata_get` | `int(char *out, uint32_t len)` | 读 Golden Unit 数据 |
| `luat_mobile_rf_test_gmdata_set` | `int(const char *data, uint32_t len)` | 写 Golden Unit 数据 |
| `luat_mobile_rf_test_set_rx_cb` | `int(const luat_mobile_rf_test_rx_cb_t *cb)` | 注册 Rx 回调（PC 仿真用） |

### 3.1 `luat_mobile_rf_test_param` key 定义

| key | 读写 | PC 后端 | 真机后端 |
|-----|------|---------|----------|
| `rfCaliDone` | 读写 | s_rf_test 静态变量 | `NPI_PROCESS_STATUS_ITEM_RFCALI` |
| `rfNSTDone` | 读写 | s_rf_test 静态变量 | `NPI_PROCESS_STATUS_ITEM_RFNST` |
| `rfCTDone` | 读写 | s_rf_test 静态变量 | `NPI_PROCESS_STATUS_ITEM_RFCT` |
| `state` | 读写 | s_rf_test 静态变量 | 本地静态变量 |
| `erfMode` | 读写 | s_rf_test 静态变量 | 本地静态变量 |
| `pmuEnable` | 读写 | s_rf_test 静态变量 | 占位 0（待 PLAT API） |
| `pmuMode` | 读写 | s_rf_test 静态变量 | 占位 0（待 PLAT API） |
| `chipVer` | 读 | s_rf_test 静态变量 | 占位 0（待 PLAT API） |
| `bandList` | 读 | s_rf_test 静态变量 | 占位 0（待 PLAT API） |
| `facChk` | 读 | s_rf_test 静态变量 | 占位 0（待 PLAT API） |
| `save` | 写 | no-op | `npiSaveConfigToAPNV2()` |

---

## 4. Lua 端 `rfa.lua`

### 4.1 公共 API

- `rfa.start(id, baud)` / `rfa.stop()`：UART 绑定
- `rfa.dispatch(line)`：纯函数 AT 派发，返回响应字符串
- `rfa.feed(chunk)`：流式切行
- `rfa.state()` / `rfa.setState(s)` / `rfa.reset()`：状态机
- `rfa.npiGet(k)` / `rfa.npiSet(k, v)`：NPI 标志
- `rfa.imei()` / `rfa.setImei(s)`：IMEI
- `rfa.register(prefix, fn)` / `rfa.registerRfnst(cmdId, fn)`：扩展点

### 4.2 内建 AT 命令覆盖

覆盖 `EC CAT1产线校准综测相关AT命令.xlsx` 中的 16 条核心命令：

| No. | AT Command | 处理说明 |
|-----|------------|----------|
| 1 | `AT` | 握手 |
| 2 | `ATE0`/`ATE1` | 回显开关 |
| 3 | `AT+CFUN=0/1/4` | 飞行模式 |
| 4 | `AT+CPIN?` | 固定 `+CME ERROR: 303` |
| 5 | `AT+CGSN=1` | 读 IMEI |
| 6 | `AT+ECPMUCFG` | 经 `mobile.rfTestParam` 读写 pmuEnable/pmuMode |
| 7 | `AT+ECRST` | 调用 `mobile.restart()` |
| 8 | `AT+ECCGSN=1,<imei>` | 写 IMEI |
| 9 | `AT+ECNPICFG` | NPI 标志读写 |
| 10 | `AT+ECGMDATA` | 经 `mobile.rfTestGmData/GmDataSet` 读写 |
| 11 | `AT+ECCHIPVER?` | 经 `mobile.rfTestParam("chipVer")` |
| 12 | `AT+ECRFNST=<hex>` | 私有协议模板响应 |
| 13 | `AT+ECBAND=?` | 经 `mobile.rfTestParam("bandList")` |
| 14 | `AT+ECICCID` | 经 `mobile.iccid()` |
| 15 | `AT+ECFACCHK=1` | 经 `mobile.rfTestParam("facChk")` |

### 4.3 状态机

| 阶段 | 值 | 触发 |
|------|---|------|
| IDLE | 0 | 初始 / reset |
| PREP | 1 | `AT+CGSN=1` |
| CALIB | 2 | 任意 `AT+ECRFNST=...` |
| SELF_CAL | 3 | cmdId `0x0D`/`0x0A` |
| WRITE_NV | 4 | `AT+ECNPICFG=rfCaliDone,1` |
| NST_TEST | 5 | cmdId `0x51~0x5A` |
| DONE | 6 | `AT+ECNPICFG=rfNSTDone,1` |

---

## 5. 真机实现细节

### 5.1 文件
- `luatos-soc-2024/interface/src/luat_mobile_ec7xx.c`
- `luatos-soc-2024/project/project.lua`（EC718HM 构建排除 audio/i2s）

### 5.2 依赖的 PLAT API
- `npi_config.h`: `npiGetProcessStatusItemValue`, `npiSetAndSaveProcessStatusItemValue`, `npiSaveConfigToAPNV2`
- `ps_lib_api.h`: `appGetImeiNumSync`, `appSetImeiNumSync`
- `luat_fs.h`: `luat_fs_fopen/fread/fwrite/fclose`

### 5.3 未实化部分
以下命令在真机目前返回占位值，需在 PLAT 侧公开对应 API 后替换：
- `AT+ECPMUCFG` 的 PMU 模式设置
- `AT+ECCHIPVER?` 的芯片版本读取
- `AT+ECBAND=?` 的支持 Band 查询
- `AT+ECFACCHK=1` 的 NV 头校验

---

## 6. 测试

- PC 端：`testcase/utest/drv/mobile_rfa_basic/` 4 套件 42+ case
- PC 端 com0com：`tools/rfa_com0com/test_rfa_com0com.py`
- 真机端：EC718HM/PM 开发板 + 产线工具或串口助手

---

## 7. 风险

1. `soc_mobile_rf_test_input` 对长 hex 字符串可能有长度限制，需与 `ATC_ECRFNST_0_STR_MAX_LEN` 对齐。
2. `AT+ECRFNST` 产线工具对响应时序敏感，需用逻辑分析仪/串口抓包对比 ec7xx-at。
3. PMU/ChipVer/Band/FACCHK 依赖未公开 PLAT API，当前为占位实现。
4. `mobile.rfTestParam` 的 `is_set` 语义在 Lua/C 边界易出错，业务代码应使用 `rfa.lua` 封装。