Config Icon

Helium Configuration Variables


Helium Configuration Variables enable connected devices to request and report settings via a Helium Channel completely over the air (OTA). Configuration Variables are very powerful and allow developers to future-proof their sensing deployments by building in an OTA update mechanism specifically for operational device parameters.

This document covers the types of Configuration Variables available within Helium and, at a high level, how they can be used by developers building applications on Helium.


Types of Configuration Variables

There are two types of Configuration Variables: Channel and Global.

Actions via Configuration Variables

Configuration Variables can be used to trigger two specific actions between devices and Channels: request and report

Requesting Configurations

A channel can request target device(s) to change a setting or settings. For example, a developer might request a configuration change to do things like:

A device can proactively retrieve requested configuration variables or it can listen passively for configuration changes to react to changes as they happen. A common usage pattern is to first request the configuration value on startup of the device (with a sensible local default value in case the network is not available or configuration value is not set on the back-end), and subsequently listen for configuration changes on a regular basis to adjust configuration as needed.

Reporting Configurations

Reported configuration variables enable the device(s) to report values for a variable or a set of variables over the air. Use cases for reporting configuration values are things like:

Configuration Variable Examples

At the lowest level, Configuration Variables are simply key:value pairs that are included in your sensor's program and are addressable over the air, via a Channel, using a known schema and naming convention.

Global Configuration Example

Here's an example of a function from an Arduino Sketch that uses Configuration Variables:

void
update_config(bool stale)
{
    if (stale)
    {
        DBG_PRINT(F("Fetching Config - "));
        int status = config.get("config.interval_ms", &send_interval, 5000);
        report_status(status);

        if (status == helium_status_OK)
        {
            DBG_PRINT(F("Updating Config - "));
            status = config.set("config.interval_ms", send_interval);
            report_status(status);
        }
    }
}

Note the presence of config.get and config.set. The former is used to when requesting a configuration variable from a Channel; and the latter is used when reporting a configuration value to the channel.

The config. prefix indicates that this is a global configuration variable. The config.get retrieves the requested configuration value from the global variables maintained by the Helium Dashboard for a given device. The Helium Atom information page would show something like this once you've entered a requested value for interval_ms:

DocImg

The config.set call will then report the successful receipt (and application) of the interval_ms variable in the Reported section, which has not yet occurred in the image below:

DocImg

Channel Configuration Example

Here's an example of a function from an Arduino Sketch that uses Configuration Variables:

void
update_config(bool stale)
{
    if (stale)
    {
        DBG_PRINT(F("Fetching Config - "));
        int status = config.get("channel.interval_ms", &send_interval, 5000);
        report_status(status);

        if (status == helium_status_OK)
        {
            DBG_PRINT(F("Updating Config - "));
            status = config.set("channel.interval_ms", send_interval);
            report_status(status);
        }
    }
}

Assuming that the channel is an Azure IoT we can go to to the Device Explorer in Azure, find the specific device and display the Device Twin details.

DocImg

Note that desired section. This is where you can add or change the interval_ms variable which the device will pick up using config.get.

The reported section will display the reported configuration variables as reported using config.set.

There are equivalent screens for AWS and Google Cloud IoT Core that enable the cloud provider to request configuration changes and receive reported configuration from the device.


Further Reading

Code Samples

Global Configuration Variables

Channel Configuration Variables