From 1dced43798b7c307bf281641018ef37ba48acda3 Mon Sep 17 00:00:00 2001 From: "Takagi, Isamu" Date: Fri, 13 Jun 2025 20:14:54 +0900 Subject: [PATCH 1/3] feat(ad-api): add mrm description api Signed-off-by: Takagi, Isamu --- .../ad-api/features/fail-safe.md | 7 + .../fail-safe/architecture.drawio.svg | 658 +++++++++++++----- .../list/api/fail_safe/mrm_description.md | 23 + .../autoware-interfaces/ad-api/list/index.md | 1 + .../msg/MrmDescription.md | 17 + .../autoware_adapi_v1_msgs/msg/MrmState.md | 2 +- .../msg/ResponseStatus.md | 1 + .../srv/ListMrmDescription.md | 18 + .../autoware-interfaces/ad-api/types/index.md | 2 + yaml/autoware-interfaces.yaml | 10 + 10 files changed, 561 insertions(+), 178 deletions(-) create mode 100644 docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_description.md create mode 100644 docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmDescription.md create mode 100644 docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ListMrmDescription.md diff --git a/docs/design/autoware-interfaces/ad-api/features/fail-safe.md b/docs/design/autoware-interfaces/ad-api/features/fail-safe.md index 9dc5d84e75e..42d42dfc671 100644 --- a/docs/design/autoware-interfaces/ad-api/features/fail-safe.md +++ b/docs/design/autoware-interfaces/ad-api/features/fail-safe.md @@ -4,6 +4,7 @@ - {{ link_ad_api('/api/fail_safe/rti_state') }} - {{ link_ad_api('/api/fail_safe/mrm_state') }} +- {{ link_ad_api('/api/fail_safe/mrm_description') }} - {{ link_ad_api('/api/fail_safe/mrm_request/send') }} - {{ link_ad_api('/api/fail_safe/mrm_request/list') }} @@ -36,6 +37,7 @@ This state also provides success or failure of the operation. Generally, MRM wil | SUCCEEDED | MRM succeeded. The vehicle is in a safe condition. | | FAILED | MRM failed. The vehicle is still in an unsafe condition. | +**[v1.9.0] Deprecated: Use the MRM behavior ID instead of following constants.** There is a dependency between MRM behaviors. For example, it switches from a comfortable stop to a emergency stop, but not the other way around. This is service dependent. Autoware supports the following transitions by default. @@ -48,6 +50,11 @@ This is service dependent. Autoware supports the following transitions by defaul | EMERGENCY_STOP | The vehicle will stop immediately with as much deceleration as possible. | | PULL_OVER | The vehicle will stop after moving to the side of the road. | +## MRM description + +Autoware supports various MRM implementation to provide appropriate behavior for each use case. +Therefore, use this API when detailed information about MRM behavior is required. The MRM behavior ID listed by this API is used in MRM state API. + ## MRM request MRM request is a feature that triggers MRM from an application, and is mainly used when the application wants to transition the vehicle to a safe state by detecting an abnormality. When an MRM request is sent, Autoware attempts to operate the MRM. To distinguish requests from multiple applications, an MRM request must include a user name as an identifier. diff --git a/docs/design/autoware-interfaces/ad-api/features/fail-safe/architecture.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/fail-safe/architecture.drawio.svg index 58ddc1771c0..47e9c818d70 100644 --- a/docs/design/autoware-interfaces/ad-api/features/fail-safe/architecture.drawio.svg +++ b/docs/design/autoware-interfaces/ad-api/features/fail-safe/architecture.drawio.svg @@ -1,212 +1,516 @@ - - - - - - - - -
-
-
- Autoware Planner + + + + + + + + + + + + + + + +
+
+
+ Autoware Planner +
-
- - Autoware Planner - - - - - - -
-
-
- Fail-safe Gate + + Autoware Planner + + + + + + + + + + +
+
+
+ Command Selector +
-
- - Fail-safe Gate - - - - - - - - -
-
-
- MRM Selector + + Command Selector + + + + + + + + + + + + + + +
+
+
+ Autonomous Command +
-
- - MRM Selector - - - - - - - - -
-
-
- Operation Mode Selector + + Autonomous Command + + + + + + + + + + + + + + +
+
+
+ Other Mode +
Planners
+
-
- - Operation Mode Selector - - - - - - - - -
-
-
- Other Modes + + Other Mode... + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ Fail-safe +
+ Module +
-
- - Other Modes - - - - - - - - - - - - - - -
-
-
- Fail-safe -
- Module + + Fail-safe... + + + + + + + + + + +
+
+
+ select +
-
- - Fail-safe... - - - - - - -
-
-
- state + + select + + + + + + + + + + +
+
+
+ change mode +
-
- - state - - - - - - -
-
-
- behavior + + change mode + + + + + + + + + + + + + + + + + +
+
+
+ Independent +
+ MRM Planner +
-
- - behavior - - - - - - -
-
-
- change mode + + Independent... + + + + + + + + + + + + + + +
+
+
+ MRM commands +
-
- - change mode - - - - - - - - -
-
-
- Independent -
- MRM Planner + + MRM commands + + + + + + + + + + + + + + +
+
+
+ MRM command +
+
+
+ + MRM command + + + + + + + + + + + + + + +
+
+
+ Other Mode +
+ Commands +
+
-
- - Independent... - + + Other Mode... + + - - Viewer does not support full SVG 1.1 + + Text is not SVG - cannot display diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_description.md b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_description.md new file mode 100644 index 00000000000..cb37413079f --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_description.md @@ -0,0 +1,23 @@ +--- +title: /api/fail_safe/mrm_description +status: not released +method: function call +type: + name: autoware_adapi_v1_msgs/srv/ListMrmDescription + req: + - name: descriptions.behavior + text: The behavior ID of the MRM. + - name: descriptions.name + text: The name of the MRM. + - name: descriptions.description + text: The description of the MRM. + res: + - name: status + text: response status +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the list of MRM description. +For details, see the [fail-safe](../../../../features/fail-safe.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/index.md b/docs/design/autoware-interfaces/ad-api/list/index.md index 52ec9e13d82..4c1d13292d6 100644 --- a/docs/design/autoware-interfaces/ad-api/list/index.md +++ b/docs/design/autoware-interfaces/ad-api/list/index.md @@ -2,6 +2,7 @@ | API | Release | Method | | ------------------------------------------------------------------------------------------------ | ------------ | --------------- | +| [/api/fail_safe/mrm_description](./api/fail_safe/mrm_description.md) | not released | function call | | [/api/fail_safe/mrm_request/list](./api/fail_safe/mrm_request/list.md) | not released | notification | | [/api/fail_safe/mrm_request/send](./api/fail_safe/mrm_request/send.md) | not released | function call | | [/api/fail_safe/mrm_state](./api/fail_safe/mrm_state.md) | v1.1.0 | notification | diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmDescription.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmDescription.md new file mode 100644 index 00000000000..58c871328cf --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmDescription.md @@ -0,0 +1,17 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/MrmDescription +used: + - autoware_adapi_v1_msgs/srv/ListMrmDescription +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint16 behavior +string name +string description +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmState.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmState.md index 79a62cc8cd3..6c14c36de0c 100644 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmState.md +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmState.md @@ -18,7 +18,7 @@ uint16 MRM_OPERATING = 2 uint16 MRM_SUCCEEDED = 3 uint16 MRM_FAILED = 4 -# For behavior +# For behavior. Deprecated: use description API. uint16 NONE = 1 uint16 EMERGENCY_STOP = 2 uint16 COMFORTABLE_STOP = 3 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 f93d251274c..4a2035d699b 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 @@ -11,6 +11,7 @@ used: - autoware_adapi_v1_msgs/srv/GetVehicleSpecs - autoware_adapi_v1_msgs/srv/InitializeLocalization - autoware_adapi_v1_msgs/srv/ListManualControlMode + - autoware_adapi_v1_msgs/srv/ListMrmDescription - autoware_adapi_v1_msgs/srv/SelectManualControlMode - autoware_adapi_v1_msgs/srv/SendMrmRequest - autoware_adapi_v1_msgs/srv/SetCooperationCommands diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ListMrmDescription.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ListMrmDescription.md new file mode 100644 index 00000000000..adca00dbbff --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ListMrmDescription.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/ListMrmDescription +uses: + - autoware_adapi_v1_msgs/msg/MrmDescription + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +autoware_adapi_v1_msgs/MrmDescription[] descriptions +--- +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 0943f687cca..e9181648406 100644 --- a/docs/design/autoware-interfaces/ad-api/types/index.md +++ b/docs/design/autoware-interfaces/ad-api/types/index.md @@ -28,6 +28,7 @@ - [autoware_adapi_v1_msgs/msg/ManualControlModeStatus](./autoware_adapi_v1_msgs/msg/ManualControlModeStatus.md) - [autoware_adapi_v1_msgs/msg/ManualOperatorHeartbeat](./autoware_adapi_v1_msgs/msg/ManualOperatorHeartbeat.md) - [autoware_adapi_v1_msgs/msg/MotionState](./autoware_adapi_v1_msgs/msg/MotionState.md) +- [autoware_adapi_v1_msgs/msg/MrmDescription](./autoware_adapi_v1_msgs/msg/MrmDescription.md) - [autoware_adapi_v1_msgs/msg/MrmRequest](./autoware_adapi_v1_msgs/msg/MrmRequest.md) - [autoware_adapi_v1_msgs/msg/MrmRequestList](./autoware_adapi_v1_msgs/msg/MrmRequestList.md) - [autoware_adapi_v1_msgs/msg/MrmState](./autoware_adapi_v1_msgs/msg/MrmState.md) @@ -64,6 +65,7 @@ - [autoware_adapi_v1_msgs/srv/GetVehicleSpecs](./autoware_adapi_v1_msgs/srv/GetVehicleSpecs.md) - [autoware_adapi_v1_msgs/srv/InitializeLocalization](./autoware_adapi_v1_msgs/srv/InitializeLocalization.md) - [autoware_adapi_v1_msgs/srv/ListManualControlMode](./autoware_adapi_v1_msgs/srv/ListManualControlMode.md) +- [autoware_adapi_v1_msgs/srv/ListMrmDescription](./autoware_adapi_v1_msgs/srv/ListMrmDescription.md) - [autoware_adapi_v1_msgs/srv/SelectManualControlMode](./autoware_adapi_v1_msgs/srv/SelectManualControlMode.md) - [autoware_adapi_v1_msgs/srv/SendMrmRequest](./autoware_adapi_v1_msgs/srv/SendMrmRequest.md) - [autoware_adapi_v1_msgs/srv/SetCooperationCommands](./autoware_adapi_v1_msgs/srv/SetCooperationCommands.md) diff --git a/yaml/autoware-interfaces.yaml b/yaml/autoware-interfaces.yaml index eb55e7f532f..51c7bfb63e7 100644 --- a/yaml/autoware-interfaces.yaml +++ b/yaml/autoware-interfaces.yaml @@ -116,6 +116,11 @@ types: msg: stamp: builtin_interfaces/msg/Time state: uint16 + autoware_adapi_v1_msgs/msg/MrmDescription: + msg: + behavior: uint16 + description: string + name: string autoware_adapi_v1_msgs/msg/MrmRequest: msg: sender: string @@ -291,6 +296,11 @@ types: res: modes: autoware_adapi_v1_msgs/msg/ManualControlMode[] status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/ListMrmDescription: + req: + descriptions: autoware_adapi_v1_msgs/msg/MrmDescription[] + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus autoware_adapi_v1_msgs/srv/SelectManualControlMode: req: mode: autoware_adapi_v1_msgs/msg/ManualControlMode From 5b2ee6b8b6699d21b8ecb62bcb3b8ea8427b87e5 Mon Sep 17 00:00:00 2001 From: "Takagi, Isamu" Date: Fri, 13 Jun 2025 20:18:40 +0900 Subject: [PATCH 2/3] fix deploy-docs Signed-off-by: Takagi, Isamu --- .../ad-api/list/api/fail_safe/mrm_description.md | 2 +- .../ad-api/list/api/fail_safe/mrm_request/list.md | 2 +- .../ad-api/list/api/fail_safe/mrm_request/send.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_description.md b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_description.md index cb37413079f..3ee375032ca 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_description.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_description.md @@ -19,5 +19,5 @@ type: {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} {% block description %} Get the list of MRM description. -For details, see the [fail-safe](../../../../features/fail-safe.md). +For details, see the [fail-safe](../../../features/fail-safe.md). {% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_request/list.md b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_request/list.md index f72103b7324..079a9803a72 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_request/list.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_request/list.md @@ -5,7 +5,7 @@ method: notification type: name: autoware_adapi_v1_msgs/msg/MrmRequestList msg: - - name: requests.user + - name: requests.sender text: The sender name of the MRM request. - name: requests.strategy text: The strategy of the MRM request. diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_request/send.md b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_request/send.md index 68ef0936880..a1903ed4807 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_request/send.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_request/send.md @@ -5,7 +5,7 @@ method: function call type: name: autoware_adapi_v1_msgs/srv/SendMrmRequest req: - - name: request.user + - name: request.sender text: The sender name of the MRM request. - name: request.strategy text: The strategy of the MRM request. From 056c75c3f167a2385a6b5ead6e03866e6749d4b3 Mon Sep 17 00:00:00 2001 From: "Takagi, Isamu" Date: Fri, 13 Jun 2025 20:21:38 +0900 Subject: [PATCH 3/3] modify order Signed-off-by: Takagi, Isamu --- .../autoware-interfaces/ad-api/features/fail-safe.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/design/autoware-interfaces/ad-api/features/fail-safe.md b/docs/design/autoware-interfaces/ad-api/features/fail-safe.md index 42d42dfc671..48005d100bb 100644 --- a/docs/design/autoware-interfaces/ad-api/features/fail-safe.md +++ b/docs/design/autoware-interfaces/ad-api/features/fail-safe.md @@ -3,8 +3,8 @@ ## Related API - {{ link_ad_api('/api/fail_safe/rti_state') }} -- {{ link_ad_api('/api/fail_safe/mrm_state') }} - {{ link_ad_api('/api/fail_safe/mrm_description') }} +- {{ link_ad_api('/api/fail_safe/mrm_state') }} - {{ link_ad_api('/api/fail_safe/mrm_request/send') }} - {{ link_ad_api('/api/fail_safe/mrm_request/list') }} @@ -23,6 +23,11 @@ The fail-safe module selects the behavior of MRM according to the abnormality an The RTI state indicates whether RTI is requested. If for some reason autonomous driving cannot continue, Autoware will request a change to manual driving. As a side note, RTI is sometimes called Take Over Request (TOR). +## MRM description + +Autoware supports various MRM implementation to provide appropriate behavior for each use case. +Therefore, use this API when detailed information about MRM behavior is required. The MRM behavior ID listed by this API is used in MRM state API. + ## MRM state The MRM state indicates whether MRM is operating and its current behavior. @@ -50,11 +55,6 @@ This is service dependent. Autoware supports the following transitions by defaul | EMERGENCY_STOP | The vehicle will stop immediately with as much deceleration as possible. | | PULL_OVER | The vehicle will stop after moving to the side of the road. | -## MRM description - -Autoware supports various MRM implementation to provide appropriate behavior for each use case. -Therefore, use this API when detailed information about MRM behavior is required. The MRM behavior ID listed by this API is used in MRM state API. - ## MRM request MRM request is a feature that triggers MRM from an application, and is mainly used when the application wants to transition the vehicle to a safe state by detecting an abnormality. When an MRM request is sent, Autoware attempts to operate the MRM. To distinguish requests from multiple applications, an MRM request must include a user name as an identifier.