Chapter 07 · Build a repeatable robot laboratory in Gazebo

Today in the field story

One problem, then the next

Close the Rainy-Day Simulator Lab with frozen initial conditions, named oracle, fault schedule, reset, artifacts, and limitations. Run nominal, delay, frozen-stamp, dropout, scale, and bridge-direction rows one cause at a time before combined stress. Keep failed trials and show exactly which modeled conditions passed, which terminal state occurred, and which hardware, site, and safety claims remain unverified.

Why now: A controlled matrix turns the simulator from a visual demo into a regression laboratory.
Ignore today: Ignore sim-to-real success claims and manual scene editing during acceptance runs.
Unlocks next: A qualified base and evidence harness for resilient navigation.

Understand

Build the physical picture first

A simulation test is a controlled scientific experiment: freeze the starting conditions, change one cause, and judge a measurable result.

A reusable scenario is more than a world file. It names the world and model revisions, initial poses, time and physics settings, configuration, seed set, launch order, command input, fault schedule, duration, and reset procedure. It also defines an oracle: a machine-checkable rule for the expected result. A screenshot of a rover beside a wall is not an oracle. An assertion such as no collision, stop command within 150 ms, measured speed below 0.02 m/s within 400 ms, and terminal result ABORTED is inspectable.

Fault injection introduces a known problem at a known boundary and time. Useful sensor faults include added bias, noise burst, lower rate, packet drop, frozen timestamp, invalid value, delayed transform, and complete disconnect. Inject one first so the evidence has one likely cause; combined faults belong in later stress tests. Preserve the clean baseline and verify it again after each repair. A fault tool that changes internal state without recording exactly what it changed can make the test less trustworthy than the bug.

Use a small scenario matrix rather than one perfect demo. Give every row an ID, seed, change from baseline, predicted symptom, expected detection, bounded response, terminal state, metrics, and artifact paths. Run multiple trials when noise or concurrency affects outcomes. Report successes over attempts, detection and stop latency percentiles or ranges, false alarms, collisions, timeouts, and unexplained cases. Never delete a failure merely because a later rerun passed.

This chapter's portfolio artifact should let a reviewer run one command, see a baseline and several controlled failures, and inspect a concise report linked to raw logs and MCAP. State the evidence boundary plainly: Gazebo validates software integration against modeled physics and faults. It does not prove real friction, sensor optics, motor current, network interference, emergency-stop circuitry, human interaction, or site acceptance. That honesty makes the work stronger for validation, integration, robotics-software, and physical-AI deployment roles.

Words you need

Name each idea precisely

Scenario: A versioned test definition containing starting state, inputs, conditions, timing, expected result, and evidence.
Physical example:
Rover starts two metres from a wall, receives 0.3 m/s for three seconds, then its lidar timestamp freezes at simulation time 2.0 s.
Oracle: A rule that decides whether the observed result satisfies the test expectation.
Physical example:
No contact plus measured speed below 0.02 m/s within 400 ms is stronger than a person saying the stop looked fine.
Fault injection: Deliberately introducing a known failure at a controlled boundary and time.
Physical example:
A relay node keeps publishing scans while freezing their timestamps to test freshness handling.
Seed set: A recorded collection of random seeds used to repeat particular noise cases and sample outcome variation.
Physical example:
Seeds 3, 17, and 42 create three named noise sequences included in every regression run.
Regression: A previously working behavior that breaks after a change, detected by rerunning stable tests.
Physical example:
A bridge update makes the frozen-stamp scenario time out instead of reaching the expected safe abort.

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.

Programmer analogy

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.

With $r=0.1\,\mathrm{m}$ , $L=0.5\,\mathrm{m}$ , and $\omega_R=\omega_L=4\,\mathrm{rad/s}$ , the expected motion is $v=0.4\,\mathrm{m/s}$ and $\Omega=0$ . Setting only $\omega_R=0$ gives

v=\frac{0.1(0+4)}{2}=0.2\,\mathrm{m/s},\qquad \Omega=\frac{0.1(0-4)}{0.5}=-0.8\,\mathrm{rad/s}.

Fixed numeric expectations make the injected fault auditable.

Design a four-row sensor-fault matrix

A simulated rover approaches a wall at 0.30 m/s. Its command gate should stop on stale or invalid lidar before contact.

Define the nominal row: seed 17, fresh 20 Hz scans, no collision, task completes, and all health checks remain healthy.
Define a noise row: add the documented range spread, expect no false stop across the declared seed set, and record minimum clearance.
Define a frozen-stamp row at simulation time 2.0 s: expect stale detection within the age limit and a bounded stop before contact.
Define a disconnect row: stop scan delivery, expect a distinct no-data reason, bounded output, and terminal ABORTED rather than endless RUNNING.
For every row capture scenario ID, versions, seed, message counts, detection latency, command trace, measured velocity, clearance, contact count, terminal state, and artifact links.
Run the baseline again after restoring faults and compare the full result table rather than only the final status.

Result

The matrix distinguishes normal variability, freshness failure, and transport loss while using measurable safe outcomes instead of visual judgement.

What this proves

A small, controlled, repeatable matrix teaches more than a large unstructured demonstration.

Physical examples

Where this appears in real life

Fire drill

A building drill fixes the alarm condition, observes detection and evacuation, records problems, and never claims that one drill proves every possible fire safe.

Look for:

Relate the alarm to injected stimulus, evacuation criteria to the oracle, and untested real fire conditions to the simulation evidence boundary.

Bicycle brake test

A mechanic marks a start line, speed, surface, load, braking point, and stopping-distance limit, then changes one condition at a time.

Look for:

Without controlled speed and surface, two stopping distances cannot be fairly compared.

Hands-on exercise

Make the idea observable

Package the week's world, differential-drive model, sensor configuration, command gate, health monitor, and MCAP evidence into one reproducible repository.

Write a scenario schema containing IDs, versions, hashes, initial state, time and physics settings, seed, inputs, fault schedule, assertions, and artifact locations.
Implement one clean baseline plus at least frozen timestamp, rate reduction or dropout, invalid value, and disconnect as isolated scenario rows.
Run each row from a full reset, preserve raw logs and selected MCAP, and calculate detection time, bounded-command time, measured-stop time, clearance, contacts, and terminal state.
Repeat stochastic rows over the declared seed set, retain every failure, and produce a concise table linked to the decisive evidence.
Have a second engineer or clean environment execute the documented entry point, then record differences and the simulation-to-hardware limitations that remain unverified.

Observe

A useful harness makes the expected failure visible, reaches a bounded terminal result, resets cleanly, and produces the same explanation without manual scene editing.

Done when

A reviewer can reproduce the nominal and fault rows, trace every verdict to raw evidence, and see an explicit list of hardware, safety, and site claims the simulator cannot prove.

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 weekly ship note explains how “Reproducible simulation scenario and fault-injection demo” changed the build, what still fails, and the first task for next week.

Common mistakes

Catch the wrong mental model

Wrong

Calling a saved world a reproducible scenario.

Better

Include model and code versions, effective configuration, initial state, clock, physics, seed, input, fault schedule, reset, oracle, and artifacts.

Wrong

Injecting several failures in one first test and guessing which one caused the outcome.

Better

Establish a clean baseline and inject one controlled fault per diagnostic scenario before combined stress cases.

Wrong

Presenting simulation success as real-robot safety or site acceptance.

Better

State that the harness validates software against modeled conditions and list the physical, electrical, environmental, and human factors still unverified.

Job connection

How this becomes employable evidence

Ship a deterministic-enough Gazebo regression harness that scores nominal and degraded robot behavior, retains failures, and forms the software-in-the-loop layer of a later HIL and real-robot evidence chain.

Relevant target roles

Robotics Deployment, Integration & Validation Engineer
Robotics Software Engineer — ROS 2 / AMR
Robot Learning Deployment / Physical AI Integration Engineer

Chapter 07 interview drill

Interview questions: Reproducible simulation scenario and fault-injection demo

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

Design a simulation test for a rover that must stop when lidar timestamps freeze. Specify the fixture, injection point, clock, oracle, metrics, reset, artifacts, repeated trials, and claims you would not make.

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 turns a visual demo into a test?

Model interview answer

Controlled starting conditions and inputs, a repeatable procedure, a machine-checkable expected result, measured evidence, and a clean reset.

Q2Why keep failed trials when a rerun passes?

Model interview answer

Intermittent failures reveal nondeterminism or missing controls; deleting them hides the reliability distribution the test is meant to measure.

Q3What does a Gazebo sensor-fault test not prove?

Model interview answer

It does not prove real sensor optics, wiring, power, floor contact, motor behavior, networks, emergency-stop circuitry, people, or site acceptance.

Chapter starter artifact

Check simulated drive geometry and frozen time

A pinned Jazzy/Harmonic world launches one differential-drive robot, verifies bridge and ros2_control boundaries against ground truth, records sensor contracts and MCAP evidence, detects frozen or degraded sensors, and reproduces nominal plus controlled-fault verdicts.

week-07-rainy-day-lab.mjsJavaScriptDownload starter

const mission = "rainy-day-simulator";
const wheelRadius = 0.1;
const wheelSeparation = 0.5;
const leftRadPerSec = 4;
const rightRadPerSec = 6;
const linear = wheelRadius * (rightRadPerSec + leftRadPerSec) / 2;
const yawRate = wheelRadius * (rightRadPerSec - leftRadPerSec) / wheelSeparation;
const simulatedSeconds = 20;
const wallSeconds = 30;
const realTimeFactor = simulatedSeconds / wallSeconds;
const sourceStamps = [0, 0.05, 0.1, 0.1];
const geometryValid = [
  wheelRadius, wheelSeparation, leftRadPerSec, rightRadPerSec,
  simulatedSeconds, wallSeconds,
].every(Number.isFinite) && wheelRadius > 0 && wheelSeparation > 0 && wallSeconds > 0;
if (!geometryValid) throw new Error("invalid simulation contract");
const timeProgresses = sourceStamps.every((stamp, index) =>
  Number.isFinite(stamp) && stamp >= 0 && stamp <= simulatedSeconds &&
  (index === 0 || stamp > sourceStamps[index - 1])
);
const health = timeProgresses ? "HEALTHY" : "DEGRADED";
console.log("mission=" + mission);
console.log("linear=" + linear.toFixed(3) + "m/s");
console.log("yawRate=" + yawRate.toFixed(3) + "rad/s");
console.log("rtf=" + realTimeFactor.toFixed(3));
console.log("sensor=" + health);
console.log("status=PASS");

Download the file into your terminal's current folder, then run the command below. The expected output is exact.

Run: node week-07-rainy-day-lab.mjs
Expected output: mission=rainy-day-simulator linear=0.500m/s yawRate=0.400rad/s rtf=0.667 sensor=DEGRADED status=PASS
Planted failure to diagnose: Check only callback arrival intervals and delete the source-stamp progression test. Replayed frozen measurements then look healthy even though simulated observation time has stopped.