Message Converter

This is the design document for the actuation_message_converter package.

Purpose / Use cases

This package allows communication between the main pipeline (from autoware.universe) and the Pure Pursuit service (from Autoware.Auto) running in the Safety Island.

Data structure conversion

CycloneDDS provides a simple compiler for IDL files, generating C headers implementing the data structures. ROS2 uses its own IDL compiler that generates different data structures than the CycloneDDS compiler (specifically, the sequences and strings are implemented differently), as well as additional C files containing initialization code. The difference in data structures makes it impossible to simply use the ROS2 message types on the Autoware side and the CycloneDDS message types on the pure_pursuit side.

Message type conversion

This package translates the message types between the Autoware pipeline and Pure Pursuit. See the Inputs / Outputs / API paragraph below for details.

Domain separation

DDS participants discover all the other endpoints available in their DDS Domain. It results in allocating memory for each of those remote endpoints and keeping it allocated until their termination. This represents a very significant amount of memory for the constrained resources of the Safety Island sub-system. This package is used to bridge two different Domain IDs, one dedicated to the main pipeline and one for the Pure Pursuit service.

Design

This package generates both ROS2 message types and CycloneDDS message types from the message definitions used. Both are used by the node to translate an incoming message in one type to an output message in the other.

This node receives messages from Autoware nodes, and upon reception creates CycloneDDS messages to be sent using the CycloneDDS API to the pure_pursuit app. The same thing would then be done for translating back the messages emitted by the pure_pursuit app and sent to the right Autoware packages.

Assumptions / Known limits

The node is not generic. The code needs to be modified to accommodate for a change in the flow of messages.

The idlc compiler from CycloneDDS 0.8 doesn’t support default values for the message fields (it seems support was added on more recent versions). It is not a problem when the default values are 0, which is the case most of the time, but other default values need to be carefully handled when creating those messages, and messages that depend on them. Currently that is only the case for the w field of the Quaternion message, ultimately used in Trajectory and VehicleKinematicState, that should be default-valued to 1.

The idlc compiler from CycloneDDS doesn’t prevent multiple includes of the same file, leading to a re-definition of the Quaternion struct in our case. It needs to be worked around. The least intrusive way is by having a local Quaternion definition in Transform.

Inputs / Outputs / API

Conversion table
rosidl (Primary Compute)	idlc (Safety Island)
Odometry	VehicleKinematicState
Trajectory	Trajectory
AckermannControlCommand	VehicleControlCommand

Inner-workings / Algorithms

Message compilation

The Autoware messages to be translated are compiled to IDLC with the CycloneDDS compiler. Those messages, and their dependencies, are:

VehicleControlCommand (from the Safety Island)
- Time
Trajectory (CI->SI)
- TrajectoryPoint
  - Pose
    - Point
    - Quaternion
  - Duration
- Header
  - Time
VehicleKinematicState (to the Safety Island)
- TrajectoryPoint
  - Pose
    - Point
    - Quaternion
  - Duration
- Transform
  - Quaternion
  - Vector3
- Header
  - Time

Error detection and handling

The node aborts on any error code from the CycloneDDS API during initialization. A message is printed on any error code after CycloneDDS has been initialized.

Security considerations

Spoofing

The origin of the incoming messages does not matter.
Tampering

This package handles variable-length data structures: Incoming C strings are not parsed by the package, but rather left to CycloneDDS for handling. The length of incoming arrays is checked against the internal maximum length; if the incoming length is greater, the extra elements are silently ignored.
Repudiation

The actions of external actors should not affect this package.
Information disclosure

There is no information to disclose.
Denial of Service

The package relies on the DDS middleware to mitigate for Denial of Service threats.
Elevation of Privilege

There is no privileges to elevate.

Testing

This package translates messages format from ROSIDL to IDLC (from Autoware to the Safety Island) or from IDLC to ROSIDL (from the Safety Island to Autoware), depending on the message.

The unit test creates DDS participants around actuation_message_converter to simulate a full loop of Autoware -> Converter -> SI -> Converter -> Autoware. Where the Converter in bold is the functionality under test and the rest is the test-bench.

The goal is to evaluate the conversion, but also to ensure that the rest of the pipeline is working as intended.