Skip to main content

Write a Direct Device Analyzer

Read the MQTT and device-connection sections before implementing an Analyzer. AirNgin also provides Lab tools that can help you test Analyzer behavior before final approval.

This page describes the Direct Device Analyzer model. Gateway-mediated Child Devices use a different architecture: downlink protocol translation belongs to the Gateway Driver, and an optional Gateway Analyzer is uplink-only.

JSON basics​

JSON is a structured text format made of objects, arrays, and key/value pairs. AirNgin uses JSON extensively for logical Device commands and state.

Device-to-server Analyzer​

When a Direct Device sends manufacturer-specific data that does not already match the AirNgin logical model, the receive Analyzer converts that payload into the Operation/Command model.

The current server-side Analyzer contract uses a JavaScript function named main.

function main(inputJsonString, outputJsonString) {
  var inputJson = JSON.parse(inputJsonString);
  var outputJson = JSON.parse(outputJsonString);

  outputJson.result = 'OK';
  outputJson.status.push({key: 'CHANNEL_NAME', value: 'COMMAND'});

  if (outputJson.status.length === 0 && inputJson.status !== undefined) {
    outputJson.status = inputJson.status;
  }

  return JSON.stringify(outputJson);
}
  • inputJsonString is the payload received from the Device.
  • outputJsonString is the server-provided output template.
  • result indicates the Analyzer result.
  • status contains logical {key, value} records where key is the AirNgin operationName and value is the canonical Command value.

A typical output is:

{
  "result": "OK",
  "status": [
    {"key": "ch1", "value": "on"}
  ]
}

The manufacturer payload can be any format that your Analyzer understands—for example pole1on, ch1on, or JSON. The Analyzer's job is to convert that manufacturer format into the AirNgin logical model.

Server-to-device Analyzer​

For the legacy Direct Device Analyzer path, a separate JavaScript function can convert an AirNgin logical command to the manufacturer protocol expected by the Device.

function main(inputJsonString) {
  var inputJson = JSON.parse(inputJsonString);
  var output = '';

  switch (inputJson.operationName) {
    case 'ch1':
      if (inputJson.value === 'on') output = 'pole1on';
      else if (inputJson.value === 'off') output = 'pole1off';
      break;
    case 'ch2':
      if (inputJson.value === 'on') output = 'pole2on';
      else if (inputJson.value === 'off') output = 'pole2off';
      break;
  }

  return JSON.stringify(output);
}

The server input has the logical identity and Command value:

{
  "deviceSerial": "AIRN1234567890",
  "operationName": "ch1",
  "value": "on"
}

The Direct Device server then delivers the Analyzer output to the target Device in the appropriate server-to-device envelope.

Important boundaries​

  • The Analyzer must map to Operations and Commands that really exist in the Device definition.
  • Do not invent logical Operations locally.
  • Keep security-sensitive data out of Analyzer source and output.
  • Direct Device Analyzer behavior must not be copied to the Gateway downlink path; Gateway Drivers own native command translation.