HA MQTT Integrations

配置

在 Home Assistant（简称HA） 使用 MQTT功能的前提条件：

• MQTT Integration

  在HA中添加方式：Settings -> Devices & services。若在Discovered能够出现 MQTT 可以直接点击“ADD”，否则，点击“ADD INTEGRATION”，搜索“MQTT”，点击添加。

• MQTT Broker

  可以在HA中通过Add-ons方式安装MQTT Broker，当然也可以使用其他主机中的MQTT Broker。

  在HA中添加方式：Settings -> Add-ons -> ADD-ON STORE。可以在 Official add-ons 中找到 "Mosquitto broker"，点击安装。

发现

在HA中可以通过三种方式来发现设备：

• 通过 MQTT 发现配置MQTT组件
• 通过 YAML 配置MQTT组件
• 通过 子条目配置MQTT组件

这里主要介绍一下 MQTT发现。在设备端按照HA MQTT设备发现规定的数据格式，将主题和消息发布到MQTT Broker后，HA端可以发现设备，并添加设备到MQTT集成。

发现主题

发现主题特定的格式：<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

• <discovery_prefix>：发现前缀默认为 homeassistant，该前缀可以修改。
• <component>：受支持的MQTT集成之一。
• <node_id>：可选，提供主题的节点ID，HA不会使用此ID，但可用于构建MQTT主题。
• <object_id>：设备的ID。这仅用于为每个设备创建单独的主题，不用于 entity_id。

可以将<node_id>忽略，而将<object_id> 改为 <unique_id>更具有实用性。

设备发现有效载荷

有效载荷的格式需要根据具体的类型来决定，当前已经支持的类型有：

• Alarm control panel
• Binary sensor
• Button
• Camera
• Cover
• Device tracker
• Device trigger
• Event
• Fan
• Humidifier
• Image
• Climate/HVAC
• Lawn mower
• Light
• Lock
• Notify
• Number
• Scene
• Select
• Sensor
• Siren
• Switch
• Update
• Tag scanner
• Text
• Vacuum
• Valve
• Water heater

对部分类型进行详细介绍。

Event

mqtt事件平台允许您处理来自 MQTT 消息的事件信息。事件是在发生某些事件时发出的信号，例如，当用户按下门铃等物理按钮或遥控器上的按钮时。借助事件，您可以发送一些事件属性，使其成为实体的属性。MQTT 事件是无状态的。例如，门铃没有“开”或“关”之类的状态，而是被短暂按下。

Topic：homeassistant/event/701ECD78-press-1/config

{
  "device": {
    "connections": [
      [
        "mac",
        "70:1E:CD:78"
      ]
    ],
    "identifiers": "701ECD78",
    "hw_version": "1.0.0",
    "manufacturer": "SONOFF",
    "model": "Smate",
    "name": "Smate",
    "serial_number": "701ECD78",
    "sw_version": "1.0.0"
  },
  "event_types": [
    "Single press",
    "Double press",
    "Long press"
  ],
  "availability_topic": "dongle-m-subdevice/event/701ECD78-press-1/availability",
  "state_topic": "dongle-m-subdevice/event/701ECD78-press-1/state",
  "platform": "event",
  "object_id": "701ECD78",
  "unique_id": "701ECD78-press-1",
  "value_template": "{\"event_type\": \"{{ value_json.press }}\"}",
  "device_class": "button",
  "name": "Channel 1"
}

注意：

• event_type：必选项
• platform：必选项，值为event
• state_topic：必选项，该主题的payload必须包含 event_type 字段，且该字段的值应该是 event_type 列表元素之一。

Sensor

mqtt传感器平台使用 MQTT 消息负载作为传感器值。如果此平台中的消息state_topic发布时带有RETAIN标志，传感器将收到包含最新已知值的即时更新。否则，初始状态将为未定义状态。

Topic：homeassistant/sensor/701ECD78-pairing-time/config

{
  "device": {
    "identifiers": "701ECD78"
  },
  "availability_topic": "dongle-m-subdevice/sensor/701ECD78-pairing-time/availability",
  "state_topic": "dongle-m-subdevice/sensor/701ECD78-pairing-time/state",
  "platform": "sensor",
  "object_id": "701ECD78",
  "unique_id": "701ECD78-pairing-time",
  "entity_category": "diagnostic",
  "value_template": "{{ value_json.time }}",
  "name": "Pairing time"
}

