Skip to content
ros-navigation/navigation2

Partner with Nav2

Sponsorship opportunities & professional services available. Learn More

Behavior-Tree Navigator

Source code on Github.

The BT Navigator (Behavior Tree Navigator) module implements the NavigateToPose, NavigateThroughPoses, and other task interfaces. It is a Behavior Tree-based implementation of navigation that is intended to allow for flexibility in the navigation task and provide a way to easily specify complex robot behaviors, including recovery.

Consider checking out the Groot Tutorials tutorial for using Groot to visualize and modify behavior trees.

Make sure to review all parameters for non-default navigator plugins not discussed on this page (e.g. CoverageNavigator or custom additions).

Parameters

Type: vector<string> Default: ["navigate_to_pose", "navigate_through_poses"]

Plugins for navigator types implementing the nav2_core::BehaviorTreeNavigator interface. They implement custom action servers with custom interface definitions and use that data to populate and process behavior tree navigation requests. Plugin classes are defined under the same namespace, see examples below. Defaults correspond to the NavigateToPoseNavigator and NavigateThroughPosesNavigator navigators.

default_nav_to_pose_bt_xml

Type: string Default: N/A

Path to the default behavior tree XML description for NavigateToPose, see Behavior Tree XML Nodes for details on this file. You can use substitution to specify file path like $(find-pkg-share my_package)/behavior_tree/my_nav_to_pose_bt.xml. However, if left empty, the default behavior tree XML will be loaded from the nav2_bt_navigator package.

default_nav_through_poses_bt_xml

Type: string Default: N/A

Path to the default behavior tree XML description for NavigateThroughPoses, see Behavior Tree XML Nodes for details on this file. You can use substitution to specify file path like $(find-pkg-share my_package)/behavior_tree/my_nav_through_poses_bt.xml. However, if left empty, the default behavior tree XML will be loaded from the nav2_bt_navigator package.

always_reload_bt_xml

Type: bool Default: false

Always load the requested behavior tree XML description, regardless of the name of the currently active XML.

bt_log_idle_transitions

Type: bool Default: true

Whether to log idle (no state change) transitions in the behavior tree to the /behavior_tree_log topic and console output. When false, only state changes are logged, reducing topic and console noise. When true (default), all tick transitions including idle ones are published.

plugin_lib_names

Type: vector<string> Default: [""]

List of behavior tree node shared libraries. All Nav2 BT libraries are automatically included for you, so this only needs to include your new custom plugins.

bt_loop_duration

Type: int Default: 10

Duration (in milliseconds) for each iteration of BT execution.

filter_duration

Type: double Default: 0.3

Duration (secs) over which robot velocity should be smoothed.

default_server_timeout

Type: int Default: 20

Default timeout value (in milliseconds) for a BT action node to wait for acknowledgement from an action server. This value will be overwritten for a BT node if the input port server_timeout is provided.

default_cancel_timeout

Type: int Default: 50

Default timeout (in milliseconds) for BT action node cancellation requests during node halt. This value will be overwritten for a BT node if the input port cancel_timeout is provided.

wait_for_service_timeout

Type: int Default: 1000

Default timeout value (in milliseconds) for an Action or Service BT nodes to wait for acknowledgement from an service or action server on BT initialization (e.g. wait_for_action_server(timeout)). This value will be overwritten for a BT node if the input port wait_for_service_timeout is provided.

introspection_mode

Type: string Default: "disabled"

The introspection mode for services and actions. Options are "disabled", "metadata", "contents".

transform_tolerance

Type: double Default: 0.1 Unit: seconds

TF transform tolerance.

global_frame

Type: string Default: "map"

Reference frame.

robot_base_frame

Type: string Default: "base_link"

Robot base frame.

odom_topic

Type: string Default: "odom"

Topic on which odometry is published

error_code_name_prefixes

Type: vector<string> Default: ["assisted_teleop", "backup", "compute_path", "dock_robot", "drive_on_heading", "follow_path", "nav_thru_poses", "nav_to_pose", "spin", "route", "undock_robot", "wait"]

List of of error code name prefixes to be appended with _error_code and _error_msg and searched for during aborted navigator error processing.

bond_heartbeat_period

Type: double Default: 0.25

The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0.

allow_parameter_qos_overrides

Type: bool Default: true

Whether to allow QoS profiles to be overwritten with parameterized values.

bt_search_directories

