Chapter 3

Transforms

Edge processing via “Transforms”

GATE-Ware can be configured to apply custom transforms to the LoRa uplink payload. This is useful for performing custom operations on the LoRa uplink data, and even selectively transmitting only the data that you want to keep.

Why process data in a costly cloud service?

You can use custom transforms to convert the payload to a different format, or to perform calculations on the payload, or even perform actions directly on the gateway.

We’ve even had customers write transforms that perform lengthy calculations and averages, moving most of their business logic out of the cloud and onto the Conduit - reducing backend costs a by a great amount.

Built-In Transforms

Use Transforms without even creating one

GATE-Ware comes packages with common Transforms built right in. The great thing about Built-In transfroms is that using them requires only a configuration change. Built-Ins available to you immediately are:

Forward

Configure selective forwarding of data.

Discard

Configure discarding of data.

Text

Convert LoRa uplink data to ASCII for human readability.

> Click here for steps toward configuring Built-In transforms

Custom Transforms

The Basics

Custom transform can be written in any language that can be executed from the command line. The transform program must be executable and must return a JSON object. In order to implement a Custom Transform, two components are necessary:

  1. The custom transform source itself.
  2. An entry in the GATE-Ware configuration file.

To get you started, some custom transform examples have been placed in the transforms/ directory, with an accompanying configuration example.

Example

For example, to run the transforms/bash_examples/insert_uuid.sh custom transform on any messages to AppEUI 2b-7e-15-16-28-ae-d2-a5 on LoRa Port 5, add the following to your gateware.json:

{
  "gateware_uplink_transforms": [
    {
      "appeui": "2b-7e-15-16-28-ae-d2-a5",
      "lora_ports": [
        {
          "port": 5,
          "action": "external_handler",
          "external_handler": "transforms/bash_examples/insert_uuid.sh",
          "external_handler_timeout_seconds": 1
        }
      ]
    }
  ]
}

The sections below discuss the general I/O behind Custom Transforms, as well as a method for discarding and timing out if processing goes too long.

Input

The input to your custom transform is delivered as a JSON object via stdin.

The JSON object comes directly from the Conduit and follows the specification of the Up Message Format.

Output

The output of your custom transform must be valid JSON returned via stdout.

Discarding A Message

If you wish to discard a message, simply do not return any stdout.

Timeout

The custom transform will be terminated if it does not return a valid JSON object within the specified external_handler_timeout_seconds.