zhoujie
b69717b964
✨ feat(system-overview): 创建系统总览文档 - 描述项目背景与硬件平台配置 - 提供 FreeRTOS 任务拓扑表（任务优先级、栈大小、职责） - 详细说明系统启动序列和初始化依赖关系 - 绘制 2D/1D 状态机完整流程图 - 解释 TEMP_REQ 辅助通道工作机制 - 说明任务间同步机制（Frame_Ready_Flag、双缓冲 TX） ✨ feat(dvp-module-design): 创建 DVP 模块设计文档 - 提供 DVP 硬件连接引脚映射表 - 描述 DVP 时序配置（信号极性、工作模式） - 解释 DMA ping-pong 行缓冲机制和切换逻辑 - 说明 DVP IRQ 帧组装流程（STR_FRM/ROW_DONE） - 定义 FrameBuffer 数据格式和像素访问方式 - 说明 TMP 模式温度换算公式和字节序要求 ✨ feat(qdx-protocol-design): 创建 QDX 协议设计文档 - 描述完整 TLV 帧结构（FrameHeader + TLV + CRC） - 列出所有 Class/Type 映射表和用途说明 - 解释零拷贝 TX 缓冲区架构（HeadOffset 机制） - 说明分片机制和最大载荷限制 - 定义 Flags 字段各位含义和使用场景 ✨ feat(tcp-module-design): 创建 TCP 通信模块设计文档 - 描述双流连接架构（控制流 5511 / 数据流 5512） - 说明握手流程和连接建立时序 - 解释心跳机制和 TCP Keepalive 配置 - 描述配置下发与缓存机制 - 说明数据发送队列和背压处理策略 - 解释 WCHNET 网络栈驱动任务工作机制 ✨ feat(integration-guide): 创建对接集成指南 - 提供网络接入参数表（IP、端口、协议） - 详细说明握手流程和配置下发格式 - 提供 2D/1D 温度帧解析方法和示例代码 - 说明检测结果上报和 NG 响应机制 - 解释 TEMP_REQ 按需截图工作方式 - 列出错误码表和对接故障排查步骤
49 lines
3.6 KiB
Markdown
49 lines
3.6 KiB
Markdown
# tcp-module-design Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change software-design-doc. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: 双流连接架构描述
|
||
文档 SHALL 描述控制流（5511）和数据流（5512）的职责分工、连接方式和状态管理。
|
||
|
||
#### Scenario: 开发者理解双流设计意图
|
||
- **WHEN** 开发者排查连接问题时
|
||
- **THEN** 文档 SHALL 说明：控制流 srcport=5511（MCU 主动连接 Server），用于握手、配置下发、心跳、TEMP_REQ、DetectionResult 上报；数据流 desport=5512（MCU 主动连接 Server），用于温度帧数据上报；两流独立管理，数据流断开不影响控制流
|
||
|
||
#### Scenario: 开发者理解 TCP 连接建立时序
|
||
- **WHEN** 开发者排查首次握手失败时
|
||
- **THEN** 文档 SHALL 说明：`TcpLogic_Start` 派生后台连接状态机，先尝试控制流连接 → 连接成功后发送 TYPE_HANDSHAKE（含 DeviceUUID=MAC地址、AuthToken=NULL）→ 收到服务器握手响应后标记连接就绪 → 同步尝试数据流连接
|
||
|
||
### Requirement: 心跳机制描述
|
||
文档 SHALL 描述心跳帧的发送周期、TCP Keepalive 配置和连接保活策略。
|
||
|
||
#### Scenario: 开发者调整心跳参数
|
||
- **WHEN** 网络中间件（NAT/防火墙）超时断连时
|
||
- **THEN** 文档 SHALL 说明：应用层心跳 TYPE_HEARTBEAT 由 TcpLogic 内部定时发送；TCP Keepalive 配置：空闲 20 秒（`idle=20000ms`）后开始探测，每次间隔 15 秒（`interval=15000ms`），最多 9 次（`count=9`）探测无响应则断链重连
|
||
|
||
### Requirement: 配置下发与缓存机制描述
|
||
文档 SHALL 描述服务器配置的接收、缓存和通知流程。
|
||
|
||
#### Scenario: 开发者追踪配置更新流程
|
||
- **WHEN** 服务器下发配置后行为未按预期改变时
|
||
- **THEN** 文档 SHALL 描述：服务器发送 TYPE_CONFIG_COMMON + TYPE_CONFIG_2D + TYPE_CONFIG_1D → TcpLogic 解析并缓存至内部 shadow 寄存器 → 触发 ConfigUpdateCallback（`OnConfigUpdate`）→ 回调内调用 `Preprocess_Settings_Change` 更新预处理参数；`TcpLogic_GetLatestConfig` 可随时读取最新配置副本
|
||
|
||
#### Scenario: 开发者理解无配置时的默认行为
|
||
- **WHEN** 设备启动后服务器尚未下发配置时
|
||
- **THEN** 文档 SHALL 说明：`TcpLogic_GetLatestConfig` 返回 -1，业务任务跳过 2D/1D 处理，仅响应 TEMP_REQ（若有）；默认 burst 参数 DEFAULT_BURST_COUNT=3、DEFAULT_BURST_INTERVAL_MS=200ms 作为 fallback
|
||
|
||
### Requirement: 数据发送队列和背压处理描述
|
||
文档 SHALL 描述温度帧发送的队列机制和发送失败时的处理策略。
|
||
|
||
#### Scenario: 开发者排查数据帧丢失问题
|
||
- **WHEN** 网络繁忙时出现帧丢失时
|
||
- **THEN** 文档 SHALL 说明：`TcpLogic_BuildAndSendTemperatureFrame` 返回 0 表示成功入队，返回 <0 表示发送失败（队列满或连接断开）；当前固件对发送失败仅打印 DBG_ERR，不重试；双缓冲 TX 保证当前帧被入队时，下一帧可立即写入另一个缓冲
|
||
|
||
### Requirement: WCHNET 网络栈驱动任务描述
|
||
文档 SHALL 描述 task_wchnet 的职责和与 WCHNET 库的交互方式。
|
||
|
||
#### Scenario: 开发者理解网络栈如何被驱动
|
||
- **WHEN** 开发者排查网络响应迟缓问题时
|
||
- **THEN** 文档 SHALL 说明：`task_wchnet_entry` 每 5ms 轮询一次，调用 `WCHNET_MainTask`（协议栈心跳）和 `WCHNET_HandleGlobalInt`（socket 事件分发）；socket 接收/连接/断开事件通过 `qdx_port_sock_*_notify` 转发给 QDX 网络层；`qdx_port_net_lock/unlock` 用互斥量保护 WCHNET 调用，防止业务任务和网络任务并发访问
|
||
|