zhoujie b69717b964 📝 docs(design): 新增系统设计文档集

✨ 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 按需截图工作方式
- 列出错误码表和对接故障排查步骤

2026-03-15 19:17:41 +08:00

2.9 KiB

Raw Permalink Blame History

qdx-protocol-design Specification

Purpose

TBD - created by archiving change software-design-doc. Update Purpose after archive.

Requirements

Requirement: TLV 帧结构完整描述

文档 SHALL 描述 QDX 协议的完整帧结构，包含帧头各字段含义、TLV 格式和帧尾 CRC。

Scenario: 开发者手动构造一个协议帧

WHEN 开发者需要调试发送内容时
THEN 文档 SHALL 提供帧结构：[FrameHeader 16B] + [TLV_Header 3B] + [Value NB] + [CRC16 2B]，其中 FrameHeader = {Magic(2)=0x55AA, Version(1)=0x20, Length(2), Sequence(2), Timestamp(4), Source(1), DevID(2), Class(1), Flags(1)}

Scenario: 开发者理解 Class 和 TLV Type 的对应关系

WHEN 开发者解析收到的帧时
THEN 文档 SHALL 列出完整的 Class/Type 映射表：CLASS_CONTROL(0x01)、CLASS_DATA(0x02)、CLASS_RESPONSE(0x03)、CLASS_SYSTEM(0x04)；Type 包含 TYPE_HANDSHAKE(0x01)、TYPE_HEARTBEAT(0x02)、TYPE_TEMP_FRAME(0x10)、TYPE_CONFIG_COMMON(0x20)、TYPE_CONFIG_2D(0x22)、TYPE_CONFIG_1D(0x23)、TYPE_ACK_PAYLOAD(0x30)、TYPE_DETECTION_RESULT(0x40) 等

Requirement: 零拷贝 TX 缓冲区架构描述

文档 SHALL 描述 TcpTxBuffer_t 的双缓冲零拷贝发送架构和 HeadOffset 的使用方式。

Scenario: 开发者理解零拷贝的实现方式

WHEN 开发者需要在减少内存拷贝的前提下添加新的帧类型时
THEN 文档 SHALL 说明：TcpTxBuffer_t 包含 pBuffer（9216B）、HeadOffset（64B）、ValidPayloadLen；图像数据由预处理模块写入 pBuffer + HeadOffset 开始的位置；TcpLogic_BuildAndSendTemperatureFrame 在 HeadOffset 前的 64 字节内直接写入帧头（FrameHeader + TLV），无需额外 memcpy

Scenario: 开发者计算单次可发送的最大像素数

WHEN 开发者调整 ROI 大小时
THEN 文档 SHALL 说明：有效载荷容量 = TotalCapacity(9216) - HeadOffset(64) - CRC(2) - TLV_Header(3) - FrameHeader(16) = 9131 字节，每像素 2 字节，最多 4565 个像素（约 67×67 ROI）

Requirement: 分片机制描述

文档 SHALL 描述协议层的分片上限和分片标志用法。

Scenario: 开发者发送超大载荷时

WHEN 开发者发送超过 MAX_FRAGMENT_PAYLOAD(1400B) 的数据时
THEN 文档 SHALL 说明分片最大载荷为 1400B（受 TCP MSS=1460 限制），大帧通过 FLAG_LAST_FRAGMENT(0x20) 标志标识末片；当前 TX 缓冲区为 9216B，单次发送通常不超过此限制

Requirement: Flags 字段用法描述

文档 SHALL 描述 FrameHeader.Flags 各位的含义和当前固件的使用情况。

Scenario: 开发者解析收到的 Flags 字段

WHEN 上位机解析帧时
THEN 文档 SHALL 说明：FLAG_PRIORITY_MASK(0x03)=优先级（0-3）、FLAG_COMPRESSED(0x04)=压缩（当前未使用）、FLAG_ENCRYPTED(0x08)=加密（当前未使用）、FLAG_ACK_REQ(0x10)=需要 ACK、FLAG_LAST_FRAGMENT(0x20)=末片标志

2.9 KiB Raw Permalink Blame History Unescape Escape