161 lines
5.1 KiB
Markdown
161 lines
5.1 KiB
Markdown
# OBD2 Terminal Dashboard
|
|
|
|
This repository contains a Textual-based terminal dashboard for querying an OBD-II adapter and presenting live vehicle telemetry alongside raw command output.
|
|
|
|
`scanbus.py` is intentionally excluded from this README.
|
|
|
|
## What It Does
|
|
|
|
- Displays live dashboard metrics for speed, RPM, fuel level, oil temperature, and coolant temperature.
|
|
- Renders a command table for OBD modes `01`, `02`, `03`, `04`, `06`, `07`, and `09`.
|
|
- Polls commands asynchronously with a global queries-per-second limit.
|
|
- Deduplicates concurrent reads of the same OBD command.
|
|
- Caches command results using a default TTL plus per-command overrides from `command_ttl.conf`.
|
|
- Supports a simulated mode for UI development without a physical adapter.
|
|
- Streams application logs inside the terminal UI.
|
|
|
|
## Repository Layout
|
|
|
|
- `obd2_tui.py`: main Textual app, CLI entry point, keyboard bindings, command polling, and inline TTL editing.
|
|
- `obd2_interface.py`: async OBD abstraction, connection lifecycle, rate limiting, caching, TTL config reloads, and simulation support.
|
|
- `models.py`: Pydantic models for the live telemetry report and scan definitions.
|
|
- `ui.css`: Textual stylesheet for the dashboard, command table, and log panel.
|
|
- `command_ttl.conf`: command-specific cache TTL overrides in milliseconds.
|
|
- `test.py`: unit tests for report normalization, interface behavior, caching, TTL updates, simulation, and UI helpers.
|
|
- `requirements.txt`: Python dependencies.
|
|
|
|
## Architecture
|
|
|
|
The application has two main layers:
|
|
|
|
1. `OBD2App` in `obd2_tui.py`
|
|
- Builds the terminal UI with Textual.
|
|
- Polls a small set of key telemetry commands continuously for the metric cards.
|
|
- Polls the currently visible rows in the selected OBD mode table.
|
|
- Lets the user edit a selected command's cache TTL from the UI.
|
|
|
|
2. `OBD2Interface` in `obd2_interface.py`
|
|
- Connects to the adapter through `python-OBD`.
|
|
- Serializes outbound queries through a worker queue.
|
|
- Enforces a global rate limit.
|
|
- Maintains a TTL cache keyed by command name.
|
|
- Watches `command_ttl.conf` and hot-reloads TTL overrides.
|
|
|
|
`SimulatedOBD2Interface` swaps in a fake connection that generates dynamic values for development and testing.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11+ recommended
|
|
- An ELM327-compatible OBD-II adapter for real vehicle data
|
|
- Terminal support suitable for a Textual application
|
|
|
|
Install dependencies:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Running
|
|
|
|
Run against a real OBD adapter:
|
|
|
|
```bash
|
|
python3 obd2_tui.py
|
|
```
|
|
|
|
Run in simulated mode:
|
|
|
|
```bash
|
|
python3 obd2_tui.py --simulated
|
|
```
|
|
|
|
Optional flags:
|
|
|
|
- `--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
|
|
```
|
|
|
|
## UI Behavior
|
|
|
|
The dashboard is composed of:
|
|
|
|
- Metric cards for the five primary telemetry values
|
|
- A command table for the selected OBD mode
|
|
- A TTL editor bound to the currently highlighted command
|
|
- An in-app log panel
|
|
|
|
The polling strategy is selective:
|
|
|
|
- Core telemetry commands are always queried so the metric cards stay current.
|
|
- The mode table queries only commands that are currently visible in the viewport.
|
|
- Duplicate requests for the same command are coalesced through the interface queue and cache.
|
|
|
|
## Keyboard Controls
|
|
|
|
- `q`: quit
|
|
- `b`: toggle metric card border style
|
|
- `e`: focus the TTL editor
|
|
- `escape`: return focus to the command table
|
|
- `left` / `right`: previous or next OBD mode
|
|
- `shift+up` / `shift+down`: jump to top or bottom of the table
|
|
- `1`, `2`, `3`, `4`, `6`, `7`, `9`: switch directly to that OBD mode
|
|
|
|
## TTL Configuration
|
|
|
|
`command_ttl.conf` uses the format:
|
|
|
|
```text
|
|
COMMAND_NAME,ttl_ms
|
|
```
|
|
|
|
Examples:
|
|
|
|
```text
|
|
SPEED,10
|
|
RPM,10
|
|
FUEL_LEVEL,5000
|
|
GET_DTC,86400000
|
|
```
|
|
|
|
Notes:
|
|
|
|
- TTL values are stored in milliseconds.
|
|
- A value of `0` effectively disables caching for that command.
|
|
- The app reloads the file automatically while running.
|
|
- Editing a TTL in the UI writes the updated value back to the configured TTL file.
|
|
|
|
## Testing
|
|
|
|
Run the unit tests with:
|
|
|
|
```bash
|
|
python3 -m unittest -v test.py
|
|
```
|
|
|
|
The tests cover:
|
|
|
|
- Report value normalization
|
|
- Query rate limiting
|
|
- Cache hit and cache expiry behavior
|
|
- TTL override parsing and persistence
|
|
- Simulated connection behavior
|
|
- Display formatting and duration parsing helpers
|
|
|
|
## Current Environment Note
|
|
|
|
In the current workspace environment, `python3 -m unittest -v test.py` fails immediately because `pydantic` is not installed. After installing dependencies from `requirements.txt`, the test command should be rerun.
|
|
|
|
## Development Notes
|
|
|
|
- Logging is routed into the Textual `RichLog` panel through a custom logging handler.
|
|
- The codebase uses `Report` as the shared mutable telemetry state for the UI.
|
|
- `command_ttl.conf` is large because it predefines cache behavior for many standard OBD commands.
|
|
- `obd2_interface.py` also contains a non-TUI `__main__` path that continuously logs report snapshots, but the primary entry point for normal use is `obd2_tui.py`.
|