diff --git a/docs/design/autoware-interfaces/ad-api/features/cooperation.md b/docs/design/autoware-interfaces/ad-api/features/cooperation.md new file mode 100644 index 00000000000..b094e41340f --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/features/cooperation.md @@ -0,0 +1,94 @@ +# Cooperation + +## Related API + +- {{ link_ad_api('/api/planning/velocity_factors') }} +- {{ link_ad_api('/api/planning/steering_factors') }} +- {{ link_ad_api('/api/planning/cooperation/set_commands') }} +- {{ link_ad_api('/api/planning/cooperation/set_policies') }} +- {{ link_ad_api('/api/planning/cooperation/get_policies') }} + +## Description + +Request to cooperate (RTC) is a feature that enables a human operator to support the decision in autonomous driving mode. +Autoware usually drives the vehicle using its own decisions, but the operator may prefer to make their decisions in experiments and complex situations. + +The planning component manages each situation that requires decision as a scene. +Each scene has an ID that doesn't change until the scene is completed or canceled. +The operator can override the decision of the target scene using this ID. +In practice, the user interface application can hides the specification of the ID and provides an abstracted interface to the operator. + +For example, in the situation in the diagram below, vehicle is expected to make two lane changes and turning left at the intersection. +Therefore the planning component generates three scene instances for each required action, and each scene instance will wait for the decision to be made, in this case "changing or keeping lane" and "turning left or waiting at the intersection". +Here Autoware decides not to change lanes a second time due to the obstacle, so the vehicle will stop there. +However, operator could overwrite that decision through RTC function and force the lane change so that vehicle could reach to it's goal. +Using RTC, the operator can override these decisions to continue driving the vehicle to the goal. + +![cooperation-scenes](./cooperation/scenes.drawio.svg) + +## Architecture + +Modules that support RTC have the operator decision and cooperation policy in addition to the module decision as shown below. +These modules use the merged decision that is determined by these values when planning vehicle behavior. +See decisions section for details of these values. +The cooperation policy is used when there is no operator decision and has a default value set by the system settings. +If the module supports RTC, these information are available in [velocity factors or steering factors](./planning-factors.md) as [cooperation status](../types/autoware_adapi_v1_msgs/msg/CooperationStatus.md). + +![cooperation-architecture](./cooperation/architecture.drawio.svg) + +## Sequence + +This is an example sequence that overrides the scene decision to force a lane change. It is for the second scene in the diagram in the architecture section. +Here let's assume the cooperation policy is set to optional, see the decisions section described later for details. + +1. A planning module creates a scene instance with unique ID when approaching a place where a lane change is needed. +2. The scene instance generates the module decision from the current situation. In this case, the module decision is not to do a lane change due to the obstacle. +3. The scene instance generates the merged decision. At this point, there is no operator decision yet, so it is based on the module decision. +4. The scene instance plans the vehicle to keep the lane according to the merged decision. +5. The scene instance sends a cooperation status. +6. The operator receives the cooperation status. +7. The operator sends a cooperation command to override the module decision and to do a lane change. +8. The scene instance receives the cooperation command and update the operator decision. +9. The scene instance updates the module decision from the current situation. +10. The scene instance updates the merged decision. It is based on the operator decision received. +11. The scene instance plans the vehicle to change the lane according to the merged decision. + +## Decisions + +The merged decision is determined by the module decision, operator decision, and cooperation policy, each of which takes the value shown in the table below. + +| Status | Values | +| ------------------ | -------------------------------------- | +| merged decision | deactivate, activate | +| module decision | deactivate, activate | +| operator decision | deactivate, activate, autonomous, none | +| cooperation policy | required, optional | + +The meanings of these values are as follows. Note that the cooperation policy is common per module, so changing it will affect all scenes in the same module. + +| Value | Description | +| ---------- | ------------------------------------------------------------------------------------------ | +| deactivate | An operator/module decision to plan vehicle behavior with priority on safety. | +| activate | An operator/module decision to plan vehicle behavior with priority on driving. | +| autonomous | An operator decision that follows the module decision. | +| none | An initial value for operator decision, indicating that there is no operator decision yet. | +| required | A policy that requires the operator decision to continue driving. | +| optional | A policy that does not require the operator decision to continue driving. | + +The following flow is how the merged decision is determined. + +![cooperation-decisions](./cooperation/decisions.drawio.svg) + +## Examples + +This is an example of cooperation for lane change module. The behaviors by the combination of decisions are as follows. + +| Operator decision | Policy | Module decision | Description | +| ----------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| deactivate | - | - | The operator instructs to keep lane regardless the module decision. So the vehicle keeps the lane by the operator decision. | +| activate | - | - | The operator instructs to change lane regardless the module decision. So the vehicle changes the lane by the operator decision. | +| autonomous | - | deactivate | The operator instructs to follow the module decision. So the vehicle keeps the lane by the module decision. | +| autonomous | - | activate | The operator instructs to follow the module decision. So the vehicle changes the lane by the module decision. | +| none | required | - | The required policy is used because no operator instruction. So the vehicle keeps the lane by the cooperation policy. | +| none | optional | deactivate | The optional policy is used because no operator instruction. So the vehicle keeps the lane by the module decision. | +| none | optional | activate | The optional policy is used because no operator instruction. So the vehicle change the lane by the module decision. | diff --git a/docs/design/autoware-interfaces/ad-api/features/cooperation/architecture.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/cooperation/architecture.drawio.svg new file mode 100644 index 00000000000..77f18865950 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/features/cooperation/architecture.drawio.svg @@ -0,0 +1,260 @@ + + + + + + + + + + + + +
+
+
+ planning +
+ module +
+
+
+ + + planning... + + + + + + + + + +
+
+
+ merged decision +
+
+
+ + + merged decision + + + + + + + + + +
+
+
+ cooperation policy + +
+ +
+
+
+ + + cooperation policy + + + + + + + + + + + +
+
+
+ operator +
+
+
+ + + operator + + + + + + + +
+
+
+ cooperation status +
+
+
+ + + cooperation stat... + + + + + + + + + +
+
+
+ operator decision +
+
+
+ + + operator decision + + + + + + + + + +
+
+
+ module decision +
+
+
+ + + module decision + + + + + + + + + +
+
+
+ system +
+ settings +
+
+
+ + + system... + + + + + + + +
+
+
+ init +
+
+
+ + + init + + + + + + + +
+
+
+ set decision +
+
+
+ + + set decision + + + + + + + +
+
+
+ set policy +
+
+
+ + + set policy + + + + + + + +
+
+
+ for each scene class +
+
+
+ + + for each scene class + + + + + + + +
+
+
+ for each scene instance +
+
+
+ + + for each scene instance + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-interfaces/ad-api/features/cooperation/decisions.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/cooperation/decisions.drawio.svg new file mode 100644 index 00000000000..14ce9fee5f4 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/features/cooperation/decisions.drawio.svg @@ -0,0 +1,337 @@ + + + + + + + + + + + + + + +
+
+
+ Check the operator decision. +
+
+
+ + + Check the operator decision. + + + + + + + + + + + + + + + + + + +
+
+
+ Check the cooperation policy. +
+
+
+ + + Check the cooperation policy. + + + + + + + +
+
+
+ [autonomous] +
+
+
+ + + [autonomous] + + + + + + + + + +
+
+
+ The merged decision is deactivate +
+ by the cooperation policy. +
+
+
+ + + The merged decision is deactivate... + + + + + + + +
+
+
+ [optional] +
+
+
+ + + [optional] + + + + + + + + + +
+
+
+ The merged decision is activate +
+ by the operator decision. +
+
+
+ + + The merged decision is activate... + + + + + + + + + + + + +
+
+
+ [none] +
+
+
+ + + [none] + + + + + + + +
+
+
+ [deactivate] +
+
+
+ + + [deactivate] + + + + + + + +
+
+
+ [activate] +
+
+
+ + + [activate] + + + + + + + +
+
+
+ + [required] + +
+
+
+ + + [required] + + + + + + + +
+
+
+ [deactivate] +
+
+
+ + + [deactivate] + + + + + + + + + +
+
+
+ Check the module decision. +
+
+
+ + + Check the module decision. + + + + + + + + + + + + + + +
+
+
+ The merged decision is activate +
+ by the module decision. +
+
+
+ + + The merged decision is activate... + + + + + + + + + +
+
+
+ The merged decision is deactivate +
+ by the module decision. +
+
+
+ + + The merged decision is deactivate... + + + + + + + + + +
+
+
+ The merged decision is deactivate +
+ by the operator decision. +
+
+
+ + + The merged decision is deactivate... + + + + + + + +
+
+
+ [activate] +
+
+
+ + + [activate] + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-interfaces/ad-api/features/cooperation/scenes.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/cooperation/scenes.drawio.svg new file mode 100644 index 00000000000..9b813850ed5 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/features/cooperation/scenes.drawio.svg @@ -0,0 +1,140 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ obstacle +
+
+
+ + + obstacle + + + + + + + + + + + + + +
+
+
+
+ Scene ID: 1234 +
+
+ Behavior: lane-change +
+
+ Decision: activate +
+
+
+
+ + + Scene ID: 1234... + + + + + + + + +
+
+
+ Scene ID + + : 5678 + +
+
+ Behavior: lane-change +
+
+ Decision: deactivate +
+
+
+
+ + + Scene ID: 5678... + + + + + + + + +
+
+
+ Scene ID + + : ABCD + +
+
+ Behavior: intersection +
+
+ Decision: activate +
+
+
+
+ + + Scene ID: ABCD... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-interfaces/ad-api/features/planning-factors.md b/docs/design/autoware-interfaces/ad-api/features/planning-factors.md index eff614ae230..d595448687f 100644 --- a/docs/design/autoware-interfaces/ad-api/features/planning-factors.md +++ b/docs/design/autoware-interfaces/ad-api/features/planning-factors.md @@ -12,59 +12,58 @@ Applications can notify the vehicle behavior to the people around and visualize ## Velocity factors -The velocity factors is an array of information on the behavior that the vehicle stops (or slows down). -Each factor has a type shown below, pose in the base link, distance, status, and detailed data depending on its type. +The velocity factors is an array of information on the behavior that the vehicle stops or slows down. +Each factor has a behavior type which is described below. +Some behavior types have sequence and details as additional information. + +| Behavior | Description | +| --------------------------- | ----------------------------------------------------------------------------------- | +| surrounding-obstacle | There are obstacles immediately around the vehicle. | +| route-obstacle | There are obstacles along the route ahead. | +| intersection | There are obstacles in other lanes in the path. | +| crosswalk | There are obstacles on the crosswalk. | +| rear-check | There are obstacles behind that would be in a human driver's blind spot. | +| user-defined-attention-area | There are obstacles in the predefined attention area. | +| no-stopping-area | There is not enough space beyond the no stopping area. | +| stop-sign | A stop by a stop sign. | +| traffic-signal | A stop by a traffic signal. | +| v2x-gate-area | A stop by a gate area. It has enter and leave as sequences and v2x type as details. | +| merge | A stop before merging lanes. | +| sidewalk | A stop before crossing the sidewalk. | +| lane-change | A lane change. | +| avoidance | A path change to avoid an obstacle in the current lane. | +| emergency-operation | A stop by emergency instruction from the operator. | + +Each factor also provides status, poses in the base link frame, and distance from that pose. As the vehicle approaches the stop position, this factor appears with a status of APPROACHING. And when the vehicle reaches that position and stops, the status will be STOPPED. -The pose indicates the stop position or the base link if the stop position cannot be calculated. +The pose indicates the stop position, or the base link if the stop position cannot be calculated. ![velocity-factors](./planning-factors/velocity-factors.drawio.svg) -| Factor Type | Description | -| --------------------------- | ------------------------------------------------------------------------ | -| SURROUNDING_OBSTACLE | There are obstacles immediately around the vehicle. | -| ROUTE_OBSTACLE | There are obstacles along the route ahead. | -| INTERSECTION | There are obstacles in other lanes in the path. | -| CROSSWALK | There are obstacles on the crosswalk. | -| REAR_CHECK | There are obstacles behind that would be in a human driver's blind spot. | -| USER_DEFINED_DETECTION_AREA | There are obstacles in the predefined detection area. | -| NO_STOPPING_AREA | There is not enough space beyond the no stopping area. | -| STOP_SIGN | A stop by a stop sign. | -| TRAFFIC_SIGNAL | A stop by a traffic signal. | -| V2I_GATE_CONTROL_ENTER | A stop by a V2I gate entering. | -| V2I_GATE_CONTROL_LEAVE | A stop by a V2I gate leaving. | -| MERGE | A stop before merging lanes. | -| SIDEWALK | A stop before crossing the sidewalk. | -| LANE_CHANGE | A lane change. | -| AVOIDANCE | A path change to avoid an obstacle in the current lane. | -| EMERGENCY_OPERATION | A stop by emergency instruction from the operator. | - ## Steering factors The steering factors is an array of information on the maneuver that requires use of turn indicators, such as turning left or right. -Each factor has a type shown below, pose in the base link, distance, status, and detailed data depending on its type. +Each factor has a behavior type which is described below and steering direction. +Some behavior types have sequence and details as additional information. + +| Behavior | Description | +| ------------------- | --------------------------------------------------------------------------- | +| intersection | A turning left or right at an intersection. | +| lane-change | A lane change. | +| avoidance | A path change to avoid an obstacle. It has a sequence of change and return. | +| start-planner | T.B.D. | +| goal-planner | T.B.D. | +| emergency-operation | A path change by emergency instruction from the operator. | + +Each factor also provides status, poses in the base link frame, and distances from that poses. As the vehicle approaches the position to start steering, this factor appears with a status of APPROACHING. And when the vehicle reaches that position, the status will be TURNING. -The pose indicates the start position when APPROACHING and the end position when TURNING. +The poses indicate the start and end position of the section where the status is TURNING. ![steering-factors-1](./planning-factors/steering-factors-1.drawio.svg) In cases such as lane change and avoidance, the vehicle will start steering at any position in the range depending on the situation. -As the vehicle approaches the start position of the range, this factor appears with a status of APPROACHING. -And when the vehicle reaches that position, the status will be TRYING. -Then, when it is possible, the vehicle will start steering and the status will be TURNING. -The pose indicates the start of the range (A) when APPROACHING and the end of the range (B) when TRYING. -The position to end steering (C to D) for TURNING depends on the position to start steering. +For these types, the section where the status is TURNING will be updated dynamically and the poses will follow that. ![steering-factors-2](./planning-factors/steering-factors-2.drawio.svg) - -| Factor Type | Description | -| --------------------- | ------------------------------------------------------------------------ | -| INTERSECTION | A turning left or right at an intersection. | -| LANE_CHANGE | A lane change. | -| AVOIDANCE_PATH_CHANGE | A path change to avoid an obstacle in the current lane. | -| AVOIDANCE_PATH_RETURN | A path change to return to the original lane after avoiding an obstacle. | -| STATION | T.B.D. (bus stop) | -| PULL_OUT | T.B.D. | -| PULL_OVER | T.B.D. | -| EMERGENCY_OPERATION | A path change by emergency instruction from the operator. | diff --git a/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-1.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-1.drawio.svg index a47339dbf64..b5c1d2eb3f3 100644 --- a/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-1.drawio.svg +++ b/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-1.drawio.svg @@ -1,4 +1,4 @@ - + @@ -60,7 +60,7 @@ - Viewer does not support full SVG 1.1 + Text is not SVG - cannot display diff --git a/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-2.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-2.drawio.svg index b2f15b2ff99..74511043061 100644 --- a/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-2.drawio.svg +++ b/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-2.drawio.svg @@ -1,4 +1,4 @@ - + @@ -7,8 +7,7 @@ - - + @@ -31,25 +30,6 @@ - - - - - - -
-
-
- TRYING -
-
-
- - - TRYING - - - @@ -58,11 +38,11 @@ - + -
+
TURNING @@ -70,85 +50,17 @@
- + TURNING - - - - -
-
-
- A -
-
-
- - - A - - - - - - - -
-
-
- B -
-
-
- - - B - - - - - - - -
-
-
- C -
-
-
- - - C - - - - - - - -
-
-
- D -
-
-
- - - D - - - - Viewer does not support full SVG 1.1 + Text is not SVG - cannot display diff --git a/docs/design/autoware-interfaces/ad-api/index.md b/docs/design/autoware-interfaces/ad-api/index.md index d530255f586..35d60d980fb 100644 --- a/docs/design/autoware-interfaces/ad-api/index.md +++ b/docs/design/autoware-interfaces/ad-api/index.md @@ -25,7 +25,7 @@ Service providers can combine these use cases to define user stories and check i - [Drive to the designated position](./use-cases/drive-designated-position.md) - [Get on and get off](./use-cases/get-on-off.md) - [Vehicle monitoring](./use-cases/vehicle-monitoring.md) -- [Request to cooperate](./use-cases/request-to-cooperate.md) +- [Vehicle operation](./use-cases/vehicle-operation.md) ## Features @@ -39,3 +39,4 @@ Service providers can combine these use cases to define user stories and check i - [Fail-safe](./features/fail-safe.md) - [Vehicle status](./features/vehicle-status.md) - [Vehicle doors](./features/vehicle-doors.md) +- [Cooperation](./features/cooperation.md) diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/get_policies.md b/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/get_policies.md new file mode 100644 index 00000000000..6ffce00a8a1 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/get_policies.md @@ -0,0 +1,22 @@ +--- +title: /api/planning/cooperation/get_policies +status: not released +method: function call +type: + name: autoware_adapi_v1_msgs/srv/GetCooperationPolicies + res: + - name: status + text: response status + - name: policies.behavior + text: The type of the target behavior. + - name: policies.sequence + text: The type of the target sequence. + - name: policies.policy + text: The type of the cooporation policy. +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the default decision that is used instead when the operator's decision is undecided. +For details, see the [cooperation](../../../../features/cooperation.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/set_commands.md b/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/set_commands.md new file mode 100644 index 00000000000..bcca69658ed --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/set_commands.md @@ -0,0 +1,21 @@ +--- +title: /api/planning/cooperation/set_commands +status: not released +method: function call +type: + name: autoware_adapi_v1_msgs/srv/SetCooperationCommands + req: + - name: commands.uuid + text: The ID in the cooperation status. + - name: commands.cooperator + text: The operator's decision. + res: + - name: status + text: response status +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Set the operator's decision for cooperation. +For details, see the [cooperation](../../../../features/cooperation.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/set_policies.md b/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/set_policies.md new file mode 100644 index 00000000000..463bf6af96c --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/planning/cooperation/set_policies.md @@ -0,0 +1,23 @@ +--- +title: /api/planning/cooperation/set_policies +status: not released +method: function call +type: + name: autoware_adapi_v1_msgs/srv/SetCooperationPolicies + req: + - name: policies.behavior + text: The type of the target behavior. + - name: policies.sequence + text: The type of the target sequence. + - name: policies.policy + text: The type of the cooporation policy. + res: + - name: status + text: response status +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Set the default decision that is used instead when the operator's decision is undecided. +For details, see the [cooperation](../../../../features/cooperation.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/steering_factors.md b/docs/design/autoware-interfaces/ad-api/list/api/planning/steering_factors.md index 55afd3720b0..b5d0970e88a 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/planning/steering_factors.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/planning/steering_factors.md @@ -9,14 +9,18 @@ type: text: The base link pose related to the steering factor. - name: factors.distance text: The distance from the base link to the above pose. - - name: factors.type - text: The type of the steering factor. - name: factors.direction text: The direction of the steering factor. - name: factors.status text: The status of the steering factor. + - name: factors.behavior + text: The behavior type of the steering factor. + - name: factors.sequence + text: The sequence type of the steering factor. - name: factors.detail text: The additional information of the steering factor. + - name: factors.cooperation + text: The cooperation status if the module supports. --- {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/velocity_factors.md b/docs/design/autoware-interfaces/ad-api/list/api/planning/velocity_factors.md index 8758e6016e5..8889cbb69cf 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/planning/velocity_factors.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/planning/velocity_factors.md @@ -9,12 +9,16 @@ type: text: The base link pose related to the velocity factor. - name: factors.distance text: The distance from the base link to the above pose. - - name: factors.type - text: The type of the velocity factor. - name: factors.status text: The status of the velocity factor. + - name: factors.behavior + text: The behavior type of the velocity factor. + - name: factors.sequence + text: The sequence type of the velocity factor. - name: factors.detail text: The additional information of the velocity factor. + - name: factors.cooperation + text: The cooperation status if the module supports. --- {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} diff --git a/docs/design/autoware-interfaces/ad-api/list/index.md b/docs/design/autoware-interfaces/ad-api/list/index.md index 9005e34f5ad..a95a73b670b 100644 --- a/docs/design/autoware-interfaces/ad-api/list/index.md +++ b/docs/design/autoware-interfaces/ad-api/list/index.md @@ -14,6 +14,9 @@ - [/api/operation_mode/enable_autoware_control](./api/operation_mode/enable_autoware_control.md) - [/api/operation_mode/state](./api/operation_mode/state.md) - [/api/perception/objects](./api/perception/objects.md) +- [/api/planning/cooperation/get_policies](./api/planning/cooperation/get_policies.md) +- [/api/planning/cooperation/set_commands](./api/planning/cooperation/set_commands.md) +- [/api/planning/cooperation/set_policies](./api/planning/cooperation/set_policies.md) - [/api/planning/steering_factors](./api/planning/steering_factors.md) - [/api/planning/velocity_factors](./api/planning/velocity_factors.md) - [/api/routing/clear_route](./api/routing/clear_route.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationCommand.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationCommand.md new file mode 100644 index 00000000000..c088129687d --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationCommand.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/CooperationCommand +used: + - autoware_adapi_v1_msgs/srv/SetCooperationCommands +uses: + - autoware_adapi_v1_msgs/msg/CooperationDecision +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +unique_identifier_msgs/UUID uuid +autoware_adapi_v1_msgs/CooperationDecision cooperator +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationDecision.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationDecision.md new file mode 100644 index 00000000000..1725dd81f79 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationDecision.md @@ -0,0 +1,22 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/CooperationDecision +used: + - autoware_adapi_v1_msgs/msg/CooperationCommand + - autoware_adapi_v1_msgs/msg/CooperationStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint8 UNKNOWN = 0 +uint8 DEACTIVATE = 1 +uint8 ACTIVATE = 2 +uint8 AUTONOMOUS = 3 +uint8 UNDECIDED = 4 + +uint8 decision +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationPolicy.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationPolicy.md new file mode 100644 index 00000000000..58bfbc9ae8d --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationPolicy.md @@ -0,0 +1,21 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/CooperationPolicy +used: + - autoware_adapi_v1_msgs/srv/GetCooperationPolicies + - autoware_adapi_v1_msgs/srv/SetCooperationPolicies +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint8 OPTIONAL = 1 +uint8 REQUIRED = 2 + +string behavior +string sequence +uint8 policy +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationStatus.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationStatus.md new file mode 100644 index 00000000000..eee513f2c67 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/CooperationStatus.md @@ -0,0 +1,21 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/CooperationStatus +used: + - autoware_adapi_v1_msgs/msg/SteeringFactor + - autoware_adapi_v1_msgs/msg/VelocityFactor +uses: + - autoware_adapi_v1_msgs/msg/CooperationDecision +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +unique_identifier_msgs/UUID uuid +autoware_adapi_v1_msgs/CooperationDecision autonomous +autoware_adapi_v1_msgs/CooperationDecision cooperator +bool cancellable +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md index 9918fa9323a..7a2b8f31505 100644 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md @@ -5,9 +5,12 @@ used: - autoware_adapi_v1_msgs/srv/AcceptStart - autoware_adapi_v1_msgs/srv/ChangeOperationMode - autoware_adapi_v1_msgs/srv/ClearRoute + - autoware_adapi_v1_msgs/srv/GetCooperationPolicies - autoware_adapi_v1_msgs/srv/GetDoorLayout - autoware_adapi_v1_msgs/srv/GetVehicleDimensions - autoware_adapi_v1_msgs/srv/InitializeLocalization + - autoware_adapi_v1_msgs/srv/SetCooperationCommands + - autoware_adapi_v1_msgs/srv/SetCooperationPolicies - autoware_adapi_v1_msgs/srv/SetDoorCommand - autoware_adapi_v1_msgs/srv/SetRoute - autoware_adapi_v1_msgs/srv/SetRoutePoints diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactor.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactor.md index 1b35ddeb8a3..907033274ab 100644 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactor.md +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactor.md @@ -3,6 +3,8 @@ title: autoware_adapi_v1_msgs/msg/SteeringFactor used: - autoware_adapi_v1_msgs/msg/SteeringFactorArray +uses: + - autoware_adapi_v1_msgs/msg/CooperationStatus --- {% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} @@ -12,18 +14,6 @@ used: # constants for common use uint16 UNKNOWN = 0 -# constants for type -uint16 INTERSECTION = 1 -uint16 LANE_CHANGE = 2 -uint16 AVOIDANCE_PATH_CHANGE = 3 -uint16 AVOIDANCE_PATH_RETURN = 4 -uint16 STATION = 5 -uint16 PULL_OUT = 6 # Deprecated. Use START_PLANNER. -uint16 START_PLANNER = 6 -uint16 PULL_OVER = 7 # Deprecated. Use GOAL_PLANNER. -uint16 GOAL_PLANNER = 7 -uint16 EMERGENCY_OPERATION = 8 - # constants for direction uint16 LEFT = 1 uint16 RIGHT = 2 @@ -31,16 +21,37 @@ uint16 STRAIGHT = 3 # constants for status uint16 APPROACHING = 1 -uint16 TRYING = 2 uint16 TURNING = 3 # variables geometry_msgs/Pose[2] pose float32[2] distance -uint16 type uint16 direction uint16 status +string behavior +string sequence string detail +autoware_adapi_v1_msgs/CooperationStatus[<=1] cooperation + + + +# deprecated constants for type +uint16 INTERSECTION = 1 +uint16 LANE_CHANGE = 2 +uint16 AVOIDANCE_PATH_CHANGE = 3 +uint16 AVOIDANCE_PATH_RETURN = 4 +uint16 STATION = 5 +uint16 PULL_OUT = 6 # Deprecated. Use START_PLANNER. +uint16 START_PLANNER = 6 +uint16 PULL_OVER = 7 # Deprecated. Use GOAL_PLANNER. +uint16 GOAL_PLANNER = 7 +uint16 EMERGENCY_OPERATION = 8 + +# deprecated constants for status +uint16 TRYING = 2 + +# deprecated variables +uint16 type ``` {% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactor.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactor.md index 7cb4125992f..8749fcd7b0f 100644 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactor.md +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactor.md @@ -3,6 +3,8 @@ title: autoware_adapi_v1_msgs/msg/VelocityFactor used: - autoware_adapi_v1_msgs/msg/VelocityFactorArray +uses: + - autoware_adapi_v1_msgs/msg/CooperationStatus --- {% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} @@ -12,7 +14,22 @@ used: # constants for common use uint16 UNKNOWN = 0 -# constants for type +# constants for status +uint16 APPROACHING = 1 +uint16 STOPPED = 2 + +# variables +geometry_msgs/Pose pose +float32 distance +uint16 status +string behavior +string sequence +string detail +autoware_adapi_v1_msgs/CooperationStatus[<=1] cooperation + + + +# deprecated constants for type uint16 SURROUNDING_OBSTACLE = 1 uint16 ROUTE_OBSTACLE = 2 uint16 INTERSECTION = 3 @@ -31,16 +48,8 @@ uint16 AVOIDANCE = 15 uint16 EMERGENCY_STOP_OPERATION = 16 uint16 NO_DRIVABLE_LANE = 17 -# constants for status -uint16 APPROACHING = 1 -uint16 STOPPED = 2 - -# variables -geometry_msgs/Pose pose -float32 distance +# deprecated variables uint16 type -uint16 status -string detail ``` {% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetCooperationPolicies.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetCooperationPolicies.md new file mode 100644 index 00000000000..e6cc04266b2 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetCooperationPolicies.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/GetCooperationPolicies +uses: + - autoware_adapi_v1_msgs/msg/CooperationPolicy + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +--- +autoware_adapi_v1_msgs/ResponseStatus status +autoware_adapi_v1_msgs/CooperationPolicy[] policies +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetCooperationCommands.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetCooperationCommands.md new file mode 100644 index 00000000000..be9e777245a --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetCooperationCommands.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/SetCooperationCommands +uses: + - autoware_adapi_v1_msgs/msg/CooperationCommand + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +autoware_adapi_v1_msgs/CooperationCommand[] commands +--- +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetCooperationPolicies.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetCooperationPolicies.md new file mode 100644 index 00000000000..b25068edd9a --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetCooperationPolicies.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/SetCooperationPolicies +uses: + - autoware_adapi_v1_msgs/msg/CooperationPolicy + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +autoware_adapi_v1_msgs/CooperationPolicy[] policies +--- +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/index.md b/docs/design/autoware-interfaces/ad-api/types/index.md index fc2a043a3ac..c620381a216 100644 --- a/docs/design/autoware-interfaces/ad-api/types/index.md +++ b/docs/design/autoware-interfaces/ad-api/types/index.md @@ -1,5 +1,9 @@ # Types of Autoware AD API +- [autoware_adapi_v1_msgs/msg/CooperationCommand](./autoware_adapi_v1_msgs/msg/CooperationCommand.md) +- [autoware_adapi_v1_msgs/msg/CooperationDecision](./autoware_adapi_v1_msgs/msg/CooperationDecision.md) +- [autoware_adapi_v1_msgs/msg/CooperationPolicy](./autoware_adapi_v1_msgs/msg/CooperationPolicy.md) +- [autoware_adapi_v1_msgs/msg/CooperationStatus](./autoware_adapi_v1_msgs/msg/CooperationStatus.md) - [autoware_adapi_v1_msgs/msg/DoorCommand](./autoware_adapi_v1_msgs/msg/DoorCommand.md) - [autoware_adapi_v1_msgs/msg/DoorLayout](./autoware_adapi_v1_msgs/msg/DoorLayout.md) - [autoware_adapi_v1_msgs/msg/DoorStatus](./autoware_adapi_v1_msgs/msg/DoorStatus.md) @@ -33,9 +37,12 @@ - [autoware_adapi_v1_msgs/srv/AcceptStart](./autoware_adapi_v1_msgs/srv/AcceptStart.md) - [autoware_adapi_v1_msgs/srv/ChangeOperationMode](./autoware_adapi_v1_msgs/srv/ChangeOperationMode.md) - [autoware_adapi_v1_msgs/srv/ClearRoute](./autoware_adapi_v1_msgs/srv/ClearRoute.md) +- [autoware_adapi_v1_msgs/srv/GetCooperationPolicies](./autoware_adapi_v1_msgs/srv/GetCooperationPolicies.md) - [autoware_adapi_v1_msgs/srv/GetDoorLayout](./autoware_adapi_v1_msgs/srv/GetDoorLayout.md) - [autoware_adapi_v1_msgs/srv/GetVehicleDimensions](./autoware_adapi_v1_msgs/srv/GetVehicleDimensions.md) - [autoware_adapi_v1_msgs/srv/InitializeLocalization](./autoware_adapi_v1_msgs/srv/InitializeLocalization.md) +- [autoware_adapi_v1_msgs/srv/SetCooperationCommands](./autoware_adapi_v1_msgs/srv/SetCooperationCommands.md) +- [autoware_adapi_v1_msgs/srv/SetCooperationPolicies](./autoware_adapi_v1_msgs/srv/SetCooperationPolicies.md) - [autoware_adapi_v1_msgs/srv/SetDoorCommand](./autoware_adapi_v1_msgs/srv/SetDoorCommand.md) - [autoware_adapi_v1_msgs/srv/SetRoute](./autoware_adapi_v1_msgs/srv/SetRoute.md) - [autoware_adapi_v1_msgs/srv/SetRoutePoints](./autoware_adapi_v1_msgs/srv/SetRoutePoints.md) diff --git a/docs/design/autoware-interfaces/ad-api/use-cases/request-to-cooperate.md b/docs/design/autoware-interfaces/ad-api/use-cases/request-to-cooperate.md deleted file mode 100644 index 7b0dc2385d3..00000000000 --- a/docs/design/autoware-interfaces/ad-api/use-cases/request-to-cooperate.md +++ /dev/null @@ -1,7 +0,0 @@ -# Request to cooperate - -!!! warning - - Under Construction - -AD API supports operator cooperation for vehicle decisions. diff --git a/docs/design/autoware-interfaces/ad-api/use-cases/vehicle-operation.md b/docs/design/autoware-interfaces/ad-api/use-cases/vehicle-operation.md new file mode 100644 index 00000000000..4cfb7b2639e --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/use-cases/vehicle-operation.md @@ -0,0 +1,14 @@ +# Vehicle operation + +## Request to intervene + +Request to intervene (RTI) is a feature that requires the operator to switch to manual driving mode. It is also called Take Over Request (TOR). +Interfaces for RTI are currently being discussed. For now assume that manual driving is requested if the MRM state is not NORMAL. +See [fail-safe](../features/fail-safe.md) for details. + +## Request to cooperate + +Request to cooperate (RTC) is a feature that the operator supports the decision in autonomous driving mode. +Autoware usually drives the vehicle using its own decisions, but the operator may prefer to make their own decisions in complex situations. +Since RTC only overrides the decision and does not need to change operation mode, the vehicle can continue autonomous driving, unlike RTC. +See [cooperation](../features/cooperation.md) for details. diff --git a/yaml/autoware-interfaces.yaml b/yaml/autoware-interfaces.yaml index a86ed502e4d..7ee9a89be63 100644 --- a/yaml/autoware-interfaces.yaml +++ b/yaml/autoware-interfaces.yaml @@ -1,4 +1,22 @@ types: + autoware_adapi_v1_msgs/msg/CooperationCommand: + msg: + cooperator: autoware_adapi_v1_msgs/msg/CooperationDecision + uuid: unique_identifier_msgs/msg/UUID + autoware_adapi_v1_msgs/msg/CooperationDecision: + msg: + decision: uint8 + autoware_adapi_v1_msgs/msg/CooperationPolicy: + msg: + behavior: string + policy: uint8 + sequence: string + autoware_adapi_v1_msgs/msg/CooperationStatus: + msg: + autonomous: autoware_adapi_v1_msgs/msg/CooperationDecision + cancellable: bool + cooperator: autoware_adapi_v1_msgs/msg/CooperationDecision + uuid: unique_identifier_msgs/msg/UUID autoware_adapi_v1_msgs/msg/DoorCommand: msg: command: uint8 @@ -100,10 +118,13 @@ types: state: uint16 autoware_adapi_v1_msgs/msg/SteeringFactor: msg: + behavior: string + cooperation: autoware_adapi_v1_msgs/msg/CooperationStatus[<=1] detail: string direction: uint16 distance: float32[2] pose: geometry_msgs/msg/Pose[2] + sequence: string status: uint16 type: uint16 autoware_adapi_v1_msgs/msg/SteeringFactorArray: @@ -141,9 +162,12 @@ types: turn_indicators: autoware_adapi_v1_msgs/msg/TurnIndicators autoware_adapi_v1_msgs/msg/VelocityFactor: msg: + behavior: string + cooperation: autoware_adapi_v1_msgs/msg/CooperationStatus[<=1] detail: string distance: float32 pose: geometry_msgs/msg/Pose + sequence: string status: uint16 type: uint16 autoware_adapi_v1_msgs/msg/VelocityFactorArray: @@ -159,6 +183,10 @@ types: autoware_adapi_v1_msgs/srv/ClearRoute: res: status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/GetCooperationPolicies: + res: + policies: autoware_adapi_v1_msgs/msg/CooperationPolicy[] + status: autoware_adapi_v1_msgs/msg/ResponseStatus autoware_adapi_v1_msgs/srv/GetDoorLayout: res: doors: autoware_adapi_v1_msgs/msg/DoorLayout[] @@ -172,6 +200,16 @@ types: pose: geometry_msgs/msg/PoseWithCovarianceStamped[<=1] res: status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/SetCooperationCommands: + req: + commands: autoware_adapi_v1_msgs/msg/CooperationCommand[] + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/SetCooperationPolicies: + req: + policies: autoware_adapi_v1_msgs/msg/CooperationPolicy[] + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus autoware_adapi_v1_msgs/srv/SetDoorCommand: req: doors: autoware_adapi_v1_msgs/msg/DoorCommand[]