Skip to content

About

理想汽车 Home Assistant 集成 —— 实时车辆状态 + 远程控制 + Lovelace 卡片

Topics

Resources

Contributing

Stars

21 stars

Watchers

0 watching

Forks

Repository files navigation

Li Auto for Home Assistant

理想汽车(Li Auto)Home Assistant 集成 —— 实时车辆状态 + 远程控制。

Validate HACS Custom License Version

理想汽车全系车型(L6 / L7 / L8 / L9 / MEGA / i 系列 / 理想 ONE)均已验证可用。

本项目为个人学习 / 研究用途,非理想汽车官方项目,未获官方授权。 使用可能违反理想汽车的服务条款,所有风险由使用者自行承担。 请勿用于商业用途,请勿公开你的账号、车辆、位置等敏感信息。


目录


功能

实时状态

覆盖 198 个车辆信号,包括电量、续航里程、门锁、车窗、轮胎压力、 车内外温度、充电状态、车辆位置、座椅加热通风、空调状态等。

不同车型的数据来源自动适配:新平台车型走 VSS 信号服务, 理想 ONE 等老平台车型走 real-time-state 接口,对使用者透明。

远程控制

锁车 / 解锁、前备箱、尾门、车窗、空调(开关、温度设定、快速制热制冷、 除霜)、座椅加热与通风(8 个座位、含档位)、方向盘加热、 远程启动与停止、寻车(闪灯 / 鸣笛)、远程拍照、哨兵模式。

新平台车型的车控走 cmd/send 通道;理想 ONE 走 send-command 通道。 两条通道均由本集成自动选择,无需手动配置。

理想 ONE 的空调与座椅控制,在实现时按官方 App 的命令结构单独适配 (m01_control 模块),已可正常使用。

车型与账号自适应

  • 车型自适应 —— 自动读取服务端下发的车型能力表, 车上没有的功能不会创建对应实体,避免出现"点了没反应"的入口。
  • 账号自适应 —— 自动识别车主、家人共享、试驾等账号角色, 对服务端限制的功能给出明确说明,而不是静默失败。
  • 多车支持 —— 一个账号下的多辆车各自独立接入,互不干扰。

任务大师

读取车机端的「任务大师」任务列表,支持创建、更新、删除、启停任务。

  • sensor.任务大师 —— 只读汇总:任务总数、启用数、每个任务的名称/启停/条件动作摘要
  • 服务 get_tasks / create_task / update_task / delete_task —— 按需调用

v1.7 起不再为每个任务生成启停开关实体。 旧实体的启停走 update-task 全量回传,用的是集成缓存里的任务快照(10 分钟轮询), 在 App 改完任务后再点 HA 开关会把旧快照覆盖回线上,冲掉 App 上的修改。 要启停任务请用 lixiang_auto.update_task(只传 config_id + enabled), 它会先拉线上最新再只改该字段。

前端卡片

提供理想 App 风格的车控页面卡片,支持:

  • 零配置 —— 自动发现实体,无需手填
  • 深色玻璃风格 —— 3D 车模 + 高德地图
  • 卡片拖拽排序 —— 长按拖动即可调整卡片位置,顺序本地保存

详见 前端卡片。

已实现的远程控制

功能 状态
锁车 / 解锁 ✅ 全系
前备箱 / 尾门 / 车窗(含位置) ✅ 全系
空调(开关 / 温度 / 快速制热制冷 / 除霜) ✅ 全系
座椅加热与通风(含档位) ✅ L / i / X 系
✅ 理想 ONE(8 个:六座无二排中)
方向盘加热 ✅ 全系
远程启动 / 停止 ✅ 全系
寻车(闪灯 / 鸣笛) ✅ L / i / X 系
远程拍照 ✅ 全系
哨兵模式开关 ✅ 全系
充电启停 ✅ 理想 ONE
充电上限 / 电池保温 / 预约充电 / 预约空调 ✅ 理想 ONE
唤醒车辆 ✅ 全系

安装

方式一:HACS(推荐)

  1. 打开 HACS → 集成 → 右上角 ⋮ → 自定义存储库
  2. 添加仓库地址,类型选择 Integration
  3. 搜索 Li Auto 并下载
  4. 重启 Home Assistant

方式二:手动

将 custom_components/lixiang_auto 目录复制到 HA 配置目录下:

config/
└── custom_components/
    └── lixiang_auto/

然后重启 Home Assistant。

车辆外观图(默认自带,无需配置)

首页顶部那张车模图默认走官方静态图,零配置:

卡片 → GET /lixiang_auto/car-image.json
     → 后端按车型/车漆返回官方图 URL(p.ampmake.com)
     → 后端按需下载并缓存 → 卡片 <img> 引用

全自动:车型与颜色都由服务端识别,用户不需要任何设置。

关于 3D 车模(当前不可用,请勿开启)

⚠️ 实测状态:car_3d: true 目前是死开关。

卡片会去加载 /lixiang_auto/lixiang-3d/index.html, 但该查看器页面并不随集成分发(www/lixiang-3d/ 在集成包内不存在), 因此开启后该区域只会白屏/404,不会显示任何 3D 车模。 请保持默认 car_3d: false,使用官方静态车模图(本节上半部分)。

历史原因:早期版本曾内置一个基于 <model-viewer> 的查看器, 依赖约 45 MB 的 carmodel.glb(从理想 App Unity bundle 提取)。 该资源体积过大且无法随 HACS 分发,查看器已从集成中移除, 仅保留了代码里的旧路径分支(默认不启用)。

若你自行实现查看器,需要同时准备:

config/
├── www/lixiang-3d/carmodel.glb                  ← 3D 模型(约 45 MB)
└── custom_components/lixiang_auto/www/lixiang-3d/index.html   ← 查看器页面

carmodel.glb 是理想官方 App 的 3D 资源,仅供个人自用; 集成不包含、也不分发该文件。


配置

  1. 进入 设置 → 设备与服务 → 添加集成,搜索 Li Auto
  2. 输入理想汽车账号与密码
  3. 首次登录需要在弹出的辅助页面中完成验证(短信验证码)
  4. VIN 会自动从账号获取,无需手动填写

登录身份

身份 说明
理想汽车 主应用账号,功能最全
理想同学 独立客户端账号,仅支持其范围内的功能

轮询间隔

默认 60 秒。可对以下类别单独调整:

  • 实时状态 —— 默认 60 秒
  • 配置类(很少变动)—— 默认 1 小时
  • OTA / 保养 —— 默认 24 小时

车辆休眠时自动跳过轮询,节省流量并降低账号风控风险。


实体

共 198 个信号定义。实际启用的实体数量取决于车型与账号权限, 典型情况下理想 L6 约 174 个、理想 ONE 约 71 个。

平台 说明
sensor 电量、续航、温度、胎压、充电、车外温度等
binary_sensor 门锁、车窗、充电枪、各类告警
fan 座椅加热 / 通风(关闭 / 低 / 中 / 高 档位)
switch 快速制热、快速制冷、除霜、哨兵、方向盘加热、充电相关
button 寻车、授权驾驶、闪灯、鸣笛、远程拍照
cover 尾门、全车窗(支持开合与位置读回)
number 空调设定温度、充电上限
select 空调控制类型、充电模式
time 充电开始 / 结束时间
climate 空调(温度与模式)
lock 车锁
device_tracker 车辆位置

域选择说明:座椅加热通风使用 fan(原生档位 UI); 尾门车窗使用 cover(支持位置,无需拆成多个开关); 哨兵与快捷空调功能使用 switch(开关状态一目了然)。

诊断类实体(OTA、保养、版本等)默认隐藏,需要时可在设备页面启用。


服务

所有服务都可通过 开发者工具 → 动作 调用。

日常使用

服务 说明
lixiang_auto.refresh 立即刷新一次数据
lixiang_auto.wakeup 唤醒休眠中的车辆

数据查询

服务 说明
lixiang_auto.get_travel 查询行程与陪伴里程
lixiang_auto.get_charge 查询充电记录
lixiang_auto.get_svm_photo 查询驻车照片
lixiang_auto.dump_ability 导出本车能力表(排查功能缺失)
lixiang_auto.dump_realtime_state 导出原始状态响应(排查数据异常)

任务大师

服务 说明
lixiang_auto.get_tasks 查询任务列表
lixiang_auto.create_task 创建任务
lixiang_auto.update_task 更新/启停任务(只传要改的字段;先拉线上最新再合并,不会用旧快照覆盖)
lixiang_auto.delete_task 删除任务

车控排障

车控不正常时,用 lixiang_auto.probe_send_command 定位问题:

service: lixiang_auto.probe_send_command
返回结果 含义
「命令不存在」类 通道正常,只是命令参数需要调整
100035 / access_denied 通道被拒绝,需要检查账号权限

该服务不会对车辆执行任何操作,可放心使用。

除 wakeup / refresh 外,其余服务都支持可选的 vin 字段, 用于在多车场景中指定车辆;单车时省略即可。


前端卡片

集成提供理想 App 风格的车控页面卡片。

零配置使用

type: custom:lixiang-app-home-card
title: 理想汽车

