Rig Backends

Each interface section in the rig TOML specifies a backend field. This determines which driver is used at runtime. Switching backends requires only a TOML change — test code is unaffected.

CAN backends

`virtual`

In-process simulation. No hardware or OS dependencies. Frames are passed through an in-memory queue.

[rig.can.can0]
interface = "can0"
bitrate   = 500000
backend   = "virtual"

Best for: CI, local development, unit tests, any environment without CAN hardware.

`socketcan`

Linux SocketCAN. Uses the python-can SocketCAN interface. Requires the CAN interface to be configured in the OS before connecting:

sudo ip link set can0 type can bitrate 500000
sudo ip link set can0 up

[rig.can.powertrain]
interface = "can0"
bitrate   = 500000
fd        = false
backend   = "socketcan"

Best for: Linux bench machines with SocketCAN adapters (Kvaser, EMS, or any native CAN interface). No extra install needed — python-can ships with the base package.

`peak`

PEAK PCAN adapters (PCAN-USB, PCAN-PCI). Uses the python-can PCAN interface.

[rig.can.powertrain]
interface = "PCAN_USBBUS1"
bitrate   = 500000
fd        = false
backend   = "peak"

For CAN-FD:

[rig.can.powertrain]
interface = "PCAN_USBBUS1"
bitrate   = 500000
fd        = true
backend   = "peak"

Best for: Windows and Linux benches with PEAK USB or PCIe adapters. No extra install needed — python-can ships with the base package.

Custom backend (module path)

Any Python class implementing AbstractCANBackend can be loaded by specifying its module path. Use "module.path:ClassName", or a bare module path that exports a Backend attribute:

[rig.can.custom_bus]
interface = "COM3"
bitrate   = 500000
backend   = "myorg.my_can_adapter:MyCANBackend"

CruciHiL resolves the path via importlib. This works for every interface type — CAN, SOME/IP, DoIP, power, GPIO, UDP, and UDS sections all accept a module path in their backend field. The class must implement:

from crucihil.hal.backends.base import AbstractCANBackend

class MyCANBackend(AbstractCANBackend):
    async def connect(self, interface: str, bitrate: int, fd: bool = False) -> None: ...
    async def disconnect(self) -> None: ...
    async def send(self, arb_id: int, data: bytes) -> None: ...
    def add_listener(self, cb) -> None: ...
    def remove_listener(self, cb) -> None: ...

Generate a stub with:

crucihil scaffold --adapter can --name MyCANAdapter

DoIP backends

`virtual`

In-process DoIP simulation. Responds to entity discovery and routing activation without network hardware.

[rig.ethernet.eth0]
interface      = "eth0"
ip             = "127.0.0.1"
doip_backend   = "virtual"
someip_backend = "python-someip"

`python-doip`

Real DoIP transport using the python-doip library. Requires an actual DoIP gateway on the network.

[rig.ethernet.chassis_eth]
interface      = "eth1"
ip             = "169.254.0.1"
doip_backend   = "python-doip"
someip_backend = "python-someip"

Best for: ECUs with DoIP-capable diagnostic interfaces (many Tier 1 ECUs support ISO 13400-2).

SOME/IP backends

`python-someip`

SOME/IP Events and Fields. Currently backed by the in-process virtual SOME/IP implementation — used in the virtual rig. Scope: Events and Fields only (Methods come later).

[rig.ethernet.eth0]
someip_backend = "python-someip"

`vsomeip`

Real SOME/IP via the vsomeip wrapper backend.

[rig.ethernet.chassis_eth]
someip_backend = "vsomeip"

Power backends

`virtual_power`

In-process power simulation. Tracks on/off state in memory. No hardware dependency.

[rig.power.ecu_main]
backend = "virtual_power"
default = "on"

`gpio_relay`

Controls power via a GPIO output pin. Typically used with a relay board connected to a GPIO header.

gpio_relay and bench_psu are reserved names whose hardware implementations have not shipped yet — using one fails at rig init with guidance. Until they ship, use a custom power backend via module path.

[rig.power.ecu_main]
backend  = "gpio_relay"
gpio_pin = 18
default  = "off"

`bench_psu`

Controls a bench power supply over serial. Supported instruments include Keysight E3631A and compatible.

[rig.power.ecu_12v]
backend = "bench_psu"
port    = "/dev/ttyUSB0"
model   = "keysight_e3631a"
default = "off"

Custom power backend

[rig.power.custom_supply]
backend = "myorg.bench_hardware:CustomPSUBackend"
default = "off"

Implement AbstractPowerBackend:

from crucihil.hal.backends.base import AbstractPowerBackend

class CustomPSUBackend(AbstractPowerBackend):
    async def connect(self) -> None: ...
    async def disconnect(self) -> None: ...
    async def on(self) -> None: ...
    async def off(self) -> None: ...
    async def read_voltage(self) -> float: ...
    async def set_voltage(self, voltage: float) -> None: ...

GPIO backends

