Configuration Fields

Configuration Fields allow you to create static variables that have a product-wide default and can be overwritten per device.

Abstract

Configuration Fields can be used for example if you have a large fleet of the same devices, where individual devices need to be configured with an individual value, for example a threshold.

Create a Configuration Field

Configuration Fields can be found in the Device's configuration at the bottom of the "Fields" panel. Create a new field by clicking the "Add Configuration Field" button on the top right.

This will open a modal where you can define the properties of the field:

Type

You can choose between Number (which can store Integers as well as Floats), String and Boolean.

Once a field has been created, you can not change the type of the field.

Name

This is the display name of the field, which has no strict requirements about the used characters.

Identifier

The identifier can only contain letters, numbers and underscores. It is unique per product and by default pre-populated from the entered name.

Once a field has been created, you can not change the identifier of the field.

Description

An optional description, can be used to explain the effect of the value to the user.

Unit

An optional unit, can be used to make the expected value more clear.

Default Value

This is the value of every device that has no explicit overwrite.

Using Configuration Fields

Overview of existing configuration fields

In the above example, I have created a field with the identifier TEST_FIELD and a default value of 2. The (x) icon next to the value indicates that this is the default value, and the device has not set an explicit overwrite.

Changing the value for a single device

To set a value for a device different from the default, use the context-menu on the right and choose "Set Value". This will open a modal where you can set a value and also reset the value to the Product's default value.

Using Configuration Fields in en- and decoders

Configuration Values are available both in decoders as well as encoders (to configure downlinks) via the global configurationValues variable. It's an object with the field identifier as key and the value as value.

An example decoder using the previously created variable could look like this:

function Decoder(bytes, port) {

    var configuredValue = configurationValues.TEST_FIELD;
    
    // configured value can now be used to modify the payload which we are not doing in this simple example
    
    return [
        {
            field: "MY_FIELD",
            value: configuredValue,
        }
    ]
}

Configuration Fields in Downlink Encoders

Configuration Fields can be used on Downlinks for a variety of things. See the following example on how to access those fields in your Downlink Decoder.

The following example is valid for all Datacake device types.

Code

function Encoder(device, measurements) {
    
    // Read configuration field value
    var downlinkSerial = configurationValues["DOWNLINK_SERIAL"]
    
    if (downlinkSerial === "0") {
        console.log("Serial is not set for downlinks!")
        return;
    }
    
    var status = measurements.CONTROL_FIELD.value;
    
    var payload = {
        "serial": downlinkSerial,
        "command": 3,
        "value": status ? 1:0
    }
    
    return {topic: 'device/down', payload: JSON.stringify(payload)};
}

Notes

In the example above, there is no need to access configuration fields using a Datacake UUID (as shown in the examples below for decoders). This is because, on Downlinks, the encoder is initiated on the Datacake frontend or rule engine. Hence, we already know the device on which the downlink needs to run.

Therefore, no device addressing is needed, and the configuration value is fetched from the scope automatically.

Configuration Fields on MQTT Decoders

Datacake provides a flexible way to handle incoming data from devices using MQTT or HTTP integrations. By using payload decoders, Datacake allows you to adapt to any incoming payload format without needing to modify the third-party payload. This is particularly useful for customers using their own serial numbers to identify devices.

Configuration fields in Datacake can hold static values and be customized per device level. These fields are accessed within payload decoders using the Datacake UUID, which allows the retrieval of specific configuration settings and measurements. The following guide will walk you through the process of using configuration fields in combination with MQTT payload decoders.

Step-by-Step Guide

Setup Configuration Fields in Datacake

• Navigate to the device's settings in Datacake.

• Add a configuration field (e.g., Temperature Offset) with a unique identifier (TEMPERATURE_OFFSET). Set a default value, which can be overridden at the device level if necessary.

Example from the screenshots.

• Name: Temperature Offset

• Identifier: TEMPERATURE_OFFSET

• Type: Number

• Default Value: 2

Define MQTT Topics and Payloads

Your device will send data to a specific topic. For example, devices/mycustomserial01/data, where mycustomserial01 is the custom serial number of the device.

Example Payload:

{"temp": 23.45}

Create an MQTT Payload Decoder in Datacake

In the payload decoder, write a function to handle the incoming MQTT data. This function will parse the payload, retrieve configuration values, and compute the desired output.

Example Decoder Function:

function Decoder(topic, payload) {
    // Convert MQTT payload to JSON
    var data = JSON.parse(payload);
    
    // Extract custom serial number from topic
    var serialNumber = topic.split("/")[1];
    
    // Get UUID for custom serial number
    var datacakeUUID = deviceSerialToId[serialNumber];
    
    // Access configuration value from device using UUID
    var tempOffset = configurationValues[datacakeUUID]["TEMPERATURE_OFFSET"];
    
    // Optional: Access the current stored measurement value
    var oldTemp = measurements[datacakeUUID]["TEMPERATURE"].value;
    
    // Read new temperature from JSON and add configuration value offset
    var newTemp = data.temp + tempOffset;
    
    // Store the new value only if it has changed
    if (oldTemp != newTemp) {
        return [
            {
                device: serialNumber, // Use custom Serial Number or Device UUID
                field: "TEMPERATURE",
                value: newTemp
            }
        ];
    }
}

