canviz 0.2.0

Open-source browser-based CAN bus analyzer

CANviz

A browser-based CAN bus analyzer. Plug in. One command. Analyze.

pip install canviz
canviz
# → browser opens at http://localhost:8080

Works with any Candlelight-firmware USB CAN adapter (~$8). No GUI install. No driver setup. No account. No internet connection required.

---

What CANviz is

CANviz is a pip install away, runs entirely in your browser at localhost, and works with cheap commodity hardware. The goal is to make CAN bus analysis accessible, whether you are an embedded engineer debugging a vehicle ECU, a researcher studying automotive protocols, or a hobbyist building your first CAN project.

It is designed to complement, not replace, the excellent tools that already exist. SavvyCAN is a mature, feature-rich native desktop analyzer with a strong community, if you prefer a native app with a long track record, it is an excellent choice. python-can is the library CANviz is built on and is invaluable for scripting and automation. CANviz takes a different approach: browser-first, pip-installable, and SSH-friendly for engineers working on remote and headless setups.

---

Features

Live message table

Every frame on the bus, in real time. ID, DLC, raw bytes, frame count, update rate, last seen timestamp. Virtual scrolling handles thousands of rows without frame loss. Tested at 2,000 fps sustained with zero drops.

DBC signal decoding

Upload your .dbc file and raw hex bytes become named signal values - inline in the message table. Toggle between raw and decoded view at any time.

Signal time-series plotting (new in v0.2.0)

Plot any DBC-decoded signal as a live time-series graph. Select up to 8 signals simultaneously on a shared time axis. Built on uPlot : handles 36,000 buffered points per signal with LTTB downsampling, rendering at a smooth 10 Hz regardless of bus rate.

• Adjustable time window : 10s, 30s, 1m, 5m, 30m
• Zoom and pan : drag to zoom, double-click to resume live scroll
• Threshold lines : set a limit per signal; line and pill border turn red on breach
• Multi-signal overlay : compare RPM, throttle, and vehicle speed on one axis
• PNG export : one click, includes signal legend and axis labels

Bus health statistics (new in v0.2.0)

Always-visible status bar showing frames Rx/Tx, bus load %, error frame count, bus-off events, and KB/s throughput. Error frame visibility depends on hardware, slcan devices typically drop error frames silently; a tooltip explains this when a slcan interface is active.

Multi-frame transmit with timers (new in v0.2.0)

Build a list of frames, each with its own independent transmission interval. Send a heartbeat at 20 Hz and a speed signal at 10 Hz simultaneously. Each row has its own start/stop control. State persists across tab switches.

Record and replay

Record sessions to industry-standard .asc and .csv formats. Replay any log file with adjustable speed (0.5× to 10×).

CLI and headless mode (new in v0.2.0)

canviz monitor --interface socketcan --channel can0 --dbc vehicle.dbc
canviz capture --output trace.json --duration 60
canviz decode  --input trace.json --dbc vehicle.dbc
canviz serve   --headless --port 8080   # API + WebSocket only, no browser

canviz monitor renders a live colour-coded table in the terminal, works over SSH, in CI pipelines, and on headless Raspberry Pi setups where opening a browser is not an option.

Filtering

Filter by message ID (hex range) or signal name. Filter state persists in the URL so you can share an exact view with a colleague.

---

Security model

CANviz does not use WebUSB or any browser-level hardware access API.

The architecture is:

Browser  (your local browser tab)
    ↕  HTTP + WebSocket : localhost only, never leaves your machine
Python backend  (127.0.0.1:8080)
    ↕  python-can
USB CAN adapter
    ↕
CAN Bus

The browser communicates only with a local Python process at 127.0.0.1:8080. No data leaves your machine. No cloud. No telemetry. No external connections of any kind. All USB communication happens inside the Python backend, the browser never has direct access to your USB device or CAN bus.

The security model is the same as running any locally installed Python tool: you are trusting the code you installed via pip, the same trust you extend to any local development tool. If you are security-conscious, you are encouraged to review the source on GitHub before installing.

Remote deployments: If you are running CANviz on a remote machine (e.g. a Raspberry Pi on a shared network), use the default --host 127.0.0.1 binding and access it via SSH port forwarding. Do not expose port 8080 to an untrusted network without additional controls such as a reverse proxy with authentication.

---

Hardware

Plug and play on Windows

Any module running Candlelight firmware (most cheap CAN USB modules ship with this):

Hardware	Price	Notes
FYSETC UCAN (STM32F072)	~$8	Validated reference hardware
CANable 1.0 (Candlelight firmware)	~$15	Widely available
Any gs_usb / WinUSB compatible device	varies	Should work

These appear in Windows Device Manager as gs_usb / WinUSB : no COM port, no driver install, no reflashing needed.

If your device shows a COM port in Device Manager, it is running slcan firmware. Use --interface slcan --channel COM3 instead.

Also supported

• slcan : devices running slcan firmware (COM port)
• SocketCAN : Linux, Raspberry Pi, WSL2
• PEAK PCAN-USB, Kvaser, Vector : via python-can config, no code changes
• Virtual bus : software loopback, no hardware needed

---

Quick Start

Windows : gs_usb (Candlelight firmware)

pip install canviz
canviz

Auto-detects your connected device. Browser opens automatically.

Windows : slcan / COM port

pip install canviz
canviz --interface slcan --channel COM3 --bitrate 500000

