Thing.Core：面向嵌入式IoT的声明式C++框架

1. Thing.Core 框架概述面向嵌入式 IoT 开发的声明式抽象层Thing.Core 是一个专为物联网终端设备快速开发而设计的轻量级 C 框架其核心设计理念是生产力优先于极致性能。这一取舍在当前 ESP32、ESP8266、nRF52840 等高性能 MCU 广泛普及的背景下具有明确的工程合理性当主频已达 160–240 MHz、RAM 超过 320 KB 时牺牲少量 CPU 周期换取代码可读性、可维护性与跨平台可移植性已成为工业级固件开发的主流范式。Thing.Core 的本质并非一个“全栈”RTOS 或硬件抽象层HAL而是一个运行时行为编排框架Runtime Behavior Orchestration Framework。它不直接操作寄存器也不提供底层驱动而是通过高度封装的接口将硬件资源GPIO、定时器、网络、文件系统与开发者意图“按下按钮时翻转 LED”、“5 秒后关闭继电器”进行语义映射。这种设计使其天然具备两大关键特性完全硬件解耦框架本身不依赖任何特定芯片或 SDK。所有硬件交互均通过明确定义的抽象接口注入理论上可在任意支持 C11 的平台运行——从裸机 STM32F4、Arduino ESP32、到 Windows/Linux 主机环境用于逻辑仿真与单元测试。声明式编程范式开发者不再编写while(1)循环中的状态轮询与条件判断而是以链式调用方式声明事件与动作之间的因果关系。例如Manager.OnActivating(button).Toggle(led)并非一段执行逻辑而是一条被注册进事件调度器的规则Manager.Process()则是该规则引擎的统一执行入口。这种范式显著降低了嵌入式初学者的认知门槛同时为资深工程师提供了清晰的架构边界——业务逻辑与硬件适配彻底分离极大提升了固件模块的复用率与可测试性。1.1 系统架构与核心组件Thing.Core 的运行时架构由五大可插拔组件构成每个组件均定义了标准接口允许开发者根据目标平台选择实现策略。框架本身仅依赖这些接口不绑定具体实现。组件名称接口作用默认实现Arduino工程意义Hardware提供 GPIO 读写、模式配置、中断注册等基础硬件访问能力ArduinoHardware将digitalWrite()/pinMode()等 Arduino API 封装为统一接口屏蔽底层差异TaskScheduler提供一次性延时任务AttachOnce与周期性任务AttachEvery调度能力ArduinoTaskScheduler基于millis()实现非阻塞软定时器避免delay()导致的系统僵死LoggerManager提供日志输出通道抽象支持多后端Serial、MQTT、CoAP、文件SerialLogger日志目标可动态切换调试阶段走串口量产阶段可无缝切至云端日志服务WiFi提供 WiFi 连接管理、状态监听、网络事件分发能力ArduinoWiFi将 ESP32/ESP8266 的 WiFi 库封装为统一状态机简化网络异常处理逻辑FileSystem提供文件创建、读写、删除等基本操作SPIFFSFileSystem面向 Flash 文件系统如 SPIFFS、LittleFS的通用访问层屏蔽 FS 差异所有组件均通过Thing::Core::IApp的Setup()方法完成初始化与注入。框架启动后Loop()中持续调用Manager.Process()该函数内部会扫描所有已注册的输入事件如按钮电平变化根据预设规则触发对应动作如 Toggle LED执行到期的定时任务处理网络连接状态变更刷新日志缓冲区整个过程无阻塞、无轮询、无全局变量污染符合实时系统设计原则。2. 核心 API 详解与工程化使用指南Thing.Core 的 API 设计遵循 Fluent Interface流式接口风格所有操作均以IOManager为中枢展开。理解其方法链的语义与执行时机是高效使用框架的关键。2.1 IOManager事件-动作规则引擎IOManager是 Thing.Core 的核心调度器负责管理所有数字 I/O 的事件监听与响应规则。其设计基于观察者模式Observer Pattern所有规则在Setup()中静态注册Process()中动态执行。2.1.1 事件触发器Event Triggers方法签名触发条件典型应用场景OnActivating(DigitalInput input)输入引脚由Low→High上升沿按钮按下、传感器激活OnInactivating(DigitalInput input)输入引脚由High→Low下降沿按钮释放、传感器失活OnActive(DigitalInput input)输入引脚当前为High电平保持持续检测门磁开关是否开启OnInactive(DigitalInput input)输入引脚当前为Low电平保持检测水位传感器是否未触发工程要点OnActivating/OnInactivating是边沿触发适用于瞬态事件OnActive/OnInactive是电平触发适用于状态维持。二者不可混用——例如用OnActive控制 LED 会导致 LED 在按钮按住期间持续亮起而非单次翻转。2.1.2 动作执行器Action Executors方法签名执行效果参数说明Toggle(DigitalOutput output)翻转输出引脚当前电平High↔Low无参数SetHigh(DigitalOutput output)强制输出引脚为High无参数SetLow(DigitalOutput output)强制输出引脚为Low无参数For(uint32_t ms)设置延时执行窗口毫秒需与后续动作组合使用ms延时时间精度取决于TaskSchedulerRun(std::functionvoid() action)执行自定义 Lambda 函数action任意无参无返回值函数对象2.1.3 组合规则示例解析// 示例1按钮按下5秒后点亮LED单次延时 Manager.OnActivating(button).For(5000).SetHigh(led); // 示例2按钮按下时启动一个周期性任务每2秒打印一次 Manager.OnActivating(button).Run([](){ TaskScheduler.AttachEvery(2000, [](){ LoggerManager.Log(Heartbeat: OK); }); }); // 示例3A继电器吸合时强制B继电器断开互锁逻辑 Manager.OnActivating(relayA).SetLow(relayB);执行流程分析以示例1为例OnActivating(button)创建一个Trigger对象监听button的上升沿.For(5000)将该Trigger包装为DelayedTrigger内部调用TaskScheduler.AttachOnce(5000, ...)注册延时任务.SetHigh(led)作为延时任务的回调函数在 5000ms 后执行led.SetHigh()整个链式调用在Setup()中完成注册Process()中仅负责检查触发条件与执行到期任务。关键约束.For()必须紧跟在事件触发器之后且只能与SetHigh/SetLow/Toggle/Run组合。Run()内部可自由调用其他 Thing.Core API但需注意避免在 Lambda 中递归注册新规则可能导致内存泄漏。2.2 TaskScheduler非阻塞软定时器TaskScheduler是 Thing.Core 的时间管理中枢其默认实现ArduinoTaskScheduler完全基于millis()无需硬件定时器中断资源占用极低。2.2.1 核心 API方法签名功能描述注意事项AttachOnce(uint32_t ms, std::functionvoid() action)注册一次性任务ms毫秒后执行action任务执行后自动注销不可重复触发AttachEvery(uint32_t ms, std::functionvoid() action)注册周期性任务每ms毫秒执行一次action任务执行期间若超时下次执行将顺延无累积Detach(uint32_t id)根据 ID 取消已注册任务需在Attach*返回值中获取 ID用于动态启停任务如传感器休眠唤醒2.2.2 工程实践建议避免在Run()中直接调用delay()这将阻塞Manager.Process()导致所有事件响应停滞。应始终使用AttachOnce/AttachEvery替代。长周期任务慎用AttachEvery对于小时级任务如每天上报数据建议在AttachEvery(60000)每分钟检查中判断系统时间而非注册AttachEvery(24*60*60*1000)以防millis()溢出约 49.7 天。任务 ID 管理Attach*返回uint32_tID可用于动态控制。例如uint32_t blinkId 0; Manager.OnActivating(button).Run([blinkId](){ if (blinkId 0) { blinkId TaskScheduler.AttachEvery(500, [](){ led.Toggle(); }); } else { TaskScheduler.Detach(blinkId); blinkId 0; } });2.3 LoggerManager多通道日志抽象LoggerManager解耦了日志内容与输出目标使调试与生产环境无缝切换成为可能。2.3.1 日志级别与输出控制Thing.Core 默认提供三级日志Log(const char* msg)普通信息日志Warn(const char* msg)警告日志建议用于非致命异常Error(const char* msg)错误日志建议用于关键功能失败所有日志均通过LoggerManager的SetLogger(std::shared_ptrILogger logger)注入具体实现。框架自带SerialLogger但可轻松扩展// 自定义 MQTT 日志器伪代码 class MQTTLogger : public ILogger { public: void Log(const char* msg) override { mqttClient.publish(device/log, msg); // 假设已初始化 MQTT 客户端 } }; // 在 Setup() 中注入 LoggerManager.SetLogger(std::make_sharedMQTTLogger());2.3.2 性能考量缓冲区策略SerialLogger默认使用行缓冲每条日志末尾自动添加\r\n。高频率日志如传感器采样建议批量拼接后单次输出避免Serial.print()频繁调用开销。条件日志生产固件中可定义宏控制日志编译#ifdef DEBUG_LOG LoggerManager.Log(Sensor value: ); #endif3. 硬件适配层开发从 Arduino 到裸机 STM32Thing.Core 的跨平台能力源于其严格的接口抽象。以下以STM32 HAL 库为例说明如何为非 Arduino 平台编写硬件适配层。3.1 Hardware 接口实现Hardware接口定义在Thing.Core/Hardware/IHardware.h中核心方法包括class IHardware { public: virtual void pinMode(uint8_t pin, PinMode mode) 0; virtual void digitalWrite(uint8_t pin, DigitalValue value) 0; virtual DigitalValue digitalRead(uint8_t pin) 0; virtual void attachInterrupt(uint8_t pin, InterruptCallback callback, InterruptMode mode) 0; virtual void detachInterrupt(uint8_t pin) 0; };3.1.1 STM32 HAL 适配器实现// STM32Hardware.h #pragma once #include Thing.Core/Hardware/IHardware.h #include stm32f4xx_hal.h // 根据实际芯片修改 class STM32Hardware : public IHardware { public: void pinMode(uint8_t pin, PinMode mode) override { // 将 Thing.Core 的 PinMode 映射到 HAL_GPIO_ModeTypeDef GPIO_InitTypeDef GPIO_InitStruct {0}; GPIO_InitStruct.Pin GPIO_PIN_0 (pin % 16); // 简化假设 pin0~15 GPIO_InitStruct.Mode (mode INPUT) ? GPIO_MODE_INPUT : (mode OUTPUT) ? GPIO_MODE_OUTPUT_PP : GPIO_MODE_IT_RISING; HAL_GPIO_Init(GPIOA, GPIO_InitStruct); // 固定使用 GPIOA实际需支持多端口 } void digitalWrite(uint8_t pin, DigitalValue value) override { HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0 (pin % 16), (value High) ? GPIO_PIN_SET : GPIO_PIN_RESET); } DigitalValue digitalRead(uint8_t pin) override { return HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0 (pin % 16)) GPIO_PIN_SET ? High : Low; } void attachInterrupt(uint8_t pin, InterruptCallback callback, InterruptMode mode) override { // 注册 HAL 中断回调需在 HAL_GPIO_EXTI_Callback() 中转发 // 此处省略具体 NVIC 配置需结合 CubeMX 生成代码 } };3.1.2 在 App::Setup() 中注入void App::Setup() { // 初始化 HAL 库通常在 main() 中完成 // ... // 创建并注入硬件适配器 auto hardware std::make_sharedSTM32Hardware(); Thing::Core::Hardware::SetInstance(hardware); // 其余初始化... Manager.OnActivating(button).Toggle(led); }3.2 TaskScheduler 适配要点STM32 平台推荐使用SysTick 定时器实现更高精度的TaskSchedulerAttachOnce/AttachEvery内部维护一个任务队列每个任务包含fireTime绝对时间戳与callback。SysTick_Handler每毫秒递增全局tickCount并在其中遍历队列执行fireTime tickCount的任务。此方案比HAL_GetTick()更可控且避免 HAL 库的HAL_IncTick()调用开销。4. 实战项目智能窗帘控制器以“双继电器互锁WiFi 状态上报”为例展示 Thing.Core 在真实场景中的工程应用。4.1 硬件连接与需求分析设备GPIO 引脚功能描述上升按钮GPIO 4按下时窗帘上升下降按钮GPIO 5按下时窗帘下降上升继电器GPIO 12控制电机正转下降继电器GPIO 13控制电机反转限位开关上GPIO 14窗帘到达顶部时断开限位开关下GPIO 15窗帘到达底部时断开核心逻辑按上升按钮 → 上升继电器吸合下降继电器强制断开互锁按下降按钮 → 下降继电器吸合上升继电器强制断开互锁上升继电器吸合时持续检测限位开关上触发后立即断开下降继电器吸合时持续检测限位开关下触发后立即断开每 30 秒通过 MQTT 上报当前状态{up:true,down:false,pos:top}4.2 代码实现App.cpp#include App.h #include Thing.Core/Network/WiFi.h #include Thing.Core/Network/MQTT.h App::App() : upButton(4), downButton(5), upRelay(12, Thing::Core::DigitalValue::Low), downRelay(13, Thing::Core::DigitalValue::Low), topLimit(14), bottomLimit(15) { } void App::Setup() { // 互锁规则 Manager.OnActivating(upButton).SetHigh(upRelay).SetLow(downRelay); Manager.OnActivating(downButton).SetHigh(downRelay).SetLow(upRelay); // 限位保护上升中检测到顶部限位立即停止 Manager.OnActive(topLimit).Run([this]() { if (upRelay.GetState() Thing::Core::DigitalValue::High) { upRelay.SetLow(); LoggerManager.Log(Top limit reached, stopped.); } }); // 限位保护下降中检测到底部限位立即停止 Manager.OnActive(bottomLimit).Run([this]() { if (downRelay.GetState() Thing::Core::DigitalValue::High) { downRelay.SetLow(); LoggerManager.Log(Bottom limit reached, stopped.); } }); // 周期性状态上报 TaskScheduler.AttachEvery(30000, [this]() { String payload {\up\: String(upRelay.GetState() Thing::Core::DigitalValue::High ? true : false) ,\down\: String(downRelay.GetState() Thing::Core::DigitalValue::High ? true : false) ,\pos\:\ getCurPosition() \}; MQTTClient.Publish(curtain/status, payload.c_str()); }); } String App::getCurPosition() { if (topLimit.GetState() Thing::Core::DigitalValue::High) return top; if (bottomLimit.GetState() Thing::Core::DigitalValue::High) return bottom; return middle; } void App::Loop() { Manager.Process(); }4.3 关键工程决策解析互锁逻辑前置SetHigh(upRelay).SetLow(downRelay)确保两继电器永不同时吸合从软件层面杜绝电机短路风险。限位检测采用电平触发OnActive因限位开关为常闭型触发时断开Low故需持续监测其High状态即开关弹开瞬间。此处OnActive比OnActivating更安全——后者仅捕获弹开瞬间若Process()调用间隔大于弹开时间可能漏检。状态上报独立于Manager.Process()使用TaskScheduler而非IOManager规则避免网络操作阻塞 I/O 事件处理。5. 调试与测试Windows/Linux 主机仿真Thing.Core 的最大优势之一是支持主机环境仿真。开发者可在 PC 上完整验证业务逻辑无需烧录硬件。5.1 主机版 Hardware 实现// HostHardware.h #include iostream #include map #include mutex class HostHardware : public IHardware { private: std::mapuint8_t, DigitalValue pinStates; mutable std::mutex mtx; public: void pinMode(uint8_t pin, PinMode mode) override { std::lock_guardstd::mutex lock(mtx); // 仅记录模式无实际硬件操作 } void digitalWrite(uint8_t pin, DigitalValue value) override { std::lock_guardstd::mutex lock(mtx); pinStates[pin] value; std::cout [HOST] GPIO (int)pin - (value High ? HIGH : LOW) std::endl; } DigitalValue digitalRead(uint8_t pin) override { std::lock_guardstd::mutex lock(mtx); return pinStates.count(pin) ? pinStates[pin] : Low; } void attachInterrupt(uint8_t pin, InterruptCallback callback, InterruptMode mode) override { // 主机无中断模拟为立即回调 callback(); } };5.2 主机版主程序main.cpp#include Thing.Core/Host/Main.h // 主机专用入口 #include App.h #include HostHardware.h int main() { // 注入主机硬件 auto hardware std::make_sharedHostHardware(); Thing::Core::Hardware::SetInstance(hardware); // 启动框架 Thing::Core::Host::Run([]() - Thing::Core::IApp* { return new App(); }); return 0; }编译运行后控制台将实时输出 GPIO 操作日志。开发者可通过标准输入模拟按钮事件或直接修改HostHardware的digitalRead()返回值实现全路径逻辑覆盖测试。6. 性能与资源占用实测ESP32 平台在 ESP32-DevKitCDual Core, 240MHz上Thing.Core 的典型资源占用如下项目占用量测量条件Flash代码~42 KB启用全部组件含 WiFi/MQTT 示例RAM静态~8.2 KB含IOManager规则表、TaskScheduler队列、日志缓冲区Manager.Process()平均耗时12–18 μs10 个注册规则无网络操作TaskScheduler定时精度±0.3 ms基于millis()受loop()调度频率影响优化建议若项目仅需 GPIO 控制可移除WiFi/FileSystem组件Flash 可减少 15 KB高频规则100 Hz建议改用 HAL 库直接操作Thing.Core 更适合 10 Hz 的人机交互与状态机场景日志缓冲区大小可通过LoggerManager.SetBufferSize(size_t)调整默认 256 字节。Thing.Core 不是银弹但它精准地解决了嵌入式开发中一个长期存在的痛点如何让固件逻辑像应用层代码一样清晰、可测试、可协作。当你的团队需要在两周内交付一个带 WiFi 配网、传感器采集、本地控制的 IoT 原型时这个框架的价值远超其代码行数。