Proposal for providing a stable interface

[isamu-takagi]

Overview

With current Autoware, when a ROS message type changes, all packages that depend on that message must be updated. However, when the interface changes due to implementation reasons, it is inconvenient for the old interface to suddenly become unusable, so it is desirable to provide a transition period.

Also, since you don't know which interfaces are exposed, external components may use implementation-dependent private topics or services. Therefore, we need a way to distinguish between topics and services that are available externally.

Goals

• Provide a transition period for interfaces.
• Clarify exposed interfaces.

Approach

Use REP-2007 Type Adaptation Feature to define the conversion between custom type and ROS message type, and use the custom type as an interface. This custom type does not change once it is released. This allows you to update the conversion function and maintain the interface even if you change the message.

Of course, you can also use ROS message type directly as before. The advantage of using custom type for interface is that you do not need to modify your code even if the ROS message type changes.

Packages

As shown in the figure below, create a package that defines the interface, and add the interface type and type adapter to it. The parts that need to be updated when the ROS message type is changed are shown in red.

Versioning

After the transition period expires, the old interface type will be removed. An example is shown below. The color of the bar in the diagram indicates that the message has changed. The length of the transition period is not determined here. The message maintainer will decide based on the situation.

Implementation

The sample code is here.

• https://github.com/isamu-takagi/ros2_sandbox/tree/interface-v1/src/sample_nodes/src
• https://github.com/isamu-takagi/ros2_sandbox/tree/interface-v2/src/sample_nodes/src
• isamu-takagi/ros2_sandbox@interface-v1...interface-v2

The interface specification package provides classes for abstracted interface generation. Use the interface as below through this class.

1 - Declare abstracted publisher/subscription.

using InterfaceClass = interface_specification_package::interface_name::v1::Interface;
InterfaceClass::Publisher pub_;     // alias for rclcpp::Publisher<TypeAdaptor>
InterfaceClass::Subscription sub_;  // alias for rclcpp::Subscription<TypeAdaptor>

2 - Create interface via interface generation class.

const auto interface = ComponentInterfaceManager(node);
pub = interface.create_publisher<InterfaceClass>();
sub = interface.create_subscription<InterfaceClass>(callback);

3 - Publish/subscribe using custom type.

