1. 项目概述HA MQTT Discovery 是一个专为嵌入式平台特别是 ESP32/ESP8266设计的轻量级 C 库用于实现与 Home Assistant 的原生 MQTT 自动发现Auto-Discovery协议兼容的设备与实体注册。其核心目标并非替代完整的 MQTT 客户端而是作为上层逻辑粘合剂——在已有稳定 MQTT 连接如 EspMQTTClient基础上自动生成、格式化并发布符合 Home Assistant 官方规范的 JSON 配置载荷discovery payload从而让设备无需手动在 HA 前端配置即可被自动识别、集成并呈现为可交互的传感器、开关、灯等实体。该库严格遵循 Home Assistant MQTT Discovery 官方协议 所有生成的config主题、JSON 字段、Topic 层级结构均与 HA 服务端解析器完全对齐。其工程价值在于将原本需硬编码、易出错、难维护的 JSON 构造与 Topic 管理逻辑封装为面向对象、类型安全、可复用的 C 接口显著降低嵌入式开发者对接 Home Assistant 的技术门槛与调试成本。1.1 设计哲学与工程定位HA MQTT Discovery 并非一个独立的网络栈或协议解析器而是一个典型的“协议适配层”Protocol Adapter Layer。其设计遵循嵌入式开发的黄金法则零内存分配Zero-Allocation优先所有字符串操作基于String类PlatformIO/Arduino 环境但关键路径如getConfigPayload()内部采用预分配缓冲区与静态 JSON 模板避免运行时动态malloc保障实时性与内存稳定性。依赖注入Dependency Injection设备HAMqttDevice与实体HAMqttEntity不持有 MQTT 客户端实例而是通过构造函数或setClient()注入。这使得同一设备对象可灵活切换不同客户端如测试用 Mock Client 或生产用 EspMQTTClient极大提升单元测试可行性。配置即代码Configuration-as-Code所有 HA 所需的元数据厂商、固件版本、设备类、状态类等均通过addConfig()方法以键值对形式注入而非修改头文件宏定义。这实现了配置与逻辑分离支持 OTA 动态更新设备描述信息。主题路径抽象化Topic Abstraction引入~占位符机制如getCommandTopic(true)返回~/command由 HA 服务端在接收时自动替换为实际的 base topic。此设计使固件代码完全解耦于具体的 MQTT 主题前缀增强部署灵活性。1.2 典型应用场景该库适用于所有需通过 MQTT 与 Home Assistant 无缝集成的 ESP 系列物联网终端设备典型用例包括能源监控节点将电表脉冲计数、电压/电流采样值作为sensor实体上报自动启用total_increasing状态类与energy设备类直接接入 HA 的能源管理面板。智能照明控制器将 RGB LED 驱动模块注册为light实体支持亮度、色温、RGB 颜色控制并通过availability主题实现设备在线状态感知。环境传感器网关将温湿度、PM2.5、CO2 等多路传感器数据分别注册为独立sensor实体共享同一device对象形成逻辑统一的物理设备视图。执行器节点将继电器、电机驱动器注册为switch或fan实体接收 HA 下发的ON/OFF命令并通过state_topic反馈实际执行状态构建闭环控制。2. 核心架构与对象模型HA MQTT Discovery 采用清晰的两级对象模型HAMqttDevice表征物理设备如一台 ESP32 开发板HAMqttEntity表征设备提供的逻辑功能单元如一个温度传感器、一个电源开关。二者通过强引用关联确保 Topic 路径与配置数据的一致性。2.1 HAMqttDevice设备级抽象HAMqttDevice是整个发现流程的根对象负责管理设备全局属性、可用性Availability心跳及基础 Topic 命名空间。其构造函数签名如下HAMqttDevice::HAMqttDevice(String device_name, EspMQTTClient client);device_name设备唯一标识符。必须为 ASCII 字符禁止重音符号、Unicode建议使用下划线分隔的英文小写如living_room_sensor。该名称将参与生成device.id、device.name及 Topic 路径是 HA 前端设备列表显示的关键字段。client引用已初始化的EspMQTTClient实例。若未提供manageAvailability()、sendAvailable()等依赖网络的操作将失效但getConfigPayload()等纯数据生成方法仍可调用。设备配置管理设备级通用配置通过addConfig()方法注入这些键值对将被合并到所有下属HAMqttEntity的 discovery payload 中的device字段内。常用配置项包括键Key值Value示例说明manufacturerEspressif设备制造商名称显示在 HA 设备信息页modelESP32-WROOM-32设备型号sw_versionv2.1.0固件版本号触发 HA 的固件更新提示identifiersesp32_abc123设备唯一硬件 ID推荐使用 MAC 地址哈希用于 HA 设备去重与关联configuration_urlhttp://192.168.1.100设备本地 Web 配置页面 URLHA 前端提供快捷访问按钮代码示例设备初始化与配置#include EspMQTTClient.h #include HAMqttDevice.h // 初始化 MQTT 客户端需提前连接 WiFi EspMQTTClient mqttClient( your_ssid, your_password, 192.168.1.100, // MQTT Broker IP user, pass ); // 创建设备对象绑定客户端 HAMqttDevice device(bedroom_climate, mqttClient); void setup() { // 注入设备元数据 device.addConfig(manufacturer, Acme Corp); device.addConfig(model, Thermostat v1); device.addConfig(sw_version, 1.2.3); device.addConfig(identifiers, thermo_bedroom_001); // 建议使用 MAC 地址 device.addConfig(configuration_url, http://192.168.1.101); }可用性Availability管理Home Assistant 通过订阅availability_topic判断设备在线状态。HAMqttDevice提供两种机制手动心跳调用manageAvailability(uint16_t keepAliveSecond)库将在loop()中自动以指定间隔秒向availability_topic发布online消息。手动控制调用sendAvailable()立即发布online或sendUnavailable()发布offline需自行实现离线逻辑。关键点availability_topic默认格式为base_topic/availability其中base_topic由库自动生成如homeassistant/sensor/bedroom_climate_001开发者无需手动拼接。代码示例可用性心跳void loop() { mqttClient.loop(); // 维持 MQTT 连接 // 每 60 秒发送一次 online 心跳 device.manageAvailability(60); // 其他业务逻辑... }2.2 HAMqttEntity实体级抽象HAMqttEntity代表设备提供的具体功能如一个温度读数、一个开关状态。其构造函数需关联父设备并指定组件类型HAMqttEntity::HAMqttEntity(HAMqttDevice device, String name, Component component);device父HAMqttDevice引用决定实体所属的设备上下文与 Topic 基础路径。name实体名称如Temperature将显示在 HA 界面中作为entity_id的一部分最终为sensor.bedroom_climate_temperature。component枚举类型HAMqttEntity::Component明确告知 HA 此实体的语义类型。该参数直接决定 discovery payload 的顶层主题与 JSON 结构。支持的组件类型Component枚举值HA Topic 前缀典型用途关键配置字段示例HAMqttEntity::SENSORsensor/温湿度、电量、能耗等数值型传感器device_class,state_class,unit_of_measurementHAMqttEntity::SWITCHswitch/电源开关、继电器控制payload_on,payload_off,optimisticHAMqttEntity::LIGHTlight/RGB/W 白光灯控制rgb,color_temp,brightnessHAMqttEntity::BINARY_SENSORbinary_sensor/门磁、烟雾报警器等二值状态payload_on,payload_off,device_classHAMqttEntity::FANfan/风扇速度控制speed_count,oscillation注若所需组件不在列表中如climate需向项目 GitHub 提交 Issue 请求扩展。库的设计允许在不破坏现有 API 的前提下通过新增枚举值与对应 JSON 模板轻松支持新组件。实体 Topic 管理每个实体需至少配置command_topic接收 HA 命令和state_topic上报设备状态addCommandTopic()为实体启用命令接收能力。库自动生成command_topic如homeassistant/switch/bedroom_climate_power/setHA 将向此 Topic 发布ON/OFF等指令。addStateTopic()为实体启用状态上报能力。库自动生成state_topic如homeassistant/switch/bedroom_climate_power/state设备需主动向此 Topic 发布当前状态。代码示例创建开关实体// 创建一个名为 Power 的开关实体隶属于 device HAMqttEntity entityPower(device, Power, HAMqttEntity::SWITCH); void setup() { // 启用命令与状态 Topic entityPower.addCommandTopic(); entityPower.addStateTopic(); // 配置开关特有参数 entityPower.addConfig(payload_on, ON); entityPower.addConfig(payload_off, OFF); // optimistictrue 表示设备不反馈状态HA 直接信任命令结果 entityPower.addConfig(optimistic, true); } void loop() { // ... 检测物理开关状态 if (physicalSwitchIsOn()) { // 向 state_topic 发布 ON同步 HA 界面 mqttClient.publish(entityPower.getStateTopic(), ON); } }实体配置管理实体级配置通过addConfig()注入字段取决于Component类型。例如SENSOR实体常用配置键Key值Value示例说明device_classtemperature告知 HA 该传感器类型启用对应图标与单位℃state_classmeasurement告知 HA 数据为瞬时测量值非累计值unit_of_measurement°C显示单位value_template{{ value_json.temperature }}若 payload 为 JSON用 Jinja2 模板提取字段需 HA 2021.12代码示例创建温度传感器实体HAMqttEntity entityTemp(device, Temperature, HAMqttEntity::SENSOR); void setup() { entityTemp.addStateTopic(); // 注入传感器语义配置 entityTemp.addConfig(device_class, temperature); entityTemp.addConfig(state_class, measurement); entityTemp.addConfig(unit_of_measurement, °C); // 若上报 JSON {temperature: 23.5}则用此模板提取 entityTemp.addConfig(value_template, {{ value_json.temperature }}); } void loop() { float temp readDHT22(); // 读取传感器 // 构造 JSON payload 并发布 String json {\temperature\: String(temp, 1) }; mqttClient.publish(entityTemp.getStateTopic(), json); }3. API 详解与关键方法剖析3.1 Device 核心 API方法签名返回值作用说明工程要点String getConfigPayload()String生成完整的设备配置 JSON不含实体仅device元数据内部调用ArduinoJson库序列化结果可直接用于publish()无客户端时不崩溃String getAvailabilityTopic(bool relativefalse)String获取可用性 Topic。relativetrue返回~/availabilityfalse返回完整路径~由 HA 解析推荐在publish()中使用relativetrue保持代码简洁void manageAvailability(uint16_t sec)void启动后台定时任务每sec秒发布online消息必须在loop()中周期调用首次调用即发送online后续按间隔续发void sendAvailable()/sendUnavailable()void立即发送online/offline消息适用于设备启动/关机、WiFi 断连等需即时通知的场景3.2 Entity 核心 API方法签名返回值作用说明工程要点String getConfigPayload()String生成该实体的完整 discovery JSON含device字段继承调用此方法前必须已调用addCommandTopic()或addStateTopic()至少其一String getStateTopic(bool relativefalse)String获取状态 Topic。relativetrue返回~/state设备上报状态时应使用此 Topic 发布String getCommandTopic(bool relativefalse)String获取命令 Topic。relativetrue返回~/setHA 下发命令时订阅此 Topic设备需在此回调中解析ON/OFF等指令String getDiscoveryTopic(bool relativefalse)String获取 discovery 主题如homeassistant/switch/.../config这是向 HA 注册实体的关键 Topic必须向此 Topic 发布getConfigPayload()3.3 Discovery 流程全链路代码示例以下为一个完整、可运行的 ESP32 示例实现一个带温度传感器与电源开关的复合设备#include Arduino.h #include WiFi.h #include EspMQTTClient.h #include HAMqttDevice.h #include HAMqttEntity.h // WiFi MQTT 配置 const char* WIFI_SSID YourNetwork; const char* WIFI_PASSWORD YourPass; const char* MQTT_IP 192.168.1.100; const char* MQTT_USER ha; const char* MQTT_PASS ha123; // 全局对象 WiFiClient wifiClient; EspMQTTClient mqttClient(wifiClient, WIFI_SSID, WIFI_PASSWORD, MQTT_IP, 1883, MQTT_USER, MQTT_PASS); HAMqttDevice device(kitchen_sensor, mqttClient); // 实体对象 HAMqttEntity entityTemp(device, Temperature, HAMqttEntity::SENSOR); HAMqttEntity entityPower(device, Power, HAMqttEntity::SWITCH); void onMqttConnect(bool sessionPresent) { Serial.println(Connected to MQTT.); // 【关键步骤1】向 discovery topic 发布 config payload // 这会触发 HA 自动创建实体 mqttClient.publish( entityTemp.getDiscoveryTopic(), entityTemp.getConfigPayload(), true // retain true确保 HA 重启后仍能发现 ); mqttClient.publish( entityPower.getDiscoveryTopic(), entityPower.getConfigPayload(), true ); // 【关键步骤2】订阅 command topic接收 HA 指令 mqttClient.subscribe(entityPower.getCommandTopic()); } void onMqttMessage(const String topic, const String payload) { // 处理开关命令 if (topic entityPower.getCommandTopic()) { if (payload ON) { digitalWrite(LED_BUILTIN, HIGH); // 控制物理开关 // 【关键步骤3】立即反馈状态到 state topic mqttClient.publish(entityPower.getStateTopic(), ON); } else if (payload OFF) { digitalWrite(LED_BUILTIN, LOW); mqttClient.publish(entityPower.getStateTopic(), OFF); } } } void setup() { Serial.begin(115200); pinMode(LED_BUILTIN, OUTPUT); // 配置设备元数据 device.addConfig(manufacturer, ESP Labs); device.addConfig(model, Kitchen Sensor Node); device.addConfig(sw_version, 1.0.0); device.addConfig(identifiers, esp32_kitchen_001); // 配置温度传感器 entityTemp.addStateTopic(); entityTemp.addConfig(device_class, temperature); entityTemp.addConfig(unit_of_measurement, °C); entityTemp.addConfig(state_class, measurement); // 配置电源开关 entityPower.addCommandTopic(); entityPower.addStateTopic(); entityPower.addConfig(payload_on, ON); entityPower.addConfig(payload_off, OFF); // 设置 MQTT 回调 mqttClient.onConnectionEstablished(onMqttConnect); mqttClient.onMessage(onMqttMessage); } void loop() { mqttClient.loop(); device.manageAvailability(60); // 60秒心跳 // 每2秒读取并上报温度 static unsigned long lastTemp 0; if (millis() - lastTemp 2000) { lastTemp millis(); float temp 24.5 random(-100, 100) / 100.0; // 模拟读数 String tempStr String(temp, 1); mqttClient.publish(entityTemp.getStateTopic(), tempStr); } }执行流程解析设备启动连接 WiFi 与 MQTT。onMqttConnect触发向homeassistant/sensor/kitchen_sensor_temperature/config发布 JSON 配置。HA 接收后自动创建sensor.kitchen_sensor_temperature实体并订阅其state_topic。设备周期性向state_topic发布温度值HA 实时更新界面。用户在 HA 点击开关HA 向command_topic发布ON设备onMqttMessage回调捕获并执行物理动作再反馈状态。4. 高级配置与工程实践4.1 Topic 命名空间定制库默认使用homeassistant作为 base topic 前缀。若需修改如部署到hassio实例可通过预编译宏覆盖#define HA_MQTT_BASE_TOPIC hassio #include HAMqttDevice.h4.2 内存优化技巧在资源受限的 ESP8266 上String对象可能引发碎片化。可强制使用char[]缓冲区char payloadBuffer[512]; entityTemp.getConfigPayload().toCharArray(payloadBuffer, sizeof(payloadBuffer)); mqttClient.publish(entityTemp.getDiscoveryTopic(), payloadBuffer, true);4.3 错误处理与调试验证 JSON 有效性将getConfigPayload()输出复制到在线 JSON 校验器如 jsonlint.com确认无语法错误。监听 MQTT Broker使用mosquitto_sub -t homeassistant/# -v查看设备发布的所有 discovery 消息。检查 HA 日志HA 的home-assistant.log会记录 discovery 失败原因如Invalid config for [mqtt]: required key not provided data[state_topic]。4.4 与 FreeRTOS 集成示例在多任务环境中将 discovery 发布置于独立任务void discoveryTask(void* pvParameters) { while(1) { // 等待 MQTT 连接就绪信号量 xSemaphoreTake(mqttConnectedSemaphore, portMAX_DELAY); // 发布所有实体配置 mqttClient.publish(entityTemp.getDiscoveryTopic(), entityTemp.getConfigPayload(), true); vTaskDelay(1000 / portTICK_PERIOD_MS); // 避免 Topic 冲突 vTaskDelete(NULL); } } // 在 setup() 中创建任务 xTaskCreate(discoveryTask, DISCOVERY, 4096, NULL, 1, NULL);5. 故障排查与常见问题Q1HA 未发现设备日志显示Received message on illegal discovery topic原因getDiscoveryTopic()返回的 Topic 格式错误或未使用retaintrue发布。解决确认publish()第四个参数为true打印getDiscoveryTopic()输出验证是否为homeassistant/sensor/xxx/config。Q2实体创建成功但状态不更新原因state_topic发布的 payload 与value_template不匹配或未订阅state_topic。解决关闭value_template测试用mosquitto_sub监听state_topic确认设备确实在发布。Q3设备频繁显示unavailable原因manageAvailability()未在loop()中调用或keepAliveSecond设置过大。解决确保device.manageAvailability(60)在主循环中检查 WiFi 信号强度与 MQTT 连接稳定性。Q4中文设备名显示为乱码原因device_name包含非 ASCII 字符。解决严格使用 ASCII 字符命名如shi_yan_shi_wen_du替代实验室温度。该库的工程价值在于将 Home Assistant 复杂的 MQTT Discovery 协议转化为嵌入式工程师可理解、可调试、可复用的 C 对象接口。当一个entityTemp.addConfig(device_class, temperature)调用最终在 HA 前端渲染出精准的温度图标与摄氏度单位时底层协议的严谨性与上层 API 的简洁性共同构成了物联网设备无缝接入生态的坚实桥梁。