`virtual_gpio`

In-process GPIO simulation. Default for all GPIO pins in virtual mode.

[rig.gpio]
ignition_enable = { pin = 22, direction = "out", default = false, backend = "virtual_gpio" }

`linux_gpio`

Linux GPIO for bench machines and single-board computers with a GPIO header.

linux_gpio is a reserved name whose hardware implementation has not shipped yet — using it fails at rig init with guidance. Until it ships, use a custom GPIO backend via module path.

[rig.gpio]
ignition_enable = { pin = 22, direction = "out", default = false, backend = "linux_gpio" }

Custom GPIO backend

[rig.gpio]
relay_1 = { pin = 1, direction = "out", default = false, backend = "myorg.io_board:IOBoardGPIO" }

Implement AbstractGPIOBackend:

from crucihil.hal.backends.base import AbstractGPIOBackend

class IOBoardGPIO(AbstractGPIOBackend):
    async def connect(self) -> None: ...
    async def disconnect(self) -> None: ...
    async def setup_pin(self, name: str, pin: int, direction: str, default: bool) -> None: ...
    async def set(self, name: str, high: bool) -> None: ...
    async def read(self, name: str) -> bool: ...

UDP backends

`virtual_udp`

In-process UDP simulation for [rig.udp.<name>] sections. Currently the only built-in UDP backend — a real UDP transport ships in a later phase. Custom module paths are accepted.

[rig.udp.telemetry]
interface = "eth0"
ip        = "192.168.1.10"
port      = 5005
backend   = "virtual_udp"

UDS backends

`virtual_uds`

In-process UDS simulation for the [rig.uds] section. Currently the only built-in UDS backend — custom module paths are accepted. UDS over DoIP does not use this section; it is handled by [rig.ethernet] + [rig.ecus].

[rig.uds]
backend = "virtual_uds"
timeout = 2.0

Custom protocol transports

[rig.custom.<name>] sections pair a codec with a transport. Built-in transports are the virtual twins:

Backend	Shape
`virtual_datagram`	Datagram (CAN-like, message-oriented)
`virtual_stream`	Stream (UART/TCP-like, framer delimits)
`virtual_spi`	Transactional (register-map peripheral emulation)
`virtual_i2c`	Transactional (register-map peripheral emulation)

[rig.custom.motor_bus]
backend     = "virtual_datagram"
definitions = "defs/motor_protocol.yaml"
codec       = "declarative"
kind        = "datagram"

Real-hardware transports are loaded via module path (backend = "myorg.uart_bridge:UARTTransport"). Generate a stub with crucihil scaffold --adapter datagram|stream|transactional|codec. See Custom Protocols for the declarative wire-format YAML and the round-trip verification harness.

Backend selection summary

Interface	Development / CI	Linux bench	Windows bench	Custom HW
CAN	`virtual`	`socketcan`	`peak`	module path
DoIP	`virtual`	`python-doip`	`python-doip`	module path
SOME/IP	`python-someip`	`python-someip`	`python-someip`	—
Power	`virtual_power`	`gpio_relay` or `bench_psu`	`bench_psu`	module path
GPIO	`virtual_gpio`	`linux_gpio`	—	module path
UDP	`virtual_udp`	module path	module path	module path
UDS	`virtual_uds`	module path	module path	module path
Custom protocol	`virtual_datagram` / `virtual_stream` / `virtual_spi` / `virtual_i2c`	module path	module path	module path

Rig Configuration

CAN backends

`virtual`

`socketcan`

`peak`

Custom backend (module path)

DoIP backends

`virtual`

`python-doip`

SOME/IP backends

`python-someip`

`vsomeip`

Power backends

`virtual_power`

`gpio_relay`

`bench_psu`

Custom power backend

GPIO backends

`virtual_gpio`

`linux_gpio`

Custom GPIO backend

UDP backends

`virtual_udp`

UDS backends

`virtual_uds`

Custom protocol transports

Backend selection summary

See also

​CAN backends

​virtual

​socketcan

​peak

​Custom backend (module path)

​DoIP backends

​virtual

​python-doip

​SOME/IP backends

​python-someip

​vsomeip

​Power backends

​virtual_power

​gpio_relay

​bench_psu

​Custom power backend

​GPIO backends

​virtual_gpio

​linux_gpio

​Custom GPIO backend

​UDP backends

​virtual_udp

​UDS backends

​virtual_uds

​Custom protocol transports

​Backend selection summary

​See also

CAN backends

`virtual`

`socketcan`

`peak`

Custom backend (module path)

DoIP backends

`virtual`

`python-doip`

SOME/IP backends

`python-someip`

`vsomeip`

Power backends

`virtual_power`

`gpio_relay`

`bench_psu`

Custom power backend

GPIO backends

`virtual_gpio`

`linux_gpio`

Custom GPIO backend

UDP backends

`virtual_udp`

UDS backends

`virtual_uds`

Custom protocol transports

Backend selection summary

See also