洛汐文档库

外观

system.digitalkey

约 1003 字大约 3 分钟

2026-07-15

数字车钥匙系统桥，后端是 DKF/ICCOA 服务、蓝牙栈和安全单元。可用于创建和激活车钥匙、处理 APDU、订阅车辆状态并发送远程无钥匙进入（RKE）动作。

import digitalkey from '@system.digitalkey'

警告

这是安全关键接口。错误调用可能导致钥匙停用、删除、车辆连接中断或安全单元状态不一致。不要在没有车厂协议、帐号授权及恢复流程时调用写操作。

回调约定

除事件属性外，方法采用 options 对象和 success/fail/complete 回调：

interface Callbacks<T = object> {
  success?: (data: T) => void
  fail?: (data: object, code?: number) => void
  complete?: () => void
}

固件还注册了 onscanresult、onconnect、ondisconnect、onkeyactive 和 onvehicleconnectionstatechange 事件属性。预装应用主要使用订阅方法与 onkeyactive。

服务与扫描

getDkfInfo(options?)

读取 DKF 服务和安全单元基础信息。预装应用从成功结果使用 dkAttestation，并把它交给云端钥匙激活流程。

digitalkey.getDkfInfo({
  success(info) { console.log('DKF ready', Boolean(info)) },
  fail(data, code) { console.error(code) }
})

startScan(options) / stopScan()

startScan(options: Callbacks & {
  keyId: string
  timeout?: number
}): void

stopScan(): void

keyId 必需；原生实现还校验 timeout 必须是数值。扫描结果通过成功回调或 onscanresult 到达。

蓝牙连接

connect(options: Callbacks & { address: string }): void
disconnect(options: Callbacks & { address: string }): void
getVehicleConnectionState(options: Callbacks & { keyId: string }): void

address 是扫描得到的车辆蓝牙地址。连接状态还会通过 onconnect、ondisconnect 或车辆状态订阅回调更新。

钥匙生命周期

createKey(options: Callbacks & {
  vid?: string
  vehicleId?: string
  vehicleOEMId?: string
}): void

enableKey(options: Callbacks & { keyId: string }): void
disableKey(options: Callbacks & { keyId: string }): void
deleteKey(options: Callbacks & { keyId: string }): void
getKeyActivedData(options: Callbacks & { keyId: string }): void
getKeyInfo(options: Callbacks & { keyId?: string }): void
字段/方法说明
vid / vehicleId / vehicleOEMId创建钥匙的车辆标识；原生实现要求这组标识完整到足以定位车辆，预装应用同时传入 vehicleId 和 vehicleOEMId
enableKey重新启用已存在的本地钥匙
disableKey暂停钥匙，不删除安全材料
deleteKey删除本地钥匙；通常还需同步云端状态
getKeyActivedData读取激活流程所需数据
getKeyInfo读取本地钥匙/安全单元信息；预装应用使用结果中的 seCplc/cplc
digitalkey.createKey({
  vehicleId: 'vehicle-id-from-cloud',
  vehicleOEMId: 'oem-id-from-cloud',
  success(data) { console.log('created') },
  fail(data, code) { console.error('createKey', code) }
})

安全单元 APDU

requestApplet(options)

requestApplet(options: Callbacks & {
  data: string | ArrayBuffer
}): void

data 必需。预装应用按云端下发的 APDU 序列逐项调用，并检查 responseData 与 responseSw。输入格式、分包和允许的 APDU 都由 DKF/车厂协议决定，不应使用任意命令探测安全单元。

setVehicleBleMac(options)

setVehicleBleMac(options: Callbacks & {
  keyId: string
  mac: string
}): void

keyId 和 mac 都必需，用于把云端/扫描取得的车辆蓝牙地址绑定到钥匙。

RKE 动作

requestRKEAction(options: Callbacks & {
  keyId: string
  functionId: number
  actionId: number
  isConsecutive?: boolean
}): void

keyId、functionId、actionId 必需。固件还检查 isConsecutive 的类型。动作编号属于车辆协议，不能把不同品牌或车型的编号互换。

digitalkey.requestRKEAction({
  keyId,
  functionId,
  actionId,
  isConsecutive: false,
  success(data) { console.log('RKE accepted') },
  fail(data, code) { console.error('RKE failed', code) }
})

成功回调只说明请求被 DKF 接收；车辆是否执行还应从后续状态消息确认。

状态订阅

subscribeKeyStatus(options: Callbacks & {
  keyId: string
  callback?: (status: object) => void
}): void

unsubscribeKeyStatus(options: { keyId: string } | string): void

subscribeVehicleStatus(options: Callbacks & {
  keyId: string
  callback?: (status: object) => void
}): void

unsubscribeVehicleStatus(options: { keyId: string } | string): void

两个订阅均强制要求 keyId。预装应用从车辆状态中处理 entityId、entityStatus、entityStatusUnit、timeStamp 等字段；字段语义仍由车厂协议定义。

digitalkey.subscribeVehicleStatus({
  keyId,
  callback(status) {
    // 先按车辆协议检查时间戳与实体编号，再更新 UI。
  }
})

// 页面销毁时
digitalkey.unsubscribeVehicleStatus({ keyId })
digitalkey.unsubscribeKeyStatus({ keyId })
digitalkey.stopScan()

完整成员清单

类别成员
服务信息getDkfInfo
扫描/连接startScan、stopScan、connect、disconnect、getVehicleConnectionState
钥匙createKey、enableKey、disableKey、deleteKey、getKeyActivedData、getKeyInfo
安全单元/车辆requestApplet、setVehicleBleMac、requestRKEAction
订阅subscribeKeyStatus、unsubscribeKeyStatus、subscribeVehicleStatus、unsubscribeVehicleStatus
事件onscanresult、onconnect、ondisconnect、onkeyactive、onvehicleconnectionstatechange

机型可用性

Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
❌△

获取源代码

  • openvela Feature Framework 当前没有公开该厂商数字钥匙模块的 JIDL 或 C++ 实现。
  • Feature Framework 仓库