Conversion
The Conversion Agent Component provides a mechanism to take telemetry messages from one source and convert them into a different format. This allows for easily publishing telemetry message in a single format across different types of robot which may have different native data sources. In particular, this is important for converting telemetry topics to be compatible with some specific message formats which are recognised by the Robot Automation Portal, for example: geometric transforms which are used for binding 3D objects when rendering a robot in its environment.
The Conversion Agent Component needs Agent Version 1.6+
The general function of the Conversion component is to subscribe to a specific telemetry topic. Each time a message is received on this topic, some rules are applied to the incoming message - each rule consists of some transformational processing which results in one or more different messages being published on one or more different topics.
A single instance of the Conversion component may have multiple different rules applied at once, meaning that it may subscribe any number of different input topics, and generate any number of different output topics. Accordingly, conversion rules maybe used to condense messages from many topics into a single aggregating topic, or to split messages out from a single topic into separate topics.
Configuration
To use the Conversion component, your agent will need a section in its agent-settings.json file which enables the conversion component, as shown below. For more information on how to configure the agent components, see Agent Configuration.
...
"components": [
...
{
"enabled": false,
"id": "conversion",
"settings": {
"name": "cpu",
"logLevel": 4,
"messageParserTimeout": "250ms",
"topicTemplateTimeout": "250ms",
"schemas": {
"cpu_schema": "{\"$id\": \"%[1]s\",\"$schema\": \"https://json-schema.org/draft-07/schema#\",\"type\": \"object\",\"properties\":{\"cpu\": {\"type\": \"number\"}}}"
},
"rules": {
"cpu_rule": {
"enabled": true,
"preset": "custom",
"messageParser": "var result = [];var output = {};output.cpu = $msg.cpu;result.push(output);result;",
"payloadSchemaName": "cpu_schema",
"source": "/rocos/agent/proc",
"topicTemplate": "var result = \"cpu\";result;"
}
}
}
},
...
]
The conversion component understands the following configuration parameters. Generally, you should not need to modify these settings:
| Name | Description | Default | Unit |
|---|---|---|---|
enabled | Whether to enable the conversion component or not. | false | |
name | How this instance of the conversion plugin should be named. | "conversion" | |
logLevel | The logging verbosity: 1 - very quiet, 6 - very talkative. | 4 | |
messageParserTimeout | Because the messageParser is executed within a JavaScript environment, a timeout can be applied to the templating operation to prevent the conversion from becoming stuck on a particular message. | "250ms" | |
topicTemplateTimeout | Because the topicTemplate is executed within a JavaScript environment, a timeout can be applied to the templating operation to prevent the topic name generation from becoming stuck on a particular message. | "250ms" | |
schemas | Define schemas for the custom messages that will be published. See below. | ||
rules | Define the rules for how to handle messages from the source subscription topics. See below. |
Schemas
The conversion component requires that you define the schemas for the messages that will be published by the component, so that the Robot Automation Portal knows what data is available, and the expected format. The schemas property is a collection which maps the name of a published topic to the intended schema for that topic. An example of a schemas section is shown below:
"schemas": {
"cpu_schema": "{\"$id\": \"%[1]s\",\"$schema\": \"https://json-schema.org/draft-07/schema#\",\"type\": \"object\",\"properties\":{\"cpu\": {\"type\": \"number\"}}}"
},
In this example, the key is the string "cpu_schema" and the value is a string containing a schema definition. This schema definition only defines a single property called "cpu" for the resulting message payload.
Rules
The conversion component requires definitions for the rules that it should follow. The rules define how to subscribe to source telemetry topics and how to convert the incoming messages into output messages. Each rule requires a number of parameters to be configured:
| Name | Description | Default |
|---|---|---|
enabled | Whether the rule is enabled or not. | true |
preset | The preset identifier for this rule. The options are: - ros_tf_transforms- spot_transforms- custom | "custom" |
messageParser | A JavaScript template that will be used to parse the source message. | |
payloadSchemaName | The schema to use. This value is looked up in the schemas collection (see the Schemas section above). | |
source | The source subscription topic that provides the source data. | |
topicTemplate | A JavaScript template that is run with the parsed message where the result of running the template is the topic name that the data will be published against. |
Data Model
The conversion component will publish topics based on the rules enabled in the component settings. The payload for each of the published topics is defined in the schemas section of the component settings and is generated by running the messageParser template. The topic name for the published data is generated from running the topicTemplate with each parsed message.
Once this process has completed for a message, each parsed message is then published with the generated topic name.
Source Message Parsing
The messageParser JavaScript template inputs and outputs are described below.
Inputs:
| Name | Description |
|---|---|
$msg | The source message received from the source topic. |
$meta | Metadata related to the source message. |
Outputs:
The output of the messageParser must be an array containing all parsed messages. The structure for each output message must match the schema defined for the rule used for this source.
Topic Generation
The topicTemplate JavaScript template inputs and outputs are described below.
Inputs:
| Name | Description |
|---|---|
$msg | Each message in the array output of the messageParser JavaScript template. |
Outputs:
The output of the topicTemplate JavaScript template is a string that should be used as the topic name to which the parsed message should be published against.