OBD 参数与设备绑定 #

所有选中的 OBD 参数都位于 $data.current.obd[id]，包括标准 OBDII 模板生成的参数。基础驾驶字段仍位于 $data.current 外层。选择入口见选择需要的数据。

读数结构 #

value 可以是有限数值、文本或布尔值，由参数的解码配置决定。单位字符串统一小写，例如 rpm、°c。有效的 0、空字符串和 false 不会因为值为假而被替换为缺测。

function main() {
  // 替换为仪表设置中选中的实际参数 ID。
  const reading = $data.current.obd?.['a1b2c3d4'];
  const value = reading?.value ?? null;
  const text = value === null ? '—'
    : typeof value === 'number' ? value.toFixed(0)
    : String(value);
  return <VStack spacing={4}>
    <Text color={$env.foreground} fontSize={48}>{text}</Text>
    <Text color={$env.accent}>{reading?.unit ?? ''}</Text>
  </VStack>;
}

只有确认值为数字之后才能使用 toFixed()。不要用 value || '—'，否则会丢失零值与布尔假值。

参数属于哪台设备 #

在设置中选择某台设备的参数，会把来源设备与参数一起保存。脚本路径使用参数 ID；清单中的设备限定声明形如 device/<设备 UUID>/<参数 ID>。

同名或相同 ID 的其他设备不能代替来源设备提供读数。更换设备、导入他人的仪表包或删除参数配置后，应重新检查数据选择和脚本路径。导入包会保留原始绑定，不会自动映射到接收者的车辆。

无法解析的选择会保留为“无法找到对应数据”，脚本访问路径仍可查看。确认设置不会自动删除它；主动取消选择后才会移除。恢复原设备或参数引用后，名称可以恢复。

有效期与失败 #

成功解码后，App 在内存中保存该参数最近一次有效值和当时的单位。有效期为读取间隔的 3 倍，最少 1 秒。等待下一次查询或不再显示卡片，都不会刷新采集时间或延长这次读数的有效期。

• 新查询成功：更新值、单位与采集时间。
• 查询无数据、失败或无法解码：受影响参数立即变为 null。
• 读数过期：参数变为 null。
• 设备断连：清空该设备所有参数的缓存，其他设备不受影响。
• App 重启：不恢复这些缓存。

切换设备 #

正常使用时只有一台 OBD 设备提供实时数据。手动切换时，旧设备继续连接和查询，App 先连接并初始化新设备。

新设备准备成功后，App 才切换数据来源、断开旧设备并清空旧设备的参数。新设备连接失败时，保留旧设备及其有效读数；连续选择其他设备会取消尚未完成的切换。

仪表绑定的来源保持不变：切换到另一台设备不会让旧设备的参数自动读取新设备的同名项。

基础数据替换与历史 #

如果 App 已配置用 OBD 参数替换基础车速等数据，$data.current.speed 表示最终采用的基础车速。独立选中的原始 OBD 参数仍通过 current.obd[id] 读取，两者的声明用途不同。

$data.history 只包含基础驾驶数据，不包含 obd。参数的短期缓存也不是历史记录，不能用它恢复一整段行程的 OBD 曲线。

编辑器预览 #

OBD 预览使用设备保存的参数配置，不连接车辆：有文本映射时取一个确定的映射结果；否则使用配置上下界的中值、唯一边界，或在没有边界时返回 null。即使设备未连接，也可以预览这些样本。

预览能帮助检查格式和布局。真实适配器连接、查询响应与车辆兼容性需要在实际设备和车辆上确认。