ROS 2 Launch Argument

A ROS 2 Launch Argument is a named variable declared within a launch file (Python or XML) whose value can be supplied externally—typically via the command line—to customize the configuration of a robotic application at launch time. Its primary purpose is to create reusable, configurable launch files that avoid hard-coded values, allowing the same file to start systems with different parameters, node configurations, or even different sets of nodes based on conditional logic. This is essential for managing variations across development, simulation, and multiple physical robot deployments.

Arguments are declared in a launch file using specific functions from the launch API. In Python launch files, the DeclareLaunchArgument action is used. Each declaration includes:

• Name: A string identifier for the argument (e.g., 'use_sim_time').
• Default Value: The value used if the argument is not provided externally (e.g., default_value='false').
• Description: An optional human-readable explanation.

Example in Python:

pythonCopy
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration

launch_arguments = []
launch_arguments.append(DeclareLaunchArgument(
    'robot_model',
    default_value='turtlebot3_burger',
    description='Which robot model to configure.'
))

The argument's value is then accessed elsewhere in the launch file via a LaunchConfiguration substitution.

The power of launch arguments is realized through substitutions. The LaunchConfiguration('arg_name') object acts as a placeholder that is resolved to the argument's actual value at execution. These substitutions can be used to dynamically set:

• Node Parameters: Passing the argument's value to a node's parameter list.
• Conditional Logic: Using the argument's value in IfCondition or UnlessCondition to include or exclude launch actions.
• File Paths: Constructing paths to configuration files or URDF models.
• Remapping Rules: Dynamically remapping topic or service names.

Example of passing an argument to a node parameter:

pythonCopy
Node(
    package='my_pkg',
    executable='my_node',
    parameters=[{'model_name': LaunchConfiguration('robot_model')}]
)

The defining feature of launch arguments is their ability to be overridden from the command line when invoking the launch file using ros2 launch. The command-line syntax is arg_name:=value. This creates a clear hierarchy of configuration precedence:

1. Command-Line Value: Highest priority. Directly overrides any default.
2. Default Value in Launch File: Used if no command-line value is provided.

Example command:

bashCopy
ros2 launch my_robot launch_file.py robot_model:=turtlebot3_waffle use_sim_time:=true

This command starts the system configured for a Waffle model with simulation time enabled, regardless of the defaults in the launch file. This mechanism is critical for rapid testing, A/B comparisons, and deployment scripting.

Launch arguments enable conditional execution of launch actions, allowing a single launch file to describe multiple system configurations. This is achieved using IfCondition and UnlessCondition actions, which evaluate a Boolean expression based on the argument's value.

Common use cases include:

• Simulation vs. Real Robot: An argument like use_simulator determines whether to spawn a robot in Gazebo or connect to real hardware drivers.
• Sensor Selection: An argument like lidar_type chooses which driver node and corresponding parameters to launch.
• Debug Mode: An argument like debug controls whether to launch nodes with additional logging or visualizers.

Example:

pythonCopy
from launch.conditions import IfCondition

launch_description = LaunchDescription([
    Node(
        condition=IfCondition(LaunchConfiguration('use_gazebo')),
        package='gazebo_ros',
        executable='spawn_entity.py',
        arguments=['-topic', 'robot_description']
    )
])

It is crucial to distinguish Launch Arguments from ROS Parameters, as they operate at different system layers:

• Launch Argument: A build-time/startup-time construct for the launch system itself. It configures which nodes are launched, with what initial settings, and under which conditions. Its scope is the launch file execution.
• ROS Parameter: A runtime configuration mechanism managed by a node's parameter server. Nodes can get, set, and be dynamically reconfigured via parameters during their lifecycle.

A typical pattern is to use a launch argument to set the initial value of one or more ROS parameters. For example, a robot_speed_limit launch argument is used to populate a node's max_velocity parameter at startup. After launch, that parameter can still be changed via ros2 param set, independent of the original launch argument.

Use launch arguments to abstract hardware differences, enabling a single launch file to work across multiple robot models or sensor suites.

• Robot Model Selection: Pass the robot's name (e.g., robot_model:=turtlebot3_burger) to load the correct URDF, controller configurations, and namespace.
• Sensor Toggle: Use boolean arguments like use_lidar:=true or use_camera:=false to conditionally launch sensor driver nodes.
• Device Paths: Set arguments for serial ports or network addresses (e.g., lidar_port:=/dev/ttyUSB0).

This pattern is essential for maintaining a unified codebase across heterogeneous fleets.

Arguments control whether the system launches in simulation, on physical hardware, or for specific testing environments.

• Use Simulation: The canonical argument use_sim_time:=true directs all nodes to use simulated time published on the /clock topic.
• World Selection: In Gazebo or Ignition, use world:=warehouse to load a specific simulated environment file.
• Headless Mode: Set gui:=false to launch a physics simulation without a visual client for automated testing.

