DocumentationGetting started

Hardware

What to buy at each stage, from a laptop alone to a full vehicle, the boards and CAN interfaces the framework targets, and the OVCS1, OVCS Mini and OBD2 builds as worked examples.

You can go a long way with OVCS before you buy anything. This page walks through the stages in the order most builds take them: a laptop alone, a laptop on a real CAN bus, a VMS board, generic controllers, then bridges and extras. For each it says what to get and what the repository configures for it. Then it describes what the framework targets, and the three reference vehicles' builds as worked examples: OVCS1 with five isolated buses on a full-size car, the OVCS Mini with two buses on an RC car, and the OBD2 scan tool.

#Nothing but a laptop

A Linux laptop runs a whole vehicle. ./ovcs run <vehicle> creates the virtual CAN interfaces the vehicle's default_can_mapping(:host) names, compiles every firmware for the host and boots one BEAM per role, joined in an Erlang cluster. The Quickstart does this with a reference vehicle; the commands are the same for yours.

What works with zero hardware:

  • the VMS, the infotainment and the bridges, talking over vcan interfaces;
  • the Vue dashboard and ./ovcs attach <vehicle>, which decodes every frame with your vehicle's YAMLs;
  • injecting and replaying traffic with cansend, cangen and canplayer, including real captures under candumps/ (Testing with CAN);
  • the Gazebo simulator, with Docker: the OVCS Mini reference vehicle's VMS drives its model over the same vcan interfaces (Simulation).

The one requirement is the vcan kernel module: it ships in standard Linux kernels, not in WSL2's or most cloud kernels, so on macOS or Windows use a full Linux VM. Getting started covers the setup.

#A laptop on a real bus

The next step is a USB CAN adapter that Linux exposes as a SocketCAN interface (can0, can1, …). The repository doesn't name a specific adapter; anything that shows up in ip link as a can device works, since Cantastic binds raw SocketCAN sockets.

Bring the interfaces up at the bus bitrate. scripts/setup_can.sh sets can0, can1 and can2 to 500 kbps with a 10000-frame transmit queue:

sh
sudo ip link set can0 type can bitrate 500000
sudo ip link set can0 txqueuelen 10000
sudo ip link set up can0

Edit it to match the bitrates in your vehicle's vms.yml and the interfaces you actually have.

Then point the host VMS at the adapter instead of a vcan with CAN_NETWORK_MAPPINGS, which replaces the composer's mapping at boot. Cantastic refuses a mapping that names a network the side's YAML doesn't declare. With the OVCS Mini reference vehicle, putting ovcs on the adapter and leaving misc virtual:

sh
CAN_NETWORK_MAPPINGS=ovcs:can0,misc:vcan1 ./ovcs run ovcs_mini

Watch the bus with candump:

sh
candump can0                  # everything
candump can0,701:7FF          # one id, exact match
candump -L can0 > capture.log # record for canplayer

This is enough to adopt and test a generic controller from your desk, or to capture a car's traffic before writing its frame YAMLs. Mapping rules and the override's limits are in Running on hardware.

#A VMS: a Raspberry Pi 4 and a CAN interface

The VMS runs on a Raspberry Pi 4 with the ovcs_base_can_system_rpi4 Nerves system, which carries the CAN kernel modules and device-tree overlays. You need one SPI CAN controller per bus the VMS owns.

The OVCS1 and OVCS Mini reference vehicles use a custom multi-CAN SPI hub with MCP2517FD controllers, and custom single-channel HATs on the other Pis (CAN interface hardware). Their schematics and BOMs are not published in this repository: there are no KiCad, Gerber or BOM files in it. The off-the-shelf path is a commercial SPI CAN HAT with an MCP2515 or an MCP251xFD controller.

#The config.txt line

The Pi learns about the controller from a device-tree overlay in config.txt. The VMS firmware takes vehicles/<vehicle>/priv/firmware/vms/config.txt when your vehicle ships one and falls back to vms/firmware/targets/ovcs_base_can_system_rpi4/config.txt otherwise (vms/firmware/config/config.exs). The default is the five-controller hub, so with an off-the-shelf HAT, add your own file.

