EVCC 开放 API：接入与快速开始¶

最后更新：2026-10-11

EVCC 开放 API 是 EVCC 对第三方 Android 应用提供的标准 AIDL 接口。产品界面和调试控制台统一称为 EVCC 开放 API；代码、Binder Action 和 SDK 中使用 EvccApi，当前协议版本为 1.3。

它允许经过车机用户授权的应用读取和监听 EVCC 已启用属性源中的属性、访问变量、执行受控写入和动作，并在独立高风险授权下使用 Shell。接口不要求第三方直接管理五种车辆属性源或 APVP 链路生命周期。

它不是网络 API

EvccApi 是 Android Binder/AIDL 接口，只能由车机上的 Android 应用调用。本文档网站、网页辅助调试台以及云端服务器都不能直接连接车辆 Binder，也不能从浏览器执行 Shell。

最短接入流程¶

在应用 Manifest 声明普通权限并让系统可以发现 EVCC。
使用公开 evccapi-contract 与 evccapi-client，或复制 Demo 中的 Raw AIDL 接入代码。
引导用户进入 EVCC → 服务 → 实验功能 → EVCC 开放 API → 开放 API 控制台。
用户在“开放权限的应用”中勾选应用并确认权限预设。
绑定 com.kooo.evcc.evccapi.BIND，校验 API 主版本后建立会话。
在工作线程执行可能阻塞的读取、目录和写入调用。

源码包中的 SDK 是两个独立 Android library module。将它们复制到工程后，在 settings.gradle.kts 中加入模块，并让应用只依赖客户端模块：

// settings.gradle.kts
include(":evccapi-contract", ":evccapi-client")

// app/build.gradle.kts
dependencies {
    implementation(project(":evccapi-client"))
}

evccapi-client 会通过 api(project(":evccapi-contract")) 暴露公开模型，不依赖 EVCC 主应用、 Car API 或私有资源。公开 Demo/SDK 源码采用 Apache-2.0；这不改变 EVCC 主应用其他源码的授权状态。

<uses-permission android:name="com.kooo.evcc.permission.ACCESS_EVCC_API" />

<queries>
    <package android:name="com.kooo.evcc" />
</queries>

Manifest 权限只允许应用发现并请求绑定。EVCC 仍会按调用 UID、包名、当前签名证书摘要和用户授权修订号检查每个会话及每次调用。

推荐：客户端 SDK¶

val client = EvccApiClient(applicationContext, listener = object : EvccApiClient.Listener {
    override fun onSessionReady(apiInfo: EvccApiInfo, sessionInfo: EvccSessionInfo) {
        // 已建立授权会话；耗时调用请切换到后台线程。
    }

    override fun onResyncRequired(expectedSequence: Long, actualSequence: Long) {
        // 重新读取当前状态，并重新提交需要的订阅集合。
    }
})

client.connect()

SDK负责 Binder death、1/2/5/10/30 秒退避重连、会话重建、属性与变量订阅整批恢复以及事件序号缺口检测。发生缺口时 SDK 会自动重新提交最后一次成功的订阅集合以获得新初始快照，同时通过 onResyncRequired 通知业务暂停旧的增量基线。应用不再需要连接时调用 client.close()。

直接读取属性¶

val selector = EvccPropertySelector(
    id = 557849089L,
    source = EvccApiContract.Source.AUTO,
)
val record = withContext(Dispatchers.IO) {
    client.readProperty(selector, forceRefresh = false)
}
if (record.status == EvccApiContract.Status.AVAILABLE) {
    val typed = record.value
    val actualSource = record.resolvedSource
}

AUTO 查询顺序固定为 ECARX_VHAL → VHAL → APVP → VEHICLE_AIDL → CAPI → ADAPT_API → SOA → GEELY_CAPI → GEELY_AIDL。 ECARX_VHAL 只在领克 900（L946）的精确车型配置中可用，其他车型会直接跳过。返回值始终携带实际命中的来源；不要假定同一属性在所有车型上都来自相同链路。

兼容与限制¶

客户端必须校验 apiMajor；主版本不同应停止调用并提示升级。
契约的 Binder 单次上限为 512 KiB；服务会预留传输开销并按约 480 KiB 的有效预算裁剪结果，超大单条记录返回 PAYLOAD_TOO_LARGE。目录必须使用 pageToken + snapshotToken 分页，默认每页 100、请求上限 500，实际每页可能因字节预算提前结束。
批量写入按顺序逐项执行，但不是事务，后续失败不会回滚先前成功项。
EVCC 只使用用户已经开启的属性源，不会因普通读取偷偷开启用户关闭的数据源。
APVP 新增按需属性可能触发一次必要的链路重建；请整批替换订阅，避免逐项频繁增加。

固定资源占用¶

EvccApi 是同进程、纯绑定、按需创建的能力入口。没有可用授权或云端隐藏时 Binder 组件禁用；首个授权会话之前不创建属性运行时，空闲会话也不会自行启动属性源、自动化、Root、全量目录或网络连接。来源只随实际读写/监听/扫描取得引用，空闲后释放 EvccApi 自己的引用，不干扰 EVCC 其他功能的共享连接。具体 PSS 和延迟受车机系统与已开启来源影响，文档中的资源目标必须以 Release 包真机测量为准。

接下来建议依次阅读权限与授权、属性模型和初始化与监听。

API 1.1 音乐能力¶

API 1.1 新增歌曲、当前行、完整歌词、封面、已有 BPM 和播放控制。先确认 apiMinor>=1 和用户授予的音乐权限，见音乐与歌词。

API 1.2 音量组¶

EVCC 3.2.17 新增音量组查询、读取、绝对设置与相对增减。客户端先确认 apiMinor >= 2，并检查独立的 volume.read / volume.control 权限，见音量组。写入返回下发目标，当前值需显式读取；已有授权不自动增加权限。

API 1.4 ECARX 原生 VHAL 属性源¶

API 1.4 新增稳定来源 ID ECARX_VHAL。它在领克 900（L946）通过 EVCC 的 shell RootService 直接连接系统 android.hardware.automotive.vehicle@2.0::IVehicle/default：目录、读取、HIDL callback、写入及读回均属于同一原生 VHAL 会话，不依赖 EAS、CAPI 或 UID 0。接口继续复用既有属性 API，不增加 AIDL 方法或 Parcelable 字段。写入只发送一次；超时或无法读回时调用方必须按结果未知处理，重新读取后再决定下一步。