MQTT

Home Assistant 原生支持 MQTT 协议,以下文档将统一说明所有 MQTT 相关设备及服务的接入方法。

代理服务器

Home Assistant 支持各类 MQTT 代理服务器,接入 MQTT 设备前请配置代理服务器

内置代理服务器

Home Assistant 内置 MQTT 代理服务器(HBMQTT),以下为该代理服务器信息:

Setting Value
Host 地址 localhost
Port 端口 1883
Protocol 协议 3.1.1
User 用户 homeassistant
Password 密码 你的 HA API 密码
Websocket 端口 8080

使用内置服务器,仅需在配置文件 configuration.yaml中设置

mqtt:

如果想详细配置内置代理服务器,则可在后添加相关参数:

mqtt:
  embedded:
    listeners:
      default:
          max-connections: 50000
          type: tcp
      my-tcp-1:
          bind: 127.0.0.1:1883
      my-tcp-2:
          bind: 1.2.3.4:1884
          max-connections: 1000
      my-tcp-ssl-1:
          bind: 127.0.0.1:8885
          ssl: on
          cafile: /some/cafile
          capath: /some/folder
          capath: certificate data
          certfile: /some/certfile
          keyfile: /some/key
    my-ws-1:
          bind: 0.0.0.0:8080
          type: ws
  timeout-disconnect-delay: 2
  auth:
    plugins: ['auth.anonymous'] 
    allow-anonymous: true / false
    password-file: /some/passwd_file

备注

在 Owntracks 中使用内置 MQTT 代理服务器,请先打开 Owntracks 客户端 —— Configuration Management —— 将 mqttProtocolLevel的值变更为 4


自建代理服务器

使用 Owntracks MQTT 代理服务器,请先打开 Owntracks 客户端 —— Configuration Management —— 将 mqttProtocolLevel的值变更为 4

mqtt:
  broker: 服务器的 IP 地址
  client_id: HA 使用的用户 ID
  keepalive: 信息发送间隔,单位秒。默认 60
  username: 用户名
  password: 密码
  protocol: 协议版本,3.1.1  3.1
  certificate: MQTT 证书路径(如果有)
  tls_insecure: 是否验证正式
  tls_version: tls 版本,auto1.01.11.2

全部参数均为可选参数。


公共代理服务器

开放的 MQTT 代理服务器,使用时注意保护隐私。

mqtt:
  broker: rest.mosquittp.org
  port: 1883  8883
  certificate: 证书路径(如果有)

二元传感器

binary_sensor:
  - platform: mqtt
    name: "Window Contact Sensor"
    state_topic: "home-assistant/window/contact"
    payload_on: "ON"
    payload_off: "OFF"
    availability_topic: "home-assistant/window/availability"
    payload_available: "online"
    payload_not_available: "offline"
    qos: 0
    device_class: opening
    value_template: '{{ value.x }}'

变量说明:

  • name (可选): 名称,英文。默认 MQTT Binary Sensor.
  • state_topic (必填): 获取设备值的MQTT topic
  • payload_on (可选): 代表开启的负载类型,默认 ON
  • payload_off (可选): 代表开启的负载类型,默认 OFF
  • availability_topic (可选): 获取设备 birth&LWT 信息的 MQTT topic。如未指明,则设备的可用状态默认为 available;如指明,则设备的可用状态默认为 available
  • payload_available (可选): 指代设备在线状态的值,默认为 online.
  • payload_not_available (可选): 指代设备离线状态的值,默认为 offline.
  • qos (可选): 最大 QoS 值,默认 0
  • device_class (可选): 指定数据类型,用以生成不同图标
  • value_template (可选): 定制数据生成的模板

传感器

sensor:
  - platform: mqtt
    state_topic: "owntracks/tablet/tablet"
    name: "Battery Tablet"
    unit_of_measurement: "%"
    value_template: '{{ value_json.batt }}'

变量说明:

  • name (可选): 名称,英文。默认 MQTT Binary Sensor.
  • state_topic (必填): 获取设备值的MQTT topic
  • qos (可选): 最大 QoS 值,默认 0
  • value_template (可选): 定制数据生成的模板
  • unit_of_measurement (可选): 单位
  • expire_after (可选): 数据有效时间,以秒为单位,默认 0
  • force_update (可选): 强制更新数据,默认 false

lock:
  - platform: mqtt
    name: Frontdoor 
    state_topic: "home-assistant/frontdoor/"
    command_topic: "home-assistant/frontdoor/set"
    payload_lock: "LOCK"
    payload_unlock: "UNLOCK"
    optimistic: false
    qos: 1
    retain: true
    value_template: '{{ value.x }}'

变量说明:

  • name (可选): 名称,英文。默认 MQTT Binary Sensor
  • state_topic (必填): 获取设备值的MQTT topic
  • payload_lock (可选): 代表设备锁上的值,默认 LOCK
  • payload_unlock (可选): 代表设备开锁的值,默认 LOCK
  • optimistic (可选): 设备是否在理想模式,如果 state_topic 没有定义,默认为 true
  • qos (可选): 最大 QoS 值,默认 0
  • retain (可选): 信息发布是否带 retain 标记
  • value_template (可选): 定制数据生成的模板

开关

switch:
  - platform: mqtt
    name: "Bedroom Switch"
    state_topic: "home/bedroom/switch1"
    command_topic: "home/bedroom/switch1/set"
    availability_topic: "home/bedroom/switch1/available"
    payload_on: "ON"
    payload_off: "OFF"
    optimistic: false
    qos: 0
    retain: true

变量说明:

  • name (可选): 名称,英文。默认 MQTT Switch
  • state_topic (必填): 获取设备值的MQTT topic
  • command_topic (必填): The MQTT topic to publish commands to change the switch state.
  • availability_topic (可选): 获取设备 birth&LWT 信息的 MQTT topic。如未指明,则设备的可用状态默认为 available;如指明,则设备的可用状态默认为 available
  • payload_on (可选): 代表开启的值,默认 ON
  • payload_off (可选): 代表开启的值,默认 OFF
  • payload_available (可选): 代表设备在线状态的值, 如 'online',默认为 ON
  • payload_not_available (可选): 代表设备离线状态的值, 如 'offline',默认为 OFF
  • optimistic (可选): 设备是否在理想模式,如果 state_topic 没有定义,默认为 true
  • qos (可选): 最大 QoS 值,默认 0
  • retain (可选): 信息发布是否带 retain 标记
  • value_template (可选): 定制数据生成的模板