OBD Vehicle data

OBD is used to read data provided by the vehicle controller. The vehicle controller, also called ECU, is responsible for the engine, transmission and other systems; CapDrive sends requests to these controllers through the adapter and converts the received data into readings.

A "parameter" in the app is a piece of data to be read and displayed, such as engine engine speed (RPM), coolant temperature, or a status. It holds read requests, conversion formulas, and units. Numeric parameters can be used for numbers, progress or curves; status parameters can be displayed as D, P, etc. through text mapping.

For example, the coolant temperature parameter can be obtained using request 0105 to obtain a data byte A and converted according to A - 40. If the decimal value of the returned byte is 123, the result is 83 °C. The connection method, request definition and conversion rules must be correct to obtain usable readings.

Which parameters the vehicle supports depends on the model, year, power system and controller status. Only the values ​​actually provided by the vehicle can be read, and modifying the name or units does not increase the data capabilities of the vehicle itself.

Vehicle OBD connection requires CapDrive Plus, Bluetooth Low Energy (BLE) Adapter supporting ELM327 instructions, and Bluetooth permissions on the iPhone. Classic Bluetooth and Wi-Fi adapters are not currently supported.

Only after the adapter is plugged into the vehicle's OBD interface and powered on as required by the vehicle can the App communicate with the vehicle. Certain parameters require the vehicle to be in a specific state, such as the controller being powered on, the engine running, or the corresponding system being operational. The inclusion of "Bluetooth" in an adapter's name does not alone prove that it complies with BLE and the directive.

The OBD reading, No need to start a journey first, can be viewed and tested in the parameter list or parameter editor. Whether the mobile phone trip has started does not determine whether the vehicle will return coolant temperature, engine speed (RPM) and other parameters.

CapDrive supports configuration of read requests for hex services 01, 21, 22. For normal use, the preset matching the vehicle can be used; the specific request address and formula are subject to the preset or vehicle parameter definition.

Entry: More (…) → Vehicle OBD connection. The device page displays nearby adapters and saved devices, and the parameter configuration of the adapter is saved in the device settings.

First time connection and reconnection

When connecting for the first time, the App will establish Bluetooth communication, initialize the adapter, identify the vehicle protocol, and query which standard parameters the vehicle supports. After success, the supported standard parameters are initialized in the device’s parameter list. Whether the standard parameters have values ​​in the current state depends on the actual reading results.

When an existing device reconnects, it will continue to use the original configuration, including modified parameters and actively cleared lists. After deleting a parameter, reconnecting will not add it back. When supplementary readings are needed, import a preset or add a parameter.

Current data source

The "current device" refers to the adapter that is providing vehicle data to CapDrive. Only one device can be used as the current data source at a time. The parameters and settings of each device are saved independently; when switching to another device, the parameter references of the previous device will not be automatically used.

Disconnecting retains the configuration. Ignore device will remove the device's configuration and cache. When you need to migrate parameters, you can export the configuration and then import it into the target device; for customized instruments, you should reselect the parameters under the target device.

A preset contains ready-made parameter configurations so you do not need to enter each request and formula yourself. The standard OBD-II preset provides standard parameters, and the vehicle model preset provides parameter definitions for the corresponding vehicle model. When selecting a model preset, you should check the model year and powertrain.

Import to specified device

Open the configuration library from the bottom of the device parameter list. Downloading in the App will enter the import interface of the device; downloading the JSON file through the browser can select Import configuration in the device settings menu.

The import list is unchecked by default, and only explicitly selected parameters are saved. You can first check the name and current reading, and then check the configuration through the gear on the right. Closing the import interface will not save unconfirmed drafts.

Duplicates and configuration updates

Parameters that already have the same reading method, decoding rule, and output unit will be marked as duplicates and continue to use the original parameter identifier. Only modifying the display name does not make the same parameter a new read item.

A request can provide multiple parameters, such as two temperatures in the same response; the same name may also come from different controllers or different formulas, so duplicates cannot be judged just by name. Items with modified request or decoding rules are imported as new parameters and do not overwrite old items by name alone.

When imported into another adapter, the target device's own parameter reference is established. Custom instruments should reselect the corresponding parameters of the target device in Input bindings; keep the input identifier unchanged and no need to modify the code.

File constraints

The configuration uses JSON, the format identifier is capdrive.obd, and appVersion is the required App version; the current App version number is written when exporting. When the version is insufficient, you will be prompted to upgrade. A single file can be up to 5 MiB and contain up to 3,000 parameters. The file saves the read configuration and does not contain the device's Bluetooth connection, nor does it guarantee that all items will be readable on the target vehicle.

Open the editor via the gear to the right of the parameters. The following describes the fields in the order of "what to read from the vehicle → how to convert → how to determine validity". Test read uses the current configuration in the editor to check the results; after clicking Save, the modifications become the saved configuration of the device.

Name and update frequency

The name is used to identify vehicle parameters. Internal identifiers are automatically managed by the app and are not filled in in the parameter editor, nor are they requested PID; exported presets do not carry device native identifiers. The instrument script uses its own defined input identifier and selects vehicle parameters through input binding.

Read interval (seconds) is filled in seconds and the range is 0.3–99999. For example, 1 second means that the target query interval is 1 second. The actual update is also affected by vehicle response, other requests, and current read requirements. Visible items in the parameter list, instrument selection, and trip data usage create read requirements; simply importing parameters does not cause the entire list to always be polled at a fixed frequency. Parameters that share the same request can be reused in a response.