An MCP2515 HAT with 16 MHz crystals, such as the Waveshare 2-CH CAN HAT the OBD2 reference vehicle uses: CAN0 on SPI0 chip select 0 with its interrupt on GPIO 23, CAN1 on chip select 1 with its interrupt on GPIO 25 (vehicles/obd2/priv/firmware/vms/config.txt). A single-channel HAT needs only the mcp2515-can0 line:

text
dtparam=spi=on
dtoverlay=mcp2515-can0,oscillator=16000000,interrupt=23
dtoverlay=mcp2515-can1,oscillator=16000000,interrupt=25
dtoverlay=spi-bcm2835-overlay

An MCP251xFD controller with a 40 MHz oscillator. The OVCS Mini reference vehicle has two, on SPI0 and SPI1 (vehicles/ovcs_mini/priv/firmware/vms/config.txt):

text
dtoverlay=spi0-2cs
dtoverlay=spi1-3cs

dtoverlay=mcp251xfd,spi0-0,oscillator=40000000,interrupt=4 # cs_pin=8
dtoverlay=mcp251xfd,spi1-0,oscillator=40000000,interrupt=5 # cs_pin=18

OVCS1 adds three more on the same pattern: spi0-1 (interrupt 14), spi1-1 (interrupt 6) and spi1-2 (interrupt 12) (vehicles/ovcs1/priv/firmware/vms/config.txt). The oscillator= and interrupt= values belong to the board, not the framework: the reference numbers are the custom hub's. Take the crystal frequency and the INT GPIO from your HAT's documentation.

#The mapping must match the overlays

On target, the VMS composer's default_can_mapping(:target) names each network's SPI device as spiB.C, bus B, chip select C. That is the device the overlay's spiB-C parameter creates. At boot, VmsFirmware.Util.NetworkMapper waits for /sys/bus/spi/devices/spiB.C/net and binds the network to whichever canN the kernel attached there. If the overlay created nothing, the boot aborts with SPI interface 'spiB.C' to be used for '<network>' not ready within 5 seconds.

The OVCS Mini's composer declares its two buses against the two overlays above:

elixir
def default_can_mapping(:host), do: "ovcs:vcan0,misc:vcan1"
def default_can_mapping(:target), do: "ovcs:spi0.0,misc:spi1.0"

A vehicle generated from the template starts with ovcs:spi0.0. One MCP251xFD on spi0-0, or an MCP2515 through mcp2515-can0 (SPI0, chip select 0), satisfies it. Each extra bus is one more overlay and one more network:spiB.C pair. Bitrates come from vms.yml; Cantastic sets them at boot, with no manual step.

Building and flashing the image is in Running on hardware.

#Generic controllers

A generic controller is an Arduino R4 Minima running the framework firmware in controllers/generic_controller/. It doesn't use the board's built-in CAN peripheral. Per board, you need:

PartConnectionSource
Arduino R4 Minimaany Arduino-compatible board with EEPROM should workGeneric controllers
MCP2517FD SPI CAN controller, 40 MHz oscillatorCS on D10, INT on D3, SPI on D11 (COPI), D12 (CIPO), D13 (SCK)SPI_CAN_CS, SPI_CAN_INT, CAN_OSCILLATOR in lib/Can/Can.h
CAN transceiverbetween the MCP2517FD and the busGeneric controllers
Adoption push buttonD2Pin mapping
Up to two MCP23008 I2C expanders (optional)A4 (SDA), A5 (SCL), addresses 0x20 and 0x21src/main.cpp
PWM hat (optional)UART on D0/D1, 115200 baudController::initializeSerialTransfer in lib/Controller/Controller.cpp

