Nav2が自作ロボットで動かない原因をまとめて診断するCLI「Nav2 Ready」を公開しました

ROS 2 / Nav2では、TurtleBot3などのサンプルロボットではNavigationを動かせても、自作ロボットへ移行すると、どこに問題があるのか分からなくなることがあります。

例えば、次のような状況です。

• TFが存在しない、またはフレーム名がNav2の設定と一致していない
• /odomは存在するが、OdometryのフレームIDが期待と異なる
• LiDARのトピックは存在するが、センサーフレームからRobot Baseまで変換できない
• /cmd_velを受け取るControllerが起動していない
• Nav2のLifecycle Nodeがinactiveのままになっている
• シミュレーション時間とシステム時間が混在している

これらを個別のROS 2コマンドで調べることはできますが、Nav2を利用するための前提条件を一度に確認するには、複数のトピック、TF、Nodeを順番に調査する必要があります。

そこで、自作ロボットがNav2を利用するための基本的な前提条件をまとめて診断するCLIツール、Nav2 Ready v0.1.0をOSSとして公開しました。

• GitHub Release: https://github.com/Issey-Kubota/nav2_ready/releases/tag/v0.1.0
• Repository: https://github.com/Issey-Kubota/nav2_ready
• License: Apache-2.0

Nav2 Readyとは

Nav2 Readyは、実行中のROS 2環境を読み取り、Nav2導入時に確認したい項目をPASS、WARN、FAILで表示するCLIツールです。

診断結果だけでなく、観測した状態、考えられる原因、次に確認する内容も表示します。

ロボットへ速度指令を送信したり、Lifecycleの状態や設定を変更したりすることはありません。

v0.1.0では、以下の8項目を確認します。

ID	確認項目	主な確認内容
ENV-001	ROS 2 Distribution	ROS 2 Jazzyで実行されているか
TF-001	Odometry Transform	Odometry FrameとRobot Base FrameがTFで接続されているか、時刻が古くないか
ODOM-001	Odometry Stream	nav_msgs/msg/Odometryを受信でき、Frame IDやTimestampが妥当か
SENSOR-001	Obstacle Sensor Stream	LaserScanまたはPointCloud2を受信できるか
TF-002	Sensor Transform	Sensor FrameからRobot Base Frameへ変換できるか
CMD-001	Velocity Command Input	cmd_velを受信可能なSubscriberが存在するか
NAV-001	Nav2 Lifecycle	Nav2の主要Lifecycle Nodeがactiveか
TF-003	Global Localization Transform	Nav2実行時にMap FrameとOdometry Frameが接続されているか

対象環境

v0.1.0の対象は、ROS 2 Jazzy / Ubuntu 24.04です。

障害物センサーは、1回の実行につき以下のどちらか1トピックを確認します。

• sensor_msgs/msg/LaserScan
• sensor_msgs/msg/PointCloud2

PointCloud2について確認するのは、メッセージを受信できることや構造などの基本条件です。点群の品質、フィルタリング、Nav2のVoxel Layer設定までは診断しません。

Build

ROS 2 JazzyをSourceした環境で、v0.1.0のタグを取得してBuildします。

source /opt/ros/jazzy/setup.bash
mkdir -p ~/nav2_ready_ws/src
cd ~/nav2_ready_ws/src
git clone --branch v0.1.0 --depth 1 \
  https://github.com/Issey-Kubota/nav2_ready.git nav2_ready
cd ..
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash

基本的な実行方法

Robot Driver、Robot State Publisher、Odometry、障害物センサーなどを起動した状態で実行します。

ros2 run nav2_ready check

デフォルトでは、主に次のTopicとFrameを使用します。

• Odometry Topic: /odom
• Sensor Topic: /scan
• Velocity Topic: /cmd_vel
• Base Frame: base_link
• Odometry Frame: odom
• Map Frame: map

実際のロボット構成と異なる場合は、CLI Optionで変更できます。

例えば、TurtleBot3のJazzy Simulationでbase_footprintを使用し、Simulation Timeを有効にする場合は次のように実行します。

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

3D LiDARなど、PointCloud2のTopicを確認する場合はSensor Topicを指定します。

ros2 run nav2_ready check --sensor-topic /points

利用可能なTopic、Frame、Namespace、TimeoutのOptionは--helpで確認できます。

ros2 run nav2_ready check --help

実行結果の例

ROS 2 JazzyのTurtleBot3 Nav2 Simulationで、8項目すべてがPASSすることを確認しました。

Nav2 Ready v0.1.0
ROS distribution: jazzy
Observation time: 5.0 sec

[PASS] ENV-001 ROS 2 distribution
       Detected: jazzy

[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] TF-002 Sensor transform
       Transform available: base_scan -> base_footprint

[PASS] CMD-001 Velocity command input
       Compatible subscriber found: geometry_msgs/msg/Twist

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

[PASS] TF-003 Global localization transform
       Transform available: odom -> map

Overall: PASS
8 passed, 0 warned, 0 failed

FAILした場合の表示

例えば、/odomが見つからない場合は次のように表示します。

[FAIL] ODOM-001 Odometry stream
       Topic not found: /odom
       Cause: The odometry publisher may not be running.
       Check: Start the odometry publisher or pass --odom-topic.

この場合、単にFAILとするだけでなく、以下を確認できます。

• 観測結果：/odomが見つからない
• 考えられる原因：Odometry Publisherが起動していない可能性がある
• 次の確認：Publisherを起動するか、実際のTopicを--odom-topicで指定する

一方、Nav2をまだ起動していない場合など、現時点では必ずしも異常とはいえない状態はWARNとして扱います。

Exit Code

実行結果に応じて、以下のExit Codeを返します。

Code	意味
0	全項目がPASS
1	FAILはないが、1件以上のWARNがある
2	1件以上のFAILがある
3	Nav2 Ready自体を正常に実行できなかった

そのため、手動診断だけでなく、Shell ScriptやCIから結果を判定する用途にも利用できます。

現在の対応範囲と今後の候補

v0.1.0では、Nav2導入時に問題を切り分けるための基本的なInterface確認に焦点を絞っています。

現時点では、Nav2 ParameterのTuning、URDF全体のValidation、Costmap設定、点群品質、Navigation性能などの詳細な診断には対応していません。

今後は、実際の自作ロボット環境で寄せられたIssueやフィードバックを基に、例えば以下のような拡張を検討します。

• ROS 2 Jazzy以外のDistribution対応
• 複数の障害物Sensor Topicの確認
• PointCloud2やVoxel Layerに関する詳細な診断
• Nav2 ParameterとTopic／Frame設定の整合性確認
• rosbagを利用したオフライン診断
• 診断対象や結果の出力方法の拡充

これらは現時点で実装を確約するものではありません。実際に困っている内容や利用頻度を確認し、優先度の高いものから判断します。

なお、Nav2 Readyですべての項目がPASSしても、Navigationの正常動作やロボットの安全性を保証するものではありません。Nav2を起動する前後で、基本的なInterfaceの不足箇所を絞り込むためのツールです。

フィードバックを募集しています

Nav2 Readyを実際のCustom Robot環境で利用してもらい、Nav2導入時の問題をより効率的に切り分けられるツールへ改善していきたいと考えています。

特に、以下のフィードバックを募集しています。

• 自作ロボットへのNav2導入時に、この8項目が役立ちそうか
• 不足している重要な前提条件があるか
• 原因や次の確認内容が分かりにくくないか
• 実際の環境で誤ったPASS、WARN、FAILが表示されないか

不具合だけでなく、利用時の質問や自作ロボットでの実行結果もGitHub Issueから共有していただけると助かります。

• Issues: https://github.com/Issey-Kubota/nav2_ready/issues
• ROS Discourse: https://discourse.openrobotics.org/t/nav2-ready-v0-1-0-a-cli-readiness-checker-for-custom-nav2-robots/58095