Question

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 版本，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 (可选): 定制数据生成的模板

---