AI-on-the-edge-device MQTT 主主题MainTopic配置完全指南主题层级、发布格式与 Home Assistant 节点派生规则【免费下载链接】AI-on-the-edge-deviceEasy to use device for connecting old measuring units (water, power, gas, ...) to the digital world项目地址: https://gitcode.com/GitHub_Trending/ai/AI-on-the-edge-device导读本文聚焦 AI-on-the-edge-device 智能抄表项目连接水表、电表、气表等旧式计量设备到数字世界的 ESP32 方案中 MQTT 集成的核心参数MainTopic。该参数决定了计数器读数以何种主题层级发布到 MQTT Broker直接影响你在 Home Assistant、Node-RED、Domoticz 等平台上的订阅与自动化设计。读完本文你将掌握MainTopic的默认值、完整发布主题格式MAINTOPIC/NUMBER/RESULT_TOPIC、多级主题拆分技巧以及 Home Assistant MQTT Discovery 中node_id的自动派生规则并能结合源码理解其底层实现。参数概览MainTopic是什么MainTopic是 AI-on-the-edge-device 在[MQTT]配置段中的核心参数定义 MQTT 主主题main topic所有计数器counters的读数都发布在该主主题之下。默认值watermeter配置位置SD 卡上的 config.ini对应的示例配置行为[MQTT] ;MainTopic watermeter在仓库的 sd-card/config/config.ini 中该行以分号注释呈现即采用默认值watermeter时的写法。配置解析位于 ClassFlowMQTT.cpp其中同时接受TOPIC与MAINTOPIC两种参数名均不区分大小写if (((toUpper(_param) TOPIC) || (toUpper(splitted[0]) MAINTOPIC)) (splitted.size() 1)) { maintopic splitted[1]; }解析出的值随后通过mqttServer_setMainTopic(maintopic)传入 MQTT 服务模块见 ClassFlowMQTT.cpp最终由 server_mqtt.cpp 中的 setter 保存。注意在 interface_mqtt.cpp 中MQTT_Configure()会在URI、MainTopic或ClientID任一缺失时判定配置错误并中止初始化日志Init aborted! Config error (URI, MainTopic or ClientID missing)因此MainTopic是 MQTT 功能能否启动的必填项之一。发布主题层级MAINTOPIC/NUMBER/RESULT_TOPIC单个读数single value会以如下键key格式发布MAINTOPIC/NUMBER/RESULT_TOPIC其中各段含义如下MAINTOPIC即本参数配置的主主题。默认watermeter。NUMBER读数的名称。一个计量表可能拥有多个读数例如一个表同时输出累计值、速率等名称在模拟量analog与数字量digitROI感兴趣区域配置中定义未显式配置时默认为main。RESULT_TOPIC由系统自动填充的结果主题名用于区分不同类型的发布内容例如value读数、rate速率、timestamp时间戳、error错误等。因此采用默认配置时最常见的发布主题形如watermeter/main/value watermeter/main/timestampRESULT_TOPIC 的完整取值从 MQTT 服务模块的 Home Assistant Discovery 与发布实现server_mqtt.cpp可以看出每个读数NUMBER下实际存在的 RESULT_TOPIC 包括RESULT_TOPIC含义备注value当前读数累计值核心状态值raw原始读数值diagnostic 类别error错误标记diagnostic 类别rate_per_time_unit按所选时间单位的速率例如m³/h、W等rate_per_digitization_round自上次数字化轮次以来的变化量单位即单位/间隔timestamp读数时间戳diagnostic 类别jsonJSON 格式汇总diagnostic 类别problem基于 error 主题的二进制问题传感器特殊 binary sensor历史遗留的rate始终按 单位/分钟 发布在源码中以注释形式保留// Legacy, always Unit per Minute说明当前版本以rate_per_time_unit与rate_per_digitization_round取代了旧版速率主题订阅时需留意版本差异。连接状态主题MAINTOPIC/CONNECTION除读数外设备与 Broker 的通用连接状态发布在MAINTOPIC/CONNECTION即在主主题下追加CONNECTION一层。订阅该主题即可感知设备在线/离线状态可用于告警或联动场景。多级主题用/拆分层级MainTopic允许包含斜杠/这是其支持多层级 MQTT 主题的关键特性。利用这一点可以将读数按物理位置、设备类型等维度组织成树状结构。官方文档给出的示例/basement/meters/watermeter/1/适用于地下室有多只水表的场景每只水表分配一个独立子级如/1、/2从而避免不同设备之间的主题冲突。最终发布出来的完整主题即为/basement/meters/watermeter/1/main/value这种设计让 MQTT Broker 端的通配符订阅如#、/main/value和权限控制ACL 按前缀授权都能更精细地发挥作用。Home Assistant Discoverynode_id的自动派生规则启用 Home Assistant MQTT Service Discovery 时MainTopic还承担一项额外职责——决定 Discovery 主题中的node_id。Discovery 主题必须遵循标准 schemadiscovery_prefix/component/[node_id/]object_id/config其中discovery_prefixDiscovery 前缀Home Assistant 默认homeassistantcomponent组件类型如sensor、binary_sensornode_id不可配置由MainTopic自动派生object_id对象标识如valueconfig配置文档后缀。node_id的派生规则是保留MainTopic的最后一级主题层级剥离其余所有层级。例如MainTopic 配置值派生出的 node_id当前读数的 Discovery 主题watermeterwatermeterhomeassistant/sensor/watermeter/value/confighome/basement/watermeterwatermeterhomeassistant/sensor/watermeter/value/config这意味着在多级MainTopic场景下如home/basement/watermeterHome Assistant 侧会以最后一段watermeter作为实体节点标识自动生成对应的传感器实体。Discovery 的实际发布逻辑位于 server_mqtt.cpp 的MQTThomeassistantDiscovery()其中对每个读数发布value、raw、error、rate_per_time_unit、rate_per_digitization_round、timestamp、json、problem等实体并在设备级发布uptime、MAC、fwVersion、hostname、freeMem、wifiRSSI、CPUtemp、interval、IP、status、flowstart等诊断实体见 server_mqtt.cpp。设计提示由于node_id取最后一段当同一 Broker 下部署多台设备时应保证各设备MainTopic的末级主题互不相同例如/basement/meters/watermeter/1/与/basement/meters/watermeter/2/会派生出相同的watermeter节点Home Assistant 端需依赖object_id或 entity 配置进一步区分。底层实现MainTopic如何驱动连接与订阅从源码链路看MainTopic的用途远不止发布前缀它还参与以下底层行为连接参数传递在 ClassFlowMQTT.cpp 中maintopic作为参数传入MQTT_Configure()最终写入 interface_mqtt.cpp 的全局变量maintopic。LWT遗嘱主题拼接遗嘱主题由_maintopic / _lwt构成见 interface_mqtt.cpp即设备异常离线时发布的遗嘱消息也挂在主主题之下。下行控制订阅设备在连接成功后订阅以下两个控制主题见 interface_mqtt.cppMAINTOPIC/ctrl/flow_start // 手动触发一次数字化流程 MAINTOPIC/ctrl/set_prevalue // 设置预值prevalue这意味着MainTopic不仅是上行发布的命名空间也是下行控制指令的接收前缀双向都遵循同一层级规则。 4.连接回调callbackOnConnected(maintopic, SetRetainFlag)见 interface_mqtt.cpp在连接建立后依据主主题完成初始化发布。此外主主题还会与[MQTT]段中的其他参数协同工作例如MeterType在 ClassFlowMQTT.cpp 中配置为WATER_M3、GAS_M3、ENERGY_KWH等决定 Discovery 中value与rate_per_time_unit的单位与设备类别HomeassistantDiscovery开关见 server_mqtt.cpp决定是否在启动及周期轮次中发布 Discovery 主题调度逻辑见 server_mqtt.cpp。最佳实践与配置示例综合文档与源码给出以下实操建议单表单值默认场景保持默认即可无需显式配置。[MQTT] MainTopic watermeter发布结果watermeter/main/value、watermeter/main/timestamp、watermeter/CONNECTION。多表多位置多级主题利用/组织命名空间例如地下室两只水表[MQTT] MainTopic /basement/meters/watermeter/1/发布结果/basement/meters/watermeter/1/main/value另一只表配置为.../watermeter/2/Broker 端可用#通配订阅全部水表读数。Home Assistant 集成确保MainTopic末级唯一Discovery 将自动生成homeassistant/sensor/node_id/value/config等配置主题实体在 HA 中自动出现如末级与其他设备冲突可通过调整MainTopic末级或依赖 HA 实体配置区分。修改后生效在设备 Web 界面edit_config_raw.html或参数编辑页修改MainTopic并保存后重启设备从源码看该参数在启动阶段由ClassFlowMQTT::ReadParameter()读取ClassFlowMQTT.cpp且在MQTT_Configure()中参与配置校验interface_mqtt.cpp因此不能为空。小结MainTopic是 AI-on-the-edge-device MQTT 集成的命名空间基石它同时定义了上行读数的发布层级MAINTOPIC/NUMBER/RESULT_TOPIC、连接状态主题MAINTOPIC/CONNECTION、LWT 遗嘱主题、下行控制订阅MAINTOPIC/ctrl/...以及 Home Assistant Discovery 的node_id派生来源。理解并善用其多级主题能力可以在多表、多位置的复杂部署中建立清晰、可扩展的 MQTT 主题体系。相关实现可进一步查阅 ClassFlowMQTT.cpp、server_mqtt.cpp 与 interface_mqtt.cpp测试用例可参考 test_server_mqtt.cpp。【免费下载链接】AI-on-the-edge-deviceEasy to use device for connecting old measuring units (water, power, gas, ...) to the digital world项目地址: https://gitcode.com/GitHub_Trending/ai/AI-on-the-edge-device创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AI-on-the-edge-device MQTT 主主题（MainTopic）配置完全指南：主题层级、发布格式与 Home Assistant 节点派生规则
AI-on-the-edge-device MQTT 主主题MainTopic配置完全指南主题层级、发布格式与 Home Assistant 节点派生规则【免费下载链接】AI-on-the-edge-deviceEasy to use device for connecting old measuring units (water, power, gas, ...) to the digital world项目地址: https://gitcode.com/GitHub_Trending/ai/AI-on-the-edge-device导读本文聚焦 AI-on-the-edge-device 智能抄表项目连接水表、电表、气表等旧式计量设备到数字世界的 ESP32 方案中 MQTT 集成的核心参数MainTopic。该参数决定了计数器读数以何种主题层级发布到 MQTT Broker直接影响你在 Home Assistant、Node-RED、Domoticz 等平台上的订阅与自动化设计。读完本文你将掌握MainTopic的默认值、完整发布主题格式MAINTOPIC/NUMBER/RESULT_TOPIC、多级主题拆分技巧以及 Home Assistant MQTT Discovery 中node_id的自动派生规则并能结合源码理解其底层实现。参数概览MainTopic是什么MainTopic是 AI-on-the-edge-device 在[MQTT]配置段中的核心参数定义 MQTT 主主题main topic所有计数器counters的读数都发布在该主主题之下。默认值watermeter配置位置SD 卡上的 config.ini对应的示例配置行为[MQTT] ;MainTopic watermeter在仓库的 sd-card/config/config.ini 中该行以分号注释呈现即采用默认值watermeter时的写法。配置解析位于 ClassFlowMQTT.cpp其中同时接受TOPIC与MAINTOPIC两种参数名均不区分大小写if (((toUpper(_param) TOPIC) || (toUpper(splitted[0]) MAINTOPIC)) (splitted.size() 1)) { maintopic splitted[1]; }解析出的值随后通过mqttServer_setMainTopic(maintopic)传入 MQTT 服务模块见 ClassFlowMQTT.cpp最终由 server_mqtt.cpp 中的 setter 保存。注意在 interface_mqtt.cpp 中MQTT_Configure()会在URI、MainTopic或ClientID任一缺失时判定配置错误并中止初始化日志Init aborted! Config error (URI, MainTopic or ClientID missing)因此MainTopic是 MQTT 功能能否启动的必填项之一。发布主题层级MAINTOPIC/NUMBER/RESULT_TOPIC单个读数single value会以如下键key格式发布MAINTOPIC/NUMBER/RESULT_TOPIC其中各段含义如下MAINTOPIC即本参数配置的主主题。默认watermeter。NUMBER读数的名称。一个计量表可能拥有多个读数例如一个表同时输出累计值、速率等名称在模拟量analog与数字量digitROI感兴趣区域配置中定义未显式配置时默认为main。RESULT_TOPIC由系统自动填充的结果主题名用于区分不同类型的发布内容例如value读数、rate速率、timestamp时间戳、error错误等。因此采用默认配置时最常见的发布主题形如watermeter/main/value watermeter/main/timestampRESULT_TOPIC 的完整取值从 MQTT 服务模块的 Home Assistant Discovery 与发布实现server_mqtt.cpp可以看出每个读数NUMBER下实际存在的 RESULT_TOPIC 包括RESULT_TOPIC含义备注value当前读数累计值核心状态值raw原始读数值diagnostic 类别error错误标记diagnostic 类别rate_per_time_unit按所选时间单位的速率例如m³/h、W等rate_per_digitization_round自上次数字化轮次以来的变化量单位即单位/间隔timestamp读数时间戳diagnostic 类别jsonJSON 格式汇总diagnostic 类别problem基于 error 主题的二进制问题传感器特殊 binary sensor历史遗留的rate始终按 单位/分钟 发布在源码中以注释形式保留// Legacy, always Unit per Minute说明当前版本以rate_per_time_unit与rate_per_digitization_round取代了旧版速率主题订阅时需留意版本差异。连接状态主题MAINTOPIC/CONNECTION除读数外设备与 Broker 的通用连接状态发布在MAINTOPIC/CONNECTION即在主主题下追加CONNECTION一层。订阅该主题即可感知设备在线/离线状态可用于告警或联动场景。多级主题用/拆分层级MainTopic允许包含斜杠/这是其支持多层级 MQTT 主题的关键特性。利用这一点可以将读数按物理位置、设备类型等维度组织成树状结构。官方文档给出的示例/basement/meters/watermeter/1/适用于地下室有多只水表的场景每只水表分配一个独立子级如/1、/2从而避免不同设备之间的主题冲突。最终发布出来的完整主题即为/basement/meters/watermeter/1/main/value这种设计让 MQTT Broker 端的通配符订阅如#、/main/value和权限控制ACL 按前缀授权都能更精细地发挥作用。Home Assistant Discoverynode_id的自动派生规则启用 Home Assistant MQTT Service Discovery 时MainTopic还承担一项额外职责——决定 Discovery 主题中的node_id。Discovery 主题必须遵循标准 schemadiscovery_prefix/component/[node_id/]object_id/config其中discovery_prefixDiscovery 前缀Home Assistant 默认homeassistantcomponent组件类型如sensor、binary_sensornode_id不可配置由MainTopic自动派生object_id对象标识如valueconfig配置文档后缀。node_id的派生规则是保留MainTopic的最后一级主题层级剥离其余所有层级。例如MainTopic 配置值派生出的 node_id当前读数的 Discovery 主题watermeterwatermeterhomeassistant/sensor/watermeter/value/confighome/basement/watermeterwatermeterhomeassistant/sensor/watermeter/value/config这意味着在多级MainTopic场景下如home/basement/watermeterHome Assistant 侧会以最后一段watermeter作为实体节点标识自动生成对应的传感器实体。Discovery 的实际发布逻辑位于 server_mqtt.cpp 的MQTThomeassistantDiscovery()其中对每个读数发布value、raw、error、rate_per_time_unit、rate_per_digitization_round、timestamp、json、problem等实体并在设备级发布uptime、MAC、fwVersion、hostname、freeMem、wifiRSSI、CPUtemp、interval、IP、status、flowstart等诊断实体见 server_mqtt.cpp。设计提示由于node_id取最后一段当同一 Broker 下部署多台设备时应保证各设备MainTopic的末级主题互不相同例如/basement/meters/watermeter/1/与/basement/meters/watermeter/2/会派生出相同的watermeter节点Home Assistant 端需依赖object_id或 entity 配置进一步区分。底层实现MainTopic如何驱动连接与订阅从源码链路看MainTopic的用途远不止发布前缀它还参与以下底层行为连接参数传递在 ClassFlowMQTT.cpp 中maintopic作为参数传入MQTT_Configure()最终写入 interface_mqtt.cpp 的全局变量maintopic。LWT遗嘱主题拼接遗嘱主题由_maintopic / _lwt构成见 interface_mqtt.cpp即设备异常离线时发布的遗嘱消息也挂在主主题之下。下行控制订阅设备在连接成功后订阅以下两个控制主题见 interface_mqtt.cppMAINTOPIC/ctrl/flow_start // 手动触发一次数字化流程 MAINTOPIC/ctrl/set_prevalue // 设置预值prevalue这意味着MainTopic不仅是上行发布的命名空间也是下行控制指令的接收前缀双向都遵循同一层级规则。 4.连接回调callbackOnConnected(maintopic, SetRetainFlag)见 interface_mqtt.cpp在连接建立后依据主主题完成初始化发布。此外主主题还会与[MQTT]段中的其他参数协同工作例如MeterType在 ClassFlowMQTT.cpp 中配置为WATER_M3、GAS_M3、ENERGY_KWH等决定 Discovery 中value与rate_per_time_unit的单位与设备类别HomeassistantDiscovery开关见 server_mqtt.cpp决定是否在启动及周期轮次中发布 Discovery 主题调度逻辑见 server_mqtt.cpp。最佳实践与配置示例综合文档与源码给出以下实操建议单表单值默认场景保持默认即可无需显式配置。[MQTT] MainTopic watermeter发布结果watermeter/main/value、watermeter/main/timestamp、watermeter/CONNECTION。多表多位置多级主题利用/组织命名空间例如地下室两只水表[MQTT] MainTopic /basement/meters/watermeter/1/发布结果/basement/meters/watermeter/1/main/value另一只表配置为.../watermeter/2/Broker 端可用#通配订阅全部水表读数。Home Assistant 集成确保MainTopic末级唯一Discovery 将自动生成homeassistant/sensor/node_id/value/config等配置主题实体在 HA 中自动出现如末级与其他设备冲突可通过调整MainTopic末级或依赖 HA 实体配置区分。修改后生效在设备 Web 界面edit_config_raw.html或参数编辑页修改MainTopic并保存后重启设备从源码看该参数在启动阶段由ClassFlowMQTT::ReadParameter()读取ClassFlowMQTT.cpp且在MQTT_Configure()中参与配置校验interface_mqtt.cpp因此不能为空。小结MainTopic是 AI-on-the-edge-device MQTT 集成的命名空间基石它同时定义了上行读数的发布层级MAINTOPIC/NUMBER/RESULT_TOPIC、连接状态主题MAINTOPIC/CONNECTION、LWT 遗嘱主题、下行控制订阅MAINTOPIC/ctrl/...以及 Home Assistant Discovery 的node_id派生来源。理解并善用其多级主题能力可以在多表、多位置的复杂部署中建立清晰、可扩展的 MQTT 主题体系。相关实现可进一步查阅 ClassFlowMQTT.cpp、server_mqtt.cpp 与 interface_mqtt.cpp测试用例可参考 test_server_mqtt.cpp。【免费下载链接】AI-on-the-edge-deviceEasy to use device for connecting old measuring units (water, power, gas, ...) to the digital world项目地址: https://gitcode.com/GitHub_Trending/ai/AI-on-the-edge-device创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考