OBD 车辆数据

OBD 用于读取车辆控制器提供的数据。车辆控制器也称 ECU，负责发动机、变速箱等系统；CapDrive 通过适配器向这些控制器发送请求，再把收到的数据换算成读数。

App 中的一个“参数”就是一项要读取和显示的数据，例如发动机转速、冷却液温度或某个状态。它保存读取请求、换算公式和单位。数值参数可用于数字、进度或曲线；状态参数可以通过文本映射显示为 D、P 等文字。

例如，冷却液温度参数可以使用请求 0105 取得一个数据字节 A，按 A - 40 换算。若返回字节的十进制值为 123，结果就是 83 °C。连接方式、请求定义和换算规则都正确，才能得到可用读数。

车辆支持哪些参数，取决于车型、年款、动力系统及控制器状态。只有车辆实际提供的值才能被读取，修改名称或单位不会增加车辆本身的数据能力。

车辆 OBD 连接需要 CapDrive Plus、支持 ELM327 指令的 蓝牙低功耗（BLE）适配器，以及 iPhone 的蓝牙权限。当前不支持经典蓝牙和 Wi-Fi 适配器。

适配器插入车辆 OBD 接口并按车辆要求通电后，App 才能与车辆通信。某些参数要求车辆处于特定状态，例如控制器已通电、发动机运行或相应系统处于工作状态。适配器名称中包含“蓝牙”，并不能单独证明它符合 BLE 与指令要求。

可以在参数列表或参数编辑器中查看、测试 OBD 读数，不需要先开始一段行程。手机行程是否已开始，不决定车辆会不会返回水温、转速等参数。

CapDrive 支持配置十六进制服务 01、21、22 的读取请求。普通使用可采用与车辆匹配的预设；具体请求地址和公式以预设或车辆参数定义为准。

入口：更多（…）→ 车辆OBD连接。 设备页显示附近适配器与已保存设备，设备设置中保存该适配器的参数配置。

首次连接与重连

首次连接时，App 会建立蓝牙通信、初始化适配器、识别车辆协议，并查询车辆报告支持的标准参数。成功后将可初始化的标准参数加入该设备列表。标准参数是否在当前状态有值，还需要看实际读取结果。

已有设备重连时继续使用原来的配置，包括修改过的参数和主动清空的列表。删除参数后，重连不会把它重新加回来。需要补充读数时，可导入预设或新增参数。

当前数据源

“当前设备”指正在向 CapDrive 提供车辆数据的那台适配器。同一时间只有一台设备作为当前数据源。各台设备的参数和设置独立保存；换到另一台设备时，不会自动沿用前一台设备的参数引用。

断开连接会保留配置。忽略设备会移除该设备的配置与缓存。需要迁移参数时可导出配置，再导入目标设备；自定义仪表应重新选择目标设备下的参数。

预设是一组已经写好的参数读取配置，省去逐项填写请求与公式。标准 OBD-II 预设提供标准参数，车型预设提供相应车型的参数定义。选择车型预设时应核对年款与动力版本。

导入到指定设备

从设备参数列表底部打开配置库。App 内下载会进入该设备的导入界面；浏览器下载得到 JSON 文件，可在设备设置菜单中选择 导入配置。

导入列表默认不勾选，只保存明确选中的参数。可以先查看名称与当前读数，再通过右侧齿轮查看该项配置。关闭导入界面不会保存尚未确认的草稿。

重复项与配置更新

已有相同读取方法、解码规则与输出单位的参数会标记为重复，并继续使用原来的参数标识符。仅修改显示名称，不会让同一个参数变成新的读取项。

一个请求可以提供多个参数，例如同一响应中的两个温度；名称相同也可能来自不同控制器或不同公式，因此不能只按名称判断重复。修改了请求或解码规则的项目会作为新的参数导入，不会仅凭名称覆盖旧项。

导入到另一台适配器后，会建立目标设备自己的参数引用。自定义仪表应在输入绑定中重新选择目标设备的对应参数；保持输入标识符不变，无需修改代码。

文件约束

配置采用 JSON，格式标识为 capdrive.obd，appVersion 为所需的 App 版本；导出时写入当前 App 版本号。版本不足时会提示升级。单个文件最大 5 MiB，最多包含 3,000 个参数。文件保存读取配置，不包含设备的蓝牙连接，也不保证所有项目在目标车辆上可读。

通过参数右侧的齿轮打开编辑器。下面按“向车辆读取什么 → 怎样换算 → 怎样判定有效”的顺序说明字段。测试读取使用编辑器中的当前配置检查结果；点击保存后，修改才成为设备的已保存配置。

名称与更新频率

名称用于辨认车辆参数。内部标识符由 App 自动管理，不在参数编辑器中填写，也不是请求 PID；导出的预设不携带设备本机标识符。仪表脚本使用自己定义的输入标识符，再通过输入绑定选择车辆参数。

