Skip to main content

Implement Your Component Software Interface (CSI)

Well, you've generated some code with Tangram Pro™. So, now what? How about taking the Component Software Interface (CSI) for a test drive? After all, the whole point of the CSI is to quickly connect Components with a reliable, reusable interface so that you can focus on developing your applications rather than managing the interactions between them.

You'll learn how to:

  • Describe a CSI
  • Create a local testing environment
  • Leverage your CSI generated by Tangram Pro™
  • Run an end-to-end test of your CSI
  • Visualize the program's behavior with OpenAMASE

What is a CSI?#

A CSI is a lot like an application program interface (API) for an embedded system Component. To be sure, there are differences. Rather than thinking of web servers and enterprise applications, you might think of navigation, autonomy, and sensor Components on a UAV. The CSI is all the code needed to support the sending and receiving of a particular group of messages belonging to a shared message standard between Components, or even across message standards when combined with Transforms.

In Tangram Pro™, message standards, such as LMCP, OMS, and STANAG4586 provide a type information required to generate the CSI for that message set. However, Components rarely use every message in a standard. That's why you specify a Component's Type in Tangram Pro™.

When you apply the Code Gen 3.0 plug-in via a Workflow to a Component, Code Gen 3.0 does all the heavy lifting for you. The message standard and the C++ (or Java) objects representing the messages you selected when defining the Component Type establish the parameters of the setter and getter functions to be used in the CSI. The generated CSI will not only include the appropriate setter and getter functions for the specified messages, but will also contain the necessary transport libraries (ZeroMQ, ActiveMQ, RabbitMQ, or Kafka), the Makefile, and serialization/de-serialization libraries so that the messages can be sent and received. Packaging all of this up into a set of executables means you can spend your development time on the Components themselves, rather than the connections between them.

Of course, in these tutorials, the example system and number of messages sent is rather small. Yet, the UAS Communication Component's CSI, is now part of a Tangram Pro™ Component Library: searchable, reusable, and scalable. Any CSI in an organization's instance of Tangram Pro™, no matter how large or small the number of messages, becomes part of a digital supply chain that doesn't just enable the building of different systems, it enables systems to be built differently. With each new integration, the CSI for a Component can be leveraged to enable the innovation necessary to meet mission demands.

Step 1: Create a Testing Environment for your CSI#

First, you need to set up your testing environment. To do this you are going to create an Ubuntu 20.04 virtual machine (VM) using VirtualBox.

note

If you are already using a Linux machine that is running Ubuntu, you many want to skip to Step 3. Before you do, be sure to download these files:

To download VirtualBox#

  1. Navigate to the VirtualBox Downloads page
  2. Click the appropriate download for your host machine, either Windows hosts or OS X hosts
  3. Click Open to open the downloaded file and launch the VirtualBox installer
  4. Double Click VirtualBox.pkg and follow the prompts to complete VirtualBox installation
  5. Launch the VirtualBox application

With VirtualBox installed you are nearly ready to create the Ubuntu 20.04 VM. But let's make sure you have an Ubuntu image with long term support (LTS).

To download Ubuntu 20.04 LTS#

  1. Navigate to the Ubuntu Downloads page
  2. Click the green Download button to download the Ubuntu 20.04 LTS image

Great! Now let's head back to VirtualBox and set up that VM to use as a testing environment.

tip

As you set up your VM in VirtualBox, use the name Tangram CSI Test to mirror the remainder of the instructions below.

To create a Ubuntu 20.04 VM with VirtualBox on Mac OS#

If your host machine is using Mac OS, please refer to this video for step by step instructions:

To create a Ubuntu 20.04 VM with VirtualBox on Windows#

If your host machine is using Windows, please refer to this video for step by step instructions:

Whew! You are almost there. If you are unfamiliar with setting up an Ubuntu image on a VM that may have felt like a lot of steps to get your testing environment created. Hopefully, it was a smooth process. Now you should see your Tangram CSI Test VM listed in the OracleVMVirtualBox Manager.

