Chapter 07
Build a repeatable robot laboratory in Gazebo
Use Gazebo Harmonic as a controlled laboratory for a differential-drive robot: make physics and time explicit, connect ROS 2 without hiding boundaries, model imperfect sensors, capture evidence, and prove safe behavior under repeatable faults before making claims about hardware.
Before you start
- Recognize ROS 2 nodes, topics, messages, QoS, lifecycle state, namespaces, and launch files.
- Read a URDF or Xacro model, follow a tf2 tree, and distinguish a command from measured joint state.
- Use metres, seconds, radians, hertz, and simple averages; calculate period as one divided by frequency.
- Understand that simulation is evidence about a model, not acceptance evidence for a powered physical robot.
By the end
- Pin a supported ROS 2 and Gazebo pairing, describe a small SDF world, and distinguish simulation time, wall time, physics step size, and achieved real-time factor.
- Spawn and name a robot, bridge selected Gazebo Transport messages to ROS 2, activate simulated ros2_control interfaces, and verify differential-drive motion against Gazebo ground truth.
- Inspect lidar, RGB or depth camera, IMU, and encoder messages with the correct frame, unit, timestamp, rate, and validity interpretation.
- Add deliberate noise, bias, rate, delay, and dropout while keeping the random seed and unchanged test conditions recorded.
- Record selected ROS 2 evidence to MCAP, verify recording completeness and QoS, and explain what additional state is required for a repeatable replay.
- Design freshness, plausibility, continuity, and cross-sensor health checks with an explicit safe degraded response.
- Ship a scenario matrix that reproduces nominal behavior and controlled failures, measures detection and terminal state, and states the limits of simulation honestly.
The field story
The Rainy-Day Simulator Lab
The warehouse team cannot test outdoors during a week of heavy rain, so the validated robot model moves into a Gazebo laboratory. A previous demo looked convincing but mixed wall time with simulation time, bridged every available topic, used ground truth inside the algorithm, and lost the configuration that produced its one good run. You must rebuild the laboratory as a controlled experiment whose world, model, physics, clock, bridge directions, controllers, sensors, noise, recording, and reset are all explicit.
The Rainy-Day Simulator Lab follows one differential-drive robot through nominal travel and deliberate sensor failures. The golden path is ROS 2 Jazzy with Gazebo Harmonic; Jetty, Kilted, Lyrical, and rolling examples are compatibility research only. Ground truth is reserved for evaluation, while the robot consumes only interfaces it could plausibly have in reality. The mission finishes with a scenario matrix that another engineer can start from one command, replay from MCAP, and judge without accepting visual motion as proof.
- Why this chapter now
The model and controllers need a repeatable world where success and failure can be measured before expensive or hazardous hardware work.
- Ignore for now
Ignore photorealism, real weather, hardware safety certification, and autonomous navigation. Control one modeled world and small fault set.
- This unlocks
Nav2 integration, perception fixtures, state-estimation replay, SIL tests, and evidence-backed sim-to-real gap statements.
- Proof you will leave with
Save version and clock contract, world/model hashes, bridge map, command/state/ground-truth comparison, sensor table, noise and timestamp faults, MCAP manifest, health transitions, starter output, and scenario report.
Environment contractUbuntu 24.04, ROS 2 Jazzy, and Gazebo Harmonic form the golden simulator path. Use Jazzy-compatible ros_gz and gz_ros2_control packages from one qualified environment. The dependency-free starter runs with repository-supported Node.js 22.13.0 or newer.
- Compatibility boundary
Gazebo Jetty and later ROS distributions belong in isolated compatibility branches. Never mix Jetty install instructions, Kilted package docs, or rolling controller configuration into the Harmonic/Jazzy acceptance run.
- Smoke check
Source Jazzy, confirm
ROS_DISTRO=jazzy, recordgz sim --versions, and verifyros_gz_bridgeplus the qualified gz_ros2_control package resolve before launching the chapter world.- Contract reviewed
2026-07-25
- Runtime evidence
The dependency-free starter is executed by repository tests on the supported Node.js baseline. Chapter-specific ROS 2, Gazebo, model, dataset, checkpoint, and hardware environments are learner-created unless the repository supplies an explicit asset; run the smoke check and preserve its versions and output before claiming runtime compatibility.
- Drift risk
high
Today in the field story
One problem, then the next
Open the Rainy-Day Simulator Lab by freezing the Jazzy/Harmonic pairing, world, robot, physics step, clock source, and seed. Compare simulation time with wall time and calculate achieved real-time factor, then change only one physics setting. A faster animation or higher RTF is throughput evidence, not proof that contact, inertia, friction, or controller behavior is physically credible.
- Why now
Every later sensor and controller result depends on a controlled model and a correctly interpreted clock.
- Ignore today
Ignore Jetty migration and real-world accuracy claims.
- Unlocks next
A stable laboratory in which command and sensor boundaries can be measured.
Understand
Build the physical picture first
Gazebo is a clock-driven laboratory: on each small tick it updates a mathematical world, so you must control the clock and the model before trusting what the picture does.
Gazebo Sim is not a video game that merely draws a robot. It repeatedly applies a physics model to bodies, joints, contacts, gravity, and actuators, then lets simulated sensors observe the resulting world. SDF describes the world and its models; system plugins perform jobs such as physics, commands, sensors, and scene broadcasting. This course pins ROS 2 Jazzy with Gazebo Harmonic because the Gazebo project identifies that long-term-support pair as the recommended beginner combination. Gazebo Jetty is newer, but its normal supported pairing is the moving ROS 2 Rolling distribution. A reproducible learner project should not silently mix documentation and packages from both combinations.
Simulation time is the time inside the experiment. Wall time is what a clock on your desk measures while the computer runs it. Gazebo can pause simulation time, advance exactly one step, reset it, or run it slower or faster than the wall clock. ROS nodes that participate in the experiment must consistently use the published simulation clock; otherwise one node may stamp data with wall time while another asks tf2 for a pose in simulation time. That creates huge apparent ages and lookup failures even when both pieces of software are individually running.
The maximum physics step is the largest simulated-time interval between physics updates. With a 0.001 s step, one simulated second needs about 1,000 updates. A smaller step can represent fast contact changes more finely, but it requires more computation and does not repair wrong mass, inertia, friction, geometry, or controller gains. Real-time factor, or RTF, is simulated elapsed time divided by wall elapsed time. An achieved RTF of 0.67 means the world advances only 0.67 simulated seconds per wall second; it does not by itself say whether the model is accurate.
Treat every world as a versioned test fixture. Record the Gazebo and ROS versions, world file, expanded robot description, physics settings, initial poses, parameters, and random seed where the component supports one. Begin with a tiny known experiment such as dropping one box onto one plane. Measure contact behavior and final pose instead of judging animation smoothness. Simulation earns trust through repeatable measurements and controlled comparisons, while a real robot still needs separate checks for wiring, backlash, floor friction, load, timing, and safety.
Words you need
Name each idea precisely
- SDF
Simulation Description Format, the XML-based description of worlds, models, lights, physics settings, sensors, and plugins used by Gazebo.
Physical example:An SDF world can place a 1 kg box one metre above a plane and specify the gravity and physics step used for its fall.
- Simulation time
The experiment's own clock, which can pause, reset, step, or advance at a different rate from wall time.
Physical example:When Gazebo is paused at 4.2 s, a correctly configured ROS timer based on simulation time should not keep advancing.
- Physics step
The simulated-time interval between successive numerical updates of the world state.
Physical example:A 1 ms step asks the physics engine to update contact and motion up to 1,000 times per simulated second.
- Real-time factor
The ratio of simulated elapsed time to wall elapsed time, used to report how fast the experiment runs.
Physical example:Thirty simulated seconds completed in 45 wall seconds gives an achieved RTF of 30 ÷ 45, or about 0.67.
- Ground truth
The simulator's internal state used as a reference for checking an estimated or sensor-derived value.
Physical example:Gazebo's exact model pose can be compared with wheel odometry, but a real warehouse does not provide that exact pose for free.
Math, one line at a time
Work through today’s relationship
Prerequisite rescue · optionalSimulation time, real-time factor, and sensor noise
A simulator is useful only when time and uncertainty are measured honestly.
- RTF
- simulated elapsed time divided by real elapsed timeUnit: unitless
- μ
- average sensor valueUnit: sensor unit
- σ
- typical spread around the averageUnit: sensor unit
A run simulates 20 s but takes 25 s of wall time.
RTF = 20/25 = 0.8.
The simulator is slower than real time; compare timestamps in simulated time and report RTF with every performance result.
A test clock can be mocked in web software; robot sensor timestamps must still stay mutually consistent.
Ten simulated seconds take five real seconds. What is RTF?
10/5 = 2.0, so simulation runs twice as fast as real time.
A step requires
updates per simulated second. The real-time factor is
Calculate updates and achieved real-time factor
A fixed drop test uses a 0.001 s maximum step. Gazebo advances from 0 s to 30 s of simulation time while a monotonic wall clock advances 45 s.
Convert the step to seconds: 1 ms equals 0.001 s.
Divide one simulated second by the step: 1 ÷ 0.001 = 1,000 physics updates per simulated second.
Multiply by the run length: 30 × 1,000 = about 30,000 updates if every maximum-size step is used.
Calculate achieved real-time factor: 30 simulated seconds ÷ 45 wall seconds = 0.666…
Report the result as RTF ≈ 0.67 together with step size, run length, hardware, world version, and measured outcome.
The computer ran the experiment at about two-thirds of wall-clock speed and performed roughly 30,000 physics updates.
RTF describes throughput, while physical credibility must be checked with model parameters and measured outcomes.
Physical examples
Where this appears in real life
Slow-motion phone video
A phone records a bouncing ball at many frames per second and plays it back slowly. Video time, playback time, and the real event's time are different clocks.
Use the analogy only for clock separation: Gazebo also calculates forces and state at each step, which a recorded video does not.
Measuring a table with different rulers
A coarse ruler may miss a small gap, while a finer ruler reveals it. Neither ruler fixes a bent table or a wrong measurement method.
Relate ruler spacing to physics step size, and relate the table's actual shape to mass, geometry, friction, and other model assumptions.
Hands-on exercise
Make the idea observable
Use a saved Gazebo Harmonic world with one plane and one box. Keep mass, geometry, initial pose, solver, and camera unchanged.
Record the installed ROS and Gazebo versions, world hash, physics engine settings, initial box height, and current simulation-clock policy.
Run the drop with a supported 0.001 s maximum step and record simulated duration, wall duration, achieved RTF, final box height, and visible contact behavior.
Repeat from a full reset with one deliberately different supported step size while changing nothing else.
Compare final pose, contact penetration or bounce, update count, and RTF in one table; include the exact commands and raw world statistics.
Return to the baseline setting and confirm the original result repeats before writing a conclusion.
A smaller step normally costs more computation, but any change in contact behavior must be reported as an observation tied to this model rather than a universal law.
A second engineer can use the pinned files and settings to reproduce both runs and explain the difference between simulation time, wall time, step size, and RTF.
Build today
Simulate a ros2_control differential-drive robot in Gazebo Harmonic with lidar, RGB-D camera, IMU, noise, bridges, and MCAP replay.
Evidence to save
DONE when the learning log explains “Gazebo Harmonic physics, simulation time, and real-time factor” in five precise points and a checked example produces the predicted output.
Common mistakes
Catch the wrong mental model
Mixing Gazebo Jetty instructions into a Jazzy and Harmonic workspace because Jetty is newer.
Pin one supported pairing. For this chapter use ROS 2 Jazzy with Gazebo Harmonic; evaluate Jetty with its supported ROS pairing in a separate compatibility branch.
Treating a high real-time factor as proof that physics is accurate.
Use RTF for execution speed and compare known outcomes, model parameters, contact behavior, and real measurements for credibility.
Reducing the physics step until a bad model appears stable.
Check inertia, mass, collision geometry, friction, limits, controller period, and time source before tuning numerical settings.
Job connection
How this becomes employable evidence
Create a versioned Gazebo baseline whose world statistics and known drop test detect a changed physics configuration before a navigation regression suite runs.
Relevant target roles
- Robotics Deployment, Integration & Validation Engineer
- Robotics Application / ROS 2 Integration Engineer
- Robotics Software Engineer — ROS 2 / AMR
Chapter 07 interview drill
Interview questions: Gazebo Harmonic physics, simulation time, and real-time factor
Practise a 60–90 second answer: define the idea, connect it to a physical robot, state assumptions, frames, and units when relevant, then finish with the failure signal or evidence you would inspect.
Primary interview scenario
A simulated rover oscillates only on a slower laptop and RTF falls below 0.5. Explain how you would separate a simulation-clock bug, missed controller timing assumption, physics-step change, and merely slower wall-clock execution.
Answer shape: clarify the situation → trace the physical and software path → test the most likely boundaries → name the evidence that would confirm the result.
Technical follow-up questions
Q1What happens to a simulation-time ROS timer while Gazebo is paused?
It should stop advancing because the simulation clock is not advancing, even though wall time continues.
Q2If 20 simulated seconds take 10 wall seconds, what is achieved RTF?
RTF is 20 ÷ 10 = 2.0, so simulation time advanced twice as fast as wall time.
Q3Why can a smaller physics step still produce a wrong result?
It only changes numerical update spacing; wrong mass, inertia, geometry, friction, joint, controller, or sensor assumptions remain wrong.
Chapter references
- Gazebo — installing Gazebo with ROSThe official compatibility table and the beginner recommendation to use Ubuntu 24.04, ROS 2 Jazzy, and Gazebo Harmonic; Jetty is the current pairing for ROS 2 Rolling rather than this chapter's pinned baseline.
- Gazebo Harmonic — SDF worlds and physicsWorld structure, physics-system plugins, maximum step size, simulation statistics, and real-time factor.
- Gazebo Harmonic — sensorsOfficial examples for attaching IMU, contact, and lidar sensors, setting update rate and topic, and inspecting generated data.
- Gazebo Harmonic — ROS 2 integrationThe ros_gz_bridge boundary, supported message conversions, bridge direction, ROS-side visualization, and Gazebo-side commands.
- ROS 2 — rosbag2 MCAP storageThe maintained rosbag2 MCAP storage plugin and the record, play, and info workflow used for captured ROS 2 evidence.