ROS 2

A map, not a manual: what runs when OVCS talks to ROS 2, who owns time, which command path is real. Simulation tells you how to run the simulator; read it first.

#The fabric: one Zenoh router, everything a client

Everything ROS-shaped speaks Zenoh, not DDS. ROS 2 nodes use rmw_zenoh_cpp; the Elixir bridge speaks the rmw_zenoh wire format natively through zenohex and links nothing from ROS. Every participant is a client of one router (zenohd): no multicast discovery to configure, and a simulated vehicle appears on the same fabric as a real one.

The vehicle is the router, so the fabric survives the laptop leaving. With no vehicle on the LAN, compose/local/base.yml carries a copy of zenohd behind the standalone profile, for a simulator session with no vehicle on the LAN.

Three consequences of the wire format:

• A topic is a key expression. rmw_zenoh maps /cmd_vel to 0/cmd_vel/geometry_msgs::msg::dds_::Twist_/RIHS01_<hash>. The bridge subscribes with a /** wildcard after the topic and matches by prefix, so it can subscribe by topic without knowing the type hash. It is also why subscribing with the wrong message module fails silently (below).
• Payloads are CDR with a four-byte encapsulation header (00 01 00 00) and a 33-byte attachment carrying sequence number, source timestamp and publisher GID. rmw_zenoh subscribers drop samples without a well-formed attachment.
• Discovery is a liveliness token, not data. A publisher is invisible to ros2 topic list and Foxglove until it declares one on @ros2_lv/..., even while its samples flow.

bridges/ros_bridge/README.md has the format in full, including how to add a message type.

#Who runs what

Everything containerised lives under compose/, split by one question: is it pushed to the vehicle, or does it never leave a workstation?

compose/compute/ is pushed to balena as one unit, with your vehicle's Nav2 parameters staged into it by ./ovcs compute push; compose/local/ never is. The vehicle's images are built only from compose/compute/images/, and the local stacks build the same Dockerfiles, so a workstation runs what the car runs. A stand-in must not run while a vehicle is on the LAN: two routers are two fabrics. The profile table is in compose/README.md; the compute node itself is ROS compute node.

#What the simulator starts

The launch order, the bridged topics and the details that read like bugs until you know them (server-only Gazebo, -r, GZ_IP, the step rate) are in Simulation.

#Topics: who publishes what

The boundary between Gazebo's transport and ROS is exactly the list in gazebo.launch.py.

Two transform buffers. /tf is time-indexed: tf2 stores each sample against its stamp and interpolates. /tf_static is timeless, and carries the URDF's fixed joints, the sensor mounts among them; a point cloud stamped after the newest /tf sample could not be transformed, and Nav2 would drop it. robot_state_publisher publishes them: the simulator's launch runs it here, and the Nav2 image runs it on the vehicle, so the nav2 service in this stack starts with robot_state_publisher:=false. The bridges stamp their messages with the URDF's frame names (lidar_link, stereo_left_optical, ...) in both. The wheels' joints move, so their transforms are on /tf, from /joint_states: Gazebo's here, the ROS bridge's :ackermann_joint_states on the vehicle, from the VMS's commanded steering and the wheels' distance.

Meshes. Foxglove fetches a model's meshes through foxglove_bridge only when they are package:// URIs, so the framework expands your model with its meshes in the ovcs_description package, through a mesh_uri xacro argument (package://ovcs_description/meshes). The shared ROS image registers that package at /opt/ovcs/description, where ovcs compute stage bakes your vehicle's description/ on the vehicle and the local foxglove_bridge mounts it; Gazebo finds it on GZ_SIM_RESOURCE_PATH. Enable /robot_description in a 3D panel to draw the model, with the panel's mesh up axis set to Z-up (scene.meshUpAxis: z_up), as ROS meshes are: Foxglove assumes Y-up and turns them 90°.

#Time

The part most likely to bite, because every failure it causes looks like something else.

#Gazebo owns the clock

use_sim_time: true means "stamp with /clock, not the wall". Gazebo starts its clock at zero and advances it with physics, so a wall-clock stamp (1.79e9 s) sits decades away from everything else. Any consumer comparing stamps across topics drops the message, usually with a tf2 extrapolation error that reads as a transform problem.

ROS nodes get this from the parameter. The Elixir bridge is not a ROS node, and its drivers stamp frames with Erlang monotonic time, so something has to convert.

#The bridge tracks an offset, not the clock

Each /clock sample gives a simulator time and, read alongside it, a local monotonic time; RosBridge.Clock stores the difference in :atomics for lock-free reads. RosBridge.Timing.stamp_from_monotonic/1 projects any monotonic capture time through it:

/clock sample t_sim ─► RosBridge.Clock: offset = t_sim − t_mono ─► :atomics
driver frame (capture_ns, Erlang monotonic) ─► Timing: capture_ns + offset ─► builtin_interfaces/Time

Drivers never see simulator time: camera frames carry an Erlang-monotonic capture_ns, lidar and rangefinder samples carry system time, and Timing is the one place either is converted. RosBridge.Camera.Zenoh converts the other way, through Timing.monotonic_from_ros_time/1: a simulated frame's capture_ns is Gazebo's render stamp, so both sides of a stereo pair carry the same time and pair exactly. Stamped on arrival instead, they arrive tens of milliseconds apart, enough to pair a frame with its neighbour's, which reads as phantom depth once the car moves. Without a /clock the offset is nil and Timing stamps wall clock, so the vehicle path is untouched.

#Two monotonic clocks, not one

Erlang's monotonic time is not the kernel's CLOCK_MONOTONIC: the VM picks its own zero, about 5.8e17 ns away. libcamera's SensorTimestamp is kernel-monotonic. Project one clock's timestamp with the other's offset and it lands decades off, and builtin_interfaces/Time.sec is an int32, so it wraps negative. Timing.monotonic_from_kernel/1 converts once, at the driver boundary.

#Why Clock.init/1 blocks

RosBridge.Clock waits for the first /clock sample before returning, holding up the rest of the supervision tree. tf2 prunes its buffer relative to its newest entry: one wall-clock /tf_static message published before the offset is known discards every simulator-time entry that follows and never ages out. Every point cloud afterwards is rejected with

the timestamp on the message is earlier than all the data in the transform cache

and the costmaps ignore stereo for the whole run. Measured, the static-transform publisher wins that race by zero milliseconds. Blocking in init/1, with :simulator_clock listed before the transforms and the camera, makes the race unwinnable.

#Giving up is permanent

If no /clock arrives within 60 s (:acquire_timeout_ms), the bridge unsubscribes and stays on wall clock for the run. Switching later would be worse: wall-clock stamps would already be in tf2's buffer. The deadline is generous because docker compose up -d returns long before Gazebo has loaded a world and spawned the robot.

#Commands

Joystick positions and planner velocities reach the VMS on two CAN frames, 0x2B0 and 0x2B1; Command paths follows both, the loop the VMS closes with the simulator, and the switches that decide who commands.

#Nav2, as configured here

Nav2 1.5.1: a lifecycle manager and four servers (controller_server, planner_server, behavior_server, bt_navigator) plus velocity_smoother. Not nav2_bringup, which is absent from the Lyrical archive and would pull in map_server and AMCL.

One configuration, three deployments. The parameter file and behaviour trees are the vehicle's, in vehicles/<vehicle>/nav2/; the image and its launch file are the framework's, in compose/compute/images/nav2/, tagged ovcs/nav2:lyrical wherever it is built. ./ovcs compute stage bakes the vehicle's parameters and its expanded URDF into the onboard image; the local stacks mount them.

The file holds the vehicle's values (use_sim_time: false); the simulator overrides the clock with a launch argument rather than keeping a copy that would drift.

NavigateToPose goal ─► bt_navigator ─► planner_server (Smac Hybrid-A*) ─► path
                                   └─► controller_server (MPPI) ◄─ /odom, /tf, costmaps (the vehicle's obstacle sources)
controller_server, behavior_server ─/cmd_vel_nav_raw─► velocity_smoother ─/cmd_vel_nav @ 20 Hz─►

What is deliberately unusual:

• No map, no AMCL. Every frame is odom and both costmaps roll with the vehicle: enough to prove the velocity path drives an Ackermann vehicle without the SLAM question, and no fake static map → odom, which looks like localisation and is not.
• AckermannConstraints. MPPI's motion_model names a plugin instance; the class, mppi::AckermannMotionModel, comes from <instance>.plugin. It clamps yaw rate to |vx| / min_turning_r inside the sampler, so infeasible arcs are never considered. min_turning_r is 0.324 / tan(0.52) = 0.566 m, rounded up to 0.6.
• TwistStamped on /cmd_vel_nav. nav2_util::TwistPublisher defaults enable_stamped_cmd_vel to true; its header comment says otherwise, and the code wins.
• The rest is the vehicle's. Obstacle sources, speed limits, reverse and recovery distances follow from a vehicle's sensors and drivetrain; the OVCS Mini reference vehicle's are in its README.
• No Spin in either behaviour tree. A car produces no motion from a spin, so it ran its full duration and burned a recovery slot. The spin server stays loaded because bt_navigator resolves every action at activation.
• Smac Hybrid-A*, built from source. nav2_smac_planner is released for Lyrical but absent from its archive, so the Nav2 image builds it from that release's source, at the version of the Nav2 packages it installs. It plans arcs the vehicle can drive; a grid planner such as NavFn plans corners and sideways steps, and MPPI shuffles forward and back against them. Its configure must finish inside rmw_zenoh's 10 s service timeout, or the lifecycle manager gives up: the Reeds-Shepp lookup_table_size is what sets that time.
• default_server_timeout is 1 s. A behaviour-tree node waits that long for a server to accept its request. The default 20 ms is missed over Zenoh while the planner is searching, and a missed acknowledgment fails the whole goal.
• yaw_goal_tolerance is 3.15. A car cannot rotate in place to a final heading.

#Arriving proves almost nothing

Gazebo's AckermannSteering quietly ignores commands it cannot execute. With mppi::DiffDriveMotionModel substituted in, the vehicle reached the tight goal better than the correct configuration (0.30 m against 0.53 m) while commanding 3.68× the kinematic yaw-rate limit. Judge a configuration by what it commands, not by whether it arrives.

#Perception against the simulator

The stereo stack and the detector run unchanged against Gazebo; only the camera driver differs, RosBridge.Camera.Zenoh in place of RosBridge.Camera.LibCamera. Running perception against it covers the wiring, why the images are compressed, and the simulator's own calibration. Detection and its backends are in Perception.

#Per-vehicle bridge configuration

Every feature of RosBridge is a component your vehicle opts into through %RosBridge.Config{}; Configure it in your vehicle has the arms, the OVCS Mini's configuration, and the node names two bridges on one fabric need.

#Version pins

These move together. The pins job in .github/workflows/ros2.yml fails when the router image and the Python client disagree; it does not read bridges/ros_bridge/mix.exs, so check the zenohex pin by hand.

#Verifying end to end

With ./ovcs run <vehicle> going and the compose/local/base.yml stack up:

cd compose/local && docker compose -f base.yml exec ros2 bash -lc '
  source /opt/ros/*/setup.bash
  ros2 topic list
  ros2 topic info -v /ovcs_heartbeat
  ros2 topic echo /ovcs_heartbeat std_msgs/msg/String
'

Or open Foxglove Studio against ws://<docker-host>:8765 and subscribe to /ovcs_heartbeat. compose/local/foxglove/ovcs_stereo_tuning.json is for tuning the stereo cameras; a vehicle's own layouts live in its foxglove/ directory, such as the OVCS Mini reference vehicle's ovcs_nav2.json for the planner and ovcs_stereo.json for the stereo pipeline.

#Reading map

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