Files
CCU621M/app/plat_comm/平台联网任务功能说明.md

349 lines
17 KiB
Markdown
Raw Permalink 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.
# 平台联网任务功能说明(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 = **4GEC200A**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` | 收包并解析 JSONCALL / 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 = 4G1 = 网线。 |
| **`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` | 路径 |
|--------------|------|
| **04G** | 若 **`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_ctrlHeartbeat / 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 源码同步维护;若宏或文件名变更,请以实际编译配置为准。*