In the ROS 2 navigation framework Nav2, bringup_launch.py is the core file that connects hardware, maps, and navigation algorithms. This article, based on official source code and community documentation, analyzes advanced configuration techniques such as namespace isolation, dynamic composition, and conditional launching, applicable to multi-robot systems or resource-constrained embedded deployments.

1. Overview of Bringup File Structure

bringup_launch.py is divided into three parts: parameter declarations, conditional launch decisions, and action group definitions.

1.1 Parameter Declarations

The file declares the following parameters at the beginning (default values vary by version, here only explaining their functions):

python namespace = LaunchConfiguration('namespace') use_namespace = LaunchConfiguration('use_namespace') slam = LaunchConfiguration('slam') map_yaml_file = LaunchConfiguration('map') use_sim_time = LaunchConfiguration('use_sim_time') params_file = LaunchConfiguration('params_file') autostart = LaunchConfiguration('autostart') use_composition = LaunchConfiguration('use_composition') use_respawn = LaunchConfiguration('use_respawn') log_level = LaunchConfiguration('log_level') use_localization = LaunchConfiguration('use_localization')

1.2 Conditional Launch

IfCondition and PythonExpression are used to decide whether to launch sub-launch files:

• slam_launch.py: Launched when both slam and use_localization are true, used for SLAM mapping.
• localization_launch.py: Launched when slam is false and use_localization is true, used for AMCL localization.
• navigation_launch.py: Launched unconditionally, responsible for lifecycle management of all navigation nodes.

2. Namespace: The Foundation of Isolation in Multi-Robot Systems

ROS 2 namespaces prevent topic and node name conflicts between different robots. Through the namespace and use_namespace parameters, all launched nodes and relative topic names can be placed into a specified namespace.

2.1 Global Topic Remapping

Remappings defined at the beginning of the file​:

python remappings = [('/tf', 'tf'), ('/tf_static', 'tf_static')]

These convert global topics /tf and /tf_static to relative topics tf and tf_static. Relative topics inherit the namespace of the node they belong to, so in multi-robot scenarios, each robot's TF data will not conflict with one another.

2.2 Namespace Adaptation in Parameter Files

When a namespace is enabled, the parameter file needs to undergo two processing steps:

1. ReplaceString: Replace the placeholder <robot_namespace> in the parameter file with the actual namespace value.
2. RewrittenYaml: Rewrite the processed YAML file with the namespace as the root key. For example, the default structure:

yaml controller_manager: ros__parameters: update_rate: 100

After processing (with namespace robot1), it becomes:

yaml robot1: controller_manager: ros__parameters: update_rate: 100

This way, when nodes load parameters, they automatically look up the correct namespaced path.

2.3 PushRosNamespace and GroupAction

In action groups, PushRosNamespace is used to set the namespace for a group of nodes:

python bringup_cmd_group = GroupAction([ PushRosNamespace( condition=IfCondition(use_namespace), namespace=namespace), # ... other nodes and launch descriptions ])

GroupAction combines multiple actions together, and PushRosNamespace pushes the specified namespace onto the current context. Its scope is limited to that group action. When the group action ends, the namespace is automatically popped.

3. Composition: Inter-Process Communication Optimization

Composition runs multiple nodes within the same process, reducing inter-process communication overhead, making it suitable for resource-constrained embedded systems.

3.1 Composition Container

When use_composition is True, a composition container node named nav2_container is launched:

python Node( condition=IfCondition(use_composition), name='nav2_container', package='rclcpp_components', executable='component_container_isolated', parameters=[configured_params, {'autostart': autostart}], arguments=['--ros-args', '--log-level', log_level], remappings=remappings, output='screen', )

This container loads all Nav2 components (such as controller_server, planner_server, etc.), and components communicate via shared memory within the same process.

3.2 Trade-offs Between Composition and Independent Launch

Dynamic composition is enabled by default and can be disabled via the command-line parameter use_composition:=False. When disabled, each node starts as an independent process, which facilitates debugging and version compatibility.

Known Issue: When building Nav2 from source using the clang compiler and enabling composition, you may encounter MultiLibraryClassLoader errors, causing StaticLayer to fail to instantiate (Issue #5025). In this case, setting use_composition:=False can work around the issue.

4. Conditional Launch: Flexible Switching Between Mapping and Localization

Through the slam and use_localization parameters, you can select functionality at runtime:

• Launch slam_launch.py: Condition is slam and use_localization, used for online mapping.
• Launch localization_launch.py: Condition is not slam and use_localization, used for localization when a map already exists.
• Launch navigation_launch.py: Launched unconditionally, always running navigation nodes.

Example commands:

bash

Known map environment

ros2 launch nav2_bringup bringup_launch.py
slam:=false
use_localization:=true
map:=/path/to/map.yaml

Unknown environment mapping

ros2 launch nav2_bringup bringup_launch.py
slam:=true
use_localization:=true

5. Parameter File Processing: Namespace Adaptation Details

When a namespace is enabled, the parameter file needs to undergo two processing steps:

1. String Replacement: Use ReplaceString to replace <robot_namespace> with the actual namespace.
2. YAML Rewriting: Use RewrittenYaml to set the root key to the namespace, ensuring parameter isolation.

6. Known Issues and Considerations

6.1 Conflict Between Clang Compiler and Composition Mode

According to Issue #5025, when building with clang and enabling composition, initialization failures may occur:

MultiLibraryClassLoader: Could not create object of class type nav2_costmap_2d::StaticLayer as no factory exists for it.

Solution: Temporarily set use_composition to False, or wait for the official fix.

6.2 TF Remapping Limitations in Multi-Robot Simulation

The official README notes that directly remapping /tf and /tf_static in the launch file is ineffective for the spawn_entity node. The correct approach is to set individual remappings for each plugin in the SDF file​:

xml <remapping>/tf:=tf</remapping> <remapping>/tf_static:=tf_static</remapping>

Otherwise, TF data from different robots may become confused.

7. Practical Recommendations and Next Steps

• Beginners: Use the default configuration to start, try different parameter combinations, and observe the effects of namespaces and composition modes.
• Multi-robot developers: Enable use_namespace, use tools like cloned_multi_tb3_simulation_launch.py for simulation testing.
• Embedded users: Enable composition mode to optimize performance when resources allow; if compilation or runtime errors occur, try disabling composition or switching compilers.

Through this article, you should be able to confidently configure and debug the Nav2 launch system. Next steps include reading the Getting Started page in the official Nav2 documentation, or delving deeper into the source code of individual sub-launch files.