Skip to content
DroidFlight Wiki

Aqara + HomeKit 桥接

概念速览

  • Aqara：绿米联创的小米生态链品牌，主打 Zigbee 全屋方案；与米家深度兼容
  • HomeKit：Apple 智能家居协议；iOS 用户可零代码接入
  • Matter：CSA 主导的跨生态协议（详见 Matter & Thread）

网关选型

网关ZigbeeThreadMatter ControllerHomeKit Bridge价格推荐
Aqara M1S (Gen 2)✓❌❌✓¥300入门
Aqara M2✓❌❌✓¥400米家深度
Aqara M3 (2024)✓✓✓✓¥700⭐⭐⭐⭐⭐
Aqara G410 门铃✓✓✓✓¥1500门锁 + 视频
Aqara G350 Pro✓✓✓✓¥3000旗舰

三种 HA 接入路径

路径 A：Aqara Cloud (最简单)

[Aqara 传感器] ──Zigbee──▶ [Aqara M3] ──Cloud──▶ [HA Aqara 集成]
  1. HA 添加 “Aqara” 集成
  2. 用 Aqara App 账号登录
  3. HA 自动同步所有 Aqara 子设备
  4. 优点：零配置；缺点：依赖云端

路径 B：ZHA 直连 (推荐)

[Aqara 传感器] ──Zigbee──▶ [Aqara M3 / SONOFF] ──USB/网络──▶ [HA ZHA]
  1. 在 Aqara M3 上启用 “Developer Mode”（App → 中枢设置 → 开发者）
  2. 拿到 M3 的 LAN 调试端口
  3. HA 的 ZHA 集成添加 M3 作为协调器
  4. 重新配对所有传感器
  5. 优点：零云端，延迟 < 100 ms；缺点：需重配设备

路径 C：Matter 桥接 (面向未来)

[Aqara 传感器] ──Zigbee──▶ [Aqara M3] ──Matter──▶ [HA Matter 集成]
  1. M3 启用 Matter Bridge 功能
  2. HA 添加 “Matter” 集成
  3. 扫描 M3 提供的 Matter 配对码
  4. 优点：未来兼容 Apple Home / Google Home / SmartThings；缺点：M3 Matter 实现仍有 bug

典型传感器集成

传感器生态一览

传感器协议触发自动化示例
人体传感器 (RTCZCGQ11LM)Zigbee运动 / 光照走廊夜间灯
门窗传感器 (MCCGQ11LM)Zigbee开 / 关门开 → 玄关灯亮 30 秒
温湿度传感器 (WSDCGQ11LM)Zigbee温度 / 湿度湿度 > 70% → 开除湿机
水浸传感器 (SJCGQ11LM)Zigbee水浸厨房漏水 → 推手机 + 关水阀
烟雾报警器 (JTYJ-GD-01LM)Zigbee烟雾触发 → 全屋通知 + 通风
智能墙壁开关 (QBKG04LM)Zigbee按键双击 → 关闭所有灯
智能窗帘电机 (ZNCLDJ11LM)Zigbee位置日落 → 关窗帘

人体传感器 + 光照自动化

alias: 走廊有人天黑自动开灯
trigger:
  - platform: state
    entity_id: binary_sensor.corridor_motion
    to: "on"
condition:
  - condition: numeric_state
    entity_id: sensor.corridor_illuminance
    below: 50
action:
  - service: light.turn_on
    target:
      entity_id: light.corridor_ceiling
    data:
      brightness: 100
      color_temp: 300
  - delay: "00:00:30"
  - service: light.turn_off
    target:
      entity_id: light.corridor_ceiling

HomeKit ↔ HA 双向桥

Apple 用户最关心的部分。

HA → HomeKit (暴露 HA 设备给 iOS)

  1. HA 添加 “HomeKit Bridge” 集成
  2. 选择要暴露的 entity（灯、开关、传感器）
  3. HA 生成一个 HomeKit 配对码
  4. iOS 家庭 App → 添加设备 → 扫描配对码
  5. 设备出现在 iOS 家庭中，可用 Siri 控制

HomeKit → HA (把 HomeKit 设备反向接入)

  1. HA 添加 “HomeKit Device” 集成
  2. iOS 家庭 App 把设备”暴露”给 HA
  3. HA 中以 entity 形式出现
  4. 适用场景：把 HomeKit 专用配件（如某些智能门锁）拉入 HA 统一自动化

调试技巧

📋 复现条件

类别必备可选 / 备注
硬件Aqara M2 / M3 中枢 1 台 · Zigbee 设备 ≥ 1 个 · iOS 16+ 设备Apple HomePod / TV 作 Matter Border Router
操作系统Home Assistant 2024.10+ (HAOS / Container 都可)iOS 16 / Android 13+
软件版本Aqara Home 4.x · Apple Home 17.xAqara Studio 调试工具
网络2.4 GHz Wi-Fi · 路由器开启 mDNS / BonjourIPv6 (Matter 桥接需要)
账号Aqara 账号 (国区 / 美区) · 苹果 Apple IDGoogle / Alexa 账号 (跨生态)
时间配对 1 个传感器 10 min · HA 接入 5 min · HomeKit 桥接 10 minMatter 桥接额外 +15 min
难度⭐⭐⭐ 进阶中间步骤会断流
前置知识HA 30 分钟上手 · Matter 协议基础苹果家庭自动化

⛔ 别这么做 (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 没看门狗、刷机中途断电

参考资料