DocumentationGetting started
Running on hardware
Build and burn your vehicle's Nerves firmware, update running boards over SSH or through NervesHub, keep SSH host keys stable across burns, and attach to the running boards.
Everything that runs on your laptop with ./ovcs run also runs on the vehicle: the same firmware projects, the same vehicle package, the same Erlang cluster. The difference is that each BEAM becomes a Nerves image on its own board. This guide covers building those images, getting them onto boards, updating them, and watching them run.
The firmware projects, the Nerves systems and the ovcs CLI are the framework. Everything that varies per vehicle (the Nerves target of each role, .env.exs with its keys and secrets, the SSH host keys, the CAN mapping) belongs to your vehicle package under vehicles/<vehicle>/. The commands below use the ovcs1 and ovcs_mini reference vehicles; substitute your own package name and they work unchanged.
#Boards per role
| Role | Board | Nerves system |
|---|---|---|
| VMS | Raspberry Pi 4 | ovcs_base_can_system_rpi4 |
| Infotainment | Raspberry Pi 5 | ovcs_base_can_system_rpi5 |
bridge-radio_control (reference vehicles) | Raspberry Pi 3A | ovcs_base_can_system_rpi3a |
bridge-ros (reference vehicles) | Raspberry Pi 4 | ovcs_base_can_system_rpi4 |
bridge-ros_vision (OVCS Mini) | Raspberry Pi 5 + Hailo-8 | ovcs_bridges_system_rpi5 (Mix target rpi5) |
vision | Raspberry Pi 5, optionally with a Hailo-8 | ovcs_bridges_system_rpi5 (Mix target rpi5) |
vision | OKdo Nano C100 | nerves_system_okdo_c100 (Mix target okdo_c100) |
| Generic controller | Arduino R4 Minima | none (PlatformIO) |
These are the reference vehicles' choices, except vision: none of them runs it, and its two rows are the boards vision/firmware builds for. The target of each role is a per-vehicle decision, read from your top-level module: vms_target/0, infotainment_target/0, vision_target/0, and the :target key of each bridge_firmwares/0 entry. The :target value is the Mix target, which usually but not always equals the system's name. To deploy on other hardware, change those values in vehicles/<vehicle>/lib/<vehicle>.ex and add the matching system dependency to the firmware project's mix.exs (see the Nerves custom-systems guide).
The OVCS systems add the CAN kernel modules and device-tree overlays the SPI-CAN hardware needs. The host OTP pinned in mise.toml must match the OTP they ship: Toolchain and OTP explains why.
The generic controller firmware is a PlatformIO project. It doesn't use the R4's built-in CAN peripheral, so any Arduino-compatible board with EEPROM and an external CAN transceiver works. Flashing and adoption are in Generic controllers.
#The ovcs CLI
Every build, burn and upload goes through ./ovcs (built by mise run cli, see Getting started). The CLI reference lists every command.
./ovcs <command> <vehicle> <role> [options]
<vehicle>is the snake_case directory name of a vehicle undervehicles/.<role>isvms,infotainment,vision, orbridge-<id>for any id in the vehicle'sbridge_firmwares/0(bridge-radio_control,bridge-ros,bridge-ros_visionin the reference vehicles).visionexists when the vehicle implementsvision/0(Vision unit). Thebridge-prefix is required: a bare id is rejected, and the error lists the valid roles.- The two positional arguments are order-independent. A missing one opens an interactive picker; on a non-tty stdin the command exits with status 2.
#Build
-
Configure the vehicle's secrets. Copy
vehicles/<vehicle>/.env.exs.exampletovehicles/<vehicle>/.env.exsand fill inAUTHORIZED_SSH_KEYS(your SSH public keys),WIFI_NETWORKS, the PhoenixSECRET_KEY_BASEandSIGNING_SALT, and, for a vehicle with a ROS bridge or a vision unit,ZENOH_ENDPOINT_IP. The file is gitignored and shared by every firmware of the vehicle. -
Generate stable SSH host keys, once per vehicle (below):
./ovcs host-keys generate ovcs1 -
Build the image:
./ovcs build ovcs1 vms # VMS ./ovcs build ovcs1 infotainment # infotainment ./ovcs build ovcs1 bridge-radio_control # a bridge the vehicle declares ./ovcs build --all ovcs1 # every role, firmware projects in parallel ./ovcs build my_car vms # the same for your own vehicle
A VMS build also builds the Vue dashboard and bundles it into the image. The image lands under the firmware project's _build/<target>_dev/nerves/images/, for example vms/firmware/_build/ovcs_base_can_system_rpi4_dev/nerves/images/vms_firmware.fw.
#Stable SSH host keys across burns
A fresh SD-card burn regenerates the device's SSH host key, so every reflash trips OpenSSH's "REMOTE HOST IDENTIFICATION HAS CHANGED" warning. Persistent keys per role avoid that:
./ovcs host-keys generate ovcs1
This creates an RSA and an ed25519 key pair per role under vehicles/<vehicle>/priv/host_keys/: vms/, infotainment/, vision/, and bridges/<id>/ for each bridge. The files are gitignored. The firmware ships them in the vehicle's priv and points :nerves_ssh, :system_dir at them at boot. Re-run with --force to rotate; ./ovcs doctor warns about any vehicle missing keys.
To share one identity across a team:
./ovcs host-keys verify ovcs1 # exit 1 if any role lacks a full key set
./ovcs host-keys export ovcs1 -o ovcs1-host-keys.tar.gz # default: ./ovcs1-host-keys.tar.gz
./ovcs host-keys import ovcs1 --from ovcs1-host-keys.tar.gz
#Burn to an SD card
With the card inserted:
./ovcs burn ovcs1 vms
./ovcs burn --build ovcs1 vms # rebuild, then burn
#Upload over the network
Push an update to a running device over SSH:
./ovcs upload ovcs1 vms # to ovcs1-vms.local
./ovcs upload ovcs1 infotainment --host 192.168.1.100 # to a specific address
./ovcs upload ovcs1 vms --file path/to/custom.fw # a custom image
./ovcs upload --build ovcs1 vms # rebuild, then upload
The default host is <vehicle>-<role>.local, with every underscore turned into a dash: ovcs-mini-vms.local, ovcs1-bridge-radio-control.local.
#OTA updates via NervesHub
The VMS and vision firmwares ship NervesHubLink, so deployed vehicles can pull signed updates from a self-hosted NervesHub instance instead of being flashed over SSH. It is opt-in per vehicle: set three variables in vehicles/<vehicle>/.env.exs before building (.env.exs.example has them commented out).
NERVES_HUB_HOST: the instance's device endpoint, a bare hostname (wsson port 443) or a fullwss://host:portURL.NERVES_HUB_PRODUCT_KEYandNERVES_HUB_PRODUCT_SECRET: the shared-secret pair from the product's settings on the instance.
Without NERVES_HUB_HOST, the firmware never contacts NervesHub.
One NervesHub product per vehicle. The build stamps a product name into the image's meta-product, derived from the VEHICLE module name and the firmware: Ovcs1 - VMS, Ovcs Mini - VMS, <Vehicle> - Vision. NervesHub only accepts firmware whose metadata matches the product it's uploaded to, so create one product per vehicle with that name and put its shared-secret pair in that vehicle's .env.exs. A device then only ever sees its own vehicle's firmware. Both firmwares of a vehicle read that one pair, so it serves the VMS or the vision unit, not both.
Publish with the nh CLI:
./ovcs build ovcs1 vms
nh firmware publish \
vms/firmware/_build/ovcs_base_can_system_rpi4_dev/nerves/images/vms_firmware.fw \
--product "Ovcs1 - VMS" --key <signing-key> --deploy <deployment>
Firmware must be signed: nh key create <name> creates a signing key pair and registers the public half on the instance, and nh firmware publish --key <name> signs locally, so the private key never leaves your machine. Devices authenticate with the product's shared secret, self-register on first connect (identified by serial number), and fetch the verification keys from the instance, so nothing is baked into the image.
The link also enables health reporting (CPU, memory, disk) and a remote IEx console in the NervesHub UI, open to anyone with access to the product. nerves_hub_link starts before the main application, so a vehicle whose main application crashes at boot stays reachable for an OTA fix.
#Watching a running vehicle
./ovcs attach <vehicle> is the same split-pane TUI whether the vehicle runs on your laptop (./ovcs run) or on its boards. It tries the deployed boards first, by probing <vehicle>-<role>.local on port 22 for each role, and falls back to local BEAMs registered in epmd. Deployed, it streams each board's logs via RingLogger.attach() and opens an IEx channel per board. The panes and hotkeys are in the CLI reference.
./ovcs attach ovcs1
For a single board, connect opens a plain IEx shell. Nerves boards use IEx as their SSH login shell:
./ovcs connect ovcs1 vms # IEx on the VMS Pi
./ovcs connect ovcs1 vms --host 192.168.10.42 # bypass mDNS with a known address
Both need:
- your SSH public key in
AUTHORIZED_SSH_KEYSinvehicles/<vehicle>/.env.exswhen the firmware was built; - your private key loaded in
ssh-agent(ssh-add -lto check); - the boards resolving on the LAN by mDNS. Check with
ping ovcs1-vms.localfirst.
On a vehicle with a compute node, the boards' wired addresses sit behind it. An SSH ProxyJump block in ~/.ssh/config makes them reachable from the site Wi-Fi, since upload and connect --host run ssh underneath:
Host 10.42.0.*
ProxyJump root@COMPUTE_NODE_SITE_ADDRESS:22222
StrictHostKeyChecking accept-new
Reaching the vehicle network explains that layout. Arduino controllers have no SSH or IEx and are skipped.
#CAN interfaces
Each side's composer declares which interface carries each CAN network, per environment, in default_can_mapping/1: :host for ./ovcs run (virtual vcan interfaces), :target for the deployed image (on the VMS, spi interfaces behind the CAN hub; the infotainment uses can0). A bridge declares its own in the default_can_mapping of its bridge_firmwares/0 entry.
| Interface prefix | Type | Example |
|---|---|---|
vcan | Virtual CAN, for development | vcan0 |
can | Physical CAN interface | can0 |
spi | CAN via SPI, as on the VMS with the multi-CAN hub | spi0.0 |
The network names are declared in the vehicle's YAML. The framework's own components expect ovcs; every driver for a part on another network takes its name as a network: option. The reference vehicles declare:
| Network | Declared by | Carries |
|---|---|---|
ovcs | every vehicle | Framework traffic: VMS status, controllers, radio control, ROS commands |
leaf_drive | OVCS1 | Nissan Leaf drivetrain |
polo_drive | OVCS1 | VW Polo original systems |
orion_bms | OVCS1 | Orion BMS2 and charger |
misc | OVCS1, OVCS Mini | OVCS1: iBooster and steering-angle sensor; Mini: the VESC |
#Overriding the mapping
CAN_NETWORK_MAPPINGS replaces the composer's mapping when it is set in the environment of a BEAM at boot. It takes network:interface pairs:
CAN_NETWORK_MAPPINGS=network1:interface1,network2:interface2,...
It is read by each firmware's config/runtime.exs at boot. A deployed image boots without it in its environment and uses default_can_mapping(:target); to change a deployed mapping, change the composer.
On the host, every BEAM ./ovcs run spawns inherits it except the bridges, which always get their own mapping. Cantastic refuses a mapping that names a network its YAML doesn't declare (CAN Network: '…' is missing from the Yaml configuration), so the variable suits a vehicle whose sides share their networks. The Mini's VMS, for instance, on a physical can0 for the ovcs bus:
CAN_NETWORK_MAPPINGS=ovcs:can0,misc:vcan1 ./ovcs run ovcs_mini
#Bringing interfaces up
On a Nerves board, Cantastic sets the CAN interfaces up at boot (setup_can_interfaces: true); there is no manual step. On the host, ./ovcs can setup <vehicle> creates the vcan interfaces the vehicle's default_can_mapping(:host) names. For a Linux machine with physical CAN adapters, scripts/setup_can.sh brings can0, can1 and can2 up at 500 kbps; edit it for other bitrates or interfaces.
#Next steps
- Generic controllers: flash and adopt the Arduino boards on the
ovcsbus. - CLI reference: every subcommand, and how the attach TUI decodes frames.
- Toolchain and OTP: why host and target OTP must agree, and what A/B firmware requires.
- Troubleshooting: the failures newcomers hit most.
This page is docs/running_hardware.md in the ovcs repository; edit it there.