UMAA CASE+CODE

UMAA Standard

Latest Version: 6.0 Distro D(CUI controlled)
UMAA standard referenced: 5.2.1 (Public) Download from AUVSI

The UMAA standard defines the following(as of 6.0):

• Data model(>200 data types in an IDL format)
• No QOS (Exception: Large Collections- PRESENTATION)
• Required Topics(“Interfaces”) per “Service”.
• Application level:
  • Command state machine/handshaking("Flow Control")
  • Large data set synchronization("Large Collections")
  • Type inheritance("Generic/Specified Types")

The UMAA standard also defines some "Components", which are a collection of "Interfaces" derived from the UMAA MBSE model. These Components are currently not for public release and are not required as of 6.0.

Overview

The intention of this initial Case+Code release was to provide some reference examples focusing on the Connext infrastructure/various API’s interacting, and minimizing setup friction with some utilities:

• XML App Creation used with the following API's
  • Python API
  • Modern C++ with DynamicData Types
  • Modern C++ with Compiled Types
• CMAKE file using rticonnextdds-cmake-utils modules for code generation of large type sets
• Recommended best practices for assigning QOS to topics
• XML Debug snippets
• Utilities
  • Windows: Convert recursively to XML for 6.2.1 compatibility
  • Linux: Convert recursively to XML plus flatten includes to single folder

The application level requirements are outside of the current scope but we hope for this to be an ongoing development as we democratize best practices/lessons learned across our various customers.

Use Cases

Systems

1. I want to configure/manage all of my DDS entities external to the source code by just looking up entities defined in XML. This will minimize boilerplate code, provide a configuration layer, and minimize configuration conflicts. XML App Creation
2. I want to filter the messages coming into my application based on the UMAA Destination ID. This can be configurable and require no compilation to change. Content Filtered Topics
3. I want to convert my UMAA IDL files to xml and flatten the includes to a single folder, generating a composite includes file in the process. This is so I can pull types into either System Designer or other modeling tools, use with DynamicData, or include when disabling type propagation. XML Scripts

Software

1. I want to develop using the Modern C++ API, Compiled Types, and XML App Creation. Modern CPP Compiled Types
2. I want to develop using the Modern C++ API, DynamicData Types, and XML App Creation. Modern CPP DynamicData Types

Test/Simulation

1. I want to develop using the Python API, DynamicData Types, and XML App Creation. Python DynamicData Types
2. I want to index into a subtype inside of a sequence using the Python API and DynamicData. DynamicData indexing

Build Tools

1. I want to use CMAKE and rtiddsgen to build a shared library of UMAA types using modules created by RTI as reference. CMAKE modules

Infrastructure

1. I want to have a "black box" recording running on my vehicle and capturing selected DDS traffic. Recording Service

XML App Creation

These example applications simulate a few components using types and services from the public UMAA 5.2.1 standard. The intention here was to minimize application code and highlight the ease of access to the writers/readers and their usage.

NOTE: These components are purely for reference purposes(UMAA defined components are not public yet).

The resources/umaa_components.xml file contains the configurations for the behavior(QOS), topics, domains and types of the Connext databus.

It takes advantage of Connext’s XML-Based Application Creation framework to define and manage all of the messaging entities with XML files.

Prerequisites

• Linux-based OS or WSL.
• Connext 7.3.0/Python API setup for Python Scripts

Tested compatibility

• Ubuntu 20.04
• Connext 6.1.2/Connext 7.3.0

Cloning Repository

To clone the repository you will need to run git clone as follows to download both the repository and its submodule dependencies:

git clone --recurse-submodule https://github.com/rticommunity/rticonnextdds-usecases-umaa.git

If you forget to clone the repository with --recurse-submodule, simply run the following command to pull all the dependencies:

git submodule update --init --recursive

Configure

cd examples/
cmake -B build -DCMAKE_BUILD_TYPE=Release

Build

cmake --build ./build --config Release

NOTE: Will take ~ 15 minutes as it is compiling all the idl types into a shared library.

---

Modern CPP Compiled Types

anchor_controller

---

