# 平台联网任务功能说明（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 源码同步维护；若宏或文件名变更，请以实际编译配置为准。*