feat(ad-api): manual control

docs/design/autoware-interfaces/ad-api/features/manual-control.md

@@ -0,0 +1,63 @@
+# Manual control
+
+## Related API
+
+- {{ link_ad_api('/api/remote/control_mode/list') }}
+- {{ link_ad_api('/api/remote/control_mode/select') }}
+- {{ link_ad_api('/api/remote/control_mode/status') }}
+- {{ link_ad_api('/api/remote/operator/status') }}
+- {{ link_ad_api('/api/remote/command/pedals') }}
+- {{ link_ad_api('/api/remote/command/acceleration') }}
+- {{ link_ad_api('/api/remote/command/velocity') }}
+- {{ link_ad_api('/api/remote/command/steering') }}
+- {{ link_ad_api('/api/remote/command/gear') }}
+- {{ link_ad_api('/api/remote/command/turn_indicators') }}
+- {{ link_ad_api('/api/remote/command/hazard_lights') }}
+- {{ link_ad_api('/api/local/control_mode/list') }}
+- {{ link_ad_api('/api/local/control_mode/select') }}
+- {{ link_ad_api('/api/local/control_mode/status') }}
+- {{ link_ad_api('/api/local/operator/status') }}
+- {{ link_ad_api('/api/local/command/pedals') }}
+- {{ link_ad_api('/api/local/command/acceleration') }}
+- {{ link_ad_api('/api/local/command/velocity') }}
+- {{ link_ad_api('/api/local/command/steering') }}
+- {{ link_ad_api('/api/local/command/gear') }}
+- {{ link_ad_api('/api/local/command/turn_indicators') }}
+- {{ link_ad_api('/api/local/command/hazard_lights') }}
+
+## Description
+
+This API is used to manually control the vehicle, and provides the same interface for different operators: remote and local.
+For example, the local operator controls a vehicle without a driver's seat using a joystick, while the remote operator provides remote support when problems occur with autonomous driving.
+The command sent will be used when [operation mode](./operation_mode.md) is remote or local.
+
+## Operator status
+
+The application needs to determine whether the operator is able to drive and send that information via the operator status API.
+If the operator is unable to continue driving during manual operation, Autoware will perform MRM to bring the vehicle to a safe state.
+For level 3 and below, the operator status is referenced even during autonomous driving.
+
+## Control mode
+
+Since there are multiple ways to control a vehicle, such as pedals or acceleration, the application must first select a control mode.
+
+| Mode         | Description                                                                |
+| ------------ | -------------------------------------------------------------------------- |
+| disabled     | This is the initial mode. When selected, all command APIs are unavailable. |
+| pedals       | This mode provides longitudinal control using the pedals.                  |
+| acceleration | This mode provides longitudinal control using the target acceleration.     |
+| velocity     | This mode provides longitudinal control using the target velocity.         |
+
+## Commands
+
+The commands available in each mode are as follows.
+
+| Command         | disabled |  pedals  | acceleration | velocity |
+| --------------- | :------: | :------: | :----------: | :------: |
+| pedals          |    -     | ✓ |      -       |    -     |
+| acceleration    |    -     |    -     |   ✓   |    -     |
+| velocity        |    -     |    -     |      -       | ✓ |
+| steering        |    -     | ✓ |   ✓   | ✓ |
+| gear            |    -     | ✓ |   ✓   | ✓ |
+| turn_indicators |    -     | ✓ |   ✓   | ✓ |
+| hazard_lights   |    -     | ✓ |   ✓   | ✓ |

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

@@ -27,6 +27,7 @@ Service providers can combine these use cases to define user stories and check i
 - [Vehicle monitoring](./use-cases/vehicle-monitoring.md)
 - [Vehicle operation](./use-cases/vehicle-operation.md)
 - [System monitoring](./use-cases/system-monitoring.md)
+- [Manual control](./use-cases/manual-control/index.md)
 
 ## Features
 
@@ -43,3 +44,4 @@ Service providers can combine these use cases to define user stories and check i
 - [Cooperation](./features/cooperation.md)
 - [Heartbeat](./features/heartbeat.md)
 - [Diagnostics](./features/diagnostics.md)
+- [Manual control](./features/manual-control.md)

docs/design/autoware-interfaces/ad-api/list/api/local/command/acceleration.md

@@ -0,0 +1,18 @@
+---
+title: /api/local/command/acceleration
+status: not released
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/AccelerationCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: acceleration
+      text: Target acceleration [m/s^2].
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends acceleration command used in local operation mode.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/local/command/gear.md

@@ -0,0 +1,18 @@
+---
+title: /api/local/command/gear
+status: not released
+method: notification
+type:
+  name: autoware_adapi_v1_msgs/msg/GearCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: command
+      text: Target gear status.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends gear command used in local operation mode.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/local/command/hazard_lights.md

@@ -0,0 +1,18 @@
+---
+title: /api/local/command/hazard_lights
+status: not released
+method: notification
+type:
+  name: autoware_adapi_v1_msgs/msg/HazardLightsCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: command
+      text: Target hazard lights status.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends hazard lights command used in local operation mode.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/local/command/pedals.md

@@ -0,0 +1,20 @@
+---
+title: /api/local/command/pedals
+status: not released
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/PedalsCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: accelerator
+      text: Target accelerator pedal ratio.
+    - name: brake
+      text: Target brake pedal ratio.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends pedals command used in local operation mode. The pedal value is the ratio with the maximum pedal depression being 1.0.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/local/command/steering.md

@@ -0,0 +1,18 @@
+---
+title: /api/local/command/steering
+status: not released
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/SteeringCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: steering_tire_angle
+      text: Target steering tire angle [rad].
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Send steering command to this API.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/local/command/turn_indicators.md

@@ -0,0 +1,18 @@
+---
+title: /api/local/command/turn_indicators
+status: not released
+method: notification
+type:
+  name: autoware_adapi_v1_msgs/msg/TurnIndicatorsCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: command
+      text: Target turn indicators status.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends turn indicators command used in local operation mode.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/local/command/velocity.md

@@ -0,0 +1,18 @@
+---
+title: /api/local/command/velocity
+status: not released
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/VelocityCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: velocity
+      text: Target velocity [m/s].
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends velocity command used in local operation mode.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/local/control_mode/list.md

@@ -0,0 +1,18 @@
+---
+title: /api/local/control_mode/list
+status: not released
+method: function call
+type:
+  name: autoware_adapi_v1_msgs/srv/ListManualControlMode
+  res:
+    - name: status
+      text: response status
+    - name: modes
+      text: List of available modes.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+List the available manual control modes as described in [manual control](../../../../features/manual-control.md).
+The disabled mode is not included in the available modes.
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/local/control_mode/select.md

@@ -0,0 +1,19 @@
+---
+title: /api/local/control_mode/select
+status: not released
+method: function call
+type:
+  name: autoware_adapi_v1_msgs/srv/SelectManualControlMode
+  req:
+    - name: mode
+      text: The manual control mode to be used.
+  res:
+    - name: status
+      text: response status
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Selects the manual control mode as described in [manual control](../../../../features/manual-control.md).
+This API fails while [operation mode](../../../../features/operation_mode.md) is local.
+{% endblock %}

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

@@ -0,0 +1,15 @@
+---
+title: /api/local/control_mode/status
+status: not released
+method: notification
+type:
+  name: autoware_adapi_v1_msgs/msg/ManualControlModeStatus
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Get the current manual operation mode.
+{% endblock %}

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

@@ -0,0 +1,18 @@
+---
+title: /api/local/operator/status
+status: not released
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/ManualOperatorStatus
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: ready
+      text: Whether the operator is able to continue driving.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+The application needs to determine whether the operator is able to drive and send that information via this API.
+For details, see the [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/remote/command/acceleration.md

@@ -0,0 +1,18 @@
+---
+title: /api/remote/command/acceleration
+status: not released
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/AccelerationCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: acceleration
+      text: Target acceleration [m/s^2].
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends acceleration command used in remote operation mode.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/remote/command/gear.md

@@ -0,0 +1,18 @@
+---
+title: /api/remote/command/gear
+status: not released
+method: notification
+type:
+  name: autoware_adapi_v1_msgs/msg/GearCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: command
+      text: Target gear status.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends gear command used in remote operation mode.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/remote/command/hazard_lights.md

@@ -0,0 +1,18 @@
+---
+title: /api/remote/command/hazard_lights
+status: not released
+method: notification
+type:
+  name: autoware_adapi_v1_msgs/msg/HazardLightsCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: command
+      text: Target hazard lights status.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends hazard lights command used in remote operation mode.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/remote/command/pedals.md

@@ -0,0 +1,20 @@
+---
+title: /api/remote/command/pedals
+status: not released
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/PedalsCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: accelerator
+      text: Target accelerator pedal ratio.
+    - name: brake
+      text: Target brake pedal ratio.
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Sends pedals command used in remote operation mode. The pedal value is the ratio with the maximum pedal depression being 1.0.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/remote/command/steering.md

@@ -0,0 +1,18 @@
+---
+title: /api/remote/command/steering
+status: not released
+method: realtime stream
+type:
+  name: autoware_adapi_v1_msgs/msg/SteeringCommand
+  msg:
+    - name: stamp
+      text: Timestamp when this message was sent.
+    - name: steering_tire_angle
+      text: Target steering tire angle [rad].
+---
+
+{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
+{% block description %}
+Send steering command to this API.
+To use this API, select the corresponding mode as described in [manual control](../../../../features/manual-control.md).
+{% endblock %}