Using Environment Variables to Change Notecard Configuration

All Notecards require some level of configuration. This configuration may include how often a Notecard connects to Notehub (hub.set), how a Notecard gets its GPS/GNSS location (card.location.mode), and what radio access technologies a Notecard should use (card.transport).

When you deploy a Notecard you must hardcode its default configuration, either by placing the initial config values in a setup script that runs as part of a provisioning process, or by using host firmware to give a Notecard its initial configuration.

In this article you’ll learn how to change your Notecard’s configuration, remotely, after your device has been deployed.

Using Reserved Environment Variables

The easiest way to remotely change a Notecard’s configuration is with environment variables, which are key-value pairs that can be set in the Notehub UI or through the Notehub API. Environment variables are easy to use, and propagate to devices in a project or fleet using the same synchronization mechanism used for Notes and Notefiles.

We provide a handful of reserved environment variables specifically for altering a Notecard’s configuration remotely. Here are a few of the most commonly used ones:

• _gps_secs: Used to override the card.location.mode request’s seconds argument, which controls how often a Notecard determines its GPS/GNSS location.

• _gps_track: Setting this variable to 1 is equivalent to using the card.location.track request’s start argument.

• _sync_continuous: Setting this variable to 1 is equivalent to setting a Notecard to mode: "continuous" through the hub.set request.

• _sync_inbound_mins: Used to override the hub.set request’s inbound argument, which determines how often a Notecard synchronizes to receive inbound data from Notehub.

• _sync_outbound_mins: Used to override the hub.set request’s outbound argument, which determines how often a Notecard synchronizes to send data to Notehub.

note

If you’re new to Blues and aren’t sure how to set these environment variables, check out the Setting a Notehub Device Variable documentation article.

Also, note that after setting a variable, you must wait for your Notecard’s next inbound synchronization before your configuration change will take effect.

All of these environment variables act as overrides and take precedence over a Notecard’s default configuration. For example, if you use a Notecard’s hub.set request to set {"inbound":60}, and also have a _sync_inbound_mins environment variable on the device set to 120, your Notecard will use 120 as an inbound interval.

If you delete any of these variables your device will revert back to its currently configured values. For instance, using the previous paragraph’s example, if you delete the _sync_inbound_mins variable your Notecard will revert to an inbound interval of 60 because of the {"inbound":60} configuration you used for the hub.set request.

Creating Custom Environment Variables

Although we provide reserved environment variables for common configuration scenarios, we don’t provide built-in variables for each of the hundreds of ways you may wish to configure a Notecard.

If you want to change a Notecard’s default configuration and a reserved environment variable is not available, we recommend creating custom environment variables, and writing host firmware that uses those variables appropriately.

For example, suppose you are using a Notecard’s card.temp request to receive regular temperature readings from your device.

{
  "req": "card.temp",
  "minutes": 60
}

With the configuration above your device will take temperature readings every 60 minutes, but there is no way to change the "minutes" value remotely (aka no reserved environment variable exists for this purpose).

The code below shows a host firmware implementation that allows you to change your "minutes" value through a custom card_temp_minutes environment variable.

int currentTempInterval;

void setupTempMonitoring(int minutes) {
  J *req = NoteNewRequest("card.temp");
  if (req != NULL) {
    JAddNumberToObject(req, "minutes", minutes);
    JAddBoolToObject(req, "sync", true);
    NoteRequest(req);
    currentTempInterval = minutes;
  }
}

void setup() {
  // all other setup your project may need to do

  setupTempMonitoring(10);
}

void loop() {
  J *req = NoteNewRequest("env.get");
  if (req != NULL) {
    JAddStringToObject(req, "name", "card_temp_minutes");
    if (J *rsp = NoteRequestResponse(req)) {
      char* minutesStr = JGetString(rsp, "text");
      int minutes = atoi(minutesStr);
      if (minutes > 0 && minutes != currentTempInterval) {
        setupTempMonitoring(minutes);
      }
      NoteDeleteResponse(rsp);
    }
  }

  delay(1000);
}

note

This is C code that uses note-arduino (the official Arduino library for communicating with Notecards), but you can implement the same approach using any of the Notecard’s firmware libraries.

Let’s break down what’s happening here. First, we create a function that takes an integer minutes as an argument and invokes the card.temp request with its value. We also create a global currentTempInterval variable that stores the last-used value that we’ll reference later.

int currentTempInterval;
void setupTempMonitoring(int minutes) {
  J *req = NoteNewRequest("card.temp");
  if (req != NULL) {
    JAddNumberToObject(req, "minutes", minutes);
    JAddBoolToObject(req, "sync", true);
    NoteRequest(req);
    currentTempInterval = minutes;
  }
}

In setup() we call our new setupTempMonitoring() function with a default value of 10. This gives Notecard a default value to use for its minutes argument in case no environment variable is present.

void setup() {
  // all other setup your project may need to do

  setupTempMonitoring(10);
}

And then finally, in loop(), we use Notecard’s env.get request to get the latest value of the card_temp_minutes environment variable. If we find a valid value, and that value is different than the last-used value (currentTempInterval), we call our setupTempMonitoring() function again to update to the new minutes value.

J *req = NoteNewRequest("env.get");
if (req != NULL) {
  JAddStringToObject(req, "name", "card_temp_minutes");
  if (J *rsp = NoteRequestResponse(req)) {
    char* minutesStr = JGetString(rsp, "text");
    int minutes = atoi(minutesStr);
    if (minutes > 0 && minutes != currentTempInterval) {
      setupTempMonitoring(minutes);
    }
    NoteDeleteResponse(rsp);
  }
}

note

If you’re writing more complex code with environment variables you may want to check out Notecard Environment Variable Manager, an open-source C library we provide for fetching environment variables from a Notecard.

Wrapping Up

Being able to configure your devices is important for any remote deployment. Notecard makes this process trivial, by providing reserved environment variables for common configuration options, and a rich environment variable feature for designing custom configuration mechanisms.

Try out this article’s approach, and if you have any questions let us know in the comments.