Home Assistant 集成乐橙摄像头：全屋智能联动、语音控制与场景自动化（实战）

Home Assistant 集成乐橙摄像头：全屋智能联动、语音控制与场景自动化（实战）

---

我家装了乐橙门口机，App 里能预览、能告警，Home Assistant 里却只有一盏「离线」的灯。直到搞清一件事：ONVIF 只能拉局域网流，动检、人形、上下线这些「云能力」在 OpenAPI 里------不注册乐橙开放平台、不把设备绑进开发者账号，HA 永远只是播放器，不是全屋智能的传感器节点。

---

为什么 HA 玩家值得走「开放平台」而不是只刷 RTSP

Home Assistant 的核心是 实体（Entity）+ 自动化（Automation）。乐橙摄像头若只当「一路 RTSP/ONVIF」，你通常只能：

• 看直播；
• 偶尔抓图。

但全屋智能真正想要的是：

需求	仅 ONVIF/RTSP	乐橙 OpenAPI / 官方 HA 组件
在线/离线状态	靠 ping，不准	deviceStatus、推送 online/offline
人形/动检事件	难统一	告警消息、videoMotion 等
隐私模式、夜视	App 里改	组件或 OpenAPI 配置
语音「看门口」	需自建	HA camera + 助手实体
联动开灯/推手机	无事件源	Webhook / MQTT 桥接

乐橙开放平台面向 要把乐橙设备接进自己系统 的开发者；对极客用户，平台提供了 Home Assistant 集成组件 （基于 OpenAPI 的 Python 组件），并支持你用 **setMessageCallback** 把告警推到自建服务，再转 HA。

边界先说清：

• 配网、本地局域网预览：仍可用 App / OpenSDK；
• HA 云集成 ：设备须在 开发者账号资产池 （与 listDeviceDetailsByPage 能查到一致）；
• 接口 ：用现行 OpenAPI，勿引用 「旧版本协议、不再维护」栏目；列表用 **listDeviceDetailsByPage**，不用停维护的 deviceList。

推荐架构（极客版）

乐橙 IPC → 乐橙云 → OpenAPI
              ↓
    ┌─────────┴──────────┐
    │ Imou HA 组件（HACS） │ → camera / switch / binary_sensor
    └─────────┬──────────┘
              ↓
    可选：Webhook 桥接 ← setMessageCallback（alarm）
              ↓
    Home Assistant Automations / 语音助手

---

1. 开放平台准备（约 15 分钟）

① 乐橙开放平台注册 → 创建应用 → 记录 appId、appSecret
② 设备配网并在 App/控制台/bindDevice 绑定到开发者主账号
③ listDeviceDetailsByPage 验收：deviceId 出现且 online
④ 记下 API 域名（国内常用 openapi.lechange.cn）

踩坑 A：HA 里填了密钥但设备列表空------设备在私人 App 号下，不在开发者账号。换主账号绑定或控制台添加，直到分页接口能查到。

踩坑 B ：appSecret 写进 configuration.yaml 并提交 Git------我们改为 **secrets.yaml + 权限 600**，且仅 HA 主机本地保存。

2. 安装 Imou Home Assistant 组件

平台提供开源 Imou Home Assistant 组件（Imou-OpenPlatform 组织下），推荐 HACS 安装：

HACS → Integrations → 搜索 Imou Life → 下载
重启 Home Assistant
设置 → 设备与服务 → 添加集成 → Imou Life

配置项（UI 表单）：

字段	说明
App Id	控制台应用详情
App Secret	同上，勿泄露
API Domain	国内选 openapi.lechange.cn（与区域匹配，填错常见连接失败）

提交成功后，集成页应出现账号下 camera、binary_sensor、switch 等实体------具体以设备能力集为准（PTZ 机还会有云台相关实体）。

无 HACS 时 ：下载组件压缩包，将 imou 文件夹放入 HA 的 custom_components/imou，重启后同样「添加集成」。

3. 验收：实体与直播

集成完成后在 开发者工具 → 状态 搜索 camera.imou：

# 示例实体（名称因设备而异）
camera.imou_doorbell
binary_sensor.imou_doorbell_motion_alarm
switch.imou_doorbell_motion_detect

Dashboard 添加 Picture Entity Card 或 Live View，确认能出画。若转圈：

□ 设备 online（listDeviceDetailsByPage）
□ API 域名正确
□ 账号下直播/接口配额未用尽（控制台「我的资源」）
□ 组件日志无 TK1002 / sign 错误

4. 场景自动化一：动检开灯

组件暴露 **binary_sensor**（如移动侦测）后，可直接写 HA 自动化：

automation:
  - id: imou_porch_light_on
    alias: 门口动检开灯
    mode: single
    trigger:
      - platform: state
        entity_id: binary_sensor.imou_porch_motion_alarm
        to: "on"
    condition:
      - condition: sun
        after: sunset
        before: sunrise
    action:
      - service: light.turn_on
        target:
          entity_id: light.porch
        data:
          brightness_pct: 80
      - delay: "00:05:00"
      - service: light.turn_off
        target:
          entity_id: light.porch

说明 ：实体 ID 以你 HA 里实际为准；sun 条件避免白天误触发。

5. 场景自动化二：语音「看门口」

# configuration.yaml 片段 --- 助手可调用 script
script:
  show_door_camera:
    alias: 看门口摄像头
    sequence:
      - service: camera.play_stream
        target:
          entity_id: camera.imou_doorbell
        data:
          media_player: media_player.living_room_speaker

配合 Home Assistant Voice Assistant，说法如「打开门口监控」→ 触发 script 或切换 Dashboard 到摄像头卡片。低延迟需求高时，可改用平板常亮 Picture Glance + 组件直播流。

6. 进阶联动：OpenAPI 告警 Webhook → HA

组件覆盖大部分开关类能力；若要做 更细粒度告警 （如只要 videoMotion、要带 aiTag 人/车），可用 **setMessageCallback** 把消息推到自建桥接服务，再转 MQTT 给 HA：

// 桥接服务（Node）--- 平台侧先 setMessageCallback
app.post('/imou/callback', express.json(), (req, res) => {
  res.status(200).send('ok'); // 必须快速 200，否则平台会停推
  const msg = req.body;
  mqtt.publish(`imou/alarm/${msg.did}`, JSON.stringify(msg));
});

平台配置参数要点：

await platformCall('setMessageCallback', {
  token,
  status: 'on',
  callbackUrl: 'https://your-bridge.example.com/imou/callback',
  callbackFlag: 'alarm,deviceStatus',
  basePush: '2',
});

HA 侧 MQTT 自动化：

automation:
  - alias: 人形检测推手机
    trigger:
      - platform: mqtt
        topic: imou/alarm/TESTQWERXXXX
    condition:
      - condition: template
        value_template: "{{ trigger.payload_json.msgType == 'videoMotion' }}"
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: 门口有人
          message: "检测到移动，时间 {{ now().strftime('%H:%M') }}"

踩坑 C ：回调 URL 必须 公网 HTTPS 可达 ；内网 HA 需 frpc / 云函数中转。

踩坑 D ：未及时 200 响应 → 平台多次失败后 停止推送，我们监控桥接 5xx 率。

7. 与 OpenAPI 手工扩展（开发者向）

想在 HA 外挂 自定义传感器（如轮询在线状态），可在 HA 同机跑小型 Python 服务，复用签名壳：

# 伪代码：与 Node 版 sign 规则一致
def calc_sign(time, nonce, app_secret):
    raw = f"time:{time},nonce:{nonce},appSecret:{app_secret}"
    return hashlib.md5(raw.encode()).hexdigest()

# listDeviceDetailsByPage → 更新 HA REST sensor
# bindDeviceLive streamId=1 → 低带宽预览 URL（勿长期入库）

手工扩展适合 二次开发 ；普通玩家优先 官方 HA 组件 + 自动化 YAML 即可。

8. 端到端 checklist

□ 开放平台应用已创建，设备已绑定开发者账号
□ HACS Imou 集成配置 appId/Secret/域名
□ camera / binary_sensor 实体可见且能播
□ 至少 1 条自动化（动检或上下线）跑通
□ （可选）setMessageCallback + MQTT 桥接 + 200 响应
□ secrets 未进 Git

---

延迟与体验

• 云直播进 HA 延迟高于局域网 RTSP ，语音「看门口」可接受 3～8 秒；要门铃级秒开，保留 局域网 ONVIF 作备路。
• 多摄像头同时 Live View 会占 账号并发与带宽 ，参考多路预览文：辅码流思路 （组件/OpenAPI 侧选 streamId: 1）。

隐私与合规

• 自动化推手机前，确认 家人知情、摄像头角度合规。
• **setMessageCallback 回调体含 deviceId、告警类型**------日志脱敏，HTTPS 必开。
• 访客模式：用 HA input_boolean 一键关闭动检联动 script。

常见问题

现象	原因	处理
集成无设备	未绑开发者账号	bindDevice / 控制台添加
连接超时	API 域名区域错	国内用 lechange.cn 域
动检不触发	设备端未开侦测	App 或组件 switch 打开
Webhook 无消息	回调非 200 / 非公网	修桥接；查 setMessageCallback
PTZ 不可用	枪机无 PTZ 能力	查 deviceAbility

延伸能力

• 云录像 ：告警 token 字段可关联查询录像（getCloudRecords 链路，另文展开）。
• PTZ ：HA 组件或 controlMovePTZ 接「语音转向门口」。
• 多 homeassistant 实例：一 appId 多实例共享配额，注意 API 限流。

---

小结

Home Assistant × 乐橙，不是简单「填个 RTSP」，而是 把摄像头变成 HA 里的 camera + sensor + switch ，再用自动化接上灯、锁、通知。路径可以很短：开放平台注册 → 设备进资产池 → HACS 装 Imou 组件 → 写 YAML 场景 ；要更细告警，再叠 **setMessageCallback Webhook 桥接**。

乐橙开放平台以视频技术与安全为核心，开放低代码组件与 OpenAPI，并提供 Home Assistant 集成指引与开源组件------个人开发者也能较低成本把乐橙 IPC 纳入全屋智能，而不必从零逆向 App 协议。

如何开始 ：在 乐橙开放平台 完成开发者注册并创建应用，于控制台获取 AppId 与 AppSecret；在 在线开发文档 查阅应用开发、Home Assistant 开发指引、设备分页查询、事件消息推送等章节（请使用现行协议）。先在 HA 跑通一个 camera 实体，再加第一条自动化------比囤十个插件更有成就感。

---