📔 Navigation Configuration Guide

Section

🧭 Navigation - high-level documentation

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 Pipelines

The concept of Pipelines in the PAL Robotics Navigation Stack for ROS 2 provides a streamlined approach to managing and launching multiple ROS 2 nodes related to robot navigation. Pipelines allow users to group related ROS 2 nodes, which can be launched or stopped as a single unit. This modularity helps in organizing the navigation stack, making easier to manage different functionalities.

A Pipeline could have the following structure:

nodes:
   waypoint_follower:
      app: waypoint_follower
      params: [wait_at_waypoint]
   lifecycle_manager_navigation:
      app: lifecycle_manager
      params: [default]

containers:
   navigation_container:
      bt_navigator:
         app: bt_navigator
         params: [navigate_w_replanning_and_recovery]
      controller_server:
         app: controller_server
         params: [dwb_w_progress_checker_and_goal_checker, local_costmap]

Where the basic unit of a Pipeline is represented by the Navigation Application, each Navigation Application has the fields:

• app that is the name of the Navigation Application.

• params that is the list of Navigation Configuration File that will be used to configure the Navigation Application at startup.

Attention

Note that each Navigation Application has its own name that represents the name you want to give to the ROS 2 node. For example, in the code below

wp_node:
    app: waypoint_follower
    params: [wait_at_waypoint]

wp_node is the name of the ROS 2 Node and waypoint_follower is the name of the Navigation Application

Each Navigation application can be started as plain ROS 2 Node or as ROS 2 Component, if available for that specific , if available for that specific Navigation Application. In the Navigation Pipeline you can decide to start Navigation Applications by grouping them under the fields:

• nodes is the list of Navigation Applications that will be started as plain ROS 2 Nodes.

• containers is the list of of ROS 2 Containers that will load a list of Navigation Applications as ROS 2 Components sharing the same process.

The Available Pipelines in PAL Robotics Navigation Stack for ROS 2 are:

• Navigation Pipeline: It starts Nav2 Navigation related ROS 2 nodes, it is defined into a .yaml file named <robot>_nav.yaml.

• Localization Pipeline: It starts Nav2 Localization related ROS 2 nodes, it is defined into a .yaml file named <robot>_loc.yaml.

• SLAM Pipeline: It starts SLAM Toolbox and Nav2 related ROS 2 nodes, it is defined into a .yaml file named <robot>_slam.yaml.

Note

Navigation and Localization Pipelines are available also with composable nodes, in this case the .yaml file will have the following structure: <robot>_nav_w_composition.yaml

To list all the available Pipelines in PAL Robotics Navigation Stack, you can use the command:

ls /opt/pal/$PAL_DISTRO/share/<robot>_2dnav/params/

Attention

Make sure to replace the <robot> placeholder with the name of your robot (e.g. tiago, omni_base, tiago_pro, etc.).

Attention

When using a TIAGo family robot the naming convention for the YAML configuration files that define Navigation and Localization Pipelines includes the <base_type> of the robot. Therefore the .yaml file will have the following structure: <robot>_<base_type>_nav.yaml

Other available pipelines are:

• Laser Pipeline: It starts laser related ROS 2 nodes, it is defined into a .yaml file named <robot>_laser.yaml.

• RGBD Pipeline: It starts RGBD related ROS 2 nodes, it is defined into a .yaml file named <robot>_rgbd.yaml.

To list the Sensors pipeline you can use the command:

ls /opt/pal/$PAL_DISTRO/share/<base_type>_<sensor_type>_sensors/params/

Attention

Make sure to replace the <sensor_type> placeholder with your sensor type (e.g. laser or rgbd).

By default the PAL Robotics robots start Laser, Navigation and Localization Pipelines.

API

The Navigation Pipelines can be managed using the PAL Robotics Module Manager, to list all the available Navigation pipelines you can use the command:

pal module list

To start a Pipeline (e.g. SLAM) you can use the command:

pal module start slam

To stop a Pipeline you can use the command:

pal module stop slam

Otherwise you can restart the Pipeline by using the command:

pal module restart slam

To check the logs of the Nodes used into the Pipeline you can use the command:

pal module log slam cat

Navigation Configuration File

PAL Robots already come with some pre-configured and tested configurations that are customized for different environments and for different robots. To list all the Folders containing the available configuration for Nav2 nodes you can use the command:

ls /opt/pal/$PAL_DISTRO/share/pal_navigation_cfg_params/params/

How to change default configuration

To change the default configuration used by a Navigation application into Pipeline you can follow these steps. Stop the navigation pipeline with:

pal module stop navigation

For example, you want to change the controller_server configuration by changing the default controller used by the robot, to another type. You can list all the available configuration for the controller_server by doing:

ls /opt/pal/$PAL_DISTRO/share/pal_navigation_cfg_params/params/nav2_controller/

Once you chose the configuration you want to use (e.g. rpp_shim), you need to set it in the Navigation Pipeline by modifying the <robot>_nav.yaml file in the <robot>_2dnav package.

sudo vi /opt/pal/$PAL_DISTRO/share/<robot>_2dnav/params/<robot>_nav.yaml

Then, change the params field of the controller_server to the name of the configuration file you want to use.

nodes:
   # Other nodes
   controller_server:
      app: controller_server
      params: [rpp_shim, local_costmap_w_filters]

Finally, to apply the changes and start using another Controller Server configuration you need to restart the Navigation Pipeline with the command:

pal module restart navigation

How to create and use a custom configuration

Otherwise if you want to create a custom configuration for the controller_server, you first need to create a new directory in the .pal folder of your robot.

mkdir -p ~/.pal/pal_navigation_cfg_params/params/nav2_controller_server

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

touch ~/.pal/pal_navigation_cfg_params/params/nav2_controller_server/my_controller.yaml

Then modify the newly created configuration file with the command:

vi ~/.pal/pal_navigation_cfg_params/params/nav2_controller_server/my_controller.yaml

In this file you can set the parameters you want to use for the controller:

pal_navigation_cfg:
  ros__parameters:
    supported_robots:
    - some_pal_robot # e.g. tiago, omni_base, tiago_pro, etc.

__node_name__:
   ros__parameters:
      use_sim_time: ${use_sim_time}
      controller_frequency: 20.0
      odom_topic: ${odom_topic}
      # Other parameters

As you can see in the example above, to make your configuration file compatible with all the PAL Robotics robots you have to set the supported_robots parameter with the name of the robot you want to use the configuration with. Then you can add the parameters you want to set for the controller;

Attention

Note that by using __node_name__ , automatically, the name of the ROS 2 node you gave into the Navigation Pipeline will match the name of the ROS 2 node you want to configure.

As you can see from the example, some parameters are set using the ${} syntax, these are YAML variables that can be used to change very robot-specific parameters ( e.g. robot_radius) You can check all the given value of of these YAML variables by doing:

cat /opt/pal/$PAL_DISTRO/share/<robot>_2dnav/params/<robot>_remappings.yaml

Once created, to start using your custom Controller configuration, you need to set it in the navigation pipeline by modifying the <robot>_nav.yaml file in the <robot>_2dnav package.

sudo vi /opt/pal/$PAL_DISTRO/share/<robot>_2dnav/params/<robot>_nav.yaml

Then, change the params field of the controller_server to the name of your custom Controller Server configurationfile.

nodes:
   # Other nodes
   controller_server:
     app: controller_server
     params: [my_controller, local_costmap_w_filters]

Attention

Make sure that the name of the custom contoller configuration file you use in the params field (my_controller) is the same as the name of the file you created in the .pal folder (my_controller.yaml).

Finally, to apply the changes and start using the new controller configuration, you need to restart the navigation pipeline with the command:

pal module restart navigation