🚀 Browse our open source reference applications to accelerate your IoT project!

Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
Sign In
Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
×
HomeGuides & Tutorials
Welcome
Collecting Sensor Data
Routing Data to Cloud
Building Edge ML Applications
Twilio SMS Guide
Fleet Admin Guide
Using the Notehub API
Notecard Guides
Guide Listing
Asset Tracking
Attention Pin Guide
Connecting to a Wi-Fi Access Point
Debugging with the FTDI Debug Cable
Diagnosing Cellular Connectivity Issues
Encrypting Data With the Notecard
Minimizing Latency
Notecard Outboard Firmware Update
Remote Command and Control
Serial-Over-I2C Protocol
Understanding Environment VariablesThe Hierarchy of Environment VariablesSetting Environment VariablesSession Environment VariablesDeleting Environment VariablesReserved Environment Variables
Understanding Notecard Penalty Boxes
Updating ESP32 Host Firmware
Using External SIM Cards
Using JSONata to Transform JSON
Rate this page  
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
Can we improve this page? Send us feedbackRate this page
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
© 2023 Blues Inc.Terms & ConditionsPrivacy
blues.ioTwitterLinkedInGitHubHackster.io
Disconnected
Notecard 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.

Advanced Usage

The help command gives more info.

Connect a Notecard
Use USB to connect and start issuing requests from the browser.
Try Notecard Simulator
Experiment with Notecard's latest firmware on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up

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.

warning

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

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.

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

    Set WhereSet HowAvailable on Notecard
    NotehubNotehub Device Settings or a 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 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

    Set WhereSet HowAvailable on Notecard
    NotehubSet 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 Fleets tab in notehub.io , select the fleet you wish to update, and click "Settings."

    Notehub Fleet page with Settings link called out

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

    Notehub Fleet settings page

    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

    Set WhereSet HowAvailable on Notecard
    NotehubNotehub Project Settings or a 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 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 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.

      {
        "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)

      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:

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

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

        {
          "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)
          {
            "req": "env.set",
            "name": "temp-threshold"
          }
          J *req = notecard.newRequest("env.set");
          JAddStringToObject(req, "name", "temp-threshold");
          
          notecard.sendRequest(req);
          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.

          VariableDescriptionData TypeRelated API or Guide
          _aux_gpio_reportSet by the Notecard to reflect the current state of the AUX GPIO inputs.stringMonitoring AUX GPIO State
          _aux_gpio_report_enableUsed to enable reporting via _aux_gpio_report.stringMonitoring AUX GPIO State
          _aux_gpio_setUsed to set AUX GPIOs HIGH or LOW, or pulse them HIGH or LOW, for a specified period.stringcard.aux GPIO Mode
          _contact_affiliationAffiliation of the Notecard maintainer (overrides "default" affiliation).stringcard.contact/affiliation
          _contact_affiliation_defaultAffiliation of the Notecard maintainer.stringcard.contact/affiliation
          _contact_emailEmail of the Notecard maintainer (overrides "default" email).stringcard.contact/email
          _contact_email_defaultEmail of the Notecard maintainer.stringcard.contact/email
          _contact_nameName of the Notecard maintainer (overrides "default" name).stringcard.contact/name
          _contact_name_defaultName of the Notecard maintainer.stringcard.contact/name
          _contact_roleRole of the Notecard maintainer (overrides "default" role).stringcard.contact/role
          _contact_role_defaultRole of the Notecard maintainer.stringcard.contact/role
          _fwName of a host firmware binary to send to the Notecard for delivery to a host. Must match the name of a binary that has already been uploaded to the Notehub project.stringN/A
          _fw_retryThe UNIX epoch time, in seconds, when a host firmware update retry was requested.intN/A
          _gps_expiry_secsUsed for overriding the default 900 second GPS timeout.intN/A
          _gps_hdop_convergence_secsUsed for overriding of GPS HDOP convergence default of 15 seconds.intN/A
          _gps_hdop_minimumUsed for overriding the default GPS quality determination default of 5.intN/A
          _gps_modeSpecify the GPS module mode.stringcard.location.mode/mode
          _gps_ring_latWhen geofence is enabled, latitude in degrees of the geofence center.floatcard.location.mode/lat
          _gps_ring_lonWhen geofence is enabled, longitude in degrees of the geofence center.floatcard.location.mode/lon
          _gps_ring_metersMeters from a geofence center. Used to enable geofence location tracking.intcard.location.mode/max
          _gps_ring_secsUsed for overriding for standard 5m debounce period of going in/out of geofenced area.intN/A
          _gps_secsWhen in periodic mode, location will be sampled at this interval, if the Notecard detects motion.intcard.location.mode/seconds
          _gps_trackSet to 1 to start Notefile tracking.1 or 0card.location.track/start
          _gps_track_heartbeat_hoursIf heartbeat is enabled, add a heartbeat entry at this interval.intcard.location.track/hours
          _latUsed to override the Notecard's current GPS position latitude.floatN/A
          _logContents of the log.qo Notefile.stringN/A
          _lonUsed to override the Notecard's current GPS position longitude.floatN/A
          _net_minsUsed for overriding the cellular network information update period of 7 days.intN/A
          _restartIf set or updated, the Notecard performs a controlled restart. Suggest setting to the current UNIX Epoch time when setting/updating.stringcard.restart
          _restart_every_hoursIf defined and non-zero, the Notecard will perform a controlled restart at the specified interval in hours.intcard.restart
          _restart_no_activity_hoursIf the Notecard fails to sync with Notehub after the number of hours set in this variable, restart the device.intcard.restart
          _session_minsWhen in continuous mode, the amount of time, in minutes, of each session.inthub.set/duration
          _snThe end product's serial number (overrides "default" sn).stringhub.set/sn
          _sn_defaultThe end product's serial number.stringhub.set/sn
          _sync_continuousEnables an always-on network connection, for high power devices.1 or 0hub.set/mode:continuous
          _sync_continuous_inboundAutomatically and immediately sync each time a Notefile change is detected on Notehub.1 or 0hub.set/mode:continuous sync:true
          _sync_inbound_minsThe max wait time, in minutes, to sync inbound data from Notehub.inthub.set/inbound
          _sync_outbound_minsThe max wait time, in minutes, to sync outbound data from the Notecard.inthub.set/outbound
          _triThe triangulation approach to use for determining the Notecard location.stringcard.triangulate/mode
          _tri_alwaysTriangulate even if there was no motion detected.1 or 0card.triangulate/set:true on:true
          _tri_gps_failureTriangulate as triggered by the failure to acquire a GPS signal successfully.1 or 0N/A
          _tri_minsMinimum delay, in minutes, between triangulation attempts. Use 0 for no time-based suppression.intcard.triangulate/minutes

          Additional Resources

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