Get started
Try it with zero hardware first, then plug in an adapter.
Every path below opens the bus listen-only. You can run the whole stack with no car and no adapter, so there's no reason not to start there.
Try it with zero hardware first, then plug in an adapter.
Every path below opens the bus listen-only. You can run the whole stack with no car and no adapter, so there's no reason not to start there.
Start here
The simulator emits a realistic VAG-style bus. This is the fastest way to see the cockpit working and learn the tools.
# Backend — simulated bus
cd backend && pip install -r requirements.txt
python -m discodb2_backend --source sim # ws://localhost:8765/ws + /health
# Cockpit — the full client, in another terminal
cd frontend/cockpit && npm install && npm run dev # http://localhost:5173
# Copilot — the phone view (optional)
cd frontend/copilot && npm install && npm run dev # open the printed Network URL
Open http://localhost:5173 and click Start.
Backend and cockpit on the same machine talk over localhost —
no network setup, no mDNS.
On your own machine
The simplest layout for bench RE: backend and cockpit on the same laptop or
desktop, talking over localhost. Pick your platform — the CAN
adapter path differs.
The easiest. brew install python node libusb, then the
gs_usb adapter works over libusb with no driver install.
No SocketCAN on macOS — gs_usb is the first-class path.
The candleLight adapter binds the in-kernel gs_usb driver
and appears as SocketCAN can0 — the same path the Pi uses,
and the recommended one. --source socketcan.
No SocketCAN, and libusb needs a WinUSB driver swap (Zadig). Easiest is
an slcan-firmware adapter on a COM port (--source slcan);
gs_usb works too, with the driver dance. Bonne chance.
Leave it in the car
The Pi becomes a self-contained WiFi access point you join with your
phone or laptop. It brings up can0 listen-only, starts the
backend on boot, and serves the cockpit — no internet, no cloud.
Dev sandbox
A containerised backend for sim/replay — exercise the full WebSocket contract with zero hardware. Feeding a real adapter into a container is host-specific and Linux-only; for real hardware, prefer the native path.
docker compose -f infra/docker/docker-compose.yml up backend
# then connect a client to ws://localhost:8765/wsWhat you need
A candleLight/gs_usb device — e.g. the FYSETC UCAN
(VID 0x1d50 / PID 0x606f), or a CANable v2.
Or nothing: use the simulator to learn first.
Typically the car's OBD-II port. Confirm the bitrate — 500 kbit/s is common on VAG powertrain buses; comfort buses are often 100 kbit/s.
macOS, Linux or Windows — or a Raspberry Pi (1 B+ to 3 B+) to leave in the car.