分为三个部分

  • 发现设备：设备向 homeassistant/<类型>/<ID>/config 发布保留的 JSON 配置，HA 监听该前缀，自动注册实体；
  • 接收信息：设备将状态数据（如温度）发布到配置中声明的 state_topic，HA 订阅该主题并用 value_template 解析具体字段；
  • 控制设备：HA 向配置中声明的 command_topic 发送指令（如 "ON"），设备订阅该主题接收命令，执行后可回传状态到 state_topic 以同步界面。

1. MQTT 发现机制：设备发布配置，HA 自动创建实体

设备向 homeassistant/sensor/bedroom_env/config（保留消息）发布：

{
  // 实体在 Home Assistant UI 中显示的名称
  "name": "Bedroom Temperature",

  // 传感器类型，决定默认单位、图标和行为（如 temperature → °C，motion → 布尔）
  "device_class": "temperature",

  // HA 将订阅此主题以接收状态数据；由设备后续上报
  "state_topic": "sensors/bedroom/state",

  // 从 state_topic 的 payload（字符串）中提取实际值；
  // value_json 自动解析 JSON，.temperature 表示取 JSON 中的 "temperature" 字段
  "value_template": "{{ value_json.temperature }}",

  // 显示单位（可省略，device_class 会自动填充）
  "unit_of_measurement": "°C",

  // 全局唯一 ID，用于 HA 重启后识别同一实体、支持重命名
  "unique_id": "bedroom_temp_01",

  // 声明所属设备，实现多实体归组到一个设备卡片
  "device": {
    // 设备唯一标识（数组），所有使用相同 identifiers 的实体归为一组
    "identifiers": ["bedroom_sensor_01"],
    // 设备在 UI 中显示的名称
    "name": "Bedroom Environment Sensor"
  }
}

→ HA 监听 homeassistant/#，收到后自动创建传感器实体。

2. 传感器上报数据：设备发布状态

设备向 sensors/bedroom/state（即上述 state_topic）发布：

{
  // 温度值，对应 discovery 中 value_template 提取的字段
  "temperature": 23.5,
  // 湿度值，另一个传感器实体用 "{{ value_json.humidity }}" 提取
  "humidity": 48.2
}

→ HA 同时监听此主题，两个传感器分别用各自的 value_template 解析出温度和湿度。

3. 被控设备：通过发现声明控制接口

设备向 homeassistant/switch/pump/config（保留消息）发布：

{
  // 开关在 UI 中的名称
  "name": "Garden Pump",

  // HA 发送控制指令的目标主题；设备必须订阅此主题
  "command_topic": "actuators/pump/set",

  // 设备上报当前状态的主题；HA 订阅此主题以同步 UI
  "state_topic": "actuators/pump/state",

  // HA 发送“开”时使用的字符串（可自定义为 "1"、"true" 等）
  "payload_on": "ON",

  // HA 发送“关”时使用的字符串
  "payload_off": "OFF",

  // 设备回传“开”状态时应使用的字符串（需与设备实际发送一致）
  "state_on": "ON",

  // 设备回传“关”状态时应使用的字符串
  "state_off": "OFF",

  // 唯一 ID，用于实体持久化
  "unique_id": "pump_01",

  // 所属设备信息（可选）
  "device": {
    "identifiers": ["garden_actuator_01"],
    "name": "Garden Actuator"
  }
}

控制流程：

  • 用户点击开关 → HA 向 actuators/pump/set 发 "ON"
  • 设备收到后执行，并向 actuators/pump/state 发 "ON"
  • HA 收到状态更新 UI

参考文章：
1、深入理解Home Assistant MQTT：配置、自动化、发布等 - MQTT中文站
2、Home Assistant中使用MQTT窗帘/卷帘的示例配置 - MQTT中文站

赏