Skip to content

Commit f9fbd39

Browse files
isamu-takagiisamu-takagi
authored
docs(diagnostic_graph_aggregator): update documents (#6613)
Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>
1 parent 3c01dc9 commit f9fbd39

24 files changed

+191
-76
lines changed

‎system/diagnostic_graph_aggregator/README.md

+18-11
Original file line numberDiff line numberDiff line change
@@ -53,20 +53,27 @@ This feature breaks the generality of the graph and may be changed to a plugin o
5353

5454
## Examples
5555

56-
- [example_0.yaml](./example/example_0.yaml)
57-
- [example_1.yaml](./example/example_1.yaml)
58-
- [example_2.yaml](./example/example_2.yaml)
56+
This is an example of a diagnostic graph configuration. The configuration can be split into multiple files.
57+
58+
- [main.yaml](./example/graph/main.yaml)
59+
- [module1.yaml](./example/graph/module1.yaml)
60+
- [module2.yaml](./example/graph/module2.yaml)
61+
62+
```bash
63+
ros2 launch diagnostic_graph_aggregator example-main.launch.xml
64+
```
65+
66+
You can reuse the graph by making partial edits. For example, disable hardware checks for simulation.
67+
68+
- [edit.yaml](./example/graph/edit.yaml)
5969

6070
```bash
61-
ros2 launch diagnostic_graph_aggregator example.launch.xml
71+
ros2 launch diagnostic_graph_aggregator example-edit.launch.xml
6272
```
6373

6474
## Graph file format
6575

66-
- [GraphFile](./doc/format/graph-file.md)
67-
- [Path](./doc/format/path.md)
68-
- [Node](./doc/format/node.md)
69-
- [Diag](./doc/format/diag.md)
70-
- [Unit](./doc/format/unit.md)
71-
- [And](./doc/format/and.md)
72-
- [Or](./doc/format/or.md)
76+
- [graph](./doc/format/graph.md)
77+
- [path](./doc/format/path.md)
78+
- [node](./doc/format/node.md)
79+
- [edit](./doc/format/edit.md)

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

-11
This file was deleted.

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

-10
This file was deleted.

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

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Edit
2+
3+
The `edit` is a base object that edits the existing diagnostic graph.
4+
Any derived object can be used where a edit object is required.
5+
6+
## Format
7+
8+
| Name | Type | Required | Description |
9+
| ------ | -------- | -------- | ------------------------------------------------- |
10+
| `type` | `string` | yes | The string indicating the type of derived object. |
11+
12+
## Derived objects
13+
14+
- [remove](./edit/remove.md)

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Remove
2+
3+
The `remove` object is a edit that removes other nodes.
4+
5+
## Format
6+
7+
| Name | Type | Required | Description |
8+
| ------ | -------- | -------- | ---------------------------------------- |
9+
| `type` | `string` | yes | Specify `remove` when using this object. |
10+
| `path` | `string` | yes | The path of the node to remove. |

‎system/diagnostic_graph_aggregator/doc/format/graph-file.md

-10
This file was deleted.

‎system/diagnostic_graph_aggregator/doc/format/graph.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Graph
2+
3+
The graph object is the top level structure that makes up the configuration file.
4+
5+
## Format
6+
7+
| Name | Type | Required | Description |
8+
| ------- | -------------------------------------- | -------- | ------------------------------------------------- |
9+
| `files` | <code>list\[[path](./path.md)\]</code> | no | List of path objects for importing subgraphs. |
10+
| `nodes` | <code>list\[[node](./node.md)\]</code> | no | List of node objects that make up the graph. |
11+
| `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

+20-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,25 @@
11
# Node
22

3-
Node is a base object that makes up the diagnostic graph.
3+
The `node` is a base object that makes up the diagnostic graph.
4+
Any derived object can be used where a node object is required.
45

56
## Format
67

7-
| Name | Type | Required | Description |
8-
| ---- | ------ | -------- | ------------------------------------------- |
9-
| type | string | yes | Node type. See derived objects for details. |
8+
| Name | Type | Required | Description |
9+
| ------ | -------- | -------- | ------------------------------------------------- |
10+
| `type` | `string` | yes | The string indicating the type of derived object. |
11+
| `path` | `string` | no | Any string to reference from other nodes. |
12+
13+
## Derived objects
14+
15+
- [diag](./node/diag.md)
16+
- [and](./node/and.md)
17+
- [or](./node/or.md)
18+
- [remapping](./node/remap.md)
19+
- warn-to-ok
20+
- warn-to-error
21+
- [constant](./node/const.md)
22+
- ok
23+
- warn
24+
- error
25+
- stale

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

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# And
2+
3+
The `and` object is a node that is evaluated as the maximum error level of the input nodes.
4+
Note that error level `stale` is treated as `error`.
5+
6+
## Format
7+
8+
| Name | Type | Required | Description |
9+
| ------ | -------------------------------------- | -------- | ------------------------------------------------------------ |
10+
| `type` | <code>string</code> | yes | Specify `and` or `short-circuit-and` when using this object. |
11+
| `list` | <code>list\[[node](../node.md)]</code> | yes | List of input node objects. |
12+
13+
## Short-circuit evaluation
14+
15+
!!! warning
16+
17+
The`short-circuit-and` is work in progress (WIP).

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

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Constant
2+
3+
The constant object is a node with a fixed error level.
4+
5+
## Format
6+
7+
| Name | Type | Required | Description |
8+
| ------ | -------- | -------- | ------------------------------------------- |
9+
| `type` | `string` | yes | Specify error level when using this object. |
10+
11+
## Error levels
12+
13+
The supported error levels are as follows.
14+
15+
- `ok`
16+
- `warn`
17+
- `error`
18+
- `stale`

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Diag
2+
3+
The `diag` object is a node that refers to a specific status within the source diagnostics.
4+
5+
## Format
6+
7+
| Name | Type | Required | Description |
8+
| ------ | -------- | -------- | -------------------------------------- |
9+
| `type` | `string` | yes | Specify `diag` when using this object. |
10+
| `diag` | `string` | yes | The name of the diagnostic status. |

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Link
2+
3+
The `link` object is a node that refers to other nodes.
4+
5+
## Format
6+
7+
| Name | Type | Required | Description |
8+
| ------ | -------- | -------- | -------------------------------------- |
9+
| `type` | `string` | yes | Specify `link` when using this object. |
10+
| `link` | `string` | yes | The path of the node to reference. |

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

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

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

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Constant
2+
3+
!!! warning
4+
5+
This object is under development. It may be removed in the future.
6+
7+
The remapping object is a node that converts error levels.
8+
9+
## Format
10+
11+
| Name | Type | Required | Description |
12+
| ------ | -------------------------------------- | -------- | ---------------------------------------------------- |
13+
| `type` | `string` | yes | Specify remapping type when using this object. |
14+
| `list` | <code>list\[[node](../node.md)]</code> | yes | List of input node objects. The list size must be 1. |
15+
16+
## Remapping types
17+
18+
The supported remapping types are as follows.
19+
20+
- `warn-to-ok`
21+
- `warn-to-error`

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

-11
This file was deleted.

‎system/diagnostic_graph_aggregator/doc/format/path.md

+14-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,19 @@
11
# Path
22

3-
Path is an object that indicates the path of the file to include.
3+
The path object specifies the file path of the subgraph to be imported.
4+
The structure of the subgraph file should be [graph object](./graph.md).
45

56
## Format
67

7-
| Name | Type | Required | Description |
8-
| ------- | ------ | -------- | ----------------------------- |
9-
| package | string | yes | Package name. |
10-
| path | string | yes | Relative path in the package. |
8+
| Name | Type | Required | Description |
9+
| ------ | -------- | -------- | ------------------------------ |
10+
| `path` | `string` | yes | The file path of the subgraph. |
11+
12+
## Substitutions
13+
14+
File paths can contain substitutions like ROS 2 launch. The supported substitutions are as follows.
15+
16+
| Substitution | Description |
17+
| ----------------------------- | -------------------------------- |
18+
| `$(dirname)` | The path of this file directory. |
19+
| `$(find-pkg-share <package>)` | The path of the package. |

‎system/diagnostic_graph_aggregator/doc/format/unit.md

-10
This file was deleted.

‎system/diagnostic_graph_aggregator/example/example_diags.py ‎system/diagnostic_graph_aggregator/example/dummy-diags.py

File renamed without changes.

‎system/diagnostic_graph_aggregator/example/example.launch.xml ‎system/diagnostic_graph_aggregator/example/example-edit.launch.xml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<launch>
22
<include file="$(find-pkg-share diagnostic_graph_aggregator)/launch/diagnostic_graph_aggregator.launch.xml">
3-
<arg name="graph_file" value="$(find-pkg-share diagnostic_graph_aggregator)/example/example_0.yaml"/>
3+
<arg name="graph_file" value="$(find-pkg-share diagnostic_graph_aggregator)/example/graph/edit.yaml"/>
44
</include>
55
<node pkg="diagnostic_graph_aggregator" exec="converter" name="converter"/>
6-
<executable cmd="python3 $(find-pkg-share diagnostic_graph_aggregator)/example/example_diags.py"/>
6+
<executable cmd="python3 $(find-pkg-share diagnostic_graph_aggregator)/example/dummy-diags.py"/>
77
</launch>

‎system/diagnostic_graph_aggregator/example/example-main.launch.xml

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<launch>
2+
<include file="$(find-pkg-share diagnostic_graph_aggregator)/launch/diagnostic_graph_aggregator.launch.xml">
3+
<arg name="graph_file" value="$(find-pkg-share diagnostic_graph_aggregator)/example/graph/main.yaml"/>
4+
</include>
5+
<node pkg="diagnostic_graph_aggregator" exec="converter" name="converter"/>
6+
<executable cmd="python3 $(find-pkg-share diagnostic_graph_aggregator)/example/dummy-diags.py"/>
7+
</launch>

‎system/diagnostic_graph_aggregator/example/graph/edit.yaml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
files:
2+
- { path: $(find-pkg-share diagnostic_graph_aggregator)/example/graph/main.yaml }
3+
4+
edits:
5+
- path: /functions/obstacle_detection
6+
type: remove

‎system/diagnostic_graph_aggregator/example/example_0.yaml ‎system/diagnostic_graph_aggregator/example/graph/main.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
files:
2-
- { path: $(find-pkg-share diagnostic_graph_aggregator)/example/example_1.yaml }
3-
- { path: $(find-pkg-share diagnostic_graph_aggregator)/example/example_2.yaml }
2+
- { path: $(dirname)/module1.yaml }
3+
- { path: $(dirname)/module2.yaml }
44

55
nodes:
66
- path: /autoware/modes/stop

‎system/diagnostic_graph_aggregator/example/example_1.yaml ‎system/diagnostic_graph_aggregator/example/graph/module1.yaml

File renamed without changes.

‎system/diagnostic_graph_aggregator/example/example_2.yaml ‎system/diagnostic_graph_aggregator/example/graph/module2.yaml

File renamed without changes.

0 commit comments

Comments
 (0)