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,348 @@
+# 平台联网任务功能说明（CCU601E_D / plat_comm）
+
+本文档描述 **`CCU601E_D\app\plat_comm`** 目录内**平台联网任务**的整体架构、状态机、链路层与业务层分工，以及与计量、Flash、OCPP 的衔接。内容基于当前工程源码归纳；各子模块细节见文末**关联文档**。
+
+---
+
+## 1. 模块定位
+
+| 项目 | 说明 |
+|------|------|
+| **任务** | FreeRTOS 任务 **`TASK_ID_PlatComm`**，入口 **`v_Plat_Comm`**，周期约 **100ms**（由任务睡眠配置决定）。 |
+| **职责** | 多平台（最多 **2 路**）的 **TCP 建链 → 平台登录 → 周期收发 → 私有逻辑**；与 **FTP 远程升级 / 诊断日志上传** 分时调度；对上层屏蔽 **4G / 网线** 差异。 |
+| **协议栈** | 业务协议由 **`MasterFuncArray`** 注册（当前工程默认 **OCPP 1.6 + WebSocket**）；传输由 **`bs_connect_impl`** 统一 **发送/接收**。 |
+| **全局控制块** | **`BS_TASK_CTRL_DATA s_bs_task_ctrl`**（`plat_comm_task.c` / `plat_comm_task.h`）。 |
+
+---
+
+## 2. 编译开关与平台槽位
+
+定义见 **`app/publicdata/public_define.h`**（摘要）：
+
+| 宏 | 典型值 | 含义 |
+|----|--------|------|
+| **`MAX_BS_NUM`** | 2 | 同时支持的平台通道数（槽位 0 / 1）。 |
+| **`BS_OCPP_EN`** | 1 | OCPP 协议栈参与编译。 |
+| **`BS_IES_EN`** | 1 | 积成平台（`plat_comm/ieszt/`，登录+心跳）；详见 **[ieszt/IES积成平台功能说明.md](ieszt/IES积成平台功能说明.md)**。 |
+| **`BS_GWSDK_EN`** | 0 | 国网 SDK 平台（`gwsdk/`，本仓库目录可能未包含）。 |
+| **`BS_TLS_MBEDTLS_EN`** | 视工程 | 网口 **wss://** 时 MCU 侧 **mbedTLS** 封装。 |
+| **`LWIP_FTP_UPGRADE_ENABLE`** | 视工程 | 网线 **LwIP FTP** 固件下载状态机。 |
+
+运行时使能与联网方式**不只看宏**，还读系统配置：
+
+- **`E_BS_GET_SYS_DATA_PLAT_EN`**：`u8_gunNo` = 0 → 平台 A，= 1 → 平台 B；0 关闭、1 使能。
+- **`E_BS_GET_SYS_DATA_NET_TYPE`**：0 = **4G（EC200A）**，1 = **网线（LwIP）**。
+
+初始化在 **`v_plat_data_init()`**（`plat_comm_task.c`）中写入各槽位 **`bs_enable`**、**`u8_netType`**。
+
+---
+
+## 3. 目录结构一览
+
+```
+plat_comm/
+├── plat_comm_task.c / .h          # 联网任务主循环、平台函数表、重连入口
+├── 平台联网任务功能说明.md         # 本文档
+├── impl/
+│   ├── bs_connect_impl.c / .h     # TCP/TLS 建链、统一 v_bs_send / u16_bs_recv
+│   └── bs_public_impl.c / .h      # 桩枪数据桥接、未结订单、FTP 调度、OCPP 配置读写
+├── ocpp/                          # OCPP 1.6（详见 ocpp/OCPP功能模块说明.md）
+├── ieszt/                         # 积成 IESZT（详见 ieszt/IES积成平台功能说明.md）
+├── 4g_module/                     # EC200A AT、TCP、FTP（详见 4G模块AT指令配置功能说明.md）
+└── lwip_module/                   # 网口 socket、LwIP FTP 升级（详见 lwip_ftp功能说明.md）
+```
+
+---
+
+## 4. 联网任务主状态机（`v_Plat_Comm`）
+
+### 4.1 平台函数表 `MasterFuncArray`
+
+每个使能槽位绑定一组回调（**`plat_comm_task.c`**）：
+
+| 回调 | OCPP 实现 | 作用 |
+|------|-----------|------|
+| **`v_bs_data_init`** | `v_ocpp_init_data` | 上电/全量复位：OCPP 上下文、离线 MV FRAM、定时器等。 |
+| **`v_bs_tcp_connect`** | `v_ocpp_tcp_connect` | **TCP + WebSocket 握手**（内部先 `u8_tcp_connect`）。 |
+| **`v_bs_logon_connect`** | `v_ocpp_logo_on` | **BootNotification** 登录，成功置 **`u8_log_on_flag`**。 |
+| **`v_bs_recv_data`** | `v_ocpp_recv_data` → `ocpp_recv` | 收包并解析 JSON（CALL / CALLRESULT）。 |
+| **`v_bs_send_ctrl`** | `v_ocpp_send_ctrl` → `ocpp_send_mag_ctrl` | 周期/事件驱动主动上送（Heartbeat、MV、StopTx 等）。 |
+| **`v_bs_private_logic`** | `v_ocpp_private_logic` | 超时重连、未结订单、离线 MV 落盘、鉴权检查等。 |
+
+未使能槽位（**`bs_enable == 0`**）在本轮循环中跳过。
+
+**`BS_IES_EN`** 时槽位 **0** 常为 **`"ieszt"`**（`v_ies_*`），协议态在 **`s_bs_task_ctrl.s_ies_data`**（含 **`IES_SEND_TIMER` + `s_timerCnt[]`**，与 OCPP **`s_timerCnt`** 同套路），详见 **[ieszt/IES积成平台功能说明.md](ieszt/IES积成平台功能说明.md)**。
+
+### 4.2 单槽位连接状态（`S_BS_CTRL_DATA`）
+
+| 字段 | 含义 |
+|------|------|
+| **`u8_TCP_connect_flag`** | 1 = 传输层已就绪（OCPP 下为 TCP+WS 成功）。 |
+| **`u8_log_on_flag`** | 1 = 平台登录成功（BootNotification Accepted/Pending）。 |
+| **`u8_netType`** | 0 = 4G，1 = 网线。 |
+| **`fd`** | 网口 socket 描述符；4G 路径不使用。 |
+| **`is_secure` / `tls_ctx`** | 网口 **wss** 时 TLS 会话（**`BS_TLS_MBEDTLS_EN`**）。 |
+| **`u8_updata_flag`** | 远程升级进行中：0 无，1 FTP 固件，2 SDK OTA 等。 |
+| **`u8_4g_soft_tcp_reconnect`** | 4G：**软重连**（仅 QICLOSE+QIOPEN，不整网重驻网）。 |
+| **`s_gundata[]`** | 每枪：`txFlag_tradUpload`、`txFlag_startResult`、`txFlag_autoStart` 等与 OCPP/flow 协同。 |
+
+### 4.3 每周期调度顺序（`v_plat_comm_network_round`）
+
+对每个使能槽位 **i**：
+
+```text
+若 u8_TCP_connect_flag == 0
+    → v_bs_tcp_connect()          // 建链
+否则若 u8_log_on_flag == 0
+    → v_bs_logon_connect()          // 登录
+否则
+    → v_bs_send_ctrl()              // 已登录：主动发送
+
+→ v_bs_recv_data()                  // 收包（任意阶段均可收）
+→ v_bs_private_logic(i)             // 私有逻辑（未结单、离线 MV、超时等）
+```
+
+日志示例：`[0] tcp connect`、`[0] logOn is ok`（`Plat_Comm_LOG`）。
+
+### 4.4 与 FTP 的分时调度（4G 重点）
+
+**`u8_plat_comm_ftp_transfer_active()`** 为真时（**`u8_updata_flag != 0`**，或 4G 下 **`u8_log_file_upload`** 置位）：
+
+- **偶数周期**：仅 **`v_plat_comm_network_round()`**（保证 OCPP 仍能 recv/send）。
+- **奇数周期**：仅 **`v_plat_comm_ftp_round()`** → **`v_ftp_update_action()`** + 双路 **`v_bs_recv_data()`**（收 **+QFTP*** 等 URC）。
+
+无 FTP 时：每周期只跑联网，相位复位。
+
+> 原因：4G 与 FTP **共用一根 UART**；若在同一周期内既跑大量 AT 又跑 **QISEND**，易出现粘连、**`break off=0`**。详见 **`4g_module/4G模块AT指令配置功能说明.md`**。
+
+---
+
+## 5. 重连与初始化策略（`v_set_bs_renew`）
+
+**`void v_set_bs_renew(U8_T u8_bs)`**（`plat_comm_task.c`）为各模块统一的「断链重连」入口：
+
+| 联网方式 | 行为 |
+|----------|------|
+| **网线** | **`v_bs_eth_close_socket`**：关 socket、清 **`fd`**、**`u8_TCP_connect_flag`**，避免 LwIP **socket 泄漏**导致「再也连不上」。 |
+| **4G** | 清 TCP 标志、**`fd=-1`**，置 **`u8_4g_soft_tcp_reconnect=1`**（下次 **`u8_tcp_connect`** 走软重开 Socket）。 |
+| **公共** | **`u8_log_on_flag=0`**；**不在此处**调用 **`v_bs_data_init`**，避免每次断线都 **整模组重驻网**。 |
+
+**全量 OCPP 复位**（含 **`v_ocpp_mv_offline_init`**、运行态 RAM）由 **`v_ocpp_init_data` / `v_ocpp_init_data_ex`** 在 **上电** 或 **TCP 长时间失败**（如 RX 超时 2min）时触发，与软重连区分。
+
+OCPP 侧 **WS 握手失败**会关 socket 并清 **`u8_TCP_connect_flag`**，下一周期重试（**`v_ocpp_tcp_connect`**）。
+
+---
+
+## 6. 连接实现层（`impl/bs_connect_impl`）
+
+### 6.1 URL 解析
+
+**`parse_websocket_url_simple(url, ws_url_t *)`** 解析配置中的服务器串，得到：
+
+- **`host`**、**`port`**、**`path`**（WebSocket 路径）
+- **`is_secure`**：`ws://` → 0，`wss://` → 1
+- **`apn_str`**（4G 用，来自变量区 APN）
+
+全局 **`url_info`** 供网口/4G 共用。
+
+### 6.2 `u8_tcp_connect(u8_id)`
+
+| `u8_netType` | 路径 |
+|--------------|------|
+| **0（4G）** | 若 **`u8_4g_soft_tcp_reconnect`**：`s8_ec200a_tcp_socket_soft_reopen()`；失败累计达 **`EC200A_TCP_SOFT_REOPEN_FAIL_MAX`** 再 **`v_bs_4G_data_init()`**。否则 **`s8_ec200a_4g_init()`** 推进模组状态机至 Socket 就绪。 |
+| **1（网线）** | **`eth_do_tcp_connect`**：`netif_is_link_up` 检查 → **`lwip_tcp_connect`** → 可选 **`bs_tls_client_connect`**（wss）。成功写 **`fd`**，返回 1。 |
+
+### 6.3 统一收发
+
+| 接口 | 4G | 网线 |
+|------|-----|------|
+| **`v_bs_send`** | 透传 **`v_4g_send_data`** / 非透传 **`v_ec200a_tcp_app_send`（QISEND/QSSLSEND）** | **`lwip_tcp_send`** 或 **`bs_tls_client_send`** |
+| **`u16_bs_recv`** | **`u16_4g_recv_data`** / **`u16_ec200a_tcp_app_recv`（QIRD/QSSLRECV）** | **`lwip_tcp_recv`** / **`bs_tls_client_recv`**；对端关闭或 errno 异常 → **`eth_close_socket`** |
+
+每次 **`v_bs_send`** 后 **`mSleep(Plat_Send_Sleep)`**（默认 50ms），并累加 **`u8_sendCnt`** 用于任务末尾睡眠补偿。
+
+接收缓冲区上限：**`BS_BUF_SIZE_RECV`**（约 3KB，远程升级 JSON 可能较长）。
+
+---
+
+## 7. 公共实现层（`impl/bs_public_impl`）
+
+面向 **flow / meter / fault / UI / OCPP** 的**统一数据与控制 API**，是「业务世界」与「平台任务」的边界。
+
+### 7.1 主要能力分类
+
+| 分类 | 代表接口 | 说明 |
+|------|----------|------|
+| **系统/枪数据读** | **`u32_bs_get_sys_data`**、**`u8_get_str_data`** | 枪状态、电量、SOC、订单流水号、桩编号、4G 信号等。 |
+| **充电控制** | **`v_bs_charge_action_ctrl`** | 启停充、改订单字段（含 **`preTradeNo`** 写入计量日志）。 |
+| **状态/订单标志** | **`v_bs_log_txFlag_tradUpload`**、**`u8_bs_get_flow_state`** | 与 **`s_gundata`**、flowctrl 联动。 |
+| **未结订单** | **`s8_plat_get_unsettled_order`** | 优先 **EEPROM 掉电临时单**，再 **Flash 未结索引**；OCPP 补单数据源。 |
+| **结算确认** | **`v_bs_platform_settlement_confirm`** | StopTx 成功后删未结索引。 |
+| **FTP** | **`v_ftp_update_action`** | 按 **`t_ftp_update_info`** 与 **`u8_netType`** 分发 4G / LwIP FTP。 |
+| **OCPP 配置** | **`u8_set_ocpp_cfg_info`**、**`v_get_ocpp_cfg_info`** | 读写 Flash 中的 OCPP 配置项。 |
+| **本地鉴权** | **`v_ocpp_offline_local_authentication_check`**、**`u8_card_info_add`** | 离线卡列表与即插即充。 |
+
+### 7.2 未结订单来源（与掉电续传）
+
+**`s8_plat_get_unsettled_order`** 顺序：
+
+1. **EEPROM 临时记录**（**`v_check_temp_chg_record_valid`**）：充电中每 60s 快照；真正掉电后上电读出，置 **`E_FAULT_13073`**（异常掉电）。**充电中（flow=2）不当作掉电单**，避免误 StopTx。
+2. **Flash 未结列表**（**`unsettled_order_mng`**）：正常结束但未收到平台确认的订单索引。
+
+计量侧：**`v_meterlog_restore_temp_from_eeprom`** 上电恢复 RAM；**`preTradeNo` 更新后立即写 EEPROM**（见 **`meter_calculate_impl.c`**）。
+
+### 7.3 FTP 全局参数 `T_FTP_UPDATE_INFO`
+
+由 OCPP **UpdateFirmware** / **GetDiagnostics** 解析 **`parse_ftp_url()`** 填入：
+
+- 服务器地址、端口、用户、密码、路径、文件名
+- **`u8_netType`**：决定走 **4G AT FTP** 还是 **LwIP FTP**
+- **`u8_log_file_upload`**（OCPP 扩展）：1 = 诊断日志上传，0 = 固件升级
+
+**`v_ftp_update_action()`** 每 FTP 半周期推进一步，避免阻塞 PlatComm。
+
+---
+
+## 8. 4G 子系统（`4g_module/`）
+
+| 项目 | 说明 |
+|------|------|
+| **模组** | Quectel **EC200A** |
+| **业务 TCP** | **`QIOPEN` / `QSSLOPEN`**（wss 时模组内置 TLS），PDP **`EC200A_TCP_PDP_CTX_ID`** |
+| **FTP** | 独立 PDP **`EC200A_FTP_PDP_CTX_ID`**，与业务 TCP **禁止同 context** |
+| **模式** | **`EC200A_TCP_USE_TRANSPARENT_MODE`**：透传 vs **`QISEND`/`QIRD`** 缓冲模式 |
+| **与 PlatComm** | 仅通过 **`bs_connect_impl`** 的 **`v_bs_send`/`u16_bs_recv`** 接入；FTP 由 **`v_ftp_update_action`** 驱动 |
+
+**详细 AT 流程、QFTPGET/QFREAD 分片、与 OCPP 互斥宏** → **`4g_module/4G模块AT指令配置功能说明.md`**。
+
+---
+
+## 9. 网口子系统（`lwip_module/`）
+
+| 文件 | 职责 |
+|------|------|
+| **`lwip_module.c`** | **`lwip_tcp_connect` / `send` / `recv` / `close`**，非阻塞 socket |
+| **`lwip_ftp_upgrade.c`** | 网线 **FTP 固件下载** 状态机（PASV/RETR/按 1024B 写 Flash） |
+
+**`eth_do_tcp_connect`** 在 PHY **link down** 时不建连；重连前必须 **`v_bs_eth_close_socket`**。
+
+**详细状态机与触发条件** → **`lwip_module/lwip_ftp功能说明.md`**。
+
+---
+
+## 10. OCPP 子系统（`ocpp/`）
+
+在 **`BS_OCPP_EN`** 下，OCPP 作为 **`MasterFuncArray`** 中的一套 **Master** 实现：
+
+```text
+TCP (u8_tcp_connect)
+  → WebSocket 握手 (websocket_build)
+    → BootNotification (v_ocpp_logo_on)
+      → ocpp_send_mag_ctrl：Heartbeat / StatusNotification / MeterValues / Start&StopTransaction …
+      → ocpp_recv → recv_mags：平台下行与 CALLRESULT
+      → v_ocpp_private_logic：未结单 s8_unsettled_order_chaek、离线 MV 桥接、RX 超时重连
+```
+
+**离线 MeterValues**：未连接或未登录时 **`BS_ocpp_mv_offline_bridge`** 写 Flash；联网后 **session 补发**（在线会话）或 **unsettled 补发**（掉电/未结单）。
+
+**完整 PDU 列表、未结单状态机、session_001x 类问题修复说明** → **`ocpp/OCPP功能模块说明.md`**。
+
+---
+
+## 11. 端到端数据流（示意）
+
+### 11.1 正常充电上送（已登录）
+
+```mermaid
+flowchart TB
+    subgraph tasks
+        FC[FlowCtrl / Meterfee]
+        PC[PlatComm v_Plat_Comm]
+    end
+    subgraph ocpp
+        SEND[ocpp_send_mag_ctrl / send_mag]
+        WS[ws_send / bs_websocket]
+    end
+    subgraph link
+        BS[v_bs_send / u16_bs_recv]
+        TCP[u8_tcp_connect 4G or LwIP]
+    end
+  FC -->|订单/枪状态| PUB[bs_public_impl]
+  PUB --> SEND
+  PC --> SEND
+  SEND --> WS --> BS --> TCP
+  TCP --> CSMS[CSMS]
+  CSMS --> TCP --> BS --> WS --> RECV[ocpp_recv / recv_mags]
+  RECV --> PUB
+  PC --> RECV
+```
+
+### 11.2 掉电后补单（简化）
+
+```mermaid
+sequenceDiagram
+    participant M as meter/EEPROM
+    participant P as bs_public_impl
+    participant O as BS_ocpp_ctrl
+    participant S as CSMS
+    M->>P: s8_plat_get_unsettled_order
+    P->>O: s_unsettled_order_data
+    alt 无 preTradeNo
+        O->>S: Authorize
+        S->>O: Accepted
+        O->>S: StartTransaction
+        S->>O: transactionId
+    end
+    O->>S: MeterValues 离线补发
+    O->>S: StopTransaction PowerLoss
+```
+
+---
+
+## 12. 关键全局变量与调试
+
+| 符号 | 位置 | 用途 |
+|------|------|------|
+| **`s_bs_task_ctrl`** | `plat_comm_task.c` | 双平台连接态、枪标志、OCPP **`ocpp_data`**、IES **`s_ies_data`** |
+| **`t_ftp_update_info`** | `bs_public_impl.c` | FTP 升级/日志参数 |
+| **`url_info`** | `bs_connect_impl.c` | 解析后的 host/port/TLS |
+| **`private_ocpp_data`** | `BS_ocpp_ctrl.c` | OCPP 定时器、未结单指针、pending 通知 |
+| **`Plat_Comm_LOG` / `OCPP_PRINTF_LOG`** | 宏 | 任务日志（**`TASK_ID_PlatComm`** / **0xFF**） |
+
+**常见日志关键字**
+
+| 日志 | 含义 |
+|------|------|
+| `[n] tcp connect` | 第 n 槽传输层就绪 |
+| `[n] logOn is ok` | BootNotification 成功 |
+| `Load pwr-loss order gun=` | EEPROM 掉电单加载 |
+| `Unsettled: send StopTx` | 未结单补 StopTransaction |
+| `MV offline: session send ok` | 在线会话离线 MV 补发 |
+| `ws handshake fail` | WS 失败，将重试 TCP |
+| `End rx TO, relink` / `RX TO, relink` | 收包超时触发 **`v_set_bs_renew`** |
+
+---
+
+## 13. 关联文档索引
+
+| 文档路径 | 内容 |
+|----------|------|
+| **`ocpp/OCPP功能模块说明.md`** | OCPP 报文、未结单、离线 MV、Boot/Heartbeat、平台下行指令 |
+| **`ieszt/IES积成平台功能说明.md`** | IES 0x68 协议、`S_BS_IES_CTRL_DATA`、登录/心跳与 PlatComm 七回调 |
+| **`4g_module/4G模块AT指令配置功能说明.md`** | EC200A 初始化、透传/非透传、FTP 与 OCPP 分时、配置宏 |
+| **`lwip_module/lwip_ftp功能说明.md`** | 网线 FTP 升级状态机、与 **`v_ftp_update_action`** 关系 |
+| **`BSP/flash_file_mgr/`**（工程内） | 订单 Flash、未结索引、OCPP 离线 MV FRAM/SPI |
+| **`app/meter_calculate/`**（工程内） | 订单 RAM、EEPROM 临时单、周期存盘 |
+
+---
+
+## 14. 维护说明
+
+1. **新增平台协议**：在 **`plat_comm/`** 下增加子目录，实现 **`MasterFuncPtl`** 七个回调，并在 **`MasterFuncArray`** 中注册；**`BS_*_EN`** 与 **`E_BS_GET_SYS_DATA_PLAT_EN`** 对齐。
+2. **修改建链逻辑**：优先改 **`bs_connect_impl.c`**，业务层保持 **`v_bs_send`/`u16_bs_recv`** 不变。
+3. **FTP 与 OCPP 并发**：改 **`plat_comm_task.c`** 相位策略或 **`ec200a_4g_cfg.h`** 互斥宏前，须在 **4G 实机** 验证 **QISEND** 与 **QFTP** 不互相破坏。
+4. **未结/掉电单**：同时核对 **`bs_public_impl.c`**、**`meter_calculate_impl.c`**、**`BS_ocpp_ctrl.c`** 三处，避免 EEPROM 周期快照被误判为掉电单。
+
+---
+
+*文档版本：与 CCU601E_D plat_comm 源码同步维护；若宏或文件名变更，请以实际编译配置为准。*