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.

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.

Setting a Notehub Device variable

Environment variables can also be managed on the Notehub on an individual Device. 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 "Details."

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

Alternatively, you can set a Notehub Device variable using a hub.env.set 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 Fleet in notehub.io, and click "Settings."

Then, view and edit environment variables from the Fleet settings screen.

Alternatively, Fleet variables can be set using a hub.env.set 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 hub.env.set 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.

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 hub.env.set request and the variable name with no text value.

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

Additional Resources

• Working With Environment Variables
• env Requests
• hub.env.get
• hub.env.set