162 lines
5.4 KiB
Markdown
162 lines
5.4 KiB
Markdown
# OBD2 Terminal Dashboard
|
|
|
|
This repository contains a Textual-based terminal dashboard for querying an OBD-II adapter and rendering live telemetry, per-command values, editable cache TTLs, and application logs in one terminal UI.
|
|
|
|
## Overview
|
|
|
|
The application combines:
|
|
|
|
- A Textual dashboard for live vehicle data
|
|
- An async OBD interface built on `python-OBD`
|
|
- A per-command TTL cache with hot-reloaded overrides from `command_ttl.conf`
|
|
- A simulated adapter path for development and tests
|
|
|
|
The primary entry point is [`obd2_tui.py`](/Users/jallen/workspace/obd2/obd2_tui.py).
|
|
|
|
## Features
|
|
|
|
- Displays live metrics for speed, RPM, fuel level, coolant temperature, and oil temperature
|
|
- Shows command data for OBD modes `01`, `02`, `03`, `04`, `06`, `07`, and `09`
|
|
- Polls core telemetry continuously while only querying table rows visible in the current viewport
|
|
- Deduplicates concurrent reads of the same OBD command through a shared pending-query map
|
|
- Enforces a global query-per-second limit across all outbound adapter requests
|
|
- Caches command results with a default TTL plus command-specific overrides
|
|
- Reloads TTL overrides automatically when `command_ttl.conf` changes
|
|
- Lets the user edit a selected command TTL directly from the UI
|
|
- Supports simulated telemetry for local development without hardware
|
|
- Streams logs into the application log panel
|
|
|
|
## Repository Layout
|
|
|
|
- [`obd2_tui.py`](/Users/jallen/workspace/obd2/obd2_tui.py): Textual application, CLI parsing, mode switching, viewport-aware polling, and TTL editing
|
|
- [`obd2_interface.py`](/Users/jallen/workspace/obd2/obd2_interface.py): adapter connection lifecycle, rate limiting, caching, TTL config reloads, and simulated interface support
|
|
- [`models.py`](/Users/jallen/workspace/obd2/models.py): Pydantic models for shared telemetry state and scan definitions
|
|
- [`ui.css`](/Users/jallen/workspace/obd2/ui.css): Textual styling for the dashboard, data table, TTL editor, and log panel
|
|
- [`command_ttl.conf`](/Users/jallen/workspace/obd2/command_ttl.conf): command-specific cache TTL overrides in milliseconds
|
|
- [`test.py`](/Users/jallen/workspace/obd2/test.py): unit tests covering report normalization, interface behavior, simulation, caching, and UI helpers
|
|
- [`requirements.txt`](/Users/jallen/workspace/obd2/requirements.txt): Python dependencies
|
|
|
|
## How It Works
|
|
|
|
### UI layer
|
|
|
|
`OBD2App` builds a dashboard with:
|
|
|
|
- Five metric cards
|
|
- A command table for the selected OBD mode
|
|
- A TTL editor bound to the highlighted command
|
|
- An in-app log panel
|
|
|
|
The app refresh loop does two things on each pass:
|
|
|
|
1. Queries the five telemetry commands needed for the metric cards
|
|
2. Queries only the currently visible command rows for the selected mode
|
|
|
|
Results are then applied back into the metric displays and table cells.
|
|
|
|
### Interface layer
|
|
|
|
`OBD2Interface` is responsible for:
|
|
|
|
- Connecting to the OBD adapter
|
|
- Serializing outbound queries through a worker queue
|
|
- Enforcing the global QPS limit
|
|
- Caching query results by command name
|
|
- Deduplicating in-flight requests for the same command
|
|
- Loading and reloading TTL overrides from disk
|
|
|
|
If a live adapter is unavailable, `SimulatedOBD2Interface` uses a synthetic connection that generates changing telemetry values and a few representative string responses such as VIN and DTC output.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11 or newer recommended
|
|
- An ELM327-compatible OBD-II adapter for real vehicle data
|
|
- A terminal environment that supports Textual applications
|
|
|
|
Install dependencies:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Running
|
|
|
|
Run against a real adapter:
|
|
|
|
```bash
|
|
python3 obd2_tui.py
|
|
```
|
|
|
|
Run in simulated mode:
|
|
|
|
```bash
|
|
python3 obd2_tui.py --simulated
|
|
```
|
|
|
|
Available flags:
|
|
|
|
- `--simulated`: use generated telemetry instead of a hardware adapter
|
|
- `--qps`: maximum OBD queries per second across the app, default `10.0`
|
|
- `--ttl-config`: path to the TTL override file, default `command_ttl.conf`
|
|
|
|
Example:
|
|
|
|
```bash
|
|
python3 obd2_tui.py --simulated --qps 25 --ttl-config command_ttl.conf
|
|
```
|
|
|
|
## Keyboard Controls
|
|
|
|
- `q`: quit
|
|
- `b`: toggle metric card border style
|
|
- `e`: focus the TTL editor
|
|
- `escape`: return focus to the command table
|
|
- `left` / `right`: switch to the previous or next OBD mode
|
|
- `shift+up` / `shift+down`: jump to the top or bottom of the table
|
|
- `1`, `2`, `3`, `4`, `6`, `7`, `9`: jump directly to a supported OBD mode
|
|
|
|
## TTL Configuration
|
|
|
|
`command_ttl.conf` uses:
|
|
|
|
```text
|
|
COMMAND_NAME,ttl_ms
|
|
```
|
|
|
|
Example:
|
|
|
|
```text
|
|
SPEED,10
|
|
RPM,10
|
|
FUEL_LEVEL,5000
|
|
GET_DTC,86400000
|
|
```
|
|
|
|
Notes:
|
|
|
|
- TTL values are stored in milliseconds
|
|
- `0` disables caching for that command
|
|
- Blank lines and comment lines beginning with `#` are ignored
|
|
- Editing a value in the UI writes the updated TTL back to the configured file
|
|
- The interface reloads TTL overrides automatically while the app is running
|
|
|
|
The TTL editor accepts plain millisecond values as well as duration suffixes such as `10ms`, `30s`, `1m`, and `1h`.
|
|
|
|
## Testing
|
|
|
|
Run the test suite with:
|
|
|
|
```bash
|
|
python3 -m unittest -v test.py
|
|
```
|
|
|
|
The current workspace environment has the required dependencies installed, and this command passes.
|
|
|
|
## Notes
|
|
|
|
- The terminal dashboard is the main supported runtime path
|
|
- [`obd2_interface.py`](/Users/jallen/workspace/obd2/obd2_interface.py) also includes a standalone `__main__` path that logs report snapshots outside the TUI
|
|
- Logging is routed into the UI through a custom `logging.Handler`
|