obd-tui

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.

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

Usage

obd-tui                  # launch the dashboard
obd-tui --port /dev/ttyUSB0   # skip auto-detection
obd-tui --version

Keys: c connect · d disconnect · 1–5 panels · p PID catalogue · q quit.

Features

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), with --port to override.
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 and the PID catalogue, refreshed once per second while connected.
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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

obd_tui-0.1.0.tar.gz (107.1 kB view details)

Uploaded Aug 13, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

obd_tui-0.1.0-py3-none-any.whl (28.3 kB view details)

Uploaded Aug 13, 2026 Python 3

File details

Details for the file obd_tui-0.1.0.tar.gz.

File metadata

Download URL: obd_tui-0.1.0.tar.gz
Upload date: Aug 13, 2026
Size: 107.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for obd_tui-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`7ecb976a9760c79f22fc1ef97c82801f2d036ead3bc90501eeb7ed8eecdbde56`
MD5	`d1e3cf15cec3e046a14e2a7c436380f5`
BLAKE2b-256	`613e77678f544a37fc70bafa1d66d2d9404b8b7d40cc208e8c252abb75b82c6a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for obd_tui-0.1.0.tar.gz:

Publisher: ci.yml on goabonga/obd-tui

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: obd_tui-0.1.0.tar.gz
- Subject digest: 7ecb976a9760c79f22fc1ef97c82801f2d036ead3bc90501eeb7ed8eecdbde56
- Sigstore transparency entry: 2451328659
- Sigstore integration time: Aug 13, 2026
Source repository:
- Permalink: goabonga/obd-tui@5399485d9f56d25cf1b1e8382073ac4875f8075e
- Branch / Tag: refs/heads/main
- Owner: https://github.com/goabonga
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: ci.yml@5399485d9f56d25cf1b1e8382073ac4875f8075e
- Trigger Event: push