obdash/README.md

OBDash

Open-source, vehicle-agnostic OBD-II scanner — Python/Qt, cross-platform.

A desktop app that turns a cheap ELM327 adapter into a real diagnostic tool: live multi-axis graphs, automotive-style gauges, a sortable data table, and DTC read/clear — for any OBD-II vehicle. What it can read for each car is defined by a JSON vehicle profile (PIDs, scaling, codes, gauges), so adding a new vehicle is data, not code. Runs on Windows, macOS, and Linux.

Validated on real vehicles (1997 Jeep Wrangler 4.0 I6, 1996 Mustang Cobra 4.6 DOHC, Ford 6.0L Power Stroke, …) using a QinHeng CH340 ELM327 clone.

Features

• Live graphs with true multi-axis overlay — each metric gets its own Y axis, colored to match its line; click a line to move its axis to the left. Optional Normalize (% of range) mode.
• Gauge view — round, tach-style gauges with tick scales, needles, redline zones (configurable per metric), and peak-hold.
• Table view — value, min/max, and confidence per signal.
• Diagnostics — read/clear trouble codes (guarded), with descriptions from a built-in 1,400+ generic SAE DTC database (profiles override) and no-start codes flagged; plus freeze-frame (the snapshot when a code set).
• Emissions readiness — I/M monitor status + MIL → a "will it pass inspection?" report. Vehicle info — VIN, calibration IDs, ECU name (Mode 09).
• Trip / Performance — live MPG, trip distance/fuel, and 0-60 mph & 1/4-mile timers (auto-detected from a standing start).
• Vehicle profiles — switch/import/edit vehicles from the Profile menu.
• Units — °C/°F toggle (US/metric).
• Captures — record a session to CSV and replay it.
• Mock mode — explore the whole app with simulated data, no adapter needed.

Download

Grab a prebuilt binary from the latest release:

Platform	File
Windows	OBDash-windows.exe
macOS	OBDash-macos.zip (unzip → OBDash.app)
Linux x86_64	OBDash-linux-x86_64
Linux ARM64 (Raspberry Pi)	OBDash-linux-aarch64

Each binary ships with a .sha256 so you can verify the download:

# macOS / Linux
shasum -a 256 -c OBDash-macos.zip.sha256        # macOS
sha256sum -c OBDash-linux-x86_64.sha256         # Linux

# Windows
(Get-FileHash OBDash-windows.exe -Algorithm SHA256).Hash.ToLower()
Get-Content OBDash-windows.exe.sha256           # compare the two

Unsigned-binary warnings (expected for open source)

The binaries aren't code-signed, so the OS will warn on first launch. They're safe — verify the checksum above, then:

• Windows (SmartScreen): "Windows protected your PC" → More info → Run anyway.
• macOS (Gatekeeper): right-click the app → Open (then Open again), or clear the quarantine flag: xattr -dr com.apple.quarantine OBDash.app.
• Linux: chmod +x OBDash-linux-x86_64 && ./OBDash-linux-x86_64.

(Code signing removes these warnings but costs money / a hardware token; see the project notes. Checksums give you the same integrity guarantee for free.)

Run from source

pip install -r requirements-gui.txt
python run_gui.py        # tick "Mock" + Connect to explore with no adapter

Needs Python 3.10+. The GUI deps (PySide6, pyqtgraph, numpy, pyserial) all ship wheels for Windows / macOS (incl. Apple Silicon) / Linux.

Connecting to a vehicle

Plug an ELM327 (USB or Bluetooth) into the OBD-II port, turn the key to RUN, then pick the port and Connect. The CH340 USB adapters need a one-time driver:

• Windows — WCH CH341SER; shows as USB-SERIAL CH340 (COMx) in Device Manager.
• macOS — WCH CH34xVCPDriver (Mac App Store / wch.cn); port /dev/cu.wchusbserial*.
• Linux — ch341 is in the kernel (no install); port /dev/ttyUSB0 (add yourself to the dialout group: sudo usermod -aG dialout $USER).

Default baud is 38400; the ELM327 auto-negotiates the vehicle's protocol.

Vehicle profiles

Each profiles/*.json teaches OBDash how to read one vehicle. Bundled profiles:

Profile	Vehicle
generic-obd2.json	Any OBD-II vehicle (standard SAE PIDs) — a base to fork
ford-6.0-powerstroke.json	Ford 6.0L Power Stroke (2003–2007) — incl. enhanced ICP/FICM/EBP PIDs
jeep-wrangler-4.0-1997.json	1997 Jeep Wrangler TJ 4.0 I6
ford-mustang-cobra-4.6-1996.json	1996 Mustang SVT Cobra 4.6 DOHC
ford-mustang-gt-4.6-1996.json	1996 Mustang GT 4.6 SOHC
mercury-mountaineer-4.6-2006.json	2006 Mercury Mountaineer 4.6 V8

Add your vehicle: the format is documented in profiles/PROFILE_SPEC.md — it's written to be handed straight to an AI agent ("research <year make model> and produce an OBDash profile per this spec"). Drop the .json in profiles/, load it from the Profile menu, and open a PR. Profiles are pure data — they can't run code (formulas go through a sandboxed evaluator).

Terminal tool (Ford 6.0 no-start)

The repo also includes obd_reader.py, a self-contained CLI focused on diagnosing a 6.0 Power Stroke that won't start — a big live ICP-during-crank monitor (--crank), code read/clear, and CSV logging. It needs only pyserial. See handoff.md and diagnostics/ for the worked no-start investigation that seeded this project. (The GUI above is the general-purpose, multi-vehicle tool; the CLI is the diesel-specific workflow it grew out of.)

python obd_reader.py COM5 --crank      # big ICP cranking monitor
python obd_reader.py COM5 --clear      # read, then clear codes (guarded)

Project

• ARCHITECTURE.md — design, the acquisition engine, roadmap.
• Built on a headless obdcore package (link / registry / scheduler / store) shared by the GUI and the CLI; tested without hardware via a mock adapter.
• CI builds the cross-platform binaries on tag (.gitea/workflows/release.yml).

License

MIT — see LICENSE.