The expanders give 16 more digital pins (OVCS pins 3–18). The PWM hat drives the four external PWM outputs (0x7X5–0x7X8). The repository describes it only by its interface: the Arduino sends it duty and frequency packets over the UART with SerialTransfer, resending every 100 ms. Its hardware and firmware are not in this repository, and neither is a transceiver part number.

The firmware runs CAN at 500 kbps by default (CAN_BITRATE in Can.h), and the bus a controller joins must run at that rate. For another bitrate, set CAN_BITRATE as a build flag and reflash (Generic controllers). Flashing, adoption and candump checks are in Generic controllers.

#Bridges and extras

Each of these is optional. On the reference vehicles each runs in a bridge firmware on its own Pi; Why every bridge firmware is its own Pi explains why. A bridge firmware Pi with a CAN connection needs one CAN controller on the ovcs bus. The reference bridges use mcp251xfd,spi0-0,oscillator=40000000,interrupt=4, mapped as ovcs:spi0.0 in the vehicle's bridge_firmwares/0.

ExtraHardwareWhat the repository configures
Radio control (RadioControlBridge)Raspberry Pi 3A, an ExpressLRS receiver that outputs MAVLink, an ExpressLRS handsetThe reference config.txt loads sc16is75x-spi for the SC16IS752; the vehicle's radio_control_bridge_config(:target) reads the receiver on ttySC0 at 460800 baud (vehicles/ovcs_mini/lib/ovcs_mini.ex, radio control bridge)
ROS (RosBridge)Raspberry Pi 4 (or 5), optional BNO085 IMU on I2C, optional SLAMTEC RPLIDAR C1 and DFRobot A02YYUW ultrasonic sensors on USB serial adapters{:imu_publisher, driver: BNO085.I2C}, {:lidar_publisher, driver: RPLidar.UART} and one {:range_publisher, driver: A02YYUW.UART} per sensor on target, OvcsDrivers.Imu.Dummy on the host (ROS bridge)
Perception (RosBridge components)Raspberry Pi 5, two Camera Module 3 (IMX708) on cam0 and cam1, a Hailo-8 on a Hailo hatNo CAN controller: it maps ovcs:vcan0 and reaches the vehicle over Zenoh (Perception, ros_vision/config.txt)
Vision unit (vision role)Raspberry Pi 5 with two cameras on cam0 and cam1 and, for detection, a Hailo-8 on a Hailo hat; or an OKdo Nano C100 with two Camera Module 3 (IMX708), powered from a dedicated supply rather than over USBNo CAN controller: it reaches the vehicle over Zenoh. On the Pi 5, the default config.txt detects the cameras (camera_auto_detect=1). No reference vehicle runs one (Vision unit)
ROS compute nodeRaspberry Pi 5 (8 GB), NVMe SSD in a USB enclosure, Intel AX210 on M.2, Pi 5 RTC batterybalenaOS, not Nerves; no CAN (ROS compute node)
InfotainmentRaspberry Pi 5, a touchscreen (10-inch in OVCS1), one CAN controller on ovcsThe reference config.txt loads mcp251xfd,spi0-0,oscillator=40000000,interrupt=25; the composer maps ovcs:can0 (Infotainment)

The infotainment firmware has no SPI device lookup: it binds can0 directly, which is the name the kernel gives the only CAN controller on the board.

The Nerves system each role builds against is listed in Supported hardware and Nerves systems.

#Why every bridge firmware is its own Pi

  • Failure isolation. A misbehaving radio link or ROS publisher can hang its own BEAM without taking the VMS supervision tree down.
  • Cabling. RC receivers live near the antenna and the ROS sensors ride with the autonomy stack; both are far from the VMS bay.
  • Targets. The Pi 3A is cheap and adequate for the radio control bridge; the ROS bridge needs the memory of a Pi 4 or 5.

The BEAMs still join one Erlang cluster through OvcsBus.Cluster, so at the application level they talk as if they were processes in one VM. Any vehicle can make the same choice, or bundle several bridges into one image through bridge_firmwares/0.

#Power, ground and termination

