# embedding_metadata

key: chroma:document
string_value:
You can see both of these in action in the video above.

Don’t want to call Docking Server from a script Python or C++ script and want to use it in your Autonomous Behavior Tree? Seeopennav_docking_btforDockRobot,UndockRobotBehavior Tree nodes to call the Docking Server from your application behavior tree – with a providedXMLexample.

Note that if usingnavigate_to_staging_pose=True, you cannot callDockRobotfrom inside a Nav2 Behavior Tree, only from your higher level autonomy tree since it recursively calls Nav2.

If you wish to callDockRobotfrom inside your Nav2 BT, you must roughly pre-stage the robot near the dock first (which should be easy as a navigation goal).

However, you can always callUndockRobotfrom any behavior tree!

Happy docking!

Code Examples:

Language: unknown

File: [x,y,theta]

```

docking_server

:

ros__parameters

:

# Types of docks

dock_plugins

:

[

'nova_carter_dock'

]

nova_carter_dock

:

plugin

:

'opennav_docking::SimpleChargingDock'


key: chroma:document
string_value:
:

plugin

:

'opennav_docking::SimpleChargingDock'

# More parameters exist here that we will discuss later in the tutorial

# Dock instances

docks

:

[

'home_dock'

,

'flex_dock1'

,

'flex_dock2'

]

home_dock

:

type

:

'nova_carter_dock'

frame

:

map

pose

:

[

0.0

,

0.0

,

0.0

]

flex_dock1

:

type

:

'nova_carter_dock'

frame

:

map

pose

:

[

10.0

,

10.0

,

0.0

]

flex_dock2

:

type

:

'nova_carter_dock'

frame

:

map

pose

:

[

30.0

,

30.0

,

0.0

]

# Or use

# dock_database: /my/path/to/dock_database.yaml

```

Language: unknown

File: dock_database

```

docks

:

home_dock

:

type

:

"nova_carter_dock"

frame

:

"map"

pose

:

[

0.0

,

0.0

,

0.0

]

flex_dock1

:

type

:

"nova_carter_dock"

frame

:

"map"

pose

:

[

10.0

,

10.0

,

0.0

]

flex_dock2

:

type

:

"nova_carter_dock"

frame

:

"map"

pose

:

[

20.0

,

20.0

,

0.0

]

```

Language: unknown

File: use_battery_status

```

docking_server

:

ros__parameters

:

controller_frequency


key: chroma:document
string_value:
docking_server

:

ros__parameters

:

controller_frequency

:

50.0

initial_perception_timeout

:

5.0

wait_charge_timeout

:

5.0

dock_approach_timeout

:

30.0

undock_linear_tolerance

:

0.05

undock_angular_tolerance

:

0.1

max_retries

:

3

base_frame

:

"base_link"

fixed_frame

:

"odom"

dock_backwards

:

false

dock_prestaging_tolerance

:

0.5

# Types of docks

dock_plugins

:

[

'nova_carter_dock'

]

nova_carter_dock

:

plugin

:

'opennav_docking::SimpleChargingDock'

docking_threshold

:

0.05

staging_x_offset

:

0.7

use_external_detection_pose

:

true

use_battery_status

:

true

use_stall_detection

:

false

external_detection_timeout

:

1.0

external_detection_translation_x

:

0.18

external_detection_translation_y

:

0.0

external_detection_rotation_roll

:

1.57

external_detection_rotation_pitch

:

1.57

external_detection_rotation_yaw

:

0.0

filter_coef

:

0.1

# Sep. file of dock instances so config file can be used in multiple locations

dock_database

:


key: chroma:document
string_value:
dock_database

:

/my/path/to/dock_database.yaml

controller

:

k_phi

:

3.0

k_delta

:

2.0

v_linear_min

:

0.15

v_linear_max

:

0.15

```

Language: unknown

File: use_battery_status

```

nova_carter_dock_params_dir

=

os

.

path

.

join

(

get_package_share_directory

(

'nova_carter_docking'

),

'params'

)

params_file

=

default_value

=

os

.

path

.

join

(

nova_carter_dock_params_dir

,

'nova_carter_docking.yaml'

)

docking_server

=

Node

(

package

=

'opennav_docking'

,

executable

=

'opennav_docking'

,

name

=

'docking_server'

,

output

=

'screen'

,

parameters

=

[

params_file

],

)

```

Language: unknown

File: max_staging_time

```

#goal definition

bool

use_dock_id

True

# Whether to use the dock_id or dock_pose fields

string

dock_id

# Dock name or ID to dock at, from given dock database

geometry_msgs/PoseStamped

dock_pose

# Dock pose

string

dock_type

# If using dock_pose, what type of dock it is. Not necessary if only using one type of dock.


key: chroma:document
string_value:
float32

max_staging_time

1000

.0

# Maximum time for navigation to get to the dock's staging pose.

bool

navigate_to_staging_pose

True

# Whether or not to navigate to staging pose or assume robot is already at staging pose within tolerance to execute behavior

---

#result definition

bool

success

True

# docking success status

uint16

error_code

0

# Contextual error code, if any

uint16

num_retries

0

# Number of retries attempted

---

#feedback definition

uint16

state

# Current docking state

builtin_interfaces/Duration

docking_time

# Docking time elapsed

uint16

num_retries

0

# Number of retries attempted

```

Language: unknown

File: error_code

```

#goal definition

string

dock_type

float32

max_undocking_time

30

.0

# Maximum time to undock

---

#result definition

bool

success

True

# docking success status

uint16

error_code

0

# Contextual error code, if any

---

#feedback definition

```

Language: unknown

File: dock_id

```

def

dockRobot

(

self

,

dock_id


key: chroma:document
string_value:
File: dock_id

```

def

dockRobot

(

self

,

dock_id

=

""

):

"""Send a `DockRobot` action request."""

print

(

"Waiting for 'DockRobot' action server"

)

while

not

self

.

docking_client

.

wait_for_server

(

timeout_sec

=

1.0

):

print

(

'"DockRobot" action server not available, waiting...'

)

goal_msg

=

DockRobot

.

Goal

()

goal_msg

.

use_dock_id

=

True

goal_msg

.

dock_id

=

dock_id

# if wanting to use ID instead

print

(

'Docking at ID: '

+

str

(

dock_id

)

+

'...'

)

send_goal_future

=

self

.

docking_client

.

send_goal_async

(

goal_msg

,

self

.

_feedbackCallback

)

rclpy

.

spin_until_future_complete

(

self

,

send_goal_future

)

self

.

goal_handle

=

send_goal_future

.

result

()

if

not

self

.

goal_handle

.

accepted

:

print

(

'Docking request was rejected!'

)

return

False

self

.

result_future

=

self

.

goal_handle

.

get_result_async

()

return

True

...

dock_id

=

'home_dock'

tester

.

dockRobot

(

dock_id


key: chroma:document
string_value:
Title: Robots Using

URL: https://docs.nav2.org/about/robots.html

Section: getting_started/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
Title: RateController

URL: https://docs.nav2.org/configuration/packages/bt

plugins/decorators/RateController.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: GoalReached

```

<RateController

hz=

"1.0"

>

<!-

Add tree components here--

>

</RateController>

```


key: chroma:document
string_value:
Title: Navigating with a Physical Turtlebot 3 URL: https://docs.nav2.org/tutorials/docs/navigation2_on_real_turtlebot3.html#requirements Section: getting_started/index.html --------------------------------------------------------------------------------

## Overview This tutorial shows how to control and navigate Turtlebot 3 using the ROS 2 Nav2 on a physical Turtlebot 3 robot. Before completing this tutorials, completingGetting Startedis highly recommended especially if you are new to ROS and Nav2. This tutorial may take about 1 hour to complete. It depends on your experience with ROS, robots, and what computer system you have.

## Requirements You must install Nav2, Turtlebot3. If you don’t have them installed, please followGetting Started. The turtlebot3 software can be installed via the following or on theturtlebot3 repository:

## Tutorial Steps

## 0- Setup Your Environment Variables Run the following commands first whenever you open a new terminal during this tutorial.


key: chroma:document
string_value:
## 2- Launch Nav2 You need to have a map of the environment where you want to Navigate Turtlebot 3, or create one live with SLAM. In case you are interested, there is a use case tutorial which shows how to use Nav2 with SLAM.(SLAM) Navigating While Mapping. Required files: <your_map>.yamlis the configuration file for the map we want to provide Nav2. In this case, it has the map resolution value, threshold values for obstacles and free spaces, and a map file location. You need to make sure these values are correct. More information about the map.yaml can be foundhere. Launch Nav2. If you set autostart:=False, you need to click on the start button in RViz to initialize the nodes. Make sureuse_sim timeis set toFalse, because we want to use the system time instead of the time simulation time from Gazebo. ros2launchnav2_bringupbringup_launch.pyuse_sim_time:=Falseautostart:=Falsemap:=/path/to/your-map.yaml Note: Don’t forget to change/path/to/your-map.yamlto the actual path to the your-map.yaml file.


key: chroma:document
string_value:
## 3-  Launch RVIZ Launch RVIZ with a pre-defined configuration file. Now, you should see a shadow of Turtlebot 3 robot model in the center of the plot in Rviz. Click on the Start button (Bottom Left) if you set the auto_start parameter to false. Then, the map should appear in RViz.

## 4- Initialize the Location of Turtlebot 3 First, find where the robot is on the map. Check where your robot is in the room. Set the pose of the robot in RViz. Click on the 2D Pose Estimate button and point the location of the robot on the map. The direction of the green arrow is the orientation of Turtlebot. Now, the 3D model of Turtlebot should move to that location. A small error in the estimated location is tolerable.


key: chroma:document
string_value:
## 5-  Send a Goal Pose Pick a target location for Turtlebot on the map. You can send Turtlebot 3 a goal position and a goal orientation by using theNav2 Goalor theGoalToolbuttons. Note: Nav2 Goal button uses a ROS 2 Action to send the goal and the GoalTool publishes the goal to a topic. Once you define the target pose,  Nav2 will find a global path and start navigating the robot on the map. Now, you can see that Turtlebot 3 moves towards the goal position in the room. See the video below.

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

sudo

apt

install

ros

<ros2

distro>

turtlebot3

ros

<ros2

distro>

turtlebot3

msgs

ros

<ros2

distro>

turtlebot3

bringup

```


key: chroma:document
string_value:
Title: PathAlignCritic

URL: https://docs.nav2.org/configuration/packages/trajectory_critics/path_align.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <name>: PathAlignCritic critic name defined in the<dwb plugin>.criticsparameter defined inDWB Controller.


key: chroma:document
string_value:
Title: Filtering of Noise

Induced Obstacles

URL: https://docs.nav2.org/tutorials/docs/filtering_of_noise

induced_obstacles.html#tutorial

steps

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview Noisy sensor measurements can cause to errors inVoxelLayerorObstacleLayer. As a result, salt and pepper noise may appear on the costmap. This noise creates false obstacles that prevent the robot from finding the best path on the map. While the images above show both salt and pepper noise as well as error due to mislocalization, this layer will only remove sensor noise, not mislocalized artifacts misaligned with the static map. This tutorial shows how to configure filtering of false obstacles caused by noise. This functionality is provided by theDenoiseLayercostmap layer plugin which will be enabled and used in this document.


key: chroma:document
string_value:
## Requirements It is assumed that ROS 2, Gazebo and TurtleBot3 packages are installed or built locally. Please make sure that Nav2 project is also built locally as it was made inBuild and Install.

## Tutorial Steps


key: chroma:document
string_value:
## 1. Enable Denoise Layer Denoise Layer is Costmap2D plugin. You can enable theDenoiseLayerplugin in Costmap2D by addingdenoise_layerto thepluginsparameter innav2_params.yaml. You can place it in theglobal_costmapand (or)local_costmapto filter noise on a global or local map. The DenoiseLayer plugin should have the following parameter defined: Full list of parameters supported byDenoiseLayerare listed atDenoise Layer Parameterspage. It is important to note thatDenoiseLayertypically should be placed before the inflation layer. This is required to prevent inflation from noise-induced obstacles. Moreover,DenoiseLayerprocesses only obstacle information in the costmap. ValuesINSCRIBED_INFLATED_OBSTACLE,LETHAL_OBSTACLEand optionallyNO_INFORMATIONwill be interpreted as obstacle cell. Cells with any other values will be interpreted asFREE_SPACEwhen processed (won’t be distorted in the cost map). If a cell with an obstacle is recognized as noise, it will be replaced byFREE_SPACEafter processing. To


key: chroma:document
string_value:
as noise, it will be replaced byFREE_SPACEafter processing. To enableDenoiseLayerfor both global and local costmaps, use the following configuration:


key: chroma:document
string_value:
## 2. Run Nav2 stack After Denoise Layer was enabled for global/local costmaps, run Nav2 stack as written inGetting Started: And check that filter is working properly: with the default parameters, no standalone obstacles should remain on the cost map. This can be checked, for example, in RViz main window displaying local and global costmaps after removing unnecessary particles (illustrated at the top of this tutorial).


key: chroma:document
string_value:
## How it works The plugin is based on two algorithms. When parameterminimal_group_size= 2, the first algorithm turns on. It applyerosionfunction with kernel from image below (left ifgroup_connectivity_type= 4 or right ifgroup_connectivity_type= 8) to the costmap. White color of the kernel pixel means to use the value, black means to ignore it. As a result of erosion function the neighbors image is created. Each possible position of the kernel on the costmap corresponds to one pixel of the neighbors image. The pixel value of this image is equal to the maximum of 4/8 costmap pixels corresponding to the white pixels of the mask. In other words, the pixel of the neighbors image is equal to the obstacle code if there is an obstacle nearby, the free space code in other case. After that, obstacles corresponding to free space code on neighbors image are removed. This process is illustrated below. On the left side of the image is a costmap, on the right is a neighbors image. White pixels are free space, black


key: chroma:document
string_value:
right is a neighbors image. White pixels are free space, black pixels are obstacles,group_connectivity_type= 4. Obstacles marked at the end of the animation will be removed. When parameterminimal_group_size> 2, the second algorithm is executed. This is a generalized solution that allows you to remove groups of adjacent obstacles if their total number is less thanminimal_group_size. To select groups of adjacent obstacles, the algorithm performs their segmentation. The type of cell connectivity in one segment is determined by the parametergroup_connectivity_type. Next, the size of each segment is calculated. Obstacles segments with size less than theminimal_group_sizeare replaced with empty cells. This algorithm is about 10 times slower than first, so use it with caution and only when necessary. Its execution time depends on the size of the processed map fragment (and not depend on the value ofminimal_group_size). This algorithm is illustrated in the animation below (group_connectivity_type= 8). Obstacles


key: chroma:document
string_value:
in the animation below (group_connectivity_type= 8). Obstacles marked at the end of the animation will be removed (groups that size less 3).


key: chroma:document
string_value:
Code Examples:

Language: unknown File: DenoiseLayer ``` global_costmap: global_costmap: ros__parameters: ... plugins: ["static_layer", "obstacle_layer", "denoise_layer", "inflation_layer"] ... denoise_layer: plugin: "nav2_costmap_2d::DenoiseLayer" enabled: True ... local_costmap: local_costmap: ros__parameters: ... plugins: ["voxel_layer", "denoise_layer", inflation_layer"] ... keepout_filter: plugin: "nav2_costmap_2d::DenoiseLayer" enabled: True

```

Language: unknown

File: DenoiseLayer

```

ros2

launch

nav2_bringup

tb3_simulation_launch.py

headless:

=

False

```


key: chroma:document
string_value:
Title: Foxy to Galactic

URL: https://docs.nav2.org/migration/Foxy.html#removed

bt

xml

launch

configurations

Section: getting_started/index.html

--------------------------------------------------------------------------------

## NavigateToPose Action Feedback updates The NavigateToPose action feedback has two improvements:

## NavigateToPose BT-node Interface Changes The NavigateToPose input port has been changed to PoseStamped instead of Point and Quaternion. SeeNavigateToPosefor more information.


key: chroma:document
string_value:
## NavigateThroughPoses and ComputePathThroughPoses Actions Added TheNavigateThroughPosesaction has been added analog to theNavigateToPose. Rather than going to a single position, this Action will allow a user to specify a number of hard intermediary pose constraints between the start and final pose to plan through. The newComputePathThroughPosesaction has been added to theplanner_serverto process these requests throughNgoal_poses. TheComputePathThroughPosesaction server will take in a set ofNgoals to achieve, plan through each pose and concatenate the output path for use in navigation. The controller and navigator know nothing about the semantics of the generated path, so the robot will not stop or slow on approach to these goals. It will rather continue through each pose as it were any other point on the path continuously. When paired with theSmacPlanner, this feature can be used to generatecompletely kinematically feasible trajectories through pose constraints. If you wish to stop at each goal pose,


key: chroma:document
string_value:
pose constraints. If you wish to stop at each goal pose, consider using the waypoint follower instead, which will stop and allow a user to optionally execute a task plugin at each pose.


key: chroma:document
string_value:
## ComputePathToPose BT-node Interface Changes Thestartinput port has been added to optionally allow the request of a path fromstarttogoalinstead of from the current position of the robot togoal. SeeComputePathToPosefor more information.

## ComputePathToPose Action Interface Changes These two additional fields have been added to optionally allow, whenuse_startis true, the request of a path fromstarttogoalinstead of from the current position of the robot togoal. Corresponding changes have been done of the Planner Server.

## BackUp BT-node Interface Changes Thebackup_distandbackup_speedinput ports should both be positive values indicating the distance to go backward respectively the speed with which the robot drives backward.


key: chroma:document
string_value:
## BackUp Recovery Interface Changes speedin a backup recovery goal should be positive indicating the speed with which to drive backward.target.xin a backup recovery goal should be positive indicating the distance to drive backward. In both cases negative values are silently inverted.


key: chroma:document
string_value:
## Nav2 Controllers and Goal Checker Plugin Interface Changes As ofthis PR 2247, thecontrollerplugins will now be given a pointer to the current goal checker in use of the navigation task incomputeAndPublishVelocity(). This is geared to enabling controllers to have access to predictive checks for goal completion as well as access to the state information of the goal checker plugin. Thegoal_checkerplugins also have the change of including agetTolerances()method. This method allows a goal checker holder to access the tolerance information of the goal checker to consider at the goal. Each field of theposeandvelocityrepresents the maximum allowable error in each dimension for a goal to be considered completed. In the case of a translational tolerance (combined X and Y components), each the X and Y will be populated with the tolerance value because it is themaximumtolerance in the dimension (assuming the other has no error). If the goal checker does not contain any tolerances for a dimension,


key: chroma:document
string_value:
goal checker does not contain any tolerances for a dimension, thenumeric_limits<double>lowest()value is utilized in its place.


key: chroma:document
string_value:
## FollowPath goal_checker_id attribute For example: you could use for some specific navigation motion a more precise goal checker than the default one that it is used in usual motions. Below it is shown an example of goal_checker configuration of the controller_server node.

## Groot Support Live Monitoring and Editing of behavior trees with Groot is now possible. Switching bt-xmls on the fly through a new goal request is also included. This is all done without breaking any APIs. Enabled by default.


key: chroma:document
string_value:
## New Plugins nav2_waypoint_followerhas an action server that takes in a list of waypoints to follow and follow them in order. In some cases we might want robot to perform some tasks/behaviours at arrivals of these waypoints. In order to perform such tasks, a generic plugin interfaceWaypointTaskExecutorhas been added tonav2_core. Users can inherit from this interface to implement their own plugin to perform more specific tasks at waypoint arrivals for their needs. Several example implementations are included innav2_waypoint_follower.WaitAtWaypointandPhotoAtWaypointplusings are included innav2_waypoint_followeras run-time loadable plugins.WaitAtWaypointsimply lets robot to pause for a specified amount of time in milliseconds, at waypoint arrivals. WhilePhotoAtWaypointtakes photos at waypoint arrivals and saves the taken photos to specified directory, the format for taken photos also can be configured through parameters. All major image formats such aspng,jpeg,jpgetc. are supported, the default format ispng.


key: chroma:document
string_value:
aspng,jpeg,jpgetc. are supported, the default format ispng. Loading a plugin of this type is done throughnav2_bringup/params/nav2_param.yaml, by specifying plugin’s name, type and it’s used parameters. Original GitHub tickets:


key: chroma:document
string_value:
## Costmap Filters A new concept interacting with spatial-dependent objects called “Costmap Filters” appeared in Galactic (more information about this concept could be found atNavigation Conceptspage). Costmap filters are acting as a costmap plugins, applied to a separate costmap above common plugins. In order to make a filtered costmap and change robot’s behavior in annotated areas, filter plugin reads the data came from filter mask. Then this data is being linearly transformed into feature map in a filter space. It could be passability of an area, maximum speed limit in m/s, robot desired direction in degrees or anything else. Transformed feature map along with the map/costmap, sensors data and current robot position is used in plugin’s algorithms to make required updates in the resulting costmap and robot’s behavior. Architecturally, costmap filters consists fromCostmapFilterclass which is a basic class incorporating much common of its inherited filter plugins: Each costmap filter subscribes to filter


key: chroma:document
string_value:
filter plugins: Each costmap filter subscribes to filter info topic (publishing byCostmap Filter Info Publisher Server) having all necessary information for loaded costmap filter and filter mask topic.SpeedFilteradditionally publishes maximum speed restrictingmessagestargeted for a Controller to enforce robot won’t exceed given limit. High-level design of this concept could be foundhere. The functionality of costmap filters is being discussed inthe ticket #1263and carried out byPR #1882. The following tutorials:Navigating with Keepout ZonesandNavigating with Speed Limitswill help to easily get involved withKeepoutFilterandSpeedFilterfunctionalities.


key: chroma:document
string_value:
## SmacPlanner A new package,nav2_smac_plannerwas added containing 4 or 8 connected 2D A*, and Dubin and Reed-shepp model hybrid-A* with smoothing, multi-resolution query, and more. Thenav2_smac_plannerpackage contains an optimized templated A* search algorithm used to create multiple A*-based planners for multiple types of robot platforms. We support differential-drive and omni-directional drive robots using theSmacPlanner2Dplanner which implements a cost-aware A* planner. We support cars, car-like, and ackermann vehicles using theSmacPlannerplugin which implements a Hybrid-A* planner. This plugin is also useful for curvature constrained planning, like when planning robot at high speeds to make sure they don’t flip over or otherwise skid out of control. TheSmacPlannerfully-implements the Hybrid-A* planner as proposed inPractical Search Techniques in Path Planning for Autonomous Driving, including hybrid searching, CG smoothing, analytic expansions and heuristic functions.


key: chroma:document
string_value:
## ThetaStarPlanner A new package,nav2_theta_star_plannerwas added containing 4 or 8 connected Theta* implementation for 2D maps. This package implements an optimized version of the Theta* Path Planner (specifically theLazy Theta* Pvariant) to plan any-angled paths for differential-drive and omni-directional robots, while also taking into account the costmap costs. This plugin is useful for the cases where you might want to plan a path at a higher rate but without requiring extremely smooth paths around the corners which, for example, could be handled by a local planner/controller.


key: chroma:document
string_value:
## RegulatedPurePursuitController A new package,nav2_regulated_pure_pursuit_controllerwas added containing a novel variant of the Pure Pursuit algorithm. It also includes configurations to enable Pure Pursuit and Adaptive Pure Pursuit variations as well. This variation is specifically targeting service / industrial robot needs. It regulates the linear velocities by curvature of the path to help reduce overshoot at high speeds around blind corners allowing operations to be much more safe. It also better follows paths than any other variation currently available of Pure Pursuit. It also has heuristics to slow in proximity to other obstacles so that you can slow the robot automatically when nearby potential collisions. It also implements the Adaptive lookahead point features to be scaled by velocities to enable more stable behavior in a larger range of translational speeds. There’s more this does, that that’s the general information. See the package’sREADMEfor more.


key: chroma:document
string_value:
## Costmap2Dcurrent_Usage In costmap2D,current_was used in ROS1 to represent whether a costmap layer was still enabled and actively processing data. It would be turned tofalseonly under the situation that the expected update rate of a sensor was not met, so it was getting stale or no messages. It acts as a fail-safe for if a navigation sensor stops publishing. In galactic, that will remain turn, however it will also add additional capabilities. It is also now set tofalsewhen a costmap is reset due to clearing or other navigation recoveries. That stops the robot from creating a plan or control effort until after the costmap has been updated at least once after a reset. This enables us to make sure we cannot ever create a path or control with a completely empty costmap, potentially leading to collisions, due to clearing the costmap and then immediately requesting an algorithm to run.


key: chroma:document
string_value:
## Standard time units in parameters To follow the SI units outlined in REP-103 to the “T” nodes below were modified to use seconds consistently in every parameter. Under each node name you can see which parameters changed to seconds instead of using milliseconds.

## Ray Tracing Parameters Raytracing functionality was modified to include a minimum range parameter from which ray tracing starts to clear obstacles to avoid incorrectly clearing obstacles too close to the robot. This issue was mentioned inROS Answers. An existing parameterraytrace_rangewas renamed toraytrace_max_rangeto reflect the functionality it affects. The renamed parameters and the plugins that they belong to are mentioned below. The changes were introduced in thispull request.


key: chroma:document
string_value:
## Obstacle Marking Parameters Obstacle marking was modified to include a minimum range parameter from which obstacles are marked on the costmap to prevent addition of obstacles in the costmap due to noisy and incorrect measurements. This modification is related to the change with the raytracing parameters. The renamed parameters, newly added parameters and the plugins they belong to are given below.

## Recovery Action Changes The recovery actions,SpinandBackUpwere modified to correctly returnFAILUREif the recovery action is aborted due to a potential collision. Previously, these actions incorrectly always returnedSUCCESS. Changes to this resulted in downstream action clients, such as the default behavior tree. The changes were introduced in thispull request 1855.


key: chroma:document
string_value:
## Default Behavior Tree Changes The default behavior tree (BT)navigate_w_replanning_and_recovery.xmlhas been updated to allow for replanning in between recoveries. The changes were introduced in thisPR 1855. Additionally, an alternative BTnavigate_w_replanning_and_round_robin_recovery.xmlwas removed due to similarity with the updated default BT.

## NavFn Planner Parameters The NavFn Planner has now its 3 parameters reconfigurable at runtime (tolerance,use_astarandallow_unknown). The changes were introduced in thispull request 2181.


key: chroma:document
string_value:
## New ClearCostmapExceptRegion and ClearCostmapAroundRobot BT-nodes The ClearEntireCostmap action node was already implemented but the ClearCostmapExceptRegion and ClearCostmapAroundRobot BT nodes calling the sister services(local_or_global)_costmap/clear_except_(local_or_global)_costmapandclear_around_(local_or_global)_costmapof Costmap 2D were missing, they are now implemented in a similar way. They both expose areset_distanceinput port. SeeClearCostmapExceptRegionandClearCostmapAroundRobotfor more.  The changes were introduced in thispull request 2204.


key: chroma:document
string_value:
## New Behavior Tree Nodes A new behavior tree node was added and dynamically loadable at run-time using behavior tree cpp v3. Seenav2_behavior_treefor a full listing, orNavigation Pluginsfor the current list of behavior tree plugins and their descriptions. These plugins are set as default in thenav2_bt_navigatorbut may be overridden by thebt_pluginsparameter to include your specific plugins. Original GitHub tickets: Additionally, behavior tree nodes were modified to contain their own local executors to spin for actions, topics, services, etc to ensure that each behavior tree node is independent of each other (e.g. spinning in one BT node doesn’t trigger a callback in another).

## sensor_msgs/PointCloud to sensor_msgs/PointCloud2 Change Due to deprecation ofsensor_msgs/PointCloudthe topics which were publishing sensor_msgs/PointCloud are converted to sensor_msgs/PointCloud2. The details on these topics and their respective information are listed below. These changes were introduced inpull request 2263.


key: chroma:document
string_value:
## ControllerServer New Parameter failure_tolerance A new parameterfailure_tolerancewas added to the Controller Server for tolerating controller plugin exceptions without failing immediately. It is analogous tocontroller_patiencein ROS(1) Nav. SeeController Serverfor description. This change was introduced in thispull request 2264.

## Removed BT XML Launch Configurations The launch python configurations for CLI setting of the behavior tree XML file has been removed. Instead, you should use the yaml files to set this value. If you, however, have apathto the yaml file that is inconsistent in a larger deployment, you can use theRewrittenYamltool in your parent launch file to remap the default XML paths utilizing theget_shared_package_path()directory finder (or as you were before in python3). The use of map subscription QoS launch configuration was also removed, use parameter file. This change was introduced in thispull request 2295.


key: chroma:document
string_value:
## Nav2 RViz Panel Action Feedback Information The Nav2 RViz Panel now displays the action feedback published bynav2_msgs/NavigateToPoseandnav2_msgs/NavigateThroughPosesactions. Users can find information like the estimated time of arrival, distance remaining to goal, time elapsed since navigation started, and number of recoveries performed during a navigation action directly through the RViz panel. This feature was introduced in thispull request 2338.

Code Examples:

Language: unknown

File: numeric_limits<double>lowest()

```

<FollowPath

path=

"{path}"

controller_id=

"FollowPath"

goal_checker_id=

"precise_goal_checker"

server_name=

"FollowPath"

server_timeout=

"10"

/>

```

Language: unknown

File: GridBased

```

controller_server

:

ros__parameters

:

goal_checker_plugins

:

[

"general_goal_checker"

,

"precise_goal_checker"

]

precise_goal_checker

:

plugin

:

"nav2_controller::SimpleGoalChecker"

xy_goal_tolerance

:

0.25

yaw_goal_tolerance

:

0.25

general_goal_checker

:


key: chroma:document
string_value:
:

0.25

yaw_goal_tolerance

:

0.25

general_goal_checker

:

plugin

:

"nav2_controller::SimpleGoalChecker"

xy_goal_tolerance

:

0.25

```

Language: unknown

File: nav2_bringup/params/nav2_param.yaml

```

waypoint_follower

:

ros__parameters

:

loop_rate

:

20

stop_on_failure

:

false

waypoint_task_executor_plugin

:

"wait_at_waypoint"

wait_at_waypoint

:

plugin

:

"nav2_waypoint_follower::WaitAtWaypoint"

enabled

:

True

waypoint_pause_duration

:

0

```


key: chroma:document
string_value:
Title: Voxel Layer Parameters

URL: https://docs.nav2.org/configuration/packages/costmap

plugins/voxel.html

Section: getting_started/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
Title: NavFn Planner

URL: https://docs.nav2.org/configuration/packages/configuring

navfn.html#parameters

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

## Example

Code Examples:

Language: unknown File: <name> ``` planner_server : ros__parameters : planner_plugins : [ 'GridBased' ] GridBased : plugin : 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::" use_astar : True allow_unknown : True tolerance : 1.0 ```


key: chroma:document
string_value:
Title: GoalAlignCritic

URL: https://docs.nav2.org/configuration/packages/trajectory_critics/goal_align.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <dwbplugin>: DWB plugin name defined in thecontroller_plugin_idsparameter inController Server. <name>: GoalAlignCritic critic name defined in the<dwb plugin>.criticsparameter defined inDWB Controller.


key: chroma:document
string_value:
Title: SimpleGoalChecker

URL: https://docs.nav2.org/configuration/packages/nav2_controller

plugins/simple_goal_checker.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <nav2_controllerplugin>: nav2_controller plugin name defined in thegoal_checker_plugin_idparameter inController Server.


key: chroma:document
string_value:
Title: AMCL

URL: https://docs.nav2.org/configuration/packages/configuring-amcl.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

## Example

Code Examples:

Language: unknown

File: first_map_only_

```

amcl

:

ros__parameters

:

alpha1

:

0.2

alpha2

:

0.2

alpha3

:

0.2

alpha4

:

0.2

alpha5

:

0.2

base_frame_id

:

"base_footprint"

beam_skip_distance

:

0.5

beam_skip_error_threshold

:

0.9

beam_skip_threshold

:

0.3

do_beamskip

:

false

global_frame_id

:

"map"

lambda_short

:

0.1

laser_likelihood_max_dist

:

2.0

laser_max_range

:

100.0

laser_min_range

:

1.0

laser_model_type

:

"likelihood_field"

max_beams

:

60

max_particles

:

2000

min_particles

:

500

odom_frame_id

:

"odom"

pf_err

:

0.05

pf_z

:

0.99

recovery_alpha_fast

:

0.0

recovery_alpha_slow

:

0.0

resample_interval

:

1

robot_model_type

:

"nav2_amcl::DifferentialMotionModel"

save_pose_rate

:

0.5


key: chroma:document
string_value:
"nav2_amcl::DifferentialMotionModel"

save_pose_rate

:

0.5

sigma_hit

:

0.2

tf_broadcast

:

true

transform_tolerance

:

1.0

update_min_a

:

0.2

update_min_d

:

0.25

z_hit

:

0.5

z_max

:

0.05

z_rand

:

0.5

z_short

:

0.05

scan_topic

:

scan

map_topic

:

map

set_initial_pose

:

false

always_reset_initial_pose

:

false

first_map_only

:

false

initial_pose

:

x

:

0.0

y

:

0.0

z

:

0.0

yaw

:

0.0

```


key: chroma:document
string_value:
Title: Map Server / Saver URL: https://docs.nav2.org/configuration/packages/configuring-map-server.html#map-saver-parameters Section: getting_started/index.html --------------------------------------------------------------------------------

## Map Saver Parameters

## Map Server Parameters

## Costmap Filter Info Server Parameters

## Example

Code Examples:

Language: unknown

File: filter_space_value=base+multiplier

mask_value

```

map_server

:

ros__parameters

:

yaml_filename

:

"turtlebot3_world.yaml"

topic_name

:

"map"

frame_id

:

"map"

map_saver

:

ros__parameters

:

save_map_timeout

:

5.0

free_thresh_default

:

0.25

occupied_thresh_default

:

0.65

costmap_filter_info_server

:

ros__parameters

:

type

:

1

filter_info_topic

:

"costmap_filter_info"

mask_topic

:

"filter_mask"

base

:

0.0

multiplier

:

0.25

```


key: chroma:document
string_value:
Title: ComputePathThroughPoses

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/ComputePathThroughPoses.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: ComputePathThroughPoses

```

<ComputePathThroughPoses

goals=

"{goals}"

path=

"{path}"

planner_id=

"GridBased"

server_name=

"ComputePathThroughPoses"

server_timeout=

"10"

error_code_id=

"{compute_path_error_code}"

/>

```


key: chroma:document
string_value:
Title: OscillationCritic

URL: https://docs.nav2.org/configuration/packages/trajectory_critics/oscillation.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <dwbplugin>: DWB plugin name defined in thecontroller_plugin_idsparameter inController Server. <name>: OscillationCritic critic name defined in the<dwb plugin>.criticsparameter defined inDWB Controller.


key: chroma:document
string_value:
Title: IsPathValid

URL: https://docs.nav2.org/configuration/packages/bt

plugins/conditions/IsPathValid.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<IsPathValid

server_timeout=

"10"

path=

"{path}"

/>

```


key: chroma:document
string_value:
Title: Development Guides

URL: https://docs.nav2.org/development_guides/index.html

Section: development_guides/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
Title: IsBatteryCharging

URL: https://docs.nav2.org/configuration/packages/bt

plugins/conditions/IsBatteryCharging.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Example

Code Examples:

Language: unknown

File: POWER_SUPPLY_STATUS_CHARGING

```

<IsBatteryCharging

battery_topic=

"/battery_status"

/>

```


key: chroma:document
string_value:
Title: ClearEntireCostmap

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/ClearEntireCostmap.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<ClearEntireCostmap

name=

"ClearLocalCostmap

Subtree"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

```


key: chroma:document
string_value:
Title: Navigating Using GPS Localization

URL: https://docs.nav2.org/tutorials/docs/navigation2_with_gps.html#interactive-gps-waypoint-follower

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview

This tutorial shows how to set up a localization system using a GPS sensor(s) as the source of global positioning, robot_localization (RL) for sensor fusion, and how to use Nav2 to follow GPS waypoints. It was written by Pedro Gonzalez atKiwibot.

## Requirements

It is assumed ROS2 and Nav2 dependent packages are installed or built locally. Additionally you will have to install robot_localization and mapviz:

The code for this tutorial is hosted onnav2_gps_waypoint_follower_demo. Though we will go through the most important steps of the setup, it’s highly recommended that you clone and build the package when setting up your dev environment.

This is available in ROS 2 Iron and newer.


key: chroma:document
string_value:
This is available in ROS 2 Iron and newer.

You may also need to install gazebo and turtlebot3 simulation if you have not executed previous tutorials or Nav2 demos. See Nav2’s Getting Started page for more information.

## GPS Localization Overview

GPS (Global Positioning System) or more broadly GNSS (Global Navigation Satellite System) is a technology that relies on satellites to provide receivers with an estimate of where they are located on the earth. These satellites are in orbit at altitudes around 20.000km and use radio frequency to continuously broadcast time signals, these are picked up by receivers when satellites are along their line of sight, they use trilateration to estimate their latitude, longitude and altitude.

Commonly GPS devices calculate their position using theWGS84 standard, which defines a cartesian system with its origin on the earth’s center of mass, thezaxis pointing north and thexaxis pointing to the first meridian as the image below shows.


key: chroma:document
string_value:
However, this reference system is impractical for describing the motion and representing the environment around objects in or close to the earth’s surface: Imagine your robot is located on a soccer field and you want it to move from one end to the other, your navigation task would look something like:

Addinally, if your robot has for instance a 2D lidar, you would have to transform its data to this reference system as well. It would make much more sense to create a local reference system where you could tell your robot “go 100 meters forward” and your sensor data could populate your environment representation accordingly, right?


key: chroma:document
string_value:
To cope with this, geodesy proposes several planar projection systems for localization with respect to the surface of the earth. One of them is theUTM coordinate system, which assumes earth is an ellipsoid and divides it in 60 zones, each of them spanning across 6 longitude degrees. A zone represents the projection of the ellipsoid’s surface over a secant cylinder parallel to its central meridian; each of them is then split into 20 latitude bands that span across 8 latitude degrees, which create local grid zones where positions are expressed using planar coordinates from the origin of the zone. The image below shows the grid zones spanning across South America.


key: chroma:document
string_value:
robot_localizationuses this projection system to transform GPS measurements in the WGS84 reference system to a cartesian system, which centered on the origin of the grid zone where the GPS is at. This is achieved through thenavsat_transform node. This node complies with the ENU convention inREP 103, meaning that the+xaxis of theutmcoordinate system faces east, the+yfaces north and the+zaxis points up.


key: chroma:document
string_value:
In the real world GPS sensors can be noisy: With standalone GPSs you should expect accuracies of 1-2 meters under excellent conditions and up to 10 meters, and frequent jumps in the position as the GPS sensor picks up less or more satellites, which can degrade the quality of navigation significantly. Several positioning augmentation technologies exists to reduce the error of GPS measurements, one of the most common ones is calledRTK(Real Time Kinematic Positioning), which can bring the accuracy of receivers down to 1cm. If accuracy matters in your application this technology is highly recommended; though this requires the deployment of a second fixed GPS called base, most of the US and Europe are already covered with public free to use bases that you can connect to. You can read more about RTK and how to get startedhere. In this tutorial we assume the robot’s GPS produces an accurate and smooth estimation of the robot’s position.


key: chroma:document
string_value:
Additionally, to fully describe a robot’s localization we need to know its heading as well, however standalone GPS sensors do not provide orientation measurements, only position measurements. In this tutorial we will refer to ‘absolute heading’ as a yaw measurement which is given w.r.t. a cardinal direction (e.g, the east), in contrast to relative heading, which is given w.r.t. the angle the robot is turned on or any other reference that cannot be directly mapped  to a cardinal direction.

When using robot_localization with GPS, measuring absolute orientation is mandatory. There are several strategies for getting absolute orientation data, like IMUs with magnetometers, dual GPS systems or matching techniques over a known map; in this tutorial we assume the robot is equipped with an IMU that can accurately measure absolute orientation following the ENU convention, meaning it will output zero yaw when facing east and +90 degrees when facing north.


key: chroma:document
string_value:
Despite the above assumption, in the real world commercial grade IMU’s mounted in actual robots will often not produce accurate absolute heading measurements because:

Thus, for a particular application you should consider the behavior and localization quality you require when making decisions about how to estimate your absolute heading. When using IMU’s without relative headings to a cardinal direction, the robot may need to move around for a bit in an ‘initialization dance’ to converge to the right heading using the filter. Using dual-GPS or 3D mapping system overlay, the initial heading is quite good.

For the purposes of this tutorial, we model a well-built system using an IMU that has absolute orientation already, but that may be augmented or replaced on a practical system using one of the techniques above (or others).

## Tutorial Steps

## 0- Setup Gazebo World


key: chroma:document
string_value:
## Tutorial Steps

## 0- Setup Gazebo World

To navigate using GPS we first need to create an outdoors Gazebo world with a robot having a GPS sensor to setup for navigation. For this tutorial we will be using theSonoma Racewaybecause its aligned with the real location. A sample world has been setuphereusing gazebo’s spherical coordinates plugin, which creates a local tangent plane centered in the set geographic origin and provides latitude, longitude and altitude coordinates for each point in the world:

To get GPS readings from Gazebo we need to create a robot model with a GPS sensor. An updated Turtlebot model with such sensor is provided in thetutorial repo, it outputsNavSatFixmessages on the topic/gps/fix:

Additionally, since we added a new GPS sensor in thegps_linkwe need to add a joint for this link that publishes a static transform w.r.t.base_link

Build thenav2_gps_waypoint_follower_demopackage, source your workspace and test your gazebo world is properly set up by launching:


key: chroma:document
string_value:
A Turtlebot waffle should appear in the Sonoma Raceway world. You may also echo the topic/gps/fixto verify the robot is indeed producing GPS measurements

## 1- Setup GPS Localization system

Once you have your simulation (or real robot) up and running, it’s time to set up your localization system. Remember that Nav2 uses atfchain with the structuremap->odom->base_link->[sensorframes]; global localization (map->odom) is usually provided byamcl, whileodom->base_linkis usually provided by the user’s odometry system (wheel odometry, visual odometry, etc).


key: chroma:document
string_value:
In this tutorial, the GPS sensor on the robot will replaceamclin providing global localization. Though you may build a custom module that takes in theNavSatFixandImumessages of your GPS and imu, and outputs atfbetween yourmapandodomframes using a planar projection, Nav2’s GPS waypoint follower currently uses robot_localization for converting GPS goals to cartesian goals, and thus at anavsat_transform_nodeshould be active. Additionally,robot_localizationfeatures reconfigurable state estimation nodes that use Kalman Filters to fuse multiple sources of data, which is yet another reason to use it.


key: chroma:document
string_value:
We will setup one Extended Kalman Filter for local odometry, fusing wheel odometry and IMU data; a second one for global localization, fusing the local cartesian converted GPS coordinates, the wheel odometry and the IMU data; and a navsat_transform node to output cartesian odometry messages from GPS data. This is a common setup on robot_localization when using GPS data and more details around its configuration can be found inRL’s docs.

Aconfiguration fileand alaunch fileare provided for this purpose. You may take a while before continuing to understand these two files and what they configure. Let’s walk through the most relevant setting of each node.

## Local Odometry


key: chroma:document
string_value:
## Local Odometry

The local odometry is provided by theekf_filter_node_odom, which publishes the transform betweenodomandbase_footprint, the base frame of the turtlebot’s diff drive plugin in gazebo. The robot state publisher provides a static transform betweenbase_footprintandbase_link, however make sure to set the base frame properly in RL according to your configuration. Note that the EKFs are set to work in 2D mode, this is because nav2’s costmap environment representation is 2-Dimensional, and several layers rely on thebase_linkframe being on the same plane as their global frame for the height related parameters to make sense. This is encoded in the following parameters:

Since perREP 105the position of the robot in theodomframe has to be continuous over time, in this filter we just want to fuse the robot’s speed measured by its wheels published/odom, and the imu heading published on/imu:

## Global Odometry


key: chroma:document
string_value:
## Global Odometry

The global odometry is provided by theekf_filter_node_map, which publishes the transform betweenmapandbase_footprint. This EKF is set to work in 2D mode as well. In addition to the IMU and wheel odometry data, this filter takes in the odometry output of the gps, published by thenavsat_transformnode on/odometry/gpsas an odometry message:

## Navsat Transform

The navsat transform produces an odometry output with the position of the GPS in themapframe, which is ingested by the global EKF as said above. It exposes thedatumparameter to set the GPS coordinates and heading of the origin ofmap; if left undeclared it will be set automatically to the coordinates of the first validNavSatFixmessage it gets, and it may be changed in runtime as well calling the/datumservice.


key: chroma:document
string_value:
In this tutorial we will go with the automaticdatuminitialization because there is no information about the environment stored in cartesian coordinates (a static map, semantic navigation waypoints, a 3D pointcloud map, etc), however if that’s the case in your application you may fix thedatumso a given pair of coordinates produced by the GPS always correspond to the same cartesian coordinates in your reference system.

The node also exposes theyaw_offsetparameter to compensate for known errors that the IMU absolute yaw measurement may have with respect to the east. Since Gazebo’s IMU follows the ENU convention this is set to0in the tutorial, but you may want to change it if you know beforehand there’s a fixed offset in your data.

Here’s the full configuration for thenavsat_transformnode:

## Localization Testing

As a sanity check that everything is working correctly, launch RL’s launch file while Gazebo is still running:


key: chroma:document
string_value:
On a different terminal launch mapviz using the pre-builtconfig filein the repo.Get a bing maps API keyand use it to display satellite pictures.

You should see the window below after properly setting the API key:

Finally run the teleop twist keyboard node to teleoperate the simulated Turtlebot:

When you have everything up and running, start teleoperating the Turtlebot and check that:

The gif below shows what you should see:

Sensors in a real robot may be less accurate than Gazebo’s, especially GPSs and absolute heading measurements from IMUs. To mitigate this you can leverage robot_localization’s EKFs to complement sensor’s capabilities:

## 2- Setup Navigation system

Once you have your localization system up and running it’s time to set up Nav2. Since RL is already providing thetftree we don’t need to launchamcl, thus we can remove its parameters from the params file and not launch Nav2’s localization launch file.

There are three main possible setups for the global costmap:


key: chroma:document
string_value:
There are three main possible setups for the global costmap:

We provide aNav2 params filewith the rolling costmap setup and alaunch fileto put it all together. Remember that the GPS setup of robot_localization was just a means for setting up the global localization system, however Nav2 is still a cartesian navigation stack and you may still use all its cartesian tools. To confirm that everything is working, launch the provided file (this launches gazebo and RL as well so close them if you have them running from the previous steps) and use rviz to send a goal to the robot:

The gif below shows what you should see Nav2 navigating the robot autonomously!

## 3-  Interactive GPS Waypoint Follower


key: chroma:document
string_value:
## 3-  Interactive GPS Waypoint Follower

Now that we have performed our complete system setup, let’s leverage Nav2 GPS waypoint follower capabilities to navigate to goals that are expressed directly in GPS coordinates. For this demo we want to build an interactive interface similar to rviz’s, that allows us to click over a map to make the robot navigate to the clicked location. For that we will use mapviz’s point click publisher on thewgs84reference frame, which will publish aPointStampedmessage with the GPS coordinates of the point clicked over the satellite image. This is a great way to get started in your custom GPS navigation setup!

For this purpose we provide theinteractive_waypoint_followerpython node, which subscribes to mapviz’s topic and calls the/follow_gps_waypointsaction server with the clicked point as goal using theBasicNavigatorinnav2_simple_commander. To run it source your workspace and with the rest of the system running type:


key: chroma:document
string_value:
You can now click on the mapviz map the pose you want the robot to go. The gif below shows the robot navigating to the finish line going through some obstacles:

## 4-  Logged GPS Waypoint Follower & Waypoint Logging

Finally let’s make a robot go through a set of predefined GPS waypoints. We provide awaypoint logging toolthat subscribes to the robot’s GPS and IMU and offers a simple GUI to save the robot coordinates and heading on demand to ayamlfile with the format:

Let’s log some waypoints for the robot to follow. Source your workspace and with the rest of the system running type:

If you don’t provide a path to save your waypoints, they will be saved in yourhomefolder by default with the namegps_waypoints.yaml. Once the node launches you should see a small GUI with a button to log waypoints, you may now move the robot around and click that button to record its position as the gif below shows:


key: chroma:document
string_value:
After that you should get ayamlfile in the location you specified with the format shown above; let’s now make the robot follow the logged waypoints. For this purpose we provide thelogged_waypoint_followernode, which takes in the path to the waypoints file as an argument and uses theBasicNavigatorinnav2_simple_commanderto send the logged goals to the/follow_gps_waypointsaction server. If not provided, the node uses thedefault waypointsin thenav2_gps_waypoint_follower_demopackage.

To run this node source your workspace and with the rest of the system running type:

You should now see the robot following the waypoints you previously logged:

## Conclusion


key: chroma:document
string_value:
## Conclusion

This tutorial discussed the usage of a GPS sensor for global localization using RL and thenavsat_transformnode, covering the setup of a gazebo simulation with a GPS equipped robot as well. It also went through the configuration changes in Nav2 for navigating with GPS localization, emphasizing on some different possibilities for setting up the global costmap. Finally it showcased the capabilities of Nav2’s GPS waypoint follower as a demonstration on how to use the stack in outdoors environments.

The tutorial should be a good starting point for setting up autonomous navigation using Nav2 on an outdoors robot, however users should keep in mind that GPS is just a means for providing global localization to the stack, and that all cartesian tools in Nav2 are still available for going past the GPS waypoint follower and building custom autonomy applications according to each use case.

Happy outdoors navigating!

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

source


key: chroma:document
string_value:
Language: unknown

File: use_cancel_deceleration

```

source

/opt/ros/<ros2-distro>/setup.bash

sudo

apt

install

ros-

$ROS_DISTRO

robot-localization

sudo

apt

install

ros-

$ROS_DISTRO

mapviz

sudo

apt

install

ros-

$ROS_DISTRO

mapviz-plugins

sudo

apt

install

ros-

$ROS_DISTRO

tile-map

```

Language: unknown

File: +z

```

<spherical_coordinates>

<!-- currently gazebo has a bug: instead of outputting lat, long, altitude in ENU

(x = East, y = North and z = Up) as the default configurations, it's outputting (-E)(-N)U,

therefore we rotate the default frame 180 so that it would go back to ENU

see: https://github.com/osrf/gazebo/issues/2022 -->

<surface_model>

EARTH_WGS84

</surface_model>

<latitude_deg>

38.161479

</latitude_deg>

<longitude_deg>

122.454630

</longitude_deg>

<elevation>

488.0

</elevation>

<heading_deg>

180

</heading_deg>

</spherical_coordinates>

```

Language: unknown

File: /gps/fix

```

<sensor

name=

"tb3_gps"

type=

"gps"

>

<always_on>

true


key: chroma:document
string_value:
<sensor

name=

"tb3_gps"

type=

"gps"

>

<always_on>

true

</always_on>

<update_rate>

1

</update_rate>

<pose>

0

0

0

0

0

0

</pose>

<gps>

<position_sensing>

<horizontal>

<noise

type=

"gaussian"

>

<mean>

0.0

</mean>

<stddev>

0.01

</stddev>

</noise>

</horizontal>

<vertical>

<noise

type=

"gaussian"

>

<mean>

0.0

</mean>

<stddev>

0.01

</stddev>

</noise>

</vertical>

</position_sensing>

</gps>

<plugin

name=

"my_gps_plugin"

filename=

"libgazebo_ros_gps_sensor.so"

>

<ros>

<remapping>

~/out:=/gps/fix

</remapping>

</ros>

</plugin>

</sensor>

```

Language: unknown

File: base_link

```

<joint

name=

"base_joint"

type=

"fixed"

>

<parent

link=

"base_link"

/>

<child

link=

"base_footprint"

/>

<origin

xyz=

"0 0 -0.010"

rpy=

"0 0 0"

/>

</joint>

```

Language: unknown

File: nav2_gps_waypoint_follower_demo

```

ros2

launch

nav2_gps_waypoint_follower_demo

gazebo_gps_world.launch.py

```

Language: unknown

File: base_link

```


key: chroma:document
string_value:
```

Language: unknown

File: base_link

```

ekf_filter_node_odom

:

ros__parameters

:

two_d_mode

:

true

publish_tf

:

true

base_link_frame

:

base_footprint

world_frame

:

odom

```

Language: unknown

File: /imu

```

odom0

:

odom

odom0_config

:

[

false

,

false

,

false

,

false

,

false

,

false

,

true

,

true

,

true

,

false

,

false

,

true

,

false

,

false

,

false

]

imu0

:

imu

imu0_config

:

[

false

,

false

,

false

,

false

,

false

,

true

,

false

,

false

,

false

,

false

,

false

,

false

,

false

,

false

,

false

]

```

Language: unknown

File: /odometry/gps

```

ekf_filter_node_map

:

ros__parameters

:

two_d_mode

:

true

publish_tf

:

true

base_link_frame

:

base_footprint

world_frame

:

map

odom1

:

odometry/gps

odom1_config

:

[

true

,

true

,

false

,

false

,

false

,

false

,

false

,

false

,

false

,

false

,

false

,

false

,

false

,

false

,

false

]

```

Language: unknown


key: chroma:document
string_value:
false

,

false

,

false

,

false

]

```

Language: unknown

File: navsat_transform

```

navsat_transform

:

ros__parameters

:

frequency

:

30.0

delay

:

3.0

magnetic_declination_radians

:

0.0

yaw_offset

:

0.0

zero_altitude

:

true

broadcast_utm_transform

:

true

publish_filtered_gps

:

true

use_odometry_yaw

:

true

wait_for_datum

:

false

# datum: [38.161491, -122.4546443, 0.0] # pre-set datum if needed, [lat, lon, yaw]

```

Language: unknown

File: navsat_transform

```

ros2

launch

nav2_gps_waypoint_follower_demo

dual_ekf_navsat.launch.py

```

Language: unknown

File: navsat_transform

```

ros2

launch

nav2_gps_waypoint_follower_demo

mapviz.launch.py

```

Language: unknown

File: navsat_transform

```

ros2

run

teleop_twist_keyboard

teleop_twist_keyboard

```

Language: unknown

File: datum

```

global_costmap

:

global_costmap

:

ros__parameters

:

...

rolling_window

:

True

width

:

50

height

:

50

```

Language: unknown

File: datum

```


key: chroma:document
string_value:
:

50

height

:

50

```

Language: unknown

File: datum

```

global_costmap

:

global_costmap

:

ros__parameters

:

...

plugins

:

[

"static_layer"

,

"obstacle_layer"

,

"inflation_layer"

]

```

Language: unknown

File: datum

```

global_costmap

:

global_costmap

:

ros__parameters

:

...

width

:

50

height

:

50

origin_x

:

25.0

origin_y

:

25.0

```

Language: unknown

File: datum

```

ros2

launch

nav2_gps_waypoint_follower_demo

gps_waypoint_follower.launch.py

use_rviz:

=

True

```

Language: unknown

File: nav2_simple_commander

```

ros2

run

nav2_gps_waypoint_follower_demo

interactive_waypoint_follower

```

Language: unknown

File: yaml

```

waypoints

:

latitude

:

38.161491054181276

longitude

:

122.45464431092836

yaw

:

0.0

latitude

:

38.161587576524845

longitude

:

122.4547994038464

yaw

:

1.57

```

Language: unknown

File: yaml

```

ros2

run

nav2_gps_waypoint_follower_demo

gps_waypoint_logger

</path/to/yaml/file.yaml>

```

Language: unknown


key: chroma:document
string_value:
</path/to/yaml/file.yaml>

```

Language: unknown

File: nav2_gps_waypoint_follower_demo

```

ros2

run

nav2_gps_waypoint_follower_demo

logged_waypoint_follower

</path/to/yaml/file.yaml>

```


key: chroma:document
string_value:
Title: DriveOnHeading

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/DriveOnHeading.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: DriveOnHeading

```

<DriveOnHeading

dist_to_travel=

"0.2"

speed=

"0.05"

server_name=

"backup_server"

server_timeout=

"10"

error_code_id=

"{drive_on_heading_error_code}"

/>

```


key: chroma:document
string_value:
Title: Inflation Layer Parameters

URL: https://docs.nav2.org/configuration/packages/costmap

plugins/inflation.html

Section: getting_started/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
Title: Smoother Server

URL: https://docs.nav2.org/configuration/packages/configuring

smoother

server.html#example

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Smoother Server Parameters

## Example

Code Examples:

Language: unknown

File: plugin

```

smoother_server

:

ros__parameters

:

smoother_plugins

:

[

"simple_smoother"

,

"curvature_smoother"

]

curvature_smoother

:

plugin

:

"nav2_ceres_costaware_smoother/CeresCostawareSmoother"

simple_smoother

:

plugin

:

"nav2_smoother::SimpleSmoother"

```

Language: unknown

File: plugin

```

smoother_server

:

ros__parameters

:

costmap_topic

:

global_costmap/costmap_raw

footprint_topic

:

global_costmap/published_footprint

robot_base_frame

:

base_link

transform_timeout

:

0.1

smoother_plugins

:

[

"simple_smoother"

]

simple_smoother

:

plugin

:

"nav2_smoother::SimpleSmoother"

tolerance

:

1.0e

10

do_refinement

:

True

```


key: chroma:document
string_value:
Title: SimpleProgressChecker

URL: https://docs.nav2.org/configuration/packages/nav2_controller

plugins/simple_progress_checker.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <nav2_controllerplugin>: nav2_controller plugin name defined in theprogress_checker_plugin_idparameter inController Server.


key: chroma:document
string_value:
Title: Get Backtrace in ROS 2 / Nav2

URL: https://docs.nav2.org/tutorials/docs/get_backtrace.html#overview

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview

This document explains one set of methods for getting backtraces for ROS 2 and Nav2.

There are many ways to accomplish this, but this is a good starting point for new C++ developers without GDB experience.

The following steps show ROS 2 users how to modify the Nav2 stack to get traces from specific servers when they encounter a problem.

This tutorial applies to both simulated and physical robots.

This will cover how to get a backtrace from a specific node usingros2run, from a launch file representing a single node usingros2launch, and from a more complex orchestration of nodes.

By the end of this tutorial, you should be able to get a backtrace when you notice a server crashing in ROS 2.

## Preliminaries

GDB is the most popular debugger for C++ on Unix systems.


key: chroma:document
string_value:
GDB is the most popular debugger for C++ on Unix systems.

It can be used to determine the reason for a crash and track threads.

It may also be used to add breakpoints in your code to check values in memory a particular points in your software.

Using GDB is a critical skill for all software developers working on C/C++.

Many IDEs will have some kind of debugger or profiler built in, but with ROS, there are few IDEs to choose.

Therefore it’s important to understand how to use these raw tools you have available rather than relying on an IDE to provide them.

Further, understanding these tools is a fundamental skill of C/C++ development and leaving it up to your IDE can be problematic if you change roles and no longer have access to it or are doing development on the fly through an ssh session to a remote asset.

Using GDB luckily is fairly simple after you have the basics under your belt.

The first step is to add-gto your compiler flags for the ROS package you want to profile / debug.


key: chroma:document
string_value:
This flag builds debug symbols that GDB and valgrind can read to tell you specific lines of code in your project are failing and why.

If you do not set this flag, you can still get backtraces but it will not provide line numbers for failures.

Be sure to remove this flag after debugging, it will slow down performance at run-time.

Adding the following line to yourCMakeLists.txtfor your project should do the trick.

If your project already has aadd_compile_options(), you can simply add-gto it.

Then simply rebuild your workspace with this packagecolconbuild--packages-select<package-name>.

It may take a little longer than usual to compile.

Now you’re ready to debug your code!

If this was a non-ROS project, at this point you might do something like below.

Here we’re launching a GDB session and telling our program to immediately run.

Once your program crashes, it will return a gdb session prompt denoted by(gdb).

At this prompt you can access the information you’re interested in.


key: chroma:document
string_value:
However, since this is a ROS project with lots of node configurations and other things going on, this isn’t a great option for beginners or those that don’t like tons of commandline work and understanding the filesystem.

Below are sections to describe the 3 major situations you could run into with ROS 2-based systems.

Read the section that best describes the problem you’re attempting to solve.

## From a Node

Just as in our non-ROS example, we need to setup a GDB session before launching our ROS 2 node.

While we could set this up through the commandline with some knowledge of the ROS 2 file system, we can instead use the launch--prefixoption the kind folks at Open Robotics provided for us.

--prefixwill execute some bits of code before ourros2command allowing us to insert some information.

If you attempted to dogdbexrun--argsros2run<pkg><node>as analog to our example in the preliminaries, you’d find that it couldn’t find theros2command.


key: chroma:document
string_value:
If you’re even more clever, you’d find that trying to source your workspace would also fail for similar reasons.

Rather than having to revert to finding the install path of the executable and typing it all out, we can instead use--prefix.

This allows us to use the sameros2runsyntax you’re used to without having to worry about some of the GDB details.

Just as before, this prefix will launch a GDB session and run the node you requested with all the additional commandline arguments.

You should now have your node running and should be chugging along with some debug printing.

Once your server crashes, you’ll see a prompt like below. At this point you can now get a backtrace.

In this session, typebacktraceand it will provide you with a backtrace.

Copy this for your needs.

For example:

In this example you should read this in the following way, starting at the bottom:


key: chroma:document
string_value:
These traces take some time to get used to reading, but in general, start at the bottom and follow it up the stack until you see the line it crashed on.

Then you can deduce why it crashed.

When you are done with GDB, typequitand it will exit the session and kill any processes still up.

It may ask you if you want to kill some threads at the end, say yes.

## From a Launch File

Just as in our non-ROS example, we need to setup a GDB session before launching our ROS 2 launch file.

While we could set this up through the commandline, we can instead make use of the same mechanics that we did in theros2runnode example, now using a launch file.

In your launch file, find the node that you’re interested in debugging.

For this section, we assume that your launch file contains only a single node (and potentially other information as well).

TheNodefunction used in thelaunch_rospackage will take in a fieldprefixtaking a list of prefix arguments.


key: chroma:document
string_value:
We will insert the GDB snippet here with one change from our node example, use ofxterm.xtermwill pop up a new terminal window to show and interact with GDB.

We do this because of issues handlingstdinon launch files (e.g. if you hit control+C, are you talking to GDB or launch?).

Seethis ticketfor more information.

See below for an example debugging SLAM Toolbox.

Just as before, this prefix will launch a GDB session, now inxtermand run the launch file you requested with all the additional launch arguments defined.

Once your server crashes, you’ll see a prompt like below, now in thextermsession. At this point you can now get a backtrace.

In this session, typebacktraceand it will provide you with a backtrace.

Copy this for your needs.

See the example trace in the section above for an example.

These traces take some time to get used to reading, but in general, start at the bottom and follow it up the stack until you see the line it crashed on.

Then you can deduce why it crashed.


key: chroma:document
string_value:
Then you can deduce why it crashed.

When you are done with GDB, typequitand it will exit the session and kill any processes still up.

It may ask you if you want to kill some threads at the end, say yes.

## From Large Project

Working with launch files with multiple nodes is a little different so you can interact with your GDB session without being bogged down by other logging in the same terminal.

For this reason, when working with larger launch files, its good to pull out the specific server you’re interested in and launching it separately.

These instructions are targeting Nav2, but are applicable to any large project with many nodes of any type in a series of launch file(s).

As such, for this case, when you see a crash you’d like to investigate, its beneficial to separate this server from the others.

If your server of interest is being launched from a nested launch file (e.g. an included launch file) you may want to do the following:


key: chroma:document
string_value:
Alternatively, if you server of interest is being launched in these files directly (e.g. you see aNode,LifecycleNode, or inside aComponentContainer), you will need to separate this from the others:

Once your server crashes, you’ll see a prompt like below in the specific server’s terminal. At this point you can now get a backtrace.

In this session, typebacktraceand it will provide you with a backtrace.

Copy this for your needs.

See the example trace in the section above for an example.

These traces take some time to get used to reading, but in general, start at the bottom and follow it up the stack until you see the line it crashed on.

Then you can deduce why it crashed.

When you are done with GDB, typequitand it will exit the session and kill any processes still up.

It may ask you if you want to kill some threads at the end, say yes.

## From Nav2 Bringup

To debug directly from the nav2 bringup launch files you may want to do the following:


key: chroma:document
string_value:
Once your server crashes, you’ll see a prompt like below in the xterm window. At this point you can now get a backtrace.

In this session, typebacktraceand it will provide you with a backtrace.

Copy this for your needs.

See the example trace in the section above for an example.

These traces take some time to get used to reading, but in general, start at the bottom and follow it up the stack until you see the line it crashed on.

Then you can deduce why it crashed.

When you are done with GDB, typequitand it will exit the session and kill any processes still up.

It may ask you if you want to kill some threads at the end, say yes.

## Automatic backtrace on crash

Thebackward-cpplibrary provides beautiful stack traces, and thebackward_roswrapper simplifies its integration.

Just add it as a dependency andfind_packageit in your CMakeLists and the backward libraries will be injected in all your executables and libraries.

Code Examples:

Language: unknown

File: colconbuild--packages-select<package-name>


key: chroma:document
string_value:
File: colconbuild--packages-select<package-name>

```

add_compile_options

(

g

)

```

Language: unknown

File: (gdb)

```

gdb

ex

run

--args

/path/to/exe/program

```

Language: unknown

File: ros2run

```

ros2

run

--prefix

'gdb -ex run --args'

<pkg>

<node>

--all-other-launch

arguments

```

Language: unknown

File: ros2run

```

(

gdb

)

```

Language: unknown

File: backtrace

```

(

gdb

)

backtrace

#0  __GI_raise (sig=sig@entry=6) at ../sysdeps/unix/sysv/linux/raise.c:50

#1  0x00007ffff79cc859 in __GI_abort () at abort.c:79

#2  0x00007ffff7c52951 in ?? () from /usr/lib/x86_64-linux-gnu/libstdc++.so.6

#3  0x00007ffff7c5e47c in ?? () from /usr/lib/x86_64-linux-gnu/libstdc++.so.6

#4  0x00007ffff7c5e4e7 in std::terminate() () from /usr/lib/x86_64-linux-gnu/libstdc++.so.6

#5  0x00007ffff7c5e799 in __cxa_throw () from /usr/lib/x86_64-linux-gnu/libstdc++.so.6

#6  0x00007ffff7c553eb in ?? () from /usr/lib/x86_64-linux-gnu/libstdc++.so.6


key: chroma:document
string_value:
#7  0x000055555555936c in std::vector<int, std::allocator<int> >::_M_range_check (

this

=

0x5555555cfdb0,

__n

=

100

)

at

/usr/include/c++/9/bits/stl_vector.h:1070

#8  0x0000555555558e1d in std::vector<int, std::allocator<int> >::at (this=0x5555555cfdb0,

__n

=

100

)

at

/usr/include/c++/9/bits/stl_vector.h:1091

#9  0x000055555555828b in GDBTester::VectorCrash (this=0x5555555cfb40)

at

/home/steve/Documents/nav2_ws/src/gdb_test_pkg/src/gdb_test_node.cpp:44

#10 0x0000555555559cfc in main (argc=1, argv=0x7fffffffc108)

at

/home/steve/Documents/nav2_ws/src/gdb_test_pkg/src/main.cpp:25

```

Language: unknown

File: stdin

```

start_sync_slam_toolbox_node

=

Node

(

parameters

=

[

get_package_share_directory

(

"slam_toolbox"

)

+

'/config/mapper_params_online_sync.yaml'

,

{

'use_sim_time'

:

use_sim_time

}

],

package

=

'slam_toolbox'

,

executable

=

'sync_slam_toolbox_node'

,

name

=

'slam_toolbox'

,

prefix

=

[

'xterm -e gdb -ex run --args'

],

output

=

'screen'


key: chroma:document
string_value:
=

[

'xterm -e gdb -ex run --args'

],

output

=

'screen'

)

```

Language: unknown

File: xterm

```

(

gdb

)

```

Language: unknown

File: --ros-args-r__node:=<node_name>--params-file/absolute/path/to/params.yaml

```

(

gdb

)

```

Language: unknown

File: ros2launchnav2_bringuptb3_simulation_launch.pyuse_composition:=False

```

(

gdb

)

```


key: chroma:document
string_value:
Title: Related Projects

URL: https://docs.nav2.org/about/related_projects.html

Section: getting_started/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
Title: Setting Up the Robot’s Footprint URL: https://docs.nav2.org/setup_guides/footprint/setup_footprint.html#configuring-the-robot-s-footprint Section: getting_started/index.html --------------------------------------------------------------------------------


key: chroma:document
string_value:
## Footprint Introduction The footprint outlines the robot’s 2D shape when projected to the ground and is primarily used by Nav2 to avoid collisions during planning. The algorithms involved in this task makes sure that the robot does not collide with the obstacles in the costmap while it computes the robot’s paths or plans. The footprint is set up using thefootprintorrobot_radiusparameter of the global and local costmaps which we tackled in the previous tutorials (Setting Up Sensors Guide). The value defined in thefootprintparameter is an ordered vector of 2-D points defining the robot’s footprint with thebase_linkframe as the origin. The first and last points in the vector are joined into the last line segment to close the footprint’s shape. As an alternative, you may also use therobot_radiusparameter wherein circular footprint is automatically generated and centered atbase_link.  In cases both thefootprintandrobot_radiusparameters have been defined in the configuration, thefootprintis used. For the global


key: chroma:document
string_value:
in the configuration, thefootprintis used. For the global costmap footprint, the decision to choose between therobot_radius(circular) orfootprint(polygon) parameter depends on the robot, its environment, and the path planning algorithm you will use. Even if you are working with a non-circular robot, there may be situations where a circular footprint is acceptable. For example, path planning algorithms likeNavFnassume that the robot is circular since it only checks for collision per grid cell, so it will not be necessary to outline the robot’s exact shape for its footprint. On the other hand, algorithms such asSmac Planner’s Hybrid-A*perform collision checking on the robot’s polygon-shaped footprint if possible and necessary. Hence, it might be useful to use a polygon-shaped footprint. Another example is having a small RC car sized robot roaming a warehouse. This robot is so small it won’t need to make confined maneuvers – thusly approximating it with the largest cross-sectional radius is a good time-saving


key: chroma:document
string_value:
with the largest cross-sectional radius is a good time-saving optimization. For the local costmap footprint, it is typical for non-circular robots to be set up withfootprint(polygon). Some situations where this is not recommended is when you do not have enough computing resources to implement collision avoidance algorithms on a polygon-shaped footprint. Another possible reason to userobot_radius(circular) for the local costmap is when the robot is very small relative to its environment such that precise collision avoidance is not necessary. However, generally the local trajectory planner should use the actual footprint polygon of the robot. Note that this can also be adjusted over time using the costmap’s~/footprinttopic, which will update the polygon over time as needed due to changes in the robot’s state, such as movement of an attached manipulator, picking up a pallet, or other actions that adjust a robot’s shape. That polygon will then automatically be used by the planners and controllers.


key: chroma:document
string_value:
## Configuring the Robot’s Footprint In this section, we will configure the footprint ofsam_botsuch thatfootprint(polygon) is used for the local costmap androbot_radius(circular) is used for the global costmap. We will utilize the default configuration file of Nav2 with a modified footprint parameter for the global and local costmaps. Under theconfigdirectory, create a new file namednav2_params.yaml. Next, copy the contents ofconfig/nav2_params.yamland paste them into the newly created file. The contents ofconfig/nav2_params.yamlare copied from the default configuration file of Nav2 but with changes in thefootprintandrobot_radiusparameters to match the shape ofsam_bot. Below is the code snippet fromnav2_params.yamldefining the local costmap footprint. In this configuration file, thefootprintparameter of the local costmap has already been set with a rectangular-shaped footprint. This box is centered at thebase_linkframe ofsam_bot. For the global costmap, we have already set therobot_radiusparameter to create


key: chroma:document
string_value:
costmap, we have already set therobot_radiusparameter to create a circular footprint that matchessam_bot’s size and centered atbase_link. The parameter that was modified is shown in the code snippet below.


key: chroma:document
string_value:
## Build, Run and Verification We will now confirm that we have properly set upsam_bot’s footprint. First, we launchlaunch/display.launch.pyto launch the robot state publisher, spawnsam_botin Gazebo, and visualizesam_botand its footprint in Rviz. The robot state publisher publishes thebase_link=>sensorstransforms defined insam_bot’s URDF, while Gazebo’s differential drive plugin publishes theodom=>base_linktransform. Open a new terminal and execute the lines below. After launchingdisplay.launch.py, RViz and Gazebo should open. RViz should showsam_bot, the frames ofsam_bot’s parts, and theodomframe without errors. Gazebo should showsam_botwith a sphere and a cube detectable bysambot’s lidar sensor. Next, we will publish themap=>odomtransform using thestatic_transform_publisher. We publish themap=>odomtransform as static in this guide as a simple way to publish the transform and visualize the footprint. Open a new terminal and execute the lines below. Themap=>odomtransform should now be being published and


key: chroma:document
string_value:
below. Themap=>odomtransform should now be being published and themapframe should be added in RViz without errors. Lastly, we will launch Nav2 using thenav2_params.yamlconfiguration file we just made andnavigation_launch.py, the built-in launch file ofnav2_bringup. Open a new terminal and execute the following: We should now be able to visualize the footprints in RViz, which will be discussed in the next section.


key: chroma:document
string_value:
## Visualizing Footprint in RViz To visualize the footprint of the local costmap, click the add button at the bottom-left part of the RViz window. Under theBytopictab, select thePolygonunder the/local_costmap/published_footprinttopic, as shown below. Set the fixed frame in RViz toodomand you should see the rectangular-shaped footprint ofsam_bot: On the other hand, for the global costmap, click the add button at the bottom-left part of the RViz window. Go toBytopictab then select thePolygonunder the/global_costmap/published_footprinttopic, as shown below. Set the fixed frame in RViz tomapand you should see the circular footprint ofsam_bot:


key: chroma:document
string_value:
## Conclusion In this guide, we have shown how to configure a circular and polygon-shaped footprint for your robot. This footprint is important since it plays a major role in Nav2’s pathfinding algorithms function. As a demo, we have configured the costmap footprint parameters ofsam_bot. We set the local costmap to use a polygon-shaped footprint followingsam_bot’s shape while we set the the global costmap to use a circular footprint. Lastly, we visualized and confirmed the footprints of the local and global costmaps in RViz.

Code Examples:

Language: unknown

File: sam_bot

```

188

resolution

:

0.05

189

footprint

:

"[

[0.21,

0.195],

[0.21,

0.195],

[

0.21,

0.195],

[

0.21,

0.195]

]"

190

plugins

:

[

"voxel_layer"

,

"inflation_layer"

]

```

Language: unknown

File: base_link

```

232

use_sim_time

:

True

233

robot_radius

:

0.3

234

resolution

:

0.05

```

Language: unknown

File: base_link

```

colcon

build

.

install/setup.bash

ros2

launch

sam_bot_description


key: chroma:document
string_value:
.

install/setup.bash

ros2

launch

sam_bot_description

display.launch.py

```

Language: unknown

File: odom

```

ros2

run

tf2_ros

static_transform_publisher

0

0

0

0

0

0

map

odom

```

Language: unknown

File: nav2_bringup

```

ros2

launch

nav2_bringup

navigation_launch.py

params_file:

=

<full/path/to/config/nav2_params.yaml>

```


key: chroma:document
string_value:
Title: Navigate To Pose and Pause Near Goal-Obstacle

URL: https://docs.nav2.org/behavior_trees/trees/nav_to_pose_and_pause_near_goal_obstacle.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

Code Examples:

Language: unknown

File: FollowPath

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<RecoveryNode

number_of_retries=

"6"

name=

"NavigateRecovery"

>

<PipelineSequence

name=

"NavigateWithReplanning"

>

<ControllerSelector

selected_controller=

"{selected_controller}"

default_controller=

"FollowPath"

topic_name=

"controller_selector"

/>

<PlannerSelector

selected_planner=

"{selected_planner}"

default_planner=

"GridBased"

topic_name=

"planner_selector"

/>

<RateController

hz=

"1.0"

>

<RecoveryNode

number_of_retries=

"1"

name=

"ComputePathToPose"

>

<ComputePathToPose

goal=

"{goal}"

path=

"{path}"

planner_id=

"{selected_planner}"

error_code_id=


key: chroma:document
string_value:
"{path}"

planner_id=

"{selected_planner}"

error_code_id=

"{compute_path_error_code}"

/>

<ClearEntireCostmap

name=

"ClearGlobalCostmap-Context"

service_name=

"global_costmap/clear_entirely_global_costmap"

/>

</RecoveryNode>

</RateController>

<ReactiveSequence

name=

"MonitorAndFollowPath"

>

<PathLongerOnApproach

path=

"{path}"

prox_len=

"3.0"

length_factor=

"2.0"

>

<RetryUntilSuccessful

num_attempts=

"1"

>

<SequenceStar

name=

"CancelingControlAndWait"

>

<CancelControl

name=

"ControlCancel"

/>

<Wait

wait_duration=

"5.0"

/>

</SequenceStar>

</RetryUntilSuccessful>

</PathLongerOnApproach>

<RecoveryNode

number_of_retries=

"1"

name=

"FollowPath"

>

<FollowPath

path=

"{path}"

controller_id=

"{selected_controller}"

error_code_id=

"{follow_path_error_code}"

/>

<ClearEntireCostmap

name=

"ClearLocalCostmap-Context"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

</RecoveryNode>

</ReactiveSequence>

</PipelineSequence>

<ReactiveFallback


key: chroma:document
string_value:
</ReactiveSequence>

</PipelineSequence>

<ReactiveFallback

name=

"RecoveryFallback"

>

<GoalUpdated/>

<RoundRobin

name=

"RecoveryActions"

>

<Sequence

name=

"ClearingActions"

>

<ClearEntireCostmap

name=

"ClearLocalCostmap-Subtree"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

<ClearEntireCostmap

name=

"ClearGlobalCostmap-Subtree"

service_name=

"global_costmap/clear_entirely_global_costmap"

/>

</Sequence>

<Spin

spin_dist=

"1.57"

/>

<Wait

wait_duration=

"5.0"

/>

<BackUp

backup_dist=

"0.30"

backup_speed=

"0.05"

/>

</RoundRobin>

</ReactiveFallback>

</RecoveryNode>

</BehaviorTree>

</root>

```


key: chroma:document
string_value:
Title: PipelineSequence

URL: https://docs.nav2.org/configuration/packages/bt

plugins/controls/PipelineSequence.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<PipelineSequence>

<!-

Add tree components here--

>

</PipelineSequence>

```


key: chroma:document
string_value:
Title: Navigate To Pose

URL: https://docs.nav2.org/behavior_trees/trees/nav_to_pose_recovery.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

Code Examples:

Language: unknown

File: FollowPath

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<RecoveryNode

number_of_retries=

"6"

name=

"NavigateRecovery"

>

<PipelineSequence

name=

"NavigateWithReplanning"

>

<ControllerSelector

selected_controller=

"{selected_controller}"

default_controller=

"FollowPath"

topic_name=

"controller_selector"

/>

<PlannerSelector

selected_planner=

"{selected_planner}"

default_planner=

"GridBased"

topic_name=

"planner_selector"

/>

<RateController

hz=

"1.0"

>

<RecoveryNode

number_of_retries=

"1"

name=

"ComputePathToPose"

>

<ComputePathToPose

goal=

"{goal}"

path=

"{path}"

planner_id=

"{selected_planner}"

error_code_id=

"{compute_path_error_code}"

/>

<Sequence>


key: chroma:document
string_value:
error_code_id=

"{compute_path_error_code}"

/>

<Sequence>

<WouldAPlannerRecoveryHelp

error_code=

"{compute_path_error_code}"

/>

<ClearEntireCostmap

name=

"ClearGlobalCostmap-Context"

service_name=

"global_costmap/clear_entirely_global_costmap"

/>

</Sequence>

</RecoveryNode>

</RateController>

<RecoveryNode

number_of_retries=

"1"

name=

"FollowPath"

>

<FollowPath

path=

"{path}"

controller_id=

"{selected_controller}"

error_code_id=

"{follow_path_error_code}"

/>

<Sequence>

<WouldAControllerRecoveryHelp

error_code=

"{follow_path_error_code}"

/>

<ClearEntireCostmap

name=

"ClearLocalCostmap-Context"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

</Sequence>

</RecoveryNode>

</PipelineSequence>

<Sequence>

<Fallback>

<WouldAControllerRecoveryHelp

error_code=

"{follow_path_error_code}"

/>

<WouldAPlannerRecoveryHelp

error_code=

"{compute_path_error_code}"

/>

</Fallback>

<ReactiveFallback

name=

"RecoveryFallback"

>

<GoalUpdated/>

<RoundRobin


key: chroma:document
string_value:
name=

"RecoveryFallback"

>

<GoalUpdated/>

<RoundRobin

name=

"RecoveryActions"

>

<Sequence

name=

"ClearingActions"

>

<ClearEntireCostmap

name=

"ClearLocalCostmap-Subtree"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

<ClearEntireCostmap

name=

"ClearGlobalCostmap-Subtree"

service_name=

"global_costmap/clear_entirely_global_costmap"

/>

</Sequence>

<Spin

spin_dist=

"1.57"

error_code_id=

"{spin_error_code}"

/>

<Wait

wait_duration=

"5.0"

/>

<BackUp

backup_dist=

"0.30"

backup_speed=

"0.05"

error_code_id=

"{backup_code_id}"

/>

</RoundRobin>

</ReactiveFallback>

</Sequence>

</RecoveryNode>

</BehaviorTree>

</root>

```


key: chroma:document
string_value:
Title: GloballyUpdatedGoal

URL: https://docs.nav2.org/configuration/packages/bt

plugins/conditions/GloballyUpdatedGoal.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<GlobalUpdatedGoal/>

```


key: chroma:document
string_value:
Title: TwirlingCritic

URL: https://docs.nav2.org/configuration/packages/trajectory_critics/twirling.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <dwbplugin>: DWB plugin name defined in thecontroller_plugin_idsparameter inController Server. <name>: TwirlingCritic critic name defined in the<dwb plugin>.criticsparameter defined inDWB Controller.


key: chroma:document
string_value:
Title: Docking Server

URL: https://docs.nav2.org/configuration/packages/configuring-docking-server.html#example

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

Note:dock_pluginsand eitherdocksordock_databaseare required.

## SimpleChargingDock Parameters

Simple Charging Dock is a provided charging dock plugin that can handle many docks and common techniques.

## Example

Code Examples:

Language: unknown

File: isDocked()=true

```

docking_server

:

ros__parameters

:

controller_frequency

:

50.0

initial_perception_timeout

:

5.0

wait_charge_timeout

:

5.0

dock_approach_timeout

:

30.0

undock_linear_tolerance

:

0.05

undock_angular_tolerance

:

0.1

max_retries

:

3

base_frame

:

"base_link"

fixed_frame

:

"odom"

dock_backwards

:

false

dock_prestaging_tolerance

:

0.5

# Types of docks

dock_plugins

:

[

'nova_carter_dock'

]

nova_carter_dock

:

plugin

:


key: chroma:document
string_value:
:

[

'nova_carter_dock'

]

nova_carter_dock

:

plugin

:

'opennav_docking::SimpleChargingDock'

# Also 'opennav_docking::SimpleNonChargingDock'

docking_threshold

:

0.05

staging_x_offset

:

0.7

use_external_detection_pose

:

true

use_battery_status

:

false

# true

use_stall_detection

:

false

external_detection_timeout

:

1.0

external_detection_translation_x

:

0.18

external_detection_translation_y

:

0.0

external_detection_rotation_roll

:

1.57

external_detection_rotation_pitch

:

1.57

external_detection_rotation_yaw

:

0.0

filter_coef

:

0.1

# Dock instances

docks

:

[

'home_dock'

]

home_dock

:

type

:

'nova_carter_dock'

frame

:

map

pose

:

[

0.0

,

0.0

,

0.0

]

id

:

'c67f50cb-e152-4720-85cc-5eb20bd85ce8'

controller

:

k_phi

:

3.0

k_delta

:

2.0

v_linear_min

:

0.15

v_linear_max

:

0.15

```


key: chroma:document
string_value:
Title: Nav2 Behavior Trees

URL: https://docs.nav2.org/behavior_trees/index.html

Section: behavior_trees/index.html

--------------------------------------------------------------------------------

Code Examples:

Language: unknown

File: nav2_bt_navigator

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<PipelineSequence

name=

"NavigateWithReplanning"

>

<DistanceController

distance=

"1.0"

>

<ComputePathToPose

goal=

"{goal}"

path=

"{path}"

/>

</DistanceController>

<FollowPath

path=

"{path}"

/>

</PipelineSequence>

</BehaviorTree>

</root>

```


key: chroma:document
string_value:
Title: Setting Up The URDF

URL: https://docs.nav2.org/setup_guides/urdf/setup_urdf.html#urdf-and-the-robot-state-publisher

Section: getting_started/index.html

--------------------------------------------------------------------------------

## URDF and the Robot State Publisher

As discussed in the previous tutorial, one of the requirements for Navigation2 is the transformation frombase_linkto the various sensors and reference frames. This transformation tree can range from a simple tree with only one link from thebase_linktolaser_linkor a tree comprised of multiple sensors located in different locations, each having their own coordinate frame. Creating multiple publishers to handle all of these coordinate frame transformations may become tedious. Therefore, we will be making use of the Robot State Publisher package to publish our transforms.


key: chroma:document
string_value:
The Robot State Publisher is a package of ROS 2 that interacts with the tf2 package to publish all of the necessary transforms that can be directly inferred from the geometry and structure of the robot. We need to provide it with the correct URDF and it will automatically handle publishing the transforms. This is very useful for complex transformations but it is still recommended for simpler transform trees.


key: chroma:document
string_value:
The Unified Robot Description Format (URDF) is an XML file that represents a robot model. In this tutorial, it will mainly be used to build transformations trees related with the robot geometry, but it also has other uses. One example is how it can be used in visualizing your robot model in RVIZ, a 3D Visualization tool for ROS, by defining visual components such as materials and meshes. Another example is how the URDF can be used to define the physical properties of the robot. These properties are then used in physics simulators such as Gazebo to simulate how your robot will interact in an environment.

Another major feature of URDF is that it also supports Xacro (XML Macros) to help you create a shorter and readable XML to help in defining complex robots. We can use these macros to eliminate the need for repeating blocks of XML in our URDF. Xacro is also useful in defining configuration constants which can be reused throughout the URDF.

## Setting Up the Environment


key: chroma:document
string_value:
## Setting Up the Environment

In this guide, we are assuming that you are already familiar with ROS 2 and how to setup your development environment, so we’ll breeze through the steps in this section.

Let’s begin by installing some additional ROS 2 packages that we will be using during this tutorial.

Next, create a directory for your project, initialize a ROS 2 workspace and give your robot a name. For ours, we’ll be calling itsam_bot.

## Writing the URDF

Now that we have our project workspace set up, let’s dive straight into writing the URDF. Below is an image of the robot we will be trying to build.

Next, let us define some constants using XAcro properties that will be reused throughout the URDF.


key: chroma:document
string_value:
Here is a brief discussion on what these properties will represent in our urdf. Thebase_*properties all define the size of the robot’s main chassis. Thewheel_radiusandwheel_widthdefine the shape of the robot’s two back wheels. Thewheel_ygapadjusts the gap between the wheel and the chassis along the y-axis whilstwheel_zoffandwheel_xoffposition the back wheels along the z-axis and x-axis appropriately. Lastly, thecaster_xoffpositions the front caster wheel along the x-axis.

Let us then define ourbase_link- this link will be a large box and will act as the main chassis of our robot. In URDF, alinkelement describes a rigid part or component of our robot. The robot state publisher then utilizes these definitions to determine coordinate frames for each link and publish the transformations between them.


key: chroma:document
string_value:
We will also be defining some of the link’s visual properties which can be used by tools such as Gazebo and Rviz to show us a 3D model of our robot. Amongst these properties are<geometry>which describes the link’s shape and<material>which describes it’s color.

For the code block block below, we access thebaseproperties from the robot constants sections we defined before using the${property}syntax. In addition, we also set the material color of the main chassis toCyan. Note that we set these parameters under the<visual>tag so they will only be applied as visual parameters which dont affect any collision or physical properties.


key: chroma:document
string_value:
Next, let us define abase_footprintlink. Thebase_footprintlink is a virtual (non-physical) link which has no dimensions or collision areas. Its primary purpose is to enable various packages determine the center of a robot projected to the ground. For example, Navigation2 uses this link to determine the center of a circular footprint used in its obstacle avoidance algorithms. Again, we set this link with no dimensions and to which position the robot’s center is in when it is projected to the ground plane.


key: chroma:document
string_value:
After defining our base_link, we then add a joint to connect it tobase_link. In URDF, ajointelement describes the kinematic and dynamic properties between coordinate frames. For this case, we will be defining afixedjoint with the appropriate offsets to place ourbase_footprintlink in the proper location based on the description above. Remember that we want to set our base_footprint to be at the ground plane when projected from the center of the main chassis, hence we get the sum of thewheel_radiusand thewheel_zoffto get the appropriate location along the z-axis.


key: chroma:document
string_value:
Now, we will be adding two large drive wheels to our robot. To make our code cleaner and avoid repetition, we will make use of macros to define a block of code that will be repeated with differing parameters. Our macro will have 3 params:prefixwhich simply adds a prefix to our link and joint names, andx_reflectandy_reflectwhich allows us to flip the positions of our wheels with respect to the x and y axis respectively. Within this macro, we can also define the visual properties of a single wheel. Lastly, we will also define acontinuousjoint to allow our wheels to freely rotate about an axis. This joint also connects our wheel to thebase_linkat the appropriate location.

At the end of this code block, we will be instantiating two wheels using the macro we just made through thexacro:wheeltags. Note that we also define the parameters to have one wheel on both sides at the back of our robot.


key: chroma:document
string_value:
Next, we will be adding a caster wheel at the front of our robot. We will be modelling this wheel as a sphere to keep things simple. Again, we define the wheel’s geometry, material and the joint to connect it tobase_linkat the appropriate location.

And that’s it! We have built a URDF for a simple differential drive robot. In the next section, we will focus on building the ROS Package containing our URDF, launching the robot state publisher, and visualizing the robot in RVIz.

## Build and Launch

Let’s start this section by adding some dependencies that will be required once we build this project. Open up the root of your project directory and add the following lines to yourpackage.xml(preferably after the<buildtool_depend>tag)


key: chroma:document
string_value:
Next, let us create our launch file. Launch files are used by ROS 2 to bring up the necessary nodes for our package. From the root of the project, create a directory namedlaunchand adisplay.launch.pyfile within it. The launch file below launches a robot publisher node in ROS 2 that uses our URDF to publish the transforms for our robot. In addition, the launch file also automatically launches RVIZ so we can visualize our robot as defined by the URDF. Copy and paste the snippet below into yourdisplay.launch.pyfile.

To keep things simpler when we get to visualization, we have provided an RVIz config file that will be loaded when we launch our package. This configuration file initializes RVIz with the proper settings so you can view the robot immediately once it launches. Create a directory namedrvizin the root of your project and a file namedurdf_config.rvizunder it. Place the following as the contents ofurdf_config.rviz


key: chroma:document
string_value:
Lastly, let us modify theCMakeLists.txtfile in the project root directory to include the files we just created during the package installation process. Add the following snippet toCMakeLists.txtfile preferably above theif(BUILD_TESTING)line:

We are now ready to build our project using colcon. Navigate to the project root and execute the following commands.

After a successful build, execute the following commands to install the ROS 2 package and launch our project.

ROS 2 should now launch a robot publisher node and start up RVIZ using our URDF. We’ll be taking a look at our robot using RVIZ in the next section.

## Visualization using RVIZ

RVIZ is a robot visualization tool that allows us to see a 3D model of our robot using its URDF. Upon a successful launch using the commands in the previous section, RVIZ should now be visible on your screen and should look like the image below. You may need to move around and manipulate the view to get a good look at your robot.


key: chroma:document
string_value:
As you can see, we have successfully created a simple differential drive robot and visualized it in RVIz. It is not necessary to visualize your robot in RVIz, but it’s a good step in order to see if you have properly defined your URDF. This helps you ensure that the robot state publisher is publishing the correct transformations.

You may have noticed that another window was launched - this is a GUI for the joint state publisher. The joint state publisher is another ROS 2 package which publishes the state for our non-fixed joints. You can manipulate this publisher through the small GUI and the new pose of the joints will be reflected in RVIz. Sliding the bars for any of the two wheels will rotate these joints. You can see this in action by viewing RVIZ as you sweep the sliders in the Joint State Publisher GUI.


key: chroma:document
string_value:
At this point, you may already decide to stop with this tutorial since we have already achieved our objective of creating a URDF for a simple differential drive robot. The robot state publisher is now publishing the transforms derived from the URDF. These transforms can now be used by other packages (such as Nav2) to get information regarding the shape and structure of your robot. However, to properly use this URDF in a simulation, we need physical properties so that the robot reacts to physical environments like a real robot would. The visualization fields are only for visualization, not collision, so your robot will drive straight through obstacles. We’ll get into adding these properties in our URDF in the next section.

## Adding Physical Properties


key: chroma:document
string_value:
## Adding Physical Properties

As an additional section to this guide, we will be modifying our current URDF to include some of our robot’s kinematic properties. This information may be used by physics simulators such as Gazebo to model and simulate how our robot will act in the virtual environment.

Let us first define macros containing the inertial properties of the geometric primitives we used in our project. Place the snippet below after our constants section in the URDF:

Let us start by adding collision areas to ourbase_linkusing the<collision>tag. We will also be using the box_inertia macro we defined before to add some inertial properties to ourbase_link. Include the following code snippet within<linkname="base_link">tag of base_link in our URDF.

Next, let us do the same for our wheel macros. Include the following code snippet within the<linkname="${prefix}_link">tag of our wheel macros in our URDF.


key: chroma:document
string_value:
Lastly, let us add the similar properties to our spherical caster wheels. Include the following in the<linkname="front_caster">tag of our caster wheel in the URDF.

Build your project and then launch RViz using the same commands in the previous section.

You can verify whether you have properly set up the collision areas by enablingCollisionEnabledunderRobotModelon the left pane (it may be easier to see if you also turn offVisualEnabled). For this tutorial we defined a collision area which is similar to our visual properties. Note that this may not always be the case since you may opt for simpler collision areas based on how your robot looks.


key: chroma:document
string_value:
For now, we will have to stop here since we will need to set up a lot more components to actually start simulating our robot in Gazebo. We will be coming back to this project during the course of these setup guides, and we will eventually see our robot move in a virtual environment once we get to the simulation sections. The major components that are missing from this work are the simulation plugins required to mimic your robot controllers. We will introduce those and add them to this URDF in the appropriate section.

## Conclusion

And that’s it. In this tutorial, you have successfully created a URDF for a simple differential drive robot. You have also set up a ROS 2 project that launches a robot publisher node, which then uses your URDF to publish the robot’s transforms. We have also used RViz to visualize our robot to verify whether our URDF is correct. Lastly, we have added in some physical properties to our URDF in order to prepare it for simulation.


key: chroma:document
string_value:
Feel free to use this tutorial as a template for your own robot. Remember that your main goal is to publish the correct transforms from your base_link up to your sensor_frames. Once these have been setup, then you may proceed to our other setup guides.

Code Examples:

Language: unknown

File: laser_link

```

sudo

apt

install

ros-<ros2-distro>-joint-state-publisher-gui

sudo

apt

install

ros-<ros2-distro>-xacro

```

Language: unknown

File: sam_bot

```

ros2

pkg

create

--build-type

ament_cmake

sam_bot_description

```

Language: unknown

File: src/description

```

1

<?xml version="1.0"?>

2

<robot

name=

"sam_bot"

xmlns:xacro=

"http://ros.org/wiki/xacro"

>

3

4

5

6

</robot>

```

Language: unknown

File: <robot>

```

4

<!-- Define robot constants -->

5

<xacro:property

name=

"base_width"

value=

"0.31"

/>

6

<xacro:property

name=

"base_length"

value=

"0.42"

/>

7

<xacro:property

name=

"base_height"

value=

"0.18"

/>

8

9

<xacro:property

name=

"wheel_radius"


key: chroma:document
string_value:
"0.18"

/>

8

9

<xacro:property

name=

"wheel_radius"

value=

"0.10"

/>

10

<xacro:property

name=

"wheel_width"

value=

"0.04"

/>

11

<xacro:property

name=

"wheel_ygap"

value=

"0.025"

/>

12

<xacro:property

name=

"wheel_zoff"

value=

"0.05"

/>

13

<xacro:property

name=

"wheel_xoff"

value=

"0.12"

/>

14

15

<xacro:property

name=

"caster_xoff"

value=

"0.14"

/>

```

Language: unknown

File: <visual>

```

17

<!-- Robot Base -->

18

<link

name=

"base_link"

>

19

<visual>

20

<geometry>

21

<box

size=

"${base_length} ${base_width} ${base_height}"

/>

22

</geometry>

23

<material

name=

"Cyan"

>

24

<color

rgba=

"0 1.0 1.0 1.0"

/>

25

</material>

26

</visual>

27

</link>

```

Language: unknown

File: wheel_zoff

```

29

<!-- Robot Footprint -->

30

<link

name=

"base_footprint"

/>

31

32

<joint

name=

"base_joint"

type=

"fixed"

>

33

<parent

link=

"base_link"

/>

34

<child

link=

"base_footprint"

/>

35

<origin

xyz=


key: chroma:document
string_value:
/>

34

<child

link=

"base_footprint"

/>

35

<origin

xyz=

"0.0 0.0 ${-(wheel_radius+wheel_zoff)}"

rpy=

"0 0 0"

/>

36

</joint>

```

Language: unknown

File: xacro:wheel

```

38

<!-- Wheels -->

39

<xacro:macro

name=

"wheel"

params=

"prefix x_reflect y_reflect"

>

40

<link

name=

"${prefix}_link"

>

41

<visual>

42

<origin

xyz=

"0 0 0"

rpy=

"${pi/2} 0 0"

/>

43

<geometry>

44

<cylinder

radius=

"${wheel_radius}"

length=

"${wheel_width}"

/>

45

</geometry>

46

<material

name=

"Gray"

>

47

<color

rgba=

"0.5 0.5 0.5 1.0"

/>

48

</material>

49

</visual>

50

</link>

51

52

<joint

name=

"${prefix}_joint"

type=

"continuous"

>

53

<parent

link=

"base_link"

/>

54

<child

link=

"${prefix}_link"

/>

55

<origin

xyz=

"${x_reflect*wheel_xoff} ${y_reflect*(base_width/2+wheel_ygap)} ${-wheel_zoff}"

rpy=

"0 0 0"

/>

56

<axis

xyz=

"0 1 0"

/>

57

</joint>

58

</xacro:macro>

59

60

<xacro:wheel

prefix=

"drivewhl_l"

x_reflect=

"-1"

y_reflect=

"1"


key: chroma:document
string_value:
prefix=

"drivewhl_l"

x_reflect=

"-1"

y_reflect=

"1"

/>

61

<xacro:wheel

prefix=

"drivewhl_r"

x_reflect=

"-1"

y_reflect=

"-1"

/>

```

Language: unknown

File: base_link

```

63

<!-- Caster Wheel -->

64

<link

name=

"front_caster"

>

65

<visual>

66

<geometry>

67

<sphere

radius=

"${(wheel_radius+wheel_zoff-(base_height/2))}"

/>

68

</geometry>

69

<material

name=

"Cyan"

>

70

<color

rgba=

"0 1.0 1.0 1.0"

/>

71

</material>

72

</visual>

73

</link>

74

75

<joint

name=

"caster_joint"

type=

"fixed"

>

76

<parent

link=

"base_link"

/>

77

<child

link=

"front_caster"

/>

78

<origin

xyz=

"${caster_xoff} 0.0 ${-(base_height/2)}"

rpy=

"0 0 0"

/>

79

</joint>

```

Language: unknown

File: <buildtool_depend>

```

<exec_depend>

joint_state_publisher

</exec_depend>

<exec_depend>

joint_state_publisher_gui

</exec_depend>

<exec_depend>

robot_state_publisher

</exec_depend>

<exec_depend>

rviz

</exec_depend>

<exec_depend>

xacro

</exec_depend>

```


key: chroma:document
string_value:
</exec_depend>

<exec_depend>

xacro

</exec_depend>

```

Language: unknown

File: display.launch.py

```

import

launch

from

launch.substitutions

import

Command

,

LaunchConfiguration

import

launch_ros

import

os

def

generate_launch_description

():

pkg_share

=

launch_ros

.

substitutions

.

FindPackageShare

(

package

=

'sam_bot_description'

)

.

find

(

'sam_bot_description'

)

default_model_path

=

os

.

path

.

join

(

pkg_share

,

'src/description/sam_bot_description.urdf'

)

default_rviz_config_path

=

os

.

path

.

join

(

pkg_share

,

'rviz/urdf_config.rviz'

)

robot_state_publisher_node

=

launch_ros

.

actions

.

Node

(

package

=

'robot_state_publisher'

,

executable

=

'robot_state_publisher'

,

parameters

=

[{

'robot_description'

:

Command

([

'xacro '

,

LaunchConfiguration

(

'model'

)])}]

)

joint_state_publisher_node

=

launch_ros

.

actions

.

Node

(

package

=

'joint_state_publisher'

,

executable

=

'joint_state_publisher'


key: chroma:document
string_value:
,

executable

=

'joint_state_publisher'

,

name

=

'joint_state_publisher'

,

parameters

=

[{

'robot_description'

:

Command

([

'xacro '

,

default_model_path

])}],

condition

=

launch

.

conditions

.

UnlessCondition

(

LaunchConfiguration

(

'gui'

))

)

joint_state_publisher_gui_node

=

launch_ros

.

actions

.

Node

(

package

=

'joint_state_publisher_gui'

,

executable

=

'joint_state_publisher_gui'

,

name

=

'joint_state_publisher_gui'

,

condition

=

launch

.

conditions

.

IfCondition

(

LaunchConfiguration

(

'gui'

))

)

rviz_node

=

launch_ros

.

actions

.

Node

(

package

=

'rviz2'

,

executable

=

'rviz2'

,

name

=

'rviz2'

,

output

=

'screen'

,

arguments

=

[

'-d'

,

LaunchConfiguration

(

'rvizconfig'

)],

)

return

launch

.

LaunchDescription

([

launch

.

actions

.

DeclareLaunchArgument

(

name

=

'gui'

,

default_value

=

'True'

,

description

=

'Flag to enable joint_state_publisher_gui'

),

launch

.

actions

.


key: chroma:document
string_value:
),

launch

.

actions

.

DeclareLaunchArgument

(

name

=

'model'

,

default_value

=

default_model_path

,

description

=

'Absolute path to robot urdf file'

),

launch

.

actions

.

DeclareLaunchArgument

(

name

=

'rvizconfig'

,

default_value

=

default_rviz_config_path

,

description

=

'Absolute path to rviz config file'

),

joint_state_publisher_node

,

joint_state_publisher_gui_node

,

robot_state_publisher_node

,

rviz_node

])

```

Language: unknown

File: urdf_config.rviz

```

Panels:

Class:

rviz_common/Displays

Help

Height:

78

Name:

Displays

Property

Tree

Widget:

Expanded:

/Global

Options1

/Status1

/RobotModel1/Links1

/TF1

Splitter

Ratio:

0

.5

Tree

Height:

557

Visualization

Manager:

Class:

""

Displays:

Alpha:

0

.5

Cell

Size:

1

Class:

rviz_default_plugins/Grid

Color:

160

;

160

;

164

Enabled:

true

Name:

Grid

Alpha:

0

.6

Class:

rviz_default_plugins/RobotModel

Description

Topic:

Depth:

5

Durability

Policy:

Volatile


key: chroma:document
string_value:
Description

Topic:

Depth:

5

Durability

Policy:

Volatile

History

Policy:

Keep

Last

Reliability

Policy:

Reliable

Value:

/robot_description

Enabled:

true

Name:

RobotModel

Visual

Enabled:

true

Class:

rviz_default_plugins/TF

Enabled:

true

Name:

TF

Marker

Scale:

0

.3

Show

Arrows:

true

Show

Axes:

true

Show

Names:

true

Enabled:

true

Global

Options:

Background

Color:

48

;

48

;

48

Fixed

Frame:

base_link

Frame

Rate:

30

Name:

root

Tools:

Class:

rviz_default_plugins/Interact

Hide

Inactive

Objects:

true

Class:

rviz_default_plugins/MoveCamera

Class:

rviz_default_plugins/Select

Class:

rviz_default_plugins/FocusCamera

Class:

rviz_default_plugins/Measure

Line

color:

128

;

128

;

0

Transformation:

Current:

Class:

rviz_default_plugins/TF

Value:

true

Views:

Current:

Class:

rviz_default_plugins/Orbit

Name:

Current

View

Target

Frame:

<Fixed

Frame>

Value:

Orbit

(

rviz

)

Saved:

~

```

Language: unknown

File: if(BUILD_TESTING)


key: chroma:document
string_value:
)

Saved:

~

```

Language: unknown

File: if(BUILD_TESTING)

```

install

(

DIRECTORY

src

launch

rviz

DESTINATION

share/

${

PROJECT_NAME

}

)

```

Language: unknown

File: if(BUILD_TESTING)

```

colcon

build

.

install/setup.bash

```

Language: unknown

File: if(BUILD_TESTING)

```

ros2

launch

sam_bot_description

display.launch.py

```

Language: unknown

File: if(BUILD_TESTING)

```

17

<!-- Define inertial property macros  -->

18

<xacro:macro

name=

"box_inertia"

params=

"m w h d"

>

19

<inertial>

20

<origin

xyz=

"0 0 0"

rpy=

"${pi/2} 0 ${pi/2}"

/>

21

<mass

value=

"${m}"

/>

22

<inertia

ixx=

"${(m/12) * (h*h + d*d)}"

ixy=

"0.0"

ixz=

"0.0"

iyy=

"${(m/12) * (w*w + d*d)}"

iyz=

"0.0"

izz=

"${(m/12) * (w*w + h*h)}"

/>

23

</inertial>

24

</xacro:macro>

25

26

<xacro:macro

name=

"cylinder_inertia"

params=

"m r h"

>

27

<inertial>

28

<origin

xyz=

"0 0 0"

rpy=

"${pi/2} 0 0"

/>

29

<mass

value=

"${m}"

/>

30

<inertia

ixx=


key: chroma:document
string_value:
/>

29

<mass

value=

"${m}"

/>

30

<inertia

ixx=

"${(m/12) * (3*r*r + h*h)}"

ixy =

"0"

ixz =

"0"

iyy=

"${(m/12) * (3*r*r + h*h)}"

iyz =

"0"

izz=

"${(m/2) * (r*r)}"

/>

31

</inertial>

32

</xacro:macro>

33

34

<xacro:macro

name=

"sphere_inertia"

params=

"m r"

>

35

<inertial>

36

<mass

value=

"${m}"

/>

37

<inertia

ixx=

"${(2/5) * m * (r*r)}"

ixy=

"0.0"

ixz=

"0.0"

iyy=

"${(2/5) * m * (r*r)}"

iyz=

"0.0"

izz=

"${(2/5) * m * (r*r)}"

/>

38

</inertial>

39

</xacro:macro>

```

Language: unknown

File: <linkname="base_link">

```

52

<collision>

53

<geometry>

54

<box

size=

"${base_length} ${base_width} ${base_height}"

/>

55

</geometry>

56

</collision>

57

58

<xacro:box_inertia

m=

"15"

w=

"${base_width}"

d=

"${base_length}"

h=

"${base_height}"

/>

```

Language: unknown

File: <linkname="${prefix}_link">

```

83

<collision>

84

<origin

xyz=

"0 0 0"

rpy=

"${pi/2} 0 0"

/>

85

<geometry>

86

<cylinder

radius=

"${wheel_radius}"

length=


key: chroma:document
string_value:
<geometry>

86

<cylinder

radius=

"${wheel_radius}"

length=

"${wheel_width}"

/>

87

</geometry>

88

</collision>

89

90

<xacro:cylinder_inertia

m=

"0.5"

r=

"${wheel_radius}"

h=

"${wheel_width}"

/>

```

Language: unknown

File: <linkname="front_caster">

```

114

<collision>

115

<origin

xyz=

"0 0 0"

rpy=

"0 0 0"

/>

116

<geometry>

117

<sphere

radius=

"${(wheel_radius+wheel_zoff-(base_height/2))}"

/>

118

</geometry>

119

</collision>

120

121

<xacro:sphere_inertia

m=

"0.5"

r=

"${(wheel_radius+wheel_zoff-(base_height/2))}"

/>

```

Language: unknown

File: base_footprint

```

colcon

build

.

install/setup.bash

ros2

launch

sam_bot_description

display.launch.py

```


key: chroma:document
string_value:
Title: WaitAtWaypoint

URL: https://docs.nav2.org/configuration/packages/nav2_waypoint_follower

plugins/wait_at_waypoint.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <nav2_waypoint_followerplugin>: nav2_waypoint_follower plugin name defined in thewaypoint_task_executor_plugin_idparameter inWaypoint Follower.


key: chroma:document
string_value:
Title: Navigate Through Poses

URL: https://docs.nav2.org/behavior_trees/trees/nav_through_poses_recovery.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

Code Examples:

Language: unknown

File: FollowPath

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<RecoveryNode

number_of_retries=

"6"

name=

"NavigateRecovery"

>

<PipelineSequence

name=

"NavigateWithReplanning"

>

<ControllerSelector

selected_controller=

"{selected_controller}"

default_controller=

"FollowPath"

topic_name=

"controller_selector"

/>

<PlannerSelector

selected_planner=

"{selected_planner}"

default_planner=

"GridBased"

topic_name=

"planner_selector"

/>

<RateController

hz=

"0.333"

>

<RecoveryNode

number_of_retries=

"1"

name=

"ComputePathThroughPoses"

>

<ReactiveSequence>

<RemovePassedGoals

input_goals=

"{goals}"

output_goals=

"{goals}"

radius=

"0.7"

/>

<ComputePathThroughPoses

goals=


key: chroma:document
string_value:
radius=

"0.7"

/>

<ComputePathThroughPoses

goals=

"{goals}"

path=

"{path}"

planner_id=

"{selected_planner}"

error_code_id=

"{compute_path_error_code}"

/>

</ReactiveSequence>

<Sequence>

<WouldAPlannerRecoveryHelp

error_code=

"{compute_path_error_code}"

/>

<ClearEntireCostmap

name=

"ClearGlobalCostmap-Context"

service_name=

"global_costmap/clear_entirely_global_costmap"

/>

</Sequence>

</RecoveryNode>

</RateController>

<RecoveryNode

number_of_retries=

"1"

name=

"FollowPath"

>

<FollowPath

path=

"{path}"

controller_id=

"{selected_controller}"

error_code_id=

"{follow_path_error_code}"

/>

<Sequence>

<WouldAControllerRecoveryHelp

error_code=

"{follow_path_error_code}"

/>

<ClearEntireCostmap

name=

"ClearLocalCostmap-Context"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

</Sequence>

</RecoveryNode>

</PipelineSequence>

<Sequence>

<Fallback>

<WouldAControllerRecoveryHelp

error_code=

"{follow_path_error_code}"

/>

<WouldAPlannerRecoveryHelp


key: chroma:document
string_value:
"{follow_path_error_code}"

/>

<WouldAPlannerRecoveryHelp

error_code=

"{compute_path_error_code}"

/>

</Fallback>

<ReactiveFallback

name=

"RecoveryFallback"

>

<GoalUpdated/>

<RoundRobin

name=

"RecoveryActions"

>

<Sequence

name=

"ClearingActions"

>

<ClearEntireCostmap

name=

"ClearLocalCostmap-Subtree"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

<ClearEntireCostmap

name=

"ClearGlobalCostmap-Subtree"

service_name=

"global_costmap/clear_entirely_global_costmap"

/>

</Sequence>

<Spin

spin_dist=

"1.57"

error_code_id=

"{spin_error_code}"

/>

<Wait

wait_duration=

"5.0"

/>

<BackUp

backup_dist=

"0.30"

backup_speed=

"0.05"

error_code_id=

"{backup_error_code}"

/>

</RoundRobin>

</ReactiveFallback>

</Sequence>

</RecoveryNode>

</BehaviorTree>

</root>

```


key: chroma:document
string_value:
Title: DockRobot

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/DockRobot.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: DockRobot

```

<DockRobot

dock_id=

"{dock_id}"

error_code_id=

"{dock_error_code}"

/>

```


key: chroma:document
string_value:
Title: Dev Containers

URL: https://docs.nav2.org/development_guides/devcontainer_docs/index.html#prerequisites

Section: getting_started/index.html

--------------------------------------------------------------------------------

## What, Why, How? Lets briefly explain what dev containers are, why you should use them, and how they work.

## What is a Dev Container? A dev container is a Docker container that has all the tools and dependencies you need to develop the project. It runs in a self-contained environment and is isolated from other containers and your host machine. This lets you reliably develop for the project anywhere, notably for linux distributions targeted by ROS, regardless of your host machine’s operating system.


key: chroma:document
string_value:
## Why use a Dev Container? A dev container provides a common and consistent development environment. It ensures that everyone on the team is using the same tools and dependencies. It also makes it easy to switch between projects because each project can use a different container. This is especially useful if you work on multiple projects that use different versions of the same tools and dependencies, such as different versions of ROS.


key: chroma:document
string_value:
## How do Dev Containers work? When you open the project in VS Code, VS Code checks for the dev container configuration nested within the.devcontainerfolder under the project’s root directory. If it finds one, it can prompt you to reopen the project in a container. If you choose to do so, it launches the container, connects to it, and mounts your project folder inside the container. You can then use VS Code in the container just as you would locally. While setting up the container, VS Code can also attempt to passthrough useful aspects of your local environment, such as git user configurations, X11 sockets, and more. This is quite similar to earlier tools used to customize and run docker containers for development:

## Prerequisites To use dev containers, you’ll need the following:


key: chroma:document
string_value:
## Getting started Getting started using dev containers is as simple as opening the project in VS Code by either: following the notification prompt to reopen the project in a container, or explicitly opening the command palette (Crtl+Shift+P) and selectingRemote-Containers:ReopeninContainer. This will create a new container, install any extensions specified in the project’s default.devcontainer/devcontainer.jsonconfig file, and mount the project’s root directory as the workspace folder. Once the container is created, VS Code will connect to it and you can start developing. While waiting for the initial setup, feel free to stretch your legs, grab a coffee, or continue to read the following guides to learn more about creating and using dev containers, or how to visualize and leverage graphical user interfaces from a headless development environment.


key: chroma:document
string_value:
## Security A word of caution when using dev containers: they are powerful tools, but can be a security concern, as the capability of arbitrary code execution facilitated by IDE extensions to enable such automation and convenience remains inherently dual use. Before launching a dev container, ensure you trust the workspaces and authors. For example, when reviewing a pull request, verify patches remain benign and do not introduce any malicious code. Although such vigilance is merited whenever compiling and running patched code, using containers with either elevated privileges or filesystem access renders this diligence even more prudent.


key: chroma:document
string_value:
Title: ClearCostmapExceptRegion

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/ClearCostmapExceptRegion.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<ClearCostmapExceptRegion

name=

"ClearLocalCostmap

Subtree"

service_name=

"local_costmap/clear_except_local_costmap"

/>

```


key: chroma:document
string_value:
Title: ProgressCheckerSelector

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/ProgressCheckerSelector.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: transientlocal

```

<ProgressCheckerSelector

selected_progress_checker=

"{selected_progress_checker}"

default_progress_checker=

"precise_progress_checker"

topic_name=

"progress_checker_selector"

/>

```


key: chroma:document
string_value:
Title: Graceful Controller

URL: https://docs.nav2.org/configuration/packages/configuring-graceful-motion-controller.html#example

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Graceful Controller Parameters

## Example

Code Examples:

Language: unknown

File: initial_rotation

```

controller_server

:

ros__parameters

:

use_sim_time

:

True

controller_frequency

:

20.0

min_x_velocity_threshold

:

0.001

min_y_velocity_threshold

:

0.5

min_theta_velocity_threshold

:

0.001

progress_checker_plugins

:

[

"progress_checker"

]

# progress_checker_plugin: "progress_checker" For Humble and older

goal_checker_plugins

:

[

"goal_checker"

]

controller_plugins

:

[

"FollowPath"

]

progress_checker

:

plugin

:

"nav2_controller::SimpleProgressChecker"

required_movement_radius

:

0.5

movement_time_allowance

:

10.0

goal_checker

:

plugin

:

"nav2_controller::SimpleGoalChecker"

xy_goal_tolerance

:

0.25


key: chroma:document
string_value:
xy_goal_tolerance

:

0.25

yaw_goal_tolerance

:

0.25

stateful

:

True

FollowPath

:

plugin

:

nav2_graceful_controller::GracefulController

transform_tolerance

:

0.1

motion_target_dist

:

0.6

initial_rotation

:

true

initial_rotation_min_angle

:

0.75

final_rotation

:

true

allow_backward

:

false

k_phi

:

3.0

k_delta

:

2.0

beta

:

0.4

lambda

:

2.0

v_linear_min

:

0.1

v_linear_max

:

1.0

v_angular_max

:

5.0

slowdown_radius

:

1.5

```


key: chroma:document
string_value:
Title: InitialPoseReceived

URL: https://docs.nav2.org/configuration/packages/bt

plugins/conditions/InitialPoseReceived.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<InitialPoseReceived/>

```


key: chroma:document
string_value:
Title: Binary Filter Parameters

URL: https://docs.nav2.org/configuration/packages/costmap-plugins/binary_filter.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Example

Code Examples:

Language: unknown

File: <filtername>

```

global_costmap

:

global_costmap

:

ros__parameters

:

...

plugins

:

[

"static_layer"

,

"obstacle_layer"

,

"inflation_layer"

]

filters

:

[

"binary_filter"

]

...

binary_filter

:

plugin

:

"nav2_costmap_2d::BinaryFilter"

enabled

:

True

filter_info_topic

:

"/costmap_filter_info"

transform_tolerance

:

0.1

default_state

:

False

binary_state_topic

:

"/binary_state"

flip_threshold

:

50.0

```


key: chroma:document
string_value:
Title: FollowPath

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/FollowPath.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: FollowPath

```

<FollowPath

path=

"{path}"

controller_id=

"FollowPath"

goal_checker_id=

"precise_goal_checker"

server_name=

"FollowPath"

server_timeout=

"10"

error_code_id=

"{follow_path_error_code}"

/>

```


key: chroma:document
string_value:
Title: Groot - Interacting with Behavior Trees

URL: https://docs.nav2.org/tutorials/docs/using_groot.html#adding-a-custom-node

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview

Grootis the companion application of theBehaviorTree.CPPlibrary used to create, edit, and visualize behavior trees.

Behavior Trees are deeply integrated into Nav2, used as the main method of orchestrating task server logic across a complex navigation and autonomy stack.

Behavior Trees, in short BTs, consist of many nodes completing different tasks and control the flow of logic, similar to a Hierarchical or Finite State Machine, but organized in a tree structure.

These nodes are of types:Action,Condition,Control, orDecorator, and are described in more detail inNavigation ConceptsandBehaviorTree.CPP.


key: chroma:document
string_value:
Writing a New Behavior Tree Pluginoffers a well written example of creating a simpleActionnode if creating new BT nodes is of interest. This tutorial will focus solely on launching Groot, visualizing a Behavior Tree, and modifying that tree for a given customization, assuming a library of BT nodes. Luckily, Nav2 provides a robust number of BT nodes for your use out of the box, enumerated inNavigation Plugins.

A BT configuration file in BehaviorTree.CPP is an XML file. This is used to dynamically load the BT node plugins at run-time from the appropriate libraries mapped to their names. The XML format is definedin detail here. Therefore, Groot needs to have a list of nodes it has access to and important metadata about them like their type and ports (or parameters). We refer to this as the “palette” of nodes later in the tutorial.

In the video above you can see Groot side-by-side with RVIz and a test platform 100% equipped with ROS-enabled hardware from SIEMENS.


key: chroma:document
string_value:
Groot not only displays the current Behavior Tree while the robot is operating. Note: Before ROS 2 Humble, live Groot behavior tree monitoring during execution was supported in Nav2. This was removed due to buggy support in BT.CPP / Groot for changing behavior trees on the fly, seeGalactic to Humblefor more details.

## Visualize Behavior Trees

To display a Behavior Tree like that inFigure 3, we will first start the Groot executable.

Out of the box, Groot can only display Behavior Trees and nodes that are from the defaults in BT.CPP, since it does not know anything about Nav2 or your other projects.

Therefore, we must point Groot to our palette, or index, of Nav2 / custom behavior tree nodes:

If you select the default treenavigate_w_replanning_and_recovery.xml, then a Groot editor should look likeFigure 3.

## Edit Behavior Trees

Now that you have a Nav2 BT open in Groot in editor mode, you should be able to trivially modify it using the GUI.


key: chroma:document
string_value:
Starting from a screen like that shown inFigure 3, you can pull in new nodes from the side panel to add them to the workspace.

You may then connect the nodes using a “drag and drop” motion between the node’s input and output ports to assemble the new nodes into the tree.

If you select a given node, you can change metadata about it such as its name or values of parameterizable ports. When you’re done modifying, simply save the new configuration file and use that on your robot the next time!

## Adding A Custom Node

Each node in the behavior tree holds a specialized function.

Sometimes, its useful to create new nodes and add them to your palette during the design process - perhaps before the implementations themselves exist.

This helps designers abstract away the implementation specifics of the nodes from the higher level logic of the tree itself and how they’d like to interact with a given node (e.g. type, ports, etc).


key: chroma:document
string_value:
Within Groot, you may create new custom nodes to add to your tree and export these new nodes back to your palette.

Implementing the node itself needs to be done separately from Groot, which is described inWriting a New Behavior Tree Plugin.

Creating a new custom node can be started by clicking the orange marked icon inFigure 4, while Groot is in Editor mode.

This should load a new window, similar toFigure 5.

In this new window, it asks you to fill in the metadata about this new node, in order to create it.

It will ask you for standard information such as name (green box), type of node (orange box), and any optional ports for parameterization or access to blackboard variables (blue box).

After completing, selectOKinFigure 5, the new custom node should appear in blue in theTreeNode Paletteas inFigure 6.

Before starting to create a new BT based on the new custom nodes, it is recommend to export the newly created nodes to save in case of Groot crashing.


key: chroma:document
string_value:
This can be performed with the icon highlighted in green fromFigure 6.

The resulting XML output from the node created inFigure 5can be seen below.

You can see more examples inNav2’s BT Node Palette XML.

Code Examples:

Language: unknown

File: Action

```

<root>

<TreeNodesModel>

<Action

ID=

"MyAwesomeNewNode"

>

<input_port

name=

"key_name"

default=

"false"

>

coffee

</input_port>

<output_port

name=

"key_name2"

default=

"42"

>

Sense

of

life

</output_port>

<inout_port

name=

"next_target"

default=

"pancakes"

>

rolling

target

</inout_port>

</Action>

</TreeNodesModel>

</root>

```


key: chroma:document
string_value:
Title: Loopback Simulator

URL: https://docs.nav2.org/configuration/packages/configuring

loopback

sim.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

## Example

Code Examples:

Language: unknown File: /clock ``` loopback_simulator : ros__parameters : base_frame_id : "base_footprint" odom_frame_id : "odom" map_frame_id : "map" scan_frame_id : "base_scan" # tb4_loopback_simulator.launch.py remaps to 'rplidar_link' update_duration : 0.02 ```


key: chroma:document
string_value:
Title: TransformAvailable

URL: https://docs.nav2.org/configuration/packages/bt

plugins/conditions/TransformAvailable.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<TransformAvailable

parent=

"odom"

child=

"base_link"

/>

```


key: chroma:document
string_value:
Title: PathExpiringTimer

URL: https://docs.nav2.org/configuration/packages/bt

plugins/conditions/PathExpiringTimer.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<PathExpiringTimer

seconds=

"15"

path=

"{path}"

/>

```


key: chroma:document
string_value:
Title: GetPoseFromPath

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/GetPoseFromPath.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File:

2

```

<GetPoseFromPath

path=

"{path}"

index=

"

1"

pose=

"{goal}"

/>

```


key: chroma:document
string_value:
Title: PathDistCritic

URL: https://docs.nav2.org/configuration/packages/trajectory_critics/path_dist.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <name>: PathDistCritic critic name defined in the<dwb plugin>.criticsparameter defined inDWB Controller.


key: chroma:document
string_value:
Title: Collision Detector Node

URL: https://docs.nav2.org/configuration/packages/collision_monitor/configuring-collision-detector-node.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Features

Similarly to the Collision Monitor, the Collision Detector uses robot’s relative polygons to define “zones”.

However, unlike the Collision Monitor that uses different behavior models, the Collision Detector does not use any of them and therefore theaction_typeshould always be set tonone. If set to anything else, it will throw an error

The zones around the robot and the data sources are the same as for the Collision Monitor, with the exception of the footprint polygon, which is not supported by the Collision Detector.

## Parameters

## Polygons parameters

<polygonname>is the corresponding polygon name ID selected for this type.

## Observation sources parameters


key: chroma:document
string_value:
## Observation sources parameters

<sourcename>is the corresponding data source name ID selected for this type.

## Example

Here is an example of configuration YAML for the Collision Detector.

Code Examples:

Language: unknown

File: source_timeout:0.0

```

collision_detector

:

ros__parameters

:

base_frame_id

:

"base_footprint"

odom_frame_id

:

"odom"

transform_tolerance

:

0.5

source_timeout

:

5.0

base_shift_correction

:

True

polygons

:

[

"PolygonFront"

]

PolygonFront

:

type

:

"polygon"

points

:

"[[0.3,

0.3],

[0.3,

0.3],

[0.0,

0.3],

[0.0,

0.3]]"

action_type

:

"none"

min_points

:

4

visualize

:

True

polygon_pub_topic

:

"polygon_front"

observation_sources

:

[

"scan"

]

scan

:

source_timeout

:

0.2

type

:

"scan"

topic

:

"scan"

enabled

:

True

pointcloud

:

type

:

"pointcloud"

topic

:

"/intel_realsense_r200_depth/points"

min_height

:

0.1

max_height

:

0.5

enabled

:

True

```


key: chroma:document
string_value:
Title: Roadmaps

URL: https://docs.nav2.org/roadmap/roadmap.html#jazzy

roadmap

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Jazzy Roadmap

## Iron Roadmap

## Humble Roadmap


key: chroma:document
string_value:
Title: Smac Hybrid-A* Planner

URL: https://docs.nav2.org/configuration/packages/smac/configuring-smac-hybrid.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

## Example

Code Examples:

Language: unknown

File: >=1

```

planner_server

:

ros__parameters

:

planner_plugins

:

[

"GridBased"

]

use_sim_time

:

True

GridBased

:

plugin

:

"nav2_smac_planner::SmacPlannerHybrid"

# In Iron and older versions, "/" was used instead of "::"

downsample_costmap

:

false

# whether or not to downsample the map

downsampling_factor

:

1

# multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm)

tolerance

:

0.25

# dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found.

allow_unknown

:

true

# allow traveling in unknown space

max_iterations

:

1000000


key: chroma:document
string_value:
# allow traveling in unknown space

max_iterations

:

1000000

# maximum total iterations to search for before failing (in case unreachable), set to -1 to disable

max_on_approach_iterations

:

1000

# Maximum number of iterations after within tolerances to continue to try to find exact solution

max_planning_time

:

5.0

# max time in s for planner to plan, smooth

motion_model_for_search

:

"DUBIN"

# Hybrid-A* Dubin, Redds-Shepp

angle_quantization_bins

:

72

# Number of angle bins for search

analytic_expansion_ratio

:

3.5

# The ratio to attempt analytic expansions during search for final approach.

analytic_expansion_max_length

:

3.0

# For Hybrid/Lattice nodes: The maximum length of the analytic expansion to be considered valid to prevent unsafe shortcutting

analytic_expansion_max_cost

:

200.0

# The maximum single cost for any part of an analytic expansion to contain and be valid, except when necessary on approach to goal

analytic_expansion_max_cost_override

:

false


key: chroma:document
string_value:
analytic_expansion_max_cost_override

:

false

#  Whether or not to override the maximum cost setting if within critical distance to goal (ie probably required)

minimum_turning_radius

:

0.40

# minimum turning radius in m of path / vehicle

reverse_penalty

:

2.0

# Penalty to apply if motion is reversing, must be => 1

change_penalty

:

0.0

# Penalty to apply if motion is changing directions (L to R), must be >= 0

non_straight_penalty

:

1.2

# Penalty to apply if motion is non-straight, must be => 1

cost_penalty

:

2.0

# Penalty to apply to higher cost areas when adding into the obstacle map dynamic programming distance expansion heuristic. This drives the robot more towards the center of passages. A value between 1.3 - 3.5 is reasonable.

retrospective_penalty

:

0.015

lookup_table_size

:

20.0

# Size of the dubin/reeds-sheep distance window to cache, in meters.

cache_obstacle_heuristic

:

false


key: chroma:document
string_value:
cache_obstacle_heuristic

:

false

# Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static.

debug_visualizations

:

false

# For Hybrid nodes: Whether to publish expansions on the /expansions topic as an array of poses (the orientation has no meaning) and the path's footprints on the /planned_footprints topic. WARNING: heavy to compute and to display, for debug only as it degrades the performance.

use_quadratic_cost_penalty

:

False

downsample_obstacle_heuristic

:

True

allow_primitive_interpolation

:

False

smooth_path

:

True

# If true, does a simple and quick smoothing post-processing to the path

smoother

:

max_iterations

:

1000

w_smooth

:

0.3

w_data

:

0.2

tolerance

:

1.0e-10

do_refinement

:

true

refinement_num

:

2

```


key: chroma:document
string_value:
Title: Using Collision Monitor

URL: https://docs.nav2.org/tutorials/docs/using_collision_monitor.html#requirements

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview

This tutorial shows how to use a Collision Monitor with Nav2 stack. Based on this tutorial, you can setup it for your environment and needs.

## Requirements

It is assumed ROS2 and Nav2 dependent packages are installed or built locally.

Please make sure that Nav2 project is also built locally as it was made inBuild and Install.

## Configuring Collision Monitor

The Collision Monitor node has its owncollision_monitor_node.launch.pylaunch-file and preset parameters in thecollision_monitor_params.yamlfile for demonstration, though its trivial to add this to Nav2’s main launch file if being used in practice.

For the demonstration, two shapes will be created - an inner stop and a larger slowdown bounding boxes placed in the front of the robot:


key: chroma:document
string_value:
If more than 3 points will appear inside a slowdown box, the robot will decrease its speed to30%from its value.

For the cases when obstacles are dangerously close to the robot, inner stop zone will work.

For this setup, the following lines should be added intocollision_monitor_params.yamlparameters file. Stop box is named asPolygonStopand slowdown bounding box - asPolygonSlow:

For the working configuration, at least one data source should be added.

In current demonstration, it is used laser scanner (thoughPointCloud2and Range/Sonar/IR sensors are also possible), which is described by the following lines for Collision Monitor node:

Set topic names, frame ID-s and timeouts to work correctly with a default Nav2 setup.

The wholenav2_collision_monitor/params/collision_monitor_params.yamlfile in this case will look as follows:

## Configuring Collision Monitor with VelocityPolygon


key: chroma:document
string_value:
## Configuring Collision Monitor with VelocityPolygon

For this part of tutorial, we will set up the Collision Monitor withVelocityPolygontype for astopaction.VelocityPolygonallows the user to setup multiple polygons to cover the range of the robot’s velocity limits. For example, the user can configure different polygons for rotation, moving forward, or moving backward. The Collision Monitor will check the robot’s velocity against each sub polygon to determine the appropriate polygon to be used for collision checking.

In general, here are the steps to configure the Collision Monitor withVelocityPolygontype:

In this example, we will consider anon-holonomicrobot with linear velocity limits of-1.0to1.0m/s and angular velocity limits of-1.0to1.0rad/s. Thelinear_minandlinear_maxparameters of the sub polygons should be set to the robot’s linear velocity limits, while thetheta_minandtheta_maxparameters should be set to the robot’s angular velocity limits.


key: chroma:document
string_value:
Below is the example configuration using 4 sub-polygons to cover the full range of the robot’s velocity limits:

For holomic robots:

For holomic robots, theholonomicproperty should be set totrue. In this scenario, thelinear_minandlinear_maxparameters should cover the robot’s resultant velocity limits, while thetheta_minandtheta_maxparameters should cover the robot’s angular velocity limits. Additionally, there will be 2 more parameters,direction_start_angleanddirection_end_angle, to specify the resultant velocity direction. The covered direction will always span fromdirection_start_angletodirection_end_anglein thecounter-clockwisedirection.

Below shows some common configurations for holonomic robots that cover multiple directions of the resultant velocity:

## Preparing Nav2 stack

The Collision Monitor is designed to operate below Nav2 as an independent safety node.

It acts as a filter for thecmd_velmessages from the controller to avoid potential collisions.


key: chroma:document
string_value:
If no such zone is triggered, then thecmd_velmessage is used.

Else, it is scaled or set to stop as appropriate.

By default, the Collision Monitor is configured for usage with the Nav2 bringup package, running in parallel with thenavigation_launch.pylaunch file. For correct operation of the Collision Monitor with the Velocity Smoother, it is required to remove the Velocity Smoother’scmd_vel_smoothedremapping in thenavigation_launch.pybringup script as presented below. This will make the output topic of the Velocity Smoother to be untouched, which will be the input to the newly added Collision Monitor:

If you have changed Collision Monitor’s defaultcmd_vel_in_topicandcmd_vel_out_topicconfiguration, make sure Velocity Smoother’s default output topiccmd_vel_smoothedshould match to the input velocitycmd_vel_in_topicparameter value of the Collision Monitor node, and the output velocitycmd_vel_out_topicparameter value should be actualcmd_velto fit the replacement.

## Demo Execution


key: chroma:document
string_value:
## Demo Execution

Once Collision Monitor node has been tuned andcmd_veltopics adjusted, Collision Monitor node is ready to run.

For that, run Nav2 stack as written inGetting Started:

In parallel console, launch Collision Monitor node by using its launch-file:

Since bothPolygonStopandPolygonSlowpolygons will have their own publishers, they could be added to visualization as shown at the picture below:

Set the initial pose and then put Nav2 goal on map.

The robot will start its movement, slowing down while running near the obstacles, and stopping in close proximity to them:

Code Examples:

Language: unknown

File: PolygonSlow

```

polygons

:

[

"PolygonStop"

,

"PolygonSlow"

]

PolygonStop

:

type

:

"polygon"

points

:

"[[0.4,

0.3],

[0.4,

0.3],

[0.0,

0.3],

[0.0,

0.3]]"

action_type

:

"stop"

min_points

:

4

# max_points: 3 for Humble

visualize

:

True

polygon_pub_topic

:

"polygon_stop"

PolygonSlow

:

type

:

"polygon"

points

:

"[[0.6,

0.4],

[0.6,

0.4],

[0.0,

0.4],


key: chroma:document
string_value:
points

:

"[[0.6,

0.4],

[0.6,

0.4],

[0.0,

0.4],

[0.0,

0.4]]"

action_type

:

"slowdown"

min_points

:

4

# max_points: 3 for Humble

slowdown_ratio

:

0.3

visualize

:

True

polygon_pub_topic

:

"polygon_slowdown"

```

Language: unknown

File: PointCloud2

```

observation_sources

:

[

"scan"

]

scan

:

type

:

"scan"

topic

:

"scan"

```

Language: unknown

File: nav2_collision_monitor/params/collision_monitor_params.yaml

```

collision_monitor

:

ros__parameters

:

use_sim_time

:

True

base_frame_id

:

"base_footprint"

odom_frame_id

:

"odom"

cmd_vel_in_topic

:

"cmd_vel_smoothed"

cmd_vel_out_topic

:

"cmd_vel"

transform_tolerance

:

0.5

source_timeout

:

5.0

stop_pub_timeout

:

2.0

enable_stamped_cmd_vel

:

True

# False for Jazzy or older by default

polygons

:

[

"PolygonStop"

,

"PolygonSlow"

]

PolygonStop

:

type

:

"polygon"

points

:

"[[0.4,

0.3],

[0.4,

0.3],

[0.0,

0.3],

[0.0,

0.3]]"

action_type

:

"stop"

min_points

:

4


key: chroma:document
string_value:
0.3],

[0.0,

0.3]]"

action_type

:

"stop"

min_points

:

4

# max_points: 3 for Humble

visualize

:

True

polygon_pub_topic

:

"polygon_stop"

PolygonSlow

:

type

:

"polygon"

points

:

"[[0.6,

0.4],

[0.6,

0.4],

[0.0,

0.4],

[0.0,

0.4]]"

action_type

:

"slowdown"

min_points

:

4

# max_points: 3 for Humble

slowdown_ratio

:

0.3

visualize

:

True

polygon_pub_topic

:

"polygon_slowdown"

observation_sources

:

[

"scan"

]

scan

:

type

:

"scan"

topic

:

"scan"

```

Language: unknown

File: theta_max

```

polygons

:

[

"VelocityPolygonStop"

]

VelocityPolygonStop

:

type

:

"velocity_polygon"

action_type

:

"stop"

min_points

:

6

visualize

:

True

enabled

:

True

polygon_pub_topic

:

"velocity_polygon_stop"

velocity_polygons

:

[

"rotation"

,

"translation_forward"

,

"translation_backward"

,

"stopped"

]

holonomic

:

false

rotation

:

points

:

"[[0.3,

0.3],

[0.3,

0.3],

[-0.3,

0.3],

[-0.3,

0.3]]"

linear_min

:

0.0

linear_max

:

0.05


key: chroma:document
string_value:
0.3],

[-0.3,

0.3]]"

linear_min

:

0.0

linear_max

:

0.05

theta_min

:

1.0

theta_max

:

1.0

translation_forward

:

points

:

"[[0.35,

0.3],

[0.35,

0.3],

[-0.2,

0.3],

[-0.2,

0.3]]"

linear_min

:

0.0

linear_max

:

1.0

theta_min

:

1.0

theta_max

:

1.0

translation_backward

:

points

:

"[[0.2,

0.3],

[0.2,

0.3],

[-0.35,

0.3],

[-0.35,

0.3]]"

linear_min

:

1.0

linear_max

:

0.0

theta_min

:

1.0

theta_max

:

1.0

# This is the last polygon to be checked, it should cover the entire range of robot's velocities

# It is used as the stopped polygon when the robot is not moving and as a fallback if the velocity

# is not covered by any of the other sub-polygons

stopped

:

points

:

"[[0.25,

0.25],

[0.25,

0.25],

[-0.25,

0.25],

[-0.25,

0.25]]"

linear_min

:

1.0

linear_max

:

1.0

theta_min

:

1.0

theta_max

:

1.0

```

Language: unknown

File: navigation_launch.py

```

Node

(

package

=

'nav2_velocity_smoother'

,

executable

=

'velocity_smoother'

,


key: chroma:document
string_value:
,

executable

=

'velocity_smoother'

,

name

=

'velocity_smoother'

,

output

=

'screen'

,

respawn

=

use_respawn

,

respawn_delay

=

2.0

,

parameters

=

[

configured_params

],

arguments

=

[

'--ros-args'

,

'--log-level'

,

log_level

],

remappings

=

remappings

+

[(

'cmd_vel'

,

'cmd_vel_nav'

),

(

'cmd_vel_smoothed'

,

'cmd_vel'

)]),

+

[(

'cmd_vel'

,

'cmd_vel_nav'

)]),

...

ComposableNode

(

package

=

'nav2_velocity_smoother'

,

plugin

=

'nav2_velocity_smoother::VelocitySmoother'

,

name

=

'velocity_smoother'

,

parameters

=

[

configured_params

],

remappings

=

remappings

+

[(

'cmd_vel'

,

'cmd_vel_nav'

),

(

'cmd_vel_smoothed'

,

'cmd_vel'

)]),

+

[(

'cmd_vel'

,

'cmd_vel_nav'

)]),

```

Language: unknown

File: cmd_vel

```

ros2

launch

nav2_bringup

tb3_simulation_launch.py

headless:

=

False

```

Language: unknown

File: cmd_vel

```

ros2

launch

nav2_collision_monitor

collision_monitor_node.launch.py

```


key: chroma:document
string_value:
Title: StandardTrajectoryGenerator

URL: https://docs.nav2.org/configuration/packages/dwb

plugins/standard_traj_generator.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <dwbplugin>: DWB plugin name defined in thecontroller_plugin_idsparameter inController Server.


key: chroma:document
string_value:
Title: Iron to Jazzy

URL: https://docs.nav2.org/migration/Iron.html#new

collision

monitor

parameter

Section: getting_started/index.html

--------------------------------------------------------------------------------

## BehaviorTree.CPP upgraded to version 4.5+ Since we migrated from version 3.8 to 4.5, users must upgrade their XML and source code accordingly. You can refer to [this page](https://www.behaviortree.dev/docs/migration) for more details, but the main changes are:

## Added TwistStamped Option for Commands A new parameterenable_stamped_cmd_velhas been added to all of the publishers and subscribers ofcmd_veland related topics. This allows you to set the publication and subscription of TwistStamped messages over Twist messages to have frame and timestamp information of the set command. For now, this is default tofalseto not change current behavior, but it is planned to makeTwistStampedthe default behavior alongside Gazebo, ROS 2 Control, and related projects.


key: chroma:document
string_value:
## Add VelocityPolygon in Collision Monitor PR #3708addsVelocityPolgontype in Collision Monitor. This allows the user to setup multiple polygons to cover the range of the robot’s velocity limits. For example, the user can configure different polygons for rotation, moving forward, or moving backward. The Collision Monitor will check the robot’s velocity against each sub polygon to determine the appropriate polygon to be used for collision checking. The tutorial is available in theConfiguring Collision Monitor with VelocityPolygonsection.


key: chroma:document
string_value:
## Change polygon points parameter format in Collision Monitor PR #4020changes the format of the Polygon points parameter fromvector<double>tostring. This makes the polygon description more uniform across the Collision Monitor and Costmap_2D. Now we can define a polygon’s points in string that has avector<vector<double>>structure like this"[[p1.x,p1.y],[p2.x,p2.y],[p3.x,p3.y],...]"with a minimum of 4 points described. An example of a Square polygon will be written as follows.


key: chroma:document
string_value:
## Introduction of Soft-Real Time Action Servers PR #3914adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. The Simple Action Server now has arealtimeinput field exposed in the Controller Server via the parameteruse_realtime_prioritywhich will set the controller’s execution thread to a higher priority than the rest of the system to meet scheduling deadlines. To use this feature, you use set the following inside of/etc/security/limits.confto give userspace access to elevated prioritization permissions. This is currently only enabled in the Controller Server, who’s execution thread is sensitive to scheduling priorities, but could be set with other threads in the future if found necessary. The Collision Monitor and Velocity Smoothers also haduse_realtime_priorityadded as well!


key: chroma:document
string_value:
## opennav_coverageProject A new metapackage exists in:https://github.com/open-navigation/opennav_coveragewhich contains complete coverage navigator plugins, BT nodes, behavior tree demos, and coverage planning server based onFields2Cover. See that project for more information. It is on long-term trajectory for inclusion intoNav2, but there are still yet a few missing features from Fields2Cover before we can integrate that into the main project to be up to snuff in terms of all the major features and capabilities users would expect from a coverage planning system. If you’d like to see coverage planning in Nav2 directly, please consider contributingto the as-of-yet needed features described here.


key: chroma:document
string_value:
## opennav_dockingProject A new metapackage exists in:https://github.com/open-navigation/opennav_dockingwhich contains complete automatic charging dock framework, BT nodes, plugins, and demos. This allows for docking of any type of robot with any type of charging dock in a repeatable and generalized way. It will be integrated into Nav2 directly soon (Update June 2024: within Nav2 stack directlynav2_docking!) SeeUsing Docking Serverfor a tutorial on using this new capability! Thanks to NVIDIA for sponsoring this package!


key: chroma:document
string_value:
## Introduce a new Multi-Robot Bringup Launch PR #3572introduces a new way of bringup tb3 multi-robot that names ascloned_tb3_simulation_launch.pyfor simulation.cloned_tb3_simulation_launch.pyenables to bring up multiple robots with same parameter that described innav2_multirobot_param_all.yaml. And multiple robots are separated by namespaces which are given as a Launch Arguments. Existingmulti_tb3_simulation_launch.pywhich was utilized in previous is replaced withunique_tb3_simulation_launch.py, allowing for multiple unique robot instances utilizingnav2_multirobot_params_<N>.yamlconfiguration files.

## New option for the Voxel and Obstacle Layers PR #3612adds a new MaxWithoutUnknownOverwrite option to combination_method parameter in Voxel and Obstacle Layers. This can be used to make sure that the static map is the dominant source of information, and easily prevent the robot to go through places that are not present in the static map.


key: chroma:document
string_value:
## use_interpolation RPP Parameter Depreciated After a distribution of testing by many users, we have depreciated the use_interpolation parameter and it is now default on at all times without the ability to disable. It improves velocity smoothness and overall quality of tracking positively in all cases.

## Changes to MPPI Goal Critic The MPPI Goal critic’s formulation is changed to better keep up with speed on approach to goal instead of preemptively slowing too significantly. It also allows you to better use the weight to adjust the degree at which it slows more naturally. This change involves adjusting thethreshold_to_considerto be the same as your prediction horizon (e.g. samples * dt * max speed) for both the goal critic and path follower critic to have a good hand-off between them without deceleration.


key: chroma:document
string_value:
## Changes to MPPI Path Angle Critic MPPI’s Path Angle critic now has amodesetting to adjust behavior depending on robot’s desired behavioral traits. Previously, it penalized path orientations that deviated far the the robot’s forward orientation to turn the robot towards sharp changes in the path. This is still default (mode:0), but other modes now exist too. mode:1sets the penalization of path’s relative directions by either forward orientation or the opposite for reversing to allow for true bidirectional motion when one way or another is not preferable for a symmetric robot. This uses only the path’s relative points to the robot to decide which direction to incentivize. mode:2instead uses the path’s orientations when a feasible path is given from the Smac Planners or the Smoother server’s algorithms. This way, the globally planned orientations are followed rather than the based solely on the path’s relative points. This is useful for non-circular robots in highly confined settings where there may be


key: chroma:document
string_value:
robots in highly confined settings where there may be restricted opportunities to change directions so following the global path’s orientation are required to end in the orientation you require.


key: chroma:document
string_value:
## Changes to MPPI Path Handling For Directionality MPPI’s Path Align Critic and Path Handler object now have options to utilize the path’s orientation information to force the controller to change directions when and only when requested by a feasible planner. Whenenforce_path_inversionistrue, the path handler will prune the path to the first time the directions change to force the controller to plan to the inversion point and then be set the rest of the path, once in tolerance. The Path Align critic also contains a parameteruse_path_orientationswhich can be paired with it to incentivize aligning the path containing orientation information to better attempt to achieve path inversions where requestedandnot do them when not requested. See MPPI’s configuration guide for complete information.


key: chroma:document
string_value:
## Addition of new MPPI Cost Critic Analog to theObstacleCritic, theCostCriticis another obstacle avoiding critic alternative if theObstacleCriticis not working well for you. This critic uses the inflated costs in the costmap to score rather than distance to obstacles as theObstaclesCriticdoes. See the configuration guide for more information.

## MPPI Acceleration New to Jazzy, MPPI is 45% faster due to a weeks long optimization campaign. Enjoy!

## Move Error Code Enumerations PR #3693moves the enumeration codes from the goal to the result section.

## Substitution in parameter file Enabled substitution in parameter file. For example, you can write the following For more information about substitutions syntax, seehere

## Allow Behavior Server Plugins to Access The Action Result PR #3704allows behavior servers plugins to access and modify the action result.


key: chroma:document
string_value:
## Smac Planner Debug Param Name Change debug_visualizationsreplacesviz_expansionsparameter in Hybrid-A* to reflect the new inclusion of footprint debug information being published as well.

## Smac Planner On Approach to Goal Shortcutting Solutions PR #3962 adds new paramsanalytic_expansion_max_costandanalytic_expansion_max_cost_overridein extension ofanalytic_expansion_max_lengthin Humble to further limit potential shortcutting of paths near obstacles in close proximity to the goal. It uses a maximum cost parameter (default200) to tell if an expansion is closer to an obstacle than a user would like. If the expansion is critically close to the goal, then it may override this constraint ifanalytic_expansion_max_cost_overrideisfalse- allowing the constraint to be overridden to find a successful path solution, as it may be required. This PR also introduces additional analytic expansion scoring logic and edge case handling to improve path qualities by an analog heuristic function.


key: chroma:document
string_value:
## Added GPS Waypoint Follower Server This PR 2814adds thefollow_gps_waypointsaction server innav2_waypoint_follower. This server accepts a set of GPS goals instead of cartesian goals and provides all the other functionalities available onnav2_waypoint_follower. A new tutorial demonstrating its functionality was also added onPR 70 on navigation2_tutorialsand can be found on the General Tutorials directory on this website.

## Smac Planner Hybrid-A* New Features New featuresallow_primitive_interpolationwhich allows for more primitives in the search set,use_quadratic_cost_penaltyto impact the cost penalty order in the traversal and heuristic functions, anddownsample_obstacle_heuristicto optionally not downsample the obstacle heuristic’s costmap were added. The default behavior will remain the same. If you would like to use these new features, please check out the Smac Planner Hybrid-A* configuration guide.


key: chroma:document
string_value:
## New node in nav2_collision_monitor: Collision Detector In thisPR #3693A new node was introduced in the nav2_collision_monitor: Collision Detector. It works similarly to the Collision Monitor, but does not affect the robot’s velocity. It will only inform that data from the configured sources has been detected within the configured polygons via message to thecollision_detector_statetopic that might be used by any external module (e.g. switching LED or sound alarm in case of collision).

## Dynamic enabling/disabling of sources/polygons in Collision Monitor/Detector In thisPR #3825we added the ability to dynamically enable/disable sources and polygons in the Collision Monitor/Detector.


key: chroma:document
string_value:
## Expose action server’s result timeout In thisPR #3787the timeout for action server’s result was exposed in all nodes having action servers. This is because in thisPR #1012in rcl a change was introduced which makes action servers discard a goal handle if the result is not produced within 10 seconds, when the default was set to 15 minutes before. Since some actions in Nav2 may take more than 10 seconds to complete, the user has now the ability to set this value through theaction_server_result_timeoutparameter, which defaults to 15 minutes in thebt_navigatorsandwaypoint_followerand to 10 seconds in all other nodes.


key: chroma:document
string_value:
## RewrittenYaml could add new parameters to YAMLs NowRewrittenYamlwidely used in Nav2 launch-scripts, could do not only substitutions of ROS-parameters existing in original YAML, but rather additions of new parameters, that did not exist in the YAML. Certainly, these parameters should be declared for target ROS-nodes, otherwise they won’t be processed in run-time. In such functionality, they should be expressed in absolute values, separated by a dot. For example, the rewrite for aprune_distanceparameter of aFollowPathnode will look like'controller_server.ros__parameters.FollowPath.prune_distance':'1.0'in aparam_rewritesdictionary ofRewrittenYaml()argument. The change was intoroduced in the scope ofPR #3785fix.

## Simple Commander API Allows Multi-Robot Namespacing The Simple Navigator API now allows multi-robot namespacing by exposing anamespacefield in the constructor to allow you to specify the Nav2 stacks’ namespace for a robot or system. Seethis PR for details.


key: chroma:document
string_value:
## Change duration type in wait_action node In thisPR #3871the type of duration variable in wait_action node is changed from int to double, which allows you to use floating values for wait_action.

## The costmap activation fails when required transforms are not available In thisPR #3866the parameterinitial_transform_timeoutis added to the costmap. The activation of the costmap now fails, if the transformation from the robot base frame to the global frame does not become available during this timeout.

## Subtrees Obtain Shared Resources PR #3911gives all sub-trees in BT.CPP the same shared resources as the main tree (node, shared timeouts, etc).


key: chroma:document
string_value:
## Collision Monitor: added watchdog mechanism based onsource_timeoutparameter with default blocking behavior PR #3880adds a watchdog mechanism that stops the robot if a source data is not published yet, or if no new data is received within thesource_timeout`parameter, or if impossible to transform data to base frame.source_timeoutparameter can now be set per source: ifsource_timeoutis not set for a source, the value of the nodesource_timeoutparameter is used. Additionally, this watchdog mechanism can be disabled by settingsource_timeout:0.0.


key: chroma:document
string_value:
## BtActionServer: use native library haltTree() PR #3950changes the method used byBehaviorTreeEngine::haltAllActionsto halt the BT nodes to the bt.cpp native methodhaltTree(). Before this change, only the active BT node was halted when finishing the action. After this change, all BT nodes halt() methods are called. This is very convenient to handle cleaning operation (switch off your lights when leaving) in halt(). Also updated nav2_behavior_tree::BtActionServer::haltTree() to use the same. It is used nowhere in nav2 but is useful for external users (like me) that want for instance to halt the tree on preemption.

## Global Frame Removed from 2 BT Nodes The Global Frame was removed fromRemovePassedGoalsandGoalReachedBT nodes and instead using theframe_idof the goal’s headers for transformation.


key: chroma:document
string_value:
## Introduction ofCostmapUpdate.msg PR #3965introduces a new type of message -CostmapUpdate.msg. It is the update message related to theCostmap.msg. Now instead of sending the whole costmap in every message, such as withCostmap.msg, theCostmapUpdate.msgincludes only the area of the costmap that has changed since the previous update message. TheCostmap.msgis sent only once at the beginning, followed by the messages of theCostmapUpdate.msgtype. The idea is to mimic theOccupancyGrid.msgandOccupancyGridUpdate.msgbehavior. To activate this feature, the Costmap2D ROS parameteralways_send_full_costmaphas to be set tofalse. To subscribe toCostmap.msgandCostmapUpdate.msgit is recommended to use theCostmapSubscriberclass.

## Full Stack Uses Node Clocks The stack no longer contains wall timers or wall rates. It will now use the node clocks. This will be ROS Time for simulation whenuse_sim_timeis true. Else, it uses a steady clock.


key: chroma:document
string_value:
## New Graceful Motion Controller PR #4021introduces a new type of controller for differential robots based on a pose-following kinematic control law that generates a smooth and comfortable trajectory. SeeGraceful Controllerfor more information.

## Plugin Libraries in BT Navigator Only Includes Custom Nodes New to Jazzy, theplugin_lib_namesparameter implicitly includes all Nav2 BT nodes automatically. It is only required now to specify additional user-generated BT plugins to load.


key: chroma:document
string_value:
## New RViz Plugin for selecting Planners, Controllers, Goal Checkers, Progress Checkers and Smoothers In PR #4091a new RViz plugin was added to select the planner, controller, goal checker, progress checker, and smoother on the fly. The primary goal of this plugin is to facilitate the developers and easy integration testing of their configuration before deploying the robot in the intended application. In order to facilitate the dynamic selection of the specified components, the BT selector nodes for all these components were utilized and were updated to all the relevant BT nodes. Here we can see the working demo of the plugin: In the GIF, it can be seen that there are two controller_ids namely,FollowPathandHighSpeedFollowPath. By default, the one defined in the Behavior tree is utilized. In this case, theFollowPathis the default controller_id. The difference between the two controller_ids is that HighSpeedFollowPath has a higher max velocity compared to the FollowPath. This difference can be well noted in


key: chroma:document
string_value:
## RPP new optionalinterpolate_curvature_after_goalbehavior and fix conflict betweenuse_rotate_to_headingandallow_reversing In PR #4140a new optionalinterpolate_curvature_after_goalparameter (defaultfalse) was added that activates the interpolation of a carrot after the goal in order to maintain a constant curvature lookahead distance. This is to avoid instabilities at the end of the path on the generation of the angular speed. The carrot used for the linear speed computation stays the same. Interpolation is based on the orientation of the vector formed by the last 2 poses of the path. Hence paths of length 1 are rejected wheninterpolate_curvature_after_goalistrue. It can be used only whenuse_fixed_curvature_lookahead:true. Additionally, the conflict betweenuse_rotate_to_headingandallow_reversingwas fixed souse_rotate_to_headingcan now be used backward.


key: chroma:document
string_value:
## Cancel Checker Interface For GlobalPlanner PR #4148introduces a new interface for theGlobalPlannerto allow for the cancellation of the current planning task. Before the planners would continue to plan even if the goal was cancelled, now they can check it and stop planning if the goal is cancelled. New interface forGlobalPlanner::createPlan: This is implemented for all the planners in the stack, you can check them for the example use ofcancel_checkerfunction (simply checkcancel_checker()). Smac and Theta* planners have a new parameterterminal_checking_intervalwhich is the frequency of the cancel or timeout checking in terms of number of iterations.

## New BtActionServer/BtNavigator parameter PR #4209introduces a new boolean parameteralways_reload_bt_xml, which enables the possibility to always reload a requested behavior tree XML description, regardless of the currently active XML. This allows keeping the action server running while changing/developing the XML description.


key: chroma:document
string_value:
## New collision monitor parameter PR #4207introduces a new boolean parameterpolygon_subscribe_transient_local(value is false by default), which set the QoS durability for polygon topic or footprint topic subscription.

## New graceful cancellation API for Controllers PR #4136introduces a new graceful cancellation API for controllers. Previously when a goal was canceled, the controller would stop the robot immediately. This API allows the controller to stop the robot in a more graceful way. The new API is implemented in theRegulatedPurePursuitControllerby adding a new parametercancel_deceleration. So when the goal is canceled, a constant deceleration will be used while continuing to track the path to stop the robot instead of stopping immediately. This API can be should be added to all controllers that have acceleration limits.


key: chroma:document
string_value:
## Standardization of Plugin Naming with Double Colons (::) `PR #4220`_standardizes plugin naming across the Navigation2 package to use double colons (::), replacing the previous mixed use of slashes (/) and double colons. Affected plugins include:

## Collision monitor: dynamic radius for circle type polygons PR #4226introduces usage of parameter<polygon_name>.polygon_sub_topicfor circle type polygons. If parameter<polygon_name>.radiusis not set, collision monitor node subscribes to topic<polygon_name>.polygon_sub_topic(subscription type isstd_msgs/msg/Float32), and the current circle polygon radius will be updating accordingly to received messages on topic.


key: chroma:document
string_value:
## Static Layer: new parameterfootprint_clearing_enabled PR #4282introduces usage of parameterfootprint_clearing_enabledfor the static layer. It works similarly to thefootprint_clearing_enabledparameter in the obstacle and voxel layer. If set totrue, the static layer will clear the costmap cells that are within the robot’s footprint. It isfalseby default to keep the previous behavior.

## Lifecycle Node: added bond_heartbeat_period parameter (and allow disabling the bond mechanism) PR #4342adds the parameterbond_heartbeat_periodto the lifecycle nodes to customize the bond mechanism publishing period (on the/bondtopic). Default value unchanged to 0.1s. Disabled if inferior or equal to 0.0.


key: chroma:document
string_value:
## Rotation Shim Controller: new parameterrotate_to_goal_heading PR #4332introduces usage of parameterrotate_to_goal_headingfor the rotation shim controller. It allows the rotation shim controller to take back control when reaching the XY goal tolerance to perform a clean rotation towards the goal heading. Some controllers will do this internally, but it is a useful option for others.

## MPPI Controller: Addition of acceleration constraints PR #4352adds new parametersax_max,ax_min,ay_max,az_maxfor the MPPI controller. These parameters will enable the MPPI controller to generate local trajectories within the specified acceleration constraints.

## RegulatedPurePursuit Controller [RPP]: new parameteruse_cancel_deceleration PR #4441adds a new parameter use_cancel_deceleration for the regulated pure pursuit controllers. This parameter enables the controller to use a constant deceleration to stop the robot gracefully instead of stopping immediately when a goal is canceled.

Code Examples:

Language: unknown


key: chroma:document
string_value:
Code Examples:

Language: unknown

File: "[[p1.x,p1.y],[p2.x,p2.y],[p3.x,p3.y],...]"

```

PolygonFront

:

type

:

"polygon"

points

:

"[[0.3,

0.3],

[0.3,

0.3],

[0.0,

0.3],

[0.0,

0.3]]"

action_type

:

"none"

min_points

:

4

visualize

:

True

polygon_pub_topic

:

"polygon_front"

```

Language: unknown

File: /etc/security/limits.conf

```

<username> soft rtprio 99

<username> hard rtprio 99

```

Language: unknown

File: ObstaclesCritic

```

bt_navigator

:

ros__parameters

:

default_nav_to_pose_bt_xml

:

$(find

pkg

share my_package)/behavior_tree/my_nav_to_pose_bt.xml

```

Language: unknown

File: GlobalPlanner::createPlan

```

virtual

nav_msgs

::

msg

::

Path

createPlan

(

const

geometry_msgs

::

msg

::

PoseStamped

&

start

,

const

geometry_msgs

::

msg

::

PoseStamped

&

goal

,

std

::

function

<

bool

()

>

cancel_checker

)

```


key: chroma:document
string_value:
Title: Configuration Guide

URL: https://docs.nav2.org/configuration/index.html

Section: configuration/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
Title: PlannerSelector

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/PlannerSelector.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: transientlocal

```

<PlannerSelector

selected_planner=

"{selected_planner}"

default_planner=

"GridBased"

topic_name=

"planner_selector"

/>

```


key: chroma:document
string_value:
Title: Kinematic Parameters

URL: https://docs.nav2.org/configuration/packages/dwb

params/kinematic.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <dwbplugin>: DWB plugin name defined in thecontroller_plugin_idsparameter inController Server.


key: chroma:document
string_value:
Title: Behavior Server

URL: https://docs.nav2.org/configuration/packages/configuring-behavior-server.html#backup-behavior-parameters

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Behavior Server Parameters

## Default Plugins

When thebehavior_pluginsparameter is not overridden, the following default plugins are loaded:

## Spin Behavior Parameters

Spin distance is given from the action request

## BackUp Behavior Parameters

Backup distance, speed and time_allowance is given from the action request.

## DriveOnHeading Behavior Parameters

DriveOnHeading distance, speed and time_allowance is given from the action request.

## AssistedTeleop Behavior Parameters

AssistedTeleop time_allowance is given in the action request

## Example

Code Examples:

Language: unknown

File: plugin

```

behavior_server

:

ros__parameters

:

behavior_plugins

:

[

"spin"

,

"backup"

,

"drive_on_heading"

,

"wait"

]

spin

:

plugin


key: chroma:document
string_value:
"backup"

,

"drive_on_heading"

,

"wait"

]

spin

:

plugin

:

"nav2_behaviors::Spin"

# In Iron and older versions, "/" was used instead of "::"

backup

:

plugin

:

"nav2_behaviors::BackUp"

# In Iron and older versions, "/" was used instead of "::"

drive_on_heading

:

plugin

:

"nav2_behaviors::DriveOnHeading"

# In Iron and older versions, "/" was used instead of "::"

wait

:

plugin

:

"nav2_behaviors::Wait"

# In Iron and older versions, "/" was used instead of "::"

```

Language: unknown

File: TwistStamped

```

behavior_server

:

ros__parameters

:

local_costmap_topic

:

local_costmap/costmap_raw

local_footprint_topic

:

local_costmap/published_footprint

global_costmap_topic

:

global_costmap/costmap_raw

global_footprint_topic

:

global_costmap/published_footprint

cycle_frequency

:

10.0

behavior_plugins

:

[

"spin"

,

"backup"

,

"drive_on_heading"

,

"wait"

,

"assisted_teleop"

]

spin

:

plugin

:

"nav2_behaviors::Spin"


key: chroma:document
string_value:
]

spin

:

plugin

:

"nav2_behaviors::Spin"

# In Iron and older versions, "/" was used instead of "::"

backup

:

plugin

:

"nav2_behaviors::BackUp"

# In Iron and older versions, "/" was used instead of "::"

drive_on_heading

:

plugin

:

"nav2_behaviors::DriveOnHeading"

# In Iron and older versions, "/" was used instead of "::"

wait

:

plugin

:

"nav2_behaviors::Wait"

# In Iron and older versions, "/" was used instead of "::"

assisted_teleop

:

plugin

:

"nav2_behaviors::AssistedTeleop"

# In Iron and older versions, "/" was used instead of "::"

local_frame

:

odom

global_frame

:

map

robot_base_frame

:

base_link

transform_timeout

:

0.1

simulate_ahead_time

:

2.0

max_rotational_vel

:

1.0

min_rotational_vel

:

0.4

rotational_acc_lim

:

3.2

enable_stamped_cmd_vel

:

true

# default false in Jazzy or older

```


key: chroma:document
string_value:
Title: NavigateThroughPoses

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/NavigateThroughPoses.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<NavigateThroughPoses

goals=

"{goals}"

server_name=

"NavigateThroughPoses"

server_timeout=

"10"

error_code_id=

"{navigate_through_poses_error_code}"

behavior_tree=

"<some

path>/behavior_trees/navigate_through_poses_w_replanning_and_recovery.xml"

/>

```


key: chroma:document
string_value:
Title: RecoveryNode

URL: https://docs.nav2.org/configuration/packages/bt

plugins/controls/RecoveryNode.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<RecoveryNode

number_of_retries=

"1"

>

<!-

Add tree components here--

>

</RecoveryNode>

```


key: chroma:document
string_value:
Title: PoseProgressChecker

URL: https://docs.nav2.org/configuration/packages/nav2_controller

plugins/pose_progress_checker.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <nav2_controllerplugin>: nav2_controller plugin name defined in theprogress_checker_plugin_idparameter inController Server.


key: chroma:document
string_value:
Title: TruncatePathLocal

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/TruncatePathLocal.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<TruncatePathLocal

input_path=

"{path}"

output_path=

"{path_local}"

distance_forward=

"3.5"

distance_backward=

"2.0"

robot_frame=

"base_link"

/>

```


key: source
string_value:
/Users/ad12/ros2-rag/exported_docs/nav2/Navigate To Pose With Consistent Replanning And If Path Becomes Invalid.txt


key: chroma:document
string_value:
Title: Navigate To Pose With Consistent Replanning And If Path Becomes Invalid

URL: https://docs.nav2.org/behavior_trees/trees/nav_to_pose_with_consistent_replanning_and_if_path_becomes_invalid.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

Code Examples:

Language: unknown

File: FollowPath

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<RecoveryNode

number_of_retries=

"6"

name=

"NavigateRecovery"

>

<PipelineSequence>

<ControllerSelector

selected_controller=

"{selected_controller}"

default_controller=

"FollowPath"

topic_name=

"controller_selector"

/>

<PlannerSelector

selected_planner=

"{selected_planner}"

default_planner=

"GridBased"

topic_name=

"planner_selector"

/>

<RateController

hz=

"1.0"

name=

"RateControllerComputePathToPose"

>

<RecoveryNode

number_of_retries=

"1"

name=

"RecoveryComputePathToPose"

>

<Fallback

name=

"FallbackComputePathToPose"

>


key: chroma:document
string_value:
>

<Fallback

name=

"FallbackComputePathToPose"

>

<ReactiveSequence

name=

"CheckIfNewPathNeeded"

>

<Inverter>

<GlobalUpdatedGoal/>

</Inverter>

<IsPathValid

path=

"{path}"

/>

</ReactiveSequence>

<ComputePathToPose

goal=

"{goal}"

path=

"{path}"

planner_id=

"{selected_planner}"

error_code_id=

"{compute_path_error_code}"

/>

</Fallback>

<ClearEntireCostmap

name=

"ClearGlobalCostmap-Context"

service_name=

"global_costmap/clear_entirely_global_costmap"

/>

</RecoveryNode>

</RateController>

<RecoveryNode

number_of_retries=

"1"

name=

"RecoveryFollowPath"

>

<FollowPath

path=

"{path}"

controller_id=

"{selected_controller}"

error_code_id=

"{follow_path_error_code}"

/>

<ClearEntireCostmap

name=

"ClearLocalCostmap-Context"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

</RecoveryNode>

</PipelineSequence>

<ReactiveFallback

name=

"FallbackRecoveries"

>

<GoalUpdated/>

<RoundRobin

name=

"RecoveryActions"

>

<Sequence

name=

"ClearingActions"

>


key: chroma:document
string_value:
"RecoveryActions"

>

<Sequence

name=

"ClearingActions"

>

<ClearEntireCostmap

name=

"ClearLocalCostmap-Subtree"

service_name=

"local_costmap/clear_entirely_local_costmap"

/>

<ClearEntireCostmap

name=

"ClearGlobalCostmap-Subtree"

service_name=

"global_costmap/clear_entirely_global_costmap"

/>

</Sequence>

<Spin

name=

"SpinRecovery"

spin_dist=

"1.57"

/>

<Wait

name=

"WaitRecovery"

wait_duration=

"5.0"

/>

<BackUp

name=

"BackUpRecovery"

backup_dist=

"0.30"

backup_speed=

"0.05"

/>

</RoundRobin>

</ReactiveFallback>

</RecoveryNode>

</BehaviorTree>

</root>

```


key: chroma:document
string_value:
Title: Adding a New Nav2 Task Server

URL: https://docs.nav2.org/tutorials/docs/adding_a_nav2_task_server.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Lifecycle Nodes

The Lifecycle node is the first key component of a nav2 task server. Lifecycle nodes were introduced in ROS 2 to systematically manage the bringup and shutdown of the different nodes involved in the robot’s operation. The use of Lifecycle nodes ensures that all nodes are successfully instantiated before they begin their execution and Nav2 shuts down all nodes if there is any unresponsive node.

Lifecycle nodes contain state machine transitions that enable deterministic behavior in ROS 2 servers. The Lifecycle node transitions in Nav2 are handled by theLifecycleManager. The Lifecycle Manager transitions the states of the Lifecycle nodes and provides greater control over the state of a system.


key: chroma:document
string_value:
The primary states of a Lifecycle node areUnconfigured,Inactive,Active, andFinalized. A Lifecycle node starts in anUnconfiguredstate after being instantiated. The Lifecycle Manager transitions a node fromUnconfiguredtoInactiveby implementing theConfiguratingtransition. TheConfiguratingtransition sets up all configuration parameters and prepares any required setup such as memory allocation and the set up of the static publication and subscription topics. A node in theInactivestate is allowed to reconfigure its parameters and but cannot perform any processing. From theInactivestate, the Lifecycle Manager implements theActivatingtransition state to transition the node fromInactivetoActive, which is the main state. A node in theActivestate is allowed to perform any processing operation. In case a node crashes, the Lifecycle Manager shuts down the system to prevent any critical failures. On shutdown, the necessary cleanup operations are performed and the nodes are transitioned to theFinalizedstate


key: chroma:document
string_value:
performed and the nodes are transitioned to theFinalizedstate viaDeactivating,CleaningUp, andShuttingDowntransition states.


key: chroma:document
string_value:
You may wish to integrate your own nodes into the Nav2 framework or add new lifecycle nodes to your system. As an example, we will add a new notional lifecycle nodesensor_driver, and have it be controlled via the Nav2 Lifecycle Manager to ensure sensor feeds are available before activating navigation. You can do so by adding asensor_drivernode in your launch file and adding it to the list of nodes to be activated by thelifecycle_managerbefore navigation, as shown in the example below.


key: chroma:document
string_value:
In the snippet above, the nodes to be handled by the Lifecycle Manager are set using thenode_namesparameter. Thenode_namesparameter takes in an ordered list of nodes to bringup through the Lifecycle transition. As shown in the snippet, thenode_namesparameter takes inlifecycle_nodeswhich contains the list of nodes to be added to the Lifecycle Manager. The Lifecycle Manager implements bringup transitions (ConfiguringandActivating) to the nodes one-by-one and in order, while the nodes are processed in reverse order for shutdown transitions. Hence, thesensor_driveris listed first before the other navigation servers so that the sensor data is available before the navigation servers are activated.


key: chroma:document
string_value:
Two other parameters of the Lifecycle Manager areautostartandbond_timeout. Setautostarttotrueif you want to set the transition nodes to theActivestate on startup. Otherwise, you will need to manually trigger Lifecycle Manager to transition up the system. Thebond_timeoutsets the waiting time to decide when to transition down all of the nodes if a node is not responding.

## Composition

Composition is the second key component nav2 task servers that was introduced to reduce the memory and CPU resources by putting multiple nodes in a single process. In Nav2, Composition can be used to compose all Nav2 nodes in a single process instead of launching them separately. This is useful for deployment on embedded systems where developers need to optimize resource usage.

In the following section, we give an example on how to add a new Nav2 server, which we notionally call theroute_server, to our system.


key: chroma:document
string_value:
We make use of the launch files to compose different servers into a single process. The process is established by theComposableNodeContainercontainer that is populated with composition nodes viaComposableNode. This container can then be launched and used the same as any other Nav2 node.

## Error codes

Your nav2 task server may also wish to return a ‘error_code’ in its action response (though not required). If there are semantically meaningful and actionable types of failures for your system, this is a systemic way to communicate those failures which may be automatically aggregated into the responses of the navigation system to your application.

It is important to note that error codes from 0-9999 are reserved for internal nav2 servers with each server offset by 100 while external servers start at 10000 and end at 65535.

The table below shows the current servers along with the expected error code structure.


key: chroma:document
string_value:
Error codes are attached to the response of the action message. An example can be seen below for the route server. Note that by convention we set the error code field within the message definition toerror_code.

As stated in the message, the priority order of the errors should match the message order, 0 is reserved for NONE and the first error code in the sequence is reserved for UNKNOWN.

Since the the route server is a external server, the errors codes start at 10000 and go up to 10099.

In order to propagate your server’s error code to the rest of the system it must be added to the nav2_params.yaml file.

Theerror_code_id_namesinside of the BT Navigator define what error codes to look for on the blackboard by the server. The lowest error code of the sequence is then returned - whereas the code enums increase the higher up in the software stack - giving higher priority to lower-level failures.

## Conclusion


key: chroma:document
string_value:
## Conclusion

In this section of the guide, we have discussed Lifecycle Nodes, Composition and Error Codes which are new and important concepts in ROS 2. We also showed how to implement Lifecycle Nodes, Composition and Error Codes to your newly created nodes/servers with Nav2. These three concepts are helpful to efficiently run your system and therefore are encouraged to be used throughout Nav2.

Code Examples:

Language: unknown

File: lifecycle_manager

```

lifecycle_nodes

=

[

'sensor_driver'

,

'controller_server'

,

'smoother_server'

,

'planner_server'

,

'behavior_server'

,

'bt_navigator'

,

'waypoint_follower'

]

...

Node

(

package

=

'nav2_sensor_driver'

,

executable

=

'sensor_driver'

,

name

=

'sensor_driver'

,

output

=

'screen'

,

parameters

=

[

configured_params

],

remappings

=

remappings

),

Node

(

package

=

'nav2_lifecycle_manager'

,

executable

=

'lifecycle_manager'

,

name

=

'lifecycle_manager_navigation'

,

output

=

'screen'

,

parameters


key: chroma:document
string_value:
,

output

=

'screen'

,

parameters

=

[{

'autostart'

:

autostart

},

{

'node_names'

:

lifecycle_nodes

}]),

```

Language: unknown

File: ComposableNode()

```

container

=

ComposableNodeContainer

(

name

=

'my_container'

,

namespace

=

''

,

package

=

'rclcpp_components'

,

executable

=

'component_container'

,

composable_node_descriptions

=

[

ComposableNode

(

package

=

'nav2_route_server'

,

plugin

=

'nav2_route_server::RouteServer'

,

name

=

'nav2_route_server'

),

],

output

=

'screen'

,

)

```

Language: unknown

File: package.xml

```

<exec_depend>

nav2_route_server

</exec_depend>

```

Language: unknown

File: error_code

```

# Error codes

# Note: The expected priority order of the errors should match the message order

uint16

NONE

=

0

# 0 is reserved for NONE

uint16

UNKNOWN

=

10000

# first error code in the sequence is reserved for UNKNOWN

# User Error codes below

int16

INVALID_START

=

10001

int16

NO_VALID_ROUTE

=

10002


key: chroma:document
string_value:
INVALID_START

=

10001

int16

NO_VALID_ROUTE

=

10002

#goal definition

route_msgs/PoseStamped

goal

route_msgs/PoseStamped

start

string

route_id

---

#result definition

nav_msgs/Route

route

builtin_interfaces/Duration

route_time

uint16

error_code

---

```

Language: unknown

File: error_code

```

error_code_id_names

:

compute_path_error_code_id

follow_path_error_code_id

route_error_code_id

```


key: chroma:document
string_value:
Title: Humble to Iron

URL: https://docs.nav2.org/migration/Humble.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## New Behavior-Tree Navigator Plugins New inPR 3345, the navigator types are exposed to users as plugins that can be replaced or new navigator types added. The default behaviors of navigate to pose and navigate through poses continue to be default behavior but are now customizable with new action interface definitions. These plugins implement thenav2_core::BehaviorTreeNavigatorbase class, which must process the action request, feedback, and completion messages. The behavior tree is handled by this base class with as much general logic as possible abstracted away from users to minimize repetition. SeeWriting a New Navigator Pluginfor a tutorial about writing new navigator plugins.


key: chroma:document
string_value:
## Added Collision Monitor PR 2982adds new safety layer operating independently of Nav2 stack which ensures the robot to control the collisions with near obstacles, obtained from different sensors (LaserScan, PointCloud, IR, Sonars, etc…). SeeCollision Monitorfor more details. It is not included in the default bringup batteries included fromnav2_bringup.

## Removed use_sim_time from yaml PR #3131makes it possible to set the use_sim_time parameter from the launch file for multiple nodes instead of individually via the yaml files. If using the Nav2 launch files, you can optionally remove the use_sim_time parameter from your yaml files and set it via a launch argument.

## Run-time Speed up of Smac Planner The core data structure of the graph implementation in the Smac Planner framework was swapped out inPR 3201to using a specialized unordered map implementation. This speeds up the planner by 10% on trivial requests and reports up to 30% on complex plans that involve numerous rehashings.


key: chroma:document
string_value:
## Recursive Refinement of Smac and Simple Smoothers The number of recursive refinements for the Simple and Smac Planner Smoothers have been exposed under therefinement_numparameter. Previous behavior had this hardcoded ifdo_refinement=Trueto4. Now, default is2to help decrease out-of-the-box over smoothing reducing in paths closer to collision than probably ideal, but old behavior can be achieved by changing this to4.

## Simple Commander Python API PR 3159and follow-up PRs add in Costmap API in Python3 simple commander to receiveOccupancyGridmessages from Nav2 and be able to work with them natively in Python3, analog to the C++ Costmap API. It also includes a line iterator and collision checking object to perform footprint or other collision checking in Python3. See the Simple Commander API for more details.

## Smac Planner Start Pose Included in Path PR 3168adds the starting pose to the Smac Planners that was previously excluded during backtracing.


key: chroma:document
string_value:
## Parameterizable Collision Checking in RPP PR 3204adds makes collision checking for RPP optional (default on).

## Expanded Planner Benchmark Tests PR 3218adds launch files and updated scripts for performing objective random planning tests across the planners in Nav2 for benchmarking and metric computation.

## Smac Planner Path Tolerances PR 3219adds path tolerances to Hybrid-A* and State Lattice planners to return approximate paths if exact paths cannot be found, within a configurable tolerance aroun the goal pose.

## costmap_2d_node default constructor PR #3222changes the constructor used by the standalone costmap node. The new constructor does not set a name and namespace internally so it can be set via the launch file.


key: chroma:document
string_value:
## Feedback for Navigation Failures PR #3146updates the global planners to throw exceptions on planning failures. These exceptions get reported back to the planner server which in turn places a error code on the Behavior Tree Navigator’s blackboard for use in contextual error handling in the autonomy application. The following errors codes are supported (with more to come as necessary): Unknown, TF Error, Start or Goal Outside of Map, Start or Goal Occupied, Timeout, or No Valid Path Found. PR #3248updates the compute path through poses action to report planning failures. These exceptions get reported back to the planner server which in turn places a error code on the Behavior Tree Navigator’s blackboard for use in contextual error handling in the autonomy application. The following errors codes are supported (with more to come as necessary): Unknown, TF Error, Start or Goal Outside of Map, Start or Goal Occupied, Timeout, No Valid Path Found and No Waypoints given. PR #3227updates the controllers to throw


key: chroma:document
string_value:
No Waypoints given. PR #3227updates the controllers to throw exceptions on failures. These exceptions get reported back to the controller server which in turn places a error code on the Behavior Tree Navigatior’s blackboard for use in contextual error handling in the autonomy application. The following error codes are supported (with more to come as necessary): Unknown, TF Error, Invalid Path, Patience Exceeded, Failed To Make Progress, or No Valid Control. PR #3251pipes the highest priority error code through the bt_navigator and defines the error code structure. A new parameter for the the BT Navigator called “error_code_id_names” was added to the nav2_params.yaml to define the error codes to compare. The lowest error in the “error_code_id_names” is then returned in the action request (navigate to pose, navigate through poses waypoint follower), whereas the code enums increase the higher up in the software stack - giving higher priority to lower-level failures. The error codes produced from the servers


key: chroma:document
string_value:
lower-level failures. The error codes produced from the servers follow the guidelines stated below. Error codes from 0 to 9999 are reserved for nav2 while error codes from 10000-65535 are reserved for external servers. Each server has two “reserved” error codes. 0 is reserved for NONE and the first error code in the sequence is reserved for UNKNOWN. The current implemented servers with error codes are: This pr also updates the waypoint follower server to throw exceptions on failures. These exceptions get reported back to the server which in turn places a error code on the Behavior Tree Navigator’s blackboard for use in contextual error handling in the autonomy application. The following errors codes are supported (with more to come as necessary): Unknown and Task Executor Failed. SeeAdding a New Nav2 Task Serverand the PR for additional information.


key: chroma:document
string_value:
## Costmap Filters Costmap Filters now are have an ability to be enabled/disabled in run-time by callingtoggle_filterservice for appropriate filter (PR #3229). Added new binary flip filter, allowing e.g. to turn off camera in sensitive areas, turn on headlights/leds/other safety things or switch operating mode when robot is inside marked on mask areas (PR #3228).

## Savitzky-Golay Smoother Adding a new smoother algorithm, the Savitzky-Golay smoother to the smoother server plugin list. See the configuration guideSavitzky-Golay Smootherfor more details.

## Changes to Map yaml file path for map_server node in Launch PR #3174adds a way to set the path to map yaml file for the map_server node either from the yaml file or using the launch configuration parametermapgiving priority to the launch configuration parameter.yaml_filenameis no longer strictly required to be present innav2_params.yaml.


key: chroma:document
string_value:
## SmootherSelector BT Node PR #3283adds a BT node to set the smoother based on a topic or a default. See the configuration guideSimple Smootherfor more details.

## Publish Costmap Layers PR #3320adds the ability for the nav2_costmap_2d package to publish out costmap data associated with each layer.

## Give Behavior Server Access to Both Costmaps PR #3255adds the ability for a behavior to access the local and global costmap. To update behaviors, any reference to the global_frame must be updated to the local_frame parameter along with theconfigurationmethod which now takes in the local and global collision checkers. Lastly,getResourceInfomust be overridden to returnCostmapInfoType::LOCAL. Other options includeGLOBALif the behavior useses global costmap and/or footprint) orBOTHif both are required. This allows us to only create and maintain the minimum amount of expensive resources.


key: chroma:document
string_value:
## New Model Predictive Path Integral Controller The new Nav2 MPPI Controller is a predictive controller - a successor to TEB and pure path tracking MPC controllers - with Nav2. It uses a sampling based approach to select optimal trajectories, optimizing between successive iterations. It contains plugin-based objective functions for customization and extension for various behaviors and behavioral attributes. See the README.md andModel Predictive Path Integral Controllerpage for more detail.


key: chroma:document
string_value:
## Behavior Tree Uses Error Codes PR #3324adds three new condition nodes to check for error codes on the blackboard set by action BT nodes which contain them. TheAreErrorCodesPresentcondition node allows the user to specify the error code from the server along with the error codes to match against. TheWouldAControllerRecoveryHelpchecks if the active error code is UNKNOWN, PATIENCE_EXCEEDED, FAILED_TO_MAKE_PROGRESS or NO_VALID_CONTROL. If the error code is a match, the condition returnsSUCCESS. These error code are potentially able to be cleared by a controller recovery. TheWouldAPlannerRecoveryHelpchecks if the active error code is UNKNOWN, NO_VALID_CONTROL, or TIMEOUT. If the error code is a match, the condition returnsSUCCESS. These error code are potentially able to be cleared by a planner recovery. TheWouldASmootherRecoveryHelpchecks if the active error code is UNKNOWN, TIMEOUT, FAILED_TO_SMOOTH_PATH, or SMOOTHED_PATH_IN_COLLISION. If the error code is a match, the condition returnsSUCCESS. These error


key: chroma:document
string_value:
code is a match, the condition returnsSUCCESS. These error code are potentially able to be cleared by a smoother recovery.


key: chroma:document
string_value:
## Load, Save and Loop Waypoints from the Nav2 Panel in RViz PR #3165provides three new functionalities for the nav2 panel in RViz, they are: Looping functionality is not specific to the nav2 panel in RViz. Users utilizing nav2_waypoint_follower can take advantage of the changes made to the FollowWaypoint action, by specifying the desired number of loops in the action request that will be eventually sent to the nav2_waypoint_follower server.

## DWB Forward vs Reverse Pruning PR #3374adds a newforward_prune_distanceparameter in the DWB controller. It replaces theprune_distancefor forward path shortening, enabled through theshorten_transformed_planboolean parameter. This change allows to use different values for forward and backward path shortening.


key: chroma:document
string_value:
## More stable regulation on curves for long lookahead distances PR #3414adds a newuse_fixed_curvature_lookaheadparameter to the RPP controller. This makes slowing down on curve not dependent on the instantaneous lookahead point, but instead on a fixed distance set by the parametercurvature_lookahead_dist.

## Publish Collision Monitor State PR #3504adds a newstate_topicparameter to the CollisionMonitor. If specified, this optional parameter enables the state topic publisher. The topic reports the currently activated polygon action type and name.

## Renamed ROS-parameter in Collision Monitor PR #3513renamesmax_pointsparameter tomin_pointsand changes its meaning. Formerlymax_pointsmeant the maximum number of points inside the area still not triggering the action, whilemin_points- is a minimal number of points starting from the action to be initiated. In other wordsmin_pointsnow should be adjusted asmax_points+1.


key: chroma:document
string_value:
## New safety behavior model “limit” in Collision Monitor PR #3519adds a new collision monitor behavior modellimitthat restricts maximum linear and angular speed to specific values (linear_limitandangular_limit) if enough points are in the given shape.

## Velocity smoother applies deceleration when timeout PR #3512makes the VelocitySmoother apply the deceleration when the input command timeout.

## PoseProgressChecker plugin PR #3530adds a newnav2_controller::PoseProgressCheckerplugin. It builds on the behavior of theSimpleProgressCheckerby adding a new parameterrequired_movement_angle, allowing the plugin to considers that there is still progress when there is no translation movement, from the moment there is a rotation movement superior torequired_movement_anglewithin themovement_time_allowance.


key: chroma:document
string_value:
## Allow multiple goal checkers and change parameter progress_checker_plugin(s) name and type PR #3555initializes the progress checker plugin(s) in the same way as for the goal checker and controller plugins: it is now a list of string and was renamed fromprogress_checker_plugintoprogress_checker_plugins, and the type changed fromstringtovector<string>. This allows the initialization of multiple progress checkers that can be chosen from the addedprogress_checker_idfieldof theFollowPathaction. Beware that it is a breaking change and that configuration files will need to be updated.

## IsBatteryChargingCondition BT Node PR #3553adds a BT node to check if the battery is charging. See the configuration guideIsBatteryChargingfor more details.

## Behavior Server Error Codes PR #3569updates the behavior server plugins to provide error codes on failure.


key: chroma:document
string_value:
## New Denoise Costmap Layer Plugin PR #2567adds the new plugin for filtering noise on the costmap. Due to errors inVoxelLayerorObstacleLayermeasurements, salt and pepper noise may appear on thecostmap. This noise creates false obstacles that prevent the robot from finding the best path on the map. The newDenoiseLayerplugin is designed to filter out noise-induced standalone obstacles or small obstacles groups. This plugin allows you to add layer that will filter local or global costmap. More information aboutDenoiseLayerplugin and how it works could be foundhere.

## SmacPlannerHybrid viz_expansions parameter PR #3577adds a new parameter for visualising SmacPlannerHybrid expansions for debug purpose.


key: chroma:document
string_value:
Title: RemoveInCollisionGoals

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/RemoveInCollisionGoals.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: use_footprint=false

```

<RemoveInCollisionGoals

input_goals=

"{goals}"

output_goals=

"{goals}"

cost_threshold=

"254.0"

use_footprint=

"true"

service_name=

"/global_costmap/get_cost_global_costmap"

/>

```


key: chroma:document
string_value:
Title: Odometry Calibration

URL: https://docs.nav2.org/behavior_trees/trees/odometry_calibration.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<Repeat

num_cycles=

"3"

>

<Sequence

name=

"Drive in a square"

>

<DriveOnHeading

dist_to_travel=

"2.0"

speed=

"0.2"

time_allowance=

"12"

/>

<Spin

spin_dist=

"1.570796"

is_recovery=

"false"

/>

<DriveOnHeading

dist_to_travel=

"2.0"

speed=

"0.2"

time_allowance=

"12"

/>

<Spin

spin_dist=

"1.570796"

is_recovery=

"false"

/>

<DriveOnHeading

dist_to_travel=

"2.0"

speed=

"0.2"

time_allowance=

"12"

/>

<Spin

spin_dist=

"1.570796"

is_recovery=

"false"

/>

<DriveOnHeading

dist_to_travel=

"2.0"

speed=

"0.2"

time_allowance=

"12"

/>

<Spin

spin_dist=

"1.570796"

is_recovery=

"false"

/>

</Sequence>


key: chroma:document
string_value:
spin_dist=

"1.570796"

is_recovery=

"false"

/>

</Sequence>

</Repeat>

</BehaviorTree>

</root>

```


key: chroma:document
string_value:
Title: Navigating with Speed Limits

URL: https://docs.nav2.org/tutorials/docs/navigation2_with_speed_filter.html#enable-speed-filter

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview

This tutorial shows how to simply utilize Speed Filter which is designed to limit the maximum speed of robots in speed restriction areas marked on a map. This functionality is being covered bySpeedFiltercostmap filter plugin which will be enabled and used in this document.

## Requirements

It is assumed that ROS 2, Gazebo and TurtleBot3 packages are installed or built locally. Please make sure that the Nav2 project is also built locally as it was made inBuild and Install.

## Tutorial Steps

## 1. Prepare filter mask


key: chroma:document
string_value:
## Tutorial Steps

## 1. Prepare filter mask

As was written inNavigation Concepts, any Costmap Filter (including Speed Filter) is reading the data marked in a filter mask file. All information about filter masks, their types, detailed structure and how to make a new one is written in aNavigating with Keepout Zonestutorial at1.Preparefiltermaskschapter. The principal of drawing the filter mask for Speed Filter is the same as for Keepout Filter (to annotate a map with the requested zones), except thatOccupancyGridmask values have another meaning: these values are encoded speed limits for the areas corresponding to the cell on map.

Let’s look, how it is being decoded. As we know,OccupancyGridvalues are belonging to the[0..100]range. For Speed Filter0value means no speed limit in the area corresponding zero-cell on mask. Values from[1..100]range are being linearly converted into a speed limit value by the following formula:

where:

The decodedspeed_limitvalue may have one of two meanings:


key: chroma:document
string_value:
The decodedspeed_limitvalue may have one of two meanings:

The meaning used by Speed Filter is being read fromnav2_msgs/CostmapFilterInfomessages.

In this tutorial we will use the first type of speed restriction expressed in a percent from maximum robot speed.

Create a new image with a PGM/PNG/BMP format: copyturtlebot3_world.pgmmain map which will be used in a world simulation from a Nav2 repository to a newspeed_mask.pgmfile. Openspeed_mask.pgmin your favourite raster graphics editor and fill speed restricted areas with grey colors. In our example darker colors will indicate areas with higher speed restriction:

Area “A” is filled with40%gray color, area “B” - with70%gray, that means that speed restriction will take100%-40%=60%in area “A” and100%-70%=30%in area “B” from maximum speed value allowed for this robot.


key: chroma:document
string_value:
We will usescalemap mode with no thresholds. In this mode darker colors will have higherOccupancyGridvalues. E.g. for area “B” with70%of grayOccupancyGriddata will be equal to70. So in order to hit the target, we need to choosebase=100.0andmultiplier=-1.0. This will reverse the scaleOccupancyGridvalues to a desired one. No thresholds (free_threshoccupied_thresh) were chosen for the convenience in theyamlfile: to have 1:1 full range conversion of lightness value from filter mask -> to speed restriction percent.

After all speed restriction areas will be filled, save thespeed_mask.pgmimage.

Like all other maps, the filter mask should have its own YAML metadata file. Copyturtlebot3_world.yamltospeed_mask.yaml. Openspeed_mask.yamland update the fields as shown below (as mentioned before for thescalemode to use whole color lightness range there should be no thresholds:free_thresh=0.0andoccupied_thresh=1.0):


key: chroma:document
string_value:
Since Costmap2D does not support orientation, the last third “yaw” component of theoriginvector should be equal to zero (for example:origin:[1.25,-5.18,0.0]). Savespeed_mask.yamland the new filter mask is ready to use.

## 2. Configure Costmap Filter Info Publisher Server

Each costmap filter reads incoming meta-information (such as filter type or data conversion coefficients) in messages ofnav2_msgs/CostmapFilterInfotype. These messages are being published byCostmap Filter Info Publisher Server. The server is running as a lifecycle node. According to thedesign document,nav2_msgs/CostmapFilterInfomessages are going in a pair withOccupancyGridfilter mask topic. Therefore, along with Costmap Filter Info Publisher Server there should be enabled a new instance of Map Server configured to publish filter masks.


key: chroma:document
string_value:
In order to enable Speed Filter in your configuration, both servers should be enabled as lifecycle nodes in Python launch-file. For example, this might look as follows, though adding them as Composition Nodes to your Navigation Component Container is also possible:

where theparams_filevariable should be set to a YAML-file having ROS parameters for Costmap Filter Info Publisher Server and Map Server nodes. These parameters and their meaning are listed atMap Server / Saverpage. Please, refer to it for more information. The example ofparams_filecould be found below:

Note, that:

Ready-to-go standalone Python launch-script, YAML-file with ROS parameters and filter mask example for Speed Filter could be found in anav2_costmap_filters_demodirectory ofnavigation2_tutorialsrepository. To simply run Filter Info Publisher Server and Map Server tuned on Turtlebot3 standard simulation written atGetting Started, build the demo and launchcostmap_filter_info.launch.pyas follows:

## 3. Enable Speed Filter


key: chroma:document
string_value:
## 3. Enable Speed Filter

Costmap Filters are Costmap2D plugins. You can enable theSpeedFilterplugin in Costmap2D by addingspeed_filterto thepluginsparameter innav2_params.yaml. The Speed Filter plugin should have the following parameters defined:

Full list of parameters supported bySpeedFilterare listed at theSpeed Filter Parameterspage.

You can place the plugin either in theglobal_costmapsection innav2_params.yamlto have speed restriction mask applied to global costmap or in thelocal_costmapto apply speed mask to the local costmap. However,SpeedFilterplugin should never be enabled simultaneously for global and local costmaps. Otherwise, it can lead to unwanted multiple “speed restriction” - “no restriction” message chains on speed restriction boundaries, that will cause jerking of the robot or another unpredictable behaviour.

In this tutorial, we will enable Speed Filter for the global costmap. For this use the following configuration:


key: chroma:document
string_value:
As stated in thedesign, Speed Filter publishes speed restrictingmessagestargeted for a Controller Server so that it could restrict maximum speed of the robot when it needed. Controller Server has aspeed_limit_topicROS parameter for that, which should be set to the same as inspeed_filterplugin value. This topic in the map server could also be used to any number of other speed-restricted applications beyond the speed limiting zones, such as dynamically adjusting maximum speed by payload mass.

Setspeed_limit_topicparameter of a Controller Server to the same value as it set forspeed_filterplugin:

## 4. Run Nav2 stack

After Costmap Filter Info Publisher Server and Map Server were launched and Speed Filter was enabled for global/local costmap, run Nav2 stack as written inGetting Started:

For better visualization of speed filter mask, in RViz in the leftDisplayspane unfoldMapand changeTopicfrom/map-> to/speed_filter_mask.


key: chroma:document
string_value:
Set the goal behind the speed restriction areas and check that the filter is working properly: robot should slow down when going through a speed restricting areas. Below is how it might look (first picture shows speed filter enabled for the global costmap, second -speed_mask.pgmfilter mask):

Code Examples:

Language: unknown

File: [1..100]

```

speed_limit

=

filter_mask_data

multiplier

+

base

;

```

Language: unknown

File: occupied_thresh=1.0

```

image

:

turtlebot3_world.pgm

>

image

:

speed_mask.pgm

mode

:

trinary

>

mode

:

scale

occupied_thresh

:

0.65

free_thresh

:

0.196

>

occupied_thresh

:

1.0

free_thresh

:

0.0

```

Language: unknown

File: OccupancyGrid

```

import

os

from

ament_index_python.packages

import

get_package_share_directory

from

launch

import

LaunchDescription

from

launch.actions

import

DeclareLaunchArgument

from

launch.substitutions

import

LaunchConfiguration

from

launch_ros.actions

import

Node

from

nav2_common.launch

import


key: chroma:document
string_value:
import

Node

from

nav2_common.launch

import

RewrittenYaml

def

generate_launch_description

():

# Get the launch directory

costmap_filters_demo_dir

=

get_package_share_directory

(

'nav2_costmap_filters_demo'

)

# Create our own temporary YAML files that include substitutions

lifecycle_nodes

=

[

'filter_mask_server'

,

'costmap_filter_info_server'

]

# Parameters

namespace

=

LaunchConfiguration

(

'namespace'

)

use_sim_time

=

LaunchConfiguration

(

'use_sim_time'

)

autostart

=

LaunchConfiguration

(

'autostart'

)

params_file

=

LaunchConfiguration

(

'params_file'

)

mask_yaml_file

=

LaunchConfiguration

(

'mask'

)

# Declare the launch arguments

declare_namespace_cmd

=

DeclareLaunchArgument

(

'namespace'

,

default_value

=

''

,

description

=

'Top-level namespace'

)

declare_use_sim_time_cmd

=

DeclareLaunchArgument

(

'use_sim_time'

,

default_value

=

'true'

,

description

=

'Use simulation (Gazebo) clock if true'

)

declare_autostart_cmd

=


key: chroma:document
string_value:
)

declare_autostart_cmd

=

DeclareLaunchArgument

(

'autostart'

,

default_value

=

'true'

,

description

=

'Automatically startup the nav2 stack'

)

declare_params_file_cmd

=

DeclareLaunchArgument

(

'params_file'

,

default_value

=

os

.

path

.

join

(

costmap_filters_demo_dir

,

'params'

,

'speed_params.yaml'

),

description

=

'Full path to the ROS 2 parameters file to use'

)

declare_mask_yaml_file_cmd

=

DeclareLaunchArgument

(

'mask'

,

default_value

=

os

.

path

.

join

(

costmap_filters_demo_dir

,

'maps'

,

'speed_mask.yaml'

),

description

=

'Full path to filter mask yaml file to load'

)

# Make re-written yaml

param_substitutions

=

{

'use_sim_time'

:

use_sim_time

,

'yaml_filename'

:

mask_yaml_file

}

configured_params

=

RewrittenYaml

(

source_file

=

params_file

,

root_key

=

namespace

,

param_rewrites

=

param_substitutions

,

convert_types

=

True

)

# Nodes launching commands

start_lifecycle_manager_cmd

=

Node

(

package

=


key: chroma:document
string_value:
start_lifecycle_manager_cmd

=

Node

(

package

=

'nav2_lifecycle_manager'

,

executable

=

'lifecycle_manager'

,

name

=

'lifecycle_manager_costmap_filters'

,

namespace

=

namespace

,

output

=

'screen'

,

emulate_tty

=

True

,

# https://github.com/ros2/launch/issues/188

parameters

=

[{

'use_sim_time'

:

use_sim_time

},

{

'autostart'

:

autostart

},

{

'node_names'

:

lifecycle_nodes

}])

start_map_server_cmd

=

Node

(

package

=

'nav2_map_server'

,

executable

=

'map_server'

,

name

=

'filter_mask_server'

,

namespace

=

namespace

,

output

=

'screen'

,

emulate_tty

=

True

,

# https://github.com/ros2/launch/issues/188

parameters

=

[

configured_params

])

start_costmap_filter_info_server_cmd

=

Node

(

package

=

'nav2_map_server'

,

executable

=

'costmap_filter_info_server'

,

name

=

'costmap_filter_info_server'

,

namespace

=

namespace

,

output

=

'screen'

,

emulate_tty

=

True

,

# https://github.com/ros2/launch/issues/188


key: chroma:document
string_value:
=

True

,

# https://github.com/ros2/launch/issues/188

parameters

=

[

configured_params

])

ld

=

LaunchDescription

()

ld

.

add_action

(

declare_namespace_cmd

)

ld

.

add_action

(

declare_use_sim_time_cmd

)

ld

.

add_action

(

declare_autostart_cmd

)

ld

.

add_action

(

declare_params_file_cmd

)

ld

.

add_action

(

declare_mask_yaml_file_cmd

)

ld

.

add_action

(

start_lifecycle_manager_cmd

)

ld

.

add_action

(

start_map_server_cmd

)

ld

.

add_action

(

start_costmap_filter_info_server_cmd

)

return

ld

```

Language: unknown

File: params_file

```

costmap_filter_info_server

:

ros__parameters

:

use_sim_time

:

true

type

:

1

filter_info_topic

:

"/costmap_filter_info"

mask_topic

:

"/speed_filter_mask"

base

:

100.0

multiplier

:

1.0

filter_mask_server

:

ros__parameters

:

use_sim_time

:

true

frame_id

:

"map"

topic_name

:

"/speed_filter_mask"

yaml_filename

:

"speed_mask.yaml"

```

Language: unknown


key: chroma:document
string_value:
yaml_filename

:

"speed_mask.yaml"

```

Language: unknown

File: costmap_filter_info.launch.py

```

$

mkdir

p

~/tutorials_ws/src

$

cd

~/tutorials_ws/src

$

git

clone

https://github.com/ros-navigation/navigation2_tutorials.git

$

cd

~/tutorials_ws

$

colcon

build

--symlink-install

--packages-select

nav2_costmap_filters_demo

$

source

~/tutorials_ws/install/setup.bash

$

ros2

launch

nav2_costmap_filters_demo

costmap_filter_info.launch.py

params_file:

=

src/navigation2_tutorials/nav2_costmap_filters_demo/params/speed_params.yaml

mask:

=

src/navigation2_tutorials/nav2_costmap_filters_demo/maps/speed_mask.yaml

```

Language: unknown

File: SpeedFilter

```

global_costmap:

global_costmap:

ros__parameters:

...

plugins: ["static_layer", "obstacle_layer", "inflation_layer"]

filters: ["speed_filter"]

...

speed_filter:

plugin: "nav2_costmap_2d::SpeedFilter"

enabled: True

filter_info_topic: "/costmap_filter_info"

speed_limit_topic: "/speed_limit"

```

Language: unknown


key: chroma:document
string_value:
speed_limit_topic: "/speed_limit"

```

Language: unknown

File: speed_filter

```

controller_server:

ros__parameters:

...

speed_limit_topic: "/speed_limit"

```

Language: unknown

File: speed_filter

```

ros2

launch

nav2_bringup

tb3_simulation_launch.py

```


key: chroma:document
string_value:
Title: Eloquent to Foxy

URL: https://docs.nav2.org/migration/Eloquent.html#eloquent

migration

Section: concepts/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
## General The lifecycle manager was split into 2 unique lifecycle managers. They are thenavigation_lifecycle_managerandlocalization_lifecycle_manager. This gives each process their own manager to allow users to switch between SLAM and localization without effecting Navigation. It also reduces the redundant code innav2_bringup. The lifecycle manager also now containsBondconnections to each lifecycle server. This means that if a server crashes or exits, the lifecycle manager will be constantly checking and transition down its lifecycle nodes for safety. This acts as a watchdog during run-time to complement the lifecycle manager’s transitioning up and down from active states. Seethis PR for details. A fix to the BT navigator was added to remove a rare issue where it may crash due to asynchronous issues. As a result, a behavior tree is created for each navigation request rather than resetting an existing tree. The creation of this tree will add a small amount of latency. Proposals to reduce this latency will


key: chroma:document
string_value:
small amount of latency. Proposals to reduce this latency will be considered before the next release.


key: chroma:document
string_value:
## Server Updates All plugin servers (controller, planner, recovery) now supports the use of multiple plugins. This can be done by loading a map of plugins, mapping the name of the plugin to its intended use-case. Each server defines a parameter where the list of names for the plugins to be loaded can be defined. The type of plugin to be mapped to a particular name has to be defined using thepluginparameter in the plugin namespace for each name defined in the server plugin list. Each name in the plugin parameter list is expected to have thepluginparameter defined. An example:controller_serverdefines the parametercontroller_pluginswhere a list of plugin names can be defined: FollowPathcontroller is of typedwb_local_planner/DWBLocalPlannerandDynamicFollowPathof typeteb_local_planner/TEBLocalPlanner. Each plugin will load the parameters in their namespace, e.g.FollowPath.max_vel_x, rather than globally in the server namespace. This will allow multiple plugins of the same type with different parameters and


key: chroma:document
string_value:
multiple plugins of the same type with different parameters and reduce conflicting parameter names. DWB Contains new parameters as an update relative to the ROS 1 updates,see here for more information. Additionally, the controller and planner interfaces were updated to include astd::stringnameparameter on initialization. This was added to the interfaces to allow the plugins to know the namespace it should load its parameters in. E.g. for a controller to find the parameterFollowPath.max_vel_x, it must be given its name,FollowPathto get this parameter. All plugins will be expected to look up parameters in the namespace of its given name.


key: chroma:document
string_value:
## New Plugins Many new behavior tree nodes were added. These behavior tree nodes are now BT plugins and dynamically loadable at run-time using behavior tree cpp v3. The default behavior trees have been upgraded to stop the recovery behaviours and trigger a replanning when the navigation goal is preempted. Seenav2_behavior_treefor a full listing, orNavigation Pluginsfor the current list of behavior tree plugins and their descriptions. These plugins are set as default in thenav2_bt_navigatorbut may be overridden by thebt_pluginsparameter to include your specific plugins. Original GitHub tickets:


key: chroma:document
string_value:
## Map Server Re-Work map_saverwas re-worked and divided into 2 parts: CLI and server. CLI part is a command-line tool that listens incoming map topic, saves map once into a file and finishes its work. This part is remained to be almost untouched: CLI executable was renamed frommap_savertomap_saver_cliwithout changing its functionality. Server is a new part. It spins in the background and can be used to save map continuously through asave_mapservice. By each service request it tries to listen incoming map topic, receive a message from it and write obtained map into a file. map_serverwas dramatically simplified and cleaned-up.OccGridLoaderwas merged withMapServerclass as it is intended to work only with oneOccupancyGridtype of messages in foreseeable future. Map Server now has newmap_iodynamic library. All functions saving/loadingOccupancyGridmessages were moved frommap_serverandmap_saverhere. These functions could be easily called from any part of external ROS 2 code even if Map Server node was not started.


key: chroma:document
string_value:
of external ROS 2 code even if Map Server node was not started. map_loaderwas completely removed fromnav2_util. All its functionality already present inmap_io. Please use it in your code instead. Please refer to theoriginal GitHub ticketandMap Server READMEfor more information.


key: chroma:document
string_value:
## New Particle Filter Messages New particle filter messages for particle clouds were added to include the particle weights along with their poses.nav2_msgs/Particledefines a single particle with a pose and a weight in a particle cloud.nav2_msgs/ParticleClouddefines a set of particles, each with a pose and a weight. AMCLnow publishes its particle cloud as anav2_msgs/ParticleCloudinstead of ageometry_msgs/PoseArray. See here for more information.


key: chroma:document
string_value:
## Selection of Behavior Tree in each navigation action TheNavigateToPoseaction allows now to select in the action request the behavior tree to be used bybt_navigatorfor carrying out the navigation action through thestringbehavior_treefield. This field indicates the absolute path of the xml file that will be used to use to carry out the action. If no file is specified, leaving this field empty, the default behavior tree specified in thedefault_bt_xml_filenameparameterwill be used. This functionality has been discussed inthe ticket #1780, and carried out inthe pull request #1784.

## FollowPoint Capability A new behavior treefollowpoint.xmlhas added. This behavior tree makes a robot follow a dynamically generated point, keeping a certain distance from the target. This can be used for moving target following maneuvers. This functionality has been discussed inthe ticket #1660, and carried out inthe pull request #1859.


key: chroma:document
string_value:
## New Costmap Layer The range sensor costmap has not been ported to navigation2 asnav2_costmap_2d::RangeSensorLayer". It uses the same probabilistic model as theROS1layer as well as much of the same interface. Documentation on parameters has been added to docs/parameters and the docs.nav2.org underConfigurationGuide.

Code Examples:

Language: unknown

File: controller_plugins

```

controller_server

:

ros__parameters

:

controller_plugins

:

[

"FollowPath"

,

"DynamicFollowPath"

]

FollowPath

:

plugin

:

"dwb_core/DWBLocalPlanner"

max_vel_x

:

0.26

DynamicFollowPath

:

plugin

:

"teb_local_planner/TEBLocalPlanner"

max_vel_x

:

0.5

```


key: chroma:document
string_value:
Title: Tuning Guide

URL: https://docs.nav2.org/tuning/index.html

Section: tuning/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
## Inflation Potential Fields Many users and ecosystem navigation configuration files the maintainers find are really missing the point of the inflation layer. While it’s true that you can simply inflate a small radius around the walls to weight against critical collisions, thetruevalue of the inflation layer is creating a consistent potential field around the entire map. Some of the most popular tuning guides for ROS Navigation / Nav2 evencall this out specificallythat there’s substantial benefit to creating a gentle potential field across the width of the map - after inscribed costs are applied - yet very few users do this in practice. This habit actually results in paths produced by NavFn, Theta*, and Smac Planner to be somewhat suboptimal. They really want to look for a smooth potential field rather than wide open 0-cost spaces in order to stay in the middle of spaces and deal with close-by moving obstacles better. It will allow search to be weighted towards freespace far before the search algorithm


key: chroma:document
string_value:
be weighted towards freespace far before the search algorithm runs into the obstacle that the inflation is caused by, letting the planner give obstacles as wide of a berth as possible. So it is the maintainers’ recommendation, as well as all other cost-aware search planners available in ROS, to increase your inflation layer cost scale and radius in order to adequately produce a smooth potential across the entire map. For very large open spaces, its fine to have 0-cost areas in the middle, but for halls, aisles, and similar;please create a smooth potential to provide the best performance.


key: chroma:document
string_value:
## Robot Footprint vs Radius Nav2 allows users to specify the robot’s shape in 2 ways: a geometricfootprintor the radius of a circle encompassing the robot. In ROS (1), it was pretty reasonable to always specify a radius approximation of the robot, since the global planning algorithms didn’t use it and the local planners / costmaps were set up with the circular assumption baked in. However, in Nav2, we now have multiple planning and controller algorithms that make use of the full SE2 footprint. If your robot is non-circular, it is recommended that you give the planners and controllers the actual, geometric footprint of your robot. This will allow the planners and controllers to plan or create trajectories into tighter spaces. For example, if you have a very long but skinny robot, the circular assumption wouldn’t allow a robot to plan into a space only a little wider than your robot, since the robot would not fit length-wise. The kinematically feasible planners (e.g. Smac Hybrid-A*, Smac State Lattice) will


key: chroma:document
string_value:
planners (e.g. Smac Hybrid-A*, Smac State Lattice) will use the SE2 footprint for collision checking to create kinematically feasible plans, if provided with the actual footprint. As of December, 2021 all of the controller plugins support full footprint collision checking to ensure safe path tracking. If you provide a footprint of your robot, it will be used to make sure trajectories are valid and it is recommended you do so. It will prevent a number of “stuck robot” situations that could have been easily avoided. If your robot is truly circular, continue to use therobot_radiusparameter. The three valid reasons for a non-circular robot to use the radius instead:


key: chroma:document
string_value:
## Rotate in Place Behavior Using theRotation Shim Controller, a robot will simply rotate in place before starting to track a holonomic path. This allows a developer to tune a controller plugin to be optimized for path tracking and give you clean rotations, out of the box. This was added due to quirks in some existing controllers whereas tuning the controller for a task can make it rigid – or the algorithm simply doesn’t rotate in place when working with holonomic paths (if that’s a desirable trait). The result is an awkward, stuttering, or whipping around behavior when your robot’s initial and path heading’s are significantly divergent. Giving a controller a better starting point to start tracking a path makes tuning the controllers significantly easier and creates more intuitive results for on-lookers (in one maintainer’s opinion). Note: If using a non-holonomic, kinematically feasible planner (e.g. Smac Hybrid-A*, Smac State Lattice), this is not a necessary behavioral optimization. This class of planner


key: chroma:document
string_value:
not a necessary behavioral optimization. This class of planner will create plans that take into account the robot’s starting heading, not requiring any rotation behaviors. This behavior is most optimially for:


key: chroma:document
string_value:
## Planner Plugin Selection Nav2 provides a number of planning plugins out of the box. For a first-time setup, seeSetting Up Navigation Pluginsfor a more verbose breakdown of algorithm styles within Nav2, andNavigation Pluginsfor a full accounting of the current list of plugins available (which may be updated over time). In general though, the following table is a good guide for the optimal planning plugin for different types of robot bases: If you are using a non-circular robot with very limited compute, it may be worth assessing the benefits of using one of the holonomic planners (e.g. particle assumption planners). It is the recommendation of the maintainers to start using one of the more advanced algorithms appropriate for your platformfirst, but to scale back the planner if need be. The run-time of the feasible planners are typically on par (or sometimes faster) than their holonomic counterparts, so don’t let the more recent nature of them fool you. Since the planning problem is primarily driven by the


key: chroma:document
string_value:
fool you. Since the planning problem is primarily driven by the robot type, the table accurately summarizes the advice to users by the maintainers. Within the circular robot regime, the choice of planning algorithm is dependent on application and desirable behavior. NavFn will typically make broad, sweeping curves; Theta* prefers straight lines and supports them at any angle; and Smac 2D is essentially a classical A* algorithm with cost-aware penalties.


key: chroma:document
string_value:
## Controller Plugin Selection Nav2 provides a number of controller plugins out of the box. For a first-time setup, seeSetting Up Navigation Pluginsfor a more verbose breakdown of algorithm styles within Nav2, andNavigation Pluginsfor a full accounting of the current list of plugins available (which may be updated over time). In general though, the following table is a good first-order description of the controller plugins available for different types of robot bases: All of the above controllers can handle both circular and arbitrary shaped robots in configuration. Regulated Pure Pursuit is good for exact path following and is typically paired with one of the kinematically feasible planners (eg State Lattice, Hybrid-A*, etc) since those paths are known to be drivable given hard physical constraints. However, it can also be applied to differential drive robots who can easily pivot to match any holonomic path. This is the plugin of choice if you simply want your robot to follow the path, rather exactly,


key: chroma:document
string_value:
you simply want your robot to follow the path, rather exactly, without any dynamic obstacle avoidance or deviation. It is simple and geometric, as well as slowing the robot in the presence of near-by obstaclesandwhile making sharp turns. DWB and MPPI are both options that will track paths, but also diverge from the path if there are dynamic obstacles present (in order to avoid them). DWB does this through scoring multiple trajectories on a set of critics. These trajectories are also generated via plugins that can be replaced, but support out of the box Omni and Diff robot types within the valid velocity and acceleration restrictions. These critics are plugins that can be selected at run-time and contain weights that may be tuned to create the desired behavior, such as minimizing path distance, minimizing distance to the goal or headings, and other action penalties that can be designed. This does require a bit of tuning for a given platform, application, and desired behavior, but it is possible to tune DWB to


key: chroma:document
string_value:
and desired behavior, but it is possible to tune DWB to do nearly any single thing well. MPPI on the other hand implements an optimization based approach, using randomly perturbed samples of the previous optimal trajectory to maximize a set of plugin-based objective functions. In that regard, it is similar to DWB however MPPI is a far more modern and advanced technique that will deal with dynamic agents in the environment and create intelligent behavior due to the optimization based trajectory planning, rather then DWB’s constant action model. MPPI however does have moderately higher compute costs, but it is highly recommended to go this route and has received considerable development resources and attention due to its power. This typically works pretty well out of the box, but to tune for specific behaviors, you may have to retune some of the parameters. The README.md file for this package contains details on how to tune it efficiently. The Rotation Shim Plugin helps assist plugins like TEB and DWB (among


key: chroma:document
string_value:
Shim Plugin helps assist plugins like TEB and DWB (among others) to rotate the robot in place towards a new path’s heading before starting to track the path. This allows you to tune your local trajectory planner to operate with a desired behavior without having to worry about being able to rotate on a dime with a significant deviation in angular distance over a very small euclidean distance. Some controllers when heavily tuned for accurate path tracking are constrained in their actions and don’t very cleanly rotate to a new heading. Other controllers have a ‘spiral out’ behavior because their sampling requires some translational velocity, preventing it from simply rotating in place. This helps alleviate that problem and makes the robot rotate in place very smoothly. Finally, Vector Pursuit is another good path tracking solution and just like RPP, is paired with a kinematically feasible planner. It is a bit more advanced than RPP in the sense it also takes path heading into account. Vector Pursuit can handle


key: chroma:document
string_value:
also takes path heading into account. Vector Pursuit can handle complex paths at high speeds, but it is still a simple geometric controller thus requiring low computation resources.


key: chroma:document
string_value:
## Caching Obstacle Heuristic in Smac Planners Smac’s Hybrid-A* and State Lattice Planners provide an option,cache_obstacle_heuristic. This can be used to cache the heuristic to use between replannings to the same goal pose, which can increase the speed of the plannersignificantly(40-300% depending on many factors). The obstacle heuristic is used to steer the robot into the middle of spaces, respecting costs, and drives the kinematically feasible search down the corridors towards a valid solution. Think of it like a 2D cost-aware search to “prime” the planner about where it should go when it needs to expend more effort in the fully feasible search / SE2 collision checking. This is useful to speed up performance to achieve better replanning speeds. However, if you cache this heuristic, it will not be updated with the most current information in the costmap to steer search. During planning, the planner will still make use of the newest cost information for collision checking,thusly this will not impact the


key: chroma:document
string_value:
for collision checking,thusly this will not impact the safety of the path. However, it may steer the search down newly blocked corridors or guide search towards areas that may have new dynamic obstacles in them, which can slow things down significantly if entire solution spaces are blocked. Therefore, it is the recommendation of the maintainers to enable this only when working in largely static (e.g. not many moving things or changes, not using live sensor updates in the global costmap, etc) environments when planning across large spaces to singular goals. Between goal changes to Nav2, this heuristic will be updated with the most current set of information, so it is not very helpful if you change goals very frequently.


key: chroma:document
string_value:
## Costmap2D Plugins Costmap2D has a number of plugins that you can use (including the availability for you to create your own!). In addition, costmap filters: -KeepoutFilter: Marks keepout, higher weighted, or lower weighted zones in the costmap -SpeedFilter: Reduces or increases robot speeds based on position -BinaryFilter: Enables or disables a binary topic when in particular zones Note: When the costmap filters can be paired with theVectorObjectserver to use vectorized zones rather than map rastered zones sharing the same software.


key: chroma:document
string_value:
## Nav2 Launch Options Nav2’s launch files are made to be very configurable. Obviously for any serious application, a user should usenav2_bringupas the basis of their navigation launch system, but should be moved to a specific repository for a users’ work. A typical thing to do is to have a<robot_name>_navconfiguration package containing the launch and parameter files. Withinnav2_bringup, there is a main entryfiletb3_simulation_launch.py. This is the main file used for simulating the robot and contains the following configurations:

## Other Pages We’d Love To Offer If you are willing to chip in, some ideas are inhttps://github.com/ros-navigation/docs.nav2.org/issues/204, but we’d be open to anything you think would be insightful!


key: chroma:document
string_value:
Title: Model Predictive Path Integral Controller

URL: https://docs.nav2.org/configuration/packages/configuring-mppic.html#path-align-critic

Section: getting_started/index.html

--------------------------------------------------------------------------------

## MPPI Parameters

## Trajectory Visualization

## Path Handler

## Ackermann Motion Model

## Constraint Critic

This critic penalizes trajectories that have components outside of the set dynamic or kinematic constraints

## Goal Angle Critic

This critic incentivizes navigating to achieve the angle of the goal posewhen in reasonable proximity to goal

## Goal Critic

This critic incentivizes navigating spatially towards the goal when in reasonable proximity to goal

## Obstacles Critic

This critic incentivizes navigating away from obstacles and critical collisions using either a circular robot point-check or full SE2 footprint check using distances from obstacles.

## Cost Critic


key: chroma:document
string_value:
## Cost Critic

This critic incentivizes navigating away from obstacles and critical collisions using either a circular robot point-check or full SE2 footprint check using the costmap values.

## Path Align Critic

This critic incentivizes aligning with the global path, if relevant. It does not implement path following behavior.

## Path Angle Critic

This critic penalizes trajectories at a high relative angle to the path. This helps the robot make sharp turns when necessary due to large accumulated angular errors.

## Path Follow Critic

This critic incentivizes making progress along the path. This is what drives the robot forward along the path.

## Prefer Forward Critic

This critic incentivizes moving in the forward direction, rather than reversing.

## Twirling Critic

This critic penalizes unnecessary ‘twisting’ with holonomic vehicles. It adds a constraint on the rotation angle to keep it consistent.

## Velocity Deadband Critic


key: chroma:document
string_value:
## Velocity Deadband Critic

This critic penalizes velocities that fall below the deadband threshold, helping to mitigate hardware limitations on certain platforms.

## Example

## Notes to Users

## General Words of Wisdom

Themodel_dtparameter generally should be set to the duration of your control frequency. So if your control frequency is 20hz, this should be0.05. However, you may also set it lowerbut not larger.

Visualization of the trajectories usingvisualizeuses compute resources to back out trajectories for visualization and therefore slows compute time. It is not suggested that this parameter is set totrueduring a deployed use, but is a useful debug instrument while tuning the system, but use sparingly. Visualizing 2000 batches @ 56 points at 30 hz isa lot.


key: chroma:document
string_value:
The most common parameters you might want to start off changing are the velocity profiles (vx_max,vx_min,wz_max, andvy_maxif holonomic) and themotion_modelto correspond to your vehicle. Its wise to consider theprune_distanceof the path plan in proportion to your maximum velocity and prediction horizon. The only deeper parameter that will likely need to be adjusted for your particular settings is the Obstacle critics’repulsion_weightsince the tuning of this is proprtional to your inflation layer’s radius. Higher radii should correspond to reducedrepulsion_weightdue to the penalty formation (e.g.inflation_radius-min_dist_to_obstacle). If this penalty is too high, the robot will slow significantly when entering cost-space from non-cost space or jitter in narrow corridors. It is noteworthy, but likely not necessary to be changed, that the Obstacle critic may use the full footprint information ifconsider_footprint=true, though comes at an increased compute cost.


key: chroma:document
string_value:
Otherwise, the parameters have been closely pre-tuned by your friendly neighborhood navigator to give you a decent starting point that hopefully you only need to retune for your specific desired behavior lightly (if at all). Varying costmap parameters or maximum speeds are the actions which require the most attention, as described below:

## Prediction Horizon, Costmap Sizing, and Offsets


key: chroma:document
string_value:
## Prediction Horizon, Costmap Sizing, and Offsets

As this is a predictive planner, there is some relationship between maximum speed, prediction times, and costmap size that users should keep in mind while tuning for their application. If a controller server costmap is set to 3.0m in size, that means that with the robot in the center, there is 1.5m of information on either side of the robot. When your prediction horizon (time_steps*model_dt) at maximum speed (vx_max) is larger than this, then your robot will be artificially limited in its maximum speeds and behavior by the costmap limitation. For example, if you predict forward 3 seconds (60 steps @ 0.05s per step) at 0.5m/s maximum speed, theminimumrequired costmap radius is 1.5m - or 3m total width.


key: chroma:document
string_value:
The same applies to the Path Follow and Align offsets from furthest. In the same example if the furthest point we can consider is already at the edge of the costmap, then further offsets are thresholded because they’re unusable. So its important while selecting these parameters to make sure that the theoretical offsets can exist on the costmap settings selected with the maximum prediction horizon and velocities desired. Setting the threshold for consideration in the path follower + goal critics as the same as your prediction horizon can make sure you have clean hand-offs between them, as the path follower will otherwise attempt to slow slightly once it reaches the final goal pose as its marker.


key: chroma:document
string_value:
The Path Follow critic cannot drive velocities greater than the projectable distance of that velocity on the available path on the rolling costmap. The Path Align criticoffset_from_furthestrepresents the number of path points a trajectory passes through while tracking the path. If this is set either absurdly low (e.g. 5) it can trigger when a robot is simply trying to start path tracking causing some suboptimal behaviors and local minima while starting a task. If it is set absurdly high (e.g. 50) relative to the path resolution and costmap size, then the critic may never trigger or only do so when at full-speed. A balance here is wise. A selection of this value to be ~30% of the maximum velocity distance projected is good (e.g. if a planner produces points every 2.5cm, 60 can fit on the 1.5m local costmap radius. If the max speed is 0.5m/s with a 3s prediction time, then 20 points represents 33% of the maximum speed projected over the prediction horizon onto the path). When in


key: chroma:document
string_value:
projected over the prediction horizon onto the path). When in doubt,prediction_horizon_s*max_speed/path_resolution/3.0is a good baseline.


key: chroma:document
string_value:
## Obstacle, Inflation Layer, and Path Following

There also exists a relationship between the costmap configurations and the Obstacle critic configurations. If the Obstacle critic is not well tuned with the costmap parameters (inflation radius, scale) it can cause the robot to wobble significantly as it attempts to take finitely lower-cost trajectories with a slightly lower cost in exchange for jerky motion. It may also perform awkward maneuvers when in free-space to try to maximize time in a small pocket of 0-cost over a more natural motion which involves moving into some low-costed region. Finally, it may generally refuse to go into costed space at all when starting in a free 0-cost space if the gain is set disproportionately higher than the Path Follow scoring to encourage the robot to move along the path. This is due to the critic cost of staying in free space becoming more attractive than entering even lightly costed space in exchange for progression along the task.


key: chroma:document
string_value:
Thus, care should be taken to select weights of the obstacle critic in conjunction with the costmap inflation radius and scale so that a robot does not have such issues. How I (Steve, your friendly neighborhood navigator) tuned this was to first create the appropriate obstacle critic behavior desirable in conjunction with the inflation layer parameters. Its worth noting that the Obstacle critic converts the cost into a distance from obstacles, so the nature of the distribution of costs in the inflation isn’t overly significant. However, the inflation radius and the scale will define the cost at the end of the distribution where free-space meets the lowest cost value within the radius. So testing for quality behavior when going over that threshold should be considered.


key: chroma:document
string_value:
As you increase or decrease your weights on the Obstacle, you may notice the aforementioned behaviors (e.g. won’t overcome free to non-free threshold). To overcome them, increase the FollowPath critic cost to increase the desire for the trajectory planner to continue moving towards the goal. Make sure to not overshoot this though, keep them balanced. A desirable outcome is smooth motion roughly in the center of spaces without significant close interactions with obstacles. It shouldn’t be perfectly following a path yet nor should the output velocity be wobbling jaggedly.


key: chroma:document
string_value:
Once you have your obstacle avoidance behavior tuned and matched with an appropriate path following penalty, tune the Path Align critic to align with the path. If you design exact-path-alignment behavior, its possible to skip the obstacle critic step as highly tuning the system to follow the path will give it less ability to deviate to avoid obstacles (though it’ll slow and stop). Tuning the critic weight for the Obstacle critic high will do the job to avoid near-collisions but the repulsion weight is largely unnecessary to you. For others wanting more dynamic behavior, itcanbe beneficial to slowly lower the weight on the obstacle critic to give the path alignment critic some more room to work. If your path was generated with a cost-aware planner (like all provided by Nav2) and providing paths sufficiently far from obstacles for your satisfaction, the impact of a slightly reduced Obstacle critic with a Path Alignment critic will do you well. Not over-weighting the path align critic will allow the robot to


key: chroma:document
string_value:
over-weighting the path align critic will allow the robot to  deviate from the path to get around dynamic obstacles in the scene or other obstacles not previous considered during path planning. It is subjective as to the best behavior for your application, but it has been shown that MPPI can be an exact path tracker and/or avoid dynamic obstacles very fluidly and everywhere in between. The defaults provided are in the generally right regime for a balanced initial trade-off.


key: chroma:document
string_value:
Code Examples:

Language: unknown

File: inflation_radius

```

controller_server

:

ros__parameters

:

controller_frequency

:

30.0

FollowPath

:

plugin

:

"nav2_mppi_controller::MPPIController"

time_steps

:

56

model_dt

:

0.05

batch_size

:

2000

vx_std

:

0.2

vy_std

:

0.2

wz_std

:

0.4

vx_max

:

0.5

vx_min

:

0.35

vy_max

:

0.5

wz_max

:

1.9

ax_max

:

3.0

ax_min

:

3.0

ay_max

:

3.0

az_max

:

3.5

iteration_count

:

1

prune_distance

:

1.7

transform_tolerance

:

0.1

temperature

:

0.3

gamma

:

0.015

motion_model

:

"DiffDrive"

visualize

:

false

reset_period

:

1.0

# (only in Humble)

regenerate_noises

:

false

TrajectoryVisualizer

:

trajectory_step

:

5

time_step

:

3

AckermannConstraints

:

min_turning_r

:

0.2

critics

:

[

"ConstraintCritic"

,

"CostCritic"

,

"GoalCritic"

,

"GoalAngleCritic"

,

"PathAlignCritic"

,

"PathFollowCritic"

,

"PathAngleCritic"

,

"PreferForwardCritic"

]

ConstraintCritic

:

enabled

:

true


key: chroma:document
string_value:
]

ConstraintCritic

:

enabled

:

true

cost_power

:

1

cost_weight

:

4.0

GoalCritic

:

enabled

:

true

cost_power

:

1

cost_weight

:

5.0

threshold_to_consider

:

1.4

GoalAngleCritic

:

enabled

:

true

cost_power

:

1

cost_weight

:

3.0

threshold_to_consider

:

0.5

PreferForwardCritic

:

enabled

:

true

cost_power

:

1

cost_weight

:

5.0

threshold_to_consider

:

0.5

# ObstaclesCritic:

#   enabled: true

#   cost_power: 1

#   repulsion_weight: 1.5

#   critical_weight: 20.0

#   consider_footprint: false

#   collision_cost: 10000.0

#   collision_margin_distance: 0.1

#   near_goal_distance: 0.5

#   inflation_radius: 0.55 # (only in Humble)

#   cost_scaling_factor: 10.0 # (only in Humble)

CostCritic

:

enabled

:

true

cost_power

:

1

cost_weight

:

3.81

critical_cost

:

300.0

consider_footprint

:

true

collision_cost

:

1000000.0

near_goal_distance

:

1.0

trajectory_point_step

:

2

PathAlignCritic

:

enabled

:

true

cost_power

:

1

cost_weight

:


key: chroma:document
string_value:
:

enabled

:

true

cost_power

:

1

cost_weight

:

14.0

max_path_occupancy_ratio

:

0.05

trajectory_point_step

:

4

threshold_to_consider

:

0.5

offset_from_furthest

:

20

use_path_orientations

:

false

PathFollowCritic

:

enabled

:

true

cost_power

:

1

cost_weight

:

5.0

offset_from_furthest

:

5

threshold_to_consider

:

1.4

PathAngleCritic

:

enabled

:

true

cost_power

:

1

cost_weight

:

2.0

offset_from_furthest

:

4

threshold_to_consider

:

0.5

max_angle_to_furthest

:

1.0

mode

:

0

# VelocityDeadbandCritic:

#   enabled: true

#   cost_power: 1

#   cost_weight: 35.0

#   deadband_velocities: [0.05, 0.05, 0.05]

# TwirlingCritic:

#   enabled: true

#   twirling_cost_power: 1

#   twirling_cost_weight: 10.0

```


key: chroma:document
string_value:
Title: AreErrorCodesPresent

URL: https://docs.nav2.org/configuration/packages/bt

plugins/conditions/AreErrorCodesPresent.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example Error codes to check are defined in another port. Error codes to check are defined to be 101, 107 and 119.

Code Examples:

Language: unknown

File: FAILURE

```

<AreErrorCodesPresent

error_code=

"{error_code}"

error_codes_to_check=

"{error_codes_to_check}"

/>

```

Language: unknown

File: FAILURE

```

<AreErrorCodesPresent

error_code=

"{error_code}"

error_codes_to_check=

"101,107,119"

/>

```


key: chroma:document
string_value:
Title: Camera Calibration

URL: https://docs.nav2.org/tutorials/docs/camera_calibration.html#tutorial-steps

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview

This tutorial shows how to obtain calibration parameters for monocular camera.

## Requirements

1- Install Camera Calibration Parser, Camera Info Manager and Launch Testing Ament Cmake using operating system’s package manager:

2- Image Pipeline need to be built from source in your workspace with:

Also, make sure you have the following:

## Tutorial Steps

1- Start a terminal in your GUI

2- Launch the ROS driver for your specific camera.

3- Make sure camera is publishing images over ROS. This can be tested by running:

4- This will show you all the topics published make sure that there is an image_raw topic /camera/image_raw. To confirm that its a real topic and actually publishing check topic hz:

5- Start the camera calibration node


key: chroma:document
string_value:
5- Start the camera calibration node

6- In order to get a good calibration you will need to move the checkerboard around in the camera frame such that:

7- As the checkerboard is moved around the 4 bars on the calibration sidebar increases in length. When all then the 4 bars are green and enough data is available for calibration the CALIBRATE button will light up. Click it to see the results. It takes around the minute for calibration to take place.

8- After the calibration is completed the save and commit buttons light up. And you can also see the result in terminal.

9-Press the save button to see the result. Data is saved to  “/tmp/calibrationdata.tar.gz”

11-In the folder images used for calibration are available and also “ost.yaml” and “ost.txt”. You can use the yaml file which contains the calibration parameters as directed by the camera driver.

Code Examples:

Language: unknown


key: chroma:document
string_value:
Code Examples:

Language: unknown

File: ros2runcamera_calibrationcameracalibrator--size7x9--square0.02--ros-args-rimage:=/my_camera/image_raw-pcamera:=/my_camera

```

Camera

Name

:

c

,

--

camera_name

name

of

the

camera

to

appear

in

the

calibration

file

Chessboard

Options

:

You

must

specify

one

or

more

chessboards

as

pairs

of

--

size

and

--

square

options

.

p

PATTERN

,

--

pattern

=

PATTERN

calibration

pattern

to

detect

'chessboard'

,

'circles'

,

'acircles'

,

'charuco'

s

SIZE

,

--

size

=

SIZE

chessboard

size

as

NxM

,

counting

interior

corners

(

e

.

g

.

a

standard

chessboard

is

7

x7

)

q

SQUARE

,

--

square

=

SQUARE

chessboard

square

size

in

meters

ROS

Communication

Options

:

--

approximate

=

APPROXIMATE

allow

specified

slop

(

in

seconds

)

when

pairing

images

from

unsynchronized

stereo

cameras

--

no

service

check

disable

check

for

set_camera_info

services

at

startup

Calibration


key: chroma:document
string_value:
for

set_camera_info

services

at

startup

Calibration

Optimizer

Options

:

--

fix

principal

point

fix

the

principal

point

at

the

image

center

--

fix

aspect

ratio

enforce

focal

lengths

(

fx

,

fy

)

are

equal

--

zero

tangent

dist

set

tangential

distortion

coefficients

(

p1

,

p2

)

to

zero

k

NUM_COEFFS

,

--

k

coefficients

=

NUM_COEFFS

number

of

radial

distortion

coefficients

to

use

(

up

to

6

,

default

2

)

--

disable_calib_cb_fast_check

uses

the

CALIB_CB_FAST_CHECK

flag

for

findChessboardCorners

This

will

open

a

calibration

window

which

highlight

the

checkerboard

.

```


key: chroma:document
string_value:
Title: XYTheta Iterator

URL: https://docs.nav2.org/configuration/packages/dwb

params/iterator.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <dwbplugin>: DWB plugin name defined in thecontroller_plugin_idsparameter inController Server.


key: chroma:document
string_value:
Title: Dynamic Object Following

URL: https://docs.nav2.org/tutorials/docs/navigation2_dynamic_point_following.html#run-dynamic-object-following-in-nav2-simulation

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview

This tutorial shows how to use Nav2 for a different task other than going from point A to point B. In this case, we will use Nav2 to follow a moving object at a distance indefinitely.

This task is useful in cases such as following a person or another robot. Below are some sample videos of applications that could be created using this capability. The “Carry My Luggage” RoboCup @ Home test, in which theCATIE Roboticsteam performs the test successfully and this real (future) world application:

The requirements for this task are as follows:


key: chroma:document
string_value:
The requirements for this task are as follows:

The detection of the dynamic object (like a person) to follow is outside the scope of this tutorial. As shown in the following diagram, your application should provide a detector for the object(s) of interest,

send the initial pose to theNavigateToPoseaction, and update it on a topic for the duration of the task. Many different types of detectors exist that you can leverage for this application:

## Tutorial Steps

## 0- Create the Behavior Tree

Let’s start from this simple behavior tree. This behavior tree replans a new path at 1 hz and passes that path to the controller to follow:

First, let’s make this behavior run until there’s a failure. For this purpose, we will use theKeepRunningUntilFailurecontrol node.


key: chroma:document
string_value:
We will then use the decoratorGoalUpdaterto accept updates of the dynamic object pose we’re trying to follow. This node takes as input the current goal and subscribes to the topic/goal_update. It sets the new goal asupdated_goalif a new goal on that topic is received.

To stay at a certain distance from the target, we will use the action nodeTruncatePath. This node modifies a path making it shorter so we don’t try to navigate into the object of interest. We can set up the desired distance to the goal using the input portdistance.

Now, you may save this behavior tree and use it in our navigation task.

For reference, this exact behavior tree ismade availableto you batteries included in thenav2_bt_navigatorpackage.

## 1- Setup Rviz clicked point


key: chroma:document
string_value:
## 1- Setup Rviz clicked point

We are going to use RViz instead of a full application so you can test at home without finding a detector to get started. We will use the “clicked point” button on the toolbar to substitute object detections to provide goal updates to Nav2. This button allows you to

publish coordinates in the topic/clicked_point. This point needs to be sent to the behavior tree, using the programclicked_point_to_pose, fromthis repo. Clone

this repo in your workspace, build, and type in a terminal.

ros2runnav2_test_utilsclicked_point_to_pose

Optionally, you can remap this topic in your rviz configuration file togoal_updates.

## 2- Run Dynamic Object Following in Nav2 Simulation

Start Nav2 in one terminal:

ros2launchnav2_bringuptb3_simulation_launch.pydefault_bt_xml_filename:=/path/to/bt.xml


key: chroma:document
string_value:
Open RViz and, after initialize the robot position, command the robot to navigate to any position. Use the button clicked point to simulate a new detection of the object of interest, as shown in the video in the head of this tutorial.

When you have a detector detecting your obstacle at a higher rate (1 hz, 10 hz, 100 hz) you will see a far more reactive robot following your detected object of interest!

Code Examples:

Language: unknown

File: NavigateToPose

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<PipelineSequence

name=

"NavigateWithReplanning"

>

<RateController

hz=

"1.0"

>

<ComputePathToPose

goal=

"{goal}"

path=

"{path}"

planner_id=

"GridBased"

/>

</RateController>

<FollowPath

path=

"{path}"

controller_id=

"FollowPath"

/>

</PipelineSequence>

</BehaviorTree>

</root>

```

Language: unknown

File: KeepRunningUntilFailure

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<PipelineSequence

name=


key: chroma:document
string_value:
>

<BehaviorTree

ID=

"MainTree"

>

<PipelineSequence

name=

"NavigateWithReplanning"

>

<RateController

hz=

"1.0"

>

<ComputePathToPose

goal=

"{goal}"

path=

"{path}"

planner_id=

"GridBased"

/>

</RateController>

<KeepRunningUntilFailure>

<FollowPath

path=

"{path}"

controller_id=

"FollowPath"

/>

</KeepRunningUntilFailure>

</PipelineSequence>

</BehaviorTree>

</root>

```

Language: unknown

File: updated_goal

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<PipelineSequence

name=

"NavigateWithReplanning"

>

<RateController

hz=

"1.0"

>

<GoalUpdater

input_goal=

"{goal}"

output_goal=

"{updated_goal}"

>

<ComputePathToPose

goal=

"{updated_goal}"

path=

"{path}"

planner_id=

"GridBased"

/>

</GoalUpdater>

</RateController>

<KeepRunningUntilFailure>

<FollowPath

path=

"{path}"

controller_id=

"FollowPath"

/>

</KeepRunningUntilFailure>

</PipelineSequence>

</BehaviorTree>

</root>

```

Language: unknown

File: distance

```


key: chroma:document
string_value:
</root>

```

Language: unknown

File: distance

```

<root

main_tree_to_execute=

"MainTree"

>

<BehaviorTree

ID=

"MainTree"

>

<PipelineSequence

name=

"NavigateWithReplanning"

>

<RateController

hz=

"1.0"

>

<Sequence>

<GoalUpdater

input_goal=

"{goal}"

output_goal=

"{updated_goal}"

>

<ComputePathToPose

goal=

"{updated_goal}"

path=

"{path}"

planner_id=

"GridBased"

/>

</GoalUpdater>

<TruncatePath

distance=

"1.0"

input_path=

"{path}"

output_path=

"{truncated_path}"

/>

</Sequence>

</RateController>

<KeepRunningUntilFailure>

<FollowPath

path=

"{truncated_path}"

controller_id=

"FollowPath"

/>

</KeepRunningUntilFailure>

</PipelineSequence>

</BehaviorTree>

</root>

```


key: chroma:document
string_value:
Title: Costmap 2D

URL: https://docs.nav2.org/configuration/packages/configuring-costmaps.html#default-plugins

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Costmap2D ROS Parameters

## Default Plugins

When thepluginsparameter is not overridden, the following default plugins are loaded:

## Plugin Parameters

## Costmap Filters Parameters

## Example

Code Examples:

Language: unknown

File: plugin

```

local_costmap

:

ros__parameters

:

plugins

:

[

"obstacle_layer"

,

"voxel_layer"

,

"inflation_layer"

]

obstacle_layer

:

plugin

:

"nav2_costmap_2d::ObstacleLayer"

voxel_layer

:

plugin

:

"nav2_costmap_2d::VoxelLayer"

inflation_layer

:

plugin

:

"nav2_costmap_2d::InflationLayer"

```

Language: unknown

File: plugin

```

local_costmap

:

ros__parameters

:

filters

:

[

"keepout_filter"

,

"speed_filter"

]

keepout_filter

:

plugin

:

"nav2_costmap_2d::KeepoutFilter"

speed_filter

:

plugin

:


key: chroma:document
string_value:
"nav2_costmap_2d::KeepoutFilter"

speed_filter

:

plugin

:

"nav2_costmap_2d::SpeedFilter"

```

Language: unknown

File: plugins

```

global_costmap

:

global_costmap

:

ros__parameters

:

footprint_padding

:

0.03

update_frequency

:

1.0

publish_frequency

:

1.0

global_frame

:

map

robot_base_frame

:

base_link

use_sim_time

:

True

robot_radius

:

0.22

# radius set and used, so no footprint points

resolution

:

0.05

plugins

:

[

"static_layer"

,

"obstacle_layer"

,

"voxel_layer"

,

"inflation_layer"

]

obstacle_layer

:

plugin

:

"nav2_costmap_2d::ObstacleLayer"

enabled

:

True

observation_sources

:

scan

footprint_clearing_enabled

:

true

max_obstacle_height

:

2.0

combination_method

:

1

scan

:

topic

:

/scan

obstacle_max_range

:

2.5

obstacle_min_range

:

0.0

raytrace_max_range

:

3.0

raytrace_min_range

:

0.0

max_obstacle_height

:

2.0

min_obstacle_height

:

0.0

clearing

:

True

marking

:

True

data_type

:

"LaserScan"

inf_is_valid

:


key: chroma:document
string_value:
marking

:

True

data_type

:

"LaserScan"

inf_is_valid

:

false

voxel_layer

:

plugin

:

"nav2_costmap_2d::VoxelLayer"

enabled

:

True

footprint_clearing_enabled

:

true

max_obstacle_height

:

2.0

publish_voxel_map

:

True

origin_z

:

0.0

z_resolution

:

0.05

z_voxels

:

16

max_obstacle_height

:

2.0

unknown_threshold

:

15

mark_threshold

:

0

observation_sources

:

pointcloud

combination_method

:

1

pointcloud

:

# no frame set, uses frame from message

topic

:

/intel_realsense_r200_depth/points

max_obstacle_height

:

2.0

min_obstacle_height

:

0.0

obstacle_max_range

:

2.5

obstacle_min_range

:

0.0

raytrace_max_range

:

3.0

raytrace_min_range

:

0.0

clearing

:

True

marking

:

True

data_type

:

"PointCloud2"

static_layer

:

plugin

:

"nav2_costmap_2d::StaticLayer"

map_subscribe_transient_local

:

True

enabled

:

true

subscribe_to_updates

:

true

transform_tolerance

:

0.1

inflation_layer

:

plugin

:

"nav2_costmap_2d::InflationLayer"


key: chroma:document
string_value:
:

plugin

:

"nav2_costmap_2d::InflationLayer"

enabled

:

true

inflation_radius

:

0.55

cost_scaling_factor

:

1.0

inflate_unknown

:

false

inflate_around_unknown

:

true

always_send_full_costmap

:

True

local_costmap

:

local_costmap

:

ros__parameters

:

update_frequency

:

5.0

publish_frequency

:

2.0

global_frame

:

odom

robot_base_frame

:

base_link

use_sim_time

:

True

rolling_window

:

true

width

:

3

height

:

3

resolution

:

0.05

```


key: chroma:document
string_value:
Title: GoalReached

URL: https://docs.nav2.org/configuration/packages/bt

plugins/conditions/GoalReached.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameter

## Example

## Input Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

bt_navigator

:

ros__parameters

:

# other bt_navigator parameters

transform_tolerance

:

0.1

goal_reached_tol

:

0.25

```

Language: unknown

File: use_cancel_deceleration

```

<GoalReached

goal=

"{goal}"

robot_base_frame=

"base_link"

/>

```


key: chroma:document
string_value:
Title: Behavior-Tree Navigator

URL: https://docs.nav2.org/configuration/packages/configuring-bt-navigator.html#example

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

## Example

Code Examples:

Language: unknown

File: NavigateThroughPoses

```

bt_navigator

:

ros__parameters

:

use_sim_time

:

true

global_frame

:

map

robot_base_frame

:

base_link

transform_tolerance

:

0.1

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

goal_blackboard_id

:

goal

goals_blackboard_id

:

goals

path_blackboard_id

:

path

navigators

:

[

'navigate_to_pose'

,

'navigate_through_poses'

]

navigate_to_pose

:

plugin

:

"nav2_bt_navigator::NavigateToPoseNavigator"


key: chroma:document
string_value:
:

plugin

:

"nav2_bt_navigator::NavigateToPoseNavigator"

# In Iron and older versions, "/" was used instead of "::"

navigate_through_poses

:

plugin

:

"nav2_bt_navigator::NavigateThroughPosesNavigator"

# In Iron and older versions, "/" was used instead of "::"

plugin_lib_names

:

nav2_compute_path_to_pose_action_bt_node

nav2_follow_path_action_bt_node

nav2_back_up_action_bt_node

nav2_spin_action_bt_node

nav2_wait_action_bt_node

nav2_clear_costmap_service_bt_node

nav2_is_stuck_condition_bt_node

nav2_is_stopped_condition_bt_node

nav2_goal_reached_condition_bt_node

nav2_initial_pose_received_condition_bt_node

nav2_goal_updated_condition_bt_node

nav2_reinitialize_global_localization_service_bt_node

nav2_rate_controller_bt_node

nav2_distance_controller_bt_node

nav2_speed_controller_bt_node

nav2_recovery_node_bt_node

nav2_pipeline_sequence_bt_node

nav2_round_robin_node_bt_node

nav2_transform_available_condition_bt_node

nav2_time_expired_condition_bt_node


key: chroma:document
string_value:
nav2_time_expired_condition_bt_node

nav2_distance_traveled_condition_bt_node

nav2_single_trigger_bt_node

error_code_names

:

compute_path_error_code

follow_path_error_code

# - smoother_error_code, navigate_to_pose_error_code, navigate_through_poses_error_code, etc

```


key: chroma:document
string_value:
Title: RemovePassedGoals

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/RemovePassedGoals.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example

Code Examples:

Language: unknown

File: ComputePathThroughPoses

```

<RemovePassedGoals

radius=

"0.6"

input_goals=

"{goals}"

output_goals=

"{goals}"

/>

```


key: chroma:document
string_value:
Title: Using Rotation Shim Controller

URL: https://docs.nav2.org/tutorials/docs/using_shim_controller.html#demo-execution

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Overview

This tutorial will discuss how to set up your robot to use theRotationShimControllerto help create intuitive, rotate-in-place, behavior for your robot while starting out to track a path. The goal of this tutorial is to explain to the reader the value of the controller, how to configure it, how to configure the primary controller with it, and finally an example of it in use.

Before starting this tutorial, completing theGetting Startedis highly recommended especially if you are new to ROS and Nav2. The requirements are having the latest install of Nav2 / ROS 2 containing this package.

## What is the Rotation Shim Controller?


key: chroma:document
string_value:
## What is the Rotation Shim Controller?

This was developed due to quirks in TEB and DWB, but applicable to any other controller plugin type that you’d like to have rotation in place behavior with.TEB’s behavior tends to whip the robot around with small turns, or when the path is starting at a very different heading than current, in a somewhat surprising way due to the elastic band approach.DWBcan be tuned to have any type of behavior, but typically to tune it to be an excellent path follower also makes it less optimally capable of smooth transitions to new paths at far away headings – there are always trade offs. Giving both TEB and DWB a better starting point to start tracking a path makes tuning the controllers significantly easier and creates more intuitive results for on-lookers.


key: chroma:document
string_value:
Note that it is not required to use this withanyplugin. Many users are perfectly successful without using this controller, but if a robot may rotate in place before beginning its path tracking task (or others), it can be advantageous to do so.

Thenav2_rotation_shim_controllerwill check the rough heading difference with respect to the robot and a newly received path. If within a threshold, it will pass the request onto theprimary_controllerto execute the task. If it is outside of the threshold, this controller will rotate the robot in place towards that path heading. Once it is within the tolerance, it will then pass off control-execution from this rotation shim controller onto the primary controller plugin. At this point, the robot’s main plugin will take control for a smooth hand off into the task.

TheRotationShimControlleris most suitable for:

## Configuring Rotation Shim Controller


key: chroma:document
string_value:
## Configuring Rotation Shim Controller

This controller is ashimbecause it is placed between the primary controller plugin and the controller server. It takes commands and pre-processes them to rotate to the heading and then passes off execution-control to the primary plugin once that condition is met - acting as a simple pass through.

As such, its configuration looks very similar to that of any other plugin. In the code block below, you can see that we’ve added theRotationShimControlleras the plugin for path tracking in the controller server. You can see that we’ve also configured it below with its internal parameters,angular_dist_thresholdthroughmax_angular_accel.

The Rotation Shim Controller is very simple and only has a couple of parameters to dictate the conditions it should be enacted.

## Configuring Primary Controller


key: chroma:document
string_value:
## Configuring Primary Controller

There is one more remaining parameter of theRotationShimControllernot mentioned above, theprimary_controller. This is the type of controller that your application would like to use as the primary modus operandi. It will share the same name and yaml namespace as the shim plugin. You can observe this below with the primary controller set theDWB(with the progress and goal checkers removed for brevity).

An important note is thatwithin the same yaml namespace, you may also include anyprimary_controllerspecific parameters required for a robot. Thusly, aftermax_angular_accel, you can include any ofDWB’s parameters for your platform.

## Demo Execution

Code Examples:

Language: unknown

File: max_angular_accel

```

controller_server

:

ros__parameters

:

use_sim_time

:

True

controller_frequency

:

20.0

min_x_velocity_threshold

:

0.001

min_y_velocity_threshold

:

0.5

min_theta_velocity_threshold

:

0.001

progress_checker_plugins

:

[

"progress_checker"

]


key: chroma:document
string_value:
0.001

progress_checker_plugins

:

[

"progress_checker"

]

# progress_checker_plugin: "progress_checker" For Humble and older

goal_checker_plugins

:

[

"goal_checker"

]

controller_plugins

:

[

"FollowPath"

]

progress_checker

:

plugin

:

"nav2_controller::SimpleProgressChecker"

required_movement_radius

:

0.5

movement_time_allowance

:

10.0

goal_checker

:

plugin

:

"nav2_controller::SimpleGoalChecker"

xy_goal_tolerance

:

0.25

yaw_goal_tolerance

:

0.25

stateful

:

True

FollowPath

:

plugin

:

"nav2_rotation_shim_controller::RotationShimController"

angular_dist_threshold

:

0.785

forward_sampling_distance

:

0.5

rotate_to_heading_angular_vel

:

1.8

max_angular_accel

:

3.2

simulate_ahead_time

:

1.0

```

Language: unknown

File: DWB

```

controller_server

:

ros__parameters

:

use_sim_time

:

True

controller_frequency

:

20.0

min_x_velocity_threshold

:

0.001

min_y_velocity_threshold

:

0.5

min_theta_velocity_threshold

:

0.001

controller_plugins

:

[


key: chroma:document
string_value:
:

0.001

controller_plugins

:

[

"FollowPath"

]

FollowPath

:

plugin

:

"nav2_rotation_shim_controller::RotationShimController"

primary_controller

:

"dwb_core::DWBLocalPlanner"

angular_dist_threshold

:

0.785

forward_sampling_distance

:

0.5

rotate_to_heading_angular_vel

:

1.8

max_angular_accel

:

3.2

simulate_ahead_time

:

1.0

# DWB parameters

...

...

...

```


key: chroma:document
string_value:
Title: Theta Star Planner

URL: https://docs.nav2.org/configuration/packages/configuring

thetastar.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters The parameters of the planner are:

## Example

Code Examples:

Language: unknown File: <name> ``` planner_server : ros__parameters : expected_planner_frequency : 20.0 use_sim_time : True planner_plugins : [ "GridBased" ] GridBased : plugin : "nav2_theta_star_planner::ThetaStarPlanner" # In Iron and older versions, "/" was used instead of "::" how_many_corners : 8 w_euc_cost : 1.0 w_traversal_cost : 2.0 w_heuristic_cost : 1.0 ```


key: chroma:document
string_value:
Title: Keepout Filter Parameters

URL: https://docs.nav2.org/configuration/packages/costmap-plugins/keepout_filter.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Example

Code Examples:

Language: unknown

File: <filtername>

```

global_costmap

:

global_costmap

:

ros__parameters

:

...

plugins

:

[

"static_layer"

,

"obstacle_layer"

,

"inflation_layer"

]

filters

:

[

"keepout_filter"

]

...

keepout_filter

:

plugin

:

"nav2_costmap_2d::KeepoutFilter"

enabled

:

True

filter_info_topic

:

"/costmap_filter_info"

transform_tolerance

:

0.1

...

local_costmap

:

local_costmap

:

ros__parameters

:

...

plugins

:

[

"voxel_layer"

,

"inflation_layer"

]

filters

:

[

"keepout_filter"

]

...

keepout_filter

:

plugin

:

"nav2_costmap_2d::KeepoutFilter"

enabled

:

True

filter_info_topic

:

"/costmap_filter_info"

transform_tolerance

:

0.1

```


key: chroma:document
string_value:
Title: Plugin Tutorials

URL: https://docs.nav2.org/plugin_tutorials/index.html

Section: plugin_tutorials/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
Title: GoalDistCritic

URL: https://docs.nav2.org/configuration/packages/trajectory_critics/goal_dist.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters <dwbplugin>: DWB plugin name defined in thecontroller_plugin_idsparameter inController Server. <name>: GoalDistCritic critic name defined in the<dwb plugin>.criticsparameter defined inDWB Controller.


key: chroma:document
string_value:
Title: Writing a New Controller Plugin

URL: https://docs.nav2.org/plugin_tutorials/docs/writing_new_nav2controller_plugin.html#writing-new-nav2controller-plugin

Section: tuning/index.html

--------------------------------------------------------------------------------

## Overview

This tutorial shows how to create your own controllerplugin.

In this tutorial, we will be implementing the pure pursuit path tracking algorithm based on thispaper.

It is recommended you go through it.

Note: This tutorial is based on a previously existing simplified version of the Regulated Pure Pursuit controller now in the Nav2 stack.

You can find the source code matching this tutorialhere.

## Requirements

## Tutorial Steps

## 1- Create a new Controller Plugin

We will be implementing the pure pursuit controller. The annotated code in this tutorial can be found innavigation_tutorialsrepository

as thenav2_pure_pursuit_controller. This package can be considered as a reference for writing your own controller plugin.


key: chroma:document
string_value:
Our example plugin classnav2_pure_pursuit_controller::PurePursuitControllerinherits from the base classnav2_core::Controller. The base class provides a

set of virtual methods to implement a controller plugin. These methods are called at runtime by the controller server to compute velocity commands.

The list of methods, their descriptions, and necessity are presented in the table below:

In this tutorial, we will use the methodsPurePursuitController::configure,PurePursuitController::setPlanandPurePursuitController::computeVelocityCommands.

In controllers,configure()method must set member variables from ROS parameters and perform any initialization required.

Here,plugin_name_+".desired_linear_vel"is fetching the ROS parameterdesired_linear_velwhich is specific to our controller.

Nav2 allows loading of multiple plugins, and to keep things organized, each plugin is mapped to some ID/name.


key: chroma:document
string_value:
Now, if we want to retrieve the parameters for that specific plugin, we use<mapped_name_of_plugin>.<name_of_parameter>as done in the above snippet.

For example, our example controller is mapped to the nameFollowPathand to retrieve thedesired_linear_velparameter, which is specific to “FollowPath”,

we usedFollowPath.desired_linear_vel. In other words,FollowPathis used as a namespace for plugin-specific parameters.

We will see more on this when we discuss the parameters file (or params file).

The passed-in arguments are stored in member variables so that they can be used at a later stage if needed.

InsetPlan()method, we receive the updated global path for the robot to follow. In our example, we transform the received global path into

the frame of the robot and then store this transformed global path for later use.

The computation for the desired velocity happens in thecomputeVelocityCommands()method. It is used to calculate the desired velocity command given the current velocity and pose.


key: chroma:document
string_value:
The third argument - is a pointer to thenav2_core::GoalChecker, that checks whether a goal has been reached. In our example, this won’t be used.

In the case of pure pursuit, the algorithm computes velocity commands such that the robot tries to follow the global path as closely as possible.

This algorithm assumes a constant linear velocity and computes the angular velocity based on the curvature of the global path.

The remaining methods are not used, but it’s mandatory to override them. As per the rules, we did override all but left them empty.

## 2- Exporting the controller plugin

Now that we have created our custom controller, we need to export our controller plugin so that it will be visible to the controller server.

Plugins are loaded at runtime, and if they are not visible, then our controller server won’t be able to load them. In ROS 2, exporting and loading

plugins is handled bypluginlib.


key: chroma:document
string_value:
plugins is handled bypluginlib.

Coming back to our tutorial, classnav2_pure_pursuit_controller::PurePursuitControlleris loaded dynamically asnav2_core::Controllerwhich is our base class.

Note that it requires pluginlib to export out the plugin’s class. Pluginlib would provide as macroPLUGINLIB_EXPORT_CLASS, which does all the work of exporting.

It is good practice to place these lines at the end of the file, but technically, you can also write at the top.

## 3- Pass the plugin name through the params file

To enable the plugin, we need to modify thenav2_params.yamlfile as below

In the above snippet, you can observe the mapping of ournav2_pure_pursuit_controller::PurePursuitControllercontroller to its idFollowPath.

To pass plugin-specific parameters we have used<plugin_id>.<plugin_specific_parameter>.

## 4- Run Pure Pursuit Controller plugin

Run Turtlebot3 simulation with enabled Nav2. Detailed instructions on how to make it run are written atGetting Started. Below is a shortcut command for that:


key: chroma:document
string_value:
Then goto RViz and click on the “2D Pose Estimate” button at the top and point the location on the map as it was described inGetting Started.

The robot will localize on the map and then click on the “Nav2 goal” and click on the pose where you want your robot to navigate to.

After that controller will make the robot follow the global path.

Code Examples:

Language: unknown

File: configure()

```

void

PurePursuitController::configure

(

const

rclcpp_lifecycle

::

LifecycleNode

::

WeakPtr

&

parent

,

std

::

string

name

,

std

::

shared_ptr

<

tf2_ros

::

Buffer

>

tf

,

std

::

shared_ptr

<

nav2_costmap_2d

::

Costmap2DROS

>

costmap_ros

)

{

node_

=

parent

;

auto

node

=

node_

.

lock

();

costmap_ros_

=

costmap_ros

;

tf_

=

tf

;

plugin_name_

=

name

;

logger_

=

node

>

get_logger

();

clock_

=

node

>

get_clock

();

declare_parameter_if_not_declared

(

node

,

plugin_name_

+

".desired_linear_vel"

,

rclcpp

::

ParameterValue

(

0.2

));


key: chroma:document
string_value:
,

rclcpp

::

ParameterValue

(

0.2

));

declare_parameter_if_not_declared

(

node

,

plugin_name_

+

".lookahead_dist"

,

rclcpp

::

ParameterValue

(

0.4

));

declare_parameter_if_not_declared

(

node

,

plugin_name_

+

".max_angular_vel"

,

rclcpp

::

ParameterValue

(

1.0

));

declare_parameter_if_not_declared

(

node

,

plugin_name_

+

".transform_tolerance"

,

rclcpp

::

ParameterValue

(

0.1

));

node

>

get_parameter

(

plugin_name_

+

".desired_linear_vel"

,

desired_linear_vel_

);

node

>

get_parameter

(

plugin_name_

+

".lookahead_dist"

,

lookahead_dist_

);

node

>

get_parameter

(

plugin_name_

+

".max_angular_vel"

,

max_angular_vel_

);

double

transform_tolerance

;

node

>

get_parameter

(

plugin_name_

+

".transform_tolerance"

,

transform_tolerance

);

transform_tolerance_

=

rclcpp

::

Duration

::

from_seconds

(

transform_tolerance

);

}

```

Language: unknown

File: setPlan()

```

void

PurePursuitController::setPlan

(

const


key: chroma:document
string_value:
```

void

PurePursuitController::setPlan

(

const

nav_msgs

::

msg

::

Path

&

path

)

{

// Transform global path into the robot's frame

global_plan_

=

transformGlobalPlan

(

path

);

}

```

Language: unknown

File: nav2_core::GoalChecker

```

geometry_msgs

::

msg

::

TwistStamped

PurePursuitController::computeVelocityCommands

(

const

geometry_msgs

::

msg

::

PoseStamped

&

pose

,

const

geometry_msgs

::

msg

::

Twist

&

velocity

,

nav2_core

::

GoalChecker

/*goal_checker*/

)

{

// Find the first pose which is at a distance greater than the specified lookahead distance

auto

goal_pose

=

std

::

find_if

(

global_plan_

.

poses

.

begin

(),

global_plan_

.

poses

.

end

(),

[

&

](

const

auto

&

global_plan_pose

)

{

return

hypot

(

global_plan_pose

.

pose

.

position

.

x

,

global_plan_pose

.

pose

.

position

.

y

)

>=

lookahead_dist_

;

})

>

pose

;

double

linear_vel

,

angular_vel

;


key: chroma:document
string_value:
;

})

>

pose

;

double

linear_vel

,

angular_vel

;

// If the goal pose is in front of the robot then compute the velocity using the pure pursuit algorithm

// else rotate with the max angular velocity until the goal pose is in front of the robot

if

(

goal_pose

.

position

.

x

>

0

)

{

auto

curvature

=

2.0

goal_pose

.

position

.

y

/

(

goal_pose

.

position

.

x

goal_pose

.

position

.

x

+

goal_pose

.

position

.

y

goal_pose

.

position

.

y

);

linear_vel

=

desired_linear_vel_

;

angular_vel

=

desired_linear_vel_

curvature

;

}

else

{

linear_vel

=

0.0

;

angular_vel

=

max_angular_vel_

;

}

// Create and publish a TwistStamped message with the desired velocity

geometry_msgs

::

msg

::

TwistStamped

cmd_vel

;

cmd_vel

.

header

.

frame_id

=

pose

.

header

.

frame_id

;

cmd_vel

.

header

.

stamp

=

clock_

>

now

();

cmd_vel

.

twist

.

linear

.

x

=

linear_vel

;

cmd_vel

.

twist

.

angular

.

z

=

max

(

1.0

abs

(


key: chroma:document
string_value:
;

cmd_vel

.

twist

.

angular

.

z

=

max

(

1.0

abs

(

max_angular_vel_

),

min

(

angular_vel

,

abs

(

max_angular_vel_

)));

return

cmd_vel

;

}

```

Language: unknown

File: nav2_core::Controller

```

#include

"pluginlib/class_list_macros.hpp"

PLUGINLIB_EXPORT_CLASS

(

nav2_pure_pursuit_controller

::

PurePursuitController

,

nav2_core

::

Controller

)

```

Language: unknown

File: description

```

<library

path=

"nav2_pure_pursuit_controller"

>

<class

type=

"nav2_pure_pursuit_controller::PurePursuitController"

base_class_type=

"nav2_core::Controller"

>

<description>

This

is

pure

pursuit

controller

</description>

</class>

</library>

```

Language: unknown

File: share

```

pluginlib_export_plugin_description_file(nav2_core pure_pursuit_controller_plugin.xml)

```

Language: unknown

File: package.xml

```

<export>

<build_type>

ament_cmake

</build_type>

<nav2_core

plugin=

"${prefix}/pure_pursuit_controller_plugin.xml"

/>

</export>

```


key: chroma:document
string_value:
/>

</export>

```

Language: unknown

File: nav2_params.yaml

```

controller_server:

ros__parameters:

controller_plugins: ["FollowPath"]

FollowPath:

plugin: "nav2_pure_pursuit_controller::PurePursuitController" # In Iron and older versions, "/" was used instead of "::"

debug_trajectory_details: True

desired_linear_vel: 0.2

lookahead_dist: 0.4

max_angular_vel: 1.0

transform_tolerance: 1.0

```

Language: unknown

File: <plugin_id>.<plugin_specific_parameter>

```

$

ros2

launch

nav2_bringup

tb3_simulation_launch.py

params_file:

=

/path/to/your_params_file.yaml

```


key: chroma:document
string_value:
Title: CancelAssistedTeleop

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/CancelAssistedTeleop.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: assisted_teleop

```

<CancelAssistedTeleop

server_name=

"assisted_teleop"

server_timeout=

"10"

/>

```


key: chroma:document
string_value:
Title: Smac 2D Planner

URL: https://docs.nav2.org/configuration/packages/smac/configuring-smac-2d.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

## Example

Code Examples:

Language: unknown

File: <name>

```

planner_server

:

ros__parameters

:

planner_plugins

:

[

"GridBased"

]

use_sim_time

:

True

GridBased

:

plugin

:

"nav2_smac_planner::SmacPlanner2D"

# In Iron and older versions, "/" was used instead of "::"

tolerance

:

0.125

# tolerance for planning if unable to reach exact pose, in meters

downsample_costmap

:

false

# whether or not to downsample the map

downsampling_factor

:

1

# multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm)

allow_unknown

:

true

# allow traveling in unknown space

max_iterations

:

1000000

# maximum total iterations to search for before failing (in case unreachable), set to -1 to disable

max_on_approach_iterations


key: chroma:document
string_value:
max_on_approach_iterations

:

1000

# maximum number of iterations to attempt to reach goal once in tolerance

max_planning_time

:

2.0

# max time in s for planner to plan, smooth

cost_travel_multiplier

:

2.0

# Cost multiplier to apply to search to steer away from high cost areas. Larger values will place in the center of aisles more exactly (if non-`FREE` cost potential field exists) but take slightly longer to compute. To optimize for speed, a value of 1.0 is reasonable. A reasonable tradeoff value is 2.0. A value of 0.0 effective disables steering away from obstacles and acts like a naive binary search A*.

use_final_approach_orientation

:

false

# Whether to set the final path pose at the goal's orientation to the requested orientation (false) or in line with the approach angle so the robot doesn't rotate to heading (true)

smoother

:

max_iterations

:

1000

w_smooth

:

0.3

w_data

:

0.2

tolerance

:

1.0e-10

```


key: chroma:document
string_value:
Title: Jazzy to K

Turtle

URL: https://docs.nav2.org/migration/Jazzy.html#docking

with

static

infrastructure

or

dynamic

docking

Section: getting_started/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
## TwistStamped Default CmdVel Change In Kilted and newer, the defaultcmd_veltopic for allTwistpublishers and subscriptions is changed toTwistStampedin order to enable a broader range of applications. it also allows for rejection of stale velocity messages, which can be useful in some applications. Your robot should now subscribe to aTwistStampedmessage instead of aTwistmessage & update your simulation appropriately. The topic names are the same. However, this can be disabled by settingenable_twist_stampedtofalsein thenav2_params.yamlfile for all nodes that involve Twist subscriptions or publications. See the configuration guide for more information on how to configure this parameter for each node. An example simulation migration using Gazebo can be seen in thefollowing pull request for the Turtlebot 3 and 4.


key: chroma:document
string_value:
## New Nav2 Loopback Simulator Thenav2_loopback_simis a stand-alone simulator to create a “loopback” for non-physical simulation to replace robot hardware, physics simulators (Gazebo, Bullet, Isaac Sim, etc). It computes the robot’s odometry based on the command velocity’s output request to create a perfect ‘frictionless plane’-style simulation for unit testing, system testing, R&D on higher level systems, testing behaviors without concerning yourself with localization accuracy or system dynamics, and multirobot simulations.

## Docking with Static Infrastructure or Dynamic Docking InPR #4627a docking plugin type and logic was added to support non-charging dock types in the nav2 docking server. This allows users to specify docking locations to static infrastructure, such as conveyers, or dynamic docking locations, such as a pallet. It also includes a new docking plugin to demonstrate the new docking server capabilitiessimple_non_charging_dock.


key: chroma:document
string_value:
## New RViz panel for Docking InPR #4458a new RViz panel was added to interact with the Docking Server. This panel allows the user to: The panel displays the action goal status and feedback published bynav2_msgs/DockRobotandnav2_msgs/UndockRobotactions. Users can find information such as elapsed time, number of retries and the current state of the action (staging, controlling, etc.), as well as the error codes of the action. Here we can see the working demo of the plugin:

## New BT Nodes Below is a list of new BT Nodes added:

## New RViz Tool for Costmap Cost Cell Inspection InPR #4546a new RViz tool was added to get the costmap costcell’s cost and a service to get the costcell’s cost at the footprint pose. Usage: Working demo of the tool:


key: chroma:document
string_value:
## Fix flickering visualization InPR #4561amap_vis_zparameter has been introduced to Costmap2DROS to help modify the map slightly below the default plane, aiming to eliminate rviz visualization flickering issues. Default Value: Minimum Value Without Flickering: Before: After:

## Option to limit velocity through DWB trajectory InPR #4663alimit_vel_cmd_in_trajparameter was introduced to DWB local planner to allow the user to limit the velocity used in the trajectory generation based on the robot’s current velocity. Default value:

## Option to disable zero velocity publishing on goal exit InPR #4675apublish_zero_velocityparameter was introduced for theController serverin order to disable zero velocity publishing on goal exit. Default value:

## Added optional collision checking for the Docking Server InPR #4752an optional collision checking feature was added to theDocking serverto check for collisions between the robot and the dock. Default value:


key: chroma:document
string_value:
## Revamped multirobot bringup and config files to use namespaces InPR #4715multirobot bringup and the use of namespaces were overhauled to be compatible out of the box with ROS namespaces and remove custom logic, specifically: Note that some plugins / nodes might have their own local namespace. This is the case forCostmapLayerwhich will be in a/ns/[layer_name]namespace. For these, a new functionjoinWithParentNamespacehas been added to make sure joining relative paths results in/ns/topic_namerather than/ns/[layer_name]/topic_name. If your use case doesn’t require multiple robots, keeping absolute paths in yournav2_params.yamlconfig file and rviz config file will preserve existing behavior. For example, if you specifytopic:scanin thevoxel_layerof alocal_costmapand you launch your bringup with atb4namespace:


key: chroma:document
string_value:
## Removed global map_topic from Costmap node InPR #4715the globalmap_topicparameter has been removed from theCostmap2DROSnode. This parameterwas only used in theStaticLayerand should be defined as a parameter local to theStaticLayerinstead, for example:

## Simplified Costmap2DROS constructors The following constructors forCostmap2DROShave been removed: They have been consolidated into a single one: Thelocal_namespaceparameter has been removed and is now automatically set to the node’s name (which is what the second removed constructor did). Parametersparent_namespace/use_sim_timeboth provide default values to maintain the ability of creating aCostmap2DROSobject by just specifying a name.

Code Examples:

Language: unknown

File: StaticLayer

```

global_costmap

:

global_costmap

:

ros__parameters

:

[

...

]

# Not supported anymore

map_topic

:

my_map

static_layer

:

plugin

:

"nav2_costmap_2d::StaticLayer"

map_subscribe_transient_local

:

True

# Do this instead

map_topic

:

my_map

```


key: chroma:document
string_value:
:

True

# Do this instead

map_topic

:

my_map

```

Language: unknown

File: Costmap2DROS

```

explicit

Costmap2DROS

(

const

std

::

string

&

name

,

const

std

::

string

&

parent_namespace

,

const

std

::

string

&

local_namespace

,

const

bool

&

use_sim_time

);

explicit

Costmap2DROS

(

const

std

::

string

&

name

,

const

bool

&

use_sim_time

=

false

);

```

Language: unknown

File: Costmap2DROS

```

explicit

Costmap2DROS

(

const

std

::

string

&

name

,

const

std

::

string

&

parent_namespace

=

"/"

,

const

bool

&

use_sim_time

=

false

);

```


key: chroma:document
string_value:
Title: Simple Commander API

URL: https://docs.nav2.org/commander_api/index.html

Section: commander_api/index.html

--------------------------------------------------------------------------------

## Overview

The goal of the Nav2 Simple (Python3) Commander is to provide a “navigation as a library” capability to Python3 users. We provide an API that handles all the ROS 2 and Action Server tasks for you such that you can focus on building an application leveraging the capabilities of Nav2 (after you’ve configured it to your liking with your plugins of choice).We also provide you with demos and examples of API usageto build common basic capabilities in autonomous mobile robotics in thenav2_simple_commanderpackage.


key: chroma:document
string_value:
A simple demonstration is shown below. Note:goToPose(),goThroughPoses(),followWaypoints()and similar arenon-blockingsuch that you can receive and process feedback in a single-threaded application. As such while waiting for a task to be completed, thewhilenotnav.isTaskComplete()design is necessary to poll for changes in the navigation completion, and if not complete some tasks of interest to your application (like processing feedback, doing something with the data the robot is collecting, or checking for faults).

You may use this simple commander preempt commands of the same type (e.g. you can preempt agoToPose()with anothergoToPose()) but you must explicitly cancel a current command and issue a new one if switching betweengoToPose(),goThroughPoses(), orfollowWaypoints().

## Commander API

The methods provided by the basic navigator are shown below, with inputs and expected returns.


key: chroma:document
string_value:
If a server fails, it may throw an exception or return aNoneobject, so please be sure to properly wrap your navigation calls in try/catch and check returns forNonetype.

New as of September 2023: the simple navigator constructor will accept anamespacefield to support multi-robot applications or namespaced Nav2 launches.

## Costmap API

This is a Python3 API for costmap 2d messages from the stack. It provides the basic conversion, get/set, and handling semantics found in the costmap 2d C++ API.

## Footprint Collision Checker API

This is a Python3 API for a Footprint Collision Checker.

It provides the needed methods to manipulate the coordinates

and calculate the cost of a Footprint in a given map.

## Examples and Demos

All of these can be found in thepackage.

Thenav2_simple_commanderhas a few examples to highlight the API functions available to you as a user:

Thenav2_simple_commanderhas a few demonstrations to highlight a couple of simple autonomy applications you can build using the API:


key: chroma:document
string_value:
Code Examples:

Language: unknown

File: followWaypoints()

```

from

nav2_simple_commander.robot_navigator

import

BasicNavigator

import

rclpy

rclpy

.

init

()

nav

=

BasicNavigator

()

# ...

nav

.

setInitialPose

(

init_pose

)

nav

.

waitUntilNav2Active

()

# if autostarted, else use lifecycleStartup()

# ...

path

=

nav

.

getPath

(

init_pose

,

goal_pose

)

smoothed_path

=

nav

.

smoothPath

(

path

)

# ...

nav

.

goToPose

(

goal_pose

)

while

not

nav

.

isTaskComplete

():

feedback

=

nav

.

getFeedback

()

if

feedback

.

navigation_duration

>

600

:

nav

.

cancelTask

()

# ...

result

=

nav

.

getResult

()

if

result

==

TaskResult

.

SUCCEEDED

:

print

(

'Goal succeeded!'

)

elif

result

==

TaskResult

.

CANCELED

:

print

(

'Goal was canceled!'

)

elif

result

==

TaskResult

.

FAILED

:

print

(

'Goal failed!'

)

```


key: chroma:document
string_value:
Title: Planner Server

URL: https://docs.nav2.org/configuration/packages/configuring

planner

server.html#default

plugins

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

## Default Plugins When theplanner_pluginsparameter is not overridden, the following default plugins are loaded:

## Example

Code Examples:

Language: unknown File: plugin ``` planner_server : ros__parameters : planner_plugins : [ "GridBased" ] GridBased : plugin : "nav2_navfn_planner::NavfnPlanner" # In Iron and older versions, "/" was used instead of "::" ```

Language: unknown File: planner_plugins ``` planner_server : ros__parameters : expected_planner_frequency : 20.0 planner_plugins : [ 'GridBased' ] GridBased : plugin : 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::" ```


key: chroma:document
string_value:
Title: Profiling in ROS 2 / Nav2 URL: https://docs.nav2.org/tutorials/docs/get_profile.html#overview Section: getting_started/index.html --------------------------------------------------------------------------------

## Overview This document explains one method for profiling applications in ROS 2 / Nav2. The aim of profiling is to generate files that can be analyzed to see where compute time and resources are spent during the execution of a program. This can be useful to determine where the bottlenecks in your program exist and where things might be able to be improved. The following steps show ROS 2 users how to modify the Nav2 stack to get profiling information about a particular server / algorithm when they encounter a situation they’d like to understand better. This tutorial applies to both simulated and physical robots.


key: chroma:document
string_value:
## Preliminaries This tutorial makes use of two tools, callgrind from theValgrindset of tools andkcachegrind. Valgrind is used to get the profiling information about the program and kcachegrind is the visualization engine used to interpret this information to do useful work. Thus, we must install them. More information can be found in theValgrind manualincluding additional valgrind arguments that can be used to specify more information. Generally speaking, to use valgrind we need to compile with debugging information. This can be done by passing-gas a compiling option or compileCMAKE_BUILD_TYPEasDebugorRelWithDebInfo. Then, we run our program using valgrind to capture the run-time statistics for later analysis. These are stored incallgrind.out.XXXfiles, where the suffix is the PID of the process. kcachegrind is used to visualize and analyze the results of the program execution.


key: chroma:document
string_value:
## Profile from a Node As in our generic example, for a given node, we need to compile with debug flags to capture the information for profiling with Valgrind. This can be done easily from the commandline. Note that we use--packages-selectto only compile with this flag for the packages we want to profile nodes within. Optionally, you may add the following line to theCMakeLists.txtof the package you’re looking to profile. This may be preferable when you have a workspace with many packages but would like to only compile a subset with debug information using a singlecolconbuildinvocation. It is important that this should be added to both the host server and plugin packages(s) if you would like the results of a plugin’s run-time profile. After either compiling method, this node should be run in its own terminal to isolate it from the rest of your system. Thus, this should not be composed in the same process as other nodes. To run a ROS 2 node with valgrind, this can be done from the commandline via: An example


key: chroma:document
string_value:
valgrind, this can be done from the commandline via: An example of this might be used for profiling the controller server with a particular controller plugin loaded. Bothnav2_controllerand the plugin package of interest are compiled with debug flags. In the example below, we are running a ROS 2 node with remapped topics and a path to its parameter file: Once sufficient data has been collected, cleanly exit the process with Control+C.


key: chroma:document
string_value:
## Profile from a Launch File Just as in the Node example, we must also compile with debug flags when profiling a node from launch. We can complete the same valgrind call as from the commandline as within a launch file using launch prefixes. As our example before, this is how we’d launch thecontroller_servernode from inside a launch file. Note that just like before, we should isolate this process from others. So this should not be run with any other nodes in this launch file nor use node composition when profiling a particular node. Once sufficient data has been collected, cleanly exit the process with Control+C.


key: chroma:document
string_value:
## From Nav2 Bringup Because Nav2 bringup has more than one node per launch file (and in the caseuse_composition=true, more than one per process), it is necessary to separate out a particular node that you’re interested in profiling from the rest of the system. As previously described, once they’re isolated in either a launch file or as a node to be launched on the commandline, they can easily be run to collect the callgrind information. The steps within Nav2 are as follows: It is important that the profiler node is launched before Nav2 so that it can take the signals from the lifecycle manager to transition up.


key: chroma:document
string_value:
## Interpreting Results Once you have yourcallgrindresults, regardless of if you did it through a node, launch file, Nav2, or elsewhere, now we can analyze the results from the profiler to identify bottlenecks or potential areas of improvement. Usingkcachegrind: This should open a window looking like below. The left side shows all of the calls and their relative percentages of compute time they and their children functions utilized. If you select the top level entry on the left sidebar, then select “Call Graph” at the bottom of the right workspace, it should show you a call graph of where the compute time was spent as a graph of method calls. This can be exceptionally helpful to find the methods where the most time is spent.

Code Examples:

Language: unknown

File: kcachegrind

```

sudo

apt

install

valgrind

kcachegrind

```

Language: unknown

File: callgrind.out.XXX

```

# CMakeLists.txt

add_compile_options

(

g

)

```

Language: unknown

File: callgrind.out.XXX

```

cmake

DCMAKE_BUILD_TYPE

=


key: chroma:document
string_value:
File: callgrind.out.XXX

```

cmake

DCMAKE_BUILD_TYPE

=

RelWithDebInfo

```

Language: unknown

File: callgrind.out.XXX

```

valgrind

tool

=

callgrind

[

your

program

]

[

program

options

]

kcachegrind

callgrind.out.XXX

```

Language: unknown

File: -

packages

select

```

colcon

build

packages

select

<packages

of

interest>

cmake

args

DCMAKE_BUILD_TYPE

=

RelWithDebInfo

```

Language: unknown

File: colconbuild

```

add_compile_options

(

pg

)

```

Language: unknown

File: colconbuild

```

ros2

run

prefix

'valgrind -

tool=callgrind'

<pkg>

<node>

all

other

launch

arguments

```

Language: unknown

File: nav2_controller

```

ros2

run

prefix

'valgrind -

tool=callgrind'

nav2_controller

controller_server

ros

args

r

__node:

=

controller_server

r

cmd_vel:

=

cmd_vel_nav

params

file

/path/to/nav2_bringup/params/nav2_params.yaml

```

Language: unknown

File: controller_server

```

start_controller_server_node

=

Node

(

parameters

=

[


key: chroma:document
string_value:
start_controller_server_node

=

Node

(

parameters

=

[

get_package_share_directory

(

"nav2_bringup"

)

+

'/params/nav2_params.yaml'

,

{

'use_sim_time'

:

use_sim_time

}

],

package

=

'nav2_controller'

,

executable

=

'controller_server'

,

name

=

'controller_server'

,

prefix

=

[

'xterm

e valgrind -

tool=callgrind'

],

output

=

'screen'

)

```

Language: unknown

File: kcachegrind

```

kcachegrind

callgrind.out.XXX

```


key: chroma:document
string_value:
Title: Controller Server

URL: https://docs.nav2.org/configuration/packages/configuring-controller-server.html#example

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Parameters

## Provided Plugins

## Default Plugins

When theprogress_checker_plugins,goal_checker_pluginorcontroller_pluginsparameters are not overridden, the following default plugins are loaded:

## Example

Code Examples:

Language: unknown

File: plugin

```

controller_server

:

ros__parameters

:

controller_plugins

:

[

"FollowPath"

]

FollowPath

:

plugin

:

"dwb_core::DWBLocalPlanner"

```

Language: unknown

File: plugin

```

controller_server

:

ros__parameters

:

progress_checker_plugins

:

[

"progress_checker"

]

# progress_checker_plugin: "progress_checker" For Humble and older

progress_checker

:

plugin

:

"nav2_controller::SimpleProgressChecker"

```

Language: unknown

File: plugin

```

controller_server

:

ros__parameters

:


key: chroma:document
string_value:
File: plugin

```

controller_server

:

ros__parameters

:

goal_checker_plugins

:

[

"goal_checker"

]

goal_checker

:

plugin

:

"nav2_controller::SimpleGoalChecker"

```

Language: unknown

File: controller_plugins

```

controller_server

:

ros__parameters

:

use_sim_time

:

True

controller_frequency

:

20.0

min_x_velocity_threshold

:

0.001

min_y_velocity_threshold

:

0.5

min_theta_velocity_threshold

:

0.001

failure_tolerance

:

0.3

odom_topic

:

"odom"

progress_checker_plugins

:

[

"progress_checker"

]

# progress_checker_plugin: "progress_checker" For Humble and older

goal_checker_plugins

:

[

"goal_checker"

]

# goal_checker_plugin: "goal_checker" For Galactic and older

controller_plugins

:

[

"FollowPath"

]

progress_checker

:

plugin

:

"nav2_controller::SimpleProgressChecker"

required_movement_radius

:

0.5

movement_time_allowance

:

10.0

goal_checker

:

plugin

:

"nav2_controller::SimpleGoalChecker"

xy_goal_tolerance

:

0.25

yaw_goal_tolerance

:


key: chroma:document
string_value:
xy_goal_tolerance

:

0.25

yaw_goal_tolerance

:

0.25

stateful

:

True

FollowPath

:

plugin

:

"dwb_core::DWBLocalPlanner"

```


key: chroma:document
string_value:
Title: PathLongerOnApproach

URL: https://docs.nav2.org/configuration/packages/bt

plugins/decorators/PathLongerOnApproach.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

<PathLongerOnApproach

path=

"{path}"

prox_len=

"3.0"

length_factor=

"2.0"

>

<!-

Add tree components here--

>

</PathLongerOnApproach>

```


key: chroma:document
string_value:
Title: DWB Controller

URL: https://docs.nav2.org/configuration/packages/configuring-dwb-controller.html#example

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Controller

## Plugins

The plugins listed below are inside thedwb_pluginsnamespace.

## Trajectory Critics

The trajectory critics listed below are inside thedwb_criticsnamespace.

## Example

Code Examples:

Language: unknown

File: dwb_critics

```

controller_server

:

ros__parameters

:

# controller server parameters (see Controller Server for more info)

use_sim_time

:

True

controller_frequency

:

20.0

min_x_velocity_threshold

:

0.001

min_y_velocity_threshold

:

0.5

min_theta_velocity_threshold

:

0.001

progress_checker_plugins

:

[

"progress_checker"

]

# progress_checker_plugin: "progress_checker" For Humble and older

goal_checker_plugins

:

[

"goal_checker"

]

controller_plugins

:

[

"FollowPath"

]

progress_checker

:

plugin

:


key: chroma:document
string_value:
:

[

"FollowPath"

]

progress_checker

:

plugin

:

"nav2_controller::SimpleProgressChecker"

required_movement_radius

:

0.5

movement_time_allowance

:

10.0

goal_checker

:

plugin

:

"nav2_controller::SimpleGoalChecker"

xy_goal_tolerance

:

0.25

yaw_goal_tolerance

:

0.25

stateful

:

True

# DWB controller parameters

FollowPath

:

plugin

:

"dwb_core::DWBLocalPlanner"

debug_trajectory_details

:

True

min_vel_x

:

0.0

min_vel_y

:

0.0

max_vel_x

:

0.26

max_vel_y

:

0.0

max_vel_theta

:

1.0

min_speed_xy

:

0.0

max_speed_xy

:

0.26

min_speed_theta

:

0.0

acc_lim_x

:

2.5

acc_lim_y

:

0.0

acc_lim_theta

:

3.2

decel_lim_x

:

2.5

decel_lim_y

:

0.0

decel_lim_theta

:

3.2

vx_samples

:

20

vy_samples

:

5

vtheta_samples

:

20

sim_time

:

1.7

linear_granularity

:

0.05

angular_granularity

:

0.025

transform_tolerance

:

0.2

xy_goal_tolerance

:

0.25

trans_stopped_velocity

:

0.25

short_circuit_trajectory_evaluation

:

True

limit_vel_cmd_in_traj

:


key: chroma:document
string_value:
:

True

limit_vel_cmd_in_traj

:

False

stateful

:

True

critics

:

[

"RotateToGoal"

,

"Oscillation"

,

"BaseObstacle"

,

"GoalAlign"

,

"PathAlign"

,

"PathDist"

,

"GoalDist"

]

BaseObstacle.scale

:

0.02

PathAlign.scale

:

32.0

GoalAlign.scale

:

24.0

PathAlign.forward_point_distance

:

0.1

GoalAlign.forward_point_distance

:

0.1

PathDist.scale

:

32.0

GoalDist.scale

:

24.0

RotateToGoal.scale

:

32.0

RotateToGoal.slowing_factor

:

5.0

RotateToGoal.lookahead_time

:

1.0

```


key: chroma:document
string_value:
Title: Setting Up Sensors

URL: https://docs.nav2.org/setup_guides/sensors/setup_sensors.html#sensor-introduction

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Sensor Introduction

Mobile robots are equipped with a multitude of sensors that allow them to see and perceive their environment. These sensors obtain information which can be used to build and maintain the map of the environment, to localize the robot on the map, and to see the obstacles in the environment. These tasks are essential to be able to safely and efficiently navigate a robot through a dynamic environment.


key: chroma:document
string_value:
Examples of commonly used sensors are lidar, radar, RGB camera, depth camera, IMU, and GPS. To standardize the message formats of these sensors and allow for easier interoperation between vendors, ROS provides thesensor_msgspackage that defines the common sensor interfaces. This also allows users to use any sensor vendor as long as it follows the standard format insensor_msgs. In the next subsection, we introduce some of commonly used messages in navigation, namely thesensor_msgs/LaserScan,sensor_msgs/PointCloud2,sensor_msgs/Range, andsensor_msgs/Image.


key: chroma:document
string_value:
Aside from thesensor_msgspackage, there are also theradar_msgsandvision_msgsstandard interfaces you should be aware of.  Theradar_msgsdefines the messages for radar-specific sensors while thevision_msgspackage defines the messages used in computer vision such as object detection, segmentation, and other machine learning models. Messages supported by this package arevision_msgs/Classification2D,vision_msgs/Classification3D,vision_msgs/Detection2D, andvision_msgs/Detection3D, to name a few.


key: chroma:document
string_value:
Your physical robot’s sensors probably have ROS drivers written for them (e.g. a ROS node that connects to the sensors, populates data into messages, and publishes them for your robot to use) that follow the standard interface in thesensor_msgspackage. Thesensor_msgspackage makes it easy for you to use many different sensors from different manufacturers. General software packages like Nav2 can then read these standardized messages and perform tasks independent of the sensor hardware. On simulated robots such assam_bot, Gazebo has sensor plugins which also publish their information following thesensor_msgspackage.

## Common Sensor Messages

In this subsection, we discuss some of the common types ofsensor_msgsyou might encounter when setting up Nav2. We will provide a brief description for each sensor, an image of it being simulated in Gazebo and the corresponding visualization of the sensor readings in RViz.

## sensor_msgs/LaserScan


key: chroma:document
string_value:
## sensor_msgs/LaserScan

This message represents a single scan from a planar laser range-finder. This message is used inslam_toolboxandnav2_amclfor localization and mapping, or innav2_costmap_2dfor perception.

## sensor_msgs/PointCloud2

This message holds a collection of 3D points, plus optional additional information about each point. This can be from a 3D lidar, a 2D lidar, a depth camera or more.

## sensor_msgs/Range

This is a single range reading from an active ranger that emits energy and reports one range reading that is valid along an arc at the distance measured. A sonar, IR sensor, or 1D range finder are examples of sensors that use this message.

## sensor_msgs/Image

This represents the sensor readings from RGB or depth camera, corresponding to RGB or range values.

## Simulating Sensors using Gazebo


key: chroma:document
string_value:
## Simulating Sensors using Gazebo

To give you a better grasp of how to set up sensors on a simulated robot, we will build up on our previous tutorials and attach sensors to our simulated robotsam_bot. Similar to the previous tutorial where we used Gazebo plugins to add odometry sensors tosam_bot, we will be using the Gazebo plugins to simulate a lidar sensor and a depth camera onsam_bot. If you are working with a real robot, most of these steps are still required for setting up your URDF frames and it will not hurt to also add in the gazebo plugins for later use.

To be able to follow the rest of this section, make sure that you have properly installed Gazebo. You can follow the instructions at theSetup and Prerequisitesof the previous tutorial to setup Gazebo.

## Adding Gazebo Plugins to a URDF

Let us first add a lidar sensor tosam_bot. Open the URDF file,src/description/sam_bot_description.urdfand paste the following lines before the</robot>tag.


key: chroma:document
string_value:
In the code snippet above, we create alidar_linkwhich will be referenced by thegazebo_ros_ray_sensorplugin as the location to attach our sensor. We also set values to the simulated lidar’s scan and range properties. Lastly, we set the/scanas the topic to which it will publish thesensor_msgs/LaserScanmessages.

Next, let us add a depth camera tosam_bot. Paste the following lines after the</gazebo>tag of the lidar sensor.

Similar to the lidar sensor, we createcamera_linkwhich will be referenced by thegazebo_ros_cameraplugin as the sensor attachment location. We also create acamera_depth_framethat is attached to thecamera_linkand will be set as the<frame_name>of the depth camera plugin.  We also configure the plugin such that it will publishsensor_msgs/Imageandsensor_msgs/PointCloud2messages to/depth_camera/image_rawand/depth_camera/pointstopics respectively. Lastly, we also set up other basic configuration properties for our depth camera.

## Launch and Build Files


key: chroma:document
string_value:
## Launch and Build Files

To verify that the sensors are set up properly and that they can see objects in our environment, let us launchsam_botin a Gazebo world with objects.

Let us create a Gazebo world with a single cube and a single sphere that are within the range ofsam_bot’s sensors so we can verify if it can see the objects correctly.

To create the world, create a directory namedworldat the root of your project and create a file namedmy_world.sdfinside theworldfolder . Then copy the contents ofworld/my_world.sdfand paste them insidemy_world.sdf.

Now, let us edit our launch file,launch/display.launch.py, to launch Gazebo with the world we just created. First, add the path ofmy_world.sdfby adding the following lines inside thegenerate_launch_description():

Lastly, add the world path in thelaunch.actions.ExecuteProcess(cmd=['gazebo',...line, as shown below.


key: chroma:document
string_value:
We also have to add theworlddirectory to ourCMakeLists.txtfile. OpenCmakeLists.txtand append theworlddirectory inside the install(DIRECTORY…), as shown in the snippet below.

## Build, Run and Verification

We can now build and run our project. Navigate to the root of the project and execute the following lines:

RViz and the Gazebo will then be launched withsam_botpresent in both. In the Gazebo window, the world that we created should be launched andsam_botshould be spawned in that world. You should now be able to observesam_botwith the 360 lidar sensor and the depth camera, as shown in the image below.

In the RViz window, we can verify if we have properly modeled our sensors and if the transforms of our newly added sensors are correct:

Lastly, we can also visualize the sensor readings in RViz.  To visualize thesensor_msgs/LaserScanmessage published on/scantopic, click the add button at the bottom part of the RViz window. Then go to theBytopictab and select theLaserScanoption under/scan, as shown below.


key: chroma:document
string_value:
Next, set theReliabilityPolicyin RViz toBestEffortand set thesizeto 0.1 to see the points clearer. You should see the visualizedLaserScandetection as shown below. This corresponds to the detected cube and sphere that we added to the Gazebo world.

To visualizesensor_msgs/Imageandsensor_msgs/PointCloud2, do the same for topics/depth_camera/image_rawand/depth_camera/pointsrespectively:

After adding the/depth_camera/image_rawtopic in RViz, set theReliabilityPolicyin RViz toBestEffort. Then you should see the cube in the image window at the lower-left side of the RViz window, as shown below.

You should also see thesensor_msgs/PointCloud2, as shown below.

## Mapping and Localization


key: chroma:document
string_value:
## Mapping and Localization

Now that we have a robot with its sensors set up, we can use the obtained sensor information to build a map of the environment and to localize the robot on the map. Theslam_toolboxpackage is a set of tools and capabilities for 2D Simultaneous Localization and Mapping (SLAM) in potentially massive maps with ROS2. It is also one of the officially supported SLAM libraries in Nav2, and we recommend to use this package in situations you need to use SLAM on your robot setup. Aside from theslam_toolbox, localization can also be implemented through thenav2_amclpackage. This package implements Adaptive Monte Carlo Localization (AMCL) which estimates the position and orientation of the robot in a map. Other techniques may also be available, please check Nav2 documentation for more information.


key: chroma:document
string_value:
Both theslam_toolboxandnav2_amcluse information from the laser scan sensor to be able to perceive the robot’s environment. Hence, to verify that they can access the laser scan sensor readings, we must make sure that they are subscribed to the correct topic that publishes thesensor_msgs/LaserScanmessage. This can be configured by setting theirscan_topicparameters to the topic that publishes that message. It is a convention to publish thesensor_msgs/LaserScanmessages to/scantopic. Thus, by default, thescan_topicparameter is set to/scan. Recall that when we added the lidar sensor tosam_botin the previous section, we set the topic to which the lidar sensor will publish thesensor_msgs/LaserScanmessages as/scan.

In-depth discussions on the complete configuration parameters will not be a scope of our tutorials since they can be pretty complex. Instead, we recommend you to have a look at their official documentation in the links below.


key: chroma:document
string_value:
You can also refer to the(SLAM) Navigating While Mapping guidefor the tutorial on how to use Nav2 with SLAM. You can verify thatslam_toolboxandnav2_amclhave been correctly setup by visualizing the map and the robot’s pose in RViz, similar to what was shown in the previous section.

## Costmap 2D

The costmap 2D package makes use of the sensor information to provide a representation of the robot’s environment in the form of an occupancy grid. The cells in the occupancy grid store cost values between 0-254 which denote a cost to travel through these zones. A cost of 0 means the cell is free while a cost of 254 means that the cell is lethally occupied. Values in between these extremes are used by navigation algorithms to steer your robot away from obstacles as a potential field. Costmaps in Nav2 are implemented through thenav2_costmap_2dpackage.


key: chroma:document
string_value:
The costmap implementation consists of multiple layers, each of which has a certain function that contributes to a cell’s overall cost. The package consists of the following layers, but are plugin-based to allow customization and new layers to be used as well: static layer, inflation layer, range layer, obstacle layer, and voxel layer. The static layer represents the map section of the costmap, obtained from the messages published to the/maptopic like those produced by SLAM.  The obstacle layer includes the objects detected by sensors that publish either or both theLaserScanandPointCloud2messages. The voxel layer is similar to the obstacle layer such that it can use either or both theLaserScanandPointCloud2sensor information but handles 3D data instead. The range layer allows for the inclusion of information provided by sonar and infrared sensors. Lastly, the inflation layer represents the added cost values around lethal obstacles such that our robot avoids navigating into obstacles due to the robot’s


key: chroma:document
string_value:
our robot avoids navigating into obstacles due to the robot’s geometry. In the next subsection of this tutorial, we will have some discussion about the basic configuration of the different layers innav2_costmap_2d.


key: chroma:document
string_value:
The layers are integrated into the costmap through a plugin interface and then inflated using a user-specifiedinflation radius, if the inflation layer is enabled. For a deeper discussion on costmap concepts, you can have a look at theROS1 costmap_2D documentation. Note that thenav2_costmap_2dpackage is mostly a straightforward ROS2 port of the ROS1 navigation stack version with minor changes required for ROS2 support and some new layer plugins.

## Configuring nav2_costmap_2d


key: chroma:document
string_value:
## Configuring nav2_costmap_2d

In this subsection, we will show an example configuration ofnav2_costmap_2dsuch that it uses the information provided by the lidar sensor ofsam_bot. We will show an example configuration that uses static layer, obstacle layer, voxel layer, and inflation layer. We set both the obstacle and voxel layer to use theLaserScanmessages published  to the/scantopic by the lidar sensor. We also set some of the basic parameters to define how the detected obstacles are reflected in the costmap. Note that this configuration is to be included in the configuration file of Nav2.

In the configuration above, notice that we set the parameters for two different costmaps:global_costmapandlocal_costmap. We set up two costmaps since theglobal_costmapis mainly used for long-term planning over the whole map whilelocal_costmapis for short-term planning and collision avoidance.


key: chroma:document
string_value:
The layers that we use for our configuration are defined in thepluginsparameter, as shown in line 13 for theglobal_costmapand line 50 for thelocal_costmap. These values are set as a list of mapped layer names that also serve as namespaces for the layer parameters we set up starting at lines 14 and line 51. Note that each layer/namespace in this list must have apluginparameter (as indicated in lines 15, 18, 32, 52, and 68) defining the type of plugin to be loaded for that specific layer.

For the static layer (lines 14-16), we set themap_subscribe_transient_localparameter toTrue. This sets the QoS settings for the map topic. Another important parameter for the static layer is themap_topicwhich defines the map topic to subscribe to. This defaults to/maptopic when not defined.


key: chroma:document
string_value:
For the obstacle layer (lines 17-30), we define its sensor source under theobservation_sourcesparameter (line 20) asscanwhose parameters are set up in lines 22-30. We set itstopicparameter as the topic that publishes the defined sensor source and we set thedata_typeaccording to the sensor source it will use. In our configuration, the obstacle layer will use theLaserScanpublished by the lidar sensor to/scan.

Note that the obstacle layer and voxel layer can use either or bothLaserScanandPointCloud2as theirdata_typebut it is set toLaserScanby default. The code snippet below shows an example of using both theLaserScanandPointCloud2as the sensor sources. This may be particularly useful when setting up your own physical robot.


key: chroma:document
string_value:
For the other parameters of the obstacle layer, themax_obstacle_heightparameter sets the maximum height of the sensor reading to return to the occupancy grid. The minimum height of the sensor reading can also be set using themin_obstacle_heightparameter, which defaults to 0 since we did not set it in the configuration. Theclearingparameter is used to set whether the obstacle is to be removed from the costmap or not. The clearing operation is done by raytracing through the grid. The maximum and minimum range to raytrace clear objects from the costmap is set using theraytrace_max_rangeandraytrace_min_rangerespectively. Themarkingparameter is used to set whether the inserted obstacle is marked into the costmap or not. We also set the maximum and minimum range to mark obstacles in the costmap through theobstacle_max_rangeandobstacle_min_rangerespectively.


key: chroma:document
string_value:
For the inflation layer (lines 31-34 and 67-70), we set the exponential decay factor across the inflation radius using thecost_scaling_factorparameter. The value of the radius to inflate around lethal obstacles is defined using theinflation_radius.

For the voxel layer (lines 51-66), we set thepublish_voxel_mapparameter toTrueto enable the publishing of the 3D voxel grid. The resolution of the voxels in height is defined using thez_resolutionparameter, while the number of voxels in each column is defined using thez_voxelsparameter. Themark_thresholdparameter sets the minimum number of voxels in a column to mark as occupied in the occupancy grid. We set theobservation_sourcesparameter of the voxel layer toscan, and we set the scan parameters (in lines 61-66) similar to the parameters that we have discussed for the obstacle layer. As defined in itstopicanddata_typeparameters, the voxel layer will use theLaserScanpublished on the/scantopic by the lidar scanner.


key: chroma:document
string_value:
Note that the we are not using a range layer for our configuration but it may be useful for your own robot setup. For the range layer, its basic parameters are thetopics,input_sensor_type, andclear_on_max_readingparameters. The range topics to subscribe to are defined in thetopicsparameter. Theinput_sensor_typeis set to eitherALL,VARIABLE, orFIXED. Theclear_on_max_readingis a boolean parameter that sets whether to clear the sensor readings on max range.  Have a look at the configuration guide in the link below in case you need to set it up.

## Build, Run and Verification


key: chroma:document
string_value:
## Build, Run and Verification

We will first launchdisplay.launch.pywhich launches the robot state publisher that provides thebase_link=>sensorstransformations in our URDF. It also launches Gazebo that acts as our physics simulator and also provides theodom=>base_linkfrom the differential drive plugin, which we added tosam_botin the previous guide,Simulating an Odometry System Using Gazebo. It also launches RViz which we can use to visualize the robot and sensor information.

Then we will launchslam_toolboxto publish to/maptopic and provide themap=>odomtransform. Recall that themap=>odomtransform is one of the primary requirements of the Nav2 system. The messages published on the/maptopic will then be used by the static layer of theglobal_costmap.


key: chroma:document
string_value:
After we have properly setup our robot description, odometry sensors, and necessary transforms, we will finally launch the Nav2 system itself. For now, we will only be exploring the costmap generation system of Nav2. After launching Nav2, we will visualize the costmaps in RViz to confirm our output.

## Launching Description Nodes, RViz and Gazebo

Let us now launch our Robot Description Nodes, RViz and Gazebo through the launch filedisplay.launch.py. Open a new terminal and execute the lines below.

RViz and the Gazebo should now be launched withsam_botpresent in both. Recall that thebase_link=>sensorstransform is now being published byrobot_state_publisherand theodom=>base_linktransform by our Gazebo plugins. Both transforms should now be displayed show without errors in RViz.

## Launching slam_toolbox

To be able to launchslam_toolbox, make sure that you have installed theslam_toolboxpackage by executing the following command:


key: chroma:document
string_value:
We will launch theasync_slam_toolbox_nodeofslam_toolboxusing the package’s built-in launch files. Open a new terminal and then execute the following lines:

Theslam_toolboxshould now be publishing to the/maptopic and providing themap=>odomtransform.

We can verify in RViz that the/maptopic is being published. In the RViz window, click the add button at the bottom-left part then go toBytopictab then select theMapunder the/maptopic. You should be able to visualize the message received in the/mapas shown in the image below.

We can also check that the transforms are correct by executing the following lines in a new terminal:

Note: For Galactic and newer, it should beview_framesand notview_frames.pyThe line above will create aframes.pdffile that shows the current transform tree. Your transform tree should be similar to the one shown below:

## Launching Nav2

First, Make sure you have installed the Nav2 packages by executing the following:


key: chroma:document
string_value:
We will now launch Nav2 using thenav2_bringup’s built-in launch file,navigation_launch.py. Open a new terminal and execute the following:

Note that the parameters of thenav2_costmap_2dthat we discussed in the previous subsection are included in the default parameters ofnavigation_launch.py. Aside from thenav2_costmap_2dparameters, it also contains parameters for the other nodes that are included in Nav2 implementation.

After we have properly set up and launched Nav2, the/global_costmapand/local_costmaptopics should now be active.

## Visualizing Costmaps in RViz

Theglobal_costmap,local_costmapand the voxel representation of the detected obstacles can be visualized in RViz.


key: chroma:document
string_value:
To visualize theglobal_costmapin RViz, click the add button at the bottom-left part of the RViz window. Go toBytopictab then select theMapunder the/global_costmap/costmaptopic. Theglobal_costmapshould show in the RViz window, as shown below. Theglobal_costmapshows areas which should be avoided (black) by our robot when it navigates our simulated world in Gazebo.

To visualize thelocal_costmapin RViz, select theMapunder the/local_costmap/costmaptopic. Set thecolorschemein RViz tocostmapto make it appear similar to the image below.

To visualize the voxel representation of the detected object, open a new terminal and execute the following lines:

The line above sets the topic where the the markers will be published to/my_marker. To see the markers in RViz, selectMarkerunder the/my_markertopic, as shown below.

Then set thefixedframein RViz toodomand you should now see the voxels in RViz, which represent the cube and the sphere that we have in the Gazebo world:

## Conclusion


key: chroma:document
string_value:
## Conclusion

In this section of our robot setup guide, we have discussed the importance of sensor information for different tasks associated with Nav2. More specifically, tasks such as mapping (SLAM), localization (AMCL), and perception (costmap) tasks.

We also had a discussion on the common types of sensor messages in Nav2 which standardize the message formats for different sensor vendors. We also discussed how to add sensors to a simulated robot using Gazebo and how to verify that the sensors are working correctly through RViz.

Lastly, we set up a basic configuration for thenav2_costmap_2dpackage using different layers to produce a global and local costmap. We then verify our work by visualizing these costmaps in RViz.

Code Examples:

Language: unknown

File: </robot>

```

251

<link

name=

"lidar_link"

>

252

<inertial>

253

<origin

xyz=

"0 0 0"

rpy=

"0 0 0"

/>

254

<mass

value=

"0.125"

/>

255

<inertia

ixx=

"0.001"

ixy=

"0"

ixz=

"0"

iyy=

"0.001"

iyz=

"0"

izz=

"0.001"

/>


key: chroma:document
string_value:
"0"

ixz=

"0"

iyy=

"0.001"

iyz=

"0"

izz=

"0.001"

/>

256

</inertial>

257

258

<collision>

259

<origin

xyz=

"0 0 0"

rpy=

"0 0 0"

/>

260

<geometry>

261

<cylinder

radius=

"0.0508"

length=

"0.055"

/>

262

</geometry>

263

</collision>

264

265

<visual>

266

<origin

xyz=

"0 0 0"

rpy=

"0 0 0"

/>

267

<geometry>

268

<cylinder

radius=

"0.0508"

length=

"0.055"

/>

269

</geometry>

270

</visual>

271

</link>

272

273

<joint

name=

"lidar_joint"

type=

"fixed"

>

274

<parent

link=

"base_link"

/>

275

<child

link=

"lidar_link"

/>

276

<origin

xyz=

"0 0 0.12"

rpy=

"0 0 0"

/>

277

</joint>

278

279

<gazebo

reference=

"lidar_link"

>

280

<sensor

name=

"lidar"

type=

"ray"

>

281

<always_on>

true

</always_on>

282

<visualize>

true

</visualize>

283

<update_rate>

5

</update_rate>

284

<ray>

285

<scan>

286

<horizontal>

287

<samples>

360

</samples>

288

<resolution>

1.000000

</resolution>

289

<min_angle>

0.000000


key: chroma:document
string_value:
1.000000

</resolution>

289

<min_angle>

0.000000

</min_angle>

290

<max_angle>

6.280000

</max_angle>

291

</horizontal>

292

</scan>

293

<range>

294

<min>

0.120000

</min>

295

<max>

3.5

</max>

296

<resolution>

0.015000

</resolution>

297

</range>

298

<noise>

299

<type>

gaussian

</type>

300

<mean>

0.0

</mean>

301

<stddev>

0.01

</stddev>

302

</noise>

303

</ray>

304

<plugin

name=

"scan"

filename=

"libgazebo_ros_ray_sensor.so"

>

305

<ros>

306

<remapping>

~/out:=scan

</remapping>

307

</ros>

308

<output_type>

sensor_msgs/LaserScan

</output_type>

309

<frame_name>

lidar_link

</frame_name>

310

</plugin>

311

</sensor>

312

</gazebo>

```

Language: unknown

File: </gazebo>

```

314

<link

name=

"camera_link"

>

315

<visual>

316

<origin

xyz=

"0 0 0"

rpy=

"0 0 0"

/>

317

<geometry>

318

<box

size=

"0.015 0.130 0.022"

/>

319

</geometry>

320

</visual>

321

322

<collision>

323

<origin

xyz=

"0 0 0"

rpy=

"0 0 0"

/>

324


key: chroma:document
string_value:
323

<origin

xyz=

"0 0 0"

rpy=

"0 0 0"

/>

324

<geometry>

325

<box

size=

"0.015 0.130 0.022"

/>

326

</geometry>

327

</collision>

328

329

<inertial>

330

<origin

xyz=

"0 0 0"

rpy=

"0 0 0"

/>

331

<mass

value=

"0.035"

/>

332

<inertia

ixx=

"0.001"

ixy=

"0"

ixz=

"0"

iyy=

"0.001"

iyz=

"0"

izz=

"0.001"

/>

333

</inertial>

334

</link>

335

336

<joint

name=

"camera_joint"

type=

"fixed"

>

337

<parent

link=

"base_link"

/>

338

<child

link=

"camera_link"

/>

339

<origin

xyz=

"0.215 0 0.05"

rpy=

"0 0 0"

/>

340

</joint>

341

342

<link

name=

"camera_depth_frame"

/>

343

344

<joint

name=

"camera_depth_joint"

type=

"fixed"

>

345

<origin

xyz=

"0 0 0"

rpy=

"${-pi/2} 0 ${-pi/2}"

/>

346

<parent

link=

"camera_link"

/>

347

<child

link=

"camera_depth_frame"

/>

348

</joint>

349

350

<gazebo

reference=

"camera_link"

>

351

<sensor

name=

"depth_camera"

type=

"depth"

>

352

<visualize>

true

</visualize>

353


key: chroma:document
string_value:
type=

"depth"

>

352

<visualize>

true

</visualize>

353

<update_rate>

30.0

</update_rate>

354

<camera

name=

"camera"

>

355

<horizontal_fov>

1.047198

</horizontal_fov>

356

<image>

357

<width>

640

</width>

358

<height>

480

</height>

359

<format>

R8G8B8

</format>

360

</image>

361

<clip>

362

<near>

0.05

</near>

363

<far>

3

</far>

364

</clip>

365

</camera>

366

<plugin

name=

"depth_camera_controller"

filename=

"libgazebo_ros_camera.so"

>

367

<baseline>

0.2

</baseline>

368

<alwaysOn>

true

</alwaysOn>

369

<updateRate>

0.0

</updateRate>

370

<frame_name>

camera_depth_frame

</frame_name>

371

<pointCloudCutoff>

0.5

</pointCloudCutoff>

372

<pointCloudCutoffMax>

3.0

</pointCloudCutoffMax>

373

<distortionK1>

0

</distortionK1>

374

<distortionK2>

0

</distortionK2>

375

<distortionK3>

0

</distortionK3>

376

<distortionT1>

0

</distortionT1>

377

<distortionT2>

0

</distortionT2>

378

<CxPrime>

0

</CxPrime>

379

<Cx>

0

</Cx>


key: chroma:document
string_value:
378

<CxPrime>

0

</CxPrime>

379

<Cx>

0

</Cx>

380

<Cy>

0

</Cy>

381

<focalLength>

0

</focalLength>

382

<hackBaseline>

0

</hackBaseline>

383

</plugin>

384

</sensor>

385

</gazebo>

```

Language: unknown

File: generate_launch_description()

```

world_path

=

os.path.join

(

pkg_share,

'world/my_world.sdf'

)

```

Language: unknown

File: launch.actions.ExecuteProcess(cmd=['gazebo',...

```

launch.actions.ExecuteProcess

(

cmd

=[

'gazebo'

,

'--verbose'

,

'-s'

,

'libgazebo_ros_init.so'

,

'-s'

,

'libgazebo_ros_factory.so'

,

world_path

]

,

output

=

'screen'

)

,

```

Language: unknown

File: world

```

install

(

DIRECTORY

src

launch

rviz

config

world

DESTINATION

share/

${

PROJECT_NAME

}

)

```

Language: unknown

File: world

```

colcon

build

.

install/setup.bash

ros2

launch

sam_bot_description

display.launch.py

```

Language: unknown

File: /scan

```

1

global_costmap

:

2

global_costmap

:

3

ros__parameters

:

4

update_frequency


key: chroma:document
string_value:
global_costmap

:

3

ros__parameters

:

4

update_frequency

:

1.0

5

publish_frequency

:

1.0

6

global_frame

:

map

7

robot_base_frame

:

base_link

8

use_sim_time

:

True

9

robot_radius

:

0.22

10

resolution

:

0.05

11

track_unknown_space

:

false

12

rolling_window

:

false

13

plugins

:

[

"static_layer"

,

"obstacle_layer"

,

"inflation_layer"

]

14

static_layer

:

15

plugin

:

"nav2_costmap_2d::StaticLayer"

16

map_subscribe_transient_local

:

True

17

obstacle_layer

:

18

plugin

:

"nav2_costmap_2d::ObstacleLayer"

19

enabled

:

True

20

observation_sources

:

scan

21

scan

:

22

topic

:

/scan

23

max_obstacle_height

:

2.0

24

clearing

:

True

25

marking

:

True

26

data_type

:

"LaserScan"

27

raytrace_max_range

:

3.0

28

raytrace_min_range

:

0.0

29

obstacle_max_range

:

2.5

30

obstacle_min_range

:

0.0

31

inflation_layer

:

32

plugin

:

"nav2_costmap_2d::InflationLayer"

33

cost_scaling_factor

:

3.0

34

inflation_radius


key: chroma:document
string_value:
33

cost_scaling_factor

:

3.0

34

inflation_radius

:

0.55

35

always_send_full_costmap

:

True

36

37

local_costmap

:

38

local_costmap

:

39

ros__parameters

:

40

update_frequency

:

5.0

41

publish_frequency

:

2.0

42

global_frame

:

odom

43

robot_base_frame

:

base_link

44

use_sim_time

:

True

45

rolling_window

:

true

46

width

:

3

47

height

:

3

48

resolution

:

0.05

49

robot_radius

:

0.22

50

plugins

:

[

"voxel_layer"

,

"inflation_layer"

]

51

voxel_layer

:

52

plugin

:

"nav2_costmap_2d::VoxelLayer"

53

enabled

:

True

54

publish_voxel_map

:

True

55

origin_z

:

0.0

56

z_resolution

:

0.05

57

z_voxels

:

16

58

max_obstacle_height

:

2.0

59

mark_threshold

:

0

60

observation_sources

:

scan

61

scan

:

62

topic

:

/scan

63

max_obstacle_height

:

2.0

64

clearing

:

True

65

marking

:

True

66

data_type

:

"LaserScan"

67

inflation_layer

:

68

plugin

:

"nav2_costmap_2d::InflationLayer"

69


key: chroma:document
string_value:
:

68

plugin

:

"nav2_costmap_2d::InflationLayer"

69

cost_scaling_factor

:

3.0

70

inflation_radius

:

0.55

71

always_send_full_costmap

:

True

```

Language: unknown

File: PointCloud2

```

obstacle_layer:

plugin:

"nav2_costmap_2d::ObstacleLayer"

enabled:

True

observation_sources:

scan

pointcloud

scan:

topic:

/scan

data_type:

"LaserScan"

pointcloud:

topic:

/depth_camera/points

data_type:

"PointCloud2"

```

Language: unknown

File: display.launch.py

```

colcon

build

.

install/setup.bash

ros2

launch

sam_bot_description

display.launch.py

```

Language: unknown

File: slam_toolbox

```

sudo

apt

install

ros-<ros2-distro>-slam-toolbox

```

Language: unknown

File: slam_toolbox

```

ros2

launch

slam_toolbox

online_async_launch.py

```

Language: unknown

File: /map

```

ros2

run

tf2_tools

view_frames.py

```

Language: unknown

File: frames.pdf

```

sudo

apt

install

ros-<ros2-distro>-navigation2

sudo

apt

install

ros-<ros2-distro>-nav2-bringup

```


key: chroma:document
string_value:
sudo

apt

install

ros-<ros2-distro>-nav2-bringup

```

Language: unknown

File: navigation_launch.py

```

ros2

launch

nav2_bringup

navigation_launch.py

```

Language: unknown

File: costmap

```

ros2

run

nav2_costmap_2d

nav2_costmap_2d_markers

voxel_grid:

=

/local_costmap/voxel_grid

visualization_marker:

=

/my_marker

```


key: chroma:document
string_value:
Title: Nav2

URL: https://docs.nav2.org/index.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Our Sponsors

## Services

If you need professional services related to Nav2, please contact Open Navigation atinfo@opennav.org.

## Overview

Nav2 is the professionally-supported successor of the ROS Navigation Stack deploying the same kinds of technology powering Autonomous Vehicles brought down, optimized, and reworked for mobile and surface robotics.

This project allows for mobile robots to navigate through complex environments to complete user-defined application tasks with nearly any class of robot kinematics.

Not only can it move from Point A to Point B, but it can have intermediary poses, and represent other types of tasks like object following, complete coverage navigation, and more.

Nav2 is a production-grade and high-quality navigation framework trusted by 100+ companies worldwide.


key: chroma:document
string_value:
It provides perception, planning, control, localization, visualization, and much more to build highly reliable autonomous systems.

This will compute an environmental model from sensor and semantic data, dynamically path plan, compute velocities for motors, avoid obstacles, and structure higher-level robot behaviors.

To learn more about this project, such as related projects, robots using, ROS1 comparison, and maintainers, seeAbout and Contact.

To learn more about navigation and ROS concepts, seeNavigation Concepts.

Nav2 uses behavior trees to create customized and intelligent navigation behavior via orchestrating many independent modular servers.

A task server can be used to compute a path, control effort, behavior, or any other navigation

related task. These separate servers communicate with the behavior tree (BT)

over a ROS interface such as an action server or service.

A robot may utilize potentially many different behavior trees to allow a robot to perform many types of unique and complex tasks.


key: chroma:document
string_value:
The diagram below will give you a good first-look at the structure of Nav2.

Note that it is possible to have multiple plugins for controllers, planners,

and recoveries in each of their servers. This can be used to create contextual navigation behaviors.

Each of the servers also returns status indicators back to the BT Navigator in order to enact contextual behaviors based on their results.

The expected inputs to Nav2 are TF transformations conforming to REP-105, a

map source if utilizing the Static Costmap Layer, a BT XML file, and any relevant sensor data

sources. It will then provide valid velocity commands for the motors of a holonomic or

non-holonomic robot to follow when properly configured. We currently support all of the major robot types:

holonomic, differential-drive, legged, and ackermann (car-like) base types! We support

them uniquely with both circular and arbitrarily-shaped robots for SE2 collision checking.

It has tools to:

We also provide a set of starting plugins to get you going.


key: chroma:document
string_value:
We also provide a set of starting plugins to get you going.

A list of all plugins can be found onNavigation Plugins- but they include algorithms for the spanning cross section of common behaviors and robot platform types.

## Related Projects

Check out related projects to Nav2:

## Citations

If you use the navigation framework, an algorithm from this repository, or ideas from it

please cite this work in your papers!

S. Macenski, F. Martín, R. White, J. Clavero.The Marathon 2: A Navigation System.

IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2020.

IROS 2020 talk on Nav2 Marathon Experiments:

If you use any of the algorithms in Nav2 or the analysis of the algorithms in your work, please cite this work in your papers!

S. Macenski, T. Moore, DV Lu, A. Merzlyakov, M. Ferguson,From the desks of ROS maintainers: A survey of modern & capable mobile robotics algorithms in the robot operating system 2,

Robotics and Autonomous Systems, 2023


key: chroma:document
string_value:
Robotics and Autonomous Systems, 2023

Smac Planner (Hybrid A*, State Lattice, 2D):

S. Macenski, M. Booker, J. Wallace,Open-Source, Cost-Aware Kinematically Feasible Planning for Mobile and Surface Robotics,

Regulated Pure Pursuit Controller:

S. Macenski, S. Singh, F. Martin, J. Gines,Regulated Pure Pursuit for Robot Path Tracking,

Autonomous Robots, 2023.

VSLAM and formal comparisons for service robot needs:

A. Merzlyakov, S. Macenski.A Comparison of Modern General-Purpose Visual SLAM Approaches.

IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2021.

Code Examples:

Language: unknown

File: use_cancel_deceleration

```

@InProceedings

{

macenski2020marathon2,

author

=

{

Macenski,

Steven

and

Martin,

Francisco

and

White,

Ruffin

and

Ginés

Clavero,

Jonatan

}

,

title

=

{

The

Marathon

2

:

A

Navigation

System

}

,

booktitle

=

{

2020

IEEE/RSJ

International

Conference

on

Intelligent

Robots

and

Systems

(

IROS

)}

,

year

=

{

2020

}


key: chroma:document
string_value:
Robots

and

Systems

(

IROS

)}

,

year

=

{

2020

}

}

```

Language: unknown

File: use_cancel_deceleration

```

@article

{

macenski2023survey,

title

={

From

the

desks

of

ROS

maintainers:

A

survey

of

modern

&

capable

mobile

robotics

algorithms

in

the

robot

operating

system

2

}

,

author

={

S.

Macenski,

T.

Moore,

DV

Lu,

A.

Merzlyakov,

M.

Ferguson

}

,

year

={

2023

}

,

journal

=

{

Robotics

and

Autonomous

Systems

}

}

```

Language: unknown

File: use_cancel_deceleration

```

@article

{

macenski2024smac,

title

={

Open-Source,

Cost-Aware

Kinematically

Feasible

Planning

for

Mobile

and

Surface

Robotics

}

,

author

={

Steve

Macenski

and

Matthew

Booker

and

Josh

Wallace

}

,

year

={

2024

}

,

journal

=

{

Arxiv

}

}

```

Language: unknown

File: use_cancel_deceleration

```

@article

{

macenski2023regulated,

title

={

Regulated

Pure

Pursuit

for

Robot

Path

Tracking

}

,

author

={

Steve

Macenski

and


key: chroma:document
string_value:
Robot

Path

Tracking

}

,

author

={

Steve

Macenski

and

Shrijit

Singh

and

Francisco

Martin

and

Jonatan

Gines

}

,

year

={

2023

}

,

journal

=

{

Autonomous

Robots

}

}

```

Language: unknown

File: use_cancel_deceleration

```

@InProceedings

{

vslamComparison2021,

author

=

{

Merzlyakov,

Alexey

and

Macenski,

Steven

}

,

title

=

{

A

Comparison

of

Modern

General-Purpose

Visual

SLAM

Approaches

}

,

booktitle

=

{

2021

IEEE/RSJ

International

Conference

on

Intelligent

Robots

and

Systems

(

IROS

)}

,

year

=

{

2021

}

}

```


key: chroma:document
string_value:
Title: CancelCoverage

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/CancelCoverage.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Example

Code Examples:

Language: unknown

File: server_name

```

<CancelCoverage

server_name=

"compute_complete_coverage"

server_timeout=

"10"

/>

```


key: chroma:document
string_value:
Title: Build Troubleshooting Guide

URL: https://docs.nav2.org/development_guides/build_docs/build_troubleshooting_guide.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Common Nav2 Dependencies Build Failures Still can’t solve it? Let us know about your issue.Open a ticket.

## Reporting Issue


key: chroma:document
string_value:
Title: Collision Monitor

URL: https://docs.nav2.org/configuration/packages/configuring

collision

monitor.html#provided

nodes

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Provided Nodes The nodes listed below are inside thenav2_collision_monitorpackage. See the pages for individual configuration information.


key: chroma:document
string_value:
Title: Galactic to Humble

URL: https://docs.nav2.org/migration/Galactic.html

Section: getting_started/index.html

--------------------------------------------------------------------------------


key: chroma:document
string_value:
## Major improvements to Smac Planners The Smac Planner was significantly improved, of both the 2D and Hybrid-A* implementations, making the paths better, faster, and of higher quality. Additional improvements were made to include aanalytic_expansion_max_lengthparameter such that analytic expansions are limited in their potential length. If the length is too far, reject this expansion. This prevents unsafe shortcutting of paths into higher cost areas far out from the goal itself, let search to the work of getting close before the analytic expansion brings it home. This should never be smaller than 4-5x the minimum turning radius being used, or planning times will begin to spike. Further, the traversal cost and heuristic cost computations were updatedrequiring retuning of your penalty functionsif you have a previously existing configuration. Defaults of the algorithm were also retuned appropriately to the change for similar our of the box behavior as before (to use as a reference).


key: chroma:document
string_value:
## Simple (Python) Commander This PR 2411introduces a new package to Nav2, called thenav2_simple_commander. It is a set of functions in an object,BasicNavigator, which can be used to build Nav2-powered autonomy tasks in Python3 without concerning yourself with the Nav2, ROS 2, or Action server details. It contains a simple API taking common types (primarilyPoseStamped) and handles all of the implementation details behind the hood. For example, this is a simple navigation task using this API: The full API can be found in the README of the package. A number of well commented examples and demos can also be found in the package’s source code at the link prior.

## Reduce Nodes and Executors In order for nav2 to make the best use of ROS 2, we need minimize the number of nodes and executors in nav2, which can improve performance. This functionality has been discussed inthe ticket #816, and carried out in


key: chroma:document
string_value:
## API Change for nav2_core PR 2976changes the API fornav2_core::Controllerandnav2_core::Smootherby replacing the use of shared pointer references(constshared_ptr<>&)to shared pointers(shared_ptr<>). Use of shared pointer references meant that the shared pointer counter was never incremented.


key: chroma:document
string_value:
## Extending the BtServiceNode to process Service-Results This PR 2481andPR 2992addressthe ticketandthis ticketand adds a virtualon_completion()function to theBtServiceNodeclass (can be found here). Similar to the already existing virtualon_wait_for_result()function, it can be overwritten in the child class to react to a respective event with some user-defined operation. The addedon_completion()function will be called after the service interaction of theBtServiceNodehas been successfully completed. The returnedBT::NodeStatuswill set the current status of the BT-Node. Since the function has access to the results of the service, the returned node-status can depend on those service results, for example. The normal behavior of theBtServiceNodeis not affected by introducing theon_completion()function, since the the default implementation still simply returnsBT::NodeStatus::SUCCESS, if the service interaction completed successfully.


key: chroma:document
string_value:
## Including new Rotation Shim Controller Plugin This PR 2718introduces the newnav2_rotation_shim_controller. This controller will check the rough heading difference with respect to the robot and a newly received path. If within a threshold, it will pass the request onto the primary controller to execute. If it is outside of the threshold, this controller will rotate the robot towards that path heading. Once it is within the tolerance, it will then pass off control-execution from this rotation shim controller onto the primary controller plugin. At this point, the robot is still going to be rotating, allowing the current plugin to take control for a smooth hand off into path tracking. The Rotation Shim Controller is suitable for:

## Spawning the robot in Gazebo This PR 2473deletes the pkgnav2_gazebo_spawnerinside nav2_bringup directory. Instead ofnav2_gazebo_spawnerthe Nodespawn_entity.pyofgazebo_rosis recommended to spawn the robot in gazebo. Note that


key: chroma:document
string_value:
## Recovery Behavior Timeout Recoveries in Nav2, spin and backup, now havetime_allowanceports in their BT nodes and request fields in their actions to specify a timeout. This helps ensure that the robot can exit a backup or spin primitive behavior in case it gets stuck or otherwise is unable to backup the full distance over a reasonable block of time.


key: chroma:document
string_value:
## New parameteruse_final_approach_orientationfor the 3 2D planners Pull request 2488adds a new parameteruse_final_approach_orientationto the 3 2D planners (Theta*, SmacPlanner2D and NavFn),falseby default. Iftrue, the last pose of the path generated by the planner will have its orientation set to the approach orientation, i.e. the orientation of the vector connecting the last two points of the path. It allows sending the robot to a position (x,y) instead of a pose (x,y,theta) by effectively ignoring the goal orientation. For example, below, for the same goal with an orientaton pointed left of the screen,use_final_approach_orientation=false(left) anduse_final_approach_orientation=true(right)

## SmacPlanner2D and Theta*: fix goal orientation being ignored This pull request 2488fixesthe  issueof the goal pose orientation being ignored (the end path pose orientation was always set to 0).


key: chroma:document
string_value:
## SmacPlanner2D, NavFn and Theta*: fix small path corner cases This PR 2488ensures the planners are not failing when the distance between the start and the goal is small (i.e. when they are on the same costmap cell), and in that case the output path is constructed with a single pose.

## Change and fix behavior of dynamic parameter change detection Thisandthis PRmodify the method used to catch the changes of dynamic parameters. The motivation was to fix the issue thatvoidon_parameter_event_callback(constrcl_interfaces::msg::ParameterEvent::SharedPtrevent)was called for every parameter change of every node leading to unwanted parameter changes if 2 different nodes had the same parameter name.

## Dynamic Parameters Newly added dynamic parameters to:


key: chroma:document
string_value:
## Dynamic Parameters Newly added dynamic parameters to:

## BT Action Nodes Exception Changes When BT action nodes throw exceptions due to networking or action server failures, they now return a status code ofFAILUREto fail that particular action in the behavior tree to react to. This is in contrast to prior where the exceptions thrown from networking were sent to the root tree which would count as a task-level failure that the tree could not react to.


key: chroma:document
string_value:
## BT Navigator Groot Multiple Navigators This PR 2627creates separate parameters for groot monitoring for the NavToPose and NavThroughPoses navigator types so you can individually track the state of each behavior tree through the ZMQ publisher. This resolves a long-standing problem after we added multiple navigator types to BT Navigator that you could only view the nav to poses BT execution live. BT.CPP and Groot only support one static ZMQ stream at a time, so there is a bit of a quirk where you must locally reset Groot after switching trees in order to view the live stream of the Nav Through Poses BT, if in use. This is a state of the BT.CPP and Groot libraries and not something we can resolve within Nav2. There is some thought into the future regarding complete deprecation of live BT monitoring using Groot due to this quirk and the almost-certain infux of tickets on the topic. Groot will however always be supported for visualizing behavior tree XML files and modifications, simply not visualizing the BT


key: chroma:document
string_value:
tree XML files and modifications, simply not visualizing the BT execution live during robot navigation.


key: chroma:document
string_value:
## Removed Kinematic Limiting in RPP The parametersmax_linear_accelandmax_linear_decelwere removed along with the kinematic limiting in the controller causing instabilities. Instead, use a velocity smoother available in the ROS ecosystem if you would like similar behavior.

## Added Smoother Task Server A new task server was added which loads smoother plugins and executes them to improve quality of an existing planned path. Smoothing action can be called from a behavior tree using SmoothPath action node.PR 2569implements andPR 2875adds in the first of the plugins using it with a simple smoother. Other smoothers are in development and will be added in the future.

## Removed Use Approach Velocity Scaling Param in RPP The parameteruse_approach_linear_velocity_scalingis removed in favor of always on to help in smooth transitions to the goal.This PR 2701implements.


key: chroma:document
string_value:
## Refactored AMCL motion models as plugins This PR 2642creates plugins for the different motion models currently used in AMCL. This functionality enables users to use any custom motion model by creating it as a plugin and changing the robot_model_type parameter to the name of the plugin in nav2_params.yaml file. This helps to use custom motion models without the need to modify the AMCL source code.


key: chroma:document
string_value:
## Dropping Support for Live Groot Monitoring of Nav2 It was a great feature idea but never quite panned out, especially after we introduced multiple navigator types in the BT Navigator server. The issue we run into primarily is that Zero-MQ prevents users from producing multiple logger types in the same process. Since BT nav has multiple servers, the swapping between them for viewing has never had a clean hand off causing folks to file tickets or have nasty logs appear or ZMQ crashes in the background. The BT.CPP client for this doesn’t allow us to have a clean shutdown process so we’re left with hoping that ZMQ properly handles the situation, which it rarely does. Further, Groot only supports visualizing one type of tree at a time so for applications often switching between navigator types, its not possible to use a single groot client, causing great frustration. So, what I propose here is to remove live monitoring of the BT from Nav2.We can still use Groot to modify, visualize, and generally work with


key: chroma:document
string_value:
still use Groot to modify, visualize, and generally work with behavior trees, the only thing being removed is to live view the executing behavior tree as Nav2 is currently executing it (it used to light up the boxes of the current nodes). This was of dubious value anyhow, since the tree ticks so fast its difficult to visualize and get meaningful insights into things as the system is moving so quickly.


key: chroma:document
string_value:
## Replanning Only if Path is Invalid This PR 2591creates two new condition BT node to facilitate replanning only if path becomes invalid rather than constantly replanning. These new nodes were integrated into the default BT.

## Fix CostmapLayer clearArea invert param logic This PR 2772fixes the invert paramlogic of the CostmapLayer clearArea function. Hence correcting the behavior of the clearAroundRobot and clearExceptRegion services and their corresponding BT actions.


key: chroma:document
string_value:
## Dynamic Composition This PR 2750provides a optional bringup based on ROS2 dynamic composition for users. It can be used to compose all Nav2 nodes in a single process instead of launching these nodes separately, which is useful for embedded systems users that need to make optimizations due to harsh resource constraints. it’s used by default, but can be disabled by using the launch argumentuse_composition:=False. Some experiments to show performance improvement of dynamic composition, and the cpu and memory are captured bypsutil: The way of dynamic composition consumes lower memory(saves ~70%),  and lower cpu (saves ~13%) than normal multiple processes.


key: chroma:document
string_value:
## BT Cancel Node This PR 2787caters the users with an abstract node to develop cancel behaviors for different servers present in the Nav2 stack such as the controller_server, recovery_server and so on. As a start, this PR also provides theCancelControlbehavior to cancel the goal given to the controller_server. As an addition to theCancelControlThis PR 2856provides the users with the option to cancel the recoveries such as thebackup,spinandwait.


key: chroma:document
string_value:
## BT PathLongerOnApproach Node In thePR, a new Decorator BT node known asPathLongerOnApproachhas been added to provide with the functionality to check and potentially handle longer path generated due to an obstacle in the given goal proximity. To demonstrate this functionality, a new BTnavigate_to_pose_w_replanning_goal_patience_and_recovery.xmlwould serve both as an example and ready-to-use BT for a specific application that wishes to optimize their process cycle time. Demo of the developed BT can be seen below, where the robot pauses when close to a goal to see if the dynamic obstacle moves out of the way. Else, it executes the replan: Obstacle does not clear at all, withobstacle_clearance_timeto be 3 seconds: Obstacle clears and you can see the robot pass through the (could have been ideally the) same path:


key: chroma:document
string_value:
## BT TruncatePathLocal Node In thePR 2753, a new Action BT node namedTruncatePathLocalhas been added to extract a bounded-length path section near robot to be used e.g. for collision checking or computationally expensive smoothers

## Constrained Smoother Inthe PR 2753, a new Smoother namednav2_constrained_smoother::ConstrainedSmootherhas been added to optimize various path criteria such as smoothness or distance from obstacles, maintaining minimum turning radius

## Replanning at a Constant Rate and if the Path is Invalid This PR 2804introduces a new behavior tree that navigates to pose with consistent replanning and if the path becomes invalid. To facilitate the new behavior tree a new condition node PathExpiringTimer was introduced to trigger replanning at a consistent rate.


key: chroma:document
string_value:
## Euclidean Distance 2D This PR 2865changes Euclidean distance calculation throughout nav2 to project on to the XY plane (i.e. discard any information related to components in Z). This may potentially subtly change the way certain BT nodes, BT Navigators, controller servers, planner servers, and RPP behave if using custom plugins outside the Nav2 ecosystem.

## Recovery To Behavior This PR 2867renames the nav2_recoveries to nav2_behaviors. In navigation_launch.py recoveries_server -> behavior_server and nav2_recoveries -> nav2_behaviors. In nav2_params.yaml recovery_plugins -> behavior_plugins and nav2_recoveries -> nav2_behaviors.


key: chroma:document
string_value:
## Respawn Support in Launch and Lifecycle Manager PR 2752enables respawn support in Nav2. In the launch files, you may setuse_respawntotrueto enable respawning of servers that crash. This is only available in non-composed systems, since in composed systems, all of the nodes are under a single process and a crash anywhere will bring everything down (including the lifecycle manager itself). Even if the container was set to respawn, it would only respawn the empty container, not with all of the components loaded into it. That PR also enables the lifecycle manager to check if a system goes down due to a crash. If so, it allows the manager to check if the server comes back online within a given timeout period. If it does, it will automatically retransition the system back up to active to continue on its task automatically.


key: chroma:document
string_value:
## New Nav2 Velocity Smoother PR 2964introduces thenav2_velocity_smootherfor smoothing velocity commands from Nav2 to a robot controller by velocity, acceleration, and deadband constraints. SeeVelocity Smootherfor more details. It is not included in the default bringup batteries included fromnav2_bringup.

## Goal Checker API Changed PR 2965adds an extra argument in the initialize function of thenav2_core::GoalCheckerclass. The extra argument is a costmap_ros pointer. This is used to check if the goal is in collision, so that we can avoid moving towards the goal and replanning can be initiates using some BT plugin.

## Added Assisted Teleop PR 2904adds a new behavior for assisted teleop along with two new BT nodes AssistedTeleop and CancelAssistedTeleop.

Code Examples:


key: chroma:document
string_value:
Code Examples:

Language: unknown File: PoseStamped ``` def main (): rclpy . init () navigator = BasicNavigator () # Set our demo's initial pose initial_pose = PoseStamped () ... populate pose ... navigator . setInitialPose ( initial_pose ) # Wait for navigation to fully activate navigator . waitUntilNav2Active () # Go to our demos first goal pose goal_pose = PoseStamped () ... populate pose ... navigator . goToPose ( goal_pose ) while not navigator . isTaskComplete (): feedback = navigator . getFeedback () ... do something with feedback ... # Basic navigation timeout if Duration . from_msg ( feedback . navigation_time ) > Duration ( seconds = 600.0 ): navigator . cancelNav () result = navigator . getResult () if result == TaskResult . SUCCEEDED : print ( 'Goal succeeded!' ) elif result == TaskResult . CANCELED : print ( 'Goal was canceled!' ) elif result == TaskResult . FAILED : print ( 'Goal failed!' ) ```


key: chroma:document
string_value:
Language: unknown File: BtServiceNode ``` /** * @brief Function to perform some user-defined operation upon successful * completion of the service. Could put a value on the blackboard. * @param response can be used to get the result of the service call in the BT Node. * @return BT::NodeStatus Returns SUCCESS by default, user may override to return another value */ virtual BT :: NodeStatus on_completion ( std :: shared_ptr < typename ServiceT :: Response > /*response*/ ) { return BT :: NodeStatus :: SUCCESS ; } ```


key: chroma:document
string_value:
Title: ComputeCoveragePath

URL: https://docs.nav2.org/configuration/packages/bt

plugins/actions/ComputeCoveragePath.html

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Input Ports

## Output Ports

## Example Note: the blackboard IDs for the path, error code, and more may be adjusted,but need to match the corresponding parameters in theCoverageNavigatorplugin to set on the blackboard for use from the action server.

Code Examples:

Language: unknown

File: ComputeCoveragePath

```

<ComputeCoveragePath

file_field=

"{field_filepath}"

nav_path=

"{path}"

coverage_path=

"{cov_path}"

server_name=

"ComputeCoverage"

server_timeout=

"10"

error_code_id=

"{compute_coverage_error_code}"

/>

```


key: chroma:document
string_value:
Title: (SLAM) Navigating While Mapping URL: https://docs.nav2.org/tutorials/docs/navigation2_with_slam.html#launch-navigation2 Section: getting_started/index.html --------------------------------------------------------------------------------

## Overview This document explains how to use Nav2 with SLAM. The following steps show ROS 2 users how to generate occupancy grid maps and use Nav2 to move their robot around. This tutorial applies to both simulated and physical robots, but will be completed here on a physical robot. Before completing this tutorial, completing theGetting Startedis highly recommended especially if you are new to ROS and Navigation2. In this tutorial we’ll be using SLAM Toolbox. More information can be found in theROSCon talk for SLAM Toolbox

## Requirements You must install Navigation2, Turtlebot3, and SLAM Toolbox. If you don’t have them installed, please followGetting Started. SLAM Toolbox can be installed via: or from built from source in your workspace with:

## Tutorial Steps


key: chroma:document
string_value:
## Tutorial Steps

## 0- Launch Robot Interfaces For this tutorial, we will use the turtlebot3. The turtlebot3 software can be installed via the following or on theturtlebot3 repository: If you have another robot, replace with your robot specific interfaces. Typically, this includes the robot state publisher of the URDF, simulated or physical robot interfaces, controllers, safety nodes, and the like. Run the following commands first whenever you open a new terminal during this tutorial. Launch your robot’s interface and robot state publisher, for example:

## 1- Launch Navigation2 Launch Navigation without nav2_amcl and nav2_map_server. It is assumed that the SLAM node(s) will publish to /map topic and provide the map->odom transform.

## 2- Launch SLAM Bring up your choice of SLAM implementation. Make sure it provides the map->odom transform and /map topic. Run Rviz and add the topics you want to visualize such as /map, /tf, /laserscan etc. For this tutorial, we will useSLAM Toolbox.


key: chroma:document
string_value:
## 3- Working with SLAM Move your robot by requesting a goal through RViz or the ROS 2 CLI, ie: You should see the map update live! To save this map to file:

## 4- Getting Started Simplification If you’re only interested in running SLAM in the turtlebot3 getting started sandbox world, we also provide a simple way to enable SLAM as a launch configuration. Rather than individually launching the interfaces, navigation, and SLAM, you can continue to use thetb3_simulation_launch.pywithslamconfig set to true. We provide the instructions above with the assumption that you’d like to run SLAM on your own robot which would have separated simulation / robot interfaces and navigation launch files that are combined intb3_simulation_launch.pyfor the purposes of easy testing.

Code Examples:

Language: unknown

File: gitclone

b<ros2

distro>

develgit@github.com:stevemacenski/slam_toolbox.git

```

sudo

apt

install

ros

<ros2

distro>

turtlebot3

ros

<ros2

distro>

turtlebot3

msgs

ros

<ros2

distro>


key: chroma:document
string_value:
ros

<ros2

distro>

turtlebot3

msgs

ros

<ros2

distro>

turtlebot3

bringup

```

Language: unknown File: ros2launchslam_toolboxonline_async_launch.py ``` ros2 topic pub /goal_pose geometry_msgs/PoseStamped "{header: {stamp: {sec: 0}, frame_id: 'map'}, pose: {position: {x: 0.2, y: 0.0, z: 0.0}, orientation: {w: 1.0}}}" ```

Language: unknown

File: tb3_simulation_launch.py

```

ros2

launch

nav2_bringup

tb3_simulation_launch.py

slam:

=

True

```


key: chroma:document
string_value:
Title: Dev Container Guide

URL: https://docs.nav2.org/development_guides/devcontainer_docs/devcontainer_guide.html#creating

dev

containers

Section: getting_started/index.html

--------------------------------------------------------------------------------

## Creating Dev Containers Before creating a dev container, you’ll want to choose the exact configuration to use. By default the.devcontainer/devcontainer.jsonconfiguration is selected, however you can also choose any otherdevcontainer.jsonfile in the.devcontainer/directory, where such configurations can be nested to provide greater customization: either by targeting different stages within different Dockerfiles, overriding any merged metadata or default properties, or inclusion of additional extensions and alternate commands.


key: chroma:document
string_value:
## Building the image When first creating Dev Containers, any supporting tool or service used will download and build the docker images needed to run the container. This includes pulling any parent images the project’s Dockerfile buildsFROM, as well as any tags or layers declared viacacheFrom, as specified in the chosendevcontainer.jsonconfig file. This can take a while, but only needs to be done once, or at least not again until such layers are updated and pushed to the image registry. Specifically, for this project, the defaultdevcontainer.jsonfile targets thedeverstage within the project’s root Dockerfile, the stage that also includes handy tools for developing the project, such as bash auto completion. This stage is in turn builtFROMthebuilderstage, the stage that only includes the dependencies needed for building the project, as reused by the project’s CI. For example, thedeverstage modifies/etc/bash.bashrcto automatically sourceinstall/setup.bashfrom the underlay workspace, ensuring all VS Code


key: chroma:document
string_value:
the underlay workspace, ensuring all VS Code extensions are loaded with the correct environment, while avoiding any race conditions during installation and startup. To speed up the initial build, images layers from thisbuilderstage are cached by pulling the same image tag used by the project’s CI, hosted from the image registry. This ensures your local dev container replicates our CI environment as close as possible, while benefiting from any cached work preemptively performed by the CI. Yet, this still allows you to customize the project’s Dockerfile and rebuild the container, without needing to update CI images to reflect your local modifications. Once the base image from the target stage is built, the supporting tool or service may then add additional layers to the image, such as installing additionalfeaturesor customizations. For VS Code, this also includes some fancy file caching for any extensions to install later. Once this custom image is built, it is then used to start the dev container.


key: chroma:document
string_value:
## Starting the container When first creating Dev Containers, any supporting tool or service will invoke a sequence of commands specified in the chosendevcontainer.jsonconfig file. This can take a while, but only needs to be done once, or at least not again until the container is rebuilt, triggered by either updating the Dockerfile, base image, or.devcontainer/config. Specifically, for this project, the defaultdevcontainer.jsonconfig executes theonCreateCommandto initially colcon cache, clean, and build the overlay workspace for the project. This ensures the workspace is precompiled and ready to use, while also ensuring any changes to the project’s source code are reflected in the container. This is useful for: While the colcon workspace is being built, VS Code will simultaneously install any specified extensions and settings. Next theupdateContentCommandis executed, which reruns whenever the container is started or restarted. Specifically, for this project, this command re-cleans and re-builds the same


