Merge pull request autowarefoundation#1192 from tier4/update-diagnost…

…ic-agg

feat(diagnostic_graph_aggregator): update documents and tools

system/diagnostic_graph_aggregator/CMakeLists.txt

@@ -22,10 +22,17 @@ ament_auto_add_executable(converter
 )
 target_include_directories(converter PRIVATE src/common)
 
-ament_auto_add_executable(tool
-  src/tool/tool.cpp
+ament_auto_add_executable(tree
+  src/tool/tree.cpp
+  src/tool/utils/loader.cpp
 )
-target_include_directories(tool PRIVATE src/common)
+target_include_directories(tree PRIVATE src/common)
+
+ament_auto_add_executable(plantuml
+  src/tool/plantuml.cpp
+  src/tool/utils/loader.cpp
+)
+target_include_directories(plantuml PRIVATE src/common)
 
 if(BUILD_TESTING)
   get_filename_component(RESOURCE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/test/files ABSOLUTE)

system/diagnostic_graph_aggregator/README.md

@@ -53,20 +53,33 @@ This feature breaks the generality of the graph and may be changed to a plugin o
 
 ## Examples
 
-- [example_0.yaml](./example/example_0.yaml)
-- [example_1.yaml](./example/example_1.yaml)
-- [example_2.yaml](./example/example_2.yaml)
+This is an example of a diagnostic graph configuration. The configuration can be split into multiple files.
+
+- [main.yaml](./example/graph/main.yaml)
+- [module1.yaml](./example/graph/module1.yaml)
+- [module2.yaml](./example/graph/module2.yaml)
+
+```bash
+ros2 launch diagnostic_graph_aggregator example-main.launch.xml
+```
+
+You can reuse the graph by making partial edits. For example, disable hardware checks for simulation.
+
+- [edit.yaml](./example/graph/edit.yaml)
 
 ```bash
-ros2 launch diagnostic_graph_aggregator example.launch.xml
+ros2 launch diagnostic_graph_aggregator example-edit.launch.xml
 ```
 
+## Debug tools
+
+- [dump](./doc/tool/dump.md)
+- [converter](./doc/tool/converter.md)
+- [tree](./doc/tool/tree.md)
+
 ## Graph file format
 
-- [GraphFile](./doc/format/graph-file.md)
-- [Path](./doc/format/path.md)
-- [Node](./doc/format/node.md)
-  - [Diag](./doc/format/diag.md)
-  - [Unit](./doc/format/unit.md)
-  - [And](./doc/format/and.md)
-  - [Or](./doc/format/or.md)
+- [graph](./doc/format/graph.md)
+- [path](./doc/format/path.md)
+- [node](./doc/format/node.md)
+- [edit](./doc/format/edit.md)

system/diagnostic_graph_aggregator/doc/format/edit.md

@@ -0,0 +1,14 @@
+# Edit
+
+The `edit` is a base object that edits the existing diagnostic graph.
+Any derived object can be used where a edit object is required.
+
+## Format
+
+| Name   | Type     | Required | Description                                       |
+| ------ | -------- | -------- | ------------------------------------------------- |
+| `type` | `string` | yes      | The string indicating the type of derived object. |
+
+## Derived objects
+
+- [remove](./edit/remove.md)

system/diagnostic_graph_aggregator/doc/format/edit/remove.md

@@ -0,0 +1,10 @@
+# Remove
+
+The `remove` object is a edit that removes other nodes.
+
+## Format
+
+| Name   | Type     | Required | Description                              |
+| ------ | -------- | -------- | ---------------------------------------- |
+| `type` | `string` | yes      | Specify `remove` when using this object. |
+| `path` | `string` | yes      | The path of the node to remove.          |

system/diagnostic_graph_aggregator/doc/format/graph.md

@@ -0,0 +1,11 @@
+# Graph
+
+The graph object is the top level structure that makes up the configuration file.
+
+## Format
+
+| Name    | Type                                   | Required | Description                                       |
+| ------- | -------------------------------------- | -------- | ------------------------------------------------- |
+| `files` | <code>list\[[path](./path.md)\]</code> | no       | List of path objects for importing subgraphs.     |
+| `nodes` | <code>list\[[node](./node.md)\]</code> | no       | List of node objects that make up the graph.      |
+| `edits` | <code>list\[[edit](./edit.md)\]</code> | no       | List of edit objects to partially edit the graph. |

system/diagnostic_graph_aggregator/doc/format/node.md

@@ -1,9 +1,25 @@
 # Node
 
-Node is a base object that makes up the diagnostic graph.
+The `node` is a base object that makes up the diagnostic graph.
+Any derived object can be used where a node object is required.
 
 ## Format
 
-| Name | Type   | Required | Description                                 |
-| ---- | ------ | -------- | ------------------------------------------- |
-| type | string | yes      | Node type. See derived objects for details. |
+| Name   | Type     | Required | Description                                       |
+| ------ | -------- | -------- | ------------------------------------------------- |
+| `type` | `string` | yes      | The string indicating the type of derived object. |
+| `path` | `string` | no       | Any string to reference from other nodes.         |
+
+## Derived objects
+
+- [diag](./node/diag.md)
+- [and](./node/and.md)
+- [or](./node/or.md)
+- [remapping](./node/remap.md)
+  - warn-to-ok
+  - warn-to-error
+- [constant](./node/const.md)
+  - ok
+  - warn
+  - error
+  - stale

system/diagnostic_graph_aggregator/doc/format/node/and.md

@@ -0,0 +1,17 @@
+# And
+
+The `and` object is a node that is evaluated as the maximum error level of the input nodes.
+Note that error level `stale` is treated as `error`.
+
+## Format
+
+| Name   | Type                                   | Required | Description                                                  |
+| ------ | -------------------------------------- | -------- | ------------------------------------------------------------ |
+| `type` | <code>string</code>                    | yes      | Specify `and` or `short-circuit-and` when using this object. |
+| `list` | <code>list\[[node](../node.md)]</code> | yes      | List of input node objects.                                  |
+
+## Short-circuit evaluation
+
+!!! warning
+
+    The`short-circuit-and` is work in progress (WIP).

system/diagnostic_graph_aggregator/doc/format/node/const.md

@@ -0,0 +1,18 @@
+# Constant
+
+The constant object is a node with a fixed error level.
+
+## Format
+
+| Name   | Type     | Required | Description                                 |
+| ------ | -------- | -------- | ------------------------------------------- |
+| `type` | `string` | yes      | Specify error level when using this object. |
+
+## Error levels
+
+The supported error levels are as follows.
+
+- `ok`
+- `warn`
+- `error`
+- `stale`

system/diagnostic_graph_aggregator/doc/format/node/diag.md

@@ -0,0 +1,10 @@
+# Diag
+
+The `diag` object is a node that refers to a specific status within the source diagnostics.
+
+## Format
+
+| Name   | Type     | Required | Description                            |
+| ------ | -------- | -------- | -------------------------------------- |
+| `type` | `string` | yes      | Specify `diag` when using this object. |
+| `diag` | `string` | yes      | The name of the diagnostic status.     |

system/diagnostic_graph_aggregator/doc/format/node/link.md

@@ -0,0 +1,10 @@
+# Link
+
+The `link` object is a node that refers to other nodes.
+
+## Format
+
+| Name   | Type     | Required | Description                            |
+| ------ | -------- | -------- | -------------------------------------- |
+| `type` | `string` | yes      | Specify `link` when using this object. |
+| `link` | `string` | yes      | The path of the node to reference.     |

system/diagnostic_graph_aggregator/doc/format/node/or.md

@@ -0,0 +1,11 @@
+# Or
+
+The `or` object is a node that is evaluated as the minimum error level of the input nodes.
+Note that error level `stale` is treated as `error`.
+
+## Format
+
+| Name   | Type                                   | Required | Description                          |
+| ------ | -------------------------------------- | -------- | ------------------------------------ |
+| `type` | <code>string</code>                    | yes      | Specify `or` when using this object. |
+| `list` | <code>list\[[node](../node.md)]</code> | yes      | List of input node objects.          |

system/diagnostic_graph_aggregator/doc/format/node/remap.md

@@ -0,0 +1,21 @@
+# Constant
+
+!!! warning
+
+    This object is under development. It may be removed in the future.
+
+The remapping object is a node that converts error levels.
+
+## Format
+
+| Name   | Type                                   | Required | Description                                          |
+| ------ | -------------------------------------- | -------- | ---------------------------------------------------- |
+| `type` | `string`                               | yes      | Specify remapping type when using this object.       |
+| `list` | <code>list\[[node](../node.md)]</code> | yes      | List of input node objects. The list size must be 1. |
+
+## Remapping types
+
+The supported remapping types are as follows.
+
+- `warn-to-ok`
+- `warn-to-error`

system/diagnostic_graph_aggregator/doc/format/path.md

@@ -1,10 +1,19 @@
 # Path
 
-Path is an object that indicates the path of the file to include.
+The path object specifies the file path of the subgraph to be imported.
+The structure of the subgraph file should be [graph object](./graph.md).
 
 ## Format
 
-| Name    | Type   | Required | Description                   |
-| ------- | ------ | -------- | ----------------------------- |
-| package | string | yes      | Package name.                 |
-| path    | string | yes      | Relative path in the package. |
+| Name   | Type     | Required | Description                    |
+| ------ | -------- | -------- | ------------------------------ |
+| `path` | `string` | yes      | The file path of the subgraph. |
+
+## Substitutions
+
+File paths can contain substitutions like ROS 2 launch. The supported substitutions are as follows.
+
+| Substitution                  | Description                      |
+| ----------------------------- | -------------------------------- |
+| `$(dirname)`                  | The path of this file directory. |
+| `$(find-pkg-share <package>)` | The path of the package.         |

system/diagnostic_graph_aggregator/doc/tool/converter.md

@@ -0,0 +1,29 @@
+# Converter tool
+
+This tool converts `/diagnostics_graph` to `/diagnostics_agg` so it can be read by tools such as `rqt_runtime_monitor` and `rqt_robot_monitor`.
+
+## Usage
+
+```bash
+ros2 launch diagnostic_graph_aggregator converter.launch.xml complement:=false
+```
+
+The `complement` argument specifies whether to add an intermediate path that does not exist.
+This means that if the graph contains paths `/A/B` and `/A/B/C/D/E`, the intermediate paths `/A`, `/A/B/C` and `/A/B/C/D` will be added.
+This is useful for tree view in `rqt_robot_monitor`. The completed node has an error level of `STALE`.
+
+## Examples
+
+```bash
+ros2 launch diagnostic_graph_aggregator example-main.launch.xml complement:=false
+ros2 run rqt_runtime_monitor rqt_runtime_monitor --ros-args -r diagnostics:=diagnostics_agg
+```
+
+![rqt_runtime_monitor](./images/rqt_runtime_monitor.png)
+
+```bash
+ros2 launch diagnostic_graph_aggregator example-main.launch.xml complement:=true
+ros2 run rqt_robot_monitor rqt_robot_monitor
+```
+
+![rqt_robot_monitor](./images/rqt_robot_monitor.png)

system/diagnostic_graph_aggregator/doc/tool/dump.md

@@ -0,0 +1,36 @@
+# Dump tool
+
+This tool displays `/diagnostics_graph` in table format.
+
+## Usage
+
+```bash
+ros2 run diagnostic_graph_aggregator dump
+```
+
+## Examples
+
+```bash
+ros2 launch diagnostic_graph_aggregator example-main.launch.xml
+ros2 run diagnostic_graph_aggregator dump
+```
+
+```txt
+| ----- | ----- | -------------------------------- | ----- |
+| index | level | name                             | links |
+| ----- | ----- | -------------------------------- | ----- |
+| 0     | OK    | /sensing/radars/front            |       |
+| 1     | OK    | /sensing/lidars/front            |       |
+| 2     | ERROR | /sensing/lidars/top              |       |
+| 3     | OK    | /functions/obstacle_detection    | 1 0   |
+| 4     | ERROR | /functions/pose_estimation       | 2     |
+| 5     | OK    | /external/remote_command         |       |
+| 6     | OK    | /external/joystick_command       |       |
+| 7     | ERROR | /autoware/modes/pull_over        | 4 3   |
+| 8     | OK    | /autoware/modes/comfortable_stop | 3     |
+| 9     | OK    | /autoware/modes/emergency_stop   |       |
+| 10    | OK    | /autoware/modes/remote           | 5     |
+| 11    | OK    | /autoware/modes/local            | 6     |
+| 12    | ERROR | /autoware/modes/autonomous       | 4 3   |
+| 13    | OK    | /autoware/modes/stop             |       |
+```