Understanding Environment Variables

Regardless of the use case or end application, many IoT solutions must manage application state or configuration settings across multiple devices, even after those devices have been deployed into the field. Rather than forcing you to implement your own state management system, the Notecard has two built-in approaches for managing shared state:

1. Environment Variables.
2. Database (DB) Notefiles.

DB Notefiles are useful for sharing state directly between Notehub and a Notecard on a 1-1 basis. For more information, see Using Database Files for Replicated State.

Environment Variables, on the other hand, are a state and settings management feature that works for device fleets of any size, and allows several levels of control for variables that should apply to a device, across a Fleet, or to all Devices in a Project. These variables are key-value pairs, can be set in the Notehub UI or through the Notehub API, and propagate to devices in a project or fleet using the same synchronization mechanism used for Notes and Notefiles.

See environment variables in action in these accelerator projects.

The Hierarchy of Environment Variables

Environment variables can be defined in a number of locations: the Notecard, the Notehub device, the Device Fleet, and the Notehub Project. Variables set at different levels of this hierarchy can override one another. When obtaining an environment variable, the Notecard uses the following priority order, where the first matched result is returned:

1. The value set on that Notecard with the (deprecated) env.set request.
2. The value set in Notehub directly at the Device-level.
3. The value set in Notehub on a Fleet to which the Device belongs.
4. The value set in Notehub on the Project to which the Device belongs.
5. The value set on that Notecard with the env.default request.

When a host requests a variable from the Notecard using env.get, the Notecard returns the current value based on the following decision tree.

Setting Environment Variables

Environment Variables can be managed in multiple places, depending on the scope of the variable. The following sections provide additional guidance for setting variables across scopes.

warning

User-created environment variables should not start with an underscore to avoid any potential conflicts with system environment variables reserved by Blues.

Setting a Device Local Variable

warning

The env.set API is deprecated as of v7.2.2. We recommend setting environment variables in Notehub using either the Notehub user interface or Notehub API. You may also use the env.default API to provide a default value for an environment variable, until that variable is overridden by a value from Notehub.

Set an environment variable directly on a Device using an env.set request. Once set, this variable can be retrieved immediately with an env.get request.

note

When setting environment variables on the Notecard LoRa, the environment variables must be templated.

A Device local variable is the highest-priority setting. Variables set in this way cannot be overridden by variables set at the Notehub Device, Project, or Fleet level.

{
  "req": "env.set",
  "name": "temp-threshold",
  "text": "80"
}

J *req = notecard.newRequest("env.set");
JAddStringToObject(req, "name", "temp-threshold");
JAddStringToObject(req, "text", "80");

notecard.sendRequest(req);

req = {"req": "env.set"}
req["name"] = "temp-threshold"
req["text"] = "80"

card.Transaction(req)

Setting a Notehub Device Variable

Environment variables can also be managed within Notehub on individual Devices. This provides the ability to configure device-specific settings for the Notecard from within Notehub without issuing env.set requests directly to the Device. In addition, it provides developers with the ability to remove Device-specific settings and apply Fleet or Project variables without having to modify host firmware.

To set an environment variable on the Notehub Device, browse to the Device in notehub.io, select the Device and click "View."

Then, select the "Environment" tab to view and edit environment variables.

Alternatively, you can set a Notehub Device variable using a Set Device Environment Variables request to the Notehub API or by uploading key-value pairs of environment variables in CSV format.

A Notehub Device variable is available to the Notecard via an env.get request after the next sync.

Setting a Fleet Variable

Fleet-level variables apply to all Notecards in a Notehub-managed Fleet. They have a higher-priority than Project and Device default variables, but are overridden by Notehub Device and Device-local variables.

To set an environment variable on the Fleet, browse to the Fleets tab in notehub.io, select the fleet you wish to update, and click "Settings."

Then, view and edit environment variables from the Environment tab on the Fleets settings screen.

Alternatively, Fleet variables can be set using a Set Fleet Environment Variables request to the Notehub API or by uploading key-value pairs of environment variables in CSV format.

A Notehub Fleet variable is available to the Notecard via env.get after the next sync.

Setting a Project-Wide Variable

Project-level variables apply to all Notecards across all Fleets in a Notehub project. They have a higher-priority than Device default variables, but are overridden by Fleet, Notehub Device, and Device-local variables.

To set an environment variable on a Project, browse to the Project in notehub.io and select the "Environment" menu under "Settings."

Alternatively, you can set a Project variable using a Set Project Environment Variables request to the Notehub API or by uploading key-value pairs of environment variables in CSV format.

A Notehub Project variable is available to the Notecard via env.get after the next sync.

Setting a Default Variable

Set a default environment variable on a Device using an env.default request. Once set, this variable can be retrieved immediately with an env.get request, assuming this value is not overridden by a local value, or a synced value from the Notehub Device, Fleet or Project.

note

Notecard LoRa

When setting environment variables on the Notecard LoRa, the environment variables must be templated.

In addition, environment variables set with env.default on Notecard LoRa do not propagate up to Notehub. If looking for a simple way to share a variable from a Notecard to Notehub, please refer to var.set.

{
  "req": "env.default",
  "name": "temp-threshold",
  "text": "100"
}

J *req = notecard.newRequest("env.default");
JAddStringToObject(req, "name", "temp-threshold");
JAddStringToObject(req, "text", "100");

notecard.sendRequest(req);

req = {"req": "env.default"}
req["name"] = "temp-threshold"
req["text"] = "100"

card.Transaction(req)

Setting Environment Variable Templates

Notefile templates provide the Notecard with a schema the Notecard uses to store Notes as fixed-length records, rather than as flexible JSON objects. Just like Notefiles, environment variables can also be templated, and are required when using the Notecard LoRa.

The body of an env.template request specifies environment variable names, with values as "hints" for the data type. See Understanding Template Data Types for more information.

{
  "req": "env.template",
  "body": {
    "env_var_int": 11,
    "env_var_string": "10",
  }
}

J *req = NoteNewRequest("env.template");
J *body = JCreateObject();
JAddNumberToObject(body, "env_var_int", 11);
JAddStringToObject(body, "env_var_string", "10");
JAddItemToObject(req, "body", body);

NoteRequest(req);

req = {"req": "env.template"}
req["body"] = {
  "env_var_int": 11,
  "env_var_string": "10"
}
rsp = card.Transaction(req)

Batch Upload of Environment Variables

Notehub allows you to upload a CSV-formatted file with key-value pairs to create multiple environment variables. This is accomplished by navigating to the appropriate Project, Fleet, or Device environment variable settings page and uploading a CSV file.

The uploaded file must conform to the following requirements:

1. The file is limited to 2KB in size.
2. The key-value pairs are limited to 256 characters each.
3. The file must be in a .csv file format.
4. The file must include two columns (first is key and the second is value). Anything with more than two columns will be ignored.
5. If any of the entries in the key or value columns contain commas, the entry needs to be in quotes.
6. If the key exists multiple times, the last one in the list will be used.
7. If the system cannot process the file for some reason, all values in the file will be rejected and an error will be displayed.

For example:

temp_threshold,30
pump_status,true
default_mode,"off"
valid_values,"30,60,90"

Session Environment Variables

You may have noticed that there is a Notefile called _session.qo that doesn't exist on the device, but for which a single event is generated at the start of each session. It typically contains information about the device that is considered to be too noisy or would require too much overhead to include in each event.

Using a special naming convention, developers can create environment variables that are included in the _session.qo event payload at the start of each session. To differentiate themselves from standard environment variables; session environment variables begin with a $ prefix (e.g. $foo). Session environment variables can be created for a project, fleet, or device. Once created, the _session.qo event JSON will contain an object that looks like this:

"environment": {
    "$foo": "bar",
},

The primary distinction of a session environment variable is the ability to provide a unique pathway for the device to share intermittent information back to Notehub.io and on to your routes. Using session environment variables can alleviate the burden of sharing information which is considered important, but seldom changes during the life of a session. The session environment variables appear in the _session.qo event, which provides a way for a custom route to be created. This is not possible using standard environment variables, and would require non-trivial logic when using standard data queues.

In summary, at the beginning of each session, Notehub.io will receive a copy of any environment variables beginning with a $, and those variables allow the device to report information to Notehub.io.

Deleting Environment Variables

In the Notehub UI, you can delete environment variables by clicking the trashcan icon next to a variable.

From the Notehub API, delete environment variables at the Notehub Device, Fleet, and Project scope using the following Notehub APIs:

• Delete Device Environment Variables
• Delete Fleet Environment Variables
• Delete Project Environment Variables

For Notecard local and default variables, use env.default with the name argument and no text field to clear a variable.

{
  "req": "env.default",
  "name": "temp-threshold"
}

J *req = notecard.newRequest("env.default");
JAddStringToObject(req, "name", "temp-threshold");

notecard.sendRequest(req);

req = {"req": "env.default"}
req["name"] = "temp-threshold"

card.Transaction(req)

Reserved Environment Variables

Notehub reserves a set of system environment variables that can be used to override default values on the Notecard. Note that all reserved environment variable names start with an _, so it is best to never start an environment variable name with an underscore when creating user-defined variables.

Additional Resources

• Working With Environment Variables
• env Requests
• Notehub Environment Variable APIs