📔 Navigation Configuration Guide¶

The “Navigation Configuration Guide” serves as a comprehensive resource for configuring and managing the PAL Robotics Navigation Stack within ROS 2. This guide is designed to help users navigate the complexities of setting up and customizing navigation pipelines for different robotic platforms.

Navigation Modules¶

Every Navigation-related functionality in the PAL Robotics Navigation Stack is started, managed and stopped using the PAL Robotics Module Manager. This module manager provides a unified interface to control various navigation modules, which are essentially pipelines of ROS 2 nodes that work together to provide navigation capabilities. For more information about the PAL Robotics Module Manager, you can refer to the The startup process of the robot and application management documentation.

Here is a list of the Navigation-related modules, along with their description:

Module	Description
`laser`	If your robot is equipped with a LiDAR sensor, this module provides the necessary nodes to handle the laser-related functionalities, such as ROS Driver, filters, laser odometry, and so on.
`rgbd`	If your robot is equipped with an RGB-D camera, this module provides the necessary nodes to handle the RGB-D related functionalities, such as ROS Driver, filters, and so on.
`navigation`	This module provides the necessary nodes to handle the autonomous navigation functionalities, such as path planning, motion planning, decision-making, and so on. See 🥅 Goal Navigation.
`localization`	This module provides the necessary nodes to handle the localization functionalities, such as AMCL, map server, and so on. See 📍 Localization.
`slam`	This module provides the necessary nodes to handle the SLAM functionalities, such as SLAM algorithms, map saver, and so on. See 🗺️ Mapping.
`assisted_teleop`	This module provides the necessary nodes to handle the assisted teleoperation functionalities, see 🕹️ Assisted Teleop.
`docking`	This module provides the necessary nodes to handle the docking functionalities, such as docking station detection, docking action server, and undocking. See 🔋 Docking.
`advanced_navigation`	This module provides the necessary nodes to handle the advanced navigation functionalities, such as target detection, target navigation, environmental annotations, and so on. See 🎯 Target Navigation, 🚩 Waypoint Navigation, 🏛️ Environmental Annotations,

Navigation Configuration¶

Navigation-reated nodes are listed in the Nodes related to section_navigation. They already come with some pre-configured and tested configurations that are maintained and supported by PAL Robotics.

The user can list and investigate the available configurations for each node, with the pal configuration command

~$ pal configuration --help
usage: pal configuration [-h] {list,get,get_preset,info,info_preset} ...

Manage the installed PAL Configurations

positional arguments:
{list,get,get_preset,info,info_preset}
                        Verb to execute
   list                List the available configurations for each node
   get                 Get the content of a Node configuration
   get_preset          Get the content of a preset configuration
   info                Get information about a Node configuration
   info_preset         Get information about a Preset configuration

options:
-h, --help            show this help message and exit

Using this CLI, you can list all the available configurations for each node:

~$ pal configuration list
------------------------------------------------------------------------------------------------------------------------
| Package                  | Nodes                                 | Presets                                           |
------------------------------------------------------------------------------------------------------------------------
| astra_camera_cfg         | astra_camera_driver                   |                                                   |
|                          | point_cloud_xyz                       |                                                   |
|                          | point_cloud_xyzrgb                    |                                                   |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
| communication_hub        | communication_hub                     |                                                   |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
| dlo_ros                  | direct_laser_odometry                 |                                                   |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
| eulero_manager           | eulero_manager                        |                                                   |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
| hokuyo_laser_cfg         |                                       | hokuyo_driver.yaml                                |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
| i18n_manager             | i18n_manager                          |                                                   |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
| ira_laser_tools          | laserscan_multi_merger                |                                                   |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
| nav2_amcl                | amcl                                  | amcl_diff.yaml                                    |
|                          |                                       | amcl_diff_w_bad_odom.yaml                         |
|                          |                                       | amcl_omni.yaml                                    |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
| nav2_behaviors           | behavior_server                       | navigate_to_waypoint_and_zone.yaml                |
|                          | global_behavior_server                | spin_backup_wait.yaml                             |
|                          |                                       | spin_backup_wait_param_config.yaml                |
|                          |                                       | spin_backup_wait_param_config_limited.yaml        |
| ------------------------ | ------------------------------------- | ------------------------------------------------- |
...

Similarly, you can get the current configuration passed to a node:

~$ pal configuration get amcl
Node Name:  amcl
Package Name:  nav2_amcl
ROS Parameters:
   alpha1:  0.05
   alpha2:  0.2
   alpha3:  0.2
   alpha4:  0.05
   ...
Remappings:
   /tf:  tf
   /tf_static:  tf_static
Arguments:
[]

Customize Navigation Configurations¶

In addition to the available PAL configurations for the Nodes related to section_navigation, you can create new configurations for your robot. To do so, you first need to create a new directory in the .pal folder of your robot.

mkdir -p ~/.pal/config

And then, within this folder, you can create a new node configuration file.

touch ~/.pal/config/99_my_node_config.yaml

Attention

The name of the file should start with a number to ensure that it is loaded last and overrides the default PAL configurations.

Tip

The name of the file should start with a number between 90 and 99. These are reserved for user-defined configurations. The number will determine the order in which the configuration files are loaded.

Within the newly created 99_my_node_config.yaml file, you can insert your custom node parameters. For the list of available parameters, their meaning and how they affect the Node, you can refer to the corresponding section of this documentation.

Tip

To retrieve the list of available nodes, along with their package names and default parameters, you can use the pal configuration list command. This will help you identify the node you want to configure and the parameters you can modify.

When creating a new Navigation configuration file, you need to specify the node name it refers to. For example, if you are configuring the amcl node:

/amcl:
   ros__parameters:
      # Your amcl parameters

Once created, to start using your custom amcl configuration, you need to restart the corresponding Navigation Modules. In the case of the amcl node, you need to restart the localization module with the command:

pal module restart localization

Note

This change is is persistent and will be loaded every time you start the localization module. If you want to revert to the default PAL configuration, you can simply delete the custom configuration file you created in the ~/.pal/config folder.

Troubleshooting¶

Given that the parameters in your custom configuration file override the default PAL Robotics ones, you might want to investigate the default parameters and confirm that the system is using the ones you set.

To do so, you can use the pal configuration CLI

~$ pal configuration info amcl
Node Name:  amcl
Package Name:  nav2_amcl
File paths:
- /home/user/.pal/config/99_my_node_config.yaml
- /opt/pal/alum/share/pal_navigation_cfg/params/nav2_amcl/00_default.yaml

This indicates the directory where the default amcl node paarmeters are stored and also indicates that your cutom parameter file 99_my_node_config.yaml is being used to ovverride the default parameters.

Note

The order in which the file paths are listed is representative of their priority. In the example above, the /home/user/.pal/config/99_my_node_config.yaml is on top of the list and is ovverriding parameters in the /opt/pal/alum/share/pal_navigation_cfg/params/nav2_amcl/00_default.yaml

Attention

The /home/user/.pal/config/99_my_node_config.yaml will override ONLY the values of the paremeters that are declared in the base file /opt/pal/alum/share/pal_navigation_cfg/params/nav2_amcl/00_default.yaml. For example:

00_default.yaml

/my_node:
  ros__parameters:
    param_a: 1.0
    param_b: "Hi"

99_my_node_config.yaml

/my_node:
  ros__parameters:
    param_a: 2.0
    param_c: true

The resulting dictionary of parameters that will be send to the node is:

/my_node:
  ros__parameters:
    param_a: 2.0
    param_b: "Hi"
    param_c: true