DocumentationReference

Glossary

One-line definitions of the terms the OVCS documentation uses, each linked to the page that explains it.

The guides use a small set of words precisely. Each entry below gives the meaning in one or two sentences and links to the section that explains it; terms are alphabetical within each layer.

#Framework and vehicles

TermDefinition
.env.exsThe gitignored per-vehicle file under vehicles/<vehicle>/ holding SSH keys, Wi-Fi networks, Phoenix secrets, ZENOH_ENDPOINT_IP and optional NervesHub credentials, shared by every firmware of the vehicle at build time. Running on hardware
ComponentTwo senses. In Repository layout it means a piece of the framework (a core, an API, a firmware shell, a library); in How the VMS works and the composers it means a vms_core driver, a GenServer managing one piece of hardware or one input (VmsCore.Components.*).
ComposerThe vehicle's module that tells a core what to run: <Vehicle>.Vms.Composer implements VmsCore.Vehicle, <Vehicle>.Infotainment.Composer implements InfotainmentCore.Vehicle, and <Vehicle>.Vision.Composer implements VisionCore.Composer. It lists the supervised children or the vision unit's components, the CAN topology and mapping, dashboard pages and controller pinouts. Your vehicle package
FrameworkEverything vehicle-agnostic in the monorepo: cores, APIs, dashboards, Nerves firmware shells, bridge libraries, the generic controller firmware, shared libraries and the ovcs CLI. It contains no vehicle-specific code. Framework and vehicles
GeometryThe optional geometry/0 callback of a vehicle module: measured wheelbase, track, wheel radius and steering limit in SI units, used by components such as OVCS.RosVelocityCommand. OvcsVehicle
InfotainmentThe optional in-car touchscreen side: infotainment_core, its Phoenix API and a Flutter head unit on a Raspberry Pi 5, on the ovcs bus only. A vehicle opts in with infotainment/0 and infotainment_target/0. Infotainment
OvcsVehicleThe top-level behaviour every vehicle module implements: name, composer pointers, CAN config app, Nerves targets, and optionally bridge firmwares and geometry. Your vehicle package
Reference vehicleOne of the three vehicles in the repository, OVCS1, OVCS Mini and OBD2: worked examples of the framework on real hardware, never requirements for yours. Framework and vehicles
RoleOne firmware of a vehicle as the CLI addresses it: vms, infotainment, vision, or bridge-<id> for each bridge_firmwares/0 entry (the bridge- prefix is required). Each role is one BEAM on the host and one board when deployed. Running on hardware
ScaffoldThe starting package ./ovcs new <name> generates from libraries/ovcs_vehicle/priv/templates/vehicle/: a working vehicle with an example controller and a vehicle GenServer. Your vehicle package
VehicleA Mix package under vehicles/<name>/ (a vehicle package) whose top-level module implements OvcsVehicle. It is metadata and composers only, with no Application; the firmware shells load it at boot. Your vehicle package
VEHICLEThe environment variable naming the vehicle's top-level module (Ovcs1, OvcsMini, Obd2, or yours), case-sensitive. The CLI sets it per BEAM on the host; a deployed release has it baked in at build time. Repository layout
VMSVehicle Management System: the only firmware on every vehicle CAN bus, so all isolation and translation between manufacturers happens there. vms_core, its API and dashboard, on a Raspberry Pi 4. VMS

#Firmware and hardware

