Backends & Interfaces¶

CANarchy uses python-can as its live transport layer. This page explains how to choose and configure a transport backend, which interface types are available, and how to verify what is in effect.

Important boundary: the transport backend selection applies to transport-facing commands such as capture, send, generate, and gateway, and also to protocol commands when they explicitly accept an interface, such as j1939 monitor <interface>, uds scan <interface>, and uds trace <interface>. Sample/reference providers are still used where a command does not yet have a complete live execution path or when the deterministic scaffold backend is selected.

The Two Backends¶

Backend	What it does	When to use it
`python-can`	Opens a real (or virtual) CAN bus via python-can	Default — live capture, transmit, and gateway
`scaffold`	Returns deterministic fixture transport frames; never touches hardware	Offline demos, testing, CI

The default interface type is socketcan. On Linux with a configured can0, capture works immediately with no config file.

To switch to a different interface type, set it in ~/.canarchy/config.toml:

[transport]
backend = "python-can"
interface = "udp_multicast"

Or via environment variable (current session only):

export CANARCHY_PYTHON_CAN_INTERFACE=udp_multicast

To use the offline scaffold backend:

export CANARCHY_TRANSPORT_BACKEND=scaffold

To confirm what is actually in effect, run:

canarchy config show

Two-Part Addressing: interface vs. channel¶

python-can separates bus type from device address:

Concept	python-can term	CANarchy config key	Example value
Bus driver / adapter type	`interface`	`interface` in `config.toml` / `CANARCHY_PYTHON_CAN_INTERFACE`	`socketcan`, `kvaser`, `pcan`
Device or port within that type	`channel`	positional CLI argument or `[transport].default_interface` / `CANARCHY_DEFAULT_INTERFACE`	`can0`, `PCAN_USBBUS1`, `0`

Example: SocketCAN on Linux, interface can0:

canarchy capture can0   # channel = can0, interface type from config

To avoid repeating the same channel on every command, configure a default CAN interface:

[transport]
default_interface = "can0"

Then commands that accept one CAN interface can omit it:

canarchy capture
canarchy send 0x123 11223344 --json

An explicit command-line interface still wins over the configured default.

Example: PCAN-USB:

[transport]
backend = "python-can"
interface = "pcan"

canarchy capture PCAN_USBBUS1

Supported Interface Types¶

The table below covers common python-can interface types. CANarchy passes the configured interface value to python_can.Bus(channel=<channel>, interface=<interface>), so the live hardware capability comes from python-can and the vendor driver/runtime installed on the host.

Interface name	Hardware / use case	OS	Driver or dependency	Example channel
`socketcan`	Linux SocketCAN — real hardware through kernel drivers, `vcan` virtual interfaces, and many USB adapters	Linux	Kernel SocketCAN support plus device driver	`can0`, `vcan0`
`virtual`	python-can in-process virtual bus	Any	`python-can` only	`canarchy-test`
`udp_multicast`	UDP multicast virtual bus visible across processes and hosts	Any	`python-can` only; multicast routing/firewall must allow traffic	`239.0.0.1`
`pcan`	PEAK PCAN-USB and PCAN-PCIe adapters	Windows, Linux, macOS	PEAK PCAN driver/API	`PCAN_USBBUS1`
`vector`	Vector VN/VX-series hardware	Windows	Vector XL Driver Library	`0`, `1`, or configured application channel
`kvaser`	Kvaser USB/PCIe adapters	Windows, Linux	Kvaser CANlib SDK/runtime	`0`, `1`, or channel name
`ixxat`	HMS IXXAT adapters	Windows	IXXAT VCI driver/runtime	adapter-specific channel
`slcan`	Serial-line CAN adapters using ASCII CAN over USB/UART	Any	Serial device access; often `python-can` plus OS serial permissions	`/dev/ttyACM0`, `COM3`
`cantact`	CANtact / candleLight USB devices	Any	libusb / candleLight support per OS	device-specific channel
`gs_usb`	Geschwister Schneider / candleLight USB devices through kernel driver	Linux	Linux `gs_usb` kernel driver	`can0` or USB channel
`canalystii`	USB-CAN Analyzer II adapters	Any	python-can CANalyst-II dependencies and vendor library where required	`0`
`usb2can`	8devices USB2CAN	Linux	Kernel driver / SocketCAN-compatible setup	`can0`
`neovi`	Intrepid Control Systems neoVI hardware	Windows	Intrepid driver/runtime	device-specific channel
`nican`	National Instruments NI-CAN	Windows	NI-CAN runtime	`CAN0`
`nixnet`	National Instruments NI-XNET	Windows	NI-XNET runtime	interface alias
`remote`	python-can remote server over TCP	Any	Reachable python-can remote server	server endpoint

Full and up-to-date list

The canonical reference for all supported interfaces, per-interface configuration options, and required driver packages is the python-can documentation — Interfaces. CANarchy does not restrict which interfaces are available. If python-can supports an interface and its runtime is installed, configure the python-can interface name with [transport].interface or CANARCHY_PYTHON_CAN_INTERFACE and pass the channel as the command interface.

Validation scope

canarchy doctor is intentionally offline. For configured vendor interfaces such as pcan, vector, kvaser, ixxat, neovi, nican, nixnet, and canalystii, it checks whether the corresponding python-can interface module is importable and gives a driver/runtime hint when it is not. It does not open a device, claim a CAN transceiver is wired correctly, or validate bus traffic. Use the cookbook recipes below for live lab verification.

cannelloni CAN-over-UDP interop¶