request settings

Conversion formulas, byte order and units

The vehicle response is usually data bytes. A represents the first data byte, B represents the second, and so on, excluding the protocol header. A formula supports arithmetic, bitwise operations, comparisons, logical operations, and conditional expressions; it is not a script that can call arbitrary JavaScript functions.

For example, coolant temperature uses A - 40; standard engine speed (RPM) uses (A * 256 + B) / 4. If A = 26, B = 248, the latter gets 1726 rpm. The formula of a parameter should be consistent with the meaning of the bytes returned by the request.

Endianness dictates how multibyte fields are interpreted: big-endian puts the high-order byte first, little-endian puts the low-order byte first. The App executes the numerical formula after the configured processing order, and the formula should not repeatedly swap bytes again.

The unit of the formula result needs to be distinguished from the display unit. Modifying the custom unit name only changes the label and does not modify the formula value; when selecting a compatible display unit for an existing standard physical quantity, the App can perform the corresponding conversion. Please check the original units used in the formula to avoid repeated conversions.

Reading conditions and valid range

The response passes length and read condition checks before being decoded. Numeric results are clamped first, and then the exclusive validity bounds are checked; no reading is output when a finite value cannot be obtained. The read condition uses the raw response before byte order conversion.

text mapping

Text mapping displays a value obtained by a formula as text, such as 1 → D. The key supports decimals and negative numbers and must be a unique finite value. 1.5 and 1.50 represent the same item. Mapped text may be an empty string.

When the mapping is hit, the corresponding string is returned; when it is not hit, a number is returned when Return the original number when unmatched is turned on, and null is returned when it is turned off. This unmatched setting applies when a mapping exists. Matched text bypasses numeric clamping.

Therefore, the same parameter may return a number, text, or null value, and instrumentation code should handle the actual type of the parameter. When the situation "some values can be displayed and other values disappear" occurs, you should check whether the mapping is matched and whether the settings are not matched.

Save and error message

Invalid configurations will indicate the fields and reasons, and then save or test after correction. PID of services 01 and 21 is a two-digit hexadecimal number, 22 is four digits; CAN ID is 3 or 8 digits, and the extended address and timeout parameters are two digits. The read interval is 0.3–99999 seconds, the minimum number of response bytes is an integer of 0–4096, and the formula and read conditions are each up to 1,024 UTF-8 bytes. Numbers must be finite, the minimum value cannot be greater than the maximum value, and the valid lower limit must be less than the valid upper limit; the text mapping key cannot be repeated.

Replace trip data makes the base reading use the specified OBD parameter. For example, by specifying a vehicle speed parameter as "Speed", the base speed field, associated built-in instruments, and trip records can use this vehicle reading.

Alternative targets include speed, longitudinal G, lateral G, pitch and roll. Accepts km/h or mph for velocity, g or m/s² for acceleration, and degrees or radians for angle. The app will convert the units as needed for the target.

Replacement requires that parameters be supplied with appropriate numbers, units, and ranges. Parameters with text mapping cannot be used for stroke replacement; original results outside the configuration range will also be rejected, and limit values ​​after limiting will not be regarded as valid stroke measurements.

Use this source when there are valid OBD readings; fall back to mobile data when readings are missing, expired, or invalid. This base reading may still be empty when the mobile source is also unavailable. Ordinary parameter import does not automatically specify replacement targets.

Parameters such as coolant temperature, engine speed (RPM), etc. can be displayed separately in the custom instrument, and their OBD references can be used directly without configuring stroke replacement.

Click the cog next to Instrument settings → Input bindings to enter Parameter configuration and add an OBD data input, for example the identifier coolant. Return to the input binding and select the Coolant Temperature parameter under Devices for it. The script reads through $data.current.coolant; the UUID of the vehicle parameters does not need to be written into the code.

Reads include value and unit, for example { value: 83, unit: '°C' }. Text mappings may also return strings, the type should be checked before number formatting. When it is not bound, the entire input is null; when it is bound but there is no reading temporarily, value is null, and unit still takes the configuration unit.

After importing someone else’s instrument or changing the adapter, rebind the existing input to continue using the code. Expected type is used for hints, vehicle return value is not cast. The preview uses simulated inputs, and the current device and Test read should be checked when confirming real vehicle data.

Reading status

The connection is valid, the response is received and the reading is valid are three different conditions. The response may not produce a usable value due to insufficient length, unsatisfied read conditions, invalid formula, or text mapping miss.

Runtime readings have an expiration date. After disconnection, read failure or data expiration, instrument and trip replacement should not continue to use the old value as the current valid data. The parameter list can retain the last successful reading for demonstration purposes that does not equal a valid live output; the current request result can be checked using Test read.

Zero is a valid value, and a null value means there are currently no readings available. The empty string in the text map is the matched text result, which is also different from the missing reading.

Locate by fault level

Problem feedback can include the following information to differentiate between connectivity issues, configuration issues, and display issues:

• Model, year, power version and adapter model.
• Current device, preset and parameter names.
• Test read results or specific errors.
• Does it affect all parameters or individual parameters, and whether the problem occurs in the parameter list, trip replacement or custom instrument.