The repository documents a few specifics and no general wiring rules. What it says:

  • VESC drivetrain. The VESC has no termination resistor of its own, so the bus keeps its existing terminations. Its CAN ground is the vehicle ground. It stays powered from the traction battery; the VMS doesn't switch it (VESC).
  • OBD2 cable. Pin 6 is CAN-High, pin 14 CAN-Low, pins 4 and 5 ground; pin 16 carries 12 V, used only if the VMS draws its power from the port (OBD2). Continuous polling keeps the car's ECUs awake and drains a parked car's 12 V battery.
  • Compute node supply. A Pi 5 booting from USB behind a DC-DC converter needs PSU_MAX_CURRENT=5000 in its bootloader EEPROM, and the converter must then deliver 5 A at 5 V, or boot failures turn into brownouts under load (Boot media).
  • OVCS1 harnesses. vehicles/ovcs1/WIRING.md lists the Leaf inverter's ignition relay, ground and 12 V pins, and the CAN-High/CAN-Low pins of the iBooster, steering pump and Polo drive bus connectors. It is marked work in progress: the 12 V distribution and the OVCS controller looms are not captured yet.

For termination, grounding and supply on your own buses, follow the documentation of your transceivers and components.

#What the framework targets

The framework targets off-the-shelf boards: Raspberry Pis for the Elixir firmwares, with an OKdo Nano C100 as the vision unit's other board, and Arduino R4 Minimas for I/O, joined by CAN interface boards. Every vehicle shares that. Two principles shape it: each manufacturer's CAN bus stays isolated, bridged only through the VMS (Architecture), and the parts stay off the shelf, so the kit is affordable and accessible.

#Computing devices

DeviceFramework roleCAN connectivity
Raspberry Pi 4Vehicle Management System (VMS)All of the vehicle's CAN buses, through the multi-CAN SPI hub
Raspberry Pi 5Infotainment (optional)The ovcs bus
Raspberry Pi 3ABridge firmware running the radio control bridge (optional)The ovcs bus
Raspberry Pi 4 or 5Bridge firmware running the ROS bridge (optional)The ovcs bus (one running only perception may have none and reach the vehicle over Zenoh)
Raspberry Pi 5, or OKdo Nano C100Vision unit (optional)None; it reaches the vehicle over Zenoh
Raspberry Pi 5 (8 GB)ROS compute node: balenaOS, not Nerves (optional)None; it runs the Zenoh router the bridges peer with
Arduino R4 MinimaGeneric controllers, as many as the vehicle declaresThe ovcs bus

A vehicle declares which roles it uses, and on which boards, in its OvcsVehicle module (vms_target/0, infotainment/0 and infotainment_target/0, vision/0 and vision_target/0, the bridge_firmwares/0 map) and in its VMS composer's generic_controllers/0.

#CAN interface hardware

  • Custom Raspberry Pi CAN HATs: SPI-to-CAN boards connecting a Pi to one CAN network. Used on the infotainment and bridge Pis.
  • Custom multi-CAN SPI hub: fans the VMS Pi 4's SPI out to MCP2517FD CAN controllers, one per bus, each with its own transceiver. Cantastic addresses them as spiN.M interfaces (spi0.0, spi1.0, …); a vehicle maps its network names onto them in default_can_mapping(:target).

The framework's ovcs bus carries controller adoption, heartbeats, infotainment and bridge commands. Vehicles with many nodes on it run it at 1 Mbps; manufacturer buses run at the stock bitrate their components require.

#Supported hardware and Nerves systems

Framework rolePlatformNerves target
VMSRaspberry Pi 4ovcs_base_can_system_rpi4
InfotainmentRaspberry Pi 5ovcs_base_can_system_rpi5
Bridge firmware running the radio control bridgeRaspberry Pi 3Aovcs_base_can_system_rpi3a
Bridge firmware running the ROS bridgeRaspberry Pi 4 or 5ovcs_base_can_system_rpi4, or rpi5 (the ovcs_bridges_system_rpi5 system)
Vision unitRaspberry Pi 5, or OKdo Nano C100rpi5 (the ovcs_bridges_system_rpi5 system), or okdo_c100 (the nerves_system_okdo_c100 system)
Generic controllerArduino R4 MinimaPlatformIO, not Nerves

