wangyan/CCU621M
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9ceb218f8011451bcc701e3fd808b51b9dd64396
CCU621M/app/tcp_ser/tcp_ser模块说明.md
T

16 KiB
Raw Blame History

tcp_ser 模块说明

本文档描述 CCU621_M 工程 app/tcp_ser 目录的职责划分、完整文件清单、各源文件功能、TCP/BLE 双链路与命令处理流程。
返回主说明：README

文档版本：与当前工程树同步（含 BLE 调试、debug_link 链路层；阶段1 已合并 comm_link+Socket；阶段2 已合并文件类业务；不含 fwbin_protocol / fwup_protocol）。

快速跳转

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 合并实现，分三段：
• 会话上下文：单例 comm_link_ctx_t（session + backend union）
• TCP Socket 后端（本文件内 static）：lwIP init/accept/receive/send/close 等
• 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 核心状态机：
• 动态 RX 缓冲：常态 1024B，固件升级 8192B（tcp_server_rx_upgrade_begin/end）
• comm_link_receive_data 收包 → JSON 括号抽帧
• 周期上送：每 2s SystemInfo + 双枪 GunInfo；BLE 枪间加延时
• 升级进行中暂停周期上送；跳过前导垃圾字节（BLE 分片）
• 心跳超时 30s（升级中不判超时）
• 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。
system_data.h 业务接口与历史查询结构。
system_paracfg.c/h 七类参数映射表与读写。
debug_files.c 阶段2 合并实现，分两段：
• FileOperations（FATFS_EN=1）：Query/Delete/Download/Upload
• 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 工程主索引
TCP_DEBUG_PROTOCOL.md JSON 报文字段与示例
docs/CCU621_M_蓝牙调试通信方案.md 蓝牙联调方案
本文 app/tcp_ser/tcp_ser模块说明.md
Reference in New Issue View Git Blame Copy Permalink