Nav2 Ready v0.1.0 — A CLI readiness checker for custom Nav2 robots

Projects
, , , ,
1

Hi everyone,

I have released Nav2 Ready v0.1.0, an open-source CLI tool that checks whether a custom ROS 2 robot meets the basic runtime prerequisites for using Nav2.

GitHub release:

The problem

Nav2 often works successfully with sample robots such as TurtleBot3, but moving to a custom robot can be difficult.

When navigation does not start correctly, it may not be obvious whether the problem comes from:

  • TF connectivity or frame names

  • Odometry messages

  • LaserScan data

  • The sensor-to-base transform

  • A missing cmd_vel subscriber

  • Nav2 lifecycle states

  • The map to odom transform

  • Inconsistent ROS time settings

Nav2 Ready checks these prerequisites together and reports each result as PASS, WARN, or FAIL, with a possible cause and a suggested next step.

Example

[PASS] TF-001 Odometry transform
       Transform available: base_footprint -> odom

[PASS] ODOM-001 Odometry stream
       Received nav_msgs/msg/Odometry (odom -> base_footprint)

[PASS] SENSOR-001 Obstacle sensor stream
       Received sensor_msgs/msg/LaserScan (frame: base_scan)

[PASS] NAV-001 Nav2 lifecycle
       Required nodes active: behavior_server, bt_navigator,
       controller_server, planner_server

Overall: PASS
8 passed, 0 warned, 0 failed

A typical command is:

ros2 run nav2_ready check \
  --base-frame base_footprint \
  --timeout 5 \
  --ros-args -p use_sim_time:=true

Scope of v0.1.0

The initial release targets ROS 2 Jazzy and supports one obstacle sensor topic per run using either sensor_msgs/msg/LaserScan or sensor_msgs/msg/PointCloud2.

PointCloud2 validation is structural only. It does not diagnose point-cloud quality, filtering, or Nav2 voxel-layer configuration.

It intentionally does not include a GUI, AI-based diagnosis, automatic configuration changes, or support for multiple ROS distributions.

The current goal is to validate whether a small readiness checker like this is useful before expanding its scope.

Feedback wanted

I would especially appreciate feedback from people who have integrated Nav2 with a custom robot:

  1. Would these checks have helped during your Nav2 setup?

  2. Is an important prerequisite missing?

  3. Are any results or suggested actions unclear?

  4. Does the tool produce an incorrect PASS, WARN, or FAIL in your environment?

Please try it and open a GitHub Issue if you encounter a problem:

Thank you!

1 Like
ROS News for the week of September 14th, 2026
2

One small documentation question before trying this: the announcement says v0.1.0 covers LaserScan and excludes PointCloud2, but the current main README lists both and gives a /points example. The README also calls it a development snapshot rather than a released package.

Which version should someone follow for the scope described here? Linking the README at the release tag would make that clearer.

I haven’t run Nav2 Ready, so this is documentation feedback only.

Edit, September 14: the announcement now links to the v0.1.0 release and says that PointCloud2 checks are structural only. That clarifies the announcement scope I was asking about. I still have not run the tool.

3

Thank you for pointing this out. You are correct that the documentation and the announcement were inconsistent.

I checked the released v0.1.0 source again. Both LaserScan and PointCloud2 are supported as obstacle sensor inputs in v0.1.0, with one sensor topic checked per run. PointCloud2 validation is structural only; it does not diagnose point-cloud quality or Nav2 voxel-layer configuration.

Therefore, the statement in the announcement that PointCloud2 was excluded was incorrect. The “development snapshot, not a released package” wording in the README was also left over from before the release.

I have corrected the announcement and clarified the release status in the repository documentation. The v0.1.0 tag remains the authoritative source version:

Thank you again for catching these inconsistencies.

4

Thanks for checking and fixing both. Making the release tag authoritative removes the ambiguity.

One small output suggestion: include the resolved sensor type and topic name in the summary line, for example LaserScan /scan or PointCloud2 /points. When someone pastes a PASS/WARN/FAIL result into an issue, that would make it obvious which input was actually checked without needing their command history.

I still haven’t run v0.1.0, so this is based on the example output and this thread, not runtime experience.

5

Thanks — that is a useful suggestion.

Including the resolved sensor type and topic in the report summary would make pasted output more self-contained, especially when the original command is not available. I’ll keep this as a candidate for a small v0.1.x improvement.

If you have an opportunity to run Nav2 Ready on a ROS 2 Jazzy custom robot, I would also appreciate any feedback on the actual output, including incorrect PASS/WARN/FAIL results or missing checks. A successful result is useful feedback as well.