Support
Blues.io
Notehub.io
Shop
Support
Blues.io
Notehub.io
Shop
×
HomeBuild
Hookup Guide
Quickstart
Tutorials
Sensor Tutorial
Route Tutorial
Notecard Guides
Asset Tracking
Serial-Over-I2C Protocol
Updating ESP32 Host Firmware
Configuring ESP32 Attention Pin
Understanding Environment VariablesThe Hierarchy of Environment VariablesSetting Environment VariablesDeleting Environment Variables
Routing Guides
Twilio Route
MQTT Route
Azure Function Route
ThingWorx Route

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.

Flowchart visualization of the environment variables hierarchy

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 WhereSet HowAvailable on Notecard
Notecardenv.set requestImmediately

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

    Set WhereSet HowAvailable on Notecard
    NotehubNotehub Device Settings or a hub.env.set request through the Notehub APIAfter 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."

    Notehub Devices page with Details link called out

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

    Notehub Device page with Environment tab active

    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

      Set WhereSet HowAvailable on Notecard
      Notehubhub.env.set request through the Notehub APIAfter 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."

      Notehub Fleet page with Settings link called out

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

      Notehub Fleet settings page

      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

        Set WhereSet HowAvailable on Notecard
        NotehubNotehub Project Settings or a hub.env.set request through the Notehub APIAfter 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."

        Notehub Project page with Environment tab active

        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 WhereSet HowAvailable on Notecard
          Notecardenv.default requestImmediately

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

            Notehub Environment UI with trash icon called out

            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
                  Can we improve this page? Send us feedbackRate this page
                  • ★
                    ★
                  • ★
                    ★
                  • ★
                    ★
                  • ★
                    ★
                  • ★
                    ★
                  © 2021 Blues Inc.Terms & ConditionsPrivacy
                  blues.ioTwitterLinkedInGitHubHackster.io
                  Disconnected
                  Disconnected
                  Having trouble connecting?

                  Try changing your Micro USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

                  Connect a NotecardClick 'Connect' and select a USB-connected Notecard to start issuing requests from the browser.