Transformers

A transformer receives payloads from a device and computes observations that are stored and visualized.

Transformer Program Format

The Control Center allows you to dynamically create transformers that are written in JavaScript.

To do this, two JS functions must be defined, transform, and test.

Transform Function

The primary purpose of the transformer is performed by its transform function.

This function, named transform, takes four parameters and should return a JS value that can be encoded using JSON.stringify.

The parameters are documented in the table below:

Pos	Name	Type	Description
1	time	string	An 8601 ISO timestamp representing the time the payload was produced (if available), or received.
2	nwkAddr	number	An integer containing the nwkAddr of the device.
3	fPort	number	An integer containing the LoRaWAN FPort value for the payload. Some devices may use this to specify the type of payload that was transmitted.
4	payload	string	A string containing the actual payload, encoded as a Base64 value.

Test Function

To allow testing transformers, a testing function should be provided. This function must be named test, take zero arguments, and returns a boolean indicating if the tests were successful.

Example

The following code block specifies a complete transformer program and test.

function transform(time, nwkAddr, fPort, payload) {
  var payloadBytes = atob(payload);
  if (payloadBytes.length >= 7 && parseInt(payloadBytes.charCodeAt(2)) === 0) {
      var pressure = ((parseInt(payloadBytes.charCodeAt(3)) << 8) | parseInt(payloadBytes.charCodeAt(4)));
      var range = 2000.0; // Sensor range
      var density = 1.0;  // A density of 1 is water
      var height = ((pressure - 1638.3) * range) / (13106.4 * density);
      var temp = ((parseInt(payloadBytes.charCodeAt(5)) << 8) | parseInt(payloadBytes.charCodeAt(6))) / 1000;
      return {"time": time, "nwkAddr": nwkAddr, "height": height, "temperature": temp};
  } else {
      return [];
  }
}

function test() {
  var tests = {
    "reading one": [
      transform("2019-03-29T06:02:04.539Z", 65959, 15, "AacABdxfoCQ="),
      { time: "2019-03-29T06:02:04.539Z", nwkAddr: 65959, height: -21.10419337117743, temperature:24.48 }
    ],

    "reading two": [
      transform("2018-03-29T06:02:04.539Z", 62959, 12, "AacAEdxfoCQ="),
      { time: "2018-03-29T06:02:04.539Z", nwkAddr: 62959, height: 447.6744186046512, temperature:24.48 }
    ]
  };

  var testFailures = Object
    .keys(tests)
    .map(function(test) {
      return { name: test, actual: JSON.stringify(tests[test][0]), expected: JSON.stringify(tests[test][1]) };
    })
    .filter(function(test) {
      return test.actual !== test.expected;
    });

  return testFailures.length === 0 ? true :
    "[" + testFailures[0].name + "] [" + testFailures[0].actual + "] did not equal expected value [" + testFailures[0].expected + "]";
}

Creating a Transformer

To create a transformer, follow the steps below:

1. Select Settings from the left-hand navigation.
2. Select Transformers from the section navigation.
3. Select New from the right-hand part of the page.
4. A form will now appear prompting for the name, device type, observation type, and transformer program. Fill out the form, and be sure to refer to the above documentation that describes the required program format.
5. If desired, select Test on the right-hand side of the screen to run your test function. When satisfied, continue below.
6. Select Save. The transformer should now appear in the listing.

Editing a Transformer

To edit a transformer, follow the steps below:

1. Select Settings from the left-hand navigation.
2. Select Transformers from the section navigation.
3. Find the transformer you wish to modify, and select its row. Alternatively, you can select the gear icon, followed by Edit.
4. Modify the form as required.
5. If desired, select Test on the right-hand side of the screen to run your test function. When satisfied, continue below.
6. Select Save.

Removing a Transformer

To remove a transformer, follow the steps below:

1. Select Settings from the left-hand navigation.
2. Select Transformers from the section navigation.
3. Find the transformer you wish to delete, and select the gear icon, followed by Delete. The transformer should now be removed from the listing.