Raspberry Pi / Linux

sudo ip link set can0 up type can bitrate 500000
pip install canviz
canviz --interface socketcan --channel can0

Remote machine over SSH

# On your laptop : forward port 8080 from the remote machine
ssh -L 8080:localhost:8080 user@remote-ip

# On the remote machine
canviz --interface socketcan --channel can0

# Open in your local browser
http://localhost:8080

Headless / no browser

canviz --headless
# Or with the serve subcommand:
canviz serve --headless --port 8080

No hardware : virtual bus

pip install canviz
canviz --interface virtual

---

CLI Reference

Server mode (default)

canviz [OPTIONS]

  --interface   gs_usb | slcan | socketcan | virtual  (default: gs_usb)
  --channel     COM port or SocketCAN channel  (e.g. COM3, can0)
  --bitrate     CAN bitrate in bps  (default: 500000)
  --host        Host to bind to  (default: 127.0.0.1)
  --port        Port to bind to  (default: 8080)
  --headless    Start without opening a browser

Subcommands

# Live terminal monitor (works over SSH)
canviz monitor --interface socketcan --channel can0 --dbc vehicle.dbc

# Capture to file
canviz capture --output trace.json --duration 60

# Decode a captured log
canviz decode --input trace.json --dbc vehicle.dbc --output decoded.csv

# API-only server (no browser)
canviz serve --headless --port 8080

See the CLI Guide for monitor, capture, decode, and SSH workflows.

REST API & WebSocket

Full interactive docs at http://localhost:8080/docs while running.

Method	Path	Description
POST	/connect	Open CAN interface
POST	/disconnect	Close interface
GET	/status	Connection state and config
GET	/stats	Bus statistics snapshot
POST	/send	Transmit a CAN frame
WS	/ws/frames	Live frame + stats stream (JSON)
POST	/dbc/load	Upload a DBC file
GET	/dbc/messages	List decoded message definitions
DELETE	/dbc	Unload DBC
POST	/log/start	Start recording
POST	/log/stop	Stop and finalise log
GET	/log/download/{file}	Download .asc or .csv
POST	/replay/start	Start replaying a log file
POST	/replay/stop	Stop replay

---

Architecture

[CAN Bus]
    ↓
[USB CAN Module]  ~$8–$65 depending on capability
    ↓
[Python Backend]
  FastAPI · python-can · cantools · aiofiles · typer · rich
    ↓  HTTP + WebSocket (localhost only : no external connections)
[Browser UI]
  React 18 · TanStack Table · TanStack Virtual · Zustand · uPlot
    ↓
  http://localhost:8080

---

Validated Hardware & Performance

Hardware	Interface	OS	Status
FYSETC UCAN (STM32F072, Candlelight)	gs_usb	Windows 11	✅ Tested
FYSETC UCAN (STM32F072, Candlelight)	gs_usb	Raspberry Pi OS	✅ Tested
Virtual bus	virtual	Windows / Linux	✅ Tested
PEAK PCAN-USB	pcan	Windows / Linux	Config only
Kvaser	kvaser	Windows / Linux	Config only

Throughput: 2,000 fps sustained - zero frame loss, stable UI, no memory growth.

---

Known Limitations

• USB timestamp jitter ~1 ms : a hardware limitation of USB-connected CAN adapters. Not suitable for sub-millisecond timing analysis.
• Bus load above 2,000 fps : untested. A server-side throttling hook is built in and can be enabled if needed.
• CAN FD : frames with >8 byte payloads display as raw hex. Full CAN FD UI support is in progress and requires CAN FD capable hardware (~$53 minimum).
• slcan error frames : slcan firmware on most adapters silently drops error frames before forwarding to the host. Bus error statistics will read 0% on slcan interfaces even on a degraded bus. Use gs_usb (Candlelight) for accurate error visibility.
• Replay timing : depends on the Python asyncio scheduler, not a wall clock.
• Browser support : tested on Chrome. Firefox and Edge are best-effort.
• Mobile layout : not a target for v1. Optimised for 1080p and above.

---

Roadmap

• v1 : Live frame table, DBC decode, filter, send, record, replay, pip install
• v2 : Signal plotting, multi-signal overlay, threshold alerts, CLI mode, bus health statistics, multi-frame transmit with timers
• v3 : CAN FD UI, J1939 decoder, OBD-II over raw CAN, UDS diagnostics, reverse engineering toolkit, plugin API

See the full project board for live status.

---

Troubleshooting

No matching distribution found for canviz on Ubuntu/Linux Use pip3 install canviz or python3 -m pip install canviz. CANviz requires Python 3.10+. Ubuntu 20.04 ships Python 3.8 : upgrade to 22.04+ or install Python 3.10 separately.

Device shows a COM port on Windows Your adapter is running slcan firmware, not Candlelight. Use: canviz --interface slcan --channel COM3

Plot shows wrong date (1969/1970) Update to the latest version : pip install --upgrade canviz.

---

Contributing

CANviz is actively developed. The most useful contribution right now is testing hardware we have not tried - a CANable 2.0, a PEAK PCAN-USB, anything on macOS, anything on a COM port. No code required. Open an issue and tell us what happened.

Bug reports, DBC files that decode incorrectly, and code contributions are all welcome. See CONTRIBUTING.md for how to get the dev environment running.

---

License

MIT : see LICENSE.