Device Communication IoTGW

Send and receive data

In order to translate payload to and from the Managed IoT Cloud resource values we use two functions called downlink transform and uplink transform. These functions are defined for each thing type, so IoT Gateway devices with different payload formats should thus use different thing types. The topmost field in the edit thing type form is the uplink transform function and the bottom one is the downlink transform function.

You should only define the function body of the transform functions, and not the function header.

Uplink transform

The uplink transform function determines how to decode a device payload into a thing state. The function takes two arguments port and payload which is the data sent from the device. In addition you have access to a Parser object from the binary-parser library which can decode binary data into a json object. The function should return an object with keys corresponding to resource names.

An example uplink transform function could look like this:

var parser = new Parser()
  .endianess("little")
  .bit4("major_v")
  .bit2("minor_v")
  .bit2("patch_v")
  .string("temperature", { zeroTerminated:true })
  .string("humidity", { zeroTerminated:true })
  .string("pressure", { zeroTerminated:true });

return parser.parse(payload);

It assumes the device sends data where the first four bits should be translated to the major_v resource, the next two bits to minor_v resource and the two bits after that to patch_v resource. They are followed by three zero terminating strings of arbitrary length, translated to temperature, humidity, and pressure resources respectively. See the binary parser library for further documentation.

Downlink transform

The downlink transform function determines how to encode the data going from the thing state into a device payload. The function takes one argument state which is the thing state object. It must return an object with four keys, port which is an integer value, payload which is an array of bytes and/or zero terminated strings, transport which can either be coap-push or coap-pull and coapPath which determines the CoAP path.

When using coap-pull as transport:

The message will be queued and sent as a response to a CoAP GET request from the device. The device is responsible for polling the backend.

When using coap-push as transport:

The message will be sent to the device immediately as a CoAP POST to the path specified in the coapPath parameter. The device must be running a CoAP server for this to work.

An example downlink transform function that mirrors the above uplink transform function could look like this:

payload = [
  state.patch_v << 6 | state.minor_v << 4 | state.major_v,
  state.temperature, 0,
  state.humidity, 0,
  state.pressure, 0
];

return {
  transport: "coap-push",
  coapPath: "/foo",
  port: 5683,
  payload: payload
};

As demonstrated, you need to construct the individual bytes yourself if the resource values are not of byte-size length. There is no corresponding helper binary-encoder-type library at this time that helps us to construct the individual bytes from the state object.

Error Reporting

Sometimes errors occur in the transform functions. Some information about the last error is reported through two resources named uplink_transform_error and downlink_transform_error. In the device dashboard create a non-settble value widget for each of these resources.