Home Assistant（HA）+ MQTT 自定义服务器 的典型设备接入方式，总结 需要上报（Publish） 与 需要订阅（Subscribe） 的主题，以及常见字段内容。

下面按 Home Assistant（HA）+ MQTT 自定义服务器 的典型设备接入方式，总结 需要上报（Publish） 与 需要订阅（Subscribe） 的主题，以及常见字段内容。

✅ 一、MQTT 设备接入 Home Assistant 的两种方式

Home Assistant 支持两种 MQTT 设备模式：

方式 A：使用 MQTT Discovery（推荐）

设备自动被 HA 发现，无需手动配置。

方式 B：手动配置实体（不推荐）

需要用户在 configuration.yaml 写配置。

下面主要讲方式 A（MQTT Discovery），也是你使用自定义 MQTT 服务器时最常用的。

✅ 二、MQTT Discovery 主题结构（重要）

Home Assistant 的自动发现主题格式为：

homeassistant/<component>/<object_id>/config

例如：

homeassistant/sensor/temp_sensor/config
homeassistant/light/desk_light/config

当设备发布 config 消息后，HA 会自动创建实体。

✅ 三、设备需要：发布（Publish）的主题

下表总结一个典型设备接入 HA（使用 MQTT Discovery）需要的上报主题。

⭐ 1. 设备“配置”主题（必须）

设备启动时向 HA 发布一个 “配置消息”，用来告诉 HA 如何创建实体。

例：一个温度传感器：

主题：

homeassistant/sensor/room_temperature/config

消息内容(JSON)：

{
"name": "Room Temperature",
"uniq_id": "dev123_temp",
"stat_t": "mydevice/room/temperature",
"unit_of_meas": "°C",
"dev_cla": "temperature",
"val_tpl": "{{ value_json.temperature }}",
"device": {
"ids": ["dev123"],
"name": "My Device",
"mf": "YourCompany",
"mdl": "ESP32"
}
}

⚠️ HA 只有在收到 config 之后才会显示实体！

⭐ 2. 状态上报主题（stat_t）

例如：

mydevice/room/temperature

消息：

{
"temperature": 25.3
}

状态主题格式完全可自定义，只要在 config 里声明即可。

⭐ 3. 可选：设备状态（online/offline）

主题（固定约定）：

mydevice/status

payload：

online

或

offline

✅ 四、设备需要：订阅（Subscribe）的主题

如果你的设备是“可控设备”（如 light、switch），就必须订阅 HA 下发的控制指令。

常见结构如下：

⭐ 1. 控制主题（cmd_t）

例如一个灯：

设备在 config 中约定：

{
"cmd_t": "mydevice/light/desk/set",
"stat_t": "mydevice/light/desk/state"
}

那么设备需要订阅：

mydevice/light/desk/set

HA 会发布 payload，例如：

开灯

ON

关灯

OFF

对于调光灯：

{"state": "ON", "brightness": 180}

✅ 五、总结：常用组件的订阅/发布主题清单

### 🟦 1. Sensor（传感器）

📌 设备发布：

📌 设备订阅：

无（Sensor 不可控）

### 🟦 2. Binary Sensor（开关量传感器）

📌 发布：

homeassistant/binary_sensor/<id>/config
mydevice/<id>/state

payload:

ON 或 OFF

### 🟦 3. Switch（开关设备）

📌 发布：

homeassistant/switch/<id>/config
mydevice/<id>/state

📌 订阅：

mydevice/<id>/set

### 🟦 4. Light（灯）

📌 发布：

homeassistant/light/<id>/config
mydevice/light/<id>/state

📌 订阅：

mydevice/light/<id>/set

payload 示例：

{"state":"ON","brightness":128}

### 🟦 5. Cover（窗帘、电动门）

📌 发布：

homeassistant/cover/<id>/config
mydevice/cover/<id>/state

📌 订阅：

mydevice/cover/<id>/set

payload:

OPEN / CLOSE / STOP

✅ 六、通用 MQTT Discovery 配置模板（你可以直接用）

homeassistant/<component>/<object_id>/config

JSON 中常用字段（最重要）：