Options:

    -d, --domain     <int>     Domain ID this application will
                               subscribe in.
                               Default: 0
    -f, --file       <string>  XML Config file defining components
                               used to create DDS entities. 
                               Default: './resources/umaa_components.xml'
    -v, --verbosity  <int>     How much debugging output to show.
                               Range: 0-5 
                               Default: 0

Example:

./build/anchor_controller -f ./resources/umaa_components.xml

Overview:

The Anchor Controller app includes a simple state machine to manage "lowering and raising". It uses listeners to read data and can receive commands from either the gui.py application or Admin Console using
Graphical Data Publishing. NOTE: The commands don't follow the UMAA command state pattern("Flow Control") as that is outside the scope of this example.

Content Filtered Topics

By using Content Filtered Topics in tandem with XML-Application creation we are able to conveniently
filter messages destined for a specific data reader using the destination GUID field.

Reference the file umaa_components.xml for the section where the
"AnchorCommandReader" is defined.

You will see the filter defined in XML for a "GUID" value.

<data_reader name="AnchorCommandReader" topic_ref="UMAA::EO::AnchorControl::AnchorCommand">
    <!-- Here we are passing the Anchor Controller "GUID" to the Content Filter Topic
        so we only get messages addressed to this GUID
    -->
    <content_filter name="src" kind="builtin.sql">
        <!-- Can optionally use an ENV variable if desired
        <expression> destination = &amp;hex($(ANCHOR_CONTROLLER_GUID)) </expression> -->
        <expression>
            destination = &amp;hex(05 05 05 05 05 05 05 05 05 05 05 05 05 05 05 05)
        </expression>
    </content_filter>
    <datareader_qos base_name="UMAAQOSLibrary::AnchorCommandQOS"/>
</data_reader>

Topics:

Subscribers	Publishers
	UMAA::EO::AnchorStatus::AnchorReport
	UMAA::EO::AnchorControl::AnchorCommandStatus
UMAA::EO::AnchorControl::AnchorCommand

Back to Use Cases

---

Modern CPP DynamicData Types

autonomy

---

Options:

    -d, --domain     <int>     Domain ID this application will
                               subscribe in.
                               Default: 0
    -f, --file       <string>  XML Config file defining components
                               used to create DDS entities. 
                               Default: './resources/umaa_components.xml'
    -v, --verbosity  <int>     How much debugging output to show.
                               Range: 0-5 
                               Default: 0

Example:

./build/autonomy -f ./resources/umaa_components.xml

Overview:

The Autonomy app looks for a few different topics to have writers publishing for it to have "comms" to the Anchor Controller and NavData applications. (Namely: "AnchorReport", and "SpeedStatus")

It also looks for the "Anchor Payout" value to be 0, to indicate the Anchor is raised and ready for a mission.

It uses DynamicData types and a waitset to read it's data. It also uses listeners to pickup events from the databus such as "subscription_matched".

Topics:

Subscribers	Publishers
UMAA::EO::AnchorStatus::AnchorReport
UMAA::EO::AnchorControl::AnchorCommandStatus
UMAA::SA::SpeedStatus::SpeedReport

Back to Use Cases

---

Python DynamicData Types

nav_data

---

Options:

  -h, --help            Show this help message and exit
  -s INT, --source INT  Integer used to generate a source "GUID"
  -f FILE, --file FILE  XML Config file path

Example:

python ./python/nav_data.py -f ./resources/umaa_components.xml

Overview:

This example looks up multiple writers per a specific component, generates and populates the source "GUID", and publishes arbitrary values referencing the same XML file that defines
our system using XML App Creation.

Topics:

Subscribers	Publishers
	UMAA::SA::SpeedStatus::SpeedReport

---

---

gui

---

Options:

  -h, --help            Show this help message and exit
  -d INT, --dest INT    Integer used to generate a destination "GUID"
  -f FILE, --file FILE  XML Config file path
  -c INT, --command INT Anchor command enum value

Command Values:

• LOWER: 0
• RAISE: 1
• STOP: 2

Example for the "Lower" command:

python python/gui.py -c 0 -d 5

Overview:

This example generates and populates the destination "GUID" field and can be
used to send a command to the anchor controller application to "raise"/"lower".

This is to be used in tandem with the content filtering on the destination
field applied to the anchor controller application.

You should see the Anchor Controller app respond to these commands.
By changing the -d flag value you can test alternate values and verify
filtering of data.

Topics:

Subscribers	Publishers
	UMAA::EO::AnchorControl::AnchorCommand

---

---

gps

---

Options:

  -h, --help            Show this help message and exit
  -s INT, --source INT  Integer used to generate a source "GUID"
  -f FILE, --file FILE  XML Config file path

Example:

python python/gps.py

Overview:

This application instantiates a writer from a pre-defined XML file and publishes
arbitrary data utiliizing a generated source "GUID".

DynamicData indexing

This script features a basic example of how to index into a sequence of subtypes using the Python API
and DynamicData types

Topics:

Subscribers	Publishers
	UMAA::SEM::GPSStatus::GPSReport

Back to Use Cases

---

XML SCRIPTS

These scripts are meant to assist in your workflow when converting the idl files to xml.

Tested compatibility:

• UMAA IDL files: 6.0.1
• Ubuntu 20.04
• Windows 11
• Connext: 6.1.2, 7.3.0

LINUX

Configure

• Make sure you have followed the setup guide for your Connext installation, including setting the NDDSHOME variable.

• Set the environment variable $UMAA_TYPES to the target folder:

export UMAA_TYPES="<PATH_TO_UMAA_IDL_REPO>"

NOTE: Ensure a pre-processor is in your PATH environment variable.
The default is cpp. Reference the RTI code generator documentation for more info.

Usage

Generate in place:

scripts/convert_umaa_xml.sh

• Convert idl files recursively through all sub folders
• Place xml file in same location as idl file.

Flatten to /xml folder:

scripts/convert_umaa_xml.sh flatten

• Convert idl files recursively through all sub folders
• Generate the xml files into an /xml folder relative to the $UMAA_TYPES directory.
• Edit include paths to remove folders (Example: "./umaa_type.idl")

---

WINDOWS

Configure

• Make sure you have followed the setup guide for your Connext installation,
  including setting the NDDSHOME variable by running the setup script.

• Set the environment variable %UMAA_TYPES% to the target folder:

SET UMAA_TYPES="<PATH_TO_UMAA_IDL_REPO>"

NOTE: Ensure a pre-processor is in your PATH environment variable.*
The default is cp.exe. Reference the RTI code generator documentation for more info.

Usage

Generate in place:

scripts/convert_umaa_xml.bat

• Convert idl files recursively through all sub folders
• Place xml file in same location as idl file.

Back to Use Cases

---

---

CMAKE modules

This repo pulls in a git submodule from rticonnextdds-cmake-utils into the /examples/resources folder.

The rticonnextdds-cmake-utils repo provides convenient CMAKE utils to call rtiddsgen and pass in idl files as an argument. Use /examples/CMakeLists.txt as a reference for creating a shared library for your UMAA IDL set.

Back to Use Cases

---

---

Recording Service

Connext includes a recording service that can capture selected DDS traffic and store in a SQLite database to allow for playback/conversion at a later date.

[Recording Service Manual] (https://community.rti.com/static/documentation/connext-dds/7.3.0/doc/manuals/connext_dds_professional/services/recording_service/index.html)

A reference config file has been created to cover 2 scenarios "deploy" and "debug" with some assumptions made for both.

Usage

• You can use the rtisetenv*.sh scripts located in PATH_TO_CONNEXT_INSTALL/resource/scripts/ to put the bin folder into your PATH.

Start Recording in "Deploy" mode:

<PATH_TO_CONNEXT_INSTALL>/bin/rtirecordingservice -cfgName deploy -cfgFile <PATH_TO_FILE>/umaa_record.xml

Start Recording in "Debug" mode:

<PATH_TO_CONNEXT_INSTALL>/bin/rtirecordingservice -cfgName debug -cfgFile <PATH_TO_FILE>/umaa_record.xml

Back to Use Cases

---

---