Command line¶

All functions are available under one command obd-diag with subcommands. Commands that use the adapter take --port (default /dev/ttyUSB0), --baud (default 38400) and --trace for a trace (Sessions, report and trace). --lang en or --lang de sets the language of all output (Language).

Command	Purpose	sends to the vehicle
`obd-diag ports`	list adapters	nothing
`obd-diag info`	adapter identification and battery voltage	nothing (only adapter commands)
`obd-diag adapter`	adapter check: version, command set, UDS suitability (Adapter and connection)	nothing (only adapter commands)
`obd-diag scan`	read trouble codes	Mode 01, 03, 07, 0A
`obd-diag diagnose`	trouble codes, readiness, freeze frame, VIN, used-car check, control units, test results	Mode 01, 02, 03, 06, 07, 09, 0A
`obd-diag readiness`	readiness assistant: incomplete tests since clearing and during this drive (Readiness assistant)	Mode 01
`obd-diag used-car`	used-car check: cleared recently? (Used-car check)	Mode 01, 03, 07, 0A
`obd-diag vin`	read the VIN or decode one that is typed in	Mode 09
`obd-diag ecus`	control units: name, calibration ID, CVN, monitoring counters (Control units and test results)	Mode 09
`obd-diag tests`	test results with limits (Control units and test results)	Mode 06
`obd-diag live`	show and record live data	Mode 01
`obd-diag battery`	battery and cranking test (Battery and cranking test)	Mode 01
`obd-diag export`	saved session as PDF/CSV	nothing
`obd-diag compare`	compare two saved sessions (Sessions, report and trace)	nothing
`obd-diag clear`	clear trouble codes (locked)	Mode 04

Examples¶

obd-diag adapter --port /dev/ttyUSB0               # what can the adapter really do?
obd-diag scan --port /dev/ttyUSB0                  # table, language like the system
obd-diag scan --port /dev/ttyUSB0 --lang en --json # English, machine-readable
obd-diag diagnose --port /dev/ttyUSB0 --save --pdf report.pdf
obd-diag used-car --port /dev/ttyUSB0               # trouble codes cleared recently?
obd-diag vin WVWZZZ1KZ6W123456                     # decode only, without an adapter
obd-diag live --port /dev/ttyUSB0 --pids rpm,speed --interval 0.5 --record
obd-diag export ~/.local/share/obd-diag/sessions/session-20261007-143205.json --pdf report.pdf

With --json the standard output stays pure JSON; notes and paths of saved files go to the error output. Exit code 0 means success, 1 an error.

All commands and options¶

The following reference is generated from the program itself when the documentation is built and is therefore always up to date with the code.

usage: obd-diag [-h] [--version] [--lang {de,en}]
                {info,adapter,battery,scan,clear,diagnose,readiness,used-car,vin,ecus,tests,live,ports,setup-check,export,compare}
                ...

Positional Arguments¶

command: Possible choices: info, adapter, battery, scan, clear, diagnose, readiness, used-car, vin, ecus, tests, live, ports, setup-check, export, compare

Named Arguments¶

--version

show program’s version number and exit

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

Sub-commands¶

info¶

show adapter version and battery voltage