Explanation of the Decoder Function

• Parsing the Payload: The payload sent from the device is converted to a JSON object using JSON.parse(payload).

• Extracting Serial Number: The serial number is extracted from the MQTT topic, which helps map the custom serial number to the Datacake UUID using a predefined mapping (deviceSerialToId).

• Accessing Configuration Values: The Datacake UUID is used to access the configuration values specific to that device. In this case, the TEMPERATURE_OFFSET is retrieved and used to adjust the incoming temperature reading.

• Handling Measurements: The current temperature stored in the Datacake platform is accessed to compare with the new temperature reading. This comparison ensures that only changed values are updated, minimizing unnecessary storage and processing.

• Returning the Updated Value: If the temperature has changed, the function returns the updated temperature value, which Datacake will store.

Summary

Accessing configuration fields is summarized within the following code concept:

// Access configuration value from device using UUID
var tempOffset = configurationValues[datacakeUUID]["TEMPERATURE_OFFSET"];

Suppose you are working with your own serial numbers. In that case, you can convert your own serial number to a Datacake UUID (which is needed to access configuration fields) using the following code:

// Get UUID for custom serial number
var datacakeUUID = deviceSerialToId[serialNumber];

Notes

• Device Identification: Custom serial numbers allow flexibility but must be mapped to Datacake UUIDs for the platform to recognize and manage the data correctly.

• Configuration Values: Stored at the product level but can have device-specific values. These values are accessed using the UUID, which is unique to each device.

• Measurements vs. Configuration Values: Measurements can have historical data (values with timestamps), while configuration fields typically hold a single, static value.

This setup provides a powerful way to manage and process device data efficiently, using Datacake's configuration fields and MQTT payload decoders to tailor the handling of each device's data based on its unique settings.

Attention: Correct Access of Configuration Values in MQTT (or any other) Payload Decoder!

When accessing configuration values in payload decoders, ensure you do not use .value at the end of the access statement. Configuration fields are non-historical and store only a single value without timestamps. Therefore, access them directly:

• Correct: var tempOffset = configurationValues[datacakeUUID]["TEMPERATURE_OFFSET"];

• Wrong: var tempOffset = configurationValues[datacakeUUID]["TEMPERATURE_OFFSET"].value;

Appending .value is only necessary for measurement values, which contain both a value and a timestamp due to their historical storage nature.

Configuration Fields in HTTP Payload Decoders

Datacake's HTTP payload decoders offer a powerful way to integrate external devices and services by processing incoming data in a custom format. Using configuration fields in these decoders allows for dynamic behavior based on device-specific or product-level settings. Configuration fields can hold static values, like thresholds or calibration offsets, which can be utilized to enhance decision-making processes directly within the decoder logic. This section explains how to use configuration fields effectively in HTTP decoders.

Setting Up Configuration Fields

Before using configuration fields in an HTTP payload decoder, ensure that the necessary fields are configured in Datacake:

1. Define Configuration Fields:

   • Navigate to the device settings in Datacake.

   • Create a configuration field, for example, Temperature Limit, with a unique identifier (TEMPERATURE_LIMIT).

   • Assign a default value and, if necessary, customize this value at the individual device level.

   Example Configuration Field:

   • Name: Temperature Limit

   • Identifier: TEMPERATURE_LIMIT

   • Type: Number

   • Default Value: 30

2. Ensure Device Mapping with UUID:

   • Datacake uses a UUID to uniquely identify each device. If using custom serial numbers, a mapping from these serial numbers to Datacake UUIDs (deviceSerialToId) is necessary.

HTTP Payload Decoder Example

Below is an example of an HTTP payload decoder that demonstrates how to use configuration fields to process incoming data:

function Decoder(request) {
    /*
    This decoder expects JSON data in the format given below.
    Upon receiving the data, it decodes it and forwards it to the database.
    */
    
    // Parse the incoming request body into a JSON object
    var payload = JSON.parse(request.body);
    
    // Extract the custom serial number from the incoming data
    var serialNumber = payload.device;
    
    // Convert the custom serial number to the Datacake UUID
    var datacakeUUID = deviceSerialToId[serialNumber];
    
    // Example: Working with configuration fields
    
    try {
        // Access a configuration value using the Datacake UUID
        var temperatureLimit = configurationValues[datacakeUUID]["TEMPERATURE_LIMIT"];
        
        // Check if the incoming temperature exceeds the configuration limit
        if (payload["temperature"] > temperatureLimit) {
            payload["temperature_limit_reached"] = true;
        }
        
    } catch (e) {
        console.log(JSON.stringify(e));
        console.log("Error parsing Configuration Field");
    }
    
    // Prepare the data to return to Datacake
    
    // Use the current Unix timestamp in seconds
    var timestamp = Math.floor(Date.now() / 1000);
    
    // Map the payload keys to Datacake's required format
    var result = Object.keys(payload).map(function(key) {
        if (key !== "device") {
            return {
                device: payload.device,
                field: key.toUpperCase(),
                value: payload[key],
                timestamp: timestamp
            };
        }
    });
    
    return result;
}

