DocumentationGetting started

Setup

Set up a Linux workstation (or a VM on macOS) with mise, the system packages and the ovcs CLI, then check it with ./ovcs doctor and virtual CAN.

OVCS runs on your workstation without any hardware: virtual CAN interfaces stand in for the buses, and every firmware boots as a plain BEAM. This guide takes a fresh machine to a green ./ovcs doctor and working virtual CAN interfaces. From there, the Quickstart boots a whole vehicle in one command.

#What you install

Most of the toolchain is pinned in mise.toml and installed by mise in one go. A few system packages come from your distribution.

ToolVersionPurposeInstalled by
miselatestVersion manager for every runtime belowyou, once
Erlang/OTP29.1.2Runtime for Elixirmise
Elixir1.20.4-otp-29The primary languagemise
Rust1.90Compiles the ovcs CLImise
Node.js24VMS debug dashboard (Vue)mise
Ruby3.3Utility scripts under scripts/mise
Python3.12PlatformIOmise
Flutter3.32.8Infotainment dashboardmise
PlatformIOlatestGeneric controller firmware (Arduino)mise (pipx + uv)
balena CLI25.xDeploys the ROS compute node's containersmise
Docker + Compose v2latestSimulator, ROS base station, compute node imagessystem package
can-utilslatestcansend, candump, canplayersystem package
fwup1.15+Nerves firmware image packager.deb from GitHub releases
libsocketcan-devlatestCantastic's native CAN bindings (firmware builds only)system package
libmnl-devlatestHost-compiles nerves_ueventsystem package
nerves_bootstraplatestNerves Mix archivemise install hook

#Set up your machine

Every step is the same on any system except step 2, the system packages.

#1. Install mise

sh
curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc   # or bash / fish
exec $SHELL

Other shells and package-manager installs are in the mise installation docs.

#2. Install system packages

#Debian / Ubuntu

mise builds Erlang and Ruby from source, so the C toolchain and dev headers have to be present:

sh
sudo apt install -y build-essential autoconf m4 \
  libncurses-dev libssl-dev libffi-dev libyaml-dev zlib1g-dev \
  libwxgtk3.2-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev \
  libssh-dev unixodbc-dev xsltproc fop libxml2-utils pkg-config

Then the tools OVCS calls:

sh
sudo apt install -y git can-utils libsocketcan-dev libmnl-dev kmod
  • git clones the sideloaded cantastic, express_lrs, msp_osd and ovcs_control libraries (step 4).
  • kmod provides lsmod and modprobe, which ./ovcs can setup and ./ovcs run use to load vcan. Minimal container images lack it.
  • libsocketcan-dev is only needed to build firmware for physical CAN targets.
  • libmnl-dev host-compiles nerves_uevent, a transitive firmware dependency.

Docker Engine with the Compose v2 plugin is needed only for the simulator and the ROS containers; install it from the Docker Engine docs.

fwup is not in the Debian/Ubuntu repositories. Install the .deb from its releases:

sh
curl -L -o /tmp/fwup.deb "https://github.com/fwup-home/fwup/releases/download/v1.15.0/fwup_1.15.0_$(dpkg --print-architecture).deb"
sudo dpkg -i /tmp/fwup.deb

To run the Flutter infotainment dashboard on your desktop (mise run infotainment-dashboard), add the Linux desktop toolchain and check that flutter doctor ticks the Linux toolchain line:

sh
sudo apt install -y clang cmake ninja-build libgtk-3-dev

#Bluefin / atomic Fedora

On an immutable Fedora (Bluefin, Silverblue, Kinoite, Bazzite, uBlue) /usr is read-only, so you develop inside an Ubuntu distrobox: a rootless container that shares your home directory, display and devices. The Debian / Ubuntu commands above then apply verbatim inside it.

CAN kernel and network setup must happen on the host. A rootless container can't modprobe (it needs real root) or create interfaces (it needs CAP_NET_ADMIN over the host network namespace), and --privileged doesn't change that. The symptom is ./ovcs can setup running its sudo block, then failing with modprobe: Operation not permitted or RTNETLINK answers: Operation not permitted. Create the interfaces once on the host, so the CLI finds them already up:

sh
# Load the vcan module now and on every boot.
sudo modprobe vcan
echo vcan | sudo tee /etc/modules-load.d/vcan.conf

# Create vcan0..vcan4 now and on every boot via a systemd one-shot.
sudo tee /etc/systemd/system/ovcs-vcan.service >/dev/null <<'EOF'
[Unit]
Description=Create virtual CAN interfaces for OVCS
After=systemd-modules-load.service
Requires=systemd-modules-load.service

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/bin/sh -c 'for i in 0 1 2 3 4; do ip link add dev vcan$$i type vcan 2>/dev/null || true; ip link set up vcan$$i; done'

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now ovcs-vcan.service

ip -br link show | grep vcan lists vcan0 to vcan4, each with UP in its flags (<NOARP,UP,LOWER_UP>); the state column reads UNKNOWN, which is normal for vcan. Five covers the OVCS1 reference vehicle, the largest; widen the loop if your vehicle declares more networks. Then create and enter the container:

sh
distrobox create --name ovcs --image ubuntu:24.04
distrobox enter ovcs

From here on, every command in this guide runs inside the container. The clone lives in your shared home, so nothing moves, and sudo is passwordless.

The host's mise (usually a Homebrew binary) isn't mounted into the container: re-run step 1 inside it, then wire mise into the container's bash:

sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
exec bash

Run the Debian / Ubuntu apt commands and the fwup install inside the container. To burn SD cards from inside it, you may need --additional-flags "--device /dev/bus/usb" at create time. To call a container binary from the host shell, export it once:

sh
distrobox-export --bin /usr/local/bin/fwup --export-path ~/.local/bin

#macOS (Multipass VM)

You need a full Linux VM. Multipass is the simplest:

sh
multipass launch --name primary --disk 40G --cpus 2 --memory 8G
multipass shell
sudo passwd ubuntu

Size the disk for Nerves builds up front: it can't grow after creation. Clone the repository inside the VM to avoid permission and symlink problems in Nerves builds; share it back to macOS over NFS if you want your usual editor. Then follow the Debian / Ubuntu instructions inside the VM.

#3. Clone the repository

sh
git clone https://github.com/open-vehicle-control-system/ovcs.git
cd ovcs

#4. Install the runtimes

sh
mise trust
mise install

mise install installs every pinned runtime, then runs a hook that does two more things:

  • mise run bootstrap: installs hex, rebar and the nerves_bootstrap archive.
  • mise run libraries: clones cantastic, express_lrs, msp_osd and ovcs_control into libraries/. Existing clones are left alone, so your local edits there survive.

From now on, entering the directory activates the pinned versions. Reinstalling Elixir later fires the same hook.

#5. Build the CLI and check everything

sh
mise run cli      # cargo build --release, stripped and copied to cli/ovcs
./ovcs doctor

./ovcs at the repository root is a symlink to cli/ovcs, which is gitignored: every contributor builds it. doctor checks the toolchain binaries (required: mise, Elixir, Mix, Node, Python, fwup; optional, a warning when missing: Ruby, Flutter, can-utils, balena, Docker, PlatformIO), the nerves_bootstrap archive, the libsocketcan headers (warning), each vehicle's Nerves targets under vehicles/, and their SSH host keys. Missing host keys are a warning: you only need them before burning firmware.

#6. Optional: firmware builds

Skip this if you only develop on the host. Building images for the Raspberry Pis additionally needs the host packages from the Nerves installation guide (squashfs-tools, ssh-askpass, …). You don't clone the OVCS Nerves systems: each firmware project pins its system to a release tag and Mix fetches it, prebuilt, on the first build. Clone a system into systems/ only to modify it (Toolchain and OTP).

Before your first burn, generate stable SSH host keys for your vehicle, so reflashes don't trip OpenSSH's "REMOTE HOST IDENTIFICATION HAS CHANGED" warning:

sh
./ovcs host-keys generate <vehicle>   # once per vehicle, e.g. ovcs1

The build, burn and upload flow is in Running on hardware.

#Verify the setup

Provision the virtual CAN interfaces for one vehicle and check them. The commands take any vehicle under vehicles/; the OVCS Mini reference vehicle, which the Quickstart boots, needs two. Run them with ovcs1, obd2 or your own vehicle's name and they work the same:

sh
./ovcs can setup ovcs_mini
./ovcs can status ovcs_mini

can setup reads the vehicle's default_can_mapping(:host) and creates only the interfaces that are missing: it lists what it will run as root, then prompts for sudo. A second run prints All virtual CAN interfaces for OvcsMini are already up — nothing to do. can status prints one line per interface and ends with All interfaces up. An interface marked down or not created means can setup didn't finish: on an atomic Fedora, create them on the host (above).

A green ./ovcs doctor and All interfaces up. mean your toolchain works. Booting a vehicle on it is the Quickstart.

#Next steps

  • Quickstart: boot the OVCS Mini reference vehicle, open the dashboard, attach the TUI, send your first frames.
  • Your first vehicle: scaffold your own vehicle and make it do something.
  • Repository layout: the monorepo, its libraries, and where each component is documented.
  • Hardware: the Raspberry Pis, the CAN hub and the Arduino controllers.

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