Know Which Runtime You Are Looking At

Robot software often mixes several layers at once. That is useful, but it also creates a common debugging mistake: evidence from one layer gets treated as proof about another.

This course uses three major software contexts:

1. ordinary Java application code;
2. WPILib robot application code;
3. ROS 2 Jazzy runtime behavior.

A physical robot adds a fourth layer: the hardware itself.

You do not need to memorize a giant architecture diagram. You do need to know which environment produced the evidence in front of you.

Plain Java application code

Consider the method from the previous lesson:

static boolean obstacleTooClose(double rangeMeters) {
  return rangeMeters < 0.30;
}

This is ordinary Java logic.

If you call:

boolean result = obstacleTooClose(0.25);
System.out.println(result);

and the program prints:

true

then you have evidence about that Java execution path.

You know the method received 0.25, evaluated the comparison, and returned true.

You do not know where 0.25 came from unless the program shows that source separately.

WPILib adds a robot application framework

WPILib is a Java-capable framework used to structure FRC robot software.

Later in this course you will work with WPILib ideas such as subsystems, commands, testing, simulation, and data logging. Those features give Java code a robot-application runtime and architecture.

For now, the key point is simple:

WPILib behavior is more than ordinary Java syntax.

A plain method such as obstacleTooClose(...) could be used inside a WPILib subsystem or command, but it does not become part of WPILib simply because the method talks about a robot.

Likewise, a class named DriveMotor is not automatically controlling hardware. Names do not create runtime behavior.

ROS 2 adds a distributed runtime

ROS 2 organizes a running system around nodes and named communication interfaces.

A node is a participant in the ROS graph with a focused responsibility. Nodes can communicate through topics, services, actions, and parameters.

In the controlled graph used in this course, you will see names such as:

/sensor_bridge
/motor_guard

and topics such as:

/scan
/cmd_vel

A command like:

ros2 node list

asks the ROS 2 runtime which node names are visible in the graph.

That is a completely different question from:

java RobotStatus

which launches a Java class.

The commands may appear in the same terminal application, but they inspect different systems.

Compare the evidence directly

Notice how none of the rows automatically proves every row below it.

A Java method can be correct while the ROS graph is broken. A ROS topic can contain messages while a motor controller is disconnected. A motor can move while the software is using the wrong unit.

Good debugging moves through those layers deliberately.

The graph is not the hardware

Suppose you run:

ros2 node list

and see:

/sensor_bridge
/motor_guard

A tempting conclusion is:

The sensor and motor system are working.

That statement is too large.

The node list tells you that the graph contains those node names at the moment you inspected it.

It does not tell you:

• whether /sensor_bridge is receiving valid sensor data;
• whether /motor_guard is receiving fresh messages;
• whether /cmd_vel contains a useful command;
• whether a motor controller accepted the command;
• whether the physical mechanism moved correctly.

To answer those questions, you need more specific evidence.

A Java object is not a ROS node

This mistake is common enough to make explicit.

If you write:

class MotorGuard {
  static boolean allowMovement(double rangeMeters) {
    return rangeMeters >= 0.30;
  }
}

that class is not a ROS 2 node.

It does not publish, subscribe, join the ROS graph, provide a service, expose a parameter, or use a ROS client library.

The fact that its name resembles /motor_guard does not connect the two.

Integration requires actual software that bridges the application logic and ROS runtime.

Later in the course, you will design that boundary explicitly rather than pretending it already exists.

What a careful incident report sounds like

Weak report:

Java says ready and the ROS nodes are there, so the robot is fine.

Stronger report:

RobotStatus executed and printed status=READY. The inspected ROS graph also showed /sensor_bridge and /motor_guard. No evidence in these records demonstrates that the Java program produced the ROS nodes or that physical hardware responded.

The second report may sound less exciting, but it is much more useful. Another engineer knows exactly what has been checked and what remains unknown.

Practice: classify the evidence

For each item, identify the layer that produced it and write one thing it does not prove.

1. javac RobotStatus.java returns without an error.
2. needsCharge(18) returns true.
3. a WPILib test reports 1 test successful.
4. ros2 node list contains /sensor_bridge.
5. /scan appears in ros2 topic list.
6. a wheel encoder reports 420 counts.
7. a student sees the wheel turn.

Do not use the answer “robot system” for all seven. Name the specific evidence source.

In the next lesson, you will use the course terminal to inspect the ROS side directly and build a small graph evidence record.