HomeAssistant安装与基本使用

[! danger] 注意：本文记录我搭建HomeAssistant折腾的过程，基础内容省略，不予提示

一、HomeAssistant介绍

HomeAssistant 是一款开源的智能家居平台，支持多种设备和协议，用户可以通过 Web 界面或 App 进行控制。它提供自动化规则、可视化界面，并支持 MQTT、Zigbee、Z-Wave 等多种集成方式，适用于 DIY 智能家居方案。

二、HomeAssistant安装（docker）

这里使用Docker 安装：

拉取镜像：

docker pull homeassistant/home-assistant:stable

安装：

 docker run -d --name="homeassistant" -v /root/data/docker_data/homeassistant/config:/config -v /etc/localtime:/etc/localtime:ro -p 8123:8123 homeassistant/home-assistant:stable

安装完成后在对应的 8123端口打开网页，如下：

然后进行相应的配置（建立账号，选择地区），完成后界面如下：

注意打开高级模式：

三、集成MQTT

下面集成MQTT模块，用于接入MQTT协议的设备：

进入设置->设备与服务：

添加MQTT集成：

我这里对接至我自己搭建的EMQX，搭建过程可参考：EMQX文档

输入连接参数，可参考：Connect with Home Assistant

成功后如下：

点击MQTT模块，在配置选项中进行测试：

监听hello主题，并在hello主题发消息测试：

可以接受到，则配置成功

四、设备接入

在 HomeAssistant 配置好 MQTT 后，可以接入支持 MQTT 协议的设备，例如 ESP32、ESP8266、Sonoff 设备等。以下是接入 MQTT 设备的基本流程：

1. 设备端配置 MQTT

确保你的设备支持 MQTT，并正确连接到 MQTT 服务器（如 EMQX）。以 ESP32 设备为例，可以使用 PubSubClient 库（Arduino 开发）或 ESP-MQTT（ESP-IDF 开发）来连接 MQTT 服务器，并发布或订阅消息。

2. HomeAssistant 配置设备

设备自动发现

设备通过 MQTT 发布数据后，需要在 HomeAssistant 中订阅该主题并创建实体。可以使用 configuration.yaml 进行手动配置，也可以通过 MQTT 发现功能自动识别。这里我们使用HomeAssistant的自动获取设备的功能，我们可以在MQTT设置->配置MQTT选项里找到对应的开关，默认应该是开着的：

设备需要通过 MQTT 发送配置消息，HA会自动识别并添加设备，例如：

设备发送如下 JSON 到 homeassistant/sensor/esp-temp-01/config 主题：

json

{
    "unique_id": "esp-temp-01",
    "name": "温度传感器-01",
    "icon": "mdi:thermometer",
    "state_topic": "home/sensor/esp-temp-01/state",
    "json_attributes_topic": "home/sensor/esp-temp-01/attributes",
    "unit_of_measurement": "℃",
    "device": {
        "identifiers": "ESP32-01",
        "manufacturer": "若甫科技有限公司",
        "model": "HA",
        "name": "ESP32-01",
        "sw_version": "1.0"
    }
}

我这里使用MQTTX模拟设备发送：

对应homeassistant平台显示如下：

可以看到设备详细信息：

细节补充：

json里的字段说明如下：

字段	说明
`unique_id`	设备的唯一 ID，HomeAssistant 用它来区分设备，必须唯一
`name`	设备在 HomeAssistant 中显示的名称
`icon`	设备图标（这里是温度计）
`state_topic`	设备状态数据的 MQTT 主题，HomeAssistant 通过订阅这个主题获取设备的最新状态
`json_attributes_topic`	设备的额外属性（如电压、电池状态）发布的主题，HomeAssistant 会自动读取这些属性
`unit_of_measurement`	传感器单位，这里是摄氏度 `℃`
`device`	设备的基本信息
`identifiers`	设备唯一标识（如 ESP8266 的 MAC 地址或者自定义 ID），用于设备管理
`manufacturer`	设备制造商信息
`model`	设备型号
`name`	设备名称，HomeAssistant 设备管理界面会显示
`sw_version`	设备固件版本

其次、HomeAssistant 设备自动发现的 MQTT 主题一般格式如下：

homeassistant/{component}/{unique_id}/config

{component}：设备类型，如 sensor（传感器）、switch（开关）
{unique_id}：设备唯一标识，建议使用设备类型+编号，例如 esp-temp-01

示例：

homeassistant/sensor/esp-temp-01/config

设备需要定期发送状态数据，格式建议如下：

home/{设备类型}/{设备ID}/state

如果设备还有额外的属性（如信号强度、电池电压等），可以发送到 json_attributes_topic，格式建议如下：

home/{设备类型}/{设备ID}/attributes

设备上报属性：

设备上报属性只需要在给设定的state_topic主题发送数值：

例如，我这里给刚才注册的设备的home/sensor/esp32/temp/01/state发送33

对应平台的值也变为：33

多个同种设备：

如果我们要注册多个同种设备，只需要保持注册信息里的device 不变，例如：

再添加一个温度传感器：

设备发送如下 JSON 到 homeassistant/sensor/esp-temp-02/config 主题：

json

{
    "unique_id": "esp-temp-02",
    "name": "温度传感器-02",
    "icon": "mdi:thermometer",
    "state_topic": "home/sensor/esp-temp-02/state",
    "json_attributes_topic": "home/sensor/esp-temp-02/attributes",
    "unit_of_measurement": "℃",
    "device": {
        "identifiers": "ESP32-01",
        "manufacturer": "若甫科技有限公司",
        "model": "HA",
        "name": "ESP32-01",
        "sw_version": "1.0"
    }
}