cannelloni tunnels SocketCAN frames over UDP/TCP/SCTP and is the remote-bus transport used by the UTHP / TCAT heavy-vehicle appliances. CANarchy speaks the cannelloni UDP datagram wire format (version 2) so captures can be sent to, or decoded from, a cannelloni endpoint — frame-format interop, not a new python-can hardware backend.

This is a dedicated command surface rather than a [transport].interface: python-can's udp_multicast uses its own framing and does not interoperate with cannelloni.

# decode a captured cannelloni datagram payload into CAN frame events
canarchy cannelloni decode --file captured_udp_payload.bin --json

# preview the datagrams a capture would produce (no socket opened)
canarchy cannelloni send 192.168.1.50:20000 --file drive.candump --dry-run --json

# transmit a capture to a cannelloni endpoint as UDP datagrams
canarchy cannelloni send 192.168.1.50:20000 --file drive.candump --ack-active

cannelloni decode is passive and file-backed: it reads one or more concatenated cannelloni datagrams and emits the canonical frame events.
cannelloni send is an active-transmit path — it honours the active-transmit safety model (--ack-active, YES confirmation, [safety].require_active_ack); --dry-run plans the datagrams (returned as hex in the envelope) without opening a socket.
--max-count bounds frames per datagram (default 64); --rate paces datagrams per second; --seq-no sets the starting cannelloni sequence number.
The wire codec supports classic CAN, extended, RTR, error, and CAN FD frames (BRS/ESI flags). cannelloni send is CLI-only and not exposed as an MCP tool (active UDP egress to an arbitrary host); cannelloni decode is exposed.

Common Setups¶

SocketCAN on Linux (real hardware or vcan)¶

[transport]
backend = "python-can"
interface = "socketcan"

Bring up a virtual interface for testing without hardware:

sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0
canarchy capture vcan0

UDP Multicast (cross-process, no hardware)¶

Useful for testing across terminal sessions on a single machine or across hosts on a LAN. On macOS you may need a multicast route:

sudo route add -net 239.0.0.0/8 -interface lo0

[transport]
backend = "python-can"
interface = "udp_multicast"

# Terminal 1
canarchy capture 239.0.0.1 --candump

# Terminal 2
canarchy send 239.0.0.1 0x123 DEADBEEF

PCAN-USB / PCAN-PCIe¶

[transport]
backend = "python-can"
interface = "pcan"
default_interface = "PCAN_USBBUS1"

canarchy doctor --text
canarchy capture PCAN_USBBUS1 --candump

Install the PEAK PCAN driver/API for the host OS first. On Linux, SocketCAN may also expose PEAK devices as can0; use socketcan instead of pcan if you intentionally choose the kernel SocketCAN path.

Vector VN/VX hardware¶

[transport]
backend = "python-can"
interface = "vector"
default_interface = "0"

canarchy doctor --text
canarchy capture 0 --candump

Install the Vector XL Driver Library and configure the application/channel mapping with Vector tooling before opening the bus. Vector hardware access is normally Windows-first.

Kvaser USB / PCIe hardware¶

[transport]
backend = "python-can"
interface = "kvaser"
default_interface = "0"

canarchy doctor --text
canarchy capture 0 --candump

Install Kvaser CANlib before using the kvaser backend. On Linux, some Kvaser devices can also be exposed through SocketCAN; choose socketcan when you want to use the kernel can0 path.

IXXAT, neoVI, NI-CAN, NI-XNET, and other vendor backends¶

Configure the python-can interface name and vendor-specific channel exactly as python-can documents it. Examples:

[transport]
backend = "python-can"
interface = "ixxat"      # or neovi, nican, nixnet, canalystii
default_interface = "0"  # replace with the vendor channel name

Then run:

canarchy doctor --text
canarchy capture --candump

doctor can catch missing importable python-can interface modules for several vendor backends, but the authoritative hardware setup remains the vendor driver documentation plus python-can's interface page.

Virtual (same-process only)¶

[transport]
backend = "python-can"
interface = "virtual"

The virtual interface only delivers frames within the same Python process. Use udp_multicast if you need cross-process visibility.

Windows hardware adapters¶

On Windows, install the vendor driver before opening a live CAN channel. CANarchy delegates live bus access to python-can, so the configured interface value must match the vendor backend and the command argument must match the vendor channel name.

Adapter family	Driver pointer	Interface type	Typical channel
Vector VN/VX	Vector Driver Setup	`vector`	`0`
PEAK PCAN-USB/PCIe	PEAK-System drivers	`pcan`	`PCAN_USBBUS1`

PowerShell example for PCAN-USB:

$env:CANARCHY_PYTHON_CAN_INTERFACE = "pcan"
canarchy config show
canarchy capture PCAN_USBBUS1 --candump

PowerShell example for Vector:

$env:CANARCHY_PYTHON_CAN_INTERFACE = "vector"
canarchy config show
canarchy capture 0 --candump

SocketCAN and vcan are Linux-only. For Windows no-hardware tests across terminals, prefer udp_multicast; for deterministic offline smoke tests and CI, prefer CANARCHY_TRANSPORT_BACKEND=scaffold.

Verifying Your Configuration¶

canarchy config show
canarchy doctor --text

Output shows each value and its source ([env], [file], or [default]):

Effective transport configuration:
  backend: python-can  [default]
  interface: socketcan  [default]
  capture_limit: 2  [default]
  capture_timeout: 0.05  [default]
config file: /Users/you/.canarchy/config.toml  [not found]

Use --json for scripted inspection:

canarchy config show --json | jq .data.backend

config show reports the effective configuration and source of each value. doctor adds offline dependency checks, including a vendor-backend import check when [transport].interface is set to a supported hardware backend. A successful doctor result means the configured software stack is importable, not that hardware was opened.

For short live verification flows, see: