DevOps Dojo: ROS Node Configuration - ROS Node Parameter Coding Guidelines

[kaspermeck-arm]

Autoware documentation (web)

• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/parameters/

Autoware documentation (repo)

• https://github.com/autowarefoundation/autoware-documentation/blob/main/docs/contributing/coding-guidelines/ros-nodes/parameters.md
• I suggest we move the Launch parameter file bullet point to
  • https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/launch-files/
    Note: We will keep the original content here and update at a later point once we've made progress on DevOps Dojo: ROS Node Launch

Find proposed new coding guidelines below.

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 vaules 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
• About ROS 2 Parameters

JSON Schema

JSON Schema is used the validate the parameter file(s) ensuring that is 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.

{
  "$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

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
• description

Optional

• default
  • a tested and verified value, see JSON Schema default
• bound(s)
  • type dependent, e.g., format, range and 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.

/**:
  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

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.

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
  • Launch parameter files are stored under autoware_launch.

Declare Parameter Function

It is the declare_parameter(...) function which sets the parameter values during a node startup.

declare_parameter<INSERT_TYPE>("INSERT_PARAMETER_1_NAME"),
declare_parameter<INSERT_TYPE>("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<uint8_t>
PARAMETER_BOOL_ARRAY	std::vector<bool>
PARAMETER_INTEGER_ARRAY	std::vector<int64_t>
PARAMETER_DOUBLE_ARRAY	std::vector<double>
PARAMETER_STRING_ARRAY	std::vector<std::string>

The table has been derived from Parameter Type and Parameter Value.

See example: Lidar Apollo Segmentation TVM Nodes declare function

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

{
    "recommendations": [
        "redhat.vscode-yaml"
    ]
}

and settings.json containing

{
  "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.

Edit: added link for Lidar Apollo Segmentation TVM Node schema, parameter and the declare function
Edit2: added content from Launch parameter file

[kaspermeck-arm]

Add:

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.

to current proposal. Then it's complete.