TermDefinition
A/B firmwareThe partition layout of the OVCS Nerves systems: two firmware slots with automatic rollback, so an image that never calls Nerves.Runtime.validate_firmware/0 is reverted on the next boot. OvcsVehicle.FirmwareValidator does that call in every firmware shell. Toolchain and OTP
AdoptionHow a generic controller receives its pinout: the VMS broadcasts the configuration frame 0x700, you press the board's adoption button, and the board stores the configuration in EEPROM. Generic controllers
BridgeAn Elixir library under bridges/<name>/ implementing OvcsBridge that ferries data between the ovcs bus and a non-CAN world: RadioControlBridge for an ExpressLRS link, RosBridge for ROS 2. Bridges
Bridge firmwareThe bridges/firmware Nerves image that hosts a vehicle's extensions next to the ovcs bus, built once per entry of the vehicle's bridge_firmwares/0 map. An entry names the target, the bridges it runs, extra children such as the bus gateway, and the CAN mapping; the reference vehicles' entries are radio_control, ros and ros_vision. Bridges
BRIDGE_FIRMWARE_IDThe environment variable a bridge firmware reads at boot to pick its entry from bridge_firmwares/0, such as radio_control or ros_vision. Bridges
CAN HAT, multi-CAN SPI hubThe custom CAN interface boards: a HAT connects a Pi to one network; the hub fans the VMS Pi 4's SPI out to one MCP2517FD controller per bus, addressed as spiN.M. Hardware
Compute nodeThe one non-Nerves machine a vehicle may carry: a Raspberry Pi 5 on balenaOS running the Zenoh router, foxglove_bridge and Nav2 from compose/compute/. The OVCS Mini reference vehicle has one. ROS compute node
Controller idThe 4-bit id a generic controller is assigned during adoption, which fixes every frame id it uses (0b111AAAABBBB, so 0x7X1 to 0x7X9); up to 16 controllers per network. Generic controllers
Firmware shellA framework Nerves project (vms/firmware, infotainment/firmware, vision/firmware, bridges/firmware) that packages a core or bridges into a bootable image and contains no vehicle code: at boot it reads VEHICLE and loads the vehicle package. Architecture
Generic controllerAn Arduino R4 Minima running the one framework firmware in controllers/generic_controller/, whose pins are configured over CAN by the VMS rather than hardcoded. A vehicle declares its boards in generic_controllers/0. Generic controllers
Host keysStable per-role SSH host keys under vehicles/<vehicle>/priv/host_keys/, created by ./ovcs host-keys generate, so a reburn does not change the board's SSH identity. Running on hardware
Nerves systemThe package providing a board's kernel, root filesystem and ERTS, such as ovcs_base_can_system_rpi4; the OVCS forks add CAN kernel modules and device-tree overlays. Its OTP major must match the host's. Toolchain and OTP
Nerves targetThe Mix target (MIX_TARGET) a role builds for, read from vms_target/0, infotainment_target/0, vision_target/0 or a bridge entry's :target. It usually equals the system's name; rpi5 for ovcs_bridges_system_rpi5 and okdo_c100 for nerves_system_okdo_c100 are the exceptions. Running on hardware
NervesHubA self-hosted update server the VMS firmware can pull signed firmware from, opt-in per vehicle through NERVES_HUB_* variables in .env.exs, with one NervesHub product per vehicle. Running on hardware
OTAUpdating a deployed board's firmware over the network instead of reburning its SD card. The guides mean NervesHub pulls by "OTA updates"; ./ovcs upload pushes an image over SSH. Running on hardware
System forkAn OVCS fork of an upstream Nerves system, pinned to a tag; systems/ holds local clones for patching one. Toolchain and OTP
Vision unitThe optional vision role: VisionCore stereo depth, and optionally object detection, on a Raspberry Pi 5 or an OKdo Nano C100, published over Zenoh, with its own dashboard. A vehicle opts in with vision/0 and vision_target/0. Vision unit

#CAN

