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**.

![Multi-axis graph](docs/gui-p2-multiaxis.png)
![Gauge view](docs/gui-p2-gauges.png)

> 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 stored/pending/permanent trouble codes and clear them
  (guarded), with descriptions and **no-start codes flagged**.
- **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).