4. Command-line tools

These answer the question “what is the system doing right now” without editing code and without stopping anything.

Important

This matters more than it looks. When real hardware will not move, someone fluent with these finds the cause in five minutes. Someone who is not will guess between a bad cable, a bad drive, and bad code.

Inspecting topics

Command	Answers
`ros2 topic list`	What channels exist
`ros2 topic echo /name`	What the data looks like
`ros2 topic info /name`	Who publishes, who subscribes
`ros2 topic info -v /name`	The above plus QoS settings ← important
`ros2 topic hz /name`	How many messages per second
`ros2 topic pub`	Inject data yourself to test

`ros2 topic hz` — the one to reach for most

ros2 topic hz /scan

average rate: 9.998
	min: 0.099s max: 0.101s std dev: 0.00047s window: 10

average rate gives the frequency, but the number to read is max.

Warning

🔴 Averages hide stalls very effectively.

A LiDAR that should run at 10 Hz averaging 9.9 looks fine. But if max: 0.8s, there was a 0.8 second gap — long enough for the robot to drive past where it should have stopped.

Use a longer window to see more:

ros2 topic hz /scan --window 50

`ros2 topic pub` — test without writing code

Drive the turtle without teleop:

ros2 topic pub /turtle1/cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 1.0}, angular: {z: 0.0}}"

Ctrl+C to stop (it repeats), or add --once to send a single message.

Danger

On a real robot this command is dangerous. It bypasses every safety layer above it — both the speed limiter and the obstacle-based stop.

If you use it on real hardware, lift the wheels off the ground first and know where the emergency stop is.

Inspecting nodes

ros2 node list
ros2 node info /turtlesim

ros2 node info lists everything a node publishes, subscribes to, and offers as services and parameters.

Reading and changing settings

ros2 param list                              # what can be set
ros2 param get /turtlesim background_b       # read one
ros2 param set /turtlesim background_b 255   # change it live

The turtle’s background changes immediately, with no restart.

Note

Values set this way are lost when the program exits. To make them permanent you need a YAML file, covered in topic 7.

The upside is speed while tuning — change and see the result instantly, no rebuild.

`rqt_graph` — the picture

rqt_graph

You get a diagram of which node connects to which topic, with arrows showing direction.

Tip

Use it to find the missing arrow. Two nodes floating with no line between them, when they should be talking, means the topic names do not match — the trap from the previous topic.

If you see nothing at all, press refresh at the top left and choose Nodes/Topics (all) in the dropdown.

`ros2 bag` — record for later

ros2 bag record /turtle1/cmd_vel /turtle1/pose    # selected topics
ros2 bag record -a                                # everything
ros2 bag play rosbag2_2026_09_01-10_30_00          # replay
ros2 bag info rosbag2_2026_09_01-10_30_00          # what is inside

Important

Invaluable for faults that happen rarely — a robot that stutters once every ten minutes. Leave a recording running, and once it happens you can replay it as slowly and as often as you like.

Watch disk space: -a on a robot with LiDAR and a camera can be several GB per minute.

The order to check when “it will not move”

Follow this and you will not have to guess.

ros2 node list          → are the nodes that should exist running?
ros2 topic list         → do the topic names match?
ros2 topic info -v      → Publisher count 0? QoS mismatch?
ros2 topic echo         → is data actually flowing?
ros2 topic hz           → is it steady? read max, not average

Most of the time it ends at step 3 or 4.

Previous: 3. Nodes, topics, messages · Next: 5. Workspaces and your first package