Configuring an NKE device for batch reporting

NKE devices support two different reporting modes: standard reporting and batch reporting. In standard reports, every time an attribute is measured on the devices, the device will make a decision if the value should be sent and if positive, it is sent immediately over the LoRaWAN network. Batch reporting works differently in that it collects multiple measurements across different measurement times and and attributes and sends them in a single, densely-packed message. Batch reporting allows for longer battery runtime with the same number of messages at the cost of an increased delay until measured data gets delivered to the thingsHub. This article provides a brief introduction into Batch reporting and how to configure this advanced reporting mode using the thingsHub’s configuration and state management.

Standard reporting

But before we dive into Batch Reporting, let’s recapitulate Standard Reporting quickly. A simple configuration for standard reporting on an In’O device can be seen in the following configuration excerpt:

{
  "binary_input": {
    "0": {
      "present_value": {
        "standard_config": {
          "maximum_reporting_interval": "10m",
          "minimum_reporting_interval": "0s",
          "reportable_change": true
        }
      }
    },
    "1": {
      "count": {
        "standard_config": {
          "maximum_reporting_interval": "10m",
          "minimum_reporting_interval": "0s",
          "reportable_change": 1
        }
      }
    }
  }
}

The configuration enables endpoints 0 and 1 of the binary input cluster. On endpoint 0, the attribute present_value is configured to report the current state of the circuit. The value reportable_change is true, which indicates that an uplink is sent as soon as the circuit is switched, though not faster than the duty cycle allows ("minimum_reporting_interval = "0s"). If the circuit did not get switched, an uplink will be sent at latest 10 minutes after the previous uplink ("maximum_report_interval" = "10m"). On endpoint 1, a very similar standard report is set, though here it is for the attribute count, which will send the total number of switches so far.

Note that the reporting of the two attributes is independent of each other, i.e. they are always sent in separate messages and one attribute's sending behavior does not affect when the other attribute will send its data. Finally, every message that is send with these reports contains 7 bytes of overhead which encode the endpoint (0 or 1 in our example), the cluster (binary_input), the attribute (present_value or count) and an attribute type (boolean for present_value, uint32 for count). This overhead information makes it easy to parse the incoming uplinks, as all required information is easily present in the uplink itself, i.e. the uplink is self-contained.

For many use cases neither the many, smaller messages nor the overhead is problematic, but in some use cases, under more limited conditions, this can be prohibitive. For that situation, NKE’s batch report feature can be used to encode data more densely into fewer uplink messages.

Batch reporting

To enable batch reporting for the above example, the following configuration can be used:

{
  "binary_input": {
    "0": {
      "present_value": {
        "batch_config": {
          "maximum_recording_interval": "10m",
          "minimum_recording_interval": "0s",
          "recordable_change": true,
          "resolution": 1,
          "tag_value": 0,
          "tag_size": 1
        }
      }
    },
    "1": {
      "count": {
        "batch_config": {
          "maximum_recording_interval": "10m",
          "minimum_recording_interval": "0s",
          "recordable_change": 1,
          "resolution": 1,
          "tag_value": 1,
          "tag_size": 1
        }
      }
    }
  }
}

In addition to adding this, it is recommended to switch of the standard reporting with the following configuration:

{
  "binary_input": {
    "0": {
      "present_value": {
        "standard_config": {
          "maximum_reporting_interval": "0s",
          "minimum_reporting_interval": "0s",
          "reportable_change": false
        }
      }
    },
    "1": {
      "count": {
        "standard_config": {
          "maximum_reporting_interval": "0s",
          "minimum_reporting_interval": "0s",
          "reportable_change": 0
        }
      }
    }
  }
}

Batch reporting will be functional, once all of these options are synchronized with the device, i.e. they show up in the device's state field on the Device’s network tab. A few difference between Batch Reporting and Standard Reporting are notable.

New configuration options and names

In batch reporting, the configuration options use the wording recording instead of reporting. This change is meant to highlight the fact that these time intervals do not affect the time when a report is send, but the time when a measurement is recorded. For standard reporting, there is no difference between these points of time, but for batch reporting, sending a report can happen considerably later than when the measurements were recorded that contribute to this report. Note that as a consequence, the uplink timing in batch reporting cannot be influenced directly as the report will always automatically be sent when there’s no more space for additional data in the next uplink message.

There are also three new configuration options which are not required for standard reporting, namely resolution, tag_value, and tag_size.

The resolution can be used to change the precision with which values are transmitted, e.g. if the sensor would usually measure temperature with a precision of 0.01°C, a resolution value of 1 can be used to tell the device to drop the decimal places when packing the batch report. Thereby, the value takes up less space in the batch report and more values can be transmitted in the same report.

The other two new options tag_value and tag_size come as a pair. They provide a more compact means to identify a measurement series' identity, than the 7 bytes that are used in standard reporting, namely cluster, attribute, endpoint, and field. With these smaller identifiers, more values can be packed into a single batch reporting message. The downside of this is that the server-side needs to keep a mapping from tags to the measurement series, to ensure the reported data can be interpreted correctly. Fortunately, drivers make this easier to manage for the user. All that’s needed to do is set the configuration via the thingsHub and follow a few basic rules about tags:

• Each measurement series that is to be encoded in a batch report needs to have a unique tag assigned to it

• The tag_values are usually assigned starting with 0, 1, …

• The tag_size is the number of bits that will be used to encode tag_values. The smaller this number is, the more efficient data can be packed into a batch report, i.e. a with a tag_size of 1, the tag_values 0 and 1 can be used, with a tag_size of 2, all tag_values up to 3 can be used, and with a tag_size of 3, tag_values can be used up to 7.

• Obviously, the tag_size must be chosen sufficiently large so that the number of desired measurement series fits into this.

In the above example, a tag_value of 0 is chosen for the present_value of endpoint 0 and a tag_value of 1 is chosen for the count of endpoint 1. This means a tag_size of 1 is sufficient to contain all tag labels. Note that the driver currently does not validate the consistency of the tags.