ORVIBO Smart Control

ORVIBO Smart Control 是一个面向 Home Assistant 的独立自定义集成。它把 MixPad 网关局域网直连与 ORVIBO 云端协议放在同一条设备、状态和控制链路中：能在 LAN 完成的操作优先本地执行，无法本地接管的设备或失败请求由云端承接。

通道策略

默认的 LAN 与云端结合 模式会同时维护本地和云端能力，但每次控制只选择一个起始通道：

设备请求
  |
  +-- 纯云端 ------------------------------------> 云端 TLS 长连接
  |
  +-- 纯 LAN + 设备支持 LAN + 网关可达 ----------> LAN TCP
  |      +-- 不支持 / 不可达 / 执行失败 ----------> 返回失败，不走云端
  |
  +-- LAN 与云端结合 + 云专属设备 ---------------> 云端 TLS 长连接
         +-- 支持 LAN + 网关可达 ----------------> LAN TCP
         |      +-- LAN 失败一次 ----------------> 云端重试一次
         +-- 其他情况 ---------------------------> 云端 TLS 长连接

状态更新统一进入字段级状态仓库，优先级为：

LAN > 云端实时推送（SSL）> 云端快照（REST）> 乐观状态 > 初始值

低优先级的旧值不会在保护窗口内回滚刚收到的 LAN 状态。相同值会被去重。门锁 107/522 和晾衣机 52 属于云专属类型；门锁事件、媒体和临时密码始终使用云端。 因此希望这些设备保持可用时应使用默认结合模式或纯云端模式。

纯 LAN 是运行阶段的传输限制，不是完全离线安装：首次启动和重载仍需登录 ORVIBO 云端， 用于确认账号区域、家庭、设备库存、网关 UID 和可信地址；完成发现后不建立云端 TLS 实时 连接，也不执行周期云快照轮询。

实现细节和失败边界见 运行时架构。

安装

HACS 自定义仓库

1. 在 HACS 的“集成”页面打开“自定义存储库”。
2. 添加 https://github.com/maycode0-0/orvibo-smart-control，类别选择“集成”。
3. 安装 ORVIBO Smart Control 并重启 Home Assistant。
4. 进入“设置 -> 设备与服务 -> 添加集成”，搜索项目名称。

手动安装

把 custom_components/orvibo_smart_control 目录放入 Home Assistant 配置目录下的 custom_components/，确认最终路径如下，然后重启：

<ha-config>/custom_components/orvibo_smart_control/manifest.json

升级时应整体替换该组件目录，避免旧模块残留。

首次配置

配置流程依次完成账号验证、云区识别、家庭选择和设备选择。中国区与 国际区按配置项分别保存，不会互相覆盖。账号密码只在提交时用于生成协议所需的大写 MD5 摘要；配置项不保存明文，但该摘要仍可直接用于认证，必须按密码保护。

设备列表拉取完成后会根据实际设备名称和协议类型自动归类，无法识别的设备统一归入“其他 设备”。同类设备使用复选列表显示，可连续勾选而无需反复展开；同类多台时在列表中提供 “全部”选项。首次配置和“继续添加或移除设备”使用相同规则。

安装完成后可以在集成的“配置”菜单中使用：

入口	用途
配置 LAN / 云端传输模式	选择纯 LAN、纯云端或默认 LAN 与云端结合
配置独立 MixPad LAN 凭据	MixPad 账号与云账号不同时，单独保存 LAN 用户名和密码摘要
继续添加或移除设备	按动态设备分类全选或逐台调整当前配置项管理的设备
按名称隐藏设备	用名称关键词或通配符隐藏设备，不创建对应实体
更新欧瑞博账号密码	更新云端认证信息，不删除实体和设备选择
同步云端设备名称	更新集成提供的设备名称，不覆盖用户自定义名称
清理本地配置文件	删除本集成的本地门锁媒体，并可重置通用选项
配置轮询间隔时间	设置云端快照轮询间隔，范围 5 到 1440 分钟
配置设备上下线通知	分别控制上线/离线通知，可指定 domain.service
配置集成更新检查	每 6 到 168 小时检查一次 GitHub 稳定版本
锁用户映射	把门锁用户编号映射为可读名称

独立 MixPad 密码与云端密码一样只保存协议摘要，不保存明文。清理操作不会删除账号、家庭、 设备选择、锁用户映射、实体注册或 Home Assistant .storage；执行前必须在 UI 中确认。 选项保存后 Home Assistant 会重载配置项，使传输和定时任务立即按新设置重建。

“按名称隐藏设备”支持每行一条规则。普通文本会匹配名称中的任意位置，例如 测试；包含 通配符时按完整设备名称匹配，例如 *控制器*、卧室?灯。匹配不区分英文字母大小写，设备 会同时从实体平台和设备选择页面排除。规则不会改写已保存的设备 ID，删除规则后设备会重新 出现。

设备传输标识

每台已接入且具有 Home Assistant 平台的设备都会创建一个诊断实体“传输通道”，不会修改 原设备名称、业务实体名称或唯一 ID。实体状态含义如下：

状态	含义
LAN	纯 LAN 模式下，设备状态或控制使用 MixPad
云端	纯云端模式，或该设备按能力表固定使用云端
LAN 优先，云端回退	默认结合模式下优先 LAN，必要时走云端
当前模式不可用	纯 LAN 模式下设备没有 LAN 路径，例如门锁、晾衣机或云控地暖

实体属性还会显示配置模式、LAN/云控制能力、网关连接状态，以及本次 Home Assistant 运行期间 最近一次成功控制实际使用的 lan 或 cloud 通道。

支持范围

当前平台包括 light、switch、cover、climate、fan、sensor、 binary_sensor 和 camera。主要能力如下：

类别	已实现能力	典型控制通道
灯光与墙壁开关	开关、亮度、色温	LAN 优先，云兜底
窗帘与管状电机	开合、位置、停止；梦幻帘叶片角度	依型号选择 LAN 或云
风机盘管、地暖、新风	模式、温度、风速或预设模式	依型号选择 LAN 或云
安防与环境传感器	人体、门窗、烟雾、燃气、水浸、温湿度	只读状态
智能门锁	锁/门磁、电池、事件、截图、录像、临时密码	云专属
智能晾衣机	灯、消毒、风干、热干、升降	云专属

完整的已验证型号、deviceType、限制和通道标记见 设备支持矩阵。未列出的型号可能会被识别并展示，但不会据此 推测控制命令；这是防止未知设备收到错误动作的安全约束。

门锁功能

每把已支持的门锁会按实际能力创建状态、电池、事件和截图实体。事件截图不是猫眼实时 视频流；实时流使用的私有协议目前不在支持范围内。

集成还提供：

• orvibo_smart_control_lock_event 事件，用于开锁、门铃、撬锁和门未关等自动化；
• 门锁事件图片签名、H.264 录像归档及 Home Assistant 媒体浏览器索引；
• 临时密码下发、查询、撤销和每 6 小时的过期回收；
• 内置门锁总览卡片和独立的临时密码管理卡片。

只管理临时密码时，添加以下 Lovelace 卡片：

type: custom:orvibo-smart-control-temp-password-card
device_id: w-example-door-lock-id

需要同时查看门锁状态、事件和临时密码时使用总览卡片：

type: custom:orvibo-smart-control-door-lock-card
device_id: w-example-door-lock-id

服务字段、响应、事件载荷和自动化示例统一记录在 服务与事件参考。

故障定位

现象	优先检查
能登录但没有设备	账号所在云区、家庭选择、设备筛选选项；随后执行 refresh_devices
控制一直走云端	模式是否为“纯云端”、设备是否在 LAN 能力表、网关是否完成认证
网关无法连接	HA 与 MixPad 是否同一可达网络，UDP 发现和 TCP 8088 是否被 VLAN/防火墙阻断
LAN 控制失败后状态稍慢	查看云端长连接是否在线；LAN 失败只会向云端重试一次
纯 LAN 下门锁/晾衣机不可用	这是预期限制；改用默认结合模式，让 LAN 不支持的 Wi-Fi 设备走云端
独立 MixPad 凭据仍登录失败	确认 LAN 用户名和密码属于该 MixPad；留空密码只会保留已经配置过的摘要
门锁没有图片或录像	检查云端凭据、HA 的 media 目录权限；MP4 转封装还需要可用的 ffmpeg
出现重复实体	检查是否仍加载其他 ORVIBO 集成，并按迁移文档确认实体归属

需要提交问题时，请附 Home Assistant 版本、集成版本、设备公开型号、接入方式、相关日志 和可复现步骤。不要附账号、密码摘要、token、家庭/设备标识、IP、MAC、签名媒体 URL 或未经处理的诊断文件。完整规则见 安全策略。

升级与迁移

本项目是新的 Home Assistant 集成域，其他 ORVIBO 集成的配置条目不会自动转入。建议先 并行验证新集成，再处理旧实体和历史数据。操作顺序、回退方法和内部配置版本迁移的区别 见 迁移指南。

开发与验证

代码按运行时职责组织：

custom_components/orvibo_smart_control/
  capabilities.py       设备分类、平台和可用通道
  device_selection.py   配置流中的名称/类型动态分组与选择合并
  coordinator.py        Home Assistant 生命周期及双通道编排
  lan/                  网关发现、认证、TCP 会话和控制适配
  https_client.py       云端 REST 登录与设备快照
  ssl_client.py         云端 TLS 实时推送和控制
  parsers/              LAN/SSL 共用的状态归一化
  state_store.py        字段级来源优先级和去重
  control_router.py     与传输无关的设备动作路由
  control_executor.py   通道选择、执行和单次云回退
  runtime_options.py    上下线通知和可选更新检查
  lock_* / temp_*       门锁事件、媒体与临时密码
  www/                  内置门锁卡片

项目使用标准库 unittest 运行不依赖完整 Home Assistant 的测试，并由 CI 执行语法、 身份、HACS 和 hassfest 校验。参与开发前请阅读 贡献指南。

文档索引

文档	面向读者	内容
设备支持矩阵	用户、设备贡献者	已验证型号、通道和限制
服务与事件参考	自动化作者	服务字段、响应和事件载荷
迁移指南	现有集成用户	独立域迁移、去重和回退
运行时架构	维护者	数据流、路由、状态合并和 ADR
贡献指南	贡献者	开发流程、测试、真机证据和 PR 要求
安全策略	所有人	漏洞报告、秘密处理和媒体风险
变更记录	所有人	版本历史和未发布变更
MIT 许可证	所有人	使用与再分发条款

许可证与致谢

项目以 MIT License 发布。协议研究和早期设备支持受益于 ORVIBO 社区贡献者与真机测试者。

ORVIBO、HomeMate 和智家 365 是其各自权利人的商标。本项目是社区维护的软件，不代表 厂商官方支持。