实体自动发现,无需手填。

可选卡片

卡片 说明
custom:lixiang-app-home-card 车控主页(3D 车模 + 快捷操作 + 空调 + 地图)
custom:lixiang-overview-card 车辆总览(深色玻璃风格)
custom:lixiang-bindings-card 查看实体绑定关系

卡片操作

  • 点击卡片 —— 进入对应的二级页面(空调、地图等)
  • 长按 350ms 拖动 —— 调整卡片位置,支持跨组互换,顺序本地保存

特性

  • 自动发现实体,按中文名匹配
  • 自动识别车型与配置等级
  • 不可用的功能置灰并说明原因,不会静默失败
  • 键盘可达、aria-label 齐全、尊重 prefers-reduced-motion
  • 图标字体缺失时优雅降级,功能不受影响

📖 完整卡片文档见 docs/CARDS.md


故障排查

车控点击后提示失败

调用 lixiang_auto.probe_send_command 看返回结果, 按上文 车控排障 判断是通道问题还是参数问题。

首次登录要求短信验证

理想的风控机制要求受信任设备。若反复要求短信验证:

  1. 先在手机理想 App 上登录一次该账号
  2. 等待约 30 秒让服务端同步信任状态
  3. 回到 HA 重新提交

手机 App 被登出

集成与手机 App 使用同一套登录会话机制,通过复用登录会话 (持久化登录会话)保持在线,不会反复重新登录。

若发现手机上的理想 App 被登出,通常是以下原因:

原因 说明
在 HA 中重新登录 重新登录会让旧的登录凭证失效
服务端主动过期 长时间未使用或触发风控时,服务端会要求重新验证
多地同时登录 理想账号不支持长期多点在线

解决办法:在手机 App 上重新登录一次即可,HA 侧会自动恢复。

实体显示 unknown

  1. 确认车辆已联网(休眠中的车辆不上报数据)
  2. 调用 lixiang_auto.dump_ability 确认本车是否支持该功能
  3. 开启调试日志查看具体取值过程

启用调试日志

logger:
  default: warning
  logs:
    custom_components.lixiang_auto: debug

导出诊断信息

调用 lixiang_auto.dump_ability 与 lixiang_auto.dump_realtime_state, 把返回结果连同问题描述一起提交 Issue,可大幅加快定位。


已知限制

项 L / i / X 系 理想 ONE
充电控制 状态可读,控制不可用(受长连接限制) ✅ 可用
场景模式 / 冰箱预约 未实现 未实现
宠物模式 / 洗车模式 未实现 未实现
左右滑门 未实现 未实现
远程闪灯 / 鸣笛 ✅ 已实现 未实现
蓝牙启动 — 未实现
自动泊车 / 蓝牙尾门 — 未实现
哨兵视图(实时画面) 未实现 未实现
OTA 相关 无数据(服务端按账号拦截) 无数据
行程自定义查询 不可用 该车型无行程服务
按时出发 只读 只读
长连接(LiNdn) 未打通 不需要

对状态可读但控制不可用的功能,集成会在实体属性中标注原因, 点击时给出明确提示,不会静默失败。


升级注意

历史版本调整过部分实体的命名与归类。升级后如发现实体消失, 请在设备页面检查是否有被禁用的实体,或参考 CHANGELOG.md 中的「升级注意」章节。


项目状态

验证范围

项 状态
车型 ✅ 全系车型已验证(L6 / L7 / L8 / L9 / MEGA / i 系列 / 理想 ONE)
账号 ✅ 车主账号、✅ 家人共享账号
多车 ✅ 一个账号多辆车
M 系车控 ✅ 真机验证通过
单元测试 ✅ 2519 个通过
拖拽交互 ✅ 真实浏览器环境验证通过

测试

python -m pytest tests/ -q          # 单元测试
node tests/test_drag_browser.mjs    # 拖拽交互(无头浏览器)

开发

本地检查

python -m py_compile custom_components/lixiang_auto/*.py   # 语法
python -m pytest tests/ -q                                  # 测试

可安装 pre-commit hook,在提交前自动检查语法、JSON 与敏感信息。

敏感信息

仓库禁止提交真实 VIN、手机号、内网 IP、账号密码等。 测试与文档中请使用脱敏数据(如 HLX32XXXXXXXXXXXX)。 CI 会在每次推送时扫描,命中即失败。


更新日志

详见 CHANGELOG.md。


许可

MIT

About

理想汽车 Home Assistant 集成 —— 实时车辆状态 + 远程控制 + Lovelace 卡片

Topics

Resources

Contributing

Stars

21 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages