ameersmu2004-rgb/Speedometer-ECU-Simulator
GitHub: ameersmu2004-rgb/Speedometer-ECU-Simulator
Stars: 0 | Forks: 0
# Speedometer ECU Simulator
A futuristic **Tkinter-based GUI** that simulates a real automotive Speedometer ECU. It speaks the **UDS diagnostic protocol** over a virtual CAN bus (`vcan0`), making it a perfect practice target for automotive security testing, CAN fuzzing tools like **FucyFuzz**, or just learning how ECU diagnostics work.
## What This Tool Does
- Renders a live **holographic-style speedometer dial** with animated needle, RPM arc, gear indicator, fuel level, coolant temp, and battery voltage
- Runs a full **UDS/ISO-TP stack** on `vcan0` — responds to real diagnostic requests (ReadDID, WriteData, SecurityAccess, ECUReset, etc.)
- Comes with a **Vulnerability Engine** — load a JSON profile to arm intentional ECU weaknesses for fuzz testing
- Logs every UDS frame, raw CAN frame, and vulnerability trigger in separate panels, exportable to `.log` / `.jsonl`
## Requirements
| Requirement | Why |
|---|---|
| Ubuntu / Debian Linux | `vcan0` virtual CAN requires the Linux kernel `vcan` module |
| Python 3.8+ | Core runtime |
| `python3-tk` | GUI (Tkinter) |
| `python-can` | CAN bus interface library |
| `can-isotp` *(optional)* | Only needed if you want to send test frames from your own scripts |
## Setup & Run
### Step 1 — Clone or copy the project
git clone https://github.com/ameersmu2004-rgb/Speedometer-ECU-Simulator.git
cd Speedometer-ECU-Simulator/speedo-ecu
### Step 2 — One-command launch *(recommended)*
chmod +x run.sh
./run.sh
`run.sh` automatically:
- Checks for Python 3
- Installs `python3-tk` and `python-can` if missing
- Sets up the `vcan0` virtual CAN interface
- Launches the GUI
### Manual Setup (if you prefer step-by-step)
**Install dependencies:**
sudo apt update
sudo apt install -y python3-tk
pip3 install python-can --break-system-packages
**Set up the virtual CAN interface:**
sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0
**Launch the GUI:**
python3 main_speedo.py
## Using the GUI
Once running, the GUI opens with three main areas:
### Left Panel — Speedometer Dial
The animated dial auto-runs a physics simulation: the ECU starts parked, accelerates, cruises, then brakes in a loop. All live values (speed, RPM, fuel, temp) update in real time.
### Right Panel — Controls & Logs
| Tab | What it shows |
|---|---|
| **UDS Log** | Every UDS request and response (SID, DID, NRC) |
| **Raw Frame Log** | Raw CAN frames when `vcan0` is active |
| **Oracle / Vuln Log** | Vulnerability hits and oracle events |
### Loading a Vulnerability Profile
1. Click **Load Vuln JSON** in the controls
2. Select `speedometer_vulns.json` (included in the project folder)
3. The Oracle is now armed — specific malformed UDS frames will trigger logged vulnerability events
## Sending UDS Frames From Your Own Tool
Once the GUI is running, `vcan0` is live. You can talk to it from any tool (FucyFuzz, cantools, raw Python):
pip3 install can-isotp
# Read Vehicle Speed (DID 0xF40D)
import can, isotp, time
bus = can.Bus('vcan0', bustype='socketcan')
addr = isotp.Address(isotp.AddressingMode.Normal_11bits, txid=0x7E0, rxid=0x7E8)
stack = isotp.CanStack(bus, address=addr)
stack.send(bytes([0x22, 0xF4, 0x0D]))
time.sleep(0.2)
stack.process()
if stack.available():
print('Response:', stack.recv().hex().upper())
bus.shutdown()
**ECU Address Config:**
| | Value |
|---|---|
| Tester → ECU (RX) | `0x7E0` |
| ECU → Tester (TX) | `0x7E8` |
| Interface | `vcan0` |
## Supported UDS Services
| SID | Service |
|---|---|
| `0x10` | DiagnosticSessionControl (Default / Extended / Programming) |
| `0x11` | ECUReset |
| `0x27` | SecurityAccess (seed/key challenge) |
| `0x22` | ReadDataByIdentifier |
| `0x2E` | WriteDataByIdentifier |
| `0x3E` | TesterPresent |
| `0x19` | ReadDTCInformation |
| `0x14` | ClearDTC |
| `0x28` | CommunicationControl |
## Project Structure
speedo-ecu/
├── main_speedo.py ← Entry point — run this
├── speedo_gui.py ← Tkinter GUI (dial, gauges, log panels)
├── speedo_ecu.py ← UDS service handler
├── speedo_state.py ← ECU state + physics simulation loop
├── speedometer_vulns.json ← Vulnerability profiles for the Oracle engine
├── run.sh ← Auto-setup + launch script
├── config.py ← CAN interface / address config
├── uds_core.py ← UDS protocol core
├── uds_constants.py ← SID / NRC hex constants
├── uds_helpers.py ← Hex formatting helpers
├── isotp_server.py ← ISO-TP framing layer
├── vulnerability_engine.py ← Evaluates frames against vuln profiles
├── vulnerability_config.py ← Loads JSON vuln config
├── logger.py ← Structured logger (text + JSONL)
├── ecu_memory.py ← Virtual NVM / memory map
├── ecu_state.py ← Base ECU state class
└── logs/ ← Auto-created; session logs saved here
## Troubleshooting
**`ModuleNotFoundError: No module named 'can'`**
pip3 install python-can --break-system-packages
**`ModuleNotFoundError: No module named 'tkinter'`**
sudo apt install python3-tk
**`vcan0` not found / CAN frames not appearing**
sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0
**GUI opens but dial is blank / frozen**
Make sure you are running on a display (not a headless SSH session). If using SSH, forward the display with `ssh -X` or use a desktop session.
## License
Built as part of the FucyTech automotive cybersecurity internship project. For research and educational use.