238 lines
14 KiB
Markdown
238 lines
14 KiB
Markdown
# Page 1
|
||
|
||
语⾔版本函数调⽤指南
|
||
C
|
||
版本V1.0
|
||
1. 概述
|
||
本指南旨在为 CH32 单⽚机其他业务代码提供调⽤“图像预处理模块”和“TCP 打包与发送模块”的 C 语⾔ API 说明。这两个模块被封装为独⽴的底层库函数，
|
||
负责将原始采集数据处理并推送⾄上位机，同时接收上位机配置。
|
||
开发者⽆需关⼼内部的滑窗算⼒优化或是 TCP 连接维持、分⽚等细节，只需按照约定的结构体提供⼊参并调⽤相关 API 即可。
|
||
2. 核⼼数据结构
|
||
2.1 原始图像数据结构 ( RawImageBuffer_t )
|
||
该结构由采集模块（⿊盒）在采集完成后构建并传⼊处理库。注意：本库所有内部计算和过滤针对的均是 16位整数矩阵 (精确到 0.1℃的定点数)。
|
||
typedef struct {
|
||
uint16_t* pData; // 指向二维 16位 整数矩阵的起始指针(如 275 代表 27.5℃)
|
||
uint16_t Width; // 原始图像宽度
|
||
uint16_t Height; // 原始图像高度
|
||
uint32_t FrameNumber; // 当前帧号（或时间戳），用于溯源
|
||
} RawImageBuffer_t;
|
||
2.2 预处理结果结构 ( PreprocessResult_t )
|
||
预处理模块运算完毕后产出的有效数据载荷结构。
|
||
typedef struct {
|
||
uint8_t* pValidData; // 必须是 uint8_t 类型的外部缓冲区指针，规避结构体强转导致的内存对齐陷阱
|
||
uint32_t DataLength; // 有效数据的字节长度 (宽度 * 高度 * sizeof(元素))
|
||
uint16_t ValidWidth; // 产出图像宽度 (对于一维，可表示点数)
|
||
uint16_t ValidHeight; // 产出图像高度
|
||
int16_t MinTemp; // 有效区域内的最低温度
|
||
int16_t MaxTemp; // 有效区域内的最高温度
|
||
int16_t AvgTemp; // 有效区域内的平均温度
|
||
int16_t RoiTemp; // 触发点温度
|
||
uint8_t Status; // 处理状态 (0: OK, 1: 异常)
|
||
uint32_t FrameNumber; // 继承自原始图像的帧号
|
||
} PreprocessResult_t;
|
||
2.3 ⽹络封装缓冲结构 ( TcpTxBuffer_t )
|
||
专为 TCP 零拷⻉封包设计的外部分配缓冲区。应⽤层（或专⻔的内存池）提供⾜够⼤的连续内存空间。
|
||
typedef struct {
|
||
uint8_t* pBuffer; // 指向由应用层分配的具体内存区 (包含物理组装全空间)
|
||
uint32_t TotalCapacity; // 该 Buffer 总容量
|
||
uint32_t HeadOffset; // 【核心】预留给封包用的首部偏移量。载荷将从 pBuffer + HeadOffset 开始写入
|
||
uint32_t ValidPayloadLen; // 在调用封装函数后，由网络库回填的最终报文总长度
|
||
} TcpTxBuffer_t;
|
||
|
||
# Page 2
|
||
|
||
2.4 系统运⾏状态与配置 ( ConfigCommon_t , Config2D_t , Config1D_t )
|
||
系统参数配置不再使⽤单⼀的句柄封装，⽽是由通信协议中定义的三个独⽴结构体分别管理： ConfigCommon_t （通⽤参数）、 Config2D_t （⼆维专有参数）
|
||
与
|
||
Config1D_t
|
||
（⼀维专有参数）。TCP 模块会通过回调动态更新这三个结构体，应⽤层需要保存最新配置以供预处理等模块使⽤（详⻅通信协议规范 2.0）。
|
||
3. 预处理模块 API
|
||
3.1 Preprocess_Init
|
||
功能：初始化预处理模块，分配静态计算所需的⼯作内存（如列累加数组）。
|
||
原型：
|
||
int8_t Preprocess_Init(uint16_t maxWidth, uint16_t maxHeight);
|
||
⼊参：
|
||
maxWidth / maxHeight : 系统允许的最⼤处理分辨率，⽤于预分配内存池。
|
||
返回值： 0 成功， <0 失败。
|
||
3.2 Preprocess_Execute
|
||
功能：对单帧⼆维矩阵进⾏裁剪并导出。系统会基于温度过滤启动滑动窗⼝去寻找热源，锁定⽬标区域（ROI）后，会将这段区域内未被修改过的真实
|
||
原始像素原样导出，写⼊外部提供的 Buffer 中。
|
||
原型： int8_t Preprocess_Execute(const RawImageBuffer_t* input, TcpTxBuffer_t* out_buffer, PreprocessResult_t* output_meta);
|
||
⼊参：
|
||
input : 采集模块提供的原始数据句柄。
|
||
out_buffer : 应⽤层预先分配好的待发送缓冲区。库将直接通过 out_buffer->pBuffer + out_buffer->HeadOffset 零拷⻉写⼊原始图像测温字节。
|
||
出参：
|
||
output_meta : 运算完成的规范化统计结果（⻓宽、最⼤、最⼩温度、平均温度等信息，统计依据同样为未失真的原始像素）。
|
||
返回值：
|
||
0
|
||
表⽰处理成功并锁定 ROI，
|
||
<0
|
||
表⽰内存越界或其他致命错误。
|
||
3.3 Preprocess_CheckInternalTrigger2D
|
||
功能：根据上位机设定的“触发 ROI 区域”、“温度触发阈值”及“判定条件(最⾼温/平均温)”，对传⼊的单帧原始图像进⾏内部热源触发判定。
|
||
原型：
|
||
int8_t Preprocess_CheckInternalTrigger2D(const RawImageBuffer_t* input);
|
||
⼊参：
|
||
input : 当前需要评判的原始图像。
|
||
返回值： 1 表⽰触发条件满⾜（画⾯中设定的 ROI 区域发现了⾜够⾼温的⽬标）， 0 表⽰未触发， <0 参数错误。
|
||
使⽤场景：在内部触发机制（ TriggerMode = 0 ）下，结合相机的连续 DMA 或轮询输出使⽤。
|
||
3.4 Preprocess_Settings_Change
|
||
功能：安全地将通过 TCP 接收到的最新业务⼯作参数更新⾄预处理库内部。⽀持影⼦机制加锁更新策略，确保不会破坏正在进⾏处理的流⽔线帧。
|
||
原型： int8_t Preprocess_Settings_Change(const Config2D_t* newConfig2D, const Config1D_t* newConfig1D, const ConfigCommon_t* newCommon);
|
||
⼊参：
|
||
newConfig2D / newConfig1D : 从上位机新下发的专⽤参数结构体（如 TargetWidth , TriggerTemperatureThreshold ）。
|
||
newCommon : 从上位机新下发的通⽤配置结构体。
|
||
返回值： 0 成功， <0 失败。
|
||
4. TCP 打包与发送模块 API
|
||
4.1 TcpLogic_Init
|
||
功能：初始化整个应⽤层 TCP 管理任务，包括底层 Socket 绑定、接收任务建⽴以及缓冲池初始化。
|
||
原型： int8_t TcpLogic_Init(const uint8_t* deviceUUID, const uint8_t* authToken);
|
||
⼊参：
|
||
deviceUUID : 16 字节的设备物理识别码（如 MAC 或 UID）。
|
||
authToken : ⾝份验证令牌。
|
||
返回值：
|
||
0
|
||
成功，
|
||
<0
|
||
失败。
|
||
|
||
# Page 3
|
||
|
||
4.2 TcpLogic_Start
|
||
功能：⾮阻塞启动 TCP 服务管理引擎。此后库将在后台⾃动进⾏ 5511 (控制流) 与 5512 (数据流) 的连接、握⼿(Handshake)、重连和⼼跳维持。
|
||
原型：
|
||
void TcpLogic_Start(void);
|
||
4.3 TcpLogic_BuildAndSendTemperatureFrame
|
||
功能：将之前由预处理写⼊ TcpTxBuffer_t 内的数据（连同 PreprocessResult_t 结构体中的统计数据）封装。函数不需要搬移⼤块矩阵数据，直接利
|
||
⽤移位操作和 HeadOffset 空间从前向后组装报⽂头（包含 TLV、Magic等），最后压⼊ 5512 发送缓冲。
|
||
原
|
||
型：
|
||
int8_t TcpLogic_BuildAndSendTemperatureFrame(TcpTxBuffer_t* io_buffer, const PreprocessResult_t* processMeta, uint8_t frameType, uint8_t is2D);
|
||
⼊参：
|
||
io_buffer : 包含已被预处理模块填充过载荷的 Buffer 包裹器。本函数执⾏完后，其中的 ValidPayloadLen 将被更新。
|
||
processMeta : 包含帧号与温区极值统计。
|
||
frameType : 帧类型 (0x00 LIVE, 0x01 TRIGGER, 0x02 MASKED)。
|
||
is2D : 1 为⼆维数组， 0 为⼀维。
|
||
返回值： 0 已组装完毕并压⼊队列， <0 失败。
|
||
4.4 TcpLogic_GetLatestConfig
|
||
功能：主动查询并返回 TCP 库缓存的、由上位机最近⼀次下发的完整配置参数结构体。适⽤于应⽤层需要在⾮回调上下⽂中（如初始化后⾸次同步或
|
||
故障恢复后重新拉取）获取当前⽣效配置的场景。
|
||
原型：
|
||
int8_t TcpLogic_GetLatestConfig(ConfigCommon_t* out_common, Config2D_t* out_cfg2d, Config1D_t* out_cfg1d);
|
||
出参：
|
||
out_common : 由调⽤者提供的通⽤配置结构体指针，库将最新缓存的通⽤配置拷⻉到此处。
|
||
out_cfg2d : 由调⽤者提供的⼆维专有配置结构体指针。
|
||
out_cfg1d : 由调⽤者提供的⼀维专有配置结构体指针。
|
||
返回值：
|
||
0
|
||
成功（配置有效），
|
||
-1
|
||
尚未从上位机收到过任何配置，
|
||
<0
|
||
其他错误。
|
||
4.5 接收与配置更新回调注册
|
||
TCP 库在后台线程处理收到的指令（如参数更改或控制信号）。主业务通过注册回调函数来处理这些上位机下发的事件，确保底层安全。
|
||
// 定义回调函数类型
|
||
typedef void (*ConfigUpdateCallback_t)(const ConfigCommon_t* common, const Config2D_t* cfg2d, const Config1D_t* cfg1d);
|
||
typedef void (*DetectionResultCallback_t)(uint32_t frameNumber, uint8_t resultStatus);
|
||
// 【注意】：此回调专门用于测试上位机主动请求帧。实际业务由硬件触发或DMA循环完成，业务代码不应依赖或实现此回调。
|
||
typedef void (*TempFrameRequestCallback_t)(uint8_t is2dRequest);
|
||
// 注册回调 API
|
||
void TcpLogic_RegisterConfigCallback(ConfigUpdateCallback_t cb);
|
||
void TcpLogic_RegisterDetectionCallback(DetectionResultCallback_t cb);
|
||
void TcpLogic_RegisterTempFrameRequestCallback(TempFrameRequestCallback_t cb);
|
||
应⽤⽰例：参数热更新
|
||
当注册了 ConfigUpdateCallback_t ，TCP 发⽣控制流的参数接收时，后台库完成参数解析及 CRC 校验后，触发此回调。⽤⼾可在回调中利⽤软中断或影⼦
|
||
积存器机制将新参数赋予当前正在使⽤的
|
||
SystemConfig_t
|
||
。
|
||
5. 核⼼ API 设计准则与开发规范
|
||
为兼顾底层性能考量与可靠性⽹络封装，本库严格遵循以下原则：
|
||
1. “传⼊指针 + ⻓度” 与预留偏移封包 (Zero-Copy Offset) ⽅案
|
||
物理内存分配由应⽤层（依托其内存池机制）负责，传递给库的操作句柄为 out_buffer 。预处理在填充矩阵数据时，会越过 HeadOffset （这个偏移量
|
||
等于后续 TCP 组合包所需的 Header 及 TLV 指⽰器的⼤⼩）。后续 TCP ⽹络库封装时，仅需要往前填充封包信息，⽆需对上百 KB 的矩阵数据做任何
|
||
memcpy
|
||
内存搬移动作。
|
||
|
||
# Page 4
|
||
|
||
2. 防范访问陷阱 (Strict uint8_t Vectoring)
|
||
禁⽌将⽹⼝收发缓冲区中的指针强转为 uint32_t 或是具体通讯结构体使⽤。库内部所有的数据移动与地址递增处理严格使⽤ uint8_t * 处理⽹络数据
|
||
流，从根本上阻绝了因不同编译器或单⽚机对⻬法则不⼀导致的 HardFault 或越界访问。
|
||
3. 内置安全⼤⼩端转化 (Bitwise Disassembly/Assembly)
|
||
**这是针对 16位 整数矩阵数据的核⼼保障。**⽆论是将采集到的定点温度（ uint16_t / int16_t ）拆分成⽹络字节流（封包），还是从字节流解析成单⽚
|
||
机状态（解包），都彻底抛弃了直接强转或结构体对⻬强塞的⽅式。库内部严格规定使⽤单字节移位操作（如 val = (buf[0]) | (buf[1]<<8); ），完美
|
||
解决“⽹络端与主机⼩端”之间的安全切换，并在提取矩阵数据时保证 2-Byte Little-Endian 输出。
|
||
6. 底层数据收发机制与平台移植架构 (Port 层解耦)
|
||
（预处理及TCP封包逻辑）绝对不会直接操作硬件寄存器或特定的 Socket API。
|
||
取⽽代之的是⼀个位于 qdx_port.h 的硬件抽象层（HAL，Port层）。
|
||
1. 发送：硬件发送缓冲区写⼊地址 ( qdx_port_tcp_send )
|
||
当应⽤层调⽤类似 TcpLogic_BuildAndSendTemperatureFrame 时，传递的是在外部通过内存池预先分派好、并在前⾯加上了协议头的业务缓冲数组（即
|
||
io_buffer->pBuffer ）。⽹络库内部并不会“写⼊⽹卡相关的寄存器”，⽽是调⽤ qdx_port_tcp_send 。这保证了只需将封装好的完整、连续的 RAM 地址
|
||
指针和⻓度丢给驱动层。内部的 WCH NET 或 LwIP 会从给定的这个内存地址将其发往 DMA 或以太⽹ MAC。
|
||
2. 接收：硬件接收缓冲区 ( qdx_port_tcp_recv )
|
||
对应地，系统会启动后台线程监听 TCP 数据流。它每次都会从 qdx_port_tcp_recv 尝试获取数据，由底层协议栈驱动将接收到的真正⽹络⽐特流存⼊
|
||
库提供的接收缓冲中，随后库再去解析配置命令。
|
||
7. 常规调⽤流程图 (伪代码模式)
|
||
// 1. 初始化
|
||
Preprocess_Init(MAX_W, MAX_H);
|
||
TcpLogic_Init(MyUUID, MyToken);
|
||
TcpLogic_RegisterConfigCallback(OnConfigUpdated);
|
||
TcpLogic_RegisterDetectionCallback(OnHardwareReject);
|
||
// 2. 启动网络引擎线程 (RTOS环境下)
|
||
TcpLogic_Start();
|
||
// 3. 图像中断 / DMA 轮询回调
|
||
void OnCameraDataReady(uint16_t* matrix, uint16_t w, uint16_t h) {
|
||
RawImageBuffer_t rawBuff = {matrix, w, h, ++frameCnt};
|
||
// 【核心】判断这帧图像里是否有物体达到了设定的触发温度
|
||
if (Preprocess_CheckInternalTrigger2D(&rawBuff) == 1) {
|
||
// 发现高温目标！分配一块发送专用的零拷贝缓冲
|
||
TcpTxBuffer_t txBuff = MemoryPool_GetTxBuffer();
|
||
PreprocessResult_t resMeta = {0};
|
||
// 交由库执行滑动窗口剪裁，将最核心的高温区域内原始像素直接填入缓冲的预留偏移后
|
||
if (0 == Preprocess_Execute(&rawBuff, &txBuff, &resMeta)) {
|
||
// TCP封包：在头部预留好的 HeadOffset 内执行无损组包并发出
|
||
TcpLogic_BuildAndSendTemperatureFrame(&txBuff, &resMeta, 0x01, 1);
|
||
} else {
|
||
MemoryPool_FreeTxBuffer(&txBuff);
|
||
}
|
||
}
|
||
}
|
||
// 4. 当参数更新回调触发时
|
||
void OnConfigUpdated(const ConfigCommon_t* common, const Config2D_t* cfg2d, const Config1D_t* cfg1d) {
|
||
// 将获得配置输入给预处理模块，利用互斥锁安全地刷新工作参数（如 TriggerRoi）
|
||
Preprocess_Settings_Change(cfg2d, cfg1d, common);
|
||
}
|
||
|
||
# Page 5
|
||
|
||
6. 函数调⽤时序图 (Control Flow)
|
||
通过下⽅时序图，可清晰展⽰从设备启动，到外部通信介⼊，再到硬件持续触发采集的数据流动与函数调⽤顺序。
|
||
|
||
# Page 6
|
||
|
||
主机/中断(Main) TcpLogic (⽹络库) Preprocess (预处理库) ConfigServer (上位机)
|
||
1. Preprocess_Init(W, H)
|
||
2. TcpLogic_Init(UUID, Token)
|
||
3. TcpLogic_RegisterConfigCallback()
|
||
4. TcpLogic_Start()
|
||
5. ⾃动连接 5511 与 5512，完成握⼿
|
||
6. 下发⾸批动态配置指令 (Type 0x20/0x22)
|
||
7. 触发参数回调 OnConfigUpdated()
|
||
8. Preprocess_Settings_Change(cfg)
|
||
循环运转：依靠中断或任务调度持续⼯作
|
||
9. 分配待发内存 TcpTxBuffer_t(预留 Offset)
|
||
10. 等待相机 DMA 完成⼀帧或 IO 触发
|
||
11. Preprocess_Execute(&rawBuff, &txBuff)
|
||
在 Offset 位置后写⼊图⽚矩阵⻓串数据
|
||
返回处理 meta 信息及成功的 txBuff
|
||
12. TcpLogic_BuildAndSend(txBuff)
|
||
在头部 Offset 内利⽤移位封包 TLV/序列号
|
||
数据送⼊ TCP 流发送 (零拷⻉达成)
|
||
opt [获取到剔除响应]
|
||
TCP 数据流返回 Defect Result (NG)
|
||
触发 DetectionResultCallback
|
||
拉⾼ DO1 定时执⾏剔除动作
|
||
主机/中断(Main) TcpLogic (⽹络库) Preprocess (预处理库) ConfigServer (上位机)
|
||
|