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.