Skip to content
DroidFlight Wiki

智能家居 30 分钟上手 (Quick Start)

目标

30 分钟，从一台全新的树莓派到一个能控制小米智能插座 + 用人体传感器自动开关灯的 Home Assistant。本路径全程本地优先，不依赖任何云端。

物料清单 (≈ ¥1,200)

物料型号价格备注
主控树莓派 5 (8GB)¥700包含电源、SD 卡、散热
存储128 GB NVMe SSD + 载板¥200SD 卡易坏，强烈建议换 SSD
Zigbee 网关SONOFF ZBDongle-E (USB)¥80EFR32MG21 芯片，性价比高
智能插座小米米家智能插座 3 (ZNCZ05CM)¥50支持 MIoT 协议
人体传感器小米/Aqara 人体传感器 (RTCZCGQ11LM)¥80Zigbee 协议

步骤 1：安装 Home Assistant (10 min)

方案 A：树莓派 + SSD

Terminal window
# 1. 在 Mac / Linux 上下载并烧录 HAOS 镜像
#    https://github.com/home-assistant/operating-system/releases
#    选 haos_rpi5-64.img.xz


# 2. 用 Raspberry Pi Imager 烧录到 SSD
#    烧录时按 Ctrl+Shift+X 打开高级选项：设置 SSH、Wi-Fi、时区


# 3. 把 SSD 接到 Pi 5，插电启动
#    等待 5 分钟，从路由器后台找到 `homeassistant.local` 设备

方案 B：Linux 服务器 / NAS

Terminal window
# 在 Ubuntu 24.04 上跑 HA Container
sudo apt install -y docker docker-compose
mkdir ~/ha && cd ~/ha
curl -O https://raw.githubusercontent.com/home-assistant/supervised-installer/main/alternative-installs/docker-compose.yml
docker compose up -d

打开浏览器访问 http://homeassistant.local:8123 完成初始设置（创建账号、设置时区、关掉遥测）。

步骤 2：接入第一个小米插座 (5 min)

走小米账号 OAuth，最简单：

  1. 设置 → 设备与服务 → 添加集成
  2. 搜索 Xiaomi Miio 或 Xiaomi MIoT
  3. 用小米账号扫码登录
  4. HA 自动发现账号下所有支持 MIoT 的设备
  5. 重启 HA 一次以加载 entity

步骤 3：接入 Zigbee 人体传感器 (10 min)

[人体传感器] ──Zigbee──▶ [SONOFF ZBDongle-E] ──USB──▶ [HA]
  1. 设置 → 设备与服务 → 添加集成 → ZHA
  2. 选 SONOFF ZBDongle-E 作为协调器
  3. 把人体传感器按住 reset 3 秒进入配对模式
  4. HA 自动识别并创建 entity binary_sensor.<id>_occupancy

步骤 4：写第一个自动化 (5 min)

设置 → 自动化与场景 → 创建自动化 → 用 UI 编辑器：

# 完整 YAML 视图
alias: 客厅有人自动开灯
trigger:
  - platform: state
    entity_id: binary_sensor.living_room_motion
    to: "on"
condition:
  - condition: sun
    after: sunset
    after_offset: "-00:30:00"
action:
  - service: switch.turn_on
    target:
      entity_id: switch.living_room_lamp

效果：太阳下山后，检测到客厅有人移动 → 自动开灯；无人 5 分钟后自动关灯（在自动化里再加一个 trigger from on to off 持续 5 min）。

步骤 5：手机端 (2 min)

  • iOS：App Store 搜 “Home Assistant”，登录后会自动发现 http://homeassistant.local:8123
  • Android：Play Store / F-Droid 同样
  • 配置 → Companion App → 启用 传感器（位置、蓝牙）以支持”回家自动开空调”等场景

⛔ 别这么做 (Anti-patterns)

经验证的坑 —— 跳过 = 至少浪费半天，严重的烧板 / 锁机。

❌ 错误做法💥 后果⚠️ 风险范围
不要在断电前直接拔 Valetudo 改装中的 USB-TTL刷机中途断电 = 变砖。先 dmesg 确认串口没掉再操作。🟡智米扫拖一体 / Roborock S5 Max
不要把米家设备 token 上传到任何第三方云token = 设备控制权，泄漏 = 任何人可远程开门。🔴所有米家 / Aqara 设备
不要在生产 HA 配置里直接编辑 configuration.yaml 后 check_config 不通过就 reload错的 reload 会让 HA 启动失败 → 所有自动化停摆。用 configuration.yaml 备份 + git 版本化。🟢Home Assistant
不要给 Frigate 摄像头内网用 admin/admin 默认密码RTSP / ONVIF 默认账号 = 局域网裸奔。先改密码。🟡海康 / 大华摄像头
不要在 ESPHome 设备上直接 OTA 升级到主版本 (major)主版本常改 NVS 分区。OTA 升级后启动失败 = 拆壳刷机。先 flash USB 一次。🟡ESP32-S3 语音卫星 / 智能开关
不要在智能家居自动化里写死设备 IPDHCP 重启后 IP 变 = 自动化失效。用 hostname / mDNS / 静态租约。🟢Home Assistant / Hubitat
不要在 Matter 设备首次配对时关掉手机蓝牙Matter 配对 = BLE → WiFi handover，全程需要蓝牙。🟢Aqara M3 / Apple Home

🚨 风险总览 (Risk Matrix)

风险等级含义例子
🟢 低改错可回滚 / 几分钟恢复pip 全局装包、DHCP IP 写死
🟡 中需要重新刷机 / 重装 / 1-2 小时恢复装错 ROS 2 版本、没 OTA 升级看版本
🔴 高不可逆 / 烧板 / 安全风险电池反接、micro-ROS 没看门狗、刷机中途断电

下一步

📋 复现条件

类别必备可选 / 备注
硬件树莓派 5 8GB (或任意 Linux x86 小主机) · 32GB SD 卡 (A2 等级) · 1× USB 3.0 口RealSense / Zigbee 适配器按需
操作系统HAOS 14.x 或 Debian 12 BookwormUbuntu 24.04 / macOS 14 也可
软件版本Home Assistant 2024.10+ · Python 3.12Core 模式需自备 venv
网络2.4 GHz Wi-Fi (米家 / Zigbee 必须) · 路由器支持 mDNS公网 IP 仅远程访问需要
账号米家 App 已绑定 ≥ 1 个智能设备苹果账号 (HomeKit 桥接)
时间初次装机 30 min · 配 1 个米家设备 5 min跑通第一个自动化 +5 min
难度⭐⭐ 入门无 Linux 基础也能完成
前置知识能用 SSH 登录 Linux · 会看 yaml 报错不会可参考 HA 文档

常见问题