.. # Copyright (c) 2022-2023, Arm Limited. # # SPDX-License-Identifier: Apache-2.0 ############### Solution Design ############### .. image:: ../images/actuation_overview.svg :align: center .. _Autoware pipeline: ***************** 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: ***************** 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/_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: ***************** 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 ---------------------- .. list-table:: Conversion table :header-rows: 1 * - 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.