diff --git a/system/diagnostic_graph_aggregator/README.md b/system/diagnostic_graph_aggregator/README.md index 4dc44feaafc33..dabbb1402db4c 100644 --- a/system/diagnostic_graph_aggregator/README.md +++ b/system/diagnostic_graph_aggregator/README.md @@ -53,20 +53,27 @@ 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 ``` ## 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) diff --git a/system/diagnostic_graph_aggregator/doc/format/and.md b/system/diagnostic_graph_aggregator/doc/format/and.md deleted file mode 100644 index a92aa2817832e..0000000000000 --- a/system/diagnostic_graph_aggregator/doc/format/and.md +++ /dev/null @@ -1,11 +0,0 @@ -# Unit - -And is a node that is evaluated as the AND of the input nodes. - -## Format - -| Name | Type | Required | Description | -| ---- | ------------------------------------------ | -------- | ------------------------------------- | -| type | string | yes | Specify `and` when using this object. | -| name | string | yes | Name of diagnostic status. | -| list | List<[Diag](./diag.md)\|[Unit](./unit.md)> | yes | List of input node references. | diff --git a/system/diagnostic_graph_aggregator/doc/format/diag.md b/system/diagnostic_graph_aggregator/doc/format/diag.md deleted file mode 100644 index 04e850129cbbf..0000000000000 --- a/system/diagnostic_graph_aggregator/doc/format/diag.md +++ /dev/null @@ -1,10 +0,0 @@ -# Diag - -Diag is a node that refers to a source diagnostics. - -## Format - -| Name | Type | Required | Description | -| ---- | ------ | -------- | -------------------------------------- | -| type | string | yes | Specify `diag` when using this object. | -| diag | string | yes | Name of diagnostic status. | diff --git a/system/diagnostic_graph_aggregator/doc/format/edit.md b/system/diagnostic_graph_aggregator/doc/format/edit.md new file mode 100644 index 0000000000000..71ea8a96bc17f --- /dev/null +++ b/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) diff --git a/system/diagnostic_graph_aggregator/doc/format/edit/remove.md b/system/diagnostic_graph_aggregator/doc/format/edit/remove.md new file mode 100644 index 0000000000000..6cd4b25e98828 --- /dev/null +++ b/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. | diff --git a/system/diagnostic_graph_aggregator/doc/format/graph-file.md b/system/diagnostic_graph_aggregator/doc/format/graph-file.md deleted file mode 100644 index 3c4cfec996a4a..0000000000000 --- a/system/diagnostic_graph_aggregator/doc/format/graph-file.md +++ /dev/null @@ -1,10 +0,0 @@ -# GraphFile - -GraphFile is the top level object that makes up the configuration file. - -## Format - -| Name | Type | Required | Description | -| ----- | ----------------------- | -------- | ------------------------------ | -| files | List<[Path](./path.md)> | no | Paths of the files to include. | -| nodes | List<[Node](./node.md)> | no | Nodes of the diagnostic graph. | diff --git a/system/diagnostic_graph_aggregator/doc/format/graph.md b/system/diagnostic_graph_aggregator/doc/format/graph.md new file mode 100644 index 0000000000000..9dace8a2f0e6d --- /dev/null +++ b/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` | list\[[path](./path.md)\] | no | List of path objects for importing subgraphs. | +| `nodes` | list\[[node](./node.md)\] | no | List of node objects that make up the graph. | +| `edits` | list\[[edit](./edit.md)\] | no | List of edit objects to partially edit the graph. | diff --git a/system/diagnostic_graph_aggregator/doc/format/node.md b/system/diagnostic_graph_aggregator/doc/format/node.md index da8e8e57b111f..0f4b52b9b8a72 100644 --- a/system/diagnostic_graph_aggregator/doc/format/node.md +++ b/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 diff --git a/system/diagnostic_graph_aggregator/doc/format/node/and.md b/system/diagnostic_graph_aggregator/doc/format/node/and.md new file mode 100644 index 0000000000000..562018bf0995b --- /dev/null +++ b/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` | string | yes | Specify `and` or `short-circuit-and` when using this object. | +| `list` | list\[[node](../node.md)] | yes | List of input node objects. | + +## Short-circuit evaluation + +!!! warning + + The`short-circuit-and` is work in progress (WIP). diff --git a/system/diagnostic_graph_aggregator/doc/format/node/const.md b/system/diagnostic_graph_aggregator/doc/format/node/const.md new file mode 100644 index 0000000000000..13495be6cdbda --- /dev/null +++ b/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` diff --git a/system/diagnostic_graph_aggregator/doc/format/node/diag.md b/system/diagnostic_graph_aggregator/doc/format/node/diag.md new file mode 100644 index 0000000000000..beba8ed0df5b4 --- /dev/null +++ b/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. | diff --git a/system/diagnostic_graph_aggregator/doc/format/node/link.md b/system/diagnostic_graph_aggregator/doc/format/node/link.md new file mode 100644 index 0000000000000..c23aa92575e54 --- /dev/null +++ b/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. | diff --git a/system/diagnostic_graph_aggregator/doc/format/node/or.md b/system/diagnostic_graph_aggregator/doc/format/node/or.md new file mode 100644 index 0000000000000..74e94ffd628e3 --- /dev/null +++ b/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` | string | yes | Specify `or` when using this object. | +| `list` | list\[[node](../node.md)] | yes | List of input node objects. | diff --git a/system/diagnostic_graph_aggregator/doc/format/node/remap.md b/system/diagnostic_graph_aggregator/doc/format/node/remap.md new file mode 100644 index 0000000000000..abf0d11fae12d --- /dev/null +++ b/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` | list\[[node](../node.md)] | 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` diff --git a/system/diagnostic_graph_aggregator/doc/format/or.md b/system/diagnostic_graph_aggregator/doc/format/or.md deleted file mode 100644 index 3e668b686c9e8..0000000000000 --- a/system/diagnostic_graph_aggregator/doc/format/or.md +++ /dev/null @@ -1,11 +0,0 @@ -# Unit - -Or is a node that is evaluated as the OR of the input nodes. - -## Format - -| Name | Type | Required | Description | -| ---- | ------------------------------------------ | -------- | ------------------------------------ | -| type | string | yes | Specify `or` when using this object. | -| name | string | yes | Name of diagnostic status. | -| list | List<[Diag](./diag.md)\|[Unit](./unit.md)> | yes | List of input node references. | diff --git a/system/diagnostic_graph_aggregator/doc/format/path.md b/system/diagnostic_graph_aggregator/doc/format/path.md index 1f27accefa35a..6ca32a7eaad80 100644 --- a/system/diagnostic_graph_aggregator/doc/format/path.md +++ b/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 )` | The path of the package. | diff --git a/system/diagnostic_graph_aggregator/doc/format/unit.md b/system/diagnostic_graph_aggregator/doc/format/unit.md deleted file mode 100644 index 791689aa2d98a..0000000000000 --- a/system/diagnostic_graph_aggregator/doc/format/unit.md +++ /dev/null @@ -1,10 +0,0 @@ -# Unit - -Diag is a node that refers to a functional unit. - -## Format - -| Name | Type | Required | Description | -| ---- | ------ | -------- | -------------------------------------- | -| type | string | yes | Specify `unit` when using this object. | -| name | string | yes | Name of diagnostic status. | diff --git a/system/diagnostic_graph_aggregator/example/example_diags.py b/system/diagnostic_graph_aggregator/example/dummy-diags.py similarity index 100% rename from system/diagnostic_graph_aggregator/example/example_diags.py rename to system/diagnostic_graph_aggregator/example/dummy-diags.py diff --git a/system/diagnostic_graph_aggregator/example/example.launch.xml b/system/diagnostic_graph_aggregator/example/example-edit.launch.xml similarity index 81% rename from system/diagnostic_graph_aggregator/example/example.launch.xml rename to system/diagnostic_graph_aggregator/example/example-edit.launch.xml index 71e59a1833d6e..91bcc46df6494 100644 --- a/system/diagnostic_graph_aggregator/example/example.launch.xml +++ b/system/diagnostic_graph_aggregator/example/example-edit.launch.xml @@ -1,7 +1,7 @@ - + - + diff --git a/system/diagnostic_graph_aggregator/example/example-main.launch.xml b/system/diagnostic_graph_aggregator/example/example-main.launch.xml new file mode 100644 index 0000000000000..ab7bfaa2e0617 --- /dev/null +++ b/system/diagnostic_graph_aggregator/example/example-main.launch.xml @@ -0,0 +1,7 @@ + + + + + + + diff --git a/system/diagnostic_graph_aggregator/example/graph/edit.yaml b/system/diagnostic_graph_aggregator/example/graph/edit.yaml new file mode 100644 index 0000000000000..2fbdbffca438d --- /dev/null +++ b/system/diagnostic_graph_aggregator/example/graph/edit.yaml @@ -0,0 +1,6 @@ +files: + - { path: $(find-pkg-share diagnostic_graph_aggregator)/example/graph/main.yaml } + +edits: + - path: /functions/obstacle_detection + type: remove diff --git a/system/diagnostic_graph_aggregator/example/example_0.yaml b/system/diagnostic_graph_aggregator/example/graph/main.yaml similarity index 83% rename from system/diagnostic_graph_aggregator/example/example_0.yaml rename to system/diagnostic_graph_aggregator/example/graph/main.yaml index 7b01883723c76..2bea907d9c119 100644 --- a/system/diagnostic_graph_aggregator/example/example_0.yaml +++ b/system/diagnostic_graph_aggregator/example/graph/main.yaml @@ -1,6 +1,6 @@ files: - - { path: $(find-pkg-share diagnostic_graph_aggregator)/example/example_1.yaml } - - { path: $(find-pkg-share diagnostic_graph_aggregator)/example/example_2.yaml } + - { path: $(dirname)/module1.yaml } + - { path: $(dirname)/module2.yaml } nodes: - path: /autoware/modes/stop diff --git a/system/diagnostic_graph_aggregator/example/example_1.yaml b/system/diagnostic_graph_aggregator/example/graph/module1.yaml similarity index 100% rename from system/diagnostic_graph_aggregator/example/example_1.yaml rename to system/diagnostic_graph_aggregator/example/graph/module1.yaml diff --git a/system/diagnostic_graph_aggregator/example/example_2.yaml b/system/diagnostic_graph_aggregator/example/graph/module2.yaml similarity index 100% rename from system/diagnostic_graph_aggregator/example/example_2.yaml rename to system/diagnostic_graph_aggregator/example/graph/module2.yaml