The OVCS systems add the CAN kernel modules and device-tree overlays the SPI CAN boards need. They matter only when building firmware for physical hardware; local development never touches them. Each role's Nerves target comes from the vehicle's module (vms_target/0, infotainment_target/0, vision_target/0, the :target key of each bridge_firmwares/0 entry), so moving a vehicle to different boards means changing those values and adding the matching system dependency to the framework firmware's mix.exs, plus a targets/<target>/fwup.conf in that firmware (the vision firmware falls back to the system's own), and for bridges a system_deps/1 clause and the bridge library's targets: list. Why the host Elixir/OTP pin is tied to these systems is in Toolchain and OTP.

#Worked example: the OVCS1 reference vehicle

OVCS1 is a 2007 Volkswagen Polo 9N converted to an electric vehicle. It uses every role the framework offers: VMS, infotainment, two bridges and generic controllers, on five isolated buses. Pin-level notes are in the OVCS1 wiring reference.

#Components

ComponentManufacturerPurpose
Leaf AZE0 inverter and motorNissanElectric drivetrain: motor control, regenerative braking
NV200 battery cellsNissanHigh-voltage pack in custom aluminium enclosures
iBooster Gen2BoschElectronic brake booster replacing the vacuum-assisted brakes
LWS steering angle sensorBoschSteering position feedback
BMS2OrionBattery management: cell monitoring, balancing, protection
EVPT23EVPTOn-board charger
Polo 9N systemsVolkswagenABS, instrument cluster, ignition lock, power steering pump

#Topology

Every vehicle CAN bus terminates on the VMS Pi 4, so components on different buses never see each other's traffic and identifier collisions can't happen. The ovcs bus connects the VMS to the infotainment Pi, the two bridge firmwares and the Arduino controllers. The VMS, infotainment and bridge firmware BEAMs also form one Erlang-distribution mesh.

text
                 ExpressLRS handset       ROS 2 / Foxglove        Vue dashboard (laptop)
                        | MAVLink UART         | Zenoh                 | HTTP + WebSocket
                        v                      v                       |
               radio_control firmware     ros firmware                 |
               (Pi 3A)                    (Pi 4, BNO085 IMU)           |
                        |                      |                       |
  ovcs (1 Mbps) ========+======================+==========+============+=========
       |                |                  |              |            |
  Infotainment     Front controller   Rear controller  Controls      VMS (Pi 4)
  (Pi 5)           0x70x              0x71x            controller    |
                                                       0x72x         +-- leaf_drive (500 kbps): Leaf inverter        
                                                                     +-- polo_drive (500 kbps): ABS, cluster, ignition, airbag
                                                                     +-- orion_bms  (500 kbps): Orion BMS2, EVPT23 charger
                                                                     +-- misc       (500 kbps): Bosch iBooster, LWS sensor
NetworkBitratePurposeConnected components
ovcs1 MbpsFramework-internal communicationVMS, infotainment, controllers, radio_control and ros bridge firmwares
leaf_drive500 kbpsNissan Leaf drivetrainLeaf inverter
polo_drive500 kbpsOriginal VW Polo systemsABS, dashboard, ignition lock, airbag
orion_bms500 kbpsBattery managementOrion BMS2, EVPT23 charger
misc500 kbpsAdditional componentsBosch iBooster, Bosch LWS steering sensor

The hub gives OVCS1's VMS five MCP2517FD controllers: spi0.0 (ovcs), spi0.1 (leaf_drive), spi1.0 (polo_drive), spi1.1 (orion_bms), spi1.2 (misc). Network names and bitrates are your vehicle's own, declared in its vms.yml and mapped to interfaces in default_can_mapping/1. A driver for a part on one of these networks takes its name as a network: option; only the framework's own components expect ovcs.

