OBD-II Driver

jumpstarter-driver-obd wraps python-obd to query On-Board Diagnostics (OBD-II) PIDs from a vehicle ECU via an ELM327 adapter.

Installation

:substitutions:
$ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-obd

Hardware Requirements

• An ELM327 USB adapter (e.g. PremiumCord ELM327 USB)
• A vehicle with an OBD-II port (petrol cars from 2001+, diesel from 2004+, all US cars from 1996+)
• macOS only: ELM327 USB cables use a CH340 or CP2102 USB-serial chip that may need a kernel extension — install the appropriate driver if the port does not appear after plugging in

Configuration

Auto-detect (recommended for a single adapter)

Leave port unset or null to let python-obd scan available serial ports and connect to the first ELM327 it finds:

export:
  obd:
    type: jumpstarter_driver_obd.driver.OBD
    config:
      port: null

Auto-detect is reliable on Linux (e.g. `/dev/ttyUSB0`). On **macOS** it is not: python-obd
enumerates the `/dev/tty.*` call-in device nodes, but ELM327 adapters only open on the matching
`/dev/cu.*` call-out node, so auto-detect fails to connect. On macOS, pass an explicit
`/dev/cu.usbserial-*` port instead.

Explicit port

Specify the serial port directly when you have multiple adapters or want a deterministic setup:

export:
  obd:
    type: jumpstarter_driver_obd.driver.OBD
    config:
      port: /dev/ttyUSB0       # Linux
      # port: /dev/cu.usbserial-XXXX   # macOS
      baudrate: 38400

Config parameters

Usage

from jumpstarter_driver_obd import OBDConnectionStatus

# Check connection state
status = obd.status()                              # returns OBDConnectionStatus
print(status == OBDConnectionStatus.CAR_CONNECTED) # True
print(obd.is_connected())                          # True

# Discover what the ECU supports
cmds = obd.supported_commands()   # ["RPM", "SPEED", "COOLANT_TEMP", ...]

# Query individual PIDs by name
rpm   = obd.query("RPM")          # "3000.0 revolutions_per_minute"
speed = obd.query("SPEED")        # "60.0 kph"
temp  = obd.query("COOLANT_TEMP") # "90.0 degC"

# Clearing trouble codes is a separate, explicit call (see note below)
obd.clear_dtc()

query() returns None when the ECU does not answer the command (unsupported PID or no vehicle on the bus). It is read-only: it refuses destructive commands such as CLEAR_DTC (OBD-II mode 04, which erases stored trouble codes and resets emissions readiness monitors). To clear codes deliberately, call clear_dtc() instead.

Troubleshooting

Port not found on macOS Run ls /dev/cu.* before and after plugging in the cable to spot the new device. Install a CH340 or CP2102 USB-serial kernel extension if no new port appears.

Permission denied on Linux Add your user to the dialout group and log out/in:

sudo usermod -aG dialout $USER

Alternatively, create a udev rule for the adapter's USB vendor/product ID.

"No OBD-II adapters found" Make sure the cable is seated in the OBD-II port (typically under the dashboard on the driver's side) and that the vehicle ignition is in the ON or ACC position.

API Reference

.. autoclass:: jumpstarter_driver_obd.driver.OBD()
    :members:

.. autoclass:: jumpstarter_driver_obd.client.OBDClient()
    :members:

.. autoclass:: jumpstarter_driver_obd.driver.OBDConnectionStatus()
    :members: