obd-tui

Terminal dashboard for real-time OBD-II vehicle diagnostics.

obd-tui turns any ELM327-compatible OBD-II adapter into a live terminal dashboard. It auto-detects the adapter on the serial bus, asks the vehicle which commands it actually supports, and streams the readings into a tabbed Textual UI - engine, turbo/air, EGR, diagnostics, fault codes, and the full PID catalogue.

No adapter at hand? obd-tui --demo runs the whole dashboard against a simulated vehicle.

Documentation

The project site is published from main to GitHub Pages: https://goabonga.github.io/obd-tui/.

Requirements

• Python 3.11+
• An ELM327-compatible OBD-II adapter on a serial port (USB or Bluetooth RFCOMM)
• uv for development

Install

pip install obd-tui      # or: uvx obd-tui

On Ubuntu 24.04 LTS and 26.04 LTS, from the PPA:

sudo add-apt-repository ppa:goabonga/obd-tui
sudo apt install obd-tui

Usage

obd-tui                       # launch the dashboard
obd-tui --port /dev/ttyUSB0   # skip auto-detection and connect at once
obd-tui --demo                # simulated vehicle, no hardware needed
obd-tui --record drive.jsonl  # log every sweep as JSON Lines
obd-tui --units imperial      # °F, mph, psi
obd-tui --version

Keys: c connect · d disconnect · 1–7 panels · p PID catalogue · x clear DTCs · e engine · r report · q quit. Panels taller than the window scroll with the wheel, the arrows or PgUp/PgDn.

Features

• Demo mode - --demo drives the dashboard from a simulated vehicle, so the UI can be tried, screenshotted and tested with nothing plugged in.
• Trends - RPM, coolant and MAF are charted above the engine readings from a five-minute rolling history.
• Recording - --record FILE appends every sweep to a JSON Lines file, flushed as it goes, ready for jq or pandas.
• Adapter auto-detection - scans serial ports for known OBD-II adapters (vLinker / FTDI 0403:6015, and any port whose product or manufacturer string looks like an OBD adapter), falls back to bound Bluetooth RFCOMM nodes, and takes --port to override.
• Metric or imperial - --units imperial for °F, mph and psi; only the display changes, recordings stay in the units the vehicle reports.
• Configuration file - port, units, sweep period and reconnect interval in ~/.config/obd-tui/config.toml, overridden by the command line.
• Clear DTCs - x sends mode 04 after a confirmation dialog spelling out what it resets, then reads the codes back.
• Adaptive polling - readings are swept at three cadences, and whatever the open panel shows is read every sweep. A vehicle that stops answering is detected and the session drops to LINK LOST instead of hanging.
• Capability discovery - queries the vehicle for its supported commands across modes 01–09 plus the ELM adapter commands, so panels only show data the ECU can actually produce.
• Tabbed dashboard - Engine, Turbo/Air, EGR, Diagnostics, Faults, Exhaust, DPF and the PID catalogue, refreshed once per second while connected.
• Exhaust gas temperatures - every bank and sensor the vehicle answers, from PIDs 0x78 and 0x79, which python-obd does not define; a sensor far from the others is pointed out, for chasing codes like P2033. Capabilities resolve standard first, then through a manufacturer profile, so a make never leaks into the panels.
• Diesel particulate filter - differential pressure, temperatures and regeneration status from the standard PIDs 0x7A, 0x7C and 0x8B, the soot load from a manufacturer profile when one exposes it, and derived rows - restriction per unit of air flow, time since the last regeneration - marked as such. Described, never judged: elevated, not clogged.
• Manufacturer profiles - recognised from the VIN, bound to the engine you declare with --engine or pick with e, answering only what the standard cannot and only for engines they have a cited table for. Suzuki's is empty so far.
• Reports - r saves everything the session knows, dated to the second: the vehicle as recognised, the codes, every panel as it stands, the supported commands, the latest readings and their recent history, as Markdown to read and JSON to keep.
• Reconnects on its own - a missing adapter, a port that refused to open or a vehicle that went quiet is retried every few seconds, until d says the link is to stay down.
• Live connection status in the footer: state, port, and adapter VID:PID.
• Tabs stay disabled until a device is connected, and disable again on disconnect.

Getting started (development)

git clone https://github.com/goabonga/obd-tui.git
cd obd-tui
uv sync
uv run pre-commit install
uv run ruff check src tests
uv run mypy src
uv run pytest

Versioning and release

Versions are bumped from Conventional Commits by multicz. On every push to main, CI computes the bump, writes the changelog, tags, and publishes the wheel to PyPI through Trusted Publishing. Maintainers do not bump versions or edit the changelog by hand.

Stability and deprecation policy

obd-tui follows Semantic Versioning and the standard Python n + 2 deprecation cadence (announce + warn in one release, remove in the release after the next). Full policy: docs/stability.md.

Contributing

See CONTRIBUTING.md for the workflow, the commit-message convention, and the test/lint expectations. By participating you agree to the Code of Conduct.

Security issues: please follow the disclosure process in SECURITY.md.

License

Distributed under the MIT License.