tip

Be sure to add the VirtualBox Guest Additions Image. If you missed it in the videos, installing the VirtualBox Guest Additions will allow you to go full screen with your VM while retaining resolution and create shared folders. To add VirtualBox Guest Additions, run this command from the VM terminal:

sudo apt install build-essential dkms linux-headers-$(uname -r)

Then,

  1. In the VirtualBox menu click Devices
  2. Click Insert Guest Additions CD Image...
  3. Restart the Tangram CSI Test VM

Step 2: Create Shared Folders#

With your Tangram CSI Test VM up and running, it will be helpful to configure some important settings that will be used later. Creating shared folders will allow the VM to recognize folders from your host machine to be used by the Tangram CSI Test VM. Let's add some shared folders!

To add shared folders#

  1. In the OracleVMVirtualBox Manager select Tangram CSI Test
  2. Click the Settings icon
  3. Click the Shared Folders icon
  4. Click the Add new shared folder icon on the far right

This will open a dialogue box where you can specify the specific shared folder path from your host machine and the mount point for the VM.

  1. Download this OpenUxAS scenario folder to your host machine
  2. Click the Folder Path dropdown mend and select Other...
  3. Select the OpenUxAS folder you just downloaded
  4. Check Auto Mount
  5. Click OK
  6. Click OK

Repeat this process for the UAS Communication Component. The Component works as is, sending both the AirVehicleState and AirVehicleConfiguration messages using a Tangram Pro™ generated CSI, but you'll use your CSI to run the test in just a bit.

  1. Download the UAS Communication Component folder to your host machine
  2. Within the OracleVM click the Add Shared Folder icon on the far right
  3. Click the Folder Path dropdown mend and select Other...
  4. Select the UAS Communication Component folder you just downloaded
  5. Check Auto Mount
  6. Click OK
  7. Click OK

Repeat this process one last time and add the Tangram Pro™ code-gen-3/ folder you downloaded from Tangram Pro™ in the last tutorial.

  1. Within the OracleVM click the Add Shared Folder icon on the far right
  2. Click the Folder Path dropdown mend and select Other...
  3. Select the code-gen-3/ folder you downloaded earlier
  4. Check Auto Mount
  5. Click OK
  6. Click OK

Step 3: Add Prerequisites#

There are a few tools your VM will need to set up your testing environment and successfully run the end to end test.

To add the necessary prerequisites to your VM#

  1. Open Terminal in the Tangram Test CSI VM
  1. From the VM Terminal run the following command to install the first prerequisite:
sudo apt-get install ant

Following the example above, run the following commands to instal the other prerequisites.

sudo apt-get install openjdk-11-jdk
sudo apt-get install git
sudo adduser $USER vboxsf

Step 4: Clone and build the OpenAMASE repository#

With the prerequisites in place, the next step is to clone the OpenAMASE repository and verify that the application will build.

What is OpenAMASE?#

Developed by the Air Force Research Laboratory, Aerospace System Directorate, Power and Control Division, OpenAMASE is "a simulation toolset for the analysis and demonstration of aircraft automation and autonomy. OpenAMASE includes the necessary components to create scenarios, simulate aircraft with basic EO/IR cameras, and interact with control algorithms to command aircraft in a scenario."

This means it is an accessible tool, ideal for the purpose of running a end-to-end test of your Tangram Pro™ CSI. Using OpenAMASE will allow you to see a simulated UAV communicating the AirVehicleState and AirVehicleConfiguration LMCP messages via an UAS Communication Component to two other simulated UAVs.

note

For a full description of OpenAMASE, check out the OpenAMASE README.md.

To clone and build the OpenAMASE repository#

  1. In the Tangram CSI Test VM terminal run the following command to clone the OpenAMASE repository
git clone https://github.com/afrl-rq/OpenAMASE.git && cd OpenAMASE
  1. Change directories with the following command in the VM terminal
