WiFi 与 Bluetooth LE 设备接入

WiFi 设备

WiFi 是最常见的智能家居设备协议——灯泡、插座、摄像头、传感器、空气净化器等几乎所有设备都有 WiFi 版本。Home Assistant 接入 WiFi 设备有几种方式：

方式一：厂商原生集成（最佳）

很多厂商的设备在 Home Assistant 官方集成列表里：

厂商	集成名	特点
飞利浦 Hue	`hue`	局域网直连 Hue Bridge，不走云
小米 / Aqara	`xiaomi_miot`	MIoT 协议，支持大多数小米设备
SONOFF	`sonoff` / `tasmota`	局域网 API 或刷 Tasmota 固件本地控制
TP-Link / Kasa	`tplink`	局域网 API
Yeelight	`yeelight`	局域网 UDP 协议
Xiaomi Mijia (旧版)	`mijia_cloud`	需要米家账号，走云
Amazon Alexa	`alexa_media`	Alexa 设备的媒体控制
Google Home	`google_home`	Google Home / Nest 的媒体和设备控制

添加路径：Settings → Devices & services → Add integration → 搜索厂商名。

方式二：刷 Tasmota 固件

很多 SONOFF、BlitzWolf、Kogan 等设备可以刷 Tasmota 固件（开源），刷完后设备开放 Mqtt 和 HTTP API，完全本地控制：

优点：本地控制、OTA 更新、可定制
缺点：需要动手刷固件（适合极客）

刷好 Tasmota 后，Home Assistant 用 MQTT 集成就能接。

方式三：ESPHome DIY

如果设备支持 ESP8266/ESP32（绝大多数 WiFi 设备的芯片），可以用 ESPHome 自己写固件——完全本地、可定制、和 Home Assistant 深度集成。详见 ESPHome 页面。

Bluetooth LE 设备

蓝牙 LE（BLE）是低功耗短距离协议，适合电池供电的小设备（温湿度传感器、门锁、体重秤）。Home Assistant 内置了 BLE 扫描器。

Home Assistant 内置 BLE 集成

Home Assistant OS 在支持的硬件上自动开启 BLE 扫描：

树莓派 4/5、Home Assistant Green（内置蓝牙）
USB 蓝牙适配器（Container 部署时需要 USB 透传）
ESPHome 代理设备（远程位置的蓝牙设备可以通过 ESPHome 接入）

Home Assistant 内置支持的 BLE 设备：

设备	集成	功能
Mi Band / 小米手环	`xiaomi_ble`	步数、心率、电量
Aqara 温湿度传感器	`xiaomi_ble`	温度、湿度、气压
Govee 灯光	`govee_btled`	颜色控制
一些体重秤	`xiaomi_ble` / 其他	体重、体脂
BlueMaestro 温度/湿度	`bluemaestro`	温湿度数据
RuuviTag 传感器	`ruuvitag`	环境监测

BLE 扫描范围

蓝牙扫描受限于：

树莓派内置蓝牙：室内 5~10 米
USB 蓝牙适配器：8~15 米
信号被墙壁、金属干扰会下降

如果家里大、设备分散，可以用 ESPHome 代理——在远程放一个 ESP32 设备作为蓝牙扫描代理，把扫描到的数据通过 WiFi 传给 Home Assistant。

Container 部署的 BLE 问题

Docker 部署时，Home Assistant 容器默认访问不到蓝牙适配器。解决方案：

在宿主机安装 BlueZ：apt install bluez
Docker run 时加 --net=host -v /run/dbus:/run/dbus:ro 和 --cap-add=NET_ADMIN
Home Assistant 就能访问宿主机的蓝牙

或者更简单——在 Home Assistant OS 上跑，BLE 直接就能用。

MQTT：万能中间件

MQTT 是 Home Assistant 的瑞士军刀——任何支持 MQTT 的设备都能接入，不管它走的是 WiFi、Zigbee 还是蓝牙。

Home Assistant 有两种 MQTT 使用方式：

内置 Mosquitto Broker（Home Assistant OS）

Settings → Apps → 搜索 Mosquitto（官方推荐的 MQTT Broker）
安装并启动
Settings → Devices & services → Add integration → MQTT → Configure
默认自动连接到安装的 Mosquitto

手动配置

如果已经有 Mosquitto（跑在 NAS、路由器等），MQTT 集成可以连外部 Broker：

mqtt:
  broker: 192.168.1.100
  port: 1883
  username: user
  password: pass

MQTT 设备在 Home Assistant 里的定义

通过 mqtt: platform 在 YAML 里定义 MQTT 实体：

mqtt:
  switch:
    - name: "车库门"
      command_topic: "home/garage/door"
      payload_on: "open"
      payload_off: "close"
      state_topic: "home/garage/door/state"
      state_on: "open"
      state_off: "closed"

这段 YAML 会创建一个 switch.garage_door 实体，订阅 home/garage/door/state 主题获取状态，往 home/garage/door 主题发送命令。