Interface Design (AD API)

[isamu-takagi]

I would like to initiate the discussion for the interface design of Core/Universe.

The overview of the AD stack is being discussed here, and this discussion thread would focus on the details of the Interfaces between components and API for the application.

Tier IV has prepared the initial proposal in the following pages:

• docs(autoware-interfaces): add autoware interface design autoware-documentation#69
• https://autowarefoundation.github.io/autoware-documentation/pr-69/design/autoware-interfaces/

[xmfcx]

autowarefoundation/autoware-documentation#69

[isamu-takagi]

I started implementing the API prototype to help discussion of API.

• feat(default_ad_api): add interface version autoware.universe#704

[isamu-takagi]

Localization API

Unify the location initialization method to the service. The topic /initialpose from rviz is only subscribed to by adapter node and converted to API call. This API call is forwarded to the pose initializer node so it can centralize the state of pose initialization. For other nodes that require initialpose, pose initializer node publishes as /initialpose3d.

(Actually, the module when using GNSS is included in the pose initializer node.)

Docs

• https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/ad-api/list/api/localization/

PRs

• feat(autoware_ad_api_specs): define localization interface autoware.universe#1560
• feat(default_ad_api): add localization api  autoware.universe#1431
• feat(pose_initializer)!: support ad api autoware.universe#1500
• feat(autoware_launch): add rviz helper for ad api autoware_launch#70
• feat(autoware_launch): apply the change of pose initializer autoware_launch#72
• feat(tier4_localization_msgs): remove pose initialization request  tier4/tier4_autoware_msgs#44

[isamu-takagi]

Routing API

Unify the route setting method to the service. This API supports two waypoint formats, poses and HADMap segments. The goal and checkpoint topics from rviz is only subscribed to by adapter node and converted to API call. This API call is forwarded to the mission planner node so it can centralize the state of routing. For other nodes that require route, mission planner node publishes as /planning/mission_planning/route.

Docs

• https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/ad-api/list/api/routing/

PRs

• feat(autoware_ad_api_specs): define routing interface autoware.universe#1559
• feat(default_ad_api): add routing api autoware.universe#1494
• feat(autoware_launch): add rviz helper for ad api autoware_launch#70
• feat(mission_planner)!: support ad api autoware.universe#1495
• feat(autoware_common_msgs): add autoware common messages autoware_msgs#37
• feat(autoware_planning_msgs): add autoware planning messages autoware_msgs#33

[isamu-takagi]

Motion API

Provides a hook for when the vehicle starts. It is typically used for announcements that call attention to the surroundings. Add a pause function to the vehicle_cmd_gate, and API will control it based on vehicle stopped and start requested.

Docs

• https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/ad-api/list/api/motion/

PRs

• feat(autoware_ad_api_specs): define motion interface autoware.universe#1808
• feat(default_ad_api): add motion api  autoware.universe#1809
• feat(vehicle_cmd_gate)!: support ad api autoware.universe#1810
• feat(tier4_control_msgs): add accept start interface tier4/tier4_autoware_msgs#53

[isamu-takagi]

Operation Mode API

Introduce operation mode. It handles autoware engage, gate_mode, external_cmd_selector and control_mode abstractly. When the mode is changed, it will be in-transition state, and if the transition completion condition to that mode is not satisfied, it will be returned to the previous mode. Also, currently, the condition for mode change is only WaitingForEngage in /autoware/state, and the engage state is shared between modes. After introducing operation mode, each mode will have a transition available flag.

state transition

nodes and topics

Docs

• https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/ad-api/list/api/operation_mode/

PRs

• feat(autoware_ad_api_specs): define operation mode interface autoware.universe#1570
• feat(default_ad_api): add operation mode api autoware.universe#1569
• feat(component_state_monitor): add component state monitor autoware.universe#2120
• feat(topic_state_monitor): support transform topic check autoware.universe#1586
• feat(operation_mode_transition_manager): support ad api autoware.universe#1535
• feat(tier4_system_msgs): change operation mode messages tier4/tier4_autoware_msgs#46

[evshary]

@isamu-takagi This is awesome architecture and clarifies some of my questions about AD API!
After viewing the topic and service from here, I guess the idea will be that FMS uses AD API to change the operation mode, but leaves the control command to other components.
From the description below, Remote means "Manually control the vehicle from a web application on the cloud."

In your architecture, I saw that control command (remote) does not come from AD API. May I know how this works?

[isamu-takagi]

@evshary The control commands are currently available for the following topics. But these are prototypes, so topics should be designed later and defined as AD API.

• /api/external/set/command/local/control
• /api/external/set/command/local/heartbeat
• /api/external/set/command/local/shift
• /api/external/set/command/local/turn_signal
• /api/external/set/command/remote/control
• /api/external/set/command/remote/heartbeat
• /api/external/set/command/remote/shift
• /api/external/set/command/remote/turn_signal

[evshary]

@isamu-takagi Thank you for the answers.
I found that these topics are published directly in packages external_cmd_selector.
Do you mean that these topics should be moved to tier4_autoware_api_launch and covert to AD API later?

[isamu-takagi]

That's right. First, consider a message type suitable for AD API, and rename the topic name if necessary. Then, create a node to relay or convert in the AD API package. This node is launched by tier4_autoware_api_launch.

[evshary]

Good to know that. Really appreciate your answer!

[isamu-takagi]

Resource API

Cancelled.

[isamu-takagi]

We are currently considering resource API for updating the parameter file.
autowarefoundation/autoware-documentation#275

[isamu-takagi]

Related to #3123

[isamu-takagi]

Vehicle status API

#3232
#3226

[isamu-takagi]

Visualization API

#3225