Write the Startup Runbook So Another Student Can Reproduce the System

A system is not repeatable if the only working startup procedure is stored in one person's shell history.

The final Unit 7 skill is writing a runbook: a short operational procedure that states the environment, commands, expected evidence, common failures, and stop conditions clearly enough that another student can reproduce the same ROS-side runtime.

Start from a known state

The runbook should begin with assumptions, not commands.

For this course:

Operating system: Ubuntu 24.04
ROS distribution: Jazzy
ROS underlay: /opt/ros/jazzy
workspace: ~/robot_ws
bringup package: robotnix_bringup
launch file: demo_pair.launch.py

A reader should know immediately whether their environment matches the procedure.

Separate build steps from run steps

Do not mix every command into one giant block.

Build/update phase

Use when source has changed:

source /opt/ros/jazzy/setup.bash
cd ~/robot_ws
colcon build --packages-select robotnix_bringup

Preserve the build result.

Runtime shell setup

Use in every fresh shell that needs the overlay:

source /opt/ros/jazzy/setup.bash
source ~/robot_ws/install/setup.bash

Verify:

ros2 pkg prefix robotnix_bringup

Launch phase

ros2 launch \
  robotnix_bringup \
  demo_pair.launch.py

Verification phase

In a second sourced shell:

ros2 node list
ros2 topic list -t
ros2 topic info /robotnix/demo

Each phase answers a different operational question.

State the expected evidence

A runbook that only says "run these commands" is hard to debug.

Write expected results.

For example:

package prefix:
  ~/robot_ws/install/robotnix_bringup

expected nodes:
  /talker_demo
  /listener_demo

expected topic:
  /robotnix/demo [std_msgs/msg/String]

expected endpoints:
  publisher 1
  subscriber 1

Now a mismatch is visible immediately.

Include argument variations explicitly

If the launch supports:

topic_name

document both the default and override syntax.

Default:

ros2 launch robotnix_bringup demo_pair.launch.py

Override:

ros2 launch \
  robotnix_bringup \
  demo_pair.launch.py \
  topic_name:=/robotnix/test

The runbook should say which runtime topic to expect in each case.

Do not make the reader infer the effect from Python source every time.

Add a short fault-isolation table

A useful runbook includes the failures students are likely to see.

The table should point to the next evidence, not promise a universal fix.

Document clean shutdown

A runbook should say how to stop the system.

For this demo:

Ctrl+C in the launch terminal

Then verify the launched nodes disappear from the graph.

Shutdown is part of repeatability. A procedure that only explains startup leaves old processes running and makes the next experiment harder to interpret.

Record what the runbook does not start

Write this explicitly:

This runbook starts the ROS 2 demo bringup only.
It does not build, start, or connect a WPILib Java application.

That prevents the next student from assuming a Java process should appear because the course title includes Java.

A future mixed-runtime runbook would need an explicit bridge/application startup section.

Keep local paths configurable where practical

The teaching path uses:

~/robot_ws

A production or team system may use another workspace location.

Document the canonical path for the course rather than scattering absolute paths copied from one student's username.

For evidence, it is fine to preserve the actual resolved package prefix from the current machine.

Test the runbook from a fresh shell

The best review is not proofreading it while your working environment is already configured.

Open a new terminal and follow the document exactly.

If you find yourself doing an undocumented command such as:

source ~/something_else/setup.bash

then the runbook is incomplete or the environment assumptions are wrong.

Every hidden step you discover is a defect in reproducibility.

A runbook should be shorter than the lessons

The lessons explain why.

The runbook tells an informed student what to do and what to check.

Do not copy all five Week 16 lessons into the runbook.

A strong runbook is compact because the underlying concepts are already taught.

Your final pre-lab task

Draft the runbook with these headings:

Environment assumptions
Build/update
Fresh-shell setup
Package verification
Launch
Post-launch verification
Optional topic override
Shutdown
Fault isolation
Java/WPILib boundary

For every command, include the expected evidence that tells the operator whether it worked.

Then red-team the document:

• Does it depend on previous shell history?
• Does it tell the operator which workspace prefix should resolve?
• Does it separate build from launch?
• Does it say how to verify the graph?
• Does it say how to stop the runtime?
• Does it falsely imply Java is launched or integrated?

The Unit 7 lab will hand you several broken startup records. Your job will be to repair the runbook and identify the minimum change that fixes each case.