372 lines
16 KiB
Markdown
372 lines
16 KiB
Markdown
# tcp_ser 模块说明
|
||
|
||
> 本文档描述 `CCU621_M` 工程 `app/tcp_ser` 目录的职责划分、**完整文件清单**、各源文件功能、TCP/BLE 双链路与命令处理流程。
|
||
> 返回主说明：[README](../../README.md)
|
||
|
||
**文档版本**：与当前工程树同步（含 BLE 调试、`debug_link` 链路层；**阶段1** 已合并 `comm_link`+Socket；**阶段2** 已合并文件类业务；**不含** `fwbin_protocol` / `fwup_protocol`）。
|
||
|
||
## 快速跳转
|
||
|
||
- [1. 模块总览](#1-模块总览)
|
||
- [2. 目录与文件清单（完整）](#2-目录与文件清单完整)
|
||
- [3. Keil 工程源文件](#3-keil-工程源文件)
|
||
- [4. 各文件功能说明](#4-各文件功能说明)
|
||
- [5. 分层架构与调用关系](#5-分层架构与调用关系)
|
||
- [6. TCP / BLE 双链路](#6-tcp--ble-双链路)
|
||
- [7. 已支持命令与处理路径](#7-已支持命令与处理路径)
|
||
- [8. 关键流程](#8-关键流程)
|
||
- [9. 固件升级（FirmwareUpgrade）](#9-固件升级firmwareupgrade)
|
||
- [10. GunInfo 数据规则](#10-guninfo-数据规则)
|
||
- [11. CustomData / HistoryOperations](#11-customdata--historyoperations)
|
||
- [12. 编译开关与运行条件](#12-编译开关与运行条件)
|
||
- [13. 维护注意事项](#13-维护注意事项)
|
||
- [14. 已移除 / 不在树内的文件](#14-已移除--不在树内的文件)
|
||
- [关联文档](#关联文档)
|
||
|
||
---
|
||
|
||
## 1. 模块总览
|
||
|
||
`tcp_ser` 是 CCU621 的 **上位机调试服务**模块：协议与业务在 `tcp_server` / `tcp_protocol` 中**共用**，物理链路通过 `comm_link` 在 **以太网 TCP** 与 **蓝牙 BLE（FC41D）** 之间切换。
|
||
|
||
| 职责 | 说明 |
|
||
|---|---|
|
||
| 链路适配 | `comm_link`：DIP1 选 TCP 或 BLE，对上统一 `receive/send/process` |
|
||
| TCP 服务 | 监听端口（默认 **9699**），单客户端 |
|
||
| BLE 服务 | FC41D GATT 非透传（fff1/fff2/fff3），广播名默认 `CCU621_Debug` |
|
||
| 周期上送 | 每 **2s** 推送 `SystemInfo` + 双枪 `GunInfo`（客户端发 `Heartbeat` 保活） |
|
||
| 命令处理 | JSON v2.0 解析、分发、组响应 |
|
||
| 业务解耦 | 协议层与充电控制、参数、文件、升级等分离 |
|
||
|
||
```
|
||
上位机 / 小程序
|
||
│ JSON（同一套 v2.0 协议）
|
||
▼
|
||
tcp_server.c ← RX 缓冲、JSON 抽帧、周期上送、连接管理
|
||
│
|
||
├── debug_link.c ← 链路层（comm_link 分发 + TCP Socket + 会话上下文）
|
||
│ └── ble_link/fc41d_ble.c （UART7 AT + GATT，BLE 后端）
|
||
│
|
||
└── tcp_protocol.c ← JSON 解析 / 组包 / 命令路由
|
||
├── debug_files.c ← FileOperations + FirmwareUpgrade
|
||
├── system_data.c
|
||
└── system_paracfg.c
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 目录与文件清单（完整）
|
||
|
||
当前 `app/tcp_ser/` 共 **19 个文件**（含 `ble_link/` 子目录；`.c` 源文件 7 个）：
|
||
|
||
```
|
||
app/tcp_ser/
|
||
├── tcp_ser_task.c # FreeRTOS 任务入口
|
||
├── tcp_ser_task.h
|
||
├── tcp_server.c # 调试服务主逻辑（经 comm_link 收发）
|
||
├── tcp_server.h
|
||
├── debug_link.c # 链路层：comm_link 分发 + lwIP Socket + 会话上下文
|
||
├── debug_link.h # 链路层对外 API 与类型
|
||
├── debug_files.c # 文件类业务：FileOperations + FirmwareUpgrade
|
||
├── debug_files.h # 文件类业务对外 API 与类型
|
||
├── tcp_protocol.c # JSON v2.0 协议
|
||
├── tcp_protocol.h
|
||
├── system_data.c # 运行时数据、充电控制、历史、CustomData
|
||
├── system_data.h
|
||
├── system_paracfg.c # 参数映射表
|
||
├── system_paracfg.h
|
||
├── ble_link/ # ── BLE 子目录（BLE_DEBUG_EN=1 时编入）
|
||
│ ├── fc41d_ble.c # FC41D 完整实现 + comm_link 后端
|
||
│ ├── fc41d_ble.h # 配置宏、对外 API
|
||
│ └── fc41d_ble_priv.h # BLE 私有上下文（与 tcp_link_ctx union）
|
||
├── TCP_DEBUG_PROTOCOL.md # JSON 报文字段说明
|
||
└── tcp_ser模块说明.md # 本文档
|
||
```
|
||
|
||
| 子目录 | 说明 |
|
||
|---|---|
|
||
| `ble_link/` | 仅 FC41D 蓝牙；UART7 AT 辅助函数为 **本目录 static**，不扩展公共 `BSP/com/usart.c` |
|
||
|
||
---
|
||
|
||
## 3. Keil 工程源文件
|
||
|
||
`Project/GD32H759.uvprojx` 中 `tcp_ser` 相关 **.c** 源文件（按工程登记）：
|
||
|
||
| 源文件 | 路径 |
|
||
|---|---|
|
||
| `tcp_ser_task.c` | `app/tcp_ser/` |
|
||
| `tcp_server.c` | `app/tcp_ser/` |
|
||
| `debug_link.c` | `app/tcp_ser/` |
|
||
| `fc41d_ble.c` | `app/tcp_ser/ble_link/` |
|
||
| `tcp_protocol.c` | `app/tcp_ser/` |
|
||
| `system_data.c` | `app/tcp_ser/` |
|
||
| `system_paracfg.c` | `app/tcp_ser/` |
|
||
| `debug_files.c` | `app/tcp_ser/` |
|
||
|
||
头文件通过 Include Path `..\app\tcp_ser` 及子目录引用，无需单独加入工程。
|
||
|
||
---
|
||
|
||
## 4. 各文件功能说明
|
||
|
||
### 4.1 任务与调度
|
||
|
||
| 文件 | 功能 |
|
||
|---|---|
|
||
| **`tcp_ser_task.c`** | `v_tcp_ser_task`：任务锁、看门狗；`BLE_DEBUG_EN` 时 `ble_link_wait_dip_ready()` 后 `comm_link_set_type(comm_link_type_from_dip())`；每 2s 重试 `tcp_server_start()`；循环 `tcp_server_process()`。 |
|
||
| **`tcp_ser_task.h`** | 声明 `v_tcp_ser_task`。 |
|
||
|
||
### 4.2 链路层（`debug_link`）
|
||
|
||
| 文件 | 功能 |
|
||
|---|---|
|
||
| **`debug_link.c`** | 阶段1 合并实现，分三段：<br>• **会话上下文**：单例 `comm_link_ctx_t`（`session` + `backend` union）<br>• **TCP Socket 后端**（本文件内 `static`）：lwIP `init/accept/receive/send/close` 等<br>• **comm_link 分发**：`comm_link_start/stop/process`、`comm_link_receive_data`、`comm_link_send_data` 等；按 `session.type` 转发到 TCP 或 `comm_link_ble_*` |
|
||
| **`debug_link.h`** | 链路层统一头：`COMM_LINK_TCP/BLE`、`comm_link_*` API、`comm_link_ctx_*`、`tcp_link_ctx_t`、`comm_link_backend_u` |
|
||
|
||
### 4.3 传输后端（BLE）
|
||
| **`ble_link/fc41d_ble.c`** | FC41D：AT 层、PE6 复位、BLE 状态机、GATT Notify 发送、`+QBLERECV` 解析；实现 `comm_link_ble_*`；UART7 **固定 115200**（`FC41D_UART_BAUD`），阻塞收包在 `fc41d_ble.c` 内 static 实现。 |
|
||
| **`ble_link/fc41d_ble.h`** | 硬件/AT 超时宏、`FC41D_BLE_NAME`、GATT UUID、`ble_link_is_bt_mode()`、`comm_link_ble_*` API。 |
|
||
| **`ble_link/fc41d_ble_priv.h`** | AT 缓冲、link/app RX 环、状态机枚举与 `fc41d_ble_ctx_t`。 |
|
||
|
||
### 4.4 服务主控层
|
||
|
||
| 文件 | 功能 |
|
||
|---|---|
|
||
| **`tcp_server.c`** | 核心状态机：<br>• 动态 RX 缓冲：常态 **1024B**，固件升级 **8192B**（`tcp_server_rx_upgrade_begin/end`）<br>• `comm_link_receive_data` 收包 → JSON 括号抽帧<br>• 周期上送：每 **2s** `SystemInfo` + 双枪 `GunInfo`；BLE 枪间加延时<br>• 升级进行中暂停周期上送；跳过前导垃圾字节（BLE 分片）<br>• 心跳超时 30s（升级中不判超时）<br>• TCP 回包可追加 `\r\n`；BLE 纯 JSON 无 CRLF |
|
||
| **`tcp_server.h`** | `tcp_server_state_t`、`tcp_server_start/process/stop`、`tcp_server_rx_upgrade_*`。 |
|
||
|
||
### 4.5 协议层
|
||
|
||
| 文件 | 功能 |
|
||
|---|---|
|
||
| **`tcp_protocol.c`** | JSON v2.0 组包/解析/分发；**BLE 链路拒绝 `FirmwareUpgrade`**；其余命令与 TCP 相同。 |
|
||
| **`tcp_protocol.h`** | `CMD_*`、结构体、状态枚举。 |
|
||
|
||
### 4.6 业务层
|
||
|
||
| 文件 | 功能 |
|
||
|---|---|
|
||
| **`system_data.c`** | `tcp_get_default_system_info/gun_data`、充电启停、`tcp_process_custom_data`、故障与历史记录；GunInfo 见 [§10](#10-guninfo-数据规则)。 |
|
||
| **`system_data.h`** | 业务接口与历史查询结构。 |
|
||
| **`system_paracfg.c/h`** | 七类参数映射表与读写。 |
|
||
| **`debug_files.c`** | 阶段2 合并实现，分两段：<br>• **FileOperations**（`FATFS_EN=1`）：Query/Delete/Download/Upload<br>• **FirmwareUpgrade**：TCP JSON+Base64 写外置 Flash；`system_filetransfer_is_active`、空闲超时等 |
|
||
| **`debug_files.h`** | 文件类业务统一头：`file_operation_data_t`、`firmware_upgrade_context_t`、`system_filectrl_*`、`system_filetransfer_*` |
|
||
|
||
### 4.7 协议文档
|
||
|
||
| 文件 | 功能 |
|
||
|---|---|
|
||
| **`TCP_DEBUG_PROTOCOL.md`** | 上位机 JSON 字段与示例（TCP/BLE 共用）。 |
|
||
|
||
---
|
||
|
||
## 5. 分层架构与调用关系
|
||
|
||
| 层次 | 文件 | 职责 |
|
||
|---|---|---|
|
||
| **任务** | `tcp_ser_task.c` | 选链路、启服务、周期 `tcp_server_process` |
|
||
| **服务** | `tcp_server.c` | 缓冲、抽帧、定时上送、连接/超时 |
|
||
| **链路** | `debug_link.c` | TCP/BLE 字节流统一接口 + Socket 后端 |
|
||
| **后端** | `debug_link.c`（TCP）/ `fc41d_ble.c`（BLE） | 物理收发 |
|
||
| **协议** | `tcp_protocol.c` | JSON ↔ 结构体、路由 |
|
||
| **业务** | `system_data.c` / `system_paracfg.c` / `debug_files.c` | 桩数据、参数、升级、文件 |
|
||
|
||
扩展新命令：改 `tcp_protocol.h/c` → 对应 `system_*.c` 或 `debug_files.c` → 更新 `TCP_DEBUG_PROTOCOL.md`。
|
||
|
||
---
|
||
|
||
## 6. TCP / BLE 双链路
|
||
|
||
### 6.1 选路
|
||
|
||
| 条件 | 物理链路 |
|
||
|---|---|
|
||
| `BLE_DEBUG_EN=0` | 恒为 TCP（DIP1=1 仅打日志，仍走 TCP） |
|
||
| `BLE_DEBUG_EN=1` 且 DIP1=0 | 以太网 TCP，端口 **9699** |
|
||
| `BLE_DEBUG_EN=1` 且 DIP1=1 | FC41D BLE GATT |
|
||
|
||
DIP 来源：副板 `sub_comm` → `u8_sub_comm_yx_get(E_SUB_DIP_1)`。
|
||
|
||
### 6.2 协议差异
|
||
|
||
| 项目 | TCP | BLE |
|
||
|---|---|---|
|
||
| 报文格式 | JSON v2.0 | 同左 |
|
||
| 下行结束符 | 可选 `\r\n` | 无 CRLF |
|
||
| 周期上报 | 2s SystemInfo + GunInfo×2 | 同左（枪间 ~80ms 间隔） |
|
||
| `FirmwareUpgrade` | 支持 | **拒绝**（`tcp_protocol.c`） |
|
||
| 固件相关 RX 缓冲放大 | 8192B | 同左（若走 TCP 升级） |
|
||
|
||
### 6.3 硬件（BLE）
|
||
|
||
| 项目 | 说明 |
|
||
|---|---|
|
||
| 模组 | Quectel FC41D |
|
||
| UART | UART7，PE1/PE0 |
|
||
| 复位 | PE6，`FC41D_RST` 高有效 |
|
||
| 广播名 | `CCU621_Debug`（可宏改） |
|
||
| 服务/特征 | fff1 / fff2(Write) / fff3(Notify) |
|
||
|
||
---
|
||
|
||
## 7. 已支持命令与处理路径
|
||
|
||
| command | 方向 | TCP | BLE | 业务入口 |
|
||
|---|---|:---:|:---:|---|
|
||
| `Heartbeat` | 双向 | ✓ | ✓ | 更新 `last_heartbeat_received_tick` |
|
||
| `SystemInfo` | 设备→上位机 | ✓ | ✓ | `tcp_get_default_system_info` |
|
||
| `GunInfo` | 设备→上位机 | ✓ | ✓ | `tcp_get_default_gun_data` |
|
||
| `ChargeControl` | 上位机→设备 | ✓ | ✓ | `system_data_start/stop_charge` |
|
||
| `ParamQuery` / `ParamModify` | 上位机→设备 | ✓ | ✓ | `system_paracfg` |
|
||
| `FileOperations` | 上位机→设备 | ✓ | ✓ | `system_filectrl_process_*` |
|
||
| `HistoryOperations` | 上位机→设备 | ✓ | ✓ | `tcp_history_build/clear_records` |
|
||
| `FaultInfo` | 上位机→设备 | ✓ | ✓ | `tcp_get_system_fault_data` |
|
||
| `CustomData` | 上位机→设备 | ✓ | ✓ | `tcp_process_custom_data` |
|
||
| `FirmwareUpgrade` | 上位机→设备 | ✓ | **✗** | `system_filetransfer_*`（仅 TCP） |
|
||
|
||
---
|
||
|
||
## 8. 关键流程
|
||
|
||
### 8.1 下行（上位机 → 设备）
|
||
|
||
```
|
||
comm_link_receive_data()
|
||
→ tcp_rx_buffer_append()
|
||
→ tcp_rx_buffer_extract_json() // 括号匹配；升级期可 skip 前导垃圾
|
||
→ tcp_server_process_received_data()
|
||
→ tcp_parse_json_message()
|
||
→ tcp_process_received_message()
|
||
→ system_* 业务
|
||
→ tcp_generate_*_json()
|
||
→ comm_link_send_data()
|
||
```
|
||
|
||
### 8.2 上行（周期，每 2s）
|
||
|
||
`tcp_server_send_ctrl()`：
|
||
|
||
1. 发送 `SystemInfo`
|
||
2. BLE 延时 ~120ms / TCP ~20ms
|
||
3. 依次发送枪 1、枪 2 的 `GunInfo`（BLE 枪间 ~80ms）
|
||
|
||
固件升级进行中：**不**做周期上送。
|
||
|
||
### 8.3 任务主循环
|
||
|
||
```
|
||
v_tcp_ser_task
|
||
├─ [BLE] ble_link_wait_dip_ready + comm_link_set_type(DIP1)
|
||
├─ tcp_server_start() → comm_link_start()
|
||
└─ tcp_server_process()
|
||
├─ comm_link_process() // BLE 状态机
|
||
├─ comm_link_accept_client() // 仅 TCP
|
||
├─ comm_link_receive_data()
|
||
├─ tcp_server_process_rx_buffer()
|
||
├─ system_filetransfer_poll_idle_timeout()
|
||
└─ tcp_server_send_ctrl()
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 固件升级（FirmwareUpgrade）
|
||
|
||
**仅 TCP 链路**。JSON + Base64 分包，写外部 Flash 升级区。
|
||
|
||
| subCommand | 关键字段 |
|
||
|---|---|
|
||
| `Start` | `fileSize`, `totalPackets`, `packetSize`, `firmwareVersion` |
|
||
| `Data` | `packetIndex`, `data`(Base64), `crc` |
|
||
| `End` | `status`, `errorMessage` |
|
||
| `Response` | `response`(ACK/NAK), `packetIndex` |
|
||
|
||
实现：`tcp_protocol.c` + `debug_files.c`（原 `system_filetransfer`）。升级时 RX 缓冲扩至 8192B，并可用 `system_filetransfer_get_expected_packet_bytes` 判断 Data JSON 是否收齐。
|
||
|
||
---
|
||
|
||
## 10. GunInfo 数据规则
|
||
|
||
`tcp_get_default_gun_data()`（`system_data.c`）：
|
||
|
||
1. **空闲 / 仅插枪**（`chargingStatus <= CONNECTED`）：`energy`、`cost`、`batterySOC`、`chargingTime` 置 **0**；`userId`、`orderNumber` 置 **空串**（避免 Flash 残留导致 JSON 过长、BLE 分片异常）。
|
||
2. **充电中**：从 `v_meterlog_put_char_log_data` 填实时量；`tcp_copy_log_field()` 安全拷贝用户/订单字段（遇非可打印 ASCII 或 `'\0'` 停止）。
|
||
3. **SOC**：限制 0–100。
|
||
|
||
---
|
||
|
||
## 11. CustomData / HistoryOperations
|
||
|
||
### CustomData
|
||
|
||
| functionField | 行为 |
|
||
|---|---|
|
||
| `paramInit` | `v_public_param_init()` |
|
||
| `reboot` | 应答后 `v_sys_reboot()` |
|
||
| `faultInfo` | 当前故障摘要 |
|
||
|
||
### HistoryOperations
|
||
|
||
`subCommand=Query`，`historyType=fault`：分页 `queryId` / `startIndex` / `fetchCount`，`content` 格式：
|
||
`location,code,desc,actType,value1,value2`。
|
||
|
||
---
|
||
|
||
## 12. 编译开关与运行条件
|
||
|
||
| 宏 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `TCP_DEBUG_EN` | `1` | 总开关；为 0 时整模块空桩 |
|
||
| `BLE_DEBUG_EN` | `1` | 为 0 时不编入 `fc41d_ble.c` 有效代码，恒 TCP |
|
||
| `TCP_DEBUG_PORT` | `9699` | TCP 监听端口 |
|
||
| `TCP_DEBUG_MAX_CLIENTS` | `1` | 单客户端 |
|
||
|
||
约束：`BLE_DEBUG_EN` 要求 `TCP_DEBUG_EN=1`（`#error` 保护）。
|
||
|
||
运行前提：
|
||
|
||
- **TCP**：lwIP 已初始化、网口可用
|
||
- **BLE**：FC41D 硬件 + UART7；`BSP/GPIO` 中 `FC41D_RST_PORT/PIN`（PE6）
|
||
- **文件操作**：FatFS 已挂载
|
||
- **固件升级**：外部 Flash + IAP
|
||
|
||
---
|
||
|
||
## 13. 维护注意事项
|
||
|
||
1. **协议与链路分离**：JSON 逻辑只在 `tcp_server` / `tcp_protocol`；换链路只动 `comm_link` 与后端。
|
||
2. **勿改公共 usart**：FC41D 的 UART7 固定 **115200**（`FC41D_UART_BAUD`），阻塞收包在 `fc41d_ble.c` 内 static 实现。
|
||
3. **GunInfo 字符串**：订单/用户字段必须用 `tcp_copy_log_field`，禁止对定长 `U8_T[]` 直接 `%s` / `strcpy`。
|
||
4. **BLE 包长**：单条 GunInfo JSON 宜控制在 GATT 分片友好范围；空闲态勿带长 `orderNumber`。
|
||
5. **Keil**：勿再加入已删除的 `fwbin_protocol.c`、`fwup_protocol.c`、`comm_link*.c`、`tcp_server_socket.c`、`system_filectrl.c`、`system_filetransfer.c`；须包含 `debug_link.c`、`debug_files.c`、`ble_link/fc41d_ble.c`。
|
||
6. **DIP 调试**：无模组时设 `BLE_DEBUG_EN=0` 或 DIP1=0 走 TCP。
|
||
|
||
---
|
||
|
||
## 14. 已移除 / 不在树内的文件
|
||
|
||
以下文件**不在**当前 `app/tcp_ser` 目录，亦**不应**加入 Keil 工程：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `fwbin_protocol.c/h` | FWBIN 二进制升级（`F0 F9`），已废弃 |
|
||
| `fwup_protocol.c` | FWUP 行协议升级，已废弃 |
|
||
| `tcp/tcp_socket.c` | 旧路径；Socket 已合并进 `debug_link.c` |
|
||
| `comm_link.c` / `comm_link_ctx.c` / `tcp_server_socket.c` | 阶段1 已合并为 `debug_link.c` |
|
||
| `system_filectrl.c` / `system_filetransfer.c` | 阶段2 已合并为 `debug_files.c` |
|
||
| `comm_link.h` / `comm_link_ctx.h` / `system_filectrl.h` / `system_filetransfer.h` / `tcp/` | 兼容头已删除，统一 `#include "debug_link.h"` / `"debug_files.h"` |
|
||
| `_backup_phase1/` / `_backup_phase2/` | 合并过程临时备份，已删除 |
|
||
|
||
历史方案可参考备份目录 `CCU621_M-蓝牙功能升级失败-退回前保存` 与 `docs/CCU621_M_固件升级十六进制协议_FWUP.md`（**已过时**）。
|
||
|
||
---
|
||
|
||
## 关联文档
|
||
|
||
| 文档 | 说明 |
|
||
|---|---|
|
||
| [`CCU621_M/README.md`](../../README.md) | 工程主索引 |
|
||
| [`TCP_DEBUG_PROTOCOL.md`](TCP_DEBUG_PROTOCOL.md) | JSON 报文字段与示例 |
|
||
| [`docs/CCU621_M_蓝牙调试通信方案.md`](../../docs/CCU621_M_蓝牙调试通信方案.md) | 蓝牙联调方案 |
|
||
| 本文 | `app/tcp_ser/tcp_ser模块说明.md` |
|