Explanation of the Decoder Function

• Parsing the Request: The incoming HTTP request body is parsed into a JSON object for easy manipulation.

• Serial Number Handling: The custom serial number provided in the payload is extracted. This serial number is then mapped to a Datacake UUID using a predefined mapping (deviceSerialToId), allowing access to device-specific data.

• Accessing Configuration Fields:

  • Using the Datacake UUID, the decoder accesses the configuration fields set up in Datacake. For instance, it retrieves the TEMPERATURE_LIMIT to perform checks against the incoming temperature data.

  • If the incoming temperature exceeds the configured limit, a flag (temperature_limit_reached) is added to the payload.

• Error Handling: The decoder includes try-catch blocks to handle errors gracefully. If a configuration field does not exist or cannot be accessed, the decoder logs the error without crashing.

• Data Formatting and Returning: The decoder formats the processed data into a structure compatible with Datacake's API, including optional timestamps for tracking. The data is then returned, ready to be stored or further processed by Datacake.

Best Practices

• Use Configuration Fields for Dynamic Settings: Configuration fields are ideal for thresholds, offsets, or any other settings that may change over time or vary per device. This provides flexibility in managing device behavior.

• Error Handling: Always implement error handling when accessing configuration fields or measurements to ensure robustness against missing or misconfigured data.

• Keep Decoder Logic Simple: While decoders can perform complex operations, keeping the logic straightforward helps maintain performance and readability.

This approach to using configuration fields within HTTP payload decoders enhances the adaptability of device integrations, enabling customized responses based on real-time data and configurable settings. This flexibility is critical for applications that need to respond dynamically to changing environmental conditions or operational states.

Further Examples

Temperature Offset Calibration

Temperatures often need calibration or offset added to the actual temperature value reported by the sensor. You could do this in the decoder hardcoded, but configuration fields are a nicer way when you, for example, work with 100s of devices and they all belong to the same product (and so share a single payload decoder).

But even when working with a single sensor, usage of configuration fields make sense here.

Code

function Decoder(bytes, port) {
    
    var decoded = {};
    
    var temperature = (bytes[0] <<8 | bytes[1]) / 10.0;
    var offset = configurationValues.TEMPERATURE_OFFSET;
    
    decoded.temperature = temperature + offset;
    
    return decoded;

}

Fill Level Offset

When working with Fill Level Sensors you often need to convert or map the value range of the sensor to the actual height that you are measuring to derive the fill level (of the object, container, water level, and so on).

Configuration fields can be used to create a fleet of 100s of fill level sensors and store these settings individually while still having the benefits of a shared product (same dashboard, payload decoder, database fields).

Code

function Decoder(bytes, port) {
    
    var decoded = {};
    
    decoded.battery = ((bytes[0]<<8 | bytes[1]) & 0x3FFF) / 1000;
    decoded.distance = bytes[2]<<8 | bytes[3];
    
    try {

        var delta = configurationValues.SENSOR_LEVEL_EMPTY - configurationValues.SENSOR_LEVEL_FULL;
        var sensorRelative = configurationValues.SENSOR_LEVEL_EMPTY - decoded.distance;
        var fillLevel = Math.abs((sensorRelative / delta) * 100);
        
        if (fillLevel > 100) fillLevel = 100;
        else if (fillLevel < 0) fillLevel = 0;
        
        decoded.fill_level = fillLevel;
    
    } catch (e) {
    
        console.log(JSON.stringify(e));
    }
    
    try {
        
        decoded.LORA_RSSI = (!!normalizedPayload.gateways && !!normalizedPayload.gateways[0] && normalizedPayload.gateways[0].rssi) || 0;
        decoded.LORA_SNR = (!!normalizedPayload.gateways && !!normalizedPayload.gateways[0] && normalizedPayload.gateways[0].snr) || 0;
        decoded.LORA_DATARATE = normalizedPayload.data_rate;   
        
    } catch (e) {
        
        console.log(JSON.stringify(e));
    }
    
    return decoded;

}

Field Configuration

Possible Issues and Best Practices

Handling Measurement Values in Decoders

The following is not related to Configuration Fields in general, but helpful to add.

When working with decoders, it's essential to handle the retrieval of measurement values carefully. One common issue arises when a field exists on a device but no data has been stored yet. Attempting to access such a measurement value without proper handling can cause the decoder to fail. To avoid this issue, it is a best practice to use a try-catch block when accessing measurement values. By encapsulating the code that reads from a measurement in a try-catch block, you can gracefully handle the situation where the field has no stored data. This approach ensures that the decoder continues to run smoothly, and you can use the opportunity to write an initial value into the field.

For example:

try {
    var temperatureInDatabase = measurements[datacakeUUID]["TEMPERATURE"].value;
    // Further processing with temperatureInDatabase...
} catch (e) {
    console.log("Measurement field is not yet initialized. Writing initial value.");
    // Code to write an initial value into the measurement field
}

This strategy not only prevents errors but also provides a way to initialize fields dynamically, enhancing the robustness and reliability of your MQTT payload processing.