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.
| Tool | Version | Purpose | Installed by |
|---|---|---|---|
| mise | latest | Version manager for every runtime below | you, once |
| Erlang/OTP | 29.1.2 | Runtime for Elixir | mise |
| Elixir | 1.20.4-otp-29 | The primary language | mise |
| Rust | 1.90 | Compiles the ovcs CLI | mise |
| Node.js | 24 | VMS debug dashboard (Vue) | mise |
| Ruby | 3.3 | Utility scripts under scripts/ | mise |
| Python | 3.12 | PlatformIO | mise |
| Flutter | 3.32.8 | Infotainment dashboard | mise |
| PlatformIO | latest | Generic controller firmware (Arduino) | mise (pipx + uv) |
| balena CLI | 25.x | Deploys the ROS compute node's containers | mise |
| Docker + Compose v2 | latest | Simulator, ROS base station, compute node images | system package |
| can-utils | latest | cansend, candump, canplayer | system package |
| fwup | 1.15+ | Nerves firmware image packager | .deb from GitHub releases |
| libsocketcan-dev | latest | Cantastic's native CAN bindings (firmware builds only) | system package |
| libmnl-dev | latest | Host-compiles nerves_uevent | system package |
| nerves_bootstrap | latest | Nerves Mix archive | mise install hook |
#Set up your machine
Every step is the same on any system except step 2, the system packages.
#1. Install mise
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:
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:
sudo apt install -y git can-utils libsocketcan-dev libmnl-dev kmod
gitclones the sideloadedcantastic,express_lrs,msp_osdandovcs_controllibraries (step 4).kmodprovideslsmodandmodprobe, which./ovcs can setupand./ovcs runuse to loadvcan. Minimal container images lack it.libsocketcan-devis only needed to build firmware for physical CAN targets.libmnl-devhost-compilesnerves_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:
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:
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:
# 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:
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:
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:
distrobox-export --bin /usr/local/bin/fwup --export-path ~/.local/bin
#macOS (Multipass VM)
You need a full Linux VM. Multipass is the simplest:
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
git clone https://github.com/open-vehicle-control-system/ovcs.git
cd ovcs
#4. Install the runtimes
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 thenerves_bootstraparchive.mise run libraries: clonescantastic,express_lrs,msp_osdandovcs_controlintolibraries/. 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
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:
./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:
./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.