注意：

• platform：必选项，值为sensor
• state_topic：必选项

Switch

mqtt开关平台可以用于控制设备属性打开/关闭。

Topic：homeassistant/switch/E465B8CA6D98-ap-switch/config

{
  "device": {
    "identifiers": "E465B8CA6D98"
  },
  "availability_topic": "dongle-m/switch/E465B8CA6D98-ap-switch/availability",
  "state_topic": "dongle-m/switch/E465B8CA6D98-ap-switch/state",
  "platform": "switch",
  "object_id": "E465B8CA6D98",
  "unique_id": "E465B8CA6D98-ap-switch",
  "name": "AP(Access point)",
  "command_topic": "dongle-m/switch/E465B8CA6D98-ap-switch/set",
  "device_class": "switch"
}

注意：

• command_topic：必选项，该主题用来发布命令来改变开关的状态。该主题的payload默认值为：OFF 或者 ON
• platform：必选项，值为switch

Button

mqtt 按钮平台允许您在前端按下按钮或调用按钮按下操作时发送 MQTT 消息。这可用于公开远程设备的某些服务，例如重启。

Topic：homeassistant/button/E465B8CA6D98-system-restart/config

{
  "device": {
    "identifiers": "E465B8CA6D98"
  },
  "availability_topic": "dongle-m/button/E465B8CA6D98-system-restart/availability",
  "state_topic": "dongle-m/button/E465B8CA6D98-system-restart/state",
  "platform": "button",
  "object_id": "E465B8CA6D98",
  "unique_id": "E465B8CA6D98-system-restart",
  "name": "Restart",
  "entity_category": "config",
  "command_topic": "dongle-m/button/E465B8CA6D98-system-restart/set",
  "device_class": "restart",
  "payload_press": "restart"
}

注意：

• command_topic：必选项，触发案件来发布控制命令的MQTT消息
• platform：必选项，值为button

Update

mqtt 更新平台允许您将可能通过 MQTT 公开已安装固件/软件及其最新版本的设备作为更新实体集成到 Home Assistant 中。每次收到配置中 topic 下的消息时，该实体都会在 Home Assistant 中更新。

Topic：homeassistant/update/E465B8CA6D98-esp32d0wdr2-update/config

{
  "device": {
    "identifiers": "E465B8CA6D98"
  },
  "availability_topic": "dongle-m/update/E465B8CA6D98-esp32d0wdr2-update/availability",
  "state_topic": "dongle-m/update/E465B8CA6D98-esp32d0wdr2-update/state",
  "platform": "update",
  "object_id": "E465B8CA6D98",
  "unique_id": "E465B8CA6D98-esp32d0wdr2-update",
  "entity_category": "config",
  "command_topic": "dongle-m/update/E465B8CA6D98-esp32d0wdr2-update/set",
  "device_class": "firmware",
  "payload_install": "update_fw",
  "name": "ESP32D0WDR2 firmware"
}

注意：

• platform：必选项，值为update

触发器

mqtt 设备触发平台使用 MQTT 消息有效负载来生成设备触发事件。MQTT设备触发器仅支持通过MQTT发现，不支持手动设备 configuration.yaml。

Topic：homeassistant/device_automation/701ECD78-press-1/singlePress/config

{
  "platform": "device_automation",
  "type": "Button 1",
  "automation_type": "trigger",
  "subtype": "Long press",
  "payload": "Long press",
  "topic": "dongle-m-subdevice/event/701ECD78-press-1/state",
  "value_template": "{{ value_json.press }}",
  "device": {
    "model": "Smate",
    "name": "Smate",
    "identifiers": "701ECD78",
    "manufacturer": "SONOFF",
    "sw_version": "1.0.0"
  }
}

注意：

• platform：必选项，值为device_automation

• type：触发类型

• subtype：触发子类型，type 和 subtype 一起组合成了触发类型

• topic：由该主题来作为触发条件

• payload：由主题中的负载决定触发条件中的具体事件

参考来源

1、Home Assistant MQTT

2、Home Assistant MQTT Device trigger

3、深入理解Home Assistant MQTT：配置、自动化、发布等