From 869006f63744a551f956380e369e6c0a930ede6e Mon Sep 17 00:00:00 2001 From: kaspermeck-arm Date: Thu, 4 May 2023 08:34:08 -0700 Subject: [PATCH 1/5] docs(parameters): DevOps Dojo: ROS Node Config Updated the guidelines for how to configure the ROS node parameters. Signed-off-by: Kasper Mecklenburg Change-Id: Icef28c52c0876c294a8d8d39edb8d1d4fc1d9538 --- .../coding-guidelines/ros-nodes/parameters.md | 155 +++++++++++++++--- 1 file changed, 131 insertions(+), 24 deletions(-) diff --git a/docs/contributing/coding-guidelines/ros-nodes/parameters.md b/docs/contributing/coding-guidelines/ros-nodes/parameters.md index 2cb65ccedaa..c5f5a856b6d 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/parameters.md +++ b/docs/contributing/coding-guidelines/ros-nodes/parameters.md @@ -1,36 +1,143 @@ # Parameters +Autoware ROS nodes have declared parameters which values are provided during the node start up in the form of a parameter file. All the expected parameters with corresponding values should exist in the parameter file. Depending on the application, the parameter values might need to be modified. -The ROS packages in Autoware have ROS parameters. You need to customize the parameters depending on your applications. -It is recommended not to set default values when declaring ROS parameters to avoid unintended behaviors due to accidental use of default values. -Instead, set parameters from configuration files named `*.param.yaml`. +Find more information on parameters from the official ROS documentation: +- [Understanding ROS 2 Parameters](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.html) +- [About ROS 2 Parameters](https://docs.ros.org/en/humble/Concepts/About-ROS-2-Parameters.html) -For understanding ROS 2 parameters, also check out the official documentation [Understanding parameters](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.html). +## JSON Schema +[JSON Schema](https://json-schema.org/understanding-json-schema/index.html) is used the validate the parameter file(s) ensuring that it has the correct structure and content. Using JSON Schema for this purpose is considered best practice for cloud-native development. The schema template below shall be used as a starting point when defining the schema for a ROS node. -## Parameter files +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "INSERT_TITLE", + "type": "object", + "definitions": { + "INSERT_ROS_NODE_NAME": { + "type": "object", + "properties": { + "INSERT_PARAMETER_1_NAME": { + "type": "INSERT_TYPE", + "description": "INSERT_DESCRIPTION", + "default": "INSERT_DEFAULT", + "INSERT_BOUND_CONDITION(S)": "INSERT_BOUND_VALUE(S)" + }, + "INSERT_PARAMETER_N_NAME": { + "type": "INSERT_TYPE", + "description": "INSERT_DESCRIPTION", + "default": "INSERT_DEFAULT", + "INSERT_BOUND_CONDITION(S)": "INSERT_BOUND_VALUE(S)" + } + }, + "required": [ + "INSERT_PARAMETER_1_NAME", + "INSERT_PARAMETER_N_NAME" + ] + } + }, + "properties": { + "/**": { + "type": "object", + "properties": { + "ros__parameters": { + "$ref": "#/definitions/INSERT_ROS_NODE_NAME" + } + }, + "required": ["ros__parameters"] + } + }, + "required": ["/**"] +} +``` + +The schema file path is `INSERT_PATH_TO_PACKAGE/schema/` and the schema file name is `INSERT_NODE_NAME.schema.json`. To adapt the template to the ROS node, replace each `INSERT_...` and add all parameters `1..N`. + +See example: _Lidar Apollo Segmentation TVM Nodes_ [schema](https://github.com/autowarefoundation/autoware.universe/blob/main/perception/lidar_apollo_segmentation_tvm_nodes/schema/lidar_apollo_segmentation_tvm_nodes.schema.json) -Autoware has the following two types of parameter files for ROS packages: +### Attributes +Parameters have several attributes, some are required and some optional. The optional attributes are highly encouraged when applicable, as they provide useful information about a parameter to the user. -- **Node parameter file** - - Node parameter files store the default parameters provided for each package in Autoware. - - For example, [the parameter of `behavior_path_planner`](https://github.com/autowarefoundation/autoware.universe/tree/245242cee866de2d113e89c562353c5fc17f1f98/planning/behavior_path_planner/config) - - All nodes in Autoware must have a parameter file if one or more parameters that can be customized by the user are defined. - - For `FOO_package`, the parameter is expected to be stored in `FOO_package/config`. - - The launch file for individual packages must load node parameter by default: +**Required** +- name +- type + - see [JSON Schema types](http://json-schema.org/understanding-json-schema/reference/type.html) +- description -```xml - - +**Optional** +- default + - a tested and verified value, see [JSON Schema default](https://json-schema.org/understanding-json-schema/reference/generic.html) +- bound(s) + - type dependent, e.g., [integer](https://json-schema.org/understanding-json-schema/reference/numeric.html#integer), [range](https://json-schema.org/understanding-json-schema/reference/numeric.html#range) and [size](https://json-schema.org/understanding-json-schema/reference/object.html#size) - - ... - - - +## Parameter File +The parameter file is minimal as there is no need to provide the user with additional information, e.g., description or type. This is because the associated JSON Schema provides the additional information. Use the template below as a starting point for a ROS node. + +```yaml +/**: + ros__parameters: + INSERT_PARAMETER_1_NAME: INSERT_PARAMETER_1_VALUE + INSERT_PARAMETER_N_NAME: INSERT_PARAMETER_N_VALUE ``` -- **Launch parameter file** - - Launch parameter files store the customized parameters for user's vehicle. - - For example, [the customized parameter of `behavior_path_planner` stored under `autoware_launch`](https://github.com/autowarefoundation/autoware_launch/tree/5fa613b9d80bf4f0db77efde03a43f7ede6bac86/autoware_launch/config) +The parameter file path is `INSERT_PATH_TO_PACKAGE/config/` and parameter file name is `INSERT_NODE_NAME.param.yaml`. To adapt the template to the ROS node, replace each `INSERT_...` and add all parameters `1..N`. + +See example: _Lidar Apollo Segmentation TVM Nodes_ [parameter file](https://github.com/autowarefoundation/autoware.universe/blob/main/perception/lidar_apollo_segmentation_tvm_nodes/config/lidar_apollo_segmentation_tvm_nodes.param.yaml) + +Note: `/**` is used instead of the explicit node namespace, this allows the parameter file to be passed to a ROS node which has been [remapped](https://design.ros2.org/articles/static_remapping.html). + +## Launch parameter file +(Original content, will need updating) +- Launch parameter files store the customized parameters for user's vehicle. + - For example, [the customized parameter of `behavior_path_planner` stored under `autoware_launch`](https://github.com/autowarefoundation/autoware_launch/tree/5fa613b9d80bf4f0db77efde03a43f7ede6bac86/autoware_launch/config) - Launch parameter files are stored under `autoware_launch`. -All the parameter files should have the `.param.yaml` suffix so that the auto-format can be applied properly. +## Declare Parameter Function +It is the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function which sets the parameter values during a node startup. + +```cpp +declare_parameter("INSERT_PARAMETER_1_NAME"), +declare_parameter("INSERT_PARAMETER_N_NAME") +``` +As there is no _default_value_ provided, the function throws an exception if a parameter were to be missing in the provided `*.param.yaml` file. Find the types in the table below. + +| ParameterType Enum | C++ Type | +| ------------------------- | -------------------------- | +| `PARAMETER_BOOL` | `bool` | +| `PARAMETER_INTEGER` | `int64_t` | +| `PARAMETER_DOUBLE` | `double` | +| `PARAMETER_STRING` | `std::string` | +| `PARAMETER_BYTE_ARRAY` | `std::vector` | +| `PARAMETER_BOOL_ARRAY` | `std::vector` | +| `PARAMETER_INTEGER_ARRAY` | `std::vector` | +| `PARAMETER_DOUBLE_ARRAY` | `std::vector` | +| `PARAMETER_STRING_ARRAY` | `std::vector` | + +The table has been derived from [Parameter Type](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/ParameterType.msg) and [Parameter Value](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/ParameterValue.msg). + +See example: _Lidar Apollo Segmentation TVM Nodes_ [declare function](https://github.com/autowarefoundation/autoware.universe/blob/f85c90b56ed4c7d6b52e787570e590cff786b28b/perception/lidar_apollo_segmentation_tvm_nodes/src/lidar_apollo_segmentation_tvm_node.cpp#L38) + +## Tips and Tricks +Using well established standards enables the use of conventional tooling. Below is an example of how to link a schema to the parameter file(s) using VS Code. This enables convenient features such as auto-complete and parameter bound validation. + +In the root directory of where the project is hosted, create a `.vscode` folder with two files; `extensions.json` containing + +```json +{ + "recommendations": [ + "redhat.vscode-yaml" + ] +} +``` + +and `settings.json` containing + +```json +{ + "yaml.schemas": { + "./INSERT_PATH_TO_PACKAGE/schema/INSERT_NODE_NAME.schema.json": "**/INSERT_NODE_NAME/config/*.param.yaml" + } +} +``` + +The RedHat YAML extension enables validation of YAML files using JSON Schema and the `"yaml.schemas"` setting associates the `*.schema.json` file with all `*.param.yaml` files in the `config/` folder. From ae75f5f1a3bcd922ad401a905155bc289b90e351 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 12 May 2023 14:53:19 +0000 Subject: [PATCH 2/5] style(pre-commit): autofix --- .../coding-guidelines/ros-nodes/parameters.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/contributing/coding-guidelines/ros-nodes/parameters.md b/docs/contributing/coding-guidelines/ros-nodes/parameters.md index c5f5a856b6d..3a30c1d00ac 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/parameters.md +++ b/docs/contributing/coding-guidelines/ros-nodes/parameters.md @@ -1,11 +1,14 @@ # Parameters + Autoware ROS nodes have declared parameters which values are provided during the node start up in the form of a parameter file. All the expected parameters with corresponding values should exist in the parameter file. Depending on the application, the parameter values might need to be modified. Find more information on parameters from the official ROS documentation: + - [Understanding ROS 2 Parameters](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.html) - [About ROS 2 Parameters](https://docs.ros.org/en/humble/Concepts/About-ROS-2-Parameters.html) ## JSON Schema + [JSON Schema](https://json-schema.org/understanding-json-schema/index.html) is used the validate the parameter file(s) ensuring that it has the correct structure and content. Using JSON Schema for this purpose is considered best practice for cloud-native development. The schema template below shall be used as a starting point when defining the schema for a ROS node. ```json @@ -30,10 +33,7 @@ Find more information on parameters from the official ROS documentation: "INSERT_BOUND_CONDITION(S)": "INSERT_BOUND_VALUE(S)" } }, - "required": [ - "INSERT_PARAMETER_1_NAME", - "INSERT_PARAMETER_N_NAME" - ] + "required": ["INSERT_PARAMETER_1_NAME", "INSERT_PARAMETER_N_NAME"] } }, "properties": { @@ -56,21 +56,25 @@ The schema file path is `INSERT_PATH_TO_PACKAGE/schema/` and the schema file nam See example: _Lidar Apollo Segmentation TVM Nodes_ [schema](https://github.com/autowarefoundation/autoware.universe/blob/main/perception/lidar_apollo_segmentation_tvm_nodes/schema/lidar_apollo_segmentation_tvm_nodes.schema.json) ### Attributes + Parameters have several attributes, some are required and some optional. The optional attributes are highly encouraged when applicable, as they provide useful information about a parameter to the user. **Required** + - name - type - see [JSON Schema types](http://json-schema.org/understanding-json-schema/reference/type.html) - description **Optional** + - default - a tested and verified value, see [JSON Schema default](https://json-schema.org/understanding-json-schema/reference/generic.html) - bound(s) - type dependent, e.g., [integer](https://json-schema.org/understanding-json-schema/reference/numeric.html#integer), [range](https://json-schema.org/understanding-json-schema/reference/numeric.html#range) and [size](https://json-schema.org/understanding-json-schema/reference/object.html#size) ## Parameter File + The parameter file is minimal as there is no need to provide the user with additional information, e.g., description or type. This is because the associated JSON Schema provides the additional information. Use the template below as a starting point for a ROS node. ```yaml @@ -87,18 +91,22 @@ See example: _Lidar Apollo Segmentation TVM Nodes_ [parameter file](https://gith Note: `/**` is used instead of the explicit node namespace, this allows the parameter file to be passed to a ROS node which has been [remapped](https://design.ros2.org/articles/static_remapping.html). ## Launch parameter file + (Original content, will need updating) + - Launch parameter files store the customized parameters for user's vehicle. - For example, [the customized parameter of `behavior_path_planner` stored under `autoware_launch`](https://github.com/autowarefoundation/autoware_launch/tree/5fa613b9d80bf4f0db77efde03a43f7ede6bac86/autoware_launch/config) - Launch parameter files are stored under `autoware_launch`. ## Declare Parameter Function + It is the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function which sets the parameter values during a node startup. ```cpp declare_parameter("INSERT_PARAMETER_1_NAME"), declare_parameter("INSERT_PARAMETER_N_NAME") ``` + As there is no _default_value_ provided, the function throws an exception if a parameter were to be missing in the provided `*.param.yaml` file. Find the types in the table below. | ParameterType Enum | C++ Type | @@ -118,15 +126,14 @@ The table has been derived from [Parameter Type](https://github.com/ros2/rcl_int See example: _Lidar Apollo Segmentation TVM Nodes_ [declare function](https://github.com/autowarefoundation/autoware.universe/blob/f85c90b56ed4c7d6b52e787570e590cff786b28b/perception/lidar_apollo_segmentation_tvm_nodes/src/lidar_apollo_segmentation_tvm_node.cpp#L38) ## Tips and Tricks + Using well established standards enables the use of conventional tooling. Below is an example of how to link a schema to the parameter file(s) using VS Code. This enables convenient features such as auto-complete and parameter bound validation. In the root directory of where the project is hosted, create a `.vscode` folder with two files; `extensions.json` containing ```json { - "recommendations": [ - "redhat.vscode-yaml" - ] + "recommendations": ["redhat.vscode-yaml"] } ``` From de7541e01dcebef4c398679c864be3c2996302e9 Mon Sep 17 00:00:00 2001 From: kaspermeck-arm Date: Thu, 1 Jun 2023 14:56:20 -0700 Subject: [PATCH 3/5] Chapter refactor, workflow and rationale Signed-off-by: kaspermeck-arm Change-Id: I8b2fee98c497037d3293e70747bb162b9a640895 --- .../coding-guidelines/ros-nodes/parameters.md | 129 ++++++++++-------- 1 file changed, 75 insertions(+), 54 deletions(-) diff --git a/docs/contributing/coding-guidelines/ros-nodes/parameters.md b/docs/contributing/coding-guidelines/ros-nodes/parameters.md index f353dc113f2..0928e48a84d 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/parameters.md +++ b/docs/contributing/coding-guidelines/ros-nodes/parameters.md @@ -7,6 +7,79 @@ Find more information on parameters from the official ROS documentation: - [Understanding ROS 2 Parameters](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.html) - [About ROS 2 Parameters](https://docs.ros.org/en/humble/Concepts/About-ROS-2-Parameters.html) +## Workflow + +A ROS package which uses the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function should: + +* use the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) with out a default value +* create a parameter file +* create a schema file + +The rationale behind this workflow is to have a verified single source of truth to pass to the ROS node and to be used in the web documentation. The approach reduces the risk of using invalid parameter values and makes maintenance of documentation easier. This is achieved by: + +* [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) throws an exception if an expected parameter is missing in the parameter file +* the schema validates the parameter file in the CI and renders a parameter table, as depicted in the graphics below + + ```mermaid + flowchart TD + NodeSchema[Schema file: *.schema.json] + ParameterFile[Parameter file: *.param.yaml] + WebDocumentation[Web documentation table] + + NodeSchema -->|Validation| ParameterFile + NodeSchema -->|Generate| WebDocumentation + ``` + +* + +Note: a parameter value can still be modified and bypass the validation, as there is no validation during runtime. + +## Declare Parameter Function +It is the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function which sets the parameter values during a node startup. + +```cpp +declare_parameter("INSERT_PARAMETER_1_NAME"), +declare_parameter("INSERT_PARAMETER_N_NAME") +``` +As there is no _default_value_ provided, the function throws an exception if a parameter were to be missing in the provided `*.param.yaml` file. Use a type from the _C++ Type_ column in the table below for the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function, replacing _INSERT_TYPE_. + +| ParameterType Enum | C++ Type | +| ------------------------- | -------------------------- | +| `PARAMETER_BOOL` | `bool` | +| `PARAMETER_INTEGER` | `int64_t` | +| `PARAMETER_DOUBLE` | `double` | +| `PARAMETER_STRING` | `std::string` | +| `PARAMETER_BYTE_ARRAY` | `std::vector` | +| `PARAMETER_BOOL_ARRAY` | `std::vector` | +| `PARAMETER_INTEGER_ARRAY` | `std::vector` | +| `PARAMETER_DOUBLE_ARRAY` | `std::vector` | +| `PARAMETER_STRING_ARRAY` | `std::vector` | + +The table has been derived from [Parameter Type](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/ParameterType.msg) and [Parameter Value](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/ParameterValue.msg). + +See example: _Lidar Apollo Segmentation TVM Nodes_ [declare function](https://github.com/autowarefoundation/autoware.universe/blob/f85c90b56ed4c7d6b52e787570e590cff786b28b/perception/lidar_apollo_segmentation_tvm_nodes/src/lidar_apollo_segmentation_tvm_node.cpp#L38) + +## Parameter File +The parameter file is minimal as there is no need to provide the user with additional information, e.g., description or type. This is because the associated schema file provides the additional information. Use the template below as a starting point for a ROS node. + +```yaml +/**: + ros__parameters: + INSERT_PARAMETER_1_NAME: INSERT_PARAMETER_1_VALUE + INSERT_PARAMETER_N_NAME: INSERT_PARAMETER_N_VALUE +``` + +The parameter file path is `INSERT_PATH_TO_PACKAGE/config/` and parameter file name is `INSERT_NODE_NAME.param.yaml`. To adapt the template to the ROS node, replace each `INSERT_PARAMETER_..._NAME` and `INSERT_PARAMETER_..._VALUE` for all parameters. Each [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) takes one parameter as input. + +See example: _Lidar Apollo Segmentation TVM Nodes_ [parameter file](https://github.com/autowarefoundation/autoware.universe/blob/main/perception/lidar_apollo_segmentation_tvm_nodes/config/lidar_apollo_segmentation_tvm_nodes.param.yaml) + +Note: `/**` is used instead of the explicit node namespace, this allows the parameter file to be passed to a ROS node which has been [remapped](https://design.ros2.org/articles/static_remapping.html). + +## Launch parameter file +- Launch parameter files store the customized parameters for user's vehicle. + - For example, [the customized parameter of `behavior_path_planner` stored under `autoware_launch`](https://github.com/autowarefoundation/autoware_launch/tree/5fa613b9d80bf4f0db77efde03a43f7ede6bac86/autoware_launch/config) + - Launch parameter files are stored under `autoware_launch`. + ## JSON Schema [JSON Schema](https://json-schema.org/understanding-json-schema/index.html) is used the validate the parameter file(s) ensuring that it has the correct structure and content. Using JSON Schema for this purpose is considered best practice for cloud-native development. The schema template below shall be used as a starting point when defining the schema for a ROS node. @@ -57,7 +130,7 @@ See example: _Lidar Apollo Segmentation TVM Nodes_ [schema](https://github.com/a ### Attributes -Parameters have several attributes, some are required and some optional. The optional attributes are highly encouraged when applicable, as they provide useful information about a parameter to the user. +Parameters have several attributes, some are required and some optional. The optional attributes are highly encouraged when applicable, as they provide useful information about a parameter and can ensure the value of the parameter is within its bounds. #### Required @@ -73,61 +146,9 @@ Parameters have several attributes, some are required and some optional. The opt - bound(s) - type dependent, e.g., [integer](https://json-schema.org/understanding-json-schema/reference/numeric.html#integer), [range](https://json-schema.org/understanding-json-schema/reference/numeric.html#range) and [size](https://json-schema.org/understanding-json-schema/reference/object.html#size) -## Parameter File - -The parameter file is minimal as there is no need to provide the user with additional information, e.g., description or type. This is because the associated JSON Schema provides the additional information. Use the template below as a starting point for a ROS node. - -```yaml -/**: - ros__parameters: - INSERT_PARAMETER_1_NAME: INSERT_PARAMETER_1_VALUE - INSERT_PARAMETER_N_NAME: INSERT_PARAMETER_N_VALUE -``` - -The parameter file path is `INSERT_PATH_TO_PACKAGE/config/` and parameter file name is `INSERT_NODE_NAME.param.yaml`. To adapt the template to the ROS node, replace each `INSERT_...` and add all parameters `1..N`. - -See example: _Lidar Apollo Segmentation TVM Nodes_ [parameter file](https://github.com/autowarefoundation/autoware.universe/blob/main/perception/lidar_apollo_segmentation_tvm_nodes/config/lidar_apollo_segmentation_tvm_nodes.param.yaml) - -Note: `/**` is used instead of the explicit node namespace, this allows the parameter file to be passed to a ROS node which has been [remapped](https://design.ros2.org/articles/static_remapping.html). - -## Launch parameter file - -(Original content, will need updating) - -- Launch parameter files store the customized parameters for user's vehicle. - - For example, [the customized parameter of `behavior_path_planner` stored under `autoware_launch`](https://github.com/autowarefoundation/autoware_launch/tree/5fa613b9d80bf4f0db77efde03a43f7ede6bac86/autoware_launch/config) - - Launch parameter files are stored under `autoware_launch`. - -## Declare Parameter Function - -It is the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function which sets the parameter values during a node startup. - -```cpp -declare_parameter("INSERT_PARAMETER_1_NAME"), -declare_parameter("INSERT_PARAMETER_N_NAME") -``` - -As there is no _default_value_ provided, the function throws an exception if a parameter were to be missing in the provided `*.param.yaml` file. Find the types in the table below. - -| ParameterType Enum | C++ Type | -| ------------------------- | -------------------------- | -| `PARAMETER_BOOL` | `bool` | -| `PARAMETER_INTEGER` | `int64_t` | -| `PARAMETER_DOUBLE` | `double` | -| `PARAMETER_STRING` | `std::string` | -| `PARAMETER_BYTE_ARRAY` | `std::vector` | -| `PARAMETER_BOOL_ARRAY` | `std::vector` | -| `PARAMETER_INTEGER_ARRAY` | `std::vector` | -| `PARAMETER_DOUBLE_ARRAY` | `std::vector` | -| `PARAMETER_STRING_ARRAY` | `std::vector` | - -The table has been derived from [Parameter Type](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/ParameterType.msg) and [Parameter Value](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/ParameterValue.msg). - -See example: _Lidar Apollo Segmentation TVM Nodes_ [declare function](https://github.com/autowarefoundation/autoware.universe/blob/f85c90b56ed4c7d6b52e787570e590cff786b28b/perception/lidar_apollo_segmentation_tvm_nodes/src/lidar_apollo_segmentation_tvm_node.cpp#L38) - ## Tips and Tricks -Using well established standards enables the use of conventional tooling. Below is an example of how to link a schema to the parameter file(s) using VS Code. This enables convenient features such as auto-complete and parameter bound validation. +Using well established standards enables the use of conventional tooling. Below is an example of how to link a schema to the parameter file(s) using VS Code. This enables a developer with convenient features such as auto-complete and parameter bound validation. In the root directory of where the project is hosted, create a `.vscode` folder with two files; `extensions.json` containing From 88f1d594c5c6e1beaca20fdddbd3f50c7fc988fe Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 1 Jun 2023 21:58:52 +0000 Subject: [PATCH 4/5] style(pre-commit): autofix --- .../coding-guidelines/ros-nodes/parameters.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/contributing/coding-guidelines/ros-nodes/parameters.md b/docs/contributing/coding-guidelines/ros-nodes/parameters.md index 0928e48a84d..551c798b2ac 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/parameters.md +++ b/docs/contributing/coding-guidelines/ros-nodes/parameters.md @@ -11,36 +11,38 @@ Find more information on parameters from the official ROS documentation: A ROS package which uses the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function should: -* use the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) with out a default value -* create a parameter file -* create a schema file +- use the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) with out a default value +- create a parameter file +- create a schema file The rationale behind this workflow is to have a verified single source of truth to pass to the ROS node and to be used in the web documentation. The approach reduces the risk of using invalid parameter values and makes maintenance of documentation easier. This is achieved by: -* [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) throws an exception if an expected parameter is missing in the parameter file -* the schema validates the parameter file in the CI and renders a parameter table, as depicted in the graphics below +- [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) throws an exception if an expected parameter is missing in the parameter file +- the schema validates the parameter file in the CI and renders a parameter table, as depicted in the graphics below ```mermaid flowchart TD NodeSchema[Schema file: *.schema.json] ParameterFile[Parameter file: *.param.yaml] WebDocumentation[Web documentation table] - + NodeSchema -->|Validation| ParameterFile NodeSchema -->|Generate| WebDocumentation ``` -* +* Note: a parameter value can still be modified and bypass the validation, as there is no validation during runtime. ## Declare Parameter Function + It is the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function which sets the parameter values during a node startup. ```cpp declare_parameter("INSERT_PARAMETER_1_NAME"), declare_parameter("INSERT_PARAMETER_N_NAME") ``` + As there is no _default_value_ provided, the function throws an exception if a parameter were to be missing in the provided `*.param.yaml` file. Use a type from the _C++ Type_ column in the table below for the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function, replacing _INSERT_TYPE_. | ParameterType Enum | C++ Type | @@ -60,6 +62,7 @@ The table has been derived from [Parameter Type](https://github.com/ros2/rcl_int See example: _Lidar Apollo Segmentation TVM Nodes_ [declare function](https://github.com/autowarefoundation/autoware.universe/blob/f85c90b56ed4c7d6b52e787570e590cff786b28b/perception/lidar_apollo_segmentation_tvm_nodes/src/lidar_apollo_segmentation_tvm_node.cpp#L38) ## Parameter File + The parameter file is minimal as there is no need to provide the user with additional information, e.g., description or type. This is because the associated schema file provides the additional information. Use the template below as a starting point for a ROS node. ```yaml @@ -76,6 +79,7 @@ See example: _Lidar Apollo Segmentation TVM Nodes_ [parameter file](https://gith Note: `/**` is used instead of the explicit node namespace, this allows the parameter file to be passed to a ROS node which has been [remapped](https://design.ros2.org/articles/static_remapping.html). ## Launch parameter file + - Launch parameter files store the customized parameters for user's vehicle. - For example, [the customized parameter of `behavior_path_planner` stored under `autoware_launch`](https://github.com/autowarefoundation/autoware_launch/tree/5fa613b9d80bf4f0db77efde03a43f7ede6bac86/autoware_launch/config) - Launch parameter files are stored under `autoware_launch`. From a3276f6d8a3fd2b7f7e5235145fcba23742e8860 Mon Sep 17 00:00:00 2001 From: kaspermeck-arm Date: Fri, 2 Jun 2023 07:17:59 -0700 Subject: [PATCH 5/5] Removed typo Signed-off-by: kaspermeck-arm Change-Id: Ie5f412f11ac96f6a389dca814dee755deeb231bf --- docs/contributing/coding-guidelines/ros-nodes/parameters.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/contributing/coding-guidelines/ros-nodes/parameters.md b/docs/contributing/coding-guidelines/ros-nodes/parameters.md index 551c798b2ac..53f5f058da2 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/parameters.md +++ b/docs/contributing/coding-guidelines/ros-nodes/parameters.md @@ -30,8 +30,6 @@ The rationale behind this workflow is to have a verified single source of truth NodeSchema -->|Generate| WebDocumentation ``` -* - Note: a parameter value can still be modified and bypass the validation, as there is no validation during runtime. ## Declare Parameter Function