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.

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 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

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

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.

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

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

notecard.sendRequest(req);

COPY
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 Environment Variables by Device request to the Notehub API.

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 Environment Variables by Fleet request to the Notehub API.

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 Environment Variables request to the Notehub API.

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.

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

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

notecard.sendRequest(req);

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

card.Transaction(req)

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, device, or even on the device itself with env.set. Once created, the _session.qo event JSON will contain an object that looks like this:

COPY
"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 and clicking "Save."

From the Notehub API, delete environment variables at the Notehub Device, Fleet, and Project scope using a Delete Environment Variable request on the Notehub API.

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

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

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

notecard.sendRequest(req);

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

card.Transaction(req)

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

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

notecard.sendRequest(req);

COPY
req = {"req": "env.set"}
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