Automated Dynamic Downlinks

Learn how to create dynamic downlinks and send them automatically when measured values change.

Introduction

You can link downlink functions created on Datacake with one or more fields, which then serve as triggers for automated sending. This behaves as follows.

If a new measured value is written into one of the linked fields, no matter if by uplink of the sensor or API call, the downlink function (encoder) is called automatically and depending on the execution the downlink is transmitted to the LNS.

This function can be used for various reasons.

• Asking the user for input for configuration parameters (e.g. changing the transmit interval of a sensor with any input).

• Repeating a downlink if the previous response from the sensor transmitted an actual value that was different from the target value.

• Automated sending of dynamic downlinks (e.g. in connection with a slider widget on the dashboard or foreign measured value of an external sensor).

• Automation between different sensors.

In this article, we will show you how to use this feature on Datacake, and how to customize or extend existing downlinks.

Dynamic Downlinks

You can also access measurement or configuration fields in a downlink encoder and use their current values to create dynamic downlinks.

Scope

In the following examples, we use Datacake devices of the LoRaWAN type. Of course, the examples are also valid for downlinks of type MQTT or Particle.

Database Access

Before we continue with the setup of automated triggers, we need to briefly explain how you can use Fields and Measured Values as well as Configuration Fields in the Downlink Encoder code.

Measurements

Take a look at the following code example. It shows you how to access measured values stored in the database.

function Encoder(measurements, port) {
  var interval = measurements["CONFIG_REPORTING_INTERVAL"].value;
  return [0x01, interval];
}

When executing the above code, the current value of the field 'CONFIG_REPORTING_INTERVAL' is read, stored in a variable, and finally passed directly to the return value of the downlink encoder.

The above example is very minimalistic. However, you can access multiple measurements simultaneously and perform calculations. It is also possible to perform time-based operations, e.g. to check whether the downlink is within a certain time frame. See the following for a more detailed example.

Hexadecimal vs. integer

In order for a downlink to be sent, the encoder function must return a byte sequence in the form of an array (e.g. return [0x01, 0x02, 0xFF, 18, 23]).

Here it is not necessary to convert each element to a hex value in advance. You can pass an integer value directly if needed, or combine hex values with integers. The Datacake backend performs the conversion to hexadecimal or Base64 (depending on the LNS) automatically.

Configuration fields

The above example also works for configuration fields and looks like this.

function Encoder(measurements, port) {
  var interval = configurationValues["CONFIG_REPORTING_INTERVAL"];
  return [0x01, interval];
}

Why Configuration Fields?

Configuration fields or values offer the advantage that they are defined at the product level, and the user can define a default value that then applies to all devices in the product, even if new ones are created. This default value can be overwritten and set individually on the device as required.

Learn more about Configuration Fields in the following part of our documentation.

Configuration Fields

Example

The following screenshot shows you how an exemplary use of the code in a downlink encoder might look like.

Linkage of Fields

In order for a downlink to be sent automatically when one or more fields are changed, the fields must be linked to the downlink.

To do this, you must add the respective fields via an input mask in the downlink editor, as shown on the following screenshot.

Click on the input texbox and type the first letters of your field. You will only see the first five results, so you should refine your search a bit if you don't find the field right away.

Enable triggering

The downlink is not automatically executed by the linkage alone.

Only when you put a checkmark in the "Trigger on Measurements" field, a change in the field will cause the downlink to be executed automatically. See the the following screenshot for an example.

So what happens without triggering?

If you do not activate triggering, but you link measurement fields with the downlink, then the user will be asked for the current value via an input mask before sending the downlink, or must confirm the current value of the field.

Using values without link and trigger?

Even if you have not linked a field to the downlink and/or have not activated triggering, measured values and configuration fields can still be used in the downlink encoder.

When the downlink is then called manually (via button, rule or API), the current measured value of the field or the value of the configuration field is read and still used in the code of the encoder.

This means that you do not have to link a field to a downlink to use its value in the encoder's code.

Usage of Triggering

Checking Setpoints

Let's assume you use downlinks for sending new configuration to a sensor. In doing so, a desired state is transmitted to the sensor and the sensor responds either immediately or within the next regular transmission, also sending the current configuration.

You can now extend the decoder of your sensor and store the information sent by the sensor about its configuration in an extra field.

Let us now imagine that this configuration is the transmission frequency.

For an automatic comparison of the setpoint and actual value as well as resending a downlink in case of deviation, we need the following database and configuration fields

1. field in the database for Interval, which is linked to a dynamic downlink and used as trigger (e.g. DOWNLINK_SEND_INTERVAL_SETPOINT).

2. configuration field with Interval as it has been set in the cloud (our nominal value, e.g. SEND_INTERVAL_SETPOINT)

In the decoder of the device, you perform a comparison between the value that is transmitted by the sensor (actual value) and the one that has been stored in the cloud as the target value.

On the downlink, you link the downlink field and activate the automated triggering option.

If there is a deviation between configuration stored on the sensor and the setpoint on Datacake, you write the value of the configuration field (target value) into the downlink field via the decoder, which then sends the downlink automatically (due to triggering).

Examples

Automation based on Measurement Values

function Encoder(measurements, port) {

    var fillLevel = measurements["FILL_LEVEL"].value;
    var downlink = []

    if (fillLevel > 80) {
        
        downlink = [0x00, 0x80];

    } else if (fillLevel > 60) {

        downlink = [0x00, 0x60];

    } else if (fillLevel > 30) {

        downlink = [0x00, 0x30];

    } else {
        
        return; // don't send any downlink
    }

    return downlink;
}