Type: vector<string> Default: $(find-pkg-share nav2_bt_navigator)/behavior_trees

List of directories that hosts behavior trees XML files. Used to register all behavior trees and subtrees.

allow_navigator_preemption

Type: bool Default: false

Controls whether a new navigation goal can preempt a currently active navigator. If set to false, if a navigator is already running and a new goal arrives for a different navigator, the new goal is rejected. If set to true, the new goal signals the active navigator to stop, waits for it to finish, then hands control over to the new navigator.

Type: int Default: 500

Only relevant when allow_navigator_preemption is true. Sets the maximum time (in ms) to wait for the currently active navigator to stop. If the active navigator doesn't finish within this timeout, the new goal is rejected.

Type: string Default: "goal"

Blackboard variable to use to supply the goal to the behavior tree for NavigateToPose. Should match ports of BT XML file.

Type: string Default: "path"

Blackboard variable to get the path from the behavior tree for NavigateToPose feedback. Should match port names of BT XML file.

Type: string Default: "tracking_feedback"

Blackboard variable to get the tracking feedback from the behavior tree for NavigateToPose feedback. Should match port names of BT XML file.

Type: bool Default: false

Whether to enable Groot2 monitoring for this navigator.

Type: int Default: 1667

The port number for the Groot2 server.

Note
In Groot2, you only need to specify the server port value, not the publisher port, as it is always the server port +1. Therefore, in this case, to use another navigator, the next available port would be 1669.
Type: double Default: 2.0

How far (in meters) along the path the searching algorithm will look for the closest point.

Type: string Default: "goals"

Blackboard variable to use to supply the goals to the behavior tree for NavigateThroughPoses. Should match ports of BT XML file.

Type: string Default: "path"

Blackboard variable to get the path from the behavior tree for NavigateThroughPoses feedback. Should match port names of BT XML file.

Type: string Default: "tracking_feedback"

Blackboard variable to get the tracking feedback from the behavior tree for NavigateThroughPoses feedback. Should match port names of BT XML file.

Type: string Default: "waypoint_statuses"

Blackboard variable to get the statuses of waypoints from the behavior tree for NavigateThroughPoses feedback/result. Should match ports of BT XML file.

Type: bool Default: false

Whether to enable Groot2 monitoring for this navigator.

Type: int Default: 1669

The port number for the Groot2 server.

Note
In Groot2, you only need to specify the server port value, not the publisher port, as it is always the server port +1. Therefore, in this case, to use another navigator, the next available port would be 1671.
Type: double Default: 2.0

How far (in meters) along the path the searching algorithm will look for the closest point.

Example

bt_navigator:
  ros__parameters:
    global_frame: map
    robot_base_frame: base_link
    transform_tolerance: 0.1
    filter_duration: 0.3
    default_server_timeout: 20
    default_cancel_timeout: 50
    introspection_mode: "disabled"
    default_nav_to_pose_bt_xml: replace/with/path/to/bt.xml # or $(find-pkg-share my_package)/behavior_tree/my_nav_to_pose_bt.xml
    default_nav_through_poses_bt_xml: replace/with/path/to/bt.xml # or $(find-pkg-share my_package)/behavior_tree/my_nav_through_poses_bt.xml
    always_reload_bt_xml: false
    bt_log_idle_transitions: true
    navigators: ['navigate_to_pose', 'navigate_through_poses']
    bt_search_directories:
      - $(find-pkg-share nav2_bt_navigator)/behavior_trees
    navigate_to_pose:
      plugin: "nav2_bt_navigator::NavigateToPoseNavigator"
      enable_groot_monitoring: false
      groot_server_port: 1667
      search_window: 2.0
      goal_blackboard_id: goal
      path_blackboard_id: path
    navigate_through_poses:
      plugin: "nav2_bt_navigator::NavigateThroughPosesNavigator"
      enable_groot_monitoring: false
      groot_server_port: 1669
      search_window: 2.0
      goals_blackboard_id: goals
      path_blackboard_id: path
      waypoint_statuses_blackboard_id: waypoint_statuses

    # plugin_lib_names is used to add custom BT plugins to the executor (vector of strings).
    # Built-in plugins are added automatically
    # plugin_lib_names: []

    error_code_name_prefixes:
      - assisted_teleop
      - backup
      - compute_path
      - dock_robot
      - drive_on_heading
      - follow_path
      - nav_thru_poses
      - nav_to_pose
      - spin
      - route
      - undock_robot
      - wait