Home Assistant MQTT 发布动作mqtt.publish完全指南从主题发送到 MQTT Discovery 实战【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读mqtt.publish是 Home Assistant MQTT 集成中最常用的动作action它允许你在自动化automation或脚本script中向任意 MQTT 主题发布消息从而向监听该主题的灯具、继电器等设备发送控制命令或为其他系统发布可供订阅的数据。本文将完整梳理mqtt.publish的 UI 操作方式、全部可用参数Topic、Payload、QoS、Retain、Message Expiry Interval 等的语义与默认值并结合本仓库的 MQTT 集成文档 深入讲解 JSON 负载发布、MQTT Discovery 配置下发、Retain 清理技巧以及 Birth/Will 消息等底层机制帮助你写出可靠、可复用的 MQTT 发布自动化。一、动作概述与使用场景mqtt.publish的核心作用是在自动化或脚本中向指定的 MQTT 主题发布一条消息。其典型用途包括向设备发送控制命令例如向homeassistant/light/1/command主题发布ON让监听该主题的智能灯或继电器动作发布数据供其他系统订阅例如将 Home Assistant 中实体的状态值发布到其他系统可以订阅的主题上通过 MQTT Discovery 注册设备发布符合规范的 discovery 配置消息让 Home Assistant 自动创建对应的传感器、开关等实体。从官方动作定义看见 mqtt.publish 动作文档该动作属于mqtt域与之相关的动作还有 mqtt.dump转储收到的 MQTT 消息和 mqtt.reload重新加载 MQTT 集成配置。二、在 UI 中发布 MQTT 消息通过可视化编辑器发布消息的步骤如下进入设置自动化与场景Settings Automations scenes打开现有的自动化或脚本或选择创建自动化创建新自动化如果新建的是自动化需要在When触发条件部分添加一个触发器脚本不需要触发器它们由其他组件调用时运行在Then do执行动作部分选择添加动作搜索并选择Publish发布输入要发布的Topic主题可选地输入要发送的Payload负载。在Publish options发布选项下还可以设置服务质量QoS、保留标志Retain及其他选项点击保存。UI 中的选项含义UI 选项说明Topic要发布消息的主题必填。Payload要发布的消息内容。留空时发布一条空消息。Evaluate payload评估负载当负载是 Python 字节字面量时评估它并发布原始二进制数据。默认关闭。QoS服务质量0至多一次、1至少一次或2恰好一次。默认值为0。Retain开启后broker 会保存该主题最近的消息并在新订阅者订阅时发送给它。默认关闭。Message Expiry Interval消息过期间隔broker 在消息过期前保留消息的时间秒。仅 MQTT 协议 5.0 支持。三、在 YAML 中使用mqtt.publish在 YAML 中动作引用名为mqtt.publish。基础示例如下action: mqtt.publish data: topic: homeassistant/light/1/command payload: ONYAML 选项完整说明参数类型必填默认值说明topicstring是—要发布消息的主题。payloadstring否—要发布的消息。省略时发布一条空消息。evaluate_payloadboolean否false当负载是 Python 字节字面量时评估它并发布原始数据。qosinteger否0服务质量0至多一次、1至少一次或2恰好一次。retainboolean否false置位后 broker 保存该主题最新消息并在新订阅者订阅时发送。message_expiry_intervalinteger否—broker 在消息过期前保留它的秒数。仅 MQTT 协议 5.0 支持。QoS 取值语义0表示消息最多投递一次可能丢失1保证至少一次投递但可能重复2保证恰好一次投递代价是更高的握手开销。在控制命令等关键消息场景可根据 broker 与网络可靠性选择1或2。四、发布 JSON 负载格式化与转义MQTT 的 payload 必须是字符串。Home Assistant 的 MQTT 集成支持模板详见 MQTT 模板使用位置因此你可以用模板根据实体状态动态构建负载。要发布 JSON需要把它格式化为字符串并正确转义。使用 YAML 的折叠块folded block可以让 JSON 保持可读topic: homeassistant/light/1/state payload: - {Status: off, Data: something}用模板动态构建 JSON由于负载支持模板你可以直接引用实体状态来生成动态 JSON。例如action: mqtt.publish data: topic: homeassistant/sensor/temperature/state payload: - {temperature: {{ states(sensor.bathroom_temperature) }}, unit: °C}模板解析发生在发布前最终的 payload 仍以字符串形式发送到主题。五、进阶技巧原始二进制数据与 Retain 清理发布 Python 字节字面量当负载是一个 Python 字节字面量、而你希望发布原始二进制数据而非文本时可以开启Evaluate payloadevaluate_payload选项。典型场景是向期望接收字节流的设备发送二进制命令。用空消息 Retain 清除保留消息在Retain开启的状态下向某主题发布一条空消息会清除该主题此前保留的消息。这是清理过时 retained 配置或状态的标准做法action: mqtt.publish data: topic: homeassistant/sensor/old_sensor/config payload: retain: true结合 MQTT 集成文档 中关于 discovery 的描述可知发布空且保留的字符串负载到 discovery 主题即可移除对应组件、清除已发布的 discovery 负载并在无其他引用时删除设备条目。六、实战示例一回家时自动开灯下面的自动化在你到家时通过 MQTT 向门廊灯发送开启命令触发器person.me实体状态变为home动作发布 MQTT 消息automation: alias: Turn on the porch light when I get home triggers: - trigger: state entity_id: person.me to: home actions: - action: mqtt.publish data: topic: homeassistant/light/porch/command payload: ON retain: true这里开启retain的意义在于即使后续其他客户端重新连接broker 也会把最近一次的命令状态回放给它帮助新订阅方恢复一致的状态视图。七、实战示例二发布 MQTT Discovery 配置注册传感器你可以用mqtt.publish发布符合 MQTT Discovery 规范的配置消息从而在 Home Assistant 中自动创建一个温度传感器实体。核心流程与主题前缀约定详见 MQTT Discovery 章节。以下示例注册一个浴室温度传感器Discovery 主题前缀为默认的homeassistantaction: mqtt.publish data: topic: homeassistant/sensor/bathroom_temperature/config payload: - {device_class: temperature, unit_of_measurement: \u00b0C, value_template: {{ value | float }}, state_topic: sensors/bathroom/temperature, unique_id: bathroom_temperature, device: { identifiers: bathroom_sensor, name: Bathroom, manufacturer: rtl_433 } }关键字段说明state_topic传感器实际上报温度的主题value_template解析原始 payload 的模板这里把值转成floatunique_id实体的唯一标识用于身份识别与状态恢复device设备分组信息identifiers将该传感器归入同一设备payload使用-折叠块编写JSON 转义字符如\u00b0C按字符串语义处理。让 Discovery 在重启后依然生效根据 MQTT 集成的 Discovery 与可用性说明Home Assistant 重启后带unique_id的已发现 MQTT 条目会保持不可用状态直到收到新的 discovery 消息。常用解决方案有两种订阅 Birth 消息触发重发Home Assistant 的 MQTT 集成启动时默认会在homeassistant/status主题发布 birth 消息默认内容为online。设备或服务可订阅该主题收到online后重新发布 discovery 配置使用 retained discovery 消息发布 discovery 配置时开启retainbroker 会保存该消息并在 MQTT 集成连接时自动回放。需要提醒的是官方文档明确警告retained 消息会一直保留在 broker 中即使设备已停止工作、系统或 broker 重启后依然存在可能产生“幽灵实体”并带来不必要的系统负载。实体较多时请谨慎使用 retained discovery 消息。八、消息过期间隔与 MQTT 5.0message_expiry_interval允许你告诉 broker 在指定秒数后让消息过期。这在两个层面发挥作用作为mqtt.publish的参数直接控制本次发布消息的存活时间作为 MQTT 集成的配置选项可以为设备设置命令负载的过期间隔。注意该特性仅受 MQTT 协议版本 5.0 支持使用前需确认你的 broker 已启用 MQTT 5.0否则该参数会被忽略。九、在 REST API 与脚本中调用除 UI 与 YAML 外mqtt.publish同样可以通过 Home Assistant REST API 调用对应接口为POST /api/services/mqtt/publish$ curl -X POST \ -H Authorization: Bearer ABCDEFGH \ -H Content-Type: application/json \ -d {payload: Test message from HA, topic: home/notification} \ http://IP_ADDRESS:8123/api/services/mqtt/publish也可以组合脚本与自动化实现先由脚本封装发布逻辑、自动化再调用脚本的复用模式示例摘自 MQTT 集成文档的 Automations 小节automation: alias: Send me a message when I get home triggers: - trigger: state entity_id: device_tracker.me to: home actions: - action: script.notify_mqtt data: target: me message: Im home script: notify_mqtt: sequence: - action: mqtt.publish data: payload: {{ message }} topic: home/{{ target }} retain: true脚本中的payload与topic都支持模板插值因此可以根据调用参数动态生成主题与负载。十、手动测试与排错在把自动化投入使用前可以先用命令行工具验证 MQTT 链路。MQTT 集成文档的测试章节 提供了两种方式使用 mosquitto 客户端工具通常随 broker 以*-clients包提供mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m Switch is ON通过前端界面发布测试包进入设置设备与服务在Mosquitto broker卡片选择配置在Publish a packet发布数据包下的topic字段输入主题例如homeassistant/switch/1/power并点击Publish也可以使用Listen to a topic监听主题字段如输入#监听全部主题来验证消息是否按预期收发。如果消息未按预期到达可按以下顺序排查确认topic拼写与订阅方一致MQTT 主题区分大小写且支持、#通配符检查 QoS 级别是否满足投递保证需求检查 broker 是否启用 MQTT 5.0仅在使用message_expiry_interval时需要将日志级别调至 debug 观察 MQTT 通信logger: default: warning logs: homeassistant.components.mqtt: debug十一、小结mqtt.publish是打通 Home Assistant 与外部 MQTT 世界的核心动作。掌握它的全部参数语义——尤其是qos、retain、evaluate_payload与message_expiry_interval——能让你精准控制消息投递行为结合 JSON 折叠块写法、模板动态负载、Discovery 配置下发与 Birth/Will 重发机制可以构建出健壮的设备接入与系统间数据同步方案。相关完整参考可继续阅读 mqtt.publish 动作文档、mqtt.dump 动作文档 以及 MQTT 集成总文档。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考