justin
6548cf7fbe
- Diagnostics menu: Vehicle Info (VIN/cal/ECU), Emissions Readiness (I/M monitors + MIL -> pass/fail), Freeze Frame (snapshot + capturing DTC). All routed through the scheduler one-off path; dialogs, no docked panels. - New Trip / Performance view (View menu, center page): live + average MPG, trip distance/fuel/time, and 0-60 / 1/4-mile timers. The controller keeps SPEED + MAF polled in the background and feeds TripComputer/PerformanceMeter every tick, so trips accumulate regardless of the active view. Honest MAF caveat shown for speed-density/diesel vehicles. Validated headless against MockLink: VIN dialog, readiness dialog, freeze-frame dialog, and the live trip page (28.8 mpg / distance accruing). All tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016yT89n4zR4qbrySoSiEyZs
140 lines
6.1 KiB
Markdown
140 lines
6.1 KiB
Markdown
# 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**](https://git.jpaul.io/justin/obdash/releases/latest):
|
||
|
||
| 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:
|
||
|
||
```bash
|
||
# macOS / Linux
|
||
shasum -a 256 -c OBDash-macos.zip.sha256 # macOS
|
||
sha256sum -c OBDash-linux-x86_64.sha256 # Linux
|
||
```
|
||
```powershell
|
||
# 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
|
||
|
||
```bash
|
||
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`](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.)
|
||
|
||
```bash
|
||
python obd_reader.py COM5 --crank # big ICP cranking monitor
|
||
python obd_reader.py COM5 --clear # read, then clear codes (guarded)
|
||
```
|
||
|
||
## Project
|
||
|
||
- [`ARCHITECTURE.md`](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`](LICENSE).
|