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:
- Environment Variables.
- 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.
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:
- The value set on that Notecard with the
env.set
request. - The value set in Notehub directly at the Device-level.
- The value set in Notehub on a Fleet to which the Device belongs.
- The value set in Notehub on the Project to which the Device belongs.
- 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.
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.
Set Where | Set How | Available on Notecard |
---|---|---|
Notecard | env.set request | Immediately |
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.
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.
Set Where | Set How | Available on Notecard |
---|---|---|
Notehub | Notehub Device Settings or a hub.env.set request through the Notehub API | After Next Sync |
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.
Set Where | Set How | Available on Notecard |
---|---|---|
Notehub | hub.env.set request through the Notehub API | After Next Sync |
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.
Set Where | Set How | Available on Notecard |
---|---|---|
Notehub | Notehub Project Settings or a hub.env.set request through the Notehub API | After Next Sync |
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.
Set Where | Set How | Available on Notecard |
---|---|---|
Notecard | env.default request | Immediately |
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.
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.