TermDefinition
CAN mappingWhich interface carries each network, written network:interface,…. A composer declares it in default_can_mapping/1 for the :host and :target arms, and a bridge entry in its default_can_mapping key. Running on hardware
CAN_NETWORK_MAPPINGSEnvironment variable that replaces a composer's mapping when set at boot, read by each firmware's config/runtime.exs. On the host, ./ovcs run passes it to the VMS and infotainment BEAMs; bridges keep their own mapping. Running on hardware
candumps/Recorded CAN logs from real vehicles, mostly the OVCS1 Polo, for replay onto virtual interfaces with canplayer. Testing with CAN
CantasticThe sideloaded CAN library the cores and bridges use: YAML frame specs, SocketCAN, emitter and receiver, ISO-TP, OBD2, a received-frame watchdog. It sets up CAN interfaces at boot on Nerves. Repository layout
Emitted and received framesThe two lists under each network in a topology YAML (emitted_frames, received_frames): what this node sends, and what its receiver forwards to subscribers. CLI reference
Frame specThe YAML describing one CAN frame: id, frequency and the signals packed in it. Shared specs live in ovcs_can; a topology imports them. Testing with CAN
HeartbeatThe VMS status frame 0x1A0, emitted every 100 ms by VmsCore.Status; generic controllers cut every output when it goes missing, after a 30 s grace period at power-up. Generic controllers
InterfaceThe Linux device a network runs on: vcan0 (virtual), can0 (physical adapter) or spi0.0 (a controller behind an SPI CAN board). Running on hardware
NetworkA named CAN bus declared under can_networks: in a topology YAML, with its bitrate and frames, such as ovcs, misc or leaf_drive. Components refer to networks by name, never by interface. CAN frames and topology
ovcs busThe framework's internal network, declared by every vehicle: VMS heartbeat, controller adoption, radio and ROS commands, infotainment traffic. Architecture
ovcs_canThe in-tree library of shared per-component frame YAMLs under priv/can/components/, grouped by manufacturer, with no runtime logic. Topologies import from it with import!:@ovcs_can:…. Repository layout
SignalA named value inside a frame: a bit range (value_start, value_length) with a kind and optionally a scale and unit. Testing with CAN
TopologyA vehicle's YAML under priv/can/ saying which frames run on which network for one side: vms.yml, infotainment.yml, bridges/<id>.yml. CAN frames and topology
vcanA Linux virtual CAN interface (vcan0, vcan1, …). ./ovcs can setup <vehicle> creates the ones the vehicle's host mapping names, so everything runs on a laptop without CAN hardware. Testing with CAN

#Runtime

TermDefinition
ActionA command a component exposes through trigger_action/2, so a dashboard button (via POST /api/actions) or IEx can call into it. How the VMS works
AdapterOne of the bus gateway's ways out, switched on in OvcsBusGateway.Config: MQTT, which publishes every signal retained on a topic of its own, or HTTP, the JSON:API resources, live channels and dashboard. Not to be confused with a USB CAN adapter. Bus gateway
ArmThe :host or :target argument that per-environment callbacks such as default_can_mapping/1 and radio_control_bridge_config/1 receive. Your vehicle package
Bus gatewayOvcsBusGateway, the library that carries every signal published on OvcsBus out of the mesh through its adapters, with a dashboard; a vehicle runs it in a bridge firmware. Bus gateway
CommanderTwo senses. A component that requests throttle, steering or direction (the OVCS.RadioControl.* inputs, OVCS.RosActuatorCommand.*, OVCS.RosVelocityCommand); and, under :ros, the requested ROS commander, :teleop or :autonomous. How the VMS works
Control levelWho has authority over the vehicle: :manual, :radio or :ros, arbitrated by Managers.ControlLevel, which refuses unsafe transitions and makes :ros reachable only from :radio. How the VMS works
Dashboard pages and blocksThe layout a composer declares in dashboard_configuration/0 (or infotainment_configuration/0) and the API serves: pages of metric tables, charts and action buttons. Dashboard pages
FreshnessThe check that a ROS command is new: the bridge increments a sequence per ROS sample, and the VMS zeroes the command when it stops changing, since the emitter retransmits stale frames on a timer. Command paths
Host versus targetHost is your machine, where ./ovcs run spawns one BEAM per role with MIX_TARGET=host on vcan; target is a deployed Nerves board on real CAN. Architecture
Input curveOVCS.InputCurve, a component that applies a hand's dead zone and expo to a throttle source; a source map names the curve rather than the raw input. How the VMS works
ManagerFramework logic spanning several components: Managers.ControlLevel and Managers.Gear. How the VMS works
MeshThe Erlang-distribution cluster every BEAM of a vehicle joins through OvcsBus.Cluster, over loopback on the host and the vehicle LAN when deployed. No broker between the nodes. The mesh
MetricA value a component broadcasts on OvcsBus; VmsCore.Metrics aggregates them for the dashboard and API. How the VMS works
Node nameA BEAM's distribution name: <vehicle>-<role>@<host> on the host, nerves@<vehicle>-<role>.local deployed. Your vehicle package
OvcsBusThe in-tree pub/sub library: OvcsBus.broadcast/2 sends an %OvcsBus.Message{} (name, value, source, unit) to subscribers on the local node. The OVCS bus
process_nameThe option on components that can run more than once in a vehicle (OVCS.InputCurve, OVCS.GenericController, OVCS.RotationFusion, Vesc.MotorController): the name the process registers under and the source its messages carry. VESC
Ready to driveThe vehicle-level condition, reported in the VMS heartbeat, that entering :radio or :ros requires; losing it forces :manual. Architecture
SourceThe publishing module an OvcsBus.Message carries. A component is told in its composer config which module publishes what it needs (speed_source: …) and matches on it, so components never import each other. How the VMS works
Source mapA composer's requested_*_sources map, keyed by control level and, under :ros, by commander; a missing key means nothing commands that actuator. How the VMS works

#Tooling

TermDefinition
Attach TUI./ovcs attach <vehicle>: a split-pane terminal UI (logs, bus, CAN, IEx) on a running vehicle, deployed boards first, local BEAMs otherwise. CLI reference
can-utilsThe Linux tools cansend, candump, canplayer and cangen for injecting, watching and replaying frames. Testing with CAN
Dev add-onA helper process a firmware declares in dev_addons/0 and ./ovcs run starts beside the BEAMs: the VMS dashboard's Vite server on http://localhost:5173, and the vision dashboard's on http://localhost:5174. --no-addons skips them. CLI reference
In-tree libraryA library under libraries/ that is a framework-internal contract and lives in the monorepo: ovcs_vehicle, ovcs_can, ovcs_bus, ovcs_bridge, ovcs_drivers. Repository layout
ovcs CLIThe framework's Rust command-line tool, ./ovcs, built by mise run cli: scaffolds, runs, builds, burns, uploads and attaches to any vehicle. CLI reference
Sideloaded libraryA library reusable outside OVCS with its own repository (Cantastic, express_lrs, msp_osd, ovcs_control), gitignored here and cloned into libraries/ by mise run libraries, which mise install runs. Repository layout

#ROS 2

TermDefinition
Actuator commandThe 0x2B0 frame RosBridge.Consumers.Joy writes from /joy/<profile>: normalised steering and throttle positions, read by OVCS.RosActuatorCommand.*. Command paths
Base stationThe operator's workstation side, compose/local/: ROS tooling, the gamepad node and Foxglove Studio, joining the vehicle's router as clients. ROS 2
OVCS_SIMEnvironment variable (1 or true) that switches the ROS bridge in the OVCS Mini reference vehicle's ros and ros_vision bridge firmwares to simulator wiring: Zenoh camera input, no odometry publisher. Simulation
ROS bridgeRosBridge, the bridge that speaks the rmw_zenoh wire format natively over Zenoh, turning ROS topics into ovcs frames and back; a vehicle configures it in ros_bridge_config/1 or /2. ROS bridge
Stand-inA copy of a vehicle service (zenohd, foxglove_bridge, nav2) in compose/local/base.yml behind a profile, for when no vehicle is on the LAN; it must not run while one is. ROS 2
Velocity commandThe 0x2B1 frame RosBridge.Consumers.Velocity writes from a planner Twist: linear and angular velocity, turned into steering and throttle by OVCS.RosVelocityCommand against the vehicle's geometry. Command paths
ZenohThe transport everything ROS-shaped uses instead of DDS; every participant is a client of one router, zenohd, which runs on the vehicle's compute node. ROS 2
ZENOH_ENDPOINT_IPThe router address the ROS bridge and the vision unit peer with, set in .env.exs and baked into the image at build time; without it both fall back to 127.0.0.1. ROS compute node

#Next steps

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