Solution Design

Autoware pipeline

The Autoware pipeline of the Actuation Demo is the Planning simulation from the “Ad hoc” tutorial of Autoware. It can be launched with the actuation_demos package, which contains the appropriate launch scripts.

The package has been copied from the autoware_launch package of Autoware, taking a subset of files from it. Its “control” launch file has been modified to accommodate for the specific needs of the Actuation Demo.

Actuation Service

The Actuation Service provides the Safety Island feature of the Actuation Demo.

It spawns a Pure Pursuit node and waits for termination of the program.

Zephyr configuration

The project configuration options are split into several prj.conf files in order to avoid duplication of the options when used for different purposes. The files are:

prj_actuation.conf:

Contains the core options. It configures the Zephyr libc used, the common networking options (IPv4, net sockets, UDP and network buffers), the threads and the memory.

boards/<BOARD>_actuation.conf:

Board-specific configurations that get used along with prj_actuation.conf.

prj_net.conf:

Contains options specific to the network configuration. It configures the L2 layer and static IP addresses.

prj_loopback.conf:

Contains options specific to a loopback network driver usage. It configures the loopback driver and the localhost IP address.

The core configuration file is meant to be used by setting the cmake CONF_FILE variable. The other configuration files are meant to be used by setting the cmake OVERLAY_CONFIG variable. The selection process of the configuration files is explained in Zephyr’s Initial Configuration.

Devicetree overlays

The Zephyr app uses devicetree overlays to enable the board-specific devices defined in the platform’s DTS. They are placed in boards/ and meant to be discovered automatically by the Zephyr build system.

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.

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.

Additionally, this package translates the message types between the Autoware pipeline and Pure Pursuit.

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.