#Controllers

ControllerCAN ID rangePurpose
Front controller (0x70x)0x701–0x704High-voltage contactors, front sensors and relays
Rear controller (0x71x)0x711–0x714Water pump, rear sensors and relays
Controls controller (0x72x)0x721–0x725Steering column PWM, throttle pedal DAC, control inputs
Test controller (0x73x)0x731–0x738Development and testing, all pin types

#Parts

RolePart
VMSRaspberry Pi 4 with the custom hub: five MCP2517FD, spi0.0 ovcs (1 Mbps), spi0.1 leaf_drive, spi1.0 polo_drive, spi1.1 orion_bms, spi1.2 misc (500 kbps each)
InfotainmentRaspberry Pi 5 with a touchscreen
BridgesRadio control on a Pi 3A; ROS on a Pi 4 with a BNO085 IMU
ControllersThree Arduino R4 Minima: front (id 0), rear (id 1), controls (id 2)
DrivetrainNissan Leaf AZE0 inverter and motor; NV200 cells in custom enclosures
Battery and chargingOrion BMS2; EVPT23 charger
Braking and steeringBosch iBooster Gen2; Bosch LWS steering angle sensor; Polo power steering pump
Donor systemsPolo 9N ABS, instrument cluster, ignition lock

#Worked example: the OVCS Mini reference vehicle

The OVCS Mini reference vehicle runs the same framework on a Traxxas 4WD chassis, with no infotainment side.

RoleHardware
VMSRaspberry Pi 4, two MCP2517FD: spi0.0 ovcs, spi1.0 misc
ControllerOne Arduino R4 Minima ("main") with a PWM hat
MotorHobbywing Xerun AXE540 R2 sensored brushless motor, driven by a Flipsky Mini FSESC 6.7 Pro (VESC, id 1) on misc; see VESC
SteeringTraxxas servo on PWM hat output 0, 100 Hz
Spur rotationHall-effect sensor on the main controller's A1, counted by interrupt and reported as a frequency on 0x709
Radio controlExpressLRS receiver on a Pi 3A running the radio_control bridge firmware
ROS 2The ros bridge firmware on a Pi 4; the ros_vision bridge firmware on a Pi 5 with two IMX708 cameras and a Hailo-8
Compute nodeRaspberry Pi 5 running balenaOS from an NVMe SSD in a USB enclosure: Zenoh router, Foxglove bridge, Nav2, the vehicle's Wi-Fi access point. The bootloader EEPROM needs PSU_MAX_CURRENT=5000 to boot from USB on the vehicle's supply; see ROS compute node, Boot media

The Mini's VMS has two buses:

NetworkBitrateInterfaceConnected components
ovcs500 kbpsspi0.0Main controller, radio_control and ros bridge firmwares
misc500 kbpsspi1.0Third-party components: the traction motor's VESC (id 1)

The bridge firmwares sit only on ovcs; misc is the VMS's alone, so third-party traffic and identifiers never mix with the controller and bridge frames. The VESC is a CAN node of its own, commanded with closed-loop speed and reporting motor rpm, current and battery voltage. Its frames use 29-bit extended identifiers, which coexist with standard frames on the same bus.

#Worked example: the OBD2 reference vehicle

A scan tool with no drivetrain and no bridges (OBD2).

RolePart
VMSRaspberry Pi 4 with a Waveshare 2-CH CAN HAT (two MCP2515, 16 MHz): CAN0 spi0.0 obd2 (interrupt GPIO 23), CAN1 spi0.1 ovcs (interrupt GPIO 25)
Car connectionAn OBD-II cable to the HAT's CAN0 channel: pin 6 CAN-High, pin 14 CAN-Low, pins 4 and 5 ground
Infotainment (optional)Raspberry Pi 5, one CAN controller on ovcs

#Where next

This page is docs/hardware.md in the ovcs repository; edit it there.