RobotnixAcademy

Unit 16 · lab

Lab: Repair a Broken ROS 2 Bringup From the Smallest Useful Evidence

This lab closes Unit 7 by giving you a startup system that is almost correct in several different ways.

You will diagnose five bounded failures, repair each one at the correct layer, and finish with a clean-shell Repeatable Startup Runbook plus a separate Java-to-ROS Integration Contract.

The goal is not to make every problem disappear with a rebuild. The goal is to identify which layer failed before changing anything.

Guided example: wrong workspace prefix

Observed:

ros2 pkg prefix robotnix_bringup

returns:

/home/student/old_ws/install/robotnix_bringup

while you are editing:

/home/student/robot_ws/src/robotnix_bringup

A weak repair is:

rebuild robot_ws again

The current shell would still resolve the old overlay.

A stronger repair is:

new terminal
source /opt/ros/jazzy/setup.bash
source ~/robot_ws/install/setup.bash
ros2 pkg prefix robotnix_bringup

Only after the prefix resolves to robot_ws should you judge whether the new source/install state is correct.

Use that same layer-first reasoning in every case.

Case 1: clean-shell package lookup fails

Supplied evidence:

$ echo $ROS_DISTRO
jazzy

$ ros2 pkg prefix robotnix_bringup
Package not found

Additional evidence:

~/robot_ws/install/setup.bash exists
Week 14 build record: 1 package finished

Your job

Identify the missing layer and write the minimum repair command.

Then state why rebuilding is not the first justified action.

Case 2: package resolves, launch file is missing

Supplied evidence:

$ ros2 pkg prefix robotnix_bringup
/home/student/robot_ws/install/robotnix_bringup

Source tree:

src/robotnix_bringup/launch/demo_pair.launch.py

Runtime:

launch file demo_pair.launch.py not found

CMakeLists.txt excerpt:

find_package(ament_cmake REQUIRED)
ament_package()

Your job

Identify the missing install rule.

Write the corrected CMake block and the rebuild/source sequence required after the repair.

Do not edit install directly.

Case 3: launch source is newer than installed behavior

Source default:

/robotnix/stale_test

Observed launched topic:

/robotnix/demo

Package prefix resolves correctly.

The launch directory install rule is present.

Your job

Name the failure class.

Write the smallest repair sequence.

Explain why the shell overlay can be correct while the installed resource is still stale.

Case 4: both nodes launch, communication path is split

Observed nodes:

/talker_demo
/listener_demo

Observed node relationships:

/talker_demo publishes /robotnix/demo
/listener_demo subscribes /chatter

Your job

Identify the runtime configuration defect.

Write the launch-file repair and the evidence you would collect after rebuilding/relaunching.

Your verification must include endpoint counts or node-info relationships, not only node names.

Case 5: ROS bringup works, Java integration claim is unsupported

Supplied ROS evidence:

/talker_demo visible
/listener_demo visible
/robotnix/demo publisher 1
/robotnix/demo subscriber 1
one std_msgs/msg/String message observed

Supplied Java evidence:

ObstacleGuard JUnit suite PASSED

A teammate writes:

The Java robot application is connected to ROS and the full system is working.

Your job

Repair the claim.

Then create a Java-to-ROS Integration Contract containing:

  • Java/WPILib runtime responsibility;
  • ROS runtime responsibility;
  • future bridge/adapter responsibility;
  • one proposed data item;
  • units/type/freshness requirement;
  • source of truth;
  • evidence required on both sides before calling the integration demonstrated.

Do not select a pretend Java ROS client library just to make the table complete.

Build the final Repeatable Startup Runbook

Your runbook must begin from a fresh shell and include:

Environment assumptions

Ubuntu 24.04
ROS 2 Jazzy
workspace ~/robot_ws
package robotnix_bringup

Build/update phase

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

Include the expected build evidence.

Fresh-shell runtime setup

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

Package verification

ros2 pkg prefix robotnix_bringup

State the expected workspace prefix.

Launch

ros2 launch robotnix_bringup demo_pair.launch.py

Second-shell verification

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

State expected node names, topic type, and endpoint counts.

Optional override

Document:

topic_name:=/robotnix/test

and the expected runtime difference.

Shutdown

Document Ctrl+C in the launch terminal and the post-stop node check.

Fault-isolation table

Include at least these symptoms:

ros2 command not found
bringup package not found
wrong package prefix
launch file not found
runtime dependency missing
one node missing
wrong topic/remap
stale installed launch resource

Each row must name the first useful check, not a guaranteed one-line fix.

Java/WPILib boundary

End with:

This runbook starts and verifies the ROS 2 bringup only.
It does not build, start, or prove integration with a WPILib Java application.

You may rewrite the wording, but preserve the technical boundary.

Success criteria

Your Unit 7 evidence is complete when another student can:

  • identify source, build/install, shell, launch, and graph layers;
  • rebuild only when source/install evidence requires it;
  • recover a missing overlay without destroying a good build;
  • verify the intended package prefix;
  • install and locate the launch file;
  • detect stale installed resources;
  • detect a one-sided topic remap;
  • run the bringup from a clean shell;
  • verify the runtime from a second shell;
  • explain why healthy Java and ROS runtimes are not automatically integrated.

The final runbook should reduce hidden state, not document every command you happened to type while debugging.