读取间隔以秒填写，范围为 0.3–99999。例如 1 秒表示目标查询间隔为 1 秒，实际更新还受车辆响应、其他请求与当前读取需求影响。参数列表的可见项目、仪表选择和行程数据用途会产生读取需求；仅导入参数不会让整份列表始终按固定频率轮询。共享同一请求的参数可以复用一次响应。

请求设置

换算公式、字节顺序与单位

车辆响应通常是数据字节。A 表示第一个数据字节、B 表示第二个，依此类推，不包括协议头。公式支持算术、位运算、比较、逻辑运算和条件表达式；它不是可以调用任意 JavaScript 函数的脚本。

例如，冷却液温度使用 A - 40；标准发动机转速使用 (A * 256 + B) / 4。若 A = 26、B = 248，后者得到 1726 rpm。一个参数的公式应与该请求返回的字节含义一致。

字节顺序规定如何解释多字节字段：大端把高位字节放在前面，小端把低位字节放在前面。App 按配置处理顺序后再执行数值公式，公式不应再次重复交换字节。

公式结果的单位与显示单位需要区分。修改自定义单位名称只改变标注，不会修改公式数值；对已有标准物理量选择兼容的显示单位时，App 可执行相应换算。请核对公式使用的原单位，避免重复换算。

读取条件与有效范围

响应先通过长度和读取条件检查，再解码。数字结果先限幅，再检查有效上下限；无法得到有限数值时不输出读数。读取条件使用字节顺序转换前的原始响应。

文本映射

文本映射把公式得到的某个数值显示为文字，例如 1 → D。键支持小数和负数，必须是唯一的有限数值，1.5 与 1.50 代表同一项。文字允许为空字符串。

命中映射时返回对应字符串；未命中时，开启 未匹配时返回原数值 就返回数字，关闭则返回 null。这项未匹配设置在存在映射时适用。命中的文字不会继续执行数字限幅。

因此，同一项参数可能返回数字、文字或空值，仪表代码应按参数实际类型处理。出现“某些值能显示、另一些值消失”的情况时，应检查映射是否命中及未匹配设置。

保存与错误提示

无效配置会指出字段与原因，修正后再保存或测试。服务 01、21 的 PID 为两位十六进制数，22 为四位；CAN ID 为 3 或 8 位，扩展地址与超时参数为两位。读取间隔为 0.3–99999 秒，最少响应字节数为 0–4096 的整数，公式与读取条件各最多 1,024 个 UTF-8 字节。数值必须有限，最小值不能大于最大值，有效下限必须小于有效上限；文本映射键不能重复。

替换行程数据让基础读数使用指定的 OBD 参数。例如，把一个车辆速度参数指定为“速度”后，基础速度字段、相关内置仪表及行程记录可使用这个车辆读数。

可替换的目标包括速度、纵向 G 值、横向 G 值、俯仰角和侧倾角。速度接受 km/h 或 mph，加速度接受 g 或 m/s²，角度接受度或弧度。App 会按目标需要换算单位。

替换要求参数提供合适的数字、单位与范围。存在文本映射的参数不能用于行程替换；超出配置范围的原始结果也会被拒绝，不会把限幅后的边界值当作有效行程测量。

有有效 OBD 读数时使用该来源；读数缺失、过期或无效时回退到手机数据。手机来源也不可用时，该基础读数仍然可能为空。普通参数导入不会自动指定替换目标。

在自定义仪表中单独显示水温、转速等参数，可直接使用它们的 OBD 引用，无需配置行程替换。

在 仪表设置 → 输入绑定 旁点齿轮进入 参数配置，添加一个 OBD 数据 输入，例如标识符 coolant。返回输入绑定，为它选择设备下的冷却液温度参数。脚本通过 $data.current.coolant 读取；车辆参数的 UUID 不用写进代码。

读数包含 value 和 unit，例如 { value: 83, unit: '°C' }。文字映射也可能返回字符串，数字格式化前应检查类型。未绑定时整个输入为 null；已绑定但暂时没有读数时，value 为 null，unit 仍取配置单位。

导入他人作品或更换适配器后，重新绑定已有输入即可沿用代码。预期类型用于提示，不强制转换车辆返回值。预览使用模拟输入，确认实车数据时应检查当前设备与 测试读取。

读数状态

连接有效、收到响应和读数有效是三个不同条件。响应可能因长度不足、读取条件不满足、公式无效或文本映射未命中而无法产生可用值。

运行时读数具有有效期。断开连接、读取失败或数据过期后，仪表与行程替换不应继续把旧值作为当前有效数据。参数列表可以保留最近一次成功读数用于展示，该展示值不等于仍有有效的实时输出；可使用 测试读取 检查当前请求结果。

零是有效数值，空值表示当前没有可用读数。文本映射中的空字符串是已匹配的文字结果，也与缺测不同。

按故障层级定位

问题反馈可包含以下信息，以区分连接问题、配置问题和显示问题：

• 车型、年款、动力版本及适配器型号。
• 当前设备、预设及参数名称。
• 测试读取的结果或具体错误。
• 影响全部参数还是个别参数，以及问题发生在参数列表、行程替换还是自定义仪表。