Topic namespaces#

Overview#

ROS allows topics, parameters and nodes to be namespaced which provides the following benefits:

Multiple instances of the same node type will not cause naming clashes.
Topics published by a node can be automatically namespaced with the node's namespace providing a meaningful and easily-visible connection.
Keeps from cluttering the root namespace.
Helps to maintain separation-of-concerns.

This page focuses on how to use namespaces in Autoware and shows some useful examples. For basic information on topic namespaces, refer to this tutorial.

How topics should be named in node#

Autoware divides the node into the following functional categories, and adds the start namespace for the nodes according to the categories.

localization
perception
planning
control
sensing
vehicle
map
system

When a node is run in a namespace, all topics which that node publishes are given that same namespace. All nodes in the Autoware stack must support namespaces by avoiding practices such as publishing topics in the global namespace.

In general, topics should be namespaced based on the function of the node which produces them and not the node (or nodes) which consume them.

Classify topics as input or output topics based on they are subscribed or published by the node. In the node, input topic is named input/topic_name and output topic is named output/topic_name.

Configure the topic in the node's launch file. Take the joy_controller node as an example, in the following example, set the input and output topics and remap topics in the joy_controller.launch.xml file.

<launch>
  <arg name="input_joy" default="/joy"/>
  <arg name="input_odometry" default="/localization/kinematic_state"/>

  <arg name="output_control_command" default="/external/$(var external_cmd_source)/joy/control_cmd"/>
  <arg name="output_external_control_command" default="/api/external/set/command/$(var external_cmd_source)/control"/>
  <arg name="output_shift" default="/api/external/set/command/$(var external_cmd_source)/shift"/>
  <arg name="output_turn_signal" default="/api/external/set/command/$(var external_cmd_source)/turn_signal"/>
  <arg name="output_heartbeat" default="/api/external/set/command/$(var external_cmd_source)/heartbeat"/>
  <arg name="output_gate_mode" default="/control/gate_mode_cmd"/>
  <arg name="output_vehicle_engage" default="/vehicle/engage"/>

  <node pkg="joy_controller" exec="joy_controller" name="joy_controller" output="screen">
    <remap from="input/joy" to="$(var input_joy)"/>
    <remap from="input/odometry" to="$(var input_odometry)"/>

    <remap from="output/control_command" to="$(var output_control_command)"/>
    <remap from="output/external_control_command" to="$(var output_external_control_command)"/>
    <remap from="output/shift" to="$(var output_shift)"/>
    <remap from="output/turn_signal" to="$(var output_turn_signal)"/>
    <remap from="output/gate_mode" to="$(var output_gate_mode)"/>
    <remap from="output/heartbeat" to="$(var output_heartbeat)"/>
    <remap from="output/vehicle_engage" to="$(var output_vehicle_engage)"/>
  </node>
</launch>

Topic names in the code#

Have ~ so that namespace in launch configuration is applied(should not start from root /).
Have ~/input ~/output namespace before topic name used to communicate with other nodes.

e.g., In node obstacle_avoidance_planner, using topic names of type ~/input/topic_name to subscribe to topics.
```
objects_sub_ = create_subscription<PredictedObjects>(
 "~/input/objects", rclcpp::QoS{10},
 std::bind(&ObstacleAvoidancePlanner::onObjects, this, std::placeholders::_1));
```
e.g., In node obstacle_avoidance_planner, using topic names of type ~/output/topic_name to publish topic.
```
traj_pub_ = create_publisher<Trajectory>("~/output/path", 1);
```
Visualization or debug purpose topics should have ~/debug/ namespace.

e.g., In node obstacle_avoidance_planner, in order to debug or visualizing topics, using topic names of type ~/debug/topic_name to publish information.
```
debug_markers_pub_ =
 create_publisher<visualization_msgs::msg::MarkerArray>("~/debug/marker", durable_qos);

debug_msg_pub_ =
 create_publisher<tier4_debug_msgs::msg::StringStamped>("~/debug/calculation_time", 1);
```
The launch configured namespace will be add the topics before, so the topic names will be as following:

/planning/scenario_planning/lane_driving/motion_planning/obstacle_avoidance_planner/debug/marker /planning/scenario_planning/lane_driving/motion_planning/obstacle_avoidance_planner/debug/calculation_time
Rationale: we want to make topic names remapped and configurable from launch files.