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 按需截图工作方式 - 列出错误码表和对接故障排查步骤
63 lines
4.6 KiB
Markdown
63 lines
4.6 KiB
Markdown
# integration-guide Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change software-design-doc. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: 对接方网络接入参数说明
|
||
文档 SHALL 提供上位机（ConfigServer）与采集端建立 TCP 连接所需的全部参数。
|
||
|
||
#### Scenario: 对接方配置 TCP Server 监听端口
|
||
- **WHEN** 对接方开发服务端程序时
|
||
- **THEN** 文档 SHALL 提供：MCU 默认 IP=192.168.7.10，Subnet=255.255.255.0，Gateway=192.168.7.1；Server 需在 192.168.7.50 监听两个端口：5511（控制流，MCU 主动连入）和 5512（数据流，MCU 主动连入）；以太网接口为 1000M RGMII
|
||
|
||
### Requirement: 握手流程说明
|
||
文档 SHALL 描述 MCU 上电后的握手过程，使对接方能正确识别采集端设备。
|
||
|
||
#### Scenario: 对接方接收第一个数据包并识别设备
|
||
- **WHEN** MCU 连接后发送握手帧时
|
||
- **THEN** 文档 SHALL 说明：MCU 在控制流连接成功后发送 TYPE_HANDSHAKE（Class=CLASS_SYSTEM，含 ProtocolVersion=0x0200、DeviceUUID=MAC 地址、AuthToken=全零）；服务器 SHALL 回复握手响应以完成握手；握手完成后 MCU 才开始正常数据上报
|
||
|
||
### Requirement: 配置下发格式说明
|
||
文档 SHALL 描述服务器向 MCU 下发配置的帧格式和所有配置字段含义。
|
||
|
||
#### Scenario: 对接方配置 2D 触发模式
|
||
- **WHEN** 对接方发送 Config2D 配置帧时
|
||
- **THEN** 文档 SHALL 提供 Config2D_t 所有字段：Enabled(uint8_t)、TriggerMode(uint8_t, 0=内部温度/1=外部GPIO)、TriggerDebounceIntervalMs(uint16_t)、TriggerDelayMs(uint16_t)、TriggerBurstCount(uint8_t)、TriggerInternalIntervalMs(uint16_t)、TriggerTemperatureThreshold(int16_t, 0.1°C/LSB)、TriggerCondition(uint8_t, 0=Avg/1=Max)、TriggerRoiX/Y/W/H(uint16_t)、TargetWidth/Height(uint16_t)、NGioDelay(uint16_t, ms)
|
||
|
||
#### Scenario: 对接方配置 1D 采集模式
|
||
- **WHEN** 对接方发送 Config1D 配置帧时
|
||
- **THEN** 文档 SHALL 提供 Config1D_t 所有字段：Enabled(uint8_t)、RunMode(uint8_t, 0=STOP/1=RUN)、TriggerType(uint8_t, 1=内部/2=外部)、TriggerTempLimit(int16_t)、HighTimerLimit(uint16_t, ms)、NgCountLimit(uint16_t, 帧数)、BufferSize(uint16_t)、LSizeStart/RSizeStart(uint16_t, 切片参数)
|
||
|
||
### Requirement: 温度帧数据包格式说明
|
||
文档 SHALL 描述 MCU 上报的温度帧数据包的完整格式，使对接方能正确解析。
|
||
|
||
#### Scenario: 对接方解析收到的 2D 温度帧
|
||
- **WHEN** 数据流收到 TYPE_TEMP_FRAME 包时
|
||
- **THEN** 文档 SHALL 说明：Value 区域含 PreprocessResult 元数据（ValidWidth × ValidHeight 像素数组）；像素为 uint16_t little-endian，单位 0.1°C/LSB；元数据含 MaxTemp/MinTemp/AvgTemp/RoiTemp（均 int16_t, 0.1°C/LSB）、ValidWidth/ValidHeight（实际 ROI 尺寸）、FrameNumber
|
||
|
||
#### Scenario: 对接方解析收到的 1D 温度帧
|
||
- **WHEN** 数据流收到 1D TYPE_TEMP_FRAME 包时
|
||
- **THEN** 文档 SHALL 说明：is2D=0，每个样本 4 字节：[time_off_lo, time_off_hi, temp_lo, temp_hi]，time_offset 为相对采集开始的 ms 偏移（uint16_t），temp 为 uint16_t 0.1°C/LSB
|
||
|
||
### Requirement: 触发结果上报和 NG 响应机制说明
|
||
文档 SHALL 描述采集端如何响应服务器的 DetectionResult 决策和触发 NG 输出。
|
||
|
||
#### Scenario: 对接方下发检测结果
|
||
- **WHEN** 服务器完成图像分析后回传结果时
|
||
- **THEN** 文档 SHALL 说明：服务器发送 TYPE_DETECTION_RESULT（含 frameNumber、resultStatus，0=NG/1=OK）；MCU 收到 resultStatus=0 时触发 PA8 高电平 NGioDelay ms（默认 200ms）；对接方可通过 NGioDelay 配置 NG 输出脉宽
|
||
|
||
### Requirement: TEMP_REQ 按需截图说明
|
||
文档 SHALL 描述服务器如何向 MCU 请求即时截图。
|
||
|
||
#### Scenario: 对接方请求单帧截图
|
||
- **WHEN** 服务器需要调试或核查当前热场时
|
||
- **THEN** 文档 SHALL 说明：控制流发送 TYPE_CONFIG_COMMON 或专用 TEMP_REQ 命令（含 is2dRequest 字段）；MCU 将在下一个业务循环发送当前最新帧，2D 返回 ROI 裁切后温度矩阵，1D 返回中心行 30 个等间距采样点；仅在对应模式已 Enabled 时响应
|
||
|
||
### Requirement: 错误码和异常处理说明
|
||
文档 SHALL 列出协议层所有错误码含义及对接方应采取的处理措施。
|
||
|
||
#### Scenario: 对接方收到 ERR 响应帧
|
||
- **WHEN** 服务器发送格式错误的配置帧时
|
||
- **THEN** 文档 SHALL 列出错误码含义：ERR_CRC(0x1001)=CRC 校验失败、ERR_VERSION(0x1002)=协议版本不匹配、ERR_LENGTH(0x1003)=帧长度异常、ERR_AUTH(0x2001)=认证失败、ERR_BUSY(0x2002)=设备忙、ERR_PARAM(0x3001)=参数非法；收到错误码后对接方 SHALL 检查发送的帧格式后重试
|
||
|