void publish()
{
  InterfaceClass::Message msg;
  pub_->publish(msg;
}

void callback(const InterfaceClass::Message & msg)
{
  dump(msg);
}

[isamu-takagi]

These ideas were considered, but were not adopted for the following reasons.

1. Duplicate message types and topics for each version like.
   • https://github.com/orgs/autowarefoundation/discussions/3668#discussioncomment-6634936
   • Duplicating topics increases processing load
2. Use [REP-2011] Evolving Message Types
   • Details are not yet known and release date is unknown.
   • This also looks like the topic is duplicated for each version.

[isamu-takagi]

The following are some common interface issues that I hear about:

1. interface changes frequently
2. no interfaces transition period
3. clarify public/private interfaces
4. binary compatibility of messages

This proposal is for the first issue (1. interface changes frequently). Many of the message changes are small updates or package moves. These are often due to implementation reasons, but ROS message also affects the interface. So add the access class as an interface.

Note: The proposal uses type adaption, but since this requires a complete copy of the message, I think access class is better for now.

Duplicate message types and topics for each version like.

This method is effective for large changes. So I think this method will be considered for major interface update, and this resolve second issue (2. no interfaces transition period). The third and fourth issues are not resolved by this proposal, so I would like to discuss them separately.

[xmfcx]

Hello @isamu-takagi san,
Thanks for this proposal. I have tried the type adaptation feature before and it is a promising feature for us to utilize in the Autoware too.

I would like to ask some simple questions. I'm asking these just to understand, not to criticize.

Let's assume we have adopted this feature for the entire Autoware, everything has integrated this feature as you've suggested.

I see this brings the following:

const auto interface = ComponentInterfaceManager(node);
pub = interface.create_publisher<InterfaceClass>();
sub = interface.create_subscription<InterfaceClass>(callback);

• Do you think that every node in the Autoware codebase should use these interfaces to interact with any messages?
• How many interface_specification_package do we need?
  • Do we need per package/message or all should be handled within a single package?
• This feature protects only the Autoware packages from the message modifications, not the external tools/packages that depend on the messages right?

[xmfcx]

How should we start implementing these changes?

Do you have a proposed order/list of packages to start implementing this?

[isamu-takagi]

We want to maintain compatibility of the interfaces used by the simulators we are developing. Therefore, I would like to list the interfaces used by the simulator and discuss whether they are suitable as interfaces.

We are currently creating a list of interfaces.

[xmfcx]

That's good to hear! Please tag me when you create an issue.
And let me know if you need any help in any part of this work.

[isamu-takagi]

@xmfcx I started a discussion about the interface.
https://github.com/orgs/autowarefoundation/discussions/3922#discussioncomment-7563259

[isamu-takagi]

@xmfcx cc: @mitsudome-r @yukkysaito
After considering it again, it seems better to provide an accessor class. The details are explained on this page.
autowarefoundation/autoware.universe#6419

[isamu-takagi]

I asked simulator developers to list the interfaces the simulator uses. We would like to discuss whether these topics and services should be defined as interfaces.

• AD API

  • /api/fail_safe/mrm_state
  • /api/localization/initialization_state
  • /api/localization/initialize
  • /api/routing/set_route_points

• AD API prototyping (TIER IV internal, These will be replaced by AD API)

  • /api/external/get/rtc_status
  • /api/external/set/rtc_auto_mode
  • /api/external/set/rtc_commands

• Vehicle interface

  • /vehicle/status/control_mode
  • /vehicle/status/gear_status
  • /vehicle/status/turn_indicators_status
  • /vehicle/status/velocity_status
  • /vehicle/status/steering_status

• Localization component

  • /localization/acceleration
  • /localization/kinematic_state

• Planning component

  • /planning/scenario_planning/trajectory
  • /planning/scenario_planning/lane_driving/behavior_planning/behavior_velocity_planner/debug/intersection
  • /planning/scenario_planning/lane_driving/behavior_planning/path_with_lane_id
  • /planning/scenario_planning/max_velocity_default

• Control component

  • /control/command/control_cmd
  • /control/command/gear_cmd
  • /control/command/turn_indicators_cmd

• Perception component

  • /perception/object_recognition/detection/objects
  • /perception/object_recognition/ground_truth/objects
  • /perception/obstacle_segmentation/pointcloud
  • /perception/occupancy_grid_map/map
  • /perception/traffic_light_recognition/internal/traffic_signals
  • /perception/traffic_light_recognition/traffic_signals

[isamu-takagi]

Given the list above, I'm creating a list of topics and services that will be defined as interfaces. An overview is as follows.

AD API and AD API prototyping

The AD API is independently versioned and will not be discussed here.

Vehicle interface

It is appropriate to define. This allows vehicle driver developers to easily know which interfaces to implement. It would be nice if we could also define control mode change request and door that are not listed.

Localization component

It is appropriate to define. However, it may be better to wait for the conclusion of this discussion.
https://github.com/orgs/autowarefoundation/discussions/2455#discussioncomment-2241651 (Was it decided on option 1?)

Planning component

Exclude debug topics. And path_with_lane_id is not applicable because it is only used inside the component.
I think trajectory and velocity limit feature should be defined as interfaces.

Control component

It is appropriate to define.

Perception component

According to this page, The following topics are the interfaces.

• /perception/object_recognition/objects (predicted objects, not detection/objects)
• /perception/traffic_light_recognition/traffic_signals

[isamu-takagi]

First I plan to define the interface below as autoware_control_vehicle_interface. This is the interface between the vehicle and the control component.

Interface namespace	Topic/service name
control_mode_request	/control/control_mode_request
control_mode_status	/vehicle/status/control_mode
control_command	/control/command/control_cmd
velocity_status	/vehicle/status/velocity_status
steering_status	/vehicle/status/steering_status
gear_command	/control/command/gear_cmd
gear_status	/vehicle/status/gear_status
turn_indicators_command	/control/command/turn_indicators_cmd
turn_indicators_status	/vehicle/status/turn_indicators_status
hazard_lights_command	/control/command/hazard_lights_cmd
hazard_lights_status	/vehicle/status/hazard_lights_status

[isamu-takagi]

I have created a task to implement this proposal. autowarefoundation/autoware.universe#6419

[isamu-takagi]

Since type adaptation for services is not implemented, I plan to solve this by introducing a wrapper class. See the diagram in autowarefoundation/autoware.universe#6419 for details.