1. MycilaHADiscovery 库概述MycilaHADiscovery 是一个专为 Arduino 和 ESP32 平台设计的轻量级 Home AssistantHA自动发现协议实现库。其核心目标并非提供完整的 MQTT 客户端或网络栈而是聚焦于生成符合 Home Assistant MQTT Discovery 规范的 JSON 配置消息并交由用户已有的 MQTT 客户端如 PubSubClient、AsyncMqttClient完成实际发布。该库的设计哲学是“简单而高效”——它不引入额外的线程、定时器或内存池所有操作均为同步、无状态的纯函数式调用避免了在资源受限的微控制器上产生不可预测的内存碎片或阻塞风险。与 Home Assistant 官方推荐的homeassistant-mqtt或更重型的框架如 ESPHome不同MycilaHADiscovery 将控制权完全交还给开发者。它不管理设备连接状态、不重试失败的发布、不解析传入的 MQTT 消息仅承担“配置描述生成器”这一单一职责。这种极简主义设计使其具备极高的可移植性只要目标平台能运行 C11 编译器并支持标准字符串操作std::string或String即可无缝集成。在 STM32 HAL FreeRTOS 环境中只需将String替换为std::string并链接 C 标准库即可复用全部逻辑。该库的核心价值在于工程确定性。在工业嵌入式项目中开发者往往需要精确控制每一个字节的网络负载、每一个毫秒的 CPU 占用以及每一个堆分配的生命周期。MycilaHADiscovery 的零动态内存分配所有 JSON 构建均在栈上完成、无回调注册机制、无全局单例状态使其成为对实时性与可靠性要求严苛场景下的理想选择。例如在光伏逆变器监控节点中主控需在 10ms 内完成传感器采样、PID 计算与 CAN 总线通信此时一个会隐式触发堆分配或阻塞主线程的 HA 发现库将直接导致系统时序失控。而 MycilaHADiscovery 的publish()调用仅执行字符串拼接与格式化其执行时间可被精确测量与预算。2. Home Assistant Discovery 协议原理与库映射Home Assistant 的 MQTT Discovery 机制依赖于一套严格的主题Topic命名约定与 JSON 负载结构。当设备向特定主题发布包含设备元数据、功能定义及状态映射的 JSON 消息后HA 会自动将其注册为可管理实体并建立双向通信通道。MycilaHADiscovery 的全部 API 均是对该协议的 C 封装其设计严格遵循 HA 官方文档 中定义的语义。2.1 协议核心要素解析Discovery 协议的基石是三个关键概念Device设备、Component组件和Availability可用性。Device代表物理硬件单元由唯一identifiers字段标识。MycilaHADiscovery 要求在begin()时传入Device结构体其中id字段如my-app-1234将作为设备全局唯一 ID用于生成所有子组件的主题前缀。HA 通过identifiers关联同一设备下的所有传感器、开关等组件确保它们在 UI 中聚合显示。Component指代设备提供的具体功能单元如一个温度传感器、一个继电器开关或一个配置参数滑块。每种 Component 对应一个独立的 MQTT 主题格式为discovery_prefix/component_type/device_id/object_id/config。例如homeassistant/switch/my-app-1234/rel_commute/config。MycilaHADiscovery 将此映射为Switch、Button、Number等类每个类实例化时即固化其object_id如rel_commute与component_type如switch。Availability解决设备离线时 HA 状态陈旧的问题。协议要求设备定期发布online/offline状态到base_topic/status主题即setWillTopic()所设主题并为每个组件指定availability_topic与payload_available/payload_not_available。MycilaHADiscovery 提供两级可用性控制全局haDiscovery.setWillTopic()设置设备级心跳主题而各组件如Outlet可覆写availabilityTopic字段实现细粒度控制如仅当继电器驱动电路供电正常时才报告available。2.2 JSON 负载生成逻辑库内部不使用第三方 JSON 库如 ArduinoJson而是采用手工字符串拼接。以State组件为例其publish()调用最终生成的 JSON 如下{ name: Grid Electricity, state_topic: ~/grid/online, payload_on: true, payload_off: false, device_class: connectivity, unique_id: my-app-1234-grid, device: { identifiers: [my-app-1234], name: My Application Name, model: OSS, manufacturer: Mathieu Carbou, sw_version: 1.0.1 } }关键点在于state_topic中的~符号是 HA 协议定义的占位符begin()时传入的base topic如/my-app将自动替换所有~生成绝对路径/my-app/grid/online。unique_id由device.id与object_id拼接而成确保 HA 中实体 ID 全局唯一避免多设备同名冲突。device对象内容完全来自begin()传入的Device结构体实现设备元数据的一致性分发。3. 核心 API 详解与工程化用法MycilaHADiscovery 的 API 设计遵循“声明式配置”原则所有组件均以值语义value semantics构造通过publish()注册后即完成配置。以下按功能类别梳理核心 API并结合嵌入式工程实践给出深度解析。3.1 初始化与生命周期管理// 设置设备级“遗嘱”主题用于报告设备在线状态 void setWillTopic(const char* topic); // 启动发现服务注册设备元数据绑定发布回调 bool begin(const Device device, const char* baseTopic, std::functionvoid(const char*, const char*) publishCallback);setWillTopic()必须在begin()之前调用。其参数topic如~/status将被baseTopic替换为/my-app/status。此主题需由用户 MQTT 客户端设置为 LWTLast Will and Testament主题当设备异常断连时MQTT Broker 自动发布offline消息HA 由此判定设备离线。begin()的publishCallback是库与用户代码的唯一耦合点。其签名void(const char*, const char*)强制要求用户在此回调内调用mqttClient.publish(topic, payload)。这种设计解耦了网络层使库可适配任意 MQTT 客户端。在 FreeRTOS 环境中此回调可安全地放入任务队列避免在中断上下文调用耗时的网络 API。3.2 组件类族与参数语义所有组件均继承自抽象基类Component但用户直接使用具体子类。各子类构造函数参数严格对应 HA Discovery JSON 字段其命名与顺序均经过工程验证。组件类典型用途关键构造参数按声明顺序工程要点Button触发瞬时动作重启、校准id,name,command_topic,payload,icon,categorycommand_topic是 HA 向设备发送指令的主题如~/system/restartpayload是 HA 发送的触发值如restart。设备需监听此主题并执行相应动作。Counter累加型数值启动次数、错误计数id,name,state_topic,state_class,unit_of_measurement,categorystate_class: total_increasing告知 HA 此值只增不减HA 可自动计算增量。unit_of_measurement如times影响 UI 显示格式。Gauge实时测量值内存占用、电压id,name,state_topic,device_class,icon,unit_of_measurement,categorydevice_class: data_size启用 HA 的内存单位自动转换B/KB/MB。icon: mdi:memory使用 Material Design Icons需在 HA 前端启用 mdi 支持。State二值状态在线/离线、开/关id,name,state_topic,payload_on,payload_off,device_class,icon,categorydevice_class: connectivity启用 HA 的连接状态专用图标与颜色。payload_on/off必须与设备实际发布的字符串严格匹配区分大小写。Text可编辑文本配置项id,name,command_topic,state_topic,pattern,icon,categorypattern是正则表达式如^[0-9]$HA 前端将据此验证用户输入。设备需监听command_topic并更新配置再向state_topic发布新值以同步 UI。Number数值型配置阈值、延时id,name,command_topic,state_topic,mode,min,max,step,icon,categorymode: NumberMode::SLIDER强制 HA 前端显示滑块而非数字输入框。min/max/step直接约束 UI 操作范围避免无效值。Switch双态控制输出继电器、LEDid,name,command_topic,state_topic,payload_on,payload_off,icon,categorycommand_topic接收 HA 指令ON/OFFstate_topic发布设备当前状态。二者主题可不同实现命令与状态分离。Select下拉选项配置模式选择id,name,command_topic,state_topic,icon,category,optionsoptions是std::vectorconst char*如{mon,tue,...}。HA 前端生成下拉菜单设备需处理command_topic的选项字符串并更新state_topic。Outlet带可用性检测的开关扩展Switchid,name,command_topic,state_topic,payload_on,payload_off继承Switch但额外暴露availabilityTopic,payloadAvailable,payloadNotAvailable成员变量用于细粒度控制组件可用性。3.3 高级特性可用性与验证全局可用性Global Availability通过setWillTopic()设置设备级心跳主题后所有组件默认继承此可用性。设备需在主循环中定期发布// 在主循环中每30秒发布一次 if (millis() - lastHeartbeat 30000) { mqttClient.publish(/my-app/status, online); // 注意此处为绝对路径 lastHeartbeat millis(); }HA 收到online后将设备下所有组件标记为available若超时未收到则标记为unavailable。组件级可用性Per-Component Availability对于关键外设如继电器需独立监控其供电或通信状态。Outlet类提供了直接访问Outlet relay1Commute(rel_commute, Relay 1, /my-app/relays/rel1/state/set, /my-app/relays/rel1/state, on, off); // 覆写可用性主题监控继电器驱动芯片的使能引脚状态 relay1Commute.availabilityTopic /my-app/relays/rel1/enabled; relay1Commute.payloadAvailable true; relay1Commute.payloadNotAvailable false; haDiscovery.publish(relay1Commute);此时即使设备整体在线/my-app/status为online若/my-app/relays/rel1/enabled发布falseHA 仍会将rel_commute开关置灰并显示unavailable防止误操作。输入验证Regex ValidationText和Number组件支持前端验证减少无效指令。Text的pattern参数需为 POSIX ERE 格式// 仅允许输入 1-5 位数字 Text mqttInterval(mqtt_publish_interval, MQTT Publish Interval, /my-app/config/mqtt_interval/set, /my-app/config/mqtt_interval, ^[1-9][0-9]{0,4}$, // 匹配 1-99999 mdi:timer-sand, Category::CONFIG);HA 前端将此正则应用于输入框onchange事件阻止非法字符输入。设备端仍需在command_topic回调中二次校验形成纵深防御。4. 在 STM32 HAL FreeRTOS 环境中的集成实践将 MycilaHADiscovery 移植到 STM32 平台需解决三个关键问题字符串类型兼容、内存管理策略、以及与 FreeRTOS 任务的协同。以下为经过量产验证的工程方案。4.1 字符串类型适配Arduino 的String类在 STM32 HAL 中不可用需替换为std::string。修改库头文件MycilaHADiscovery.h// 替换所有 String - std::string #include string using String std::string; // 保持 API 兼容性链接时需确保编译器启用 C11 标准-stdgnu11并链接libstdc。为避免std::string的堆分配开销可在FreeRTOSConfig.h中增大configTOTAL_HEAP_SIZE或使用std::string_viewC17替代但需评估编译器支持。4.2 FreeRTOS 任务安全发布publishCallback回调必须是线程安全的。推荐方案创建专用 MQTT 发布任务所有publish()调用均通过队列投递消息// 定义消息结构 struct MqttMsg { char topic[128]; char payload[512]; }; // 创建队列 QueueHandle_t xMqttQueue; // MQTT 发布任务 void vMqttPublishTask(void *pvParameters) { MqttMsg msg; for(;;) { if (xQueueReceive(xMqttQueue, msg, portMAX_DELAY) pdPASS) { // 调用 HAL 库发布示例使用 STM32CubeMX 生成的 MQTT 客户端 HAL_MQTT_Publish(hmqqt, msg.topic, (uint8_t*)msg.payload, strlen(msg.payload), MQTT_QOS_1, 0); } } } // 修改 publishCallback 为队列投递 auto publishCallback [](const char* topic, const char* payload) { MqttMsg msg; strncpy(msg.topic, topic, sizeof(msg.topic)-1); strncpy(msg.payload, payload, sizeof(msg.payload)-1); xQueueSend(xMqttQueue, msg, 0); // 非阻塞投递 };此设计将 JSON 生成CPU 密集与网络 I/O可能阻塞分离符合 FreeRTOS 最佳实践。4.3 诊断传感器实战内存与 NTP 状态以Gauge和State组件为例展示如何在 STM32 上采集真实硬件数据// 获取 Heap 内存使用量CMSIS-RTOS API uint32_t getHeapUsed() { osMemoryPoolAttr_t attr; osMemoryPoolId_t pool osMemoryPoolNew(1024, 4, attr); // 示例池 uint32_t used osMemoryPoolGetSpace(pool); osMemoryPoolDelete(pool); return 1024 - used; // 简化计算实际需用 HAL_GetTick() 等 } // NTP 同步状态基于 SNTP 客户端 bool isNtpSynced() { return (sntp_get_sync_status() SNTP_SYNC_STATUS_COMPLETED); } // 在主循环中定期发布 void loop() { static uint32_t lastPublish 0; if (HAL_GetTick() - lastPublish 5000) { // 每5秒 // 发布内存用量 haDiscovery.publish(Gauge(memory_used, Memory Used, /my-app/system/heap_used, data_size, mdi:memory, B)); // 发布 NTP 状态 haDiscovery.publish(State(ntp, NTP, /my-app/ntp/synced, isNtpSynced() ? true : false, false, connectivity)); lastPublish HAL_GetTick(); } }注意Gauge构造时不传入具体数值publish()仅生成配置实际数值需由设备主动向state_topic发布。因此上述代码需补充// 在 publish() 后立即发布当前值 mqttClient.publish(/my-app/system/heap_used, String(getHeapUsed()).c_str()); mqttClient.publish(/my-app/ntp/synced, isNtpSynced() ? true : false);5. 配置项管理从 UI 到固件的闭环Home Assistant Discovery 的精髓在于实现“配置即服务”。Text、Number、Select等组件将 HA 前端变为设备的远程配置终端。工程实现需构建完整的读-写-持久化闭环。5.1 配置存储架构在 STM32 上推荐使用 Flash 模拟 EEPROM如 STM32CubeMX 的FLASH_EEPROMmiddleware存储配置。定义配置结构体typedef struct { uint16_t mqttPublishInterval; // 单位秒 uint16_t relay1PowerThreshold; // 单位瓦 bool output1AutoBypassEnable; uint8_t dayOfWeek; // 0mon, 1tue, ... } Config_t; Config_t g_config {30, 1500, true, 0}; // 默认值5.2 配置更新处理流程监听command_topic在 MQTT 连接回调中订阅所有配置主题。解析与校验收到消息后根据主题后缀识别配置项用sscanf()或strtol()解析数值并用Text的pattern规则二次校验。写入 Flash调用HAL_FLASHEx_DATAEEPROM_Unlock()等 API 将新值写入指定地址。同步state_topic向对应state_topic发布新值使 HA UI 实时刷新。// MQTT 消息到达回调 void mqtt_callback(char* topic, byte* payload, unsigned int length) { payload[length] \0; // 确保 null-terminated String topicStr String(topic); if (topicStr.endsWith(/config/mqtt_interval/set)) { long val strtol((char*)payload, nullptr, 10); if (val 1 val 3600) { // 二次校验 g_config.mqttPublishInterval (uint16_t)val; writeConfigToFlash(); // 实现此函数 mqttClient.publish(/my-app/config/mqtt_interval, String(val).c_str()); } } // ... 其他配置项处理 }5.3 启动时配置加载设备上电后需从 Flash 加载配置并初始化 HA 组件void setup() { readConfigFromFlash(); // 从 Flash 加载 g_config // 重新发布所有配置组件确保 HA 状态同步 haDiscovery.publish(Text(mqtt_publish_interval, MQTT Publish Interval, /my-app/config/mqtt_interval/set, /my-app/config/mqtt_interval, ^[1-9][0-9]{0,3}$, mdi:timer-sand, Category::CONFIG)); haDiscovery.publish(Number(relay1_power_threshold, Relay 1 Power Threshold, /my-app/config/rel1_power/set, /my-app/config/rel1_power, NumberMode::SLIDER, 0, 3000, 50, mdi:flash, Category::CONFIG)); // 发布当前值使 UI 显示正确初始状态 mqttClient.publish(/my-app/config/mqtt_interval, String(g_config.mqttPublishInterval).c_str()); mqttClient.publish(/my-app/config/rel1_power, String(g_config.relay1PowerThreshold).c_str()); }此流程确保设备重启后HA UI 与固件配置始终保持一致消除“配置漂移”风险。6. 故障排查与性能优化指南在实际部署中常见问题多源于协议细节疏忽或资源约束。以下是基于现场调试经验的 checklist。6.1 常见故障根因分析现象可能原因排查方法HA 中不显示任何实体begin()未调用publishCallback未正确绑定 MQTT 发布baseTopic包含非法字符空格、中文用mosquitto_sub -t homeassistant/# -v抓包确认是否收到config消息组件显示unavailablesetWillTopic()未设置设备未向status主题发布online组件availabilityTopic主题无订阅者检查status主题消息内容与频率用mosquitto_sub -t /my-app/relays/rel1/enabled验证可用性主题配置项修改后不生效command_topic未被设备监听state_topic未在修改后发布新值pattern正则语法错误如忘记转义在mqtt_callback中添加日志确认消息是否到达检查 HA 日志中是否有Invalid pattern错误设备频繁断连后 HA 状态混乱MQTT 客户端未正确设置 LWTwillTopic与setWillTopic()不一致网络超时参数过短检查MQTTClient.connect()的willTopic参数增大keepAlive时间至 120 秒6.2 内存与性能优化JSON 生成内存publish()期间最大栈消耗约 1KB取决于组件字段数。若遇栈溢出可增大configMINIMAL_STACK_SIZE或将publish()拆分为多个小组件分批发布。Flash 写入寿命配置项频繁更新会加速 Flash 擦写。建议对mqttPublishInterval等非关键配置增加软件滤波如仅当变化 10% 时才写入 Flash。MQTT QoS 选择Discovery 消息推荐QoS 0最多一次因其为静态配置丢失后可通过haDiscovery.begin()重发而状态消息state_topic应使用QoS 1至少一次确保 HA 状态准确。6.3 生产环境加固建议固件版本绑定Device.version字段应与git describe --tags输出一致如v2.1.0-5-gabc123便于在 HA 中按版本筛选设备。安全主题前缀生产环境禁用~/占位符改用绝对路径如/devices/my-app-1234避免主题解析歧义。配置变更审计在mqtt_callback中记录所有配置修改到 UART 或 SD 卡满足工业系统审计要求。MycilaHADiscovery 的价值正在于它迫使工程师直面协议本质——每一行代码都对应一个明确的 MQTT 主题与 JSON 字段。当我们在Outlet对象中显式设置availabilityTopic我们不是在调用一个黑盒 API而是在亲手编织设备与 HA 之间的信任链路。这种对底层细节的掌控力正是嵌入式系统可靠性的终极来源。
MycilaHADiscovery：轻量级Home Assistant MQTT自动发现C++库
发布时间：2026/5/19 16:01:34
1. MycilaHADiscovery 库概述MycilaHADiscovery 是一个专为 Arduino 和 ESP32 平台设计的轻量级 Home AssistantHA自动发现协议实现库。其核心目标并非提供完整的 MQTT 客户端或网络栈而是聚焦于生成符合 Home Assistant MQTT Discovery 规范的 JSON 配置消息并交由用户已有的 MQTT 客户端如 PubSubClient、AsyncMqttClient完成实际发布。该库的设计哲学是“简单而高效”——它不引入额外的线程、定时器或内存池所有操作均为同步、无状态的纯函数式调用避免了在资源受限的微控制器上产生不可预测的内存碎片或阻塞风险。与 Home Assistant 官方推荐的homeassistant-mqtt或更重型的框架如 ESPHome不同MycilaHADiscovery 将控制权完全交还给开发者。它不管理设备连接状态、不重试失败的发布、不解析传入的 MQTT 消息仅承担“配置描述生成器”这一单一职责。这种极简主义设计使其具备极高的可移植性只要目标平台能运行 C11 编译器并支持标准字符串操作std::string或String即可无缝集成。在 STM32 HAL FreeRTOS 环境中只需将String替换为std::string并链接 C 标准库即可复用全部逻辑。该库的核心价值在于工程确定性。在工业嵌入式项目中开发者往往需要精确控制每一个字节的网络负载、每一个毫秒的 CPU 占用以及每一个堆分配的生命周期。MycilaHADiscovery 的零动态内存分配所有 JSON 构建均在栈上完成、无回调注册机制、无全局单例状态使其成为对实时性与可靠性要求严苛场景下的理想选择。例如在光伏逆变器监控节点中主控需在 10ms 内完成传感器采样、PID 计算与 CAN 总线通信此时一个会隐式触发堆分配或阻塞主线程的 HA 发现库将直接导致系统时序失控。而 MycilaHADiscovery 的publish()调用仅执行字符串拼接与格式化其执行时间可被精确测量与预算。2. Home Assistant Discovery 协议原理与库映射Home Assistant 的 MQTT Discovery 机制依赖于一套严格的主题Topic命名约定与 JSON 负载结构。当设备向特定主题发布包含设备元数据、功能定义及状态映射的 JSON 消息后HA 会自动将其注册为可管理实体并建立双向通信通道。MycilaHADiscovery 的全部 API 均是对该协议的 C 封装其设计严格遵循 HA 官方文档 中定义的语义。2.1 协议核心要素解析Discovery 协议的基石是三个关键概念Device设备、Component组件和Availability可用性。Device代表物理硬件单元由唯一identifiers字段标识。MycilaHADiscovery 要求在begin()时传入Device结构体其中id字段如my-app-1234将作为设备全局唯一 ID用于生成所有子组件的主题前缀。HA 通过identifiers关联同一设备下的所有传感器、开关等组件确保它们在 UI 中聚合显示。Component指代设备提供的具体功能单元如一个温度传感器、一个继电器开关或一个配置参数滑块。每种 Component 对应一个独立的 MQTT 主题格式为discovery_prefix/component_type/device_id/object_id/config。例如homeassistant/switch/my-app-1234/rel_commute/config。MycilaHADiscovery 将此映射为Switch、Button、Number等类每个类实例化时即固化其object_id如rel_commute与component_type如switch。Availability解决设备离线时 HA 状态陈旧的问题。协议要求设备定期发布online/offline状态到base_topic/status主题即setWillTopic()所设主题并为每个组件指定availability_topic与payload_available/payload_not_available。MycilaHADiscovery 提供两级可用性控制全局haDiscovery.setWillTopic()设置设备级心跳主题而各组件如Outlet可覆写availabilityTopic字段实现细粒度控制如仅当继电器驱动电路供电正常时才报告available。2.2 JSON 负载生成逻辑库内部不使用第三方 JSON 库如 ArduinoJson而是采用手工字符串拼接。以State组件为例其publish()调用最终生成的 JSON 如下{ name: Grid Electricity, state_topic: ~/grid/online, payload_on: true, payload_off: false, device_class: connectivity, unique_id: my-app-1234-grid, device: { identifiers: [my-app-1234], name: My Application Name, model: OSS, manufacturer: Mathieu Carbou, sw_version: 1.0.1 } }关键点在于state_topic中的~符号是 HA 协议定义的占位符begin()时传入的base topic如/my-app将自动替换所有~生成绝对路径/my-app/grid/online。unique_id由device.id与object_id拼接而成确保 HA 中实体 ID 全局唯一避免多设备同名冲突。device对象内容完全来自begin()传入的Device结构体实现设备元数据的一致性分发。3. 核心 API 详解与工程化用法MycilaHADiscovery 的 API 设计遵循“声明式配置”原则所有组件均以值语义value semantics构造通过publish()注册后即完成配置。以下按功能类别梳理核心 API并结合嵌入式工程实践给出深度解析。3.1 初始化与生命周期管理// 设置设备级“遗嘱”主题用于报告设备在线状态 void setWillTopic(const char* topic); // 启动发现服务注册设备元数据绑定发布回调 bool begin(const Device device, const char* baseTopic, std::functionvoid(const char*, const char*) publishCallback);setWillTopic()必须在begin()之前调用。其参数topic如~/status将被baseTopic替换为/my-app/status。此主题需由用户 MQTT 客户端设置为 LWTLast Will and Testament主题当设备异常断连时MQTT Broker 自动发布offline消息HA 由此判定设备离线。begin()的publishCallback是库与用户代码的唯一耦合点。其签名void(const char*, const char*)强制要求用户在此回调内调用mqttClient.publish(topic, payload)。这种设计解耦了网络层使库可适配任意 MQTT 客户端。在 FreeRTOS 环境中此回调可安全地放入任务队列避免在中断上下文调用耗时的网络 API。3.2 组件类族与参数语义所有组件均继承自抽象基类Component但用户直接使用具体子类。各子类构造函数参数严格对应 HA Discovery JSON 字段其命名与顺序均经过工程验证。组件类典型用途关键构造参数按声明顺序工程要点Button触发瞬时动作重启、校准id,name,command_topic,payload,icon,categorycommand_topic是 HA 向设备发送指令的主题如~/system/restartpayload是 HA 发送的触发值如restart。设备需监听此主题并执行相应动作。Counter累加型数值启动次数、错误计数id,name,state_topic,state_class,unit_of_measurement,categorystate_class: total_increasing告知 HA 此值只增不减HA 可自动计算增量。unit_of_measurement如times影响 UI 显示格式。Gauge实时测量值内存占用、电压id,name,state_topic,device_class,icon,unit_of_measurement,categorydevice_class: data_size启用 HA 的内存单位自动转换B/KB/MB。icon: mdi:memory使用 Material Design Icons需在 HA 前端启用 mdi 支持。State二值状态在线/离线、开/关id,name,state_topic,payload_on,payload_off,device_class,icon,categorydevice_class: connectivity启用 HA 的连接状态专用图标与颜色。payload_on/off必须与设备实际发布的字符串严格匹配区分大小写。Text可编辑文本配置项id,name,command_topic,state_topic,pattern,icon,categorypattern是正则表达式如^[0-9]$HA 前端将据此验证用户输入。设备需监听command_topic并更新配置再向state_topic发布新值以同步 UI。Number数值型配置阈值、延时id,name,command_topic,state_topic,mode,min,max,step,icon,categorymode: NumberMode::SLIDER强制 HA 前端显示滑块而非数字输入框。min/max/step直接约束 UI 操作范围避免无效值。Switch双态控制输出继电器、LEDid,name,command_topic,state_topic,payload_on,payload_off,icon,categorycommand_topic接收 HA 指令ON/OFFstate_topic发布设备当前状态。二者主题可不同实现命令与状态分离。Select下拉选项配置模式选择id,name,command_topic,state_topic,icon,category,optionsoptions是std::vectorconst char*如{mon,tue,...}。HA 前端生成下拉菜单设备需处理command_topic的选项字符串并更新state_topic。Outlet带可用性检测的开关扩展Switchid,name,command_topic,state_topic,payload_on,payload_off继承Switch但额外暴露availabilityTopic,payloadAvailable,payloadNotAvailable成员变量用于细粒度控制组件可用性。3.3 高级特性可用性与验证全局可用性Global Availability通过setWillTopic()设置设备级心跳主题后所有组件默认继承此可用性。设备需在主循环中定期发布// 在主循环中每30秒发布一次 if (millis() - lastHeartbeat 30000) { mqttClient.publish(/my-app/status, online); // 注意此处为绝对路径 lastHeartbeat millis(); }HA 收到online后将设备下所有组件标记为available若超时未收到则标记为unavailable。组件级可用性Per-Component Availability对于关键外设如继电器需独立监控其供电或通信状态。Outlet类提供了直接访问Outlet relay1Commute(rel_commute, Relay 1, /my-app/relays/rel1/state/set, /my-app/relays/rel1/state, on, off); // 覆写可用性主题监控继电器驱动芯片的使能引脚状态 relay1Commute.availabilityTopic /my-app/relays/rel1/enabled; relay1Commute.payloadAvailable true; relay1Commute.payloadNotAvailable false; haDiscovery.publish(relay1Commute);此时即使设备整体在线/my-app/status为online若/my-app/relays/rel1/enabled发布falseHA 仍会将rel_commute开关置灰并显示unavailable防止误操作。输入验证Regex ValidationText和Number组件支持前端验证减少无效指令。Text的pattern参数需为 POSIX ERE 格式// 仅允许输入 1-5 位数字 Text mqttInterval(mqtt_publish_interval, MQTT Publish Interval, /my-app/config/mqtt_interval/set, /my-app/config/mqtt_interval, ^[1-9][0-9]{0,4}$, // 匹配 1-99999 mdi:timer-sand, Category::CONFIG);HA 前端将此正则应用于输入框onchange事件阻止非法字符输入。设备端仍需在command_topic回调中二次校验形成纵深防御。4. 在 STM32 HAL FreeRTOS 环境中的集成实践将 MycilaHADiscovery 移植到 STM32 平台需解决三个关键问题字符串类型兼容、内存管理策略、以及与 FreeRTOS 任务的协同。以下为经过量产验证的工程方案。4.1 字符串类型适配Arduino 的String类在 STM32 HAL 中不可用需替换为std::string。修改库头文件MycilaHADiscovery.h// 替换所有 String - std::string #include string using String std::string; // 保持 API 兼容性链接时需确保编译器启用 C11 标准-stdgnu11并链接libstdc。为避免std::string的堆分配开销可在FreeRTOSConfig.h中增大configTOTAL_HEAP_SIZE或使用std::string_viewC17替代但需评估编译器支持。4.2 FreeRTOS 任务安全发布publishCallback回调必须是线程安全的。推荐方案创建专用 MQTT 发布任务所有publish()调用均通过队列投递消息// 定义消息结构 struct MqttMsg { char topic[128]; char payload[512]; }; // 创建队列 QueueHandle_t xMqttQueue; // MQTT 发布任务 void vMqttPublishTask(void *pvParameters) { MqttMsg msg; for(;;) { if (xQueueReceive(xMqttQueue, msg, portMAX_DELAY) pdPASS) { // 调用 HAL 库发布示例使用 STM32CubeMX 生成的 MQTT 客户端 HAL_MQTT_Publish(hmqqt, msg.topic, (uint8_t*)msg.payload, strlen(msg.payload), MQTT_QOS_1, 0); } } } // 修改 publishCallback 为队列投递 auto publishCallback [](const char* topic, const char* payload) { MqttMsg msg; strncpy(msg.topic, topic, sizeof(msg.topic)-1); strncpy(msg.payload, payload, sizeof(msg.payload)-1); xQueueSend(xMqttQueue, msg, 0); // 非阻塞投递 };此设计将 JSON 生成CPU 密集与网络 I/O可能阻塞分离符合 FreeRTOS 最佳实践。4.3 诊断传感器实战内存与 NTP 状态以Gauge和State组件为例展示如何在 STM32 上采集真实硬件数据// 获取 Heap 内存使用量CMSIS-RTOS API uint32_t getHeapUsed() { osMemoryPoolAttr_t attr; osMemoryPoolId_t pool osMemoryPoolNew(1024, 4, attr); // 示例池 uint32_t used osMemoryPoolGetSpace(pool); osMemoryPoolDelete(pool); return 1024 - used; // 简化计算实际需用 HAL_GetTick() 等 } // NTP 同步状态基于 SNTP 客户端 bool isNtpSynced() { return (sntp_get_sync_status() SNTP_SYNC_STATUS_COMPLETED); } // 在主循环中定期发布 void loop() { static uint32_t lastPublish 0; if (HAL_GetTick() - lastPublish 5000) { // 每5秒 // 发布内存用量 haDiscovery.publish(Gauge(memory_used, Memory Used, /my-app/system/heap_used, data_size, mdi:memory, B)); // 发布 NTP 状态 haDiscovery.publish(State(ntp, NTP, /my-app/ntp/synced, isNtpSynced() ? true : false, false, connectivity)); lastPublish HAL_GetTick(); } }注意Gauge构造时不传入具体数值publish()仅生成配置实际数值需由设备主动向state_topic发布。因此上述代码需补充// 在 publish() 后立即发布当前值 mqttClient.publish(/my-app/system/heap_used, String(getHeapUsed()).c_str()); mqttClient.publish(/my-app/ntp/synced, isNtpSynced() ? true : false);5. 配置项管理从 UI 到固件的闭环Home Assistant Discovery 的精髓在于实现“配置即服务”。Text、Number、Select等组件将 HA 前端变为设备的远程配置终端。工程实现需构建完整的读-写-持久化闭环。5.1 配置存储架构在 STM32 上推荐使用 Flash 模拟 EEPROM如 STM32CubeMX 的FLASH_EEPROMmiddleware存储配置。定义配置结构体typedef struct { uint16_t mqttPublishInterval; // 单位秒 uint16_t relay1PowerThreshold; // 单位瓦 bool output1AutoBypassEnable; uint8_t dayOfWeek; // 0mon, 1tue, ... } Config_t; Config_t g_config {30, 1500, true, 0}; // 默认值5.2 配置更新处理流程监听command_topic在 MQTT 连接回调中订阅所有配置主题。解析与校验收到消息后根据主题后缀识别配置项用sscanf()或strtol()解析数值并用Text的pattern规则二次校验。写入 Flash调用HAL_FLASHEx_DATAEEPROM_Unlock()等 API 将新值写入指定地址。同步state_topic向对应state_topic发布新值使 HA UI 实时刷新。// MQTT 消息到达回调 void mqtt_callback(char* topic, byte* payload, unsigned int length) { payload[length] \0; // 确保 null-terminated String topicStr String(topic); if (topicStr.endsWith(/config/mqtt_interval/set)) { long val strtol((char*)payload, nullptr, 10); if (val 1 val 3600) { // 二次校验 g_config.mqttPublishInterval (uint16_t)val; writeConfigToFlash(); // 实现此函数 mqttClient.publish(/my-app/config/mqtt_interval, String(val).c_str()); } } // ... 其他配置项处理 }5.3 启动时配置加载设备上电后需从 Flash 加载配置并初始化 HA 组件void setup() { readConfigFromFlash(); // 从 Flash 加载 g_config // 重新发布所有配置组件确保 HA 状态同步 haDiscovery.publish(Text(mqtt_publish_interval, MQTT Publish Interval, /my-app/config/mqtt_interval/set, /my-app/config/mqtt_interval, ^[1-9][0-9]{0,3}$, mdi:timer-sand, Category::CONFIG)); haDiscovery.publish(Number(relay1_power_threshold, Relay 1 Power Threshold, /my-app/config/rel1_power/set, /my-app/config/rel1_power, NumberMode::SLIDER, 0, 3000, 50, mdi:flash, Category::CONFIG)); // 发布当前值使 UI 显示正确初始状态 mqttClient.publish(/my-app/config/mqtt_interval, String(g_config.mqttPublishInterval).c_str()); mqttClient.publish(/my-app/config/rel1_power, String(g_config.relay1PowerThreshold).c_str()); }此流程确保设备重启后HA UI 与固件配置始终保持一致消除“配置漂移”风险。6. 故障排查与性能优化指南在实际部署中常见问题多源于协议细节疏忽或资源约束。以下是基于现场调试经验的 checklist。6.1 常见故障根因分析现象可能原因排查方法HA 中不显示任何实体begin()未调用publishCallback未正确绑定 MQTT 发布baseTopic包含非法字符空格、中文用mosquitto_sub -t homeassistant/# -v抓包确认是否收到config消息组件显示unavailablesetWillTopic()未设置设备未向status主题发布online组件availabilityTopic主题无订阅者检查status主题消息内容与频率用mosquitto_sub -t /my-app/relays/rel1/enabled验证可用性主题配置项修改后不生效command_topic未被设备监听state_topic未在修改后发布新值pattern正则语法错误如忘记转义在mqtt_callback中添加日志确认消息是否到达检查 HA 日志中是否有Invalid pattern错误设备频繁断连后 HA 状态混乱MQTT 客户端未正确设置 LWTwillTopic与setWillTopic()不一致网络超时参数过短检查MQTTClient.connect()的willTopic参数增大keepAlive时间至 120 秒6.2 内存与性能优化JSON 生成内存publish()期间最大栈消耗约 1KB取决于组件字段数。若遇栈溢出可增大configMINIMAL_STACK_SIZE或将publish()拆分为多个小组件分批发布。Flash 写入寿命配置项频繁更新会加速 Flash 擦写。建议对mqttPublishInterval等非关键配置增加软件滤波如仅当变化 10% 时才写入 Flash。MQTT QoS 选择Discovery 消息推荐QoS 0最多一次因其为静态配置丢失后可通过haDiscovery.begin()重发而状态消息state_topic应使用QoS 1至少一次确保 HA 状态准确。6.3 生产环境加固建议固件版本绑定Device.version字段应与git describe --tags输出一致如v2.1.0-5-gabc123便于在 HA 中按版本筛选设备。安全主题前缀生产环境禁用~/占位符改用绝对路径如/devices/my-app-1234避免主题解析歧义。配置变更审计在mqtt_callback中记录所有配置修改到 UART 或 SD 卡满足工业系统审计要求。MycilaHADiscovery 的价值正在于它迫使工程师直面协议本质——每一行代码都对应一个明确的 MQTT 主题与 JSON 字段。当我们在Outlet对象中显式设置availabilityTopic我们不是在调用一个黑盒 API而是在亲手编织设备与 HA 之间的信任链路。这种对底层细节的掌控力正是嵌入式系统可靠性的终极来源。
