Demo 调试应用¶
最后更新：
EVCC API Demo 是一款独立 Android 调试应用，用来从第三方应用的视角检查 EVCC 开放 API。
即使不了解 EVCC 内部结构，也可以按“连接与全局检查 → 请求与响应 → 实时监听”依次确认应用授权、
Binder 会话、属性解析和事件回调是否正常。
Demo 同时提供推荐的 SDK 模式和底层 Raw AIDL 模式。同一项请求在两种模式下表现不同，通常 说明问题位于客户端 SDK；两种模式都失败时，再检查 EVCC 授权、服务状态和车辆属性源。
获取方式¶
- 下载页提供可独立编译的源码 ZIP；Demo 测试 APK 只有在使用独立于 EVCC 的证书签名并通过校验后才会上线。
- 源码 ZIP 不包含 EVCC 主应用源码、生产签名、JKS、证书文件、签名配置、口令、本机配置和构建产物。
- Demo 测试 APK 的包名为
com.kooo.evccapi.demo；本地 Debug 为com.kooo.evccapi.demo.debug。二者使用不同签名和不同包名，可以并行安装，但必须分别在 EVCC 中授权。下载清单没有“Demo 测试 APK”条目时表示官网 APK 尚未发布。 - 官网测试 APK 的普通测试证书私钥会在签名后销毁；安装不同版本或证书前，需要卸载旧包再安装并重新授权。
本地构建¶
解压后安装 JDK 17 与 Android SDK 36：
源码工程没有 Release signingConfig。请勿把个人或 EVCC 生产密钥复制进示例工程。
首次测试¶
- 安装 EVCC 和 Demo。
- 打开 EVCC → 服务 → 实验功能 → EVCC 开放 API → 开放 API 控制台 → 开放权限的应用。
- 勾选当前 Demo，首次弹窗选择“只读”或“标准联动”。 当前源码 Demo 也可点击“打开 EVCC 开放 API”直接进入自身授权窗口，不支持该入口时回退到控制台。
- 回到 Demo，先选 SDK 模式并连接。
- 运行“一键只读自检”，确认协议、授权、能力、五源状态、普通目录、属性解析/读取和变量读取。
- 在“请求与响应”中填写真实属性并读取一次，再到“实时监听”应用同一选择器，确认收到初始快照。
- 需要写入、动作、Shell 或全量扫描时，在 EVCC 中单独增加相应权限，再逐项测试。
“全部权限”预设包含敏感权限，保存新增敏感权限时须确认风险；系统写入仍需逐次确认。跳转入口本身 不会选择预设或保存授权。调用方式见第三方应用跳转入口。
调试工作台¶
1. 连接与全局检查¶
这一部分先判断“链路整体是否可用”，不要求预先知道具体属性 ID：
- 选择 SDK 或 Raw AIDL 后连接，查看当前 Binder 与会话状态。
- “协议与权限”显示 EVCC 版本、协议版本、Demo 包名、UID、本应用证书 SHA-256、授权预设和权限集合。
- “查询能力”读取当前会话真正可调用的能力；按钮存在不代表已获对应权限。
- “查询六源状态”分别显示 VHAL、APVP、Vehicle AIDL、CAPI、AdaptAPI 和 SOA 的启用、连接与来源代次。
- 普通目录支持首页、下一页和重置分页；目录分页期间不要改变查询条件。
- “一键只读自检”按固定顺序检查会话、能力、来源、目录、一个可用属性及一个可用变量。它不会写入、 执行动作、启动全量扫描或执行 Shell，也不会留下新的属性监听。
- “开发中心”打开与当前 API 配套的接口参考、权限说明、数据模型和错误码。
全量扫描不是普通健康检查：它可能重建 APVP 订阅，并受独立权限、限频和超时控制。只有确实需要 发现实时完整目录时才使用。
2. 请求与响应¶
属性选择器支持以下字段：
| 字段 | 填写方式 | 说明 |
|---|---|---|
| 属性 ID | 十进制或 0x 十六进制 |
与精确名称二选一 |
| 精确名称 | 目录返回的完整名称 | 与属性 ID 二选一，不做模糊匹配 |
| 来源 | AUTO、VHAL、APVP、VEHICLE_AIDL、CAPI、ADAPT_API 或 SOA |
留空等同 AUTO；返回值会标明实际来源 |
| 区域 | 十进制区域 ID，可留空 | 多个区域都可能匹配时，服务会返回区域歧义而不是猜测 |
先用“解析”查看候选项和最终选源，再执行缓存读取或强制读取。强制读取会访问上游，不适合高频轮询。
批量缓存读取每行使用一个与监听区相同的 selector，最多 100 项；它不会强制刷新上游，适合验证
readProperties() 的逐项返回和 Binder 序列化。写入前先预检查；批量写入格式为每行
属性ID=字符串值，结果逐项返回且不是事务，前面成功的项目不会因为后续失败而回滚。
“最近一次请求 / 响应”独立显示连接方式、操作、实际请求和结构化返回，便于复制对照接口文档；实时 回调和连续审计信息仍写入事件日志，不会把单次响应淹没。
3. 实时监听¶
多属性监听框每行填写一个选择器，提交时会整批替换当前属性监听集合。紧凑格式为：
示例：
数字形式的属性名可能被当成 ID。需要消除歧义或提高可读性时，推荐键值格式：
可以使用 # 开头的注释行。“应用属性监听”提交完整集合，“清空属性监听”取消全部属性监听。监听状态
会显示已请求/接受/失败数量和最后事件；初始可用值以 INITIAL_SNAPSHOT 到达，后续变化持续写入事件
日志。SDK 重连会恢复最后一次成功的完整集合；Raw AIDL 断连后需要重新连接并再次提交。
“当前属性快捷监听”用于只测试上方请求区的单个选择器；它与多行监听使用同一个会话集合，后一次提交 会覆盖前一次，而不是追加。
SDK 模式¶
用于验证推荐接入：
- 自动退避重连。
- 会话恢复。
- 属性和变量订阅整批恢复。
- 序号缺口检测与
onResyncRequired。
如果 EVCC 重启，SDK 模式应显示断开、等待重试、重新建立会话并恢复监听。 打开开发中心、EVCC 授权页或系统文件选择器后，Demo 会在返回前台时恢复此前由用户发起的 SDK 连接。
Raw AIDL 模式¶
直接调用 IEvccApi、IEvccApiSession 和 IEvccApiCallback：
- 不自动重连。
- 清楚显示 Binder 建立、会话、Parcelable 和回调步骤。
- 适合确认问题位于客户端 SDK 还是底层服务。
Raw 模式断连后需要手动重绑，这是故意设计的调试行为，不是正式应用的推荐体验。
Demo 会保留最后一次监听请求并标记 needsReapply，方便重新连接后按原集合再次提交。
手机与车机布局¶
- 手机竖屏按三个调试区依次纵向排列，页面和日志均可滚动，底部控制台不会被屏幕高度裁掉。
- 车机或大屏横屏使用工作台与事件日志分栏，按钮、文字和点击区域会随屏幕密度与可用宽度调整。
- 布局变化不改变会话和测试含义；对比两台设备时应以日志中的包名、UID、证书和授权集合区分客户端。
日志与安全¶
- Demo 不申请网络、存储、Root、Car API 或
QUERY_ALL_PACKAGES。 - Activity停止后解绑，不注册开机广播或后台常驻服务。
- “最近一次请求 / 响应”和导出日志默认隐藏属性值与 Shell 输入输出；只有显式选择包含原始内容时才保留。
- 写入、动作、全量扫描和 Shell 不进入默认自检，必须用户二次确认。
- Demo 不预置危险命令或一键车辆控制。
独立编译成功只证明示例工程完整；跨 UID授权、撤权、订阅恢复、车辆属性和 APVP 行为仍须在真机验证。
API 1.1 音乐能力¶
Demo 1.1.0 增加“音乐与歌词”入口，支持 state/listen/stop/lyrics/artwork 和播放命令，validate 前缀进行预检查。SDK 与 Raw AIDL 两种模式均使用真实 Binder；资源预览最多显示 65536 字符。
API 1.2 音量组¶
SDK 和 Demo 1.2.0 提供查询、读取、设置和增减，包含 Java/Kotlin 示例。先确认协议与独立音量权限；旧服务返回 UNSUPPORTED，重连不重放写入。见音量组接入说明。