RL Robotics LabSearch ↗
Lesson / authored

Week 12 · Build: Requirements and guardrails

Session 2 of 4 · Tune and validate · Phase 3

Plan about 15 minutes for explanation, 30 minutes for practical work and 10–15 minutes for documentation. A longer build may continue into the next session: stop safely, commit the current state and record the next check. Desktop simulations count as software evidence; label them clearly and record physical validation separately.

Engineering challenge

Does the chosen controller work on a case it was not tuned to pass? This session focuses on requirements and guardrails.

Before you start

The previous week’s recorded baseline and Week 11, Improve. For later sessions this week, retain the preceding session’s files and predictions.

Equipment: Desktop Python, editor, paper and ruler; for physical work, the configured 3pi+ 2040, clear floor mat and hardware checklist. Week 3 additionally uses the separate low-voltage LED circuit described in its procedure.

For any motion, verify the stop button, short time limit and clear floor area first. Keep the wheels raised for a new device program until its commands and stop behaviour are checked. A hazard or uncertain input is a reason to stop and document, not to force the trial to finish.

Theory and mathematics

Requirements and guardrails

A useful controller requirement specifies a measured outcome and conditions. For a simulation example: mean absolute speed error after the transient ≤0.02 m/s, overshoot ≤20%, and output ≤1 normalized unit. These are teaching values, not universal robot specifications. A guardrail prevents optimization of one metric at unacceptable expense to another. Stop behaviour, stale-input rejection and bounded run duration are mandatory even if speed error improves. Write the requirements and metric windows before running the validation.

Worked example — illustrative values

For fictional post-transient errors 0.01, −0.02, 0.00 and 0.01 m/s, mean absolute error is 0.01 m/s. If peak speed is 0.12 m/s for a 0.10 target, overshoot is 100×(0.12−0.10)/0.10 = 20%. Define the window and nonzero target before using either metric.

Write the calculation in your notebook before running code. State which values you measured, which you assumed and which the program calculates. A correct numerical calculation cannot rescue an incorrect physical assumption.

Run and explain the model

The following is desktop Python, not a ready-to-run motor program. Download this week’s example, save it in your student repository and run python3 code/w12.py from the repository root. The same small model is reused across the week so you can learn it, build with it, test it and revise it.

# Desktop Python teaching example. Numerical inputs are illustrative.
errors = [0.01, -0.02, 0.0, 0.01]  # fictional
mae = sum(abs(error) for error in errors) / len(errors)
reference, peak = 0.10, 0.12
overshoot_percent = max(0, peak - reference) / reference * 100
print("mae_m_s", mae, "overshoot_percent", overshoot_percent)

Run the example on desktop Python before adapting it. Change one valid input and check the result; keep device-only calls in a separate adapter. If an exception appears, read its final line, identify the input or assumption that caused it and make the smallest explained correction. Do not delete validation merely to obtain output.

Understanding the model and its limits

The metric code illustrates two different questions: mean absolute tracking error and peak overshoot relative to a reference. It does not run a controller; use the traces saved in Weeks 9–11. Overshoot is zero if the peak does not exceed the target. A zero reference needs a different metric because the percentage formula would divide by zero. Declare a settling band and duration before examining your final trace. Count stopped or invalid runs separately rather than assigning them an attractive small error. The chosen controller must pass the held-out route with its settings unchanged.

Practical instructions

  1. Freeze the Week 11 controller, calibration and all gains in a configuration file.
  2. Create a comparison runner that resets state and uses identical scenarios for P baseline and chosen controller.
  3. Save CSV traces with trial,controller,time_s,reference,speed,error,command fields.
  4. Add ordinary, stop and invalid-sensor checks to the runner.

Experiment

Repeat an identical simulated scenario twice after reset and verify the traces match; then inject a stale sensor to check safe failure.

Before testing, record your prediction, changed factor, measured response, fixed conditions and stopping rule. Save every attempted run, including failures, with a condition and source version. If hardware is unavailable, use an explicitly labelled synthetic/replay dataset and list the physical question it cannot answer. Do not invent completed trials.

Deliverable

A resettable runner with code/configuration provenance and correctly labelled traces.

Save notebook/w12-s2.md, the relevant code revision, raw CSV or test-case records, and one labelled diagram/plot/table. Link the files relatively from your notebook. Use the entry template and report guide.

Completion criteria

A documented failed prediction can meet the learning criteria. A missing physical trial must remain marked untested; software success alone does not validate the robot.

Reading and video

Reflection and next step

Which assumption most affected your result? Point to one observation that supports your explanation and one alternative explanation the evidence has not ruled out. Write a specific next test with a changed factor and measurable outcome, then proceed through the week’s Learn → Build → Experiment → Improve cycle.

← Previous sessionCourse roadmapNext session →