feat(ad-api): add door control (#415)

* add door command Signed-off-by: Takagi, Isamu <[email protected]> * add release status Signed-off-by: Takagi, Isamu <[email protected]> * Update docs/design/autoware-interfaces/templates/autoware-interface.jinja2 * update message name Signed-off-by: Takagi, Isamu <[email protected]> * feat: update description Signed-off-by: Takagi, Isamu <[email protected]> --------- Signed-off-by: Takagi, Isamu <[email protected]> Co-authored-by: Ryohsuke Mitsudome <[email protected]>
autowarefoundation · Jul 14, 2023 · 3c15827 · 3c15827
1 parent fe8519c
commit 3c15827
Show file tree

Hide file tree

Showing 14 changed files with 113 additions and 12 deletions.
diff --git a/docs/design/autoware-interfaces/ad-api/features/vehicle-doors.md b/docs/design/autoware-interfaces/ad-api/features/vehicle-doors.md
@@ -0,0 +1,38 @@
+# Vehicle doors
+
+## Related API
+
+- {{ link_ad_api('/api/vehicle/doors/layout') }}
+- {{ link_ad_api('/api/vehicle/doors/status') }}
+- {{ link_ad_api('/api/vehicle/doors/command') }}
+
+## Description
+
+This feature is available if the vehicle provides a software interface for the doors.
+It can be used to create user interfaces for passengers or to control sequences at bus stops.
+
+## Layout
+
+Each door in a vehicle is assigned an array index. This assignment is vehicle dependent.
+The layout API returns this information.
+The description field is a string to display in the user interface, etc.
+This is an arbitrary string and is not recommended to use for processing in applications.
+Use the roles field to know doors for getting on and off.
+Below is an example of the information returned by the layout API.
+
+| Index | Description | Roles           |
+| ----- | ----------- | --------------- |
+| 0     | front right | -               |
+| 1     | front left  | GET_ON          |
+| 2     | rear right  | GET_OFF         |
+| 3     | rear left   | GET_ON, GET_OFF |
+
+## Status
+
+The status API provides an array of door status. This array order is consistent with the layout API.
+
+## Control
+
+Use the command API to control doors.
+Unlike the status and layout APIs, array index do not correspond to doors.
+The command has a field to specify the target door index.
diff --git a/docs/design/autoware-interfaces/ad-api/features/vehicle-status.md b/docs/design/autoware-interfaces/ad-api/features/vehicle-status.md
@@ -5,8 +5,6 @@
 - {{ link_ad_api('/api/vehicle/kinematics') }}
 - {{ link_ad_api('/api/vehicle/status') }}
 - {{ link_ad_api('/api/vehicle/dimensions') }}
-- {{ link_ad_api('/api/vehicle/doors/layout') }}
-- {{ link_ad_api('/api/vehicle/doors/status') }}
 
 ## Kinematics
 
@@ -18,11 +16,6 @@ Also, using velocity and acceleration, applications can find vehicles that need
 This is the status provided by the vehicle. The indicators and steering are mainly used for visualization and remote control.
 The remaining energy can be also used for vehicle scheduling.
 
-## Doors
-
-This feature is available if the vehicle provides a software interface for the doors.
-It can be used to create user interfaces for passengers or to control sequences at bus stops.
-
 ## Dimensions
 
 The vehicle dimensions are used to know the actual distance between the vehicle and objects because the vehicle position in kinematics is the coordinates of the base link. This is necessary for visualization when supporting vehicles remotely.
diff --git a/docs/design/autoware-interfaces/ad-api/index.md b/docs/design/autoware-interfaces/ad-api/index.md
@@ -37,3 +37,4 @@ Service providers can combine these use cases to define user stories and check i
 - [Planning](./features/planning-factors.md)
 - [Fail-safe](./features/fail-safe.md)
 - [Vehicle status](./features/vehicle-status.md)
+- [Vehicle doors](./features/vehicle-doors.md)
diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/command.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/command.md
@@ -0,0 +1,20 @@
+---
+title: /api/vehicle/doors/command
+status: not released
+method: function call
+type:
+  name: autoware_adapi_v1_msgs/srv/SetDoorCommand
+  req:
+    - name: doors.index
+      text: The index of the target door.
+    - name: doors.command
+      text: The command for the target door.
+  res:
+    - name: status
+      text: response status
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Set the door command. This API is only available if the vehicle supports software door control.
+{% endblock %}
diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/layout.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/layout.md
@@ -15,5 +15,5 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Get the door layout. It is an array of pose for each door. The array index corresponds to the door status.
+Get the door layout. It is an array of roles and descriptions for each door.
 {% endblock %}
diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/status.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/status.md
@@ -11,5 +11,5 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Publish door status in array according to the door location information that received from vehicle info service.
+The status of each door such as opened or closed.
 {% endblock %}
diff --git a/docs/design/autoware-interfaces/ad-api/list/index.md b/docs/design/autoware-interfaces/ad-api/list/index.md
@@ -21,6 +21,7 @@
 - [/api/routing/set_route_points](./api/routing/set_route_points.md)
 - [/api/routing/state](./api/routing/state.md)
 - [/api/vehicle/dimensions](./api/vehicle/dimensions.md)
+- [/api/vehicle/doors/command](./api/vehicle/doors/command.md)
 - [/api/vehicle/doors/layout](./api/vehicle/doors/layout.md)
 - [/api/vehicle/doors/status](./api/vehicle/doors/status.md)
 - [/api/vehicle/kinematics](./api/vehicle/kinematics.md)

diff --git a/...sign/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorCommand.md b/...sign/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorCommand.md
@@ -0,0 +1,19 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/DoorCommand
+used:
+  - autoware_adapi_v1_msgs/srv/SetDoorCommand
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+uint8 OPEN = 1
+uint8 CLOSE = 2
+
+uint32 index
+uint8 command
+```
+
+{% endblock %}
diff --git a/...esign/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatus.md b/...esign/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatus.md
@@ -9,7 +9,6 @@ used:
 {% block definition %}
 
 ```txt
-# constants for door status
 uint8 UNKNOWN = 0
 uint8 NOT_AVAILABLE = 1
 uint8 OPENED = 2

diff --git a/...n/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md b/...n/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md
@@ -8,6 +8,7 @@ used:
   - autoware_adapi_v1_msgs/srv/GetDoorLayout
   - autoware_adapi_v1_msgs/srv/GetVehicleDimensions
   - autoware_adapi_v1_msgs/srv/InitializeLocalization
+  - autoware_adapi_v1_msgs/srv/SetDoorCommand
   - autoware_adapi_v1_msgs/srv/SetRoute
   - autoware_adapi_v1_msgs/srv/SetRoutePoints
 ---

diff --git a/...gn/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetDoorLayout.md b/...gn/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetDoorLayout.md
@@ -12,7 +12,7 @@ uses:
 ```txt
 ---
 autoware_adapi_v1_msgs/ResponseStatus status
-autoware_adapi_v1_msgs/DoorLayout doors
+autoware_adapi_v1_msgs/DoorLayout[] doors
 ```
 
 {% endblock %}
diff --git a/...n/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetDoorCommand.md b/...n/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetDoorCommand.md
@@ -0,0 +1,18 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/srv/SetDoorCommand
+uses:
+  - autoware_adapi_v1_msgs/msg/DoorCommand
+  - autoware_adapi_v1_msgs/msg/ResponseStatus
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+autoware_adapi_v1_msgs/DoorCommand[] doors
+---
+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
@@ -1,5 +1,6 @@
 # Types of Autoware AD API
 
+- [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)
 - [autoware_adapi_v1_msgs/msg/DoorStatusArray](./autoware_adapi_v1_msgs/msg/DoorStatusArray.md)
@@ -30,6 +31,7 @@
 - [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/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)
 - [autoware_adapi_version_msgs/srv/InterfaceVersion](./autoware_adapi_version_msgs/srv/InterfaceVersion.md)
diff --git a/yaml/autoware-interfaces.yaml b/yaml/autoware-interfaces.yaml
@@ -1,4 +1,8 @@
 types:
+  autoware_adapi_v1_msgs/msg/DoorCommand:
+    msg:
+      command: uint8
+      index: uint32
   autoware_adapi_v1_msgs/msg/DoorLayout:
     msg:
       description: string
@@ -131,7 +135,7 @@ types:
       status: autoware_adapi_v1_msgs/msg/ResponseStatus
   autoware_adapi_v1_msgs/srv/GetDoorLayout:
     res:
-      doors: autoware_adapi_v1_msgs/msg/DoorLayout
+      doors: autoware_adapi_v1_msgs/msg/DoorLayout[]
       status: autoware_adapi_v1_msgs/msg/ResponseStatus
   autoware_adapi_v1_msgs/srv/GetVehicleDimensions:
     res:
@@ -142,6 +146,11 @@ types:
       pose: geometry_msgs/msg/PoseWithCovarianceStamped[<=1]
     res:
       status: autoware_adapi_v1_msgs/msg/ResponseStatus
+  autoware_adapi_v1_msgs/srv/SetDoorCommand:
+    req:
+      doors: autoware_adapi_v1_msgs/msg/DoorCommand[]
+    res:
+      status: autoware_adapi_v1_msgs/msg/ResponseStatus
   autoware_adapi_v1_msgs/srv/SetRoute:
     req:
       goal: geometry_msgs/msg/Pose