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 按需截图工作方式 - 列出错误码表和对接故障排查步骤
42 lines
2.9 KiB
Markdown
42 lines
2.9 KiB
Markdown
# 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)=末片标志
|
||
|