ThetisLib：面向工业仪器仪表的嵌入式功能容器化库

1. ThetisLib 概述面向仪器仪表板的嵌入式功能容器化库ThetisLib 是一个专为 Thetis 仪器仪表板Thetis Instrumentation Board设计的嵌入式底层软件库其核心设计目标是将所有与硬件平台强相关的功能进行模块化封装与接口抽象形成可复用、可配置、可验证的“功能容器”Functional Container。该库并非通用外设驱动集合而是围绕 Thetis 板卡的特定硬件拓扑、信号链路、电源管理策略及系统级时序约束所构建的工程化中间件。从嵌入式系统架构视角看ThetisLib 处于 HALHardware Abstraction Layer之上、应用逻辑之下承担三重关键职责硬件适配层收敛屏蔽 STM32H743VI或等效主控 MCU与 Thetis 板载专用芯片如高精度 ADC/DAC、多通道模拟开关、精密基准源、隔离 CAN 收发器、高速 SPI Flash之间的寄存器操作差异功能原子化封装将“采集一路热电偶信号”、“输出 4–20 mA 电流环”、“执行一次双斜率积分 ADC 校准”等仪器级操作封装为无状态、可重入的函数单元资源协同调度基座内置轻量级资源仲裁机制确保模拟前端AFE、数字隔离通道、实时时钟RTC备份域寄存器等共享资源在多任务环境下的安全访问。该库采用 C99 标准编写零依赖第三方 RTOS兼容裸机与 FreeRTOS/ThreadX内存模型严格遵循静态分配原则——所有句柄handle、缓冲区buffer、校准参数均通过thetis_init()一次性初始化并驻留于.bss或.data段杜绝运行时malloc()调用满足 IEC 61508 SIL-2 级别确定性要求。2. 硬件平台映射与系统架构2.1 Thetis 板卡硬件拓扑解析Thetis 仪器仪表板采用分层硬件架构ThetisLib 的模块划分直接对应物理子系统子系统关键器件ThetisLib 模块名工程约束说明高精度模拟前端AD7173-824-bit Σ-Δ ADC、REF1022.5V 基准、ADG141416通道模拟开关thetis_afe采样率 ≤ 10 kSPS 时启用 Sinc5 滤波器通道切换需 ≥ 10 μs 建立时间基准电压温漂补偿系数固化于 OTP工业输出通道XTR1164–20 mA 变送器、DAC856316-bit 电压输出thetis_output电流环需支持 HART 协议频谱1.2 kHz / 2.2 kHz叠加DAC 更新速率 ≥ 100 kSPS 以抑制纹波隔离通信总线ISO1050CAN 隔离收发器、ADuM1201双通道数字隔离thetis_can/thetis_gpio_isoCAN 波特率支持 125 kbps / 250 kbps / 1 Mbps隔离 GPIO 驱动能力 ≥ 8 mA 3.3 V上升/下降时间 10 ns非易失配置存储W25Q80DV1 MB SPI Flash、STM32H743 内部备份寄存器BKPthetis_nvmFlash 扇区擦除寿命 ≥ 100k 次BKP 寄存器用于存储校准偏移量16-bit × 8 ch掉电保持时间 10 年注所有器件选型均通过 -40°C 至 85°C 工业级温度认证ThetisLib 中的时序参数如THETIS_AFE_SWITCH_SETTLE_US 12已通过示波器实测验证。2.2 ThetisLib 软件架构图--------------------------------------------------- | Application Layer | | (e.g., Modbus RTU server, HART command handler) | ------------------------------------------------- ↓ ------------------------------------------------- | ThetisLib Core API Layer | | • thetis_init() • thetis_deinit() | | • thetis_task_tick() → 1ms system tick handler | ------------------------------------------------- ↓ ↓ ↓ ---------------- ------------------ ------------------ | thetis_afe | | thetis_output | | thetis_can | | • adc_read() | | • current_set() | | • can_transmit() | | • calibrate() | | • voltage_set() | | • can_receive() | | • channel_sel()| | • hysteresis_en()| | • can_filter_cfg()| ---------------- ------------------ ------------------ ↓ ↓ ↓ ----------------------------------------------------------------- | Hardware Abstraction Layer (HAL) | | • HAL_SPI_TransmitReceive() • HAL_TIM_Base_Start_IT() | | • HAL_GPIO_WritePin() • HAL_RTCEx_BKUPWrite() | | • HAL_DAC_SetValue() • HAL_I2C_Mem_Read() [for REF] | -----------------------------------------------------------------关键设计决策说明thetis_task_tick()是唯一允许被SysTick_Handler直接调用的库函数内部实现毫秒级软定时器链表管理避免在中断中执行耗时操作所有模块初始化函数如thetis_afe_init()均返回THETIS_OK/THETIS_ERROR_INIT_FAILED错误码携带具体失败寄存器地址如0x40012000指向 ADC1_BASE便于产线快速定位硬件焊接问题thetis_nvm模块采用“影子扇区”机制写入新配置前先擦除备用扇区校验成功后再原子切换主/备扇区指针防止断电导致配置损坏。3. 核心 API 接口详解3.1 全局初始化与生命周期管理typedef enum { THETIS_OK 0, THETIS_ERROR_INIT_FAILED, THETIS_ERROR_CLOCK_CONFIG, THETIS_ERROR_PERIPH_CLK, THETIS_ERROR_GPIO_INIT, } thetis_status_t; thetis_status_t thetis_init(const thetis_config_t *config); void thetis_deinit(void); void thetis_task_tick(void);参数说明thetis_config_t结构体字段类型取值范围/说明工程意义sysclk_mhzuint32_t400 / 480 H743 最高主频触发时钟树校验若配置值与 RCC-CFGR 读出值偏差 ±5%返回THETIS_ERROR_CLOCK_CONFIGafe_spi_handleSPI_HandleTypeDef*指向已初始化的 SPI1 handle需工作在 10 MHz, 2-line master, MSB firstAFE 通信带宽瓶颈10 MHz 保障 16 通道全速扫描周期 ≤ 200 μscan_hcanCAN_HandleTypeDef*指向已初始化的 FDCAN1 handle波特率由can_baudrate_kbps决定自动配置 FDCAN_TTCR.TSS 1时间触发模式支持同步采样触发can_baudrate_kbpsuint16_t125 / 250 / 1000影响thetis_can_filter_cfg()中的验收码掩码位宽backup_reg_baseuint32_t0x40006000BKP 寄存器起始地址用于thetis_nvm模块读写备份域 RAM需在PWR-CR1.DBBE 1后访问典型初始化流程// 在 main() 中调用 thetis_config_t cfg { .sysclk_mhz 480, .afe_spi_handle hspi1, .can_hcan hfdcan1, .can_baudrate_kbps 250, .backup_reg_base 0x40006000, }; if (thetis_init(cfg) ! THETIS_OK) { // 硬件自检失败点亮 ERROR LED 并进入低功耗停机模式 HAL_GPIO_WritePin(LED_ERROR_GPIO_Port, LED_ERROR_Pin, GPIO_PIN_SET); HAL_PWR_EnterSTOPMode(PWR_LOWPOWERREGULATOR_ON, PWR_STOPENTRY_WFI); }3.2 模拟前端AFE模块 API// 通道选择支持单端/差分模式 thetis_status_t thetis_afe_channel_select(thetis_afe_ch_t ch, thetis_afe_mode_t mode); // 启动单次转换阻塞式超时 100 ms thetis_status_t thetis_afe_adc_read(int32_t *raw_data); // 执行工厂校准需外部短接 J1-J2 thetis_status_t thetis_afe_calibrate(thetis_afe_cal_type_t type); // 获取温度补偿后的工程值单位°C需先调用 thetis_afe_adc_read() float thetis_afe_get_temperature_celsius(void);关键参数表枚举类型可选值说明thetis_afe_ch_tTHETIS_AFE_CH_0~THETIS_AFE_CH_15对应 ADG1414 的 16 个模拟输入通道thetis_afe_mode_tTHETIS_AFE_MODE_SE/THETIS_AFE_MODE_DIFF单端模式下参考地为 AGND差分模式下自动配置 ADC 输入极性thetis_afe_cal_type_tTHETIS_AFE_CAL_OFFSET/THETIS_AFE_CAL_GAIN偏置校准需在 0 V 输入下执行增益校准需施加 2.5 V 精密基准电压由 REF102 提供底层实现逻辑thetis_afe_adc_read()内部执行以下原子序列通过 SPI 向 AD7173 发送0x08RDY 检查指令等待 BUSY 引脚拉低发送0x58单次转换指令启动 Sinc5 滤波器轮询DRDY引脚GPIO 输入超时则返回THETIS_ERROR_ADC_TIMEOUT读取 32-bit 数据帧含 24-bit 有效数据 8-bit 状态字状态字校验 CRC8应用温度补偿算法T_comp T_raw × (1 K_temp × (T_ambient - 25))其中K_temp 120 ppm/°C为 AD7173 温漂系数。3.3 输出通道模块 API// 设置 4–20 mA 输出值0x0000 4 mA, 0xFFFF 20 mA thetis_status_t thetis_output_current_set(uint16_t code); // 设置 DAC8563 电压输出0x0000 0 V, 0xFFFF 5 V thetis_status_t thetis_output_voltage_set(uint16_t code); // 启用/禁用电流环迟滞防抖动 thetis_status_t thetis_output_hysteresis_en(bool enable);硬件协同要点thetis_output_current_set()自动计算 XTR116 的 SET 引脚电压V_set 2.5 × (code / 65535)再通过HAL_DAC_SetValue()输出至 DAC8563迟滞功能通过比较器电路实现当设定值变化 0.1% FS即 16 LSB且持续 500 ms才更新实际输出避免传感器噪声引发误动作所有输出函数执行前检查XTR116_FAULT引脚GPIO 输入若检测到开路/短路故障立即返回THETIS_ERROR_OUTPUT_FAULT并锁存故障标志。3.4 隔离 CAN 模块 API// 配置 CAN 过滤器支持标准帧 ID 0x000–0x7FF thetis_status_t thetis_can_filter_cfg(uint32_t id, uint32_t mask); // 发送 CAN 报文非阻塞使用 FIFO 缓冲 thetis_status_t thetis_can_transmit(const uint8_t data[8], uint8_t len, uint32_t id); // 接收 CAN 报文阻塞式超时 10 ms thetis_status_t thetis_can_receive(uint8_t data[8], uint8_t *len, uint32_t *id);过滤器配置逻辑根据can_baudrate_kbps自适应设置FDCAN_SIDFC.LSS标准 ID 列表大小125 kbps →LSS 32支持 32 个独立 ID 过滤250 kbps →LSS 161000 kbps →LSS 4此设计确保在高速率下仍能维持 ≤ 5 μs 的报文处理延迟满足实时控制需求。4. 实际工程应用示例4.1 多通道热电偶温度巡检仪FreeRTOS 集成// 创建采集任务 void vAfeTask(void *pvParameters) { int32_t raw_data; float temp_c; // 初始化 AFE选择通道 0差分模式 thetis_afe_channel_select(THETIS_AFE_CH_0, THETIS_AFE_MODE_DIFF); for(;;) { // 每 500 ms 采集一次 if (thetis_afe_adc_read(raw_data) THETIS_OK) { temp_c thetis_afe_get_temperature_celsius(); // 发送至 CAN 总线ID0x101温度值左移 8 位存入 data[0:1] uint8_t can_data[8] {0}; can_data[0] (uint8_t)(temp_c * 100 8); // 高字节 can_data[1] (uint8_t)(temp_c * 100); // 低字节 thetis_can_transmit(can_data, 2, 0x101); } vTaskDelay(pdMS_TO_TICKS(500)); } } // 在 main() 中启动 xTaskCreate(vAfeTask, AFE, configMINIMAL_STACK_SIZE * 3, NULL, tskIDLE_PRIORITY 2, NULL);4.2 4–20 mA 回路校准工具裸机模式// 主循环中实现阶梯输出 uint16_t current_code 0x0000; // 4 mA while (1) { thetis_output_current_set(current_code); // 保持 2 秒后步进 HAL_Delay(2000); current_code 0x1000; // 步长 25% FS if (current_code 0xFFFF) { current_code 0x0000; } }5. 调试与诊断机制ThetisLib 内置三级诊断体系编译期诊断通过#error检查thetis_config_t字段合法性如can_baudrate_kbps非法值触发编译失败运行期自检thetis_init()执行thetis_afe_selftest()向 ADC 注入已知电压并比对读数误差 ±0.01% FS 则拒绝初始化在线监控提供thetis_get_diag_info()接口返回结构体包含typedef struct { uint32_t afe_errors; // ADC 超时/校验失败次数 uint32_t can_tx_drops; // FIFO 溢出丢弃报文数 uint32_t nvm_writes; // 非易失存储写入次数 uint8_t temp_sensor_c; // 板载温度传感器读数℃ } thetis_diag_t;该诊断数据可通过 SWOSerial Wire Output实时输出配合 Segger SystemView 可视化分析系统稳定性。6. 产线部署与固件升级支持ThetisLib 将固件升级能力下沉至库层thetis_nvm模块预留0x00000–0x0FFFF地址空间作为 Bootloader 跳转区提供thetis_nvm_firmware_update_start()函数执行以下操作擦除 Flash 用户区0x010000–0x07FFFF启用FLASH_OPTCR.BOR_LEV 0b11上电复位阈值 2.7 V防止升级中低压导致锁死返回THETIS_OK后应用层可安全调用memcpy()写入新固件升级完成后调用thetis_nvm_firmware_validate()校验用户区 CRC32 与首地址处存储的校验和是否一致不匹配则自动回滚至备份扇区。此机制已在某石油钻探传感器产线验证单台设备平均升级耗时 8.3 s失败率 0.002%无需专用编程器。7. 项目演进与维护边界ThetisLib 明确划定了能力边界✅持续维护ADC/DAC 精度补偿算法、CAN 协议栈鲁棒性增强、NVM wear-leveling 优化⚠️有限扩展新增传感器支持如接入 MAX31855 热电偶放大器需提供完整 datasheet 时序图❌明确排除GUI 渲染、TCP/IP 协议栈、机器学习推理——此类功能应通过标准接口如 UART/USB CDC与上位机协作实现。当前版本v2.3.1已通过 CNAS 认证实验室的 EMC 测试IEC 61000-4-2/4/5/6静电放电抗扰度达 ±8 kV接触放电完全满足工业现场部署要求。