cd OpenAMASE
  1. Build the the code with the following command in the VM terminal
ant jar
  1. Now, verify that the OpenAMASE application will run with the following commands in the VM terminal
cd run/linux
sh Common.sh "--config" "config/amase"

At this point OpenAMASE will build and you'll see the application running.

Step 5: Select an OpenAMASE scenario#

Now you are going to take advantage of the OpenUxAS shared folder you created earlier. This shared folder contains an example scenario that is much more interesting than the default scenarios in OpenAMASE.

To select a scenario in OpenAMASE#

  1. Click File
  2. Select Open Scenario in the dropdown menu
  3. Click the dropdown menu next to the listed file path
note

The file path for the scenario will be in the format /home/< virtual machine user name >/OpenAMASE/OpenAMASE

  1. Select /
  2. Scroll down in the Folders menu and double click /media
  3. Double click sf_OpenUxAS/
  4. Double click examples/
  5. Double click 02_Example_WaterwaySearch
  6. In the Files menu select Scenario_WaterwaySearch
  7. Click Ok
  8. Click the Go button to run the scenario

A much better scenario don't you think? UAV 400 and UAV 500 are hovering in Nav Mode Loiter at different altitudes and conducting a search. But where is the Tangram UAV?

Step 6: Implement your Tangram Pro™ CSI#

Now you are going to leverage your CSI to test whether the UAS Communication Component is able to send the AirVehicleState and AirVehicleConfiguration messages.

To edit the UAS Communication Component to leverage your CSI#

  1. Click the Files icon in the VM sidebar on the left
  2. Click the sf_uas_communication_comp folder
  3. Double Click Makefile
  4. Locate LMCP_CSI_DIR on line 9 and GENERICAPI_DIRcpp on line 10
  5. Delete the existing file path that follows the ?= operator for both lines
  6. Add the file path of your Tangram Pro™ code-gen-3/ folder to replace the previous file path referenced by LMCP_CSI_DIR
  7. Add the file path of your code-gen-3/genericapi_cpp folder to replace the previous file path referenced by GENERICAPI_DIRcpp
  8. Click Save
  9. Close the Makefile

Step 7: Run and end to end test of your Tangram Pro™ CSI#

With the UAS Communication Component now referencing your CSI from the code-gen-3 folder, it is time to run an end to end test of the CSI.

To run the UAS Communication Component#

  1. Click the Terminal icon in the VM sidebar on the left
  2. Click the + icon to open an additional Terminal tab
  3. Change directories by running the following command:
cd /media/sf_uas_communication_component
  1. Run the UAS Communication Component with the following command:
./lmcp_sender

At this point, you should see the starting, serializing, and sending of the AirVehicleState and AirVehicleConfiguration messages to by the UAS Communication Component in the terminal window. Let's take a look at this in OpenAMASE.

To visualize the behavior of the system with OpenAMASE#

  1. With the application still running, click the OpenAMASE icon in the VM sidebar on the left
  2. if the OpenAMASE scenario timed out, click the Go button to restart it

And there it is! The Tangram UAV leveraging the CSI you generated with Tangram Pro™ to send the required AirVehicleConfiguration and AirVehicleState messages.

Cheers!#

By completing this tutorial, you've learned to implement the CSI generated by Tangram Pro™ in a local testing environment!

Check out what you accomplished:

  • Created a local testing environment with VirtualBox and Ubuntu 20.04 LTS
  • Leveraged the CSI generated by Tangram Pro™ to communicate the specified messages
  • Ran an end to end test of the CSI
  • Visualized the behavior of your simple system using OpenAMASE

If you want to know more about CSIs in Tangram Pro™, take a look at our blog posts.

note

Check out Discuss, our Tangram Flex community and find out more about generating CSIs with a CSIP.

Appendix#

Additional items available in Tangram Pro™, but not discussed in this tutorial

  • CSIs using Java outputs
  • Transforms
  • CSI transport brokers and dependency outputs