Skip to main content

Author Transforms with Flex

The previous tutorials leveraged message-to-message transforms that are included with Tangram Pro™. But, if a component software interface needs a transform that is currently not included, a Tangram Pro™ user can define their own with Flex. In the broadest terms, a transform is like a function that accepts a data structure as input, modifies its values, and outputs a new data structure.

Flex Language Documentation is available at Flex Docs. For this tutorial, example Flex code is provided.

You'll learn how to:

  • Add support for your own transform using the Flex Code Editor

Step 1: Create a Flex Package

  1. Go to FlexLang in the top navigation bar
  2. Click on Package Manager and then the blue New button
  3. Enter a name for your package using the Namespace::PackageName format (e.g. Tutorial::Transforms), and choose an owner
  4. Click Create Package and wait for the Flex environment to load
  5. Create a new file by hovering over your package in the left side file viewer, clicking the File icon (the left icon next to your package)
  6. Enter the name "MyTransform.flex" and hit enter
  7. Paste the following code below the module name:
message struct PositionUS {
  latitudeDegrees : float64;
  longitudeDegrees : float64;
  altitudeFeet : float32;
}

message struct PositionMetric {
  latitudeRadians : float64;
  longitudeRadians : float64;
  altitudeMeters : float32;
}

transform US_to_Metric(i : PositionUS) -> PositionMetric {
  let pi : float64 = 3.14159265359;
  PositionMetric {
    latitudeRadians = pi * (i.latitudeDegrees / 180.0);
    longitudeRadians = pi * (i.longitudeDegrees / 180.0);
    altitudeMeters = i.altitudeFeet / 3.28084;
    };
 }

The first message PositionUS represents values in degrees and feet. The second message PositionMetric represents values in radians and meters. The transform US_to_Metric defines the relationship between these messages, taking PositionUS as input and outputting PositionMetric. A return keyword doesn't need to be included because the last expression of a transform is implicitly returned.

  1. Save the file by pressing the hot-key Ctrl + S / Cmd + S.
  2. Create a release of your new package by clicking the Create Release checkmark button above your package name in the left panel and then choosing Create Release r1 at the bottom right

Step 2: Use Transform in a Design

For a refresher on building a component-based design, go to Visualize a Project Design.

  1. Create a new project
  2. Add two components and update their names to be:
    • PositionUS
    • PositionMetric
  3. Add a transform object and place it anywhere
  4. Define the connection by clicking on PositionUS first, and then PositionMetric
  5. For the transform's Input Message, select your custom package and message PositionUS
  6. For the transform's Output Message, select your custom package and message PositionMetric
  7. Click the Apply Transform button. This is your Flex Transform!

Step 3: Generate Transform Code

  1. Click Build in your project
  2. Select the Transform item in the list
  3. Choose Generate Transform in its dropdown menu
  4. Click Build
  5. Download the generated code. Extract and open the folder.
  6. Open the gen folder. You should see a file called MyTransform.cpp. This was generated as a result of the transform that you defined in your custom Flex package.
  7. Open the MyTransform.cpp file. Take a look at the code and see that there is a C++ function called US_to_Metric. This is your Flex transform function transpiled into C++.

Further Exploration

  • Go to FlexLang, view the Package Manager, and open the package called Transforms::LmcpV3MavlinkV23::v1. Review each of its Flex files to see additional transform examples. These transforms convert LMCP messages to MAVLink messages.
  • Open your Flex file, and add another transform to convert in the other direction "Metric_to_US". This time converting radians to degrees, and meters to feet. Publish the changed Flex specification. Update your components to use the new version and change the In/Out directions. Delete the transform between the components, and reconnect them in the other direction. Generate Transform code and see how the changes you made to Flex affect the resulting C++ function.

Cheers!

By completing this tutorial you learned how to:

  • Use Tangram Pro™ to define and use a custom transform definition to build component-based systems.
  • Generate transform code from a custom Flex package.