BetaHydri/hymer-connect-ha

# HYMER Connect for Home Assistant [](https://github.com/hacs/integration) 用于将您的 HYMER / Erwin Hymer Group 房车或拖挂式房车连接到 [Home Assistant](https://www.home-assistant.io/) 的自定义集成。  ## 支持的品牌 此集成适用于所有配备了 **Smart Interface Unit (SIU)** 的 Erwin Hymer Group 品牌： | Brand | | Brand | |-------|-|-------| | HYMER | | Carado | | Bürstner | | Laika | | Dethleffs | | Sunlight | | Eriba | | FreeOnTour | | LMC | | Niesmann+Bischoff | ## 功能 ### 传感器 - **电池** — 电量 (%)，电压 (V)，底盘电池电压 (V) - **水箱** — 清水水位 (%)，灰水水位 (%) - **温度** — 室内 (°C)，室外 (°C) - **胎压** — 左前，右前，左后，右后 (bar) ### 二进制传感器 - **SIU 在线** — 车辆连接状态 - **市电** — 岸电已连接 - **门 / 窗** — 开/关状态 - **警报** — 警报系统激活 - **加热器 / 冰箱** — 运行状态 ### 仪表板 `dashboards/hymer_connect.yaml` 中包含了一个现成的 Lovelace 仪表板。 ## 安装 ### HACS (推荐) 1. 在 Home Assistant 中打开 HACS 2. 点击三点菜单 → **Custom repositories** (自定义仓库) 3. 添加 `https://github.com/BetaHydri/hymer-connect-ha` 为 **Integration** (集成) 4. 搜索 "HYMER Connect" 并安装 5. 重启 Home Assistant ### 手动安装 1. 将 `hymer_connect` 文件夹复制到您的 `custom_components/` 目录中 2. 重启 Home Assistant ## 配置 1. 前往 **Settings → Devices & Services → + Add Integration** (设置 → 设备与服务 → 添加集成) 2. 搜索 **HYMER Connect** 3. 选择您的品牌并输入您的 HYMER Connect 应用凭据 4. 集成将为您的车辆创建传感器实体 ## 仪表板设置 1. 前往 **Settings → Dashboards → + Add Dashboard** (设置 → 仪表板 → 添加仪表板) 2. 打开新仪表板 → 编辑 → 三点菜单 → **Raw configuration editor** (原始配置编辑器) 3. 粘贴 [`dashboards/hymer_connect.yaml`](dashboards/hymer_connect.yaml) 的内容 4. 保存 ## API 此集成与位于 `smartrv.erwinhymergroup.com` 的 HYMER Connect 云 API 通信。它使用与官方 HYMER Connect 网页和移动应用相同的 OAuth2 ROPC 身份验证。 ### 身份验证 | 参数 | 值 | |-----------|-------| | **端点** | `POST https://smartrv.erwinhymergroup.com/api/v2/oauth/token` | | **授权类型** | `password` (OAuth2 ROPC) | | **客户端认证** | HTTP Basic `OAUTH2_CLIENT:OAUTH2_CLIENT` | | **Content-Type** | `application/x-www-form-urlencoded` | | **Body** | `grant_type=password&username=&password=` | API 返回 `access_token`、`refresh_token` 和 `id_token` (JWT, RS256)。Token 刷新使用同一端点，参数为 `grant_type=refresh_token`。 `access_token` JWT 包含以下声明： - `account_number` — 用户账户的 UUID - `user_name` — 邮箱地址 - `scope` — `["default"]` - `tenant` — `"ehg"` (Erwin Hymer Group) - `client_id` — `"OAUTH2_CLIENT"` - `exp` — 过期时间戳 (Token 约在 15 分钟后过期) ### API 域 | 域 | IP | 用途 | |--------|----|---------| | `smartrv.erwinhymergroup.com` | 20.4.141.205 | 身份验证，SignalR 协商，Web 应用 | | `scc-api.smartrv.erwinhymergroup.com` | 20.103.22.48 | REST API 数据端点 | | `scc-rvtwin.smartrv.erwinhymergroup.com` | 13.107.226.45 | 车辆孪生数据 | | `scc-appcomm.smartrv.erwinhymergroup.com` | 20.4.141.205 | SignalR Hub (smartrv 的别名) | | `ehg-prod-signalr.service.signalr.net` | 变化 | Azure SignalR Service WebSocket | ### REST API 端点 所有端点都需要带有身份验证 `access_token` 的 `SCC-CsNgAccessToken` 请求头。 | 方法 | 端点 | 用途 | |--------|----------|---------| | GET | `/api/ehg/v1/accounts/me` | 当前用户账户信息 | | GET | `/api/ehg/v1/accounts/available` | 检查邮箱可用性 | | GET | `/api/ehg/v1/vehicles` | 已注册车辆列表 | | GET | `/api/ehg/v1/sius` | Smart Interface Unit 列表 | | GET | `/api/ehg/v1/sensors` | 传感器数据 | | GET | `/api/ehg/v1/legal-docs/latest` | 最新法律文档 | | GET | `/api/ehg/v1/firmwares/sius` | SIU 固件信息 | | POST | `/api/ehg/v1/updates` | 更新管理 | | POST | `/api/ehg/v1/accounts/standard/resetPassword` | 密码重置 | | GET | `/api/rv-twin/sensors/sync` | RV 孪生传感器同步 | | GET | `/api/rv-twin/rv-model/documents` | RV 型号文档 | | GET | `/api/rv-twin/rv-model/filters-hierarchy` | RV 型号筛选层级 | | GET | `/api/service-catalogue/services` | 服务目录 | | GET | `/api/push-notifications/subscriptions/scu` | 推送通知订阅 | | GET | `/datahub/negotiate` | SignalR 协商 (无需认证) | ### HTTP 请求头 | 请求头 | 描述 | |--------|-------------| | `SCC-CsNgAccessToken` | OAuth2 访问令牌 | | `SCC-CsNgRemoteToken` | OAuth2 刷新令牌 | | `SCC-Locale` | 语言代码 (例如 `de`, `en`) | | `SCC-PinCode` | 用于某些操作的 PIN 码 | | `SCC-ScuUrn` | 用于设备特定请求的 SIU URN | ### 架构 ``` graph TD AUTH["smartrv.erwinhymergroup.com
POST /api/v2/oauth/token
(OAuth2 ROPC + HTTP Basic Auth)"] API["scc-api.smartrv.erwinhymergroup
REST API data endpoints
(SCC-CsNgAccessToken header)"] AUTH -->|access_token| API VD["Vehicle Data
/api/ehg/v1/
vehicles, sius, sensors"] RT["RV Twin
scc-rvtwin
sensors/sync"] SR["SignalR Hub
scc-appcomm
/datahub (real-time)"] API --> VD API --> RT API --> SR SIU["SIU (Smart Interface Unit)
Vehicle gateway (cellular/BLE)"] VD --> SIU RT --> SIU SR --> SIU TH["Truma Heater
Alde Boiler
Hegotec Lights"] DO["Dometic
Fridge
Victron"] SE["Sensors
Battery, Temp
Water, TPMS"] SIU -->|Vehicle Bus| TH SIU -->|Vehicle Bus| DO SIU -->|Vehicle Bus| SE ``` ### SignalR DataHub (实时通信) SIU 通过 Azure SignalR Service hub 与云端通信。该应用使用 `@microsoft/signalr` 库。 | 属性 | 值 | |----------|-------| | **协商 URL** | `POST https://scc-appcomm.smartrv.erwinhymergroup.com/datahub/negotiate?negotiateVersion=1` | | **WebSocket URL** | `wss://ehg-prod-signalr.service.signalr.net/client/?hub=datahub` | | **协议** | JSON (SignalR JSON 协议，使用 `\x1e` 分隔符) | | **协商认证** | `Authorization: Bearer ` + `SCC-CsNgAccessToken: ` | | **WebSocket 认证** | 来自协商响应的 JWT 作为 `access_token` 查询参数传递 | 连接状态：`connecting` → `established` → `disconnected` (具有自动重连策略)。 ### 通信路径 **云端路径** (此集成使用)： ``` Home Assistant → HTTPS REST API → EHG Backend → SignalR DataHub → SIU (via cellular) ``` **BLE 路径** (本地，此集成未使用)： ``` Mobile App → BLE UART → SIU → Vehicle Bus → Connected Components ``` SIU 通过车辆的蜂窝调制解调器连接到云端。当 BLE 和云端同时可用时，应用优先使用云端路径。 ### Protobuf 消息类型 车辆通信使用 Protocol Buffers 进行结构化消息传递。在应用包中发现的关键消息类型： #### 车辆数据 | 消息 | 用途 | |---------|---------| | `ConnectedComponent` | 车辆总线上的单个设备 | | `ConnectedComponents` | 所有组件的集合 | | `ConnectedComponentControls` | 组件的控制命令 | | `ConnectedComponentSettings` | 组件的配置 | | `ConnectedComponentValue` / `Values` | 传感器和状态值 | | `NonCommunicatingComponents` | 离线/不可达组件 | #### 设备管理 | 消息 | 用途 | |---------|---------| | `DeviceTwin` | Azure IoT 风格的设备孪生 | | `DeviceInfo` / `DeviceInfoPatch` | 移动设备注册 | | `MobileDevices` | 已注册移动设备列表 | #### 遥测与诊断 | 消息 | 用途 | |---------|---------| | `Telemetry` / `Telemetries` | 实时遥测数据 | | `DiagnosticsData` / `DiagnosticsDataItem` | 诊断信息 | | `SystemEvent` / `SystemEvents` | 系统事件日志 | | `Statistic` / `Statistics` | 使用统计 | #### 自动化与通知 | 消息 | 用途 | |---------|---------| | `Scenario` / `Scenarios` | 自动化场景 | | `ScenarioResult` / `ScenarioType` | 场景执行结果 | | `Notification` / `NotificationSubscriptions` | 推送通知管理 | | `AlarmType` | 警报定义 | ### 应用登录流程 (通过 PCAPdroid 观察) 全新登录期间的完整网络流程，按顺序排列： | 步骤 | 域 | 发送字节 | 接收字节 | 用途 | |------|--------|-----------|---------------|---------| | 1 | `firebaseinstallations.googleapis.com` | 1.7 KB | 5.2 KB | Firebase SDK 初始化 | | 2 | `firebase-settings.crashlytics.com` | 1.5 KB | 6.1 KB | Crashlytics 配置 | | 3 | `api2.branch.io` | — | — | Branch.io 分析 | | 4 | `config.mapbox.com` | 3.7 KB | 6.0 KB | Mapbox 地图配置 | | 5 | `distributions.crowdin.net` | 5.1 KB | 443.8 KB | 翻译字符串下载 | | 6 | **`smartrv.erwinhymergroup.com`** | **4.5 KB** | **14.8 KB** | **认证 + 配置** | | 7 | **`scc-api.smartrv.erwinhymergroup.com`** | **11.2 KB** | **14.4 KB** | **REST API 调用** | | 8 | **`scc-rvtwin.smartrv.erwinhymergroup.com`** | **2.7 KB** | **429.0 KB** | **车辆孪生数据** | | 9 | `firebaselogging-pa.googleapis.com` | 2.5 KB | 5.9 KB | Firebase 事件日志记录 | ### Firebase (不用于身份验证) 该应用包含 Firebase SDK，但**不**使用 Firebase 进行主要身份验证： | 属性 | 值 | |----------|-------| | Firebase 项目 | `smart-caravan-ddde6` | | Firebase API 密钥 | `AIzaSyA1raPCBXULGkXVIBHjkDTI1IWJuDX9D9k` | | Firebase 数据库 URL | `https://smart-caravan-ddde6.firebaseio.com` | | 密码登录 | 在项目级别**已禁用** | Firebase 仅用于：Crashlytics (崩溃报告)、Analytics (分析)、Remote Config (远程配置) 和 Installations (安装)。 ### 关键术语 | 术语 | 描述 | |------|-------------| | **SIU** | Smart Interface Unit — 中央车辆网关模块 | | **SCU** | Smart Control Unit (SIU 的旧称) | | **CSNG** | 内部平台代号 | | **EHG** | Erwin Hymer Group | | **Connected Component** | 车辆总线上的任何设备 (加热器、冰箱、灯光等) | | **DataHub** | 用于实时云端通信的 SignalR hub | | **RV Twin** | 车辆的数字孪生表示 | | **PIA** | Platform Integration API (内部) | | **FOTA** | 固件空中升级 | | **BOS Battery** | 电池管理系统品牌 | | **WWL** | 无线水位传感器 | ### 源应用分析 此集成逆向工程自： - **HYMER Connect** Android 应用 v2.10.14 (`com.e.hymerconnect`) - React Native 应用，使用 Hermes 字节码引擎 (编译后的 JS，约 13 MB) - Nordic Semiconductor BLE 协议栈，用于本地 SIU 通信 - Microsoft SignalR (`@microsoft/signalr`)，用于实时云端通信 - Protocol Buffers，用于结构化车辆消息 - OkHttp，用于 HTTP 网络 - 位于 `smartrv.erwinhymergroup.com` 的 Web 应用 SPA (React + Vite，提供了认证端点发现) - Azure 基础设施：API Management、SignalR Service、Spring Boot 后端 (nginx/1.25.1) ## 开发状态 - [x] API 基础 URL 已发现 - [x] 认证端点已发现 (`/api/v2/oauth/token` 使用 HTTP Basic Auth) - [x] 认证测试成功 (返回 access_token + refresh_token) - [x] 集成骨架 (配置流程、协调器、传感器、二进制传感器) - [x] HA 集成登录正常工作 — 已创建带有实体的设备 - [x] 通过 REST API 获取车辆信息 (`/api/v2/assets`) - [x] 通过 REST API 获取账户信息 (`/api/v2/accounts/me`) - [x] 重新认证流程支持 - [x] 仪表板 YAML - [x] SignalR WebSocket 连接 + 认证正常工作 - [ ] **🔴 获取传感器数据的 SignalR hub 方法名** ← 当前阻碍点 - [ ] 实际传感器数据映射到实体 - [ ] 气候控制实体 (加热器目标温度) - [ ] 开关实体 (灯光、USB、水泵) - [ ] 遮盖实体 (遮阳篷、车顶、穹顶) - [ ] SignalR 实时推送更新 - [ ] 设备追踪器 (GPS 位置) ## 贡献 本项目需要有关 **逆向工程 SignalR 协议** 的帮助。详情请参阅上方的 [SignalR DataHub 部分](#signalr-datahub-real-time-communication)。 **已正常工作：** - OAuth2 身份验证 ✅ - 用于车辆/账户信息的 REST API ✅ - SignalR WebSocket 连接 ✅ **受阻部分：** - 应用用于从 SIU 请求传感器数据的确切 SignalR hub 方法名 - 该方法名被编译到 Hermes 字节码 v96 中，无法作为纯字符串提取 - 已测试 40 多个方法名 — 均返回 "Method does not exist" **所需工具：** - Hermes 字节码 v96 反编译器 (hbctool 仅支持到 v90) - 或：在已 root 的 Android 设备上使用 Frida 挂钩 `HubConnection.invoke()` - 或：iOS 应用分析 (可能包含可读的 JavaScript) 如果您拥有一辆 EHG 车辆并能提供帮助，请提交一个 issue！ ## 许可证 本项目不隶属于 Erwin Hymer Group，也未受其认可。

标签：Burstner, Dethleffs, Eriba, Erwin Hymer Group, HACS, Home Assistant, HYMER, IoT, Lovelace, Python, RV, SignalR, Sunlight, 房车控制, 拖挂房车, 无后门, 智能仪表盘, 智能家居, 水位监测, 温度传感器, 物联网集成, 电池监控, 网络调试, 胎压监测, 自动化, 自定义组件, 车联网, 车载传感器, 车载智能系统, 逆向工具, 露营车