This allows seamless context switching between development, testing, and deployment.

Expose critical performance knobs as launch arguments to optimize system behavior without code changes.

• Quality of Service (QoS) Profiles: Set arguments like qos_reliability:=reliable for critical control topics or qos_reliability:=best_effort for high-frequency sensor data.
• Executor Configuration: Control thread pools with arguments like single_threaded_executor:=true for deterministic callback ordering.
• Buffer Sizes: Configure internal queue depths for publishers and subscribers (e.g., queue_size:=10).

This provides operational flexibility to balance latency, reliability, and resource usage.

Launch arguments are fundamental for instantiating multiple instances of the same robot system in a single ROS graph, preventing topic and parameter collisions.

• Robot Namespace: The argument robot_namespace:=/robot1 prefixes all node names, topics, and services for that robot instance.
• Fleet Launch: A master launch file can call include actions in a loop, passing a unique robot_id argument to each included launch description.
• TF Prefix: Use an argument to set the tf_prefix for a robot's transform frames, ensuring correct coordinate frame isolation.

This pattern is the backbone of scalable multi-robot application deployment.

Arguments drive the conditional execution of launch actions, enabling complex, branching launch descriptions.

• If/Unless Conditions: Use IfCondition and UnlessCondition to include or exclude entire node groups, e.g., launching a mapping stack only if mode:=mapping.
• Choose/When Conditions: Implement switch-case logic with GroupAction containing PushRosNamespace and node declarations triggered by specific argument values.
• Composition: Arguments can determine whether nodes are launched as standalone processes or loaded as components into a shared container for lower latency and memory footprint.

This creates intelligent, context-aware startup sequences.

Launch arguments serve as the clean interface between ROS 2 launch files and external deployment, orchestration, and CI/CD systems.

• CI/CD Pipelines: Jenkins or GitLab CI jobs pass arguments like test_mode:=true and bag_file:=test.bag to launch integration tests.
• Orchestrators: Kubernetes deployments or Ansible playbooks set environment-specific arguments (e.g., map_yaml:=/maps/warehouse_v2.yaml).
• Command-Line Wrappers: Shell scripts or Python tools provide a simplified user interface that internally calls ros2 launch with a curated set of argument values.

This establishes launch files as the definitive, parameterized entry point for the robotic software system.

A ROS 2 Launch File is an XML or Python script that defines a collection of nodes, parameters, and other launch actions to be executed. It is the primary mechanism for starting a complete robotic application. Launch arguments are defined within this file to make its configuration dynamic.

• Python Launch API: The modern, programmatic way to write launch files, offering greater flexibility and logic than XML.
• Launch Actions: Include actions like Node, SetParameter, IncludeLaunchDescription, and ExecuteProcess that the launch file orchestrates.

A ROS 2 Parameter is a configuration variable stored on a node's parameter server, accessible at runtime via services. Launch arguments are often used to set the initial values of these parameters when a node starts.

• Dynamic Reconfiguration: Unlike static launch arguments, parameters can be get, set, and monitored (ParameterEvent) while the system is running.
• Types: Parameters support primitive types (integer, double, string, boolean) and arrays.
• Link: Launch arguments feed into the parameters argument of a Node action, populating the node's initial parameter state.

A ROS 2 Node is a fundamental executable process that performs computation. The primary purpose of a launch file is to start and configure one or more nodes. Launch arguments parameterize this startup process.

• Namespace and Remapping: Launch files use arguments to set a node's namespace or remap its topic/service names, altering its position in the ROS graph.
• Conditional Launch: Arguments can be used in conditional logic (IfCondition, UnlessCondition) to decide whether or not to launch specific nodes.

A Substitution in ROS 2 launch is a Python object that evaluates to a string at launch time. They are the mechanism by which launch argument values are injected into launch descriptions.

• Common Substitutions:
  • LaunchConfiguration: Fetches the value of a launch argument.
  • PythonExpression: Evaluates a Python expression, often using argument values.
  • EnvironmentVariable: Gets the value of an OS environment variable.
• Evaluation: Substitutions are lazily evaluated, allowing the final command-line or parameter values to be resolved only when the launch action is executed.

The ROS 2 Launch Command-Line Interface is the tool (ros2 launch) used to execute launch files. This is where launch argument values are typically provided from the terminal.

• Syntax: ros2 launch <package_name> <launch_file.py> argument_name:=value
• Passing Lists: Use Python list syntax: my_list:=["item1", "item2"]
• Default Values: If an argument is not provided on the CLI, its default value (from the launch file) is used.

A ROS 2 Component is a node packaged as a shared library. A Component Container is a process that dynamically loads and manages these components. Launch arguments are crucial for configuring both.

• Composable Node Launching: The ComposableNodeContainer and ComposableNode launch actions allow for building a process from components, where arguments can specify the component's plugin name and initial parameters.
• Performance: This model reduces inter-process communication overhead compared to launching many separate node executables.