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 仍取配置單位。

導入他人作品或更換適配器後，重新綁定已有輸入即可沿用程式碼。預期類型用於提示，不強制轉換車輛回傳值。預覽使用模擬輸入，確認實車資料時應檢查當前設備與 測試讀取。

讀數狀態

連線有效、收到響應和讀數有效是三個不同條件。響應可能因長度不足、讀取條件不滿足、公式無效或文本映射未命中而無法產生可用值。

執行時讀數具有有效期。斷開連線、讀取失敗或資料過期後，儀表與行程替換不應繼續把舊值作為當前有效資料。參數列表可以保留最近一次成功讀數用於展示，該展示值不等於仍有有效的即時輸出；可使用 測試讀取 檢查當前請求結果。

零是有效數值，空值表示當前沒有可用讀數。文本映射中的空字串是已匹配的文字結果，也與缺測不同。

按故障層級定位

問題反饋可包含以下信息，以區分連線問題、配置問題和顯示問題：

• 車型、年款、動力版本及適配器型號。
• 當前設備、預設及參數名稱。
• 測試讀取的結果或具體錯誤。
• 影響全部參數還是個別參數，以及問題發生在參數列表、行程替換還是自定義儀表。