HomeAssistant自定义集成，用于接入升仕（Zontes）智能摩托车数据。通过官方App接口获取车辆实时状态，支持多车辆自动轮询、数值转换、国际化显示，并支持原生远程开锁/上锁控制。
- 纯AI写的
- 多车支持：自动轮询账户下所有摩托车，每辆车创建独立设备。
- 实时数据：获取油量、胎压、续航、速度、电压、水温、里程、保养里程、GSM信号、卫星数、骑行时间、故障码、锁状态、车型等信息。
- 远程控制：支持通过私有 TCP 协议对车辆进行原生的远程开锁与上锁控制。
- 数值修正：
- 胎压原始值自动 ×2 得到 kPa
- 里程（总里程/小计里程）、电压、平均油耗原始值 ÷10 显示
- 骑行时间（
RideTimes）分钟转小时显示
- 国际化：支持中文、英文界面（实体名称自动翻译）。
- 设备跟踪：通过
device_tracker实体在地图上显示车辆位置。 - GPS 坐标转换：GCJ-02自动转换WGS84
- 确保已安装 HACS。
- 在 HACS 中点击“集成”，选择“自定义存储库”。
- 添加仓库 URL：
https://github.com/cdcp998/Zontes_Motorcycle-ha，类别选择“集成”。 - 点击“下载”按钮，下载完成后重启 Home Assistant。
- 下载 最新发布版本 的
Zontes_Motorcycle-ha.zip。 - 解压到 Home Assistant 配置目录的
custom_components/zontes_motorcycle文件夹中。 - 重启 Home Assistant。
- 进入 配置 → 设备与服务，点击“添加集成”。
- 搜索并选择 Zontes Smart Motorcycle。
- 输入您的升仕账号、密码，以及更新间隔（默认30秒）。
- 点击提交，集成将自动获取您的车辆列表并创建设备和实体。
每辆车会生成以下实体（前缀为 实体域.车型名称_）：
| 实体键 | 描述 | 单位 | 转换 |
|---|---|---|---|
oil |
油量 | % | 无 |
pressure_front |
前轮胎压 | kPa | 原始值 ×2 |
pressure_rear |
后轮胎压 | kPa | 原始值 ×2 |
range |
续航里程 | km | 无 |
speed |
速度 | km/h | 无 |
voltage |
电池电压 | V | 原始值 ÷10 |
water_temp |
水温 | °C | 无 |
odo_mileages |
总里程 | km | 原始值 ÷10 |
trip_mileage |
小计里程 | km | 原始值 ÷10 |
maintenance_mileage |
保养剩余里程 | km | 无 |
gsm_rssi |
GSM信号强度 | dBm | 无 |
satellite_num |
卫星数量 | 个 | 无 |
ride_times |
累计骑行时间 | h | 原始值 ÷60 |
fault_code |
故障码 | - | 无故障时显示“没有故障” |
trip_max_speed |
最高速度 | km/h | 无 |
oil_ause |
平均油耗 | L/100km | 原始值 ÷10 |
vehicle_model |
车型 | - | 无 |
此外，每辆车还包含：
- 锁控制实体 (
lock)：支持远程下发开锁与设防指令。 - 二进制传感器 (
binary_sensor)：表示锁的当前物理状态（0=锁定，1=解锁）。 - 设备跟踪器 (
device_tracker)：显示GPS位置。
custom_components/zontes_motorcycle/
├── __init__.py # 集成入口与数据协调器
├── manifest.json # 元数据
├── config_flow.py # 配置流
├── const.py # 常量
├── api.py # API客户端 (含4510 TCP协议与加解密逻辑)
├── sensor.py # 传感器实体
├── binary_sensor.py # 二进制传感器
├── lock.py # 远程锁控制实体
├── device_tracker.py # 设备跟踪器
├── convert.py # 坐标纠偏与数值转换
├── common.py # 通用辅助函数
└── translations/ # 国际化文件
├── en.json
└── zh-Hans.json
tools/ # 独立工具 (凭据一律经环境变量注入, 不落真实凭据)
├── zontes_4510_client.py # 4510 独立参考客户端 (lock|unlock, 双钥加密)
├── zontes_4510_tablet_test.py # 平板(安卓)网络出口控制变量探针 (adb+nc)
├── zontes_rsa_key_scan.py # 内存/堆转储 RSA-2048 公钥扫描 (钥轮换应急用)
└── zontes_4510_verify.py # pcap 帧解析与登录签名离线校验
tests/
├── test_4510_qishi_vectors.py # 帧签名/帧格式/双钥离线回归测试 (虚构向量)
└── PROTOCOL_REVERSE_PLAYBOOK.md # 协议逆向踩坑与破局实战手册 (完全脱敏)
- 账号互踢说明：升仕新版接口启用了单设备登录限制。为避免在 HA 轮询时将您的手机 App 踢下线，建议在升仕 App 的“车辆授权”中将车辆授权给一个副账号，并在 HA 中使用该副账号进行配置。
- 首次添加集成时需要输入正确的账号密码，若账号未注册或密码错误会给出明确提示。
- 如果车辆具有
StartTime/EndTime授权时间，超出时间后对应实体将自动变为不可用。 - 更新间隔不宜过短，建议至少30秒，避免被服务器限流。
- 若某辆车切换失败（例如“没有该授权车辆信息”），集成会跳过该车，其他车辆不受影响。
- 🔑 根因定案（双 RSA 密钥）：服务端对登录帧与指令帧使用两把不同的 RSA 私钥——登录帧
*UL用 A 钥加密，指令帧*UClear/*ULoc（及保活帧）必须用 K1 钥加密。此前"登录 OK、指令零回显"的故障，正是指令帧误用了 A 钥导致服务端无法解密而被静默丢弃。 - 🔬 K1 钥来源：2026-09-09 从运行中的官方
com.tayo.msboxv1.56 内存（region space 堆转储）提取（180 处引用的活动公钥），实测UClear/ULoc均获服务端指令回显 +*AM,2,1#/1,1#设备确认；生产代码路径async_set_lock_state端到端验证成功（真实锁车，changeTime 更新）。 - ⚙️ 热覆盖：指令钥经
ZONTES_4510_CMD_KEY环境变量可整体替换（App 升级可能导致钥轮换）。 - 🧪 测试同步：
tests/test_4510_qishi_vectors.py新增"登录钥≠指令钥"断言。
- 🔬 协议逐字节对齐：抓取第三方客户端《骑仕》1.56 成功控车全量 pcap 后逐包核对——本集成登录/指令帧的字段、哈希算法、时间戳与 seq 格式与骑仕完全一致（4 会话 8 帧全部离线反算匹配，向量已固化进
tests/test_4510_qishi_vectors.py，纯离线可回归）。 - ✂️ 帧纪律同步骑仕：帧内哈希一律大写、登录帧
*UL版本字段后不再带#（与抓包明文回显逐字节一致）。 - ⚡ 成功判据对齐骑仕：骑仕在收到服务器指令回显
*,OK#（约 50~100ms）后即关闭连接、车辆异步执行，并不等待*AM设备确认。锁指令现以“服务器回显接受”为成功判据（*AM属长连接附加回执、不再强制等待），避免慢速*AM造成长时间挂起；真实锁态由轮询myCarData.lock兜底核对。 - 🧪 控制变量实测结论（重要）：相同逐字节帧分别从 PC 与平板自身网络栈直发，均“登录 OK +
*BR,1#正常、指令静默无回显”；而同账号骑仕 App 于同一 WLAN 可 100% 控车。差异不在帧内容/网络出口/时序，判定为服务端账号/设备会话态门控，机制待进一步核实。新增tools/zontes_4510_tablet_test.py（脱敏 adb+nc 探针）与tools/zontes_4510_client.py（独立参考客户端）用于复现与验证。 - 🔒 仓库结构规范：工具收敛至
tools/、离线测试收敛至tests/；全库脱敏，真实凭据一律经环境变量注入（ZONTES_USER_CODE/PKE/MCUID/4510_HOST/PORT/VERSION/MAC_GUID）。
- ⚡ 性能优化：修复 4510 远程控制链路"秒开 vs 死等十几秒"玄学延迟的根因。
_read_until原先每次读块空闲超过 0.2s 就提前放弃，而设备确认帧*AM需要 0.85s（车辆蜂窝唤醒，物理瓶颈），导致正常慢速确认被误判失败并触发无谓的重连重试；现改为空闲时继续等待直到总超时，指令通常在 15 秒内一次成功。 - ✂️ 精简协议流程：移除登录后多余的心跳帧
*UH（实测无心跳时指令同样被服务器接受；且旧格式心跳紧贴登录帧发送反而可能导致会话静默丢弃指令）；登录未获确认时快速判失败，避免向服务器多发无效指令、加重限流。 - ⚡ 响应提速：指令确认成功后，锁实体改为后台刷新协调器状态（不再阻塞等待），避免 OAuth 登录慢（实测 6~20s）或网络抖动时语音控制多等十几秒。
- 🐛 修复缺陷：校准锁状态二进制传感器显示。实测确认
lock=0为设防锁定、lock=1为解锁后，修正binary_sensor.is_on与 HAlockdevice_class（on=Unlocked）的正确语义映射，恢复正确的状态显示，并在源码中补充了防踩坑注释。 - 🧪 测试工具：新增
_probe/4510/benchmark_4510.py（分步耗时基准）与_probe/4510/verify_fixed.py（修复后端到端验证），精确测量 TCP 连接 / 登录 / 心跳 / 指令回显 / 设备确认各步骤耗时。
- ✨ 接口迁移：适配升仕官方最新版
ifino.com:8081API 与 OAuth2 鉴权架构。 - ✨ 新增功能：解析 4510 私有 TCP 协议，新增
lock实体，支持远程开锁与上锁控制。 - ✨ 实体扩充：新增车架号、发动机号、车牌号等车辆档案及售后服务信息传感器。
- 🐛 修复缺陷：校准锁状态映射（修正为
lock=0锁定，lock=1解锁）。 - 🛡️ 稳定性优化：增加 API 请求与 TCP 控制的退避重试机制，缓解服务端限流问题。
- ✨ 添加：GCJ-02自动转换WGS84
- ✨ 添加：修改扫描间隔选项
- 🐛 修复：domain错误
- ✨ 新增：多车辆自动轮询支持
- ✨ 新增：授权时间管理，过期车辆自动移除
- ✨ 新增：骑行时间（RideTimes）分钟转小时显示
- ✨ 新增：故障码无故障时显示友好文本（支持国际化）
- ✨ 新增：设备信息显示车型、固件版本
- 🐛 修复：胎压、里程、电压、油耗数值转换错误
- 🐛 修复：空字符串导致传感器崩溃的问题
- 🌐 国际化：支持中文/英文实体名称
欢迎提交 Issue 或 Pull Request。
项目地址：https://github.com/cdcp998/Zontes_Motorcycle-ha
GPL-3.0 license