Vehicle Telemetry & Diagnostics Platform

A real-time car monitoring system that reads live engine data (speed, RPM, temperature) from a simulated car and displays it on a web dashboard.

What It Does

A Python script pretends to be a car's computer, broadcasting engine data. A C++ service listens, decodes the data, and pushes it to a web browser over WebSocket. A React dashboard shows live gauges and fault codes.

[Car Simulator] → [C++ Decoder] → [WebSocket] → [Browser Dashboard]

Data shown: RPM, speed, coolant temperature, engine load, throttle position, and fault codes (DTCs).

Quick Start

Requires Linux with SocketCAN (OrbStack, Ubuntu VM, or WSL2 on Windows).

Docker (easiest)

# One-time setup: create the virtual CAN network
docker run --rm --privileged --pid=host ubuntu:24.04 \
  nsenter -t 1 -m -u -n -i -- sh -c \
  'modprobe vcan; ip link add dev vcan0 type vcan 2>/dev/null; ip link set up vcan0'

# Start everything
docker compose up --build

• Dashboard: http://localhost:3000
• WebSocket: ws://localhost:8080/ws
• Database: localhost:5432

Manual (for development)

# Enter Linux machine (OrbStack)
orb

# Install dependencies (once)
sudo apt update
sudo apt install -y build-essential cmake git can-utils libasio-dev libssl-dev

# Create virtual CAN interface (once per restart)
sudo modprobe vcan
sudo ip link add dev vcan0 type vcan 2>/dev/null
sudo ip link set up vcan0

# Terminal 1: C++ service
cd telemetry && cmake -B build && cmake --build build
./build/telemetry_service

# Terminal 2: Car simulator
cd simulator && pip3 install -r requirements.txt
python3 obd_simulator.py

# Terminal 3 (macOS): React dashboard
cd dashboard && npm install && npm run dev

Project Structure

car-telemetry/
├── simulator/        # Python: fakes car engine data on a virtual CAN bus
├── telemetry/        # C++17: reads CAN frames, decodes OBD-II, serves WebSocket
│   ├── src/
│   ├── include/
│   └── tests/        # Unit tests (Catch2)
├── dashboard/        # React + Recharts: live gauges and fault code display
├── db/               # TimescaleDB schema
├── docs/             # Architecture Decision Records (ADRs)
└── docker-compose.yml

How the Car Protocol Works

Cars use CAN bus — a shared two-wire network connecting all the car's computers (ECUs). Instead of direct wires between every component, every ECU broadcasts messages onto a single pair of wires and others listen.

OBD-II is the standardized diagnostic interface in every car since 1996. You can plug a scanner into the port under the dashboard and request data like RPM or check for fault codes. This project simulates that protocol over a virtual CAN interface (vcan0).

Simulated Signals

Signal	Behavior
Engine RPM	Sine wave 800–4500
Vehicle Speed	Ramp 0–120 km/h
Coolant Temp	Warmup 75°C → 105°C
Engine Load	Tracks RPM
Throttle	Random steps

Every 30–60 seconds, a fault code is injected: P0300 (misfire) or P0128 (thermostat).

Stack

Layer	Technology	Why
CAN interface	Raw SocketCAN	Direct kernel syscalls, no abstraction
WebSocket server	Crow (C++)	Lightweight, header-only
Database	TimescaleDB	PostgreSQL + time-series optimizations
Frontend	React + Recharts	Live gauges and charts

See docs/ for detailed architecture decisions.

Testing

cd telemetry
cmake -B build && cmake --build build
ctest --test-dir build --output-on-failure

Covers: frame decoding, PID parsing, boundary values, DTC parsing.

References

• Linux SocketCAN docs
• python-can
• Crow C++ Framework
• TimescaleDB