设备及服务 - MQTT

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

代理服务器

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

内置代理服务器

Home Assistant 内置 MQTT 代理服务器（HBMQTT），以下为该代理服务器信息：

使用内置服务器，仅需在配置文件 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 版本，auto、1.0、1.1、1.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 (可选): 定制数据生成的模板