obd-diag info [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
              [--trace [FILE]]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

adapter¶

adapter check: test version, voltage and supported commands, verdict for UDS (adapter commands only, the vehicle is not addressed)

obd-diag adapter [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
                 [--trace [FILE]] [--json]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--json

print the result as JSON

Default: False

battery¶

Battery and cranking test: measure and rate resting voltage, the dip while cranking and charging voltage; you start the engine yourself when the test asks you to

obd-diag battery [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
                 [--trace [FILE]] [--start-timeout SEC] [--json]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--start-timeout

how long to wait for cranking (default 30)

Default: 30.0

--json

print the result as JSON

Default: False

scan¶

read trouble codes (stored, pending, permanent)

obd-diag scan [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
              [--trace [FILE]] [--json] [--online-codes]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--json

print the result as JSON

Default: False

--online-codes

look up codes without a catalog text online (unverified short description, English); downloads a file from the source, sends neither code nor VIN

Default: False

clear¶

clear trouble codes (mode 04), backed up first; only with engine off, ignition on

obd-diag clear [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
               [--trace [FILE]] [--yes]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--yes

clear without asking

Default: False

diagnose¶

full diagnosis: trouble codes, readiness, freeze frame, VIN, used-car check, control units and test results (read-only)

obd-diag diagnose [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
                  [--trace [FILE]] [--json] [--online-vin] [--online-codes]
                  [--save] [--pdf FILE.pdf] [--csv FILE.csv]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--json

print the session as JSON

Default: False

--online-vin

also look up the VIN at NHTSA vPIC (USA); sends the VIN to the internet, the result is cached locally

Default: False

--online-codes

look up codes without a catalog text online (unverified short description, English); downloads a file from the source, sends neither code nor VIN

Default: False

--save

save the session under $XDG_DATA_HOME/obd-diag/sessions

Default: False

--pdf

PDF report

--csv

CSV, one row per trouble code

readiness¶

Readiness assistant: incomplete tests since codes were cleared and during this drive (PIDs 01 and 41) with hints on which drive completes them

obd-diag readiness [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
                   [--trace [FILE]] [--json]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--json

print the result as JSON

Default: False

used-car¶

used-car check: were the trouble codes cleared recently? Counters since clearing, MIL, permanent codes (read-only)

obd-diag used-car [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
                  [--trace [FILE]] [--json]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--json

print the result as JSON

Default: False

vin¶

read the VIN (mode 09) and decode it

obd-diag vin [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
             [--trace [FILE]] [--json] [--online-vin]
             [VIN]

Positional Arguments¶

VIN: decode this VIN, without an adapter

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--json

print the result as JSON

Default: False

--online-vin

also look up the VIN at NHTSA vPIC (USA); sends the VIN to the internet, the result is cached locally

Default: False

ecus¶

control units (mode 09): name, calibration IDs, CVN and monitoring counters

obd-diag ecus [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
              [--trace [FILE]] [--json]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--json

print the result as JSON

Default: False

tests¶

test results of the emission self-diagnosis with limits (mode 06, CAN only)

obd-diag tests [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
               [--trace [FILE]] [--json]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--json

print the result as JSON

Default: False

live¶

show and record live data (mode 01) continuously; stop with Ctrl+C

obd-diag live [-h] [--lang {de,en}] [--port PORT] [--baud BAUD] [--demo]
              [--trace [FILE]] [--pids KEY,...] [--list] [--interval SEC]
              [--duration SEC] [--record [FILE.csv]] [--alarm KEY=LOW:HIGH]
              [--no-alarms]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

Default: '/dev/ttyUSB0'

--baud

Default: 38400

--demo

Demo vehicle instead of an adapter: sample data from a Mercedes A 180 d, to try things out without a car (same as –port demo)

Default: False

--trace

record the adapter communication (without FILE: under $XDG_DATA_HOME/obd-diag/traces); may contain the VIN

--pids

values, e.g. rpm,speed,coolant_temp (default: the usual ones, if supported; –list shows the keys)

--list

show supported values with their keys and exit

Default: False

--interval

interval between query rounds (default 1, at least 0.1)

Default: 1.0

--duration

stop after SEC seconds

--record

record as CSV (without FILE: under $XDG_DATA_HOME/obd-diag/recordings); existing files are never overwritten

--alarm

set a warning threshold, e.g. coolant_temp=:110 (empty side: no limit, KEY=: turns the warning off; may be repeated). Defaults: coolant_temp=:115, oil_temp=:130, control_voltage=11.8:15.5, voltage=11.8:15.5

--no-alarms

without the default warning thresholds (only those set with –alarm)

Default: False

ports¶

list connected adapters

obd-diag ports [-h] [--lang {de,en}]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

setup-check¶

Check the setup: find adapters, access rights and baud rate (38400, 115200); sends adapter commands only (ATZ …)

obd-diag setup-check [-h] [--lang {de,en}] [--port PORT]

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--port

check only this port (default: all adapters found)

export¶

write a saved diagnosis session (JSON) as a PDF report or CSV

obd-diag export [-h] [--lang {de,en}] [--pdf FILE.pdf] [--csv FILE.csv]
                SESSION.json

Positional Arguments¶

SESSION.json

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--pdf

PDF report

--csv

CSV, one row per trouble code

compare¶

compare two saved diagnosis sessions: new and cleared trouble codes, readiness, freeze frame (the older one counts as before)

obd-diag compare [-h] [--lang {de,en}] [--json] SESSION1.json SESSION2.json

Positional Arguments¶

SESSION1.json
SESSION2.json

Named Arguments¶

--lang

Possible choices: de, en

language of the output and the trouble code texts (default: like the system language, German only if the system language is German)

--json

print the result as JSON

Default: False