Documentation
OVCS documentation
OVCS is a framework for vehicle embedded systems. A vehicle is one package the framework loads at boot. OVCS1, OVCS Mini and OBD2 are the three reference vehicles that ship with it; you can learn from them, and you need none of them to build your own.
I want to understand what OVCS isA framework for vehicle embedded systems, and three reference vehicles built on it. Start with the vocabulary the rest of the docs use.Framework & vehicles →I have a laptop and 20 minutesBoot the OVCS Mini reference vehicle on virtual CAN, attach the TUI, and watch frames flow. No hardware involved.Quickstart →I only have DockerRun the Gazebo model of the OVCS Mini reference vehicle, drive it from a topic or a gamepad, and let Nav2 plan a route.Simulation →I am building my own vehicleYour vehicle is a package built on the framework. Scaffold it, add a frame, a component and a dashboard block, then flash real Pis.Your first vehicle →
Introduction
Getting started
SetupSet 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.QuickstartBoot the OVCS Mini reference vehicle on your laptop with virtual CAN, open the dashboard, attach the TUI and feed it its first frames.SimulationRun your vehicle's VMS, ROS bridge, perception and Nav2 against a Gazebo model of it, over virtual CAN.Your first vehicleScaffold a vehicle, give it a CAN frame in and a CAN frame out, a component that links them and a dashboard block, and drive all of it on virtual CAN.Your vehicle packageThe OvcsVehicle contract, how VEHICLE selects your package, what each firmware boots, control levels, and the ovcs new scaffold.CAN frames and topologyHow your vehicle declares its CAN networks and frames in Cantastic YAML, how the bit layout compares with DBC, and how to reuse the shared component specs.Testing with CANInject single frames with cansend, replay real captures with canplayer, watch what the VMS emits, and read frame YAMLs.HardwareWhat 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.Running on hardwareBuild 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.
Components
VMS
VMSThe Vehicle Management System, the one firmware on every CAN bus of your vehicle, what it does, where it runs, its four layers and what talks to it.How the VMS worksThe VMS supervision tree, the component pattern every driver follows, the managers that pick the gear and arbitrate control levels, and how metrics and actions reach the dashboard.Add a componentThe GenServer recipe every OVCS driver follows (CAN in, CAN out, bus messages, metrics, actions) and where your component's code goes.Dashboard pagesThe page, block and row model your composers return, every block and row type the dashboards render, and how a row finds its metric or action.DriversEvery component driver the framework ships, grouped by what it drives, with the network it talks on, the options it takes and what it publishes, and the VESC motor controller in depth.
Vision
Vision unitThe vision role, a Raspberry Pi 5 or an OKdo Nano C100 that turns stereo cameras into depth and detection, exported as ROS 2 topics, and how a vehicle opts in.Stereo vision basicsHow two cameras measure distance, explained from the lens up, with the vocabulary the vision unit uses (focal length, baseline, rectification, disparity, depth, point cloud) and the numbers that decide range and precision.How a pair flowsThe processes a pair of camera frames goes through on the vision unit, from capture to the ROS 2 topics, detection and the dashboard, and how the unit keeps up with the cameras.Stereo stagesWhat each stage of the vision unit's stereo pipeline does, what it reads and fills, its settings, and what it costs.Where depth is computedHow the vision unit runs its stereo stages, compiled from Nx for a GPU or in native Rust on CPU cores, and how each path uses the GPU, the processor and memory.Vision performanceHow fast the vision unit computes depth, where the time goes, how to read the figures it reports, and the settings that trade rate against range and quality.Vision APIHow a program reads and changes the vision unit's parameters, follows its status, previews and detections, and finds what the unit exports, over HTTP and Phoenix channels.
Bus
The OVCS busThe in-process message bus every OVCS firmware runs, the messages on it, how components publish and subscribe, and how its signals reach other boards and the outside world.Bus gatewayThe library that exposes every signal on the OVCS bus over MQTT, HTTP and Phoenix Channels, and how to enable it in your vehicle, with the OVCS Mini reference vehicle as the worked example.
Bridges
BridgesWhat a bridge is, the radio control and ROS bridges the framework ships, the bridge firmware image that hosts them, and how your vehicle declares, configures and boots its bridge firmwares.Write a bridgeWhen to write a bridge rather than a VMS component, what a bridge library is made of, a complete worked bridge with its test, and how to list it in the bridge firmware and declare it in your vehicle.Radio control bridgeThe bridge that lets a MAVLink-capable RC transmitter drive your vehicle, how its channels reach the VMS, how your vehicle configures it, and how to check it on the bench.ROS bridgeThe bridge between the ovcs CAN bus and ROS 2 over native Zenoh, the components a vehicle opts into, how to configure it on the host and the target, tune its stereo cameras at runtime, and check it end to end.Perception: object detectionObject detection on a Hailo-8 fused with stereo depth into 3D detections, the topics it publishes, the CPU/GPU backends for the simulator, and model licensing.
ROS 2
ROS 2The Zenoh fabric, who publishes which topic, simulator time, the command paths, the VMS driving Gazebo, Nav2 and perception.Command pathsThe two ways a ROS node commands your vehicle, joystick positions and planner velocities, how the VMS drives the simulator, the vehicle motion it reports back, and the switches that decide who commands.ROS compute nodeThe non-Nerves Pi that runs the Zenoh router and the on-vehicle ROS nodes on balenaOS, and the vehicle network it owns, with the OVCS Mini reference vehicle as the worked example.
Reference
CLI referenceEvery ovcs subcommand, how the CLI finds a vehicle, the attach TUI and its hotkeys, and how the CAN pane decodes frames.Repository layoutThe monorepo's tree, where each component is documented, the shared libraries, the vehicle packages and the environment variables the firmwares read.OBD2 reference vehicleA vehicle package with no drivetrain that turns the VMS into an OBD2 / KWP2000 / UDS scan tool for any car, and how to extend it for brand-specific data.Toolchain and OTPWhy the host Elixir/OTP pin is coupled to each Nerves target, what the A/B firmware layout requires of every image, and how to move a system fork forward.GlossaryOne-line definitions of the terms the OVCS documentation uses, each linked to the page that explains it.TroubleshootingThe failures newcomers hit most, collected in one place, each with the check that names the cause.Community and talksConference videos, slides, the forum thread, the GitHub organisation, and how to contribute.