Initial commit: CCU621_M firmware project with BLE debug link support.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-08 17:28:36 +08:00
commit 9ceb218f80
1597 changed files with 724159 additions and 0 deletions
@@ -0,0 +1,200 @@
+# IES 积成平台功能说明（CCU601E_D / plat_comm/ieszt）
+
+本文档描述 **积成智通 IESZT** 二进制协议在 E 工程中的落地方案、与 **PlatComm 联网任务** 的挂接关系，以及 **`S_BS_IES_CTRL_DATA`** 各字段含义。  
+上层任务状态机、双平台槽位、FTP 分时等见 **[《平台联网任务功能说明.md》](../平台联网任务功能说明.md)**。
+
+---
+
+## 1. 模块定位
+
+| 项目 | 说明 |
+|------|------|
+| **目录** | `app/plat_comm/ieszt/` |
+| **编译宏** | **`BS_IES_EN`**（`public_define.h`） |
+| **PlatComm 槽位** | `MasterFuncArray` 名称 **`"ieszt"`**（`plat_comm_task.c`）；与 OCPP 并存时通常为槽位 **0**，OCPP 为槽位 **1**（以 `PLAT_EN` 配置为准） |
+| **全局数据** | **`s_bs_task_ctrl.s_ies_data`**（`plat_comm_task.h`，类型 **`S_BS_IES_CTRL_DATA`**） |
+| **传输层** | 与 OCPP 共用 **`bs_connect_impl`**：`u8_tcp_connect` / `v_bs_send` / `u16_bs_recv`（**明文 TCP**，无 WebSocket） |
+| **当前阶段** | **登录/心跳** + **校时** + **费率** + **二维码 0x08/0x0A** |
+
+---
+
+## 2. 源文件与功能分区
+
+与 **`BS_ocpp_ctrl.c`** 相同，`.c` 内用 **`#if 1 //公共` / `#if 1  //发送` / `#if 1 //接收` / `#if 1  //外部控制使用`** 折叠分区（便于 Keil 大纲跳转与整段屏蔽调试）。
+
+| 文件 | `#if 1` 分区 | 内容 |
+|------|----------------|------|
+| **`bs_ies_ctrl.c`** | 公共 | `v_ies_timer_add`、`u8_ies_timer_ctrl`、定时器初值、`v_ies_reset_ctx`、`v_ies_on_login_ok` |
+| | 发送 | `v_ies_logo_on`、`v_ies_send_ctrl` |
+| | 接收 | `v_ies_recv_data`、`v_ies_recv_unpack` |
+| | 外部控制使用 | `v_ies_init_data`、`v_ies_tcp_connect`、`v_ies_private_logic` |
+| **`impl/bs_public_impl.c`** | — | **`u8_get_str_data` / `u8_set_str_data`**、**`u32_bs_get_sys_data` / `u8_set_sys_data`**（含 `E_STR_QR_DISPLAY`、`E_BS_GET_SYS_DATA_UNIX_TIMESTAMP`） |
+| **`bs_ies_interface.c`** | 公共 | 组帧头、CRC、`v_ies_finish_frame_and_send` |
+| | 发送 | `v_ies_register_req`、`v_ies_heart_req`、`v_ies_fee_req`、`u8_ies_send_ack` |
+| | 接收 | 登录/心跳/校时/费率/二维码；`v_ies_unpack_handle`（经 `bs_public_impl` 读写系统） |
+| **`bs_ies_ctrl.h`** | — | 协议常量、`IES_SEND_TIMER`、`S_BS_IES_CTRL_DATA`、对外 API |
+| **`bs_ies_interface.h`** | — | 报文层对外声明 |
+
+移植路线图（阶段 3+）见 **`../IES积成平台移植方案.md`**。
+
+---
+
+## 3. 与 PlatComm 的挂接（对照联网任务文档 §4）
+
+### 3.1 七回调映射
+
+| PlatComm 回调 | IES 实现 | 说明 |
+|---------------|----------|------|
+| **`v_bs_data_init`** | `v_ies_init_data` | 清零 **`s_ies_data`**，写入 **`u8_bs_flag`** |
+| **`v_bs_tcp_connect`** | `v_ies_tcp_connect` | 建链前清 **`u8_register_flag`**；内部 **`u8_tcp_connect(id)`** |
+| **`v_bs_logon_connect`** | `v_ies_logo_on` | 周期发 **0x01**；**`u8_register_flag==1`** 时返回 1，置槽位 **`u8_log_on_flag`** |
+| **`v_bs_recv_data`** | `v_ies_recv_data` | **`u16_bs_recv`** → **`v_ies_unpack_handle`** |
+| **`v_bs_recv_unpack`** | `v_ies_recv_unpack` | 空实现（4G 外部分包预留） |
+| **`v_bs_send_ctrl`** | `v_ies_send_ctrl` | 已登录后周期发 **0x03**、**0x05**（未获费率时） |
+| **`v_bs_private_logic`** | `v_ies_private_logic` | **`u8_heart_outTime_cnt`** 超限 → **`v_set_bs_renew`** |
+
+调度顺序与 **`v_plat_comm_network_round`** 一致，见 **[平台联网任务功能说明.md §4.3](../平台联网任务功能说明.md)**。
+
+### 3.2 与 `S_BS_CTRL_DATA` 的分工
+
+| 数据 | 位置 | 用途 |
+|------|------|------|
+| TCP/登录标志 | **`s_bs_ctrl[i].u8_TCP_connect_flag`** / **`u8_log_on_flag`** | PlatComm 通用状态机 |
+| IES 协议态 | **`s_ies_data`** | 登录应答、心跳计数、**`s_timerCnt[]`** 周期定时、序列号等 |
+| 槽位号 | **`s_ies_data.u8_bs_flag`** | 与 **`i`**、`E_STR_PILE_NO` 第三参数、`v_bs_send(id)` 一致 |
+
+---
+
+## 4. 运行态结构 `S_BS_IES_CTRL_DATA`
+
+所有 IES 私有计时与计数集中在 **`s_bs_task_ctrl.s_ies_data`**（`v_ies_reset_ctx` / `memset` 时一并清零）。
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| **`u8_bs_flag`** | U8 | PlatComm 槽位 **0/1**；对应 **`E_BS_GET_SYS_DATA_PLAT_EN`** 与桩编号 **`E_STR_PILE_NO`** 的 `u8_dataPara` |
+| **`u8_register_out_cnt`** | U8 | 已发 **0x01**、仍未收到 **0x02** 的累计次数；超过 **`BS_IES_LOGIN_RETRY_MAX`** 触发 **`v_set_bs_renew`** |
+| **`u8_heart_outTime_cnt`** | U8 | 已发 **0x03**、仍未收到 **0x04** 的连续次数；由 **`v_ies_heart_req`** 递增、**`v_ies_heart_ack`** 清零 |
+| **`u8_register_flag`** | U8 | **1** = 平台登录成功（**0x02** 且结果字节为 0）；为 1 时 **`v_ies_logo_on`** 返回 1 |
+| **`u8_syn_time_flag`** | U8 | **1** = 已完成平台校时（登录成功或收到 **0x76**） |
+| **`u8_ask_fee_flag`** | U8 | **1** = 已获取/下发费率，不再周期发 **0x05** |
+| **`u16_msgSerialNumber`** | U16 | 自发帧序列号（组帧头时 `s16_serialNum<=0` 自增） |
+| **`ulong_restart_timer`** | ULONG | 最近一次 TCP 建链成功时刻（`get_current_seconds`） |
+| **`s_timerCnt[]`** | 数组 | 与 OCPP **`OCPP_DATA_CTRL.s_timerCnt`** 同结构：`u16_timerCnt` 每秒 +1，`u16_timeNUM` 为周期（秒） |
+| **`ack_ctrl[]`** | 指针数组 | 平台下行需应答帧的异步队列（**`IES_DATA_RECV_ACK`**，同 OCPP **`ack_ctrl`**）；`v_ies_send_ctrl` 每轮上送一条 |
+
+### 4.1 `IES_SEND_TIMER` 与默认周期（`v_ies_init_timer_period`）
+
+| 枚举 | 默认 `u16_timeNUM`（秒） | 说明 |
+|------|-------------------------|------|
+| **`IES_TIMER_LOGIN`** | `BS_IES_LOGIN_INTERVAL_S`（20） | `v_ies_logo_on` 发 0x01 |
+| **`IES_TIMER_HEART`** | `BS_IES_HEART_INTERVAL_S`（20） | `v_ies_send_ctrl` 发 0x03 |
+| **`IES_TIMER_FEE_MODULE`** | 30 | 登录后周期发 **0x05** 直至 **0x06** 或 **0x7D** 写入费率 |
+| **`IES_TIMER_FREE_DATA_GUN1/2`** | 180 | 空闲实时 0x13 |
+| **`IES_TIMER_CHG_DATA_GUN1/2`** | 30 | 充电实时 0x15 |
+| **`IES_TIMER_METER_GUN1/2`** | 3600 | 电表 |
+| **`IES_TIMER_TRADE_GUN1`** | 10 | 账单 |
+
+内部接口（`bs_ies_ctrl.c`，与 OCPP 同名语义）：**`v_ies_timer_add()`** 每秒递增；**`u8_ies_timer_ctrl(cmd, GET_FLAG/CLEAR_FALG)`** 查询到时或清零。
+
+---
+
+## 5. 登录与心跳流程
+
+```text
+[TCP 未连接]
+  v_ies_tcp_connect → u8_tcp_connect
+      （清 u8_register_flag；CLEAR_FALG LOGIN/HEART 定时器）
+
+[TCP 已连接，未登录]
+  v_ies_logo_on → v_ies_timer_add
+      IES_TIMER_LOGIN 到时 → v_ies_register_req
+      收到 0x02 且 [BODY]==0 → v_ies_on_login_ok（含首包心跳定时到点）
+      超时次数 > BS_IES_LOGIN_RETRY_MAX → v_set_bs_renew + v_ies_reset_ctx
+
+[已登录，u8_log_on_flag==1]
+  v_ies_send_ctrl → v_ies_timer_add
+      IES_TIMER_HEART 到时 → v_ies_heart_req
+      u8_ask_fee_flag==0 且 IES_TIMER_FEE_MODULE 到时 → v_ies_fee_req
+  v_ies_recv_data → 0x04 → v_ies_heart_ack
+                  → 0x76 → v_ies_set_clk_sync（v_bs_set_time，ack 挂入 ack_ctrl）
+                  → 0x7D → 解析费率 → v_bs_save_fee_data，0x7E 挂入 ack_ctrl
+
+  v_ies_send_ctrl → ack_ctrl 非空 → u8_ies_send_ack → v_ies_free_ack_data
+
+  v_ies_private_logic → v_ies_timer_add
+      u8_heart_outTime_cnt > BS_IES_HEART_MISS_MAX → v_set_bs_renew
+```
+
+---
+
+## 6. 0x68 帧与已实现命令
+
+帧域下标见 **`bs_ies_ctrl.h`** 中 **`IES_FRM_OFF_*`**（与 A 工程 `u8_recvBuf[21/22/23]` 一致）。
+
+| 类型码 | 方向 | 函数 |
+|--------|------|------|
+| **0x01** | 上行 | `v_ies_register_req` |
+| **0x02** | 下行 | `v_ies_register_ack` |
+| **0x03** | 上行 | `v_ies_heart_req` |
+| **0x04** | 下行 | `v_ies_heart_ack` |
+| **0x05** | 上行 | `v_ies_fee_req` |
+| **0x06** | 下行 | `v_ies_fee_module_ack` → `v_bs_save_fee_data` |
+| **0x07** | 上行 | `u8_ies_send_ack` 二维码下发应答 |
+| **0x08** | 下行 | `v_ies_qr_dis` → `QRDisplay[]` + Flash |
+| **0x09** | 上行 | `u8_ies_send_ack` 二维码召唤应答 |
+| **0x0A** | 下行 | `v_ies_qr_call` |
+| **0x75** | 上行 | `v_ies_clk_sync_ack` |
+| **0x76** | 下行 | `v_ies_set_clk_sync` → `v_bs_set_time` |
+| **0x7D** | 下行 | `v_ies_fee_cfg_req` |
+| **0x7E** | 上行 | `v_ies_fee_cfg_ack` |
+| 其它 | — | `v_ies_rx_cmd_handle` 打日志占位 |
+
+---
+
+## 7. 配置与联调要点
+
+| 配置项 | 接口 | 说明 |
+|--------|------|------|
+| 平台使能 | **`E_BS_GET_SYS_DATA_PLAT_EN`** | 槽位 0/1 与 **`MasterFuncArray`** 下标一致 |
+| 联网方式 | **`E_BS_GET_SYS_DATA_NET_TYPE`** | 0=4G，1=网口；IES 与 OCPP 共用同一套 connect |
+| 桩编号 | **`E_STR_PILE_NO`** + **`u8_bs_flag`** | 双平台时平台 A/B 各一套桩号 |
+| 枪数 / 故障 | **`E_BS_GET_SYS_DATA_GUN_NUM`**、**`NOW_FAULT_ALARM_NUM`** | 登录帧、心跳帧组帧 |
+
+**双平台 + 单 4G TCP**：产品与 **`PLAT_EN`** 需约定主平台；详见移植方案「风险」章节。
+
+**FTP 升级中**：`v_ies_recv_data` 在 **`u8_updata_flag!=0` 且 4G** 时跳过收包（与 OCPP 策略一致，见联网任务文档 §4.4）。
+
+---
+
+## 8. 日志
+
+| 宏 | 定义位置 | 说明 |
+|----|----------|------|
+| **`IES_PRINT_FLAG`** | `plat_comm_task.h` | 值 **0xFE**，与 **`OCPP_PRINT_FLAG`(0xFF)** 同类：不受 `u8_task_log_flag` 门控时默认输出 |
+| **`IES_PRINTF_LOG`** | `bs_ies_ctrl.h` | `MYLOG_MSG(IES_PRINT_FLAG, …)`；**ieszt 目录内请用此宏，勿用 `Plat_Comm_LOG`** |
+
+| 日志 | 含义 |
+|------|------|
+| `IES: init slot=` | `v_ies_init_data` |
+| `IES: login req pile=` | 发出 0x01 |
+| `IES: login ok` / `login fail` | 0x02 解析结果 |
+| `IES: heartbeat tx cnt=` | 发出 0x03（含未应答计数） |
+| `IES: heartbeat ack` | 收到 0x04 |
+| `IES: clk sync` / `clk sync ack` | 0x76 校时 / 0x75 应答 |
+| `IES: fee module req` / `fee model saved` | 0x05 请求 / 0x06·0x7D 落盘 |
+| `IES: login timeout, renew` / `heartbeat miss, renew` | 触发 **`v_set_bs_renew`** |
+
+---
+
+## 9. 关联文档
+
+| 文档 | 内容 |
+|------|------|
+| **[平台联网任务功能说明.md](../平台联网任务功能说明.md)** | PlatComm 任务、双槽状态机、FTP 分时、**`v_set_bs_renew`** |
+| **[IES积成平台移植方案.md](../IES积成平台移植方案.md)** | A→E 分阶段移植清单 |
+| **`4g_module/4G模块AT指令配置功能说明.md`** | 4G TCP/FTP 与 PlatComm 分时 |
+| **`impl/bs_public_impl.h`** | **`E_STR_*`** / **`E_BS_GET_SYS_DATA_*`** 枚举 |
+
+---
+
+*文档版本：与 `plat_comm/ieszt` 源码同步；结构体字段变更时请同步更新 §4。*