欧瑞博 HomeMate / 智家365 云端设备接入 Home Assistant

GitHub Releases | HACS | MIT License

简体中文 | English

ORVIBO Cloud 可将 HomeMate 或 智家365 账号中的设备接入 Home Assistant。集成会自动探测账号所在区域的云端节点，通过 REST API 获取家庭、房间和设备信息，并通过欧瑞博的双向 TLS 二进制云协议控制已验证的设备。

• 自动探测中国、HomeMate、德国和美国区域节点
• 支持账号登录、多个家庭选择和凭据失效后的重新认证
• 从云端读取完整设备列表，由用户选择需要接入 Home Assistant 的设备
• 自动使用欧瑞博 App 中的房间作为默认区域，也可在配置时或集成选项中修改
• 支持已验证的窗帘电机和灯光设备控制
• 提供云端连接状态、当前家庭和设备数量等诊断实体
• 每 1 分钟刷新一次云端设备状态，控制命令执行后会立即更新实体状态
• 不保存明文密码；二进制会话密码仅保存在内存中

┌──────────────────┐       HTTPS / REST        ┌──────────────────┐
│ Home Assistant   │ ────────────────────────> │ ORVIBO regional  │
│ / orvibo_cloud   │ <──────────────────────── │ cloud endpoint   │
│                  │   家庭、房间、设备及状态    │                  │
│                  │                            │                  │
│                  │   mutual TLS / TCP 10002  │                  │
│                  │ ────────────────────────> │ Binary cloud     │
│                  │ <──────────────────────── │ service          │
└──────────────────┘       控制结果             └──────────────────┘

1. 自动尝试可用的区域节点，并通过 /getOauthToken 登录。
2. 获取账号下的家庭列表，并通过 /v2/cmd/app/readtable 下载设备表。
3. 将用户选择的设备及其房间信息注册到 Home Assistant。
4. 通过端口 10002 上的双向 TLS 二进制协议发送已验证的控制命令。
5. 定期从设备表刷新状态；部分控制后的状态在下一次刷新前为乐观更新。

在 HACS 中打开此仓库

1. 在 HACS 中添加自定义仓库：https://github.com/maycode0-0/orvibo-cloud
2. 仓库类型选择 Integration，然后搜索并安装 ORVIBO Cloud
3. 重启 Home Assistant
4. 进入 设置 > 设备与服务 > 添加集成，搜索 ORVIBO Cloud

通过 HACS安装后，新版本发布时会在 Home Assistant 中显示更新提醒。main有新提交时，GitHub Actions会在每周二、周五自动发布 0.x.ybN 测试版；推送与 manifest版本严格匹配的 v0.x.y轻量 Tag会自动发布正式版，也可从 main手动运行工作流补发。开始下一轮开发前，维护者需要先提升 custom_components/orvibo_cloud/manifest.json 中的目标正式版本。每个成功的 Release 都必须附带 HACS直接安装的非空 orvibo_cloud.zip。

将本仓库中的 custom_components/orvibo_cloud/ 复制到 Home Assistant 配置目录：

config/
└── custom_components/
    └── orvibo_cloud/

重启 Home Assistant，然后进入 设置 > 设备与服务 > 添加集成，搜索 ORVIBO Cloud。

安装完成后，可在集成的 配置 对话框中重新选择设备和区域。账号密码失效时，Home Assistant 会启动重新认证流程。

只有经过抓包验证的设备配置才会创建可控制实体。其他选中的设备仍会出现在 Home Assistant 设备注册表中，但不会自动获得控制实体。

• 连接：最近一次已认证云端刷新是否成功
• 家庭：当前选择的欧瑞博家庭
• 设备：云端返回的设备数量及设备类型

• 集成类型：Cloud Polling
• 状态刷新间隔：1 分钟

• 登录接口：GET https://<region>.orvibo.com/getOauthToken
• 家庭接口：POST https://<region>.orvibo.com/v2/family/statistics/users
• 设备发现：POST https://<region>.orvibo.com/v2/cmd/app/readtable
• 设备控制：双向 TLS，TCP 端口 10002
• 区域同步：读取设备表中的房间并映射到 Home Assistant 区域

• 集成不会保存明文密码，而是保存欧瑞博接口要求的大写 MD5 凭据。该值与密码等效，仍应严格保密。
• readtable 返回的二进制会话密码仅保存在内存中，不会出现在诊断信息或对象表示中。
• 不要记录 OAuth 响应、密码哈希或其他账号令牌。
• 即使敏感字段已被清理，也应将 Home Assistant 诊断导出视为私密数据。
• 端口 10002 使用已由致谢项目公开的旧版欧瑞博客户端证书和私钥。请勿将其用于控制本人欧瑞博账号以外的任何服务。

运行不依赖 Home Assistant 安装环境的协议测试：

python -m pip install "aiohttp>=3.9.0" "pycryptodome>=3.20.0" "PyYAML>=6.0.2"
python -m unittest discover -s tests -v

项目主要结构：

orvibo-cloud/
├── custom_components/orvibo_cloud/
│   ├── api.py               # REST 登录与设备表获取
│   ├── binary.py            # 双向 TLS 二进制云协议
│   ├── config_flow.py       # UI 配置、设备及区域选择
│   ├── coordinator.py       # 云端状态刷新
│   ├── cover.py             # 窗帘实体
│   ├── light.py             # 灯光实体
│   ├── sensor.py            # 诊断传感器
│   └── translations/        # 多语言翻译
├── tests/
├── hacs.json
└── README.md

协议行为通过实际抓包以及 MIT 许可的 orvibo-homeassistant-curtains 项目进行交叉验证。

ORVIBO Cloud connects devices from a HomeMate or ZhiJia365 account to Home Assistant. It discovers the account's regional endpoint, retrieves family, room, and device data through the REST API, and controls verified devices through ORVIBO's mutual-TLS binary cloud protocol.

• Discovers the China, HomeMate, Germany, or USA regional endpoint
• Supports account authentication, multiple-family selection, and Home Assistant reauthentication
• Downloads the complete cloud device table and lets you choose which devices to add
• Uses ORVIBO rooms as default Home Assistant areas, with area selection during setup or later in the integration options
• Controls verified curtain motors and light profiles
• Exposes cloud connectivity, selected family, and device count as diagnostic entities
• Refreshes cloud device state every minute and updates entity state immediately after control commands
• Never stores the plaintext password; the binary session password remains in memory only

┌──────────────────┐       HTTPS / REST        ┌──────────────────┐
│ Home Assistant   │ ────────────────────────> │ ORVIBO regional  │
│ / orvibo_cloud   │ <──────────────────────── │ cloud endpoint   │
│                  │  families, rooms, devices │                  │
│                  │                            │                  │
│                  │   mutual TLS / TCP 10002  │                  │
│                  │ ────────────────────────> │ Binary cloud     │
│                  │ <──────────────────────── │ service          │
└──────────────────┘      command result        └──────────────────┘

1. The integration tries the configured regional endpoints and authenticates through /getOauthToken.
2. It retrieves the account families and downloads the device table from /v2/cmd/app/readtable.
3. Selected devices and their room information are registered with Home Assistant.
4. Verified commands are sent through the mutual-TLS binary service on port 10002.
5. State is periodically refreshed from the device table; some command results are optimistic until the next refresh.

Open this repository in HACS

1. Add https://github.com/maycode0-0/orvibo-cloud to HACS as a custom Integration repository.
2. Search for and install ORVIBO Cloud.
3. Restart Home Assistant.
4. Open Settings > Devices & services > Add integration and search for ORVIBO Cloud.

After installation through HACS, Home Assistant will show an update when a new version is released. When main contains new commits, GitHub Actions publishes a 0.x.ybN beta every Tuesday and Friday. Pushing a lightweight v0.x.y tag that exactly matches the manifest version automatically publishes a stable release; maintainers can also run the workflow manually from main for recovery. Maintainers must bump the target stable version in custom_components/orvibo_cloud/manifest.json before starting the next release cycle. Every successful release must include a non-empty orvibo_cloud.zip asset that HACS can install directly.

Copy custom_components/orvibo_cloud/ from this repository into your Home Assistant configuration directory:

config/
└── custom_components/
    └── orvibo_cloud/

Restart Home Assistant, then open Settings > Devices & services > Add integration and search for ORVIBO Cloud.

After setup, open the integration's Configure dialog to change the selected devices or their areas. Home Assistant starts a reauthentication flow if the saved credentials are rejected.

Controllable entities are created only for packet-capture-verified profiles. Other selected devices are still added to the Home Assistant Device Registry, but they do not automatically receive control entities.

• Connection: whether the latest authenticated cloud refresh succeeded
• Family: the currently selected ORVIBO family
• Devices: the number and types of devices returned by the cloud

• Integration type: Cloud Polling
• State refresh interval: 1 minute

• Login endpoint: GET https://<region>.orvibo.com/getOauthToken
• Family endpoint: POST https://<region>.orvibo.com/v2/family/statistics/users
• Device discovery: POST https://<region>.orvibo.com/v2/cmd/app/readtable
• Device control: mutual TLS on TCP port 10002
• Area synchronization: maps rooms from the device table to Home Assistant areas

• The integration stores the uppercase MD5 credential required by ORVIBO instead of the plaintext password. Treat this value as password-equivalent and keep it private.
• The separate binary-session password returned by readtable is held in memory only and excluded from diagnostics and object representations.
• Do not log OAuth responses, the password hash, or other account tokens.
• Treat Home Assistant diagnostics exports as private even though sensitive values are redacted.
• Port 10002 uses a legacy ORVIBO client certificate and private key already published by the acknowledged project. Do not reuse them for any service other than integrating your own ORVIBO account.

Run the protocol tests, which do not require a Home Assistant installation:

python -m pip install "aiohttp>=3.9.0" "pycryptodome>=3.20.0" "PyYAML>=6.0.2"
python -m unittest discover -s tests -v

Main project structure:

orvibo-cloud/
├── custom_components/orvibo_cloud/
│   ├── api.py               # REST login and device-table retrieval
│   ├── binary.py            # Mutual-TLS binary cloud protocol
│   ├── config_flow.py       # UI setup, device, and area selection
│   ├── coordinator.py       # Cloud state refresh
│   ├── cover.py             # Curtain entities
│   ├── light.py             # Light entities
│   ├── sensor.py            # Diagnostic sensors
│   └── translations/        # Localized UI strings
├── tests/
├── hacs.json
└── README.md

Protocol behavior was cross-checked against packet captures and the MIT-licensed orvibo-homeassistant-curtains project.

MIT