docs(ad-api): add use cases of vehicle status (autowarefoundation#381)

* init vehicle status

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix spelling error

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* remove old file

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix spelling error

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix dead link

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* update vehicle message

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* change vehicle motion

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* feat(ad-api): add vehicle information api

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* fix msgs

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* update geo position

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix typo

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* change naming

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* feat: add door group

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update message

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix naming

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix typo

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* update geographic_msgs

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* docs(ad-api): add use cases of vehicle status

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* feat: remove old files

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* feat: use template

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* apply template

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update message name

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update vehicle status feature

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* fix link

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update door layout

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

---------

Signed-off-by: tkhmy <tkh.my.p@gmail.com>
Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>
Co-authored-by: tkhmy <tkh.my.p@gmail.com>
Signed-off-by: guiping meng <alan.meng@autocore.ai>

docs/design/autoware-interfaces/ad-api/features/planning-factors.md

@@ -0,0 +1,5 @@
+# Planning factors
+
+!!! warning
+
+    Under Construction

docs/design/autoware-interfaces/ad-api/features/vehicle-status.md

@@ -0,0 +1,28 @@
+# Vehicle status
+
+## Related API
+
+- {{ 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
+
+This is an estimate of the vehicle kinematics. The vehicle position is necessary for applications to schedule dispatches.
+Also, using velocity and acceleration, applications can find vehicles that need operator assistance, such as stuck or brake suddenly.
+
+## Status
+
+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.

docs/design/autoware-interfaces/ad-api/list/api/vehicle/dimensions.md

@@ -0,0 +1,16 @@
+---
+title: /api/vehicle/dimensions
+method: function call
+type:
+  name: autoware_adapi_v1_msgs/srv/GetVehicleDimensions
+  res:
+    - name: status
+      text: response status
+    - name: dimensions
+      text: vehicle dimensions
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Get the vehicle dimensions. See [here](../../../../components/vehicle-dimensions.md) for the definition of each value.
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/layout.md

@@ -0,0 +1,18 @@
+---
+title: /api/vehicle/doors/layout
+method: function call
+type:
+  name: autoware_adapi_v1_msgs/srv/GetDoorLayout
+  res:
+    - name: status
+      text: response status
+    - name: doors.roles
+      text: The roles of the door in the service the vehicle provides.
+    - name: doors.description
+      text: The description of the door for display in the interface.
+---
+
+{% 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.
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/status.md

@@ -0,0 +1,14 @@
+---
+title: /api/vehicle/doors/status
+method: notification
+type:
+  name: autoware_adapi_v1_msgs/msg/DoorStatusArray
+  msg:
+    - name: doors.status
+      text: current door status
+---
+
+{% 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.
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/vehicle/kinematics.md

@@ -0,0 +1,20 @@
+---
+title: /api/vehicle/kinematics
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/VehicleKinematics
+  msg:
+    - name: geographic_pose
+      text: The longitude and latitude of the vehicle. If the map uses local coordinates, it will not be available.
+    - name: pose
+      text: The pose with covariance from the base link.
+    - name: twist
+      text: Vehicle current twist with covariance.
+    - name: accel
+      text: Vehicle current acceleration with covariance.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Publish vehicle kinematics.
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/vehicle/status.md

@@ -0,0 +1,22 @@
+---
+title: /api/vehicle/status
+method: notification
+type:
+  name: autoware_adapi_v1_msgs/msg/VehicleStatus
+  msg:
+    - name: gear
+      text: Gear status.
+    - name: turn_indicators
+      text: Turn indicators status, only either left or right will be enabled.
+    - name: hazard_lights
+      text: Hazard lights status.
+    - name: steering_tire_angle
+      text: Vehicle current tire angle in radian.
+    - name: energy_percentage
+      text: Battery percentage or fuel percentage, it will depends on the vehicle.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Publish vehicle state information.
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorLayout.md

@@ -0,0 +1,19 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/DoorLayout
+used:
+  - autoware_adapi_v1_msgs/srv/GetDoorLayout
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+uint8 GET_ON = 1
+uint8 GET_OFF = 2
+
+uint8[] roles
+string description
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatus.md

@@ -0,0 +1,23 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/DoorStatus
+used:
+  - autoware_adapi_v1_msgs/msg/DoorStatusArray
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+# constants for door status
+uint8 UNKNOWN = 0
+uint8 NOT_AVAILABLE = 1
+uint8 OPENED = 2
+uint8 CLOSED = 3
+uint8 OPENING = 4
+uint8 CLOSING = 5
+
+uint8 status
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatusArray.md

@@ -0,0 +1,16 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/DoorStatusArray
+uses:
+  - autoware_adapi_v1_msgs/msg/DoorStatus
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+builtin_interfaces/Time stamp
+autoware_adapi_v1_msgs/DoorStatus[] doors
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/Gear.md

@@ -0,0 +1,23 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/Gear
+used:
+  - autoware_adapi_v1_msgs/msg/VehicleStatus
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+# constants
+uint8 UNKNOWN = 0
+uint8 NEUTRAL = 1
+uint8 DRIVE = 2
+uint8 REVERSE = 3
+uint8 PARK = 4
+uint8 LOW = 5
+
+uint8 status
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/HazardLights.md

@@ -0,0 +1,20 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/HazardLights
+used:
+  - autoware_adapi_v1_msgs/msg/VehicleStatus
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+# constants
+uint8 UNKNOWN = 0
+uint8 DISABLE = 1
+uint8 ENABLE = 2
+
+uint8 status
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md

@@ -5,6 +5,8 @@ used:
   - autoware_adapi_v1_msgs/srv/AcceptStart
   - autoware_adapi_v1_msgs/srv/ChangeOperationMode
   - autoware_adapi_v1_msgs/srv/ClearRoute
+  - autoware_adapi_v1_msgs/srv/GetDoorLayout
+  - autoware_adapi_v1_msgs/srv/GetVehicleDimensions
   - autoware_adapi_v1_msgs/srv/InitializeLocalization
   - autoware_adapi_v1_msgs/srv/SetRoute
   - autoware_adapi_v1_msgs/srv/SetRoutePoints

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/TurnIndicators.md

@@ -0,0 +1,21 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/TurnIndicators
+used:
+  - autoware_adapi_v1_msgs/msg/VehicleStatus
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+# constants
+uint8 UNKNOWN = 0
+uint8 DISABLE = 1
+uint8 LEFT = 2
+uint8 RIGHT = 3
+
+uint8 status
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleDimensions.md

@@ -0,0 +1,24 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/VehicleDimensions
+used:
+  - autoware_adapi_v1_msgs/srv/GetVehicleDimensions
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+float32 wheel_radius
+float32 wheel_width
+float32 wheel_base
+float32 wheel_tread
+float32 front_overhang
+float32 rear_overhang
+float32 left_overhang
+float32 right_overhang
+float32 height
+geometry_msgs/Polygon footprint
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleKinematics.md

@@ -0,0 +1,21 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/VehicleKinematics
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+# Geographic point, using the WGS 84 reference ellipsoid.
+# Currently only support conversion from single MGRS Grid code or UTM
+# If the vector map do not contain correct MGRS Grid code or UTM, this data will be not valid
+geographic_msgs/GeoPointStamped geographic_pose
+
+# Local coordinate from the autoware
+geometry_msgs/PoseWithCovarianceStamped pose
+geometry_msgs/TwistWithCovarianceStamped twist
+geometry_msgs/AccelWithCovarianceStamped accel
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleStatus.md

@@ -0,0 +1,22 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/msg/VehicleStatus
+uses:
+  - autoware_adapi_v1_msgs/msg/Gear
+  - autoware_adapi_v1_msgs/msg/HazardLights
+  - autoware_adapi_v1_msgs/msg/TurnIndicators
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+builtin_interfaces/Time stamp
+autoware_adapi_v1_msgs/Gear gear
+autoware_adapi_v1_msgs/TurnIndicators turn_indicators
+autoware_adapi_v1_msgs/HazardLights hazard_lights
+float64 steering_tire_angle
+float32 energy_percentage  # Battery percentage or fuel percentage, it will depends on the vehicle.
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactor.md

@@ -29,6 +29,7 @@ uint16 SIDEWALK = 13
 uint16 LANE_CHANGE = 14
 uint16 AVOIDANCE = 15
 uint16 EMERGENCY_STOP_OPERATION = 16
+uint16 NO_DRIVABLE_LANE = 17
 
 # constants for status
 uint16 APPROACHING = 1

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetDoorLayout.md

@@ -0,0 +1,18 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/srv/GetDoorLayout
+uses:
+  - autoware_adapi_v1_msgs/msg/DoorLayout
+  - 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/DoorLayout doors
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetVehicleDimensions.md

@@ -0,0 +1,18 @@
+---
+# This file is generated by tools/autoware-interfaces/generate.py
+title: autoware_adapi_v1_msgs/srv/GetVehicleDimensions
+uses:
+  - autoware_adapi_v1_msgs/msg/ResponseStatus
+  - autoware_adapi_v1_msgs/msg/VehicleDimensions
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}
+{% block definition %}
+
+```txt
+---
+autoware_adapi_v1_msgs/ResponseStatus status
+autoware_adapi_v1_msgs/VehicleDimensions dimensions
+```
+
+{% endblock %}

docs/design/autoware-interfaces/ad-api/use-cases/index.md

@@ -19,3 +19,9 @@ Service providers can combine these use cases to define user stories and check i
 - [Change the operation mode](change-operation-mode.md)
 - [Drive to the designated position](drive-designated-position.md)
 - [Get on and get off](get-on-off.md)
+- [Vehicle monitoring](./vehicle-monitoring.md)
+- [Request to cooperate](./request-to-cooperate.md)
+
+## Features
+
+- [Vehicle status](../features/vehicle-status.md)