docs(tutorials): add Navigate Through Poses tutorial and improve its BT behavior-tree explanation by FelixZF-Happy · Pull Request #880 · ros-navigation/docs.nav2.org

FelixZF-Happy · 2026-02-23T01:54:13Z

…BT behavior-tree explanation

Basic Info

Info	Please fill out this column
Ticket(s) this addresses	(#172 )
Does this PR contain AI-generated software?	(Yes, all python and C++ codes)

Description of contribution in a few bullet points

The BT behavior-tree explanation was refreshed to match the current
navigate_through_poses_w_replanning_and_recovery.xml flow.
This tutorial now includes TB4 minimal simulation examples in three forms:
CLI, C++, and Python.

SteveMacenski · 2026-02-26T19:11:35Z

   docs/navigation2_with_gps.rst
   docs/using_isaac_perceptor.rst
   docs/navigation2_with_semantic_segmentation.rst
+   docs/navigate_through_poses.rst


Move this above the issac perceptor, its a more 'core' intro thing

I don't think this is in the index anymore?

The title has been updated to "Navigating with Pose Constraints (Navigate Through Poses)" as you suggested earlier. I’ve also moved it above Isaac Perceptor. After clearing the webpage cache, it now appears in the correct order. I’ll review a few other tutorials to align with the style.

SteveMacenski · 2026-02-26T19:13:10Z

+- Ubuntu 24.04, ROS 2 Jazzy, Kilted or later, and Nav2 is installed.
+- The ``nav2_minimal_turtlebot_simulation`` `repository <https://github.com/ros-navigation/nav2_minimal_turtlebot_simulation>`_
+  is included in the ROS 2 system install, no need to build or source it separately.
+- Understand the ``navigate_through_poses_w_replanning_and_recovery.xml`` `behavior tree <https://docs.nav2.org/behavior_trees/trees/nav_through_poses_recovery.html>`_.


Isn't this going to go over that? 🙃

SteveMacenski · 2026-02-26T19:13:16Z

+- The ``nav2_minimal_turtlebot_simulation`` `repository <https://github.com/ros-navigation/nav2_minimal_turtlebot_simulation>`_
+  is included in the ROS 2 system install, no need to build or source it separately.
+- Understand the ``navigate_through_poses_w_replanning_and_recovery.xml`` `behavior tree <https://docs.nav2.org/behavior_trees/trees/nav_through_poses_recovery.html>`_.
+- Familiar with ROS 2 actions and `NavigateThroughPoses.action <https://github.com/ros-navigation/navigation2/blob/main/nav2_msgs/action/NavigateThroughPoses.action>`_ definition.


SteveMacenski · 2026-02-26T19:13:55Z

+- Understand the ``navigate_through_poses_w_replanning_and_recovery.xml`` `behavior tree <https://docs.nav2.org/behavior_trees/trees/nav_through_poses_recovery.html>`_.
+- Familiar with ROS 2 actions and `NavigateThroughPoses.action <https://github.com/ros-navigation/navigation2/blob/main/nav2_msgs/action/NavigateThroughPoses.action>`_ definition.
+
+Start TB4 simulation


Before jumping in, you should talk about what even is navigating through poses, why you might want to do it, a little on the action definition, and the example behavior tree using it. Motivate the subject :-)

SteveMacenski · 2026-02-26T19:14:31Z

+   ros2 launch nav2_minimal_tb4_sim simulation.launch.py
+
+This uses ``nav2_minimal_tb4_sim/launch/simulation.launch.py`` and spawns TB4 in Gazebo.
+
+Start Nav2 stack
+================
+
+Terminal 2:
+
+.. code-block:: bash
+
+   ros2 launch nav2_bringup bringup_launch.py use_sim_time:=True slam:=True autostart:=True


Use the Nav2 bringup for TB3/4. You don't need to separate these.

SteveMacenski · 2026-02-26T19:15:20Z

+
+- This repository provides simulation + robot model + BT navigator source.
+- Full navigation servers (planner, controller, recoveries, lifecycle) come from Nav2.
+- ``slam:=True`` is used so ``slam_launch.py`` starts and provides map creation + localization in a
+  fresh simulation. With ``slam:=False``, Nav2 runs ``localization_launch.py`` and expects
+  ``map:=...`` to be provided.
+
+If you already have a map, prefer:
+
+.. code-block:: bash
+
+   ros2 launch nav2_bringup bringup_launch.py use_sim_time:=True slam:=False map:=/path/to/map.yaml autostart:=True
+
+- ``autostart:=True`` brings Nav2 lifecycle nodes up automatically so the
+  ``navigate_through_poses`` action server is available. See also
+  `example_nav_through_poses.py <https://github.com/ros-navigation/navigation2/blob/main/nav2_simple_commander/nav2_simple_commander/example_nav_through_poses.py>`_.
+


This is after the navigation + slam tutorials, so you don't need to explain this again, I don't think. Stay focused on the details of this tutorial and these concepts

SteveMacenski

A video at the end showing this at work would be nice (using Smac Planner so its continuous).

A good first go, but I'd recommend reading the other tutorials at the start / getting started and try to mirror those styling more. I really appreciate your time and effort though!

SteveMacenski · 2026-02-26T19:17:01Z

+Send a goal
+===========
+
+Method 1: Using terminal command line


Remove the CLI/C++ and only have the python version, lets keep this concise

SteveMacenski · 2026-02-26T19:17:45Z

+Version note (as of February 22, 2026):
+
+- Upstream ``navigation2`` branch heads differ in
+  ``nav2_simple_commander/nav2_simple_commander/robot_navigator.py``:
+  ``jazzy`` and ``kilted`` still show
+  ``self.info(f'Navigating with {len(goal_msg.poses)} goals....')``,
+  while Rolling development (``main``) shows
+  ``self.info(f'Navigating with {len(poses.goals)} goals....')``.
+- If your installed package still has ``len(goal_msg.poses)``, you can
+  temporarily comment out that log line or change it to ``len(poses.goals)``.
+- Some binary installs or local edits may already include this fix. Verify your
+  local ``robot_navigator.py`` before editing.
+


SteveMacenski · 2026-02-26T19:18:24Z

+Run:
+
+.. code-block:: bash
+
+   chmod +x ~/tb4_sim_ws/go_through_poses.py
+   source /opt/ros/kilted/setup.bash
+   source ~/tb4_sim_ws/install/setup.bash
+   python3 ~/tb4_sim_ws/go_through_poses.py
+


SteveMacenski · 2026-02-26T19:18:33Z

+Source code quick walkthrough
+=============================


I dont' think this needs to be another section

SteveMacenski · 2026-02-26T19:19:03Z

+    Verify your installed file first, for example:
+    ``rg -n "Navigating with .*goals" /opt/ros/$ROS_DISTRO/lib/python*/site-packages/nav2_simple_commander/robot_navigator.py``.
+    If your installed file still has ``len(goal_msg.poses)``, temporarily comment
+    out that log line or change it to ``len(poses.goals)``.


Remove -- lets keep this concise

SteveMacenski · 2026-02-26T19:19:36Z

+   from nav2_simple_commander.robot_navigator import BasicNavigator, TaskResult
+
+
+   def make_pose(navigator: BasicNavigator, x: float, y: float, w: float = 1.0) -> PoseStamped:


You could just pass in the timestamp to use instead :-)

SteveMacenski · 2026-04-08T19:21:15Z

@FelixZF-Happy any update?

FelixZF-Happy · 2026-04-08T19:37:14Z

Hi Steve,
I’ll push a commit tonight incorporating all of your recommended deletions. I’ll revisit the remaining things based on your two suggestions after April 14th, and will complete them the following week. I am not busy then from the mid April. Just a few days to sort out some things urgent. But if someone want to continue to finish it this week. I am perfectly ok with that.

SteveMacenski · 2026-04-16T19:44:45Z

Let me know when you're ready! ❤️

FelixZF-Happy · 2026-04-16T20:48:31Z

I’ll set the deadline for this second modification to Sunday for sure. I’ll try to have it ready by Saturday.

…BT behavior-tree explanation Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

…ndex. Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

… with waypoint Follower. Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

…ac Planner, Demo Video. Sample script is fixed. Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

FelixZF-Happy · 2026-04-20T06:56:51Z

Hi Steve,

I added a new tutorial update for NavigateThroughPoses.

A few notes on what changed:

Added a brief overview of what “navigate through poses” means and when to use it.
Added a comparison with Waypoint Follower / GPS waypoint following. The main distinction is that Waypoint Follower treats each waypoint as a destination where the robot may stop or run waypoint tasks, while NavigateThroughPoses treats the poses as constraints along one continuous navigation task.
Added a very short explanation of the NavigateThroughPoses action definition, including its goal, result, and feedback messages, with links to the API docs.
Added a behavior tree overview and linked to the full NavigateThroughPoses recovery BT documentation.
Added a Smac Planner section showing how to copy the default nav2_params.yaml, and remap the default GridBased planner from NavFn to nav2_smac_planner::SmacPlanner2D.
Cleaned up the TB4 simulation launch instructions to use tb4_simulation_launch.py with a static map and AMCL instead of SLAM, including notes about setting the initial pose in RViz and enabling the Gazebo GUI with headless:=False.
In Python example, feedback logging for estimated time remaining is included.
Added a demo video section. I noticed most tutorial videos are linked through YouTube, so I attach this recorded demo video below, if you prefer to host it that way.

One thing I noticed while recording: if I set a goal very close to the robot’s initial pose, NavigateThroughPoses can appear to stop prematurely. I avoided that in the demo script by choosing goal poses farther from the initial robot pose. I believe a related premature-stop issue may have been fixed earlier this year, around January, but I did not dig into that history deeply for this tutorial. I can talk about it if needed. I know so far Jazzy/Kilted haven't been fixed yet.

Thank you very much!
Best,
Felix

FelixZF-Happy · 2026-04-20T11:38:30Z

NavigateThroughPoses.webm

FelixZF-Happy force-pushed the nav_through_poses_tutorials branch from 8194d61 to a91638f Compare February 23, 2026 01:59

FelixZF-Happy marked this pull request as ready for review February 23, 2026 02:05

FelixZF-Happy changed the title ~~docs(tutorials): add Navigate Through Poses tutorial and improve its …~~ docs(tutorials): add Navigate Through Poses tutorial and improve its BT behavior-tree explanation Feb 23, 2026

SteveMacenski reviewed Feb 26, 2026

View reviewed changes

FelixZF-Happy added 5 commits April 20, 2026 02:40

docs(tutorials): add Navigate Through Poses tutorial and improve its …

9aa1709

…BT behavior-tree explanation Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

Remove C++ codes and CLI and redundant contents.

f10f36f

Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

Put the navigate_through_poses doc in the correct order of tutorial i…

7f6cce9

…ndex. Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

Add section 2 what is navigating through poses and section 3 compared…

502377c

… with waypoint Follower. Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

Described action definition and behavior tree, included links. Add Sm…

b209f52

…ac Planner, Demo Video. Sample script is fixed. Signed-off-by: FelixZF-Happy <felix.zifan.fei@gmail.com>

FelixZF-Happy force-pushed the nav_through_poses_tutorials branch from ce4bf0c to b209f52 Compare April 20, 2026 06:41

		from nav2_simple_commander.robot_navigator import BasicNavigator, TaskResult


		def make_pose(navigator: BasicNavigator, x: float, y: float, w: float = 1.0) -> PoseStamped:

Conversation

FelixZF-Happy commented Feb 23, 2026

Basic Info

Description of contribution in a few bullet points

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SteveMacenski Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SteveMacenski left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SteveMacenski commented Apr 8, 2026

Uh oh!

FelixZF-Happy commented Apr 8, 2026

Uh oh!

SteveMacenski commented Apr 16, 2026

Uh oh!

FelixZF-Happy commented Apr 16, 2026

Uh oh!

FelixZF-Happy commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

FelixZF-Happy commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SteveMacenski Feb 26, 2026 •

edited

Loading

SteveMacenski left a comment •

edited

Loading

FelixZF-Happy commented Apr 20, 2026 •

edited

Loading