Cellular, LoRa, and Wi-Fi: Introducing the Next Generation of Notecards

Blues Developers
What’s New
Resources
Accelerators
Fully documented reference applications
Blog
Technical articles for developers
Community
Community projects and resources
Terminal
Connect to a Notecard in your browser
Blues.ioNotehub.io
Shop
Docs
Button IconHelp
Notehub StatusVisit our ForumContact Support
Button IconSign In
Sign In
Sign In
Docs Home
What’s New
Resources
Accelerators
Fully documented reference applications
Blog
Technical articles for developers
Community
Community projects and resources
Terminal
Connect to a Notecard in your browser
Blues.ioNotehub.io
Shop
Docs
Guides & 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 Communication Without a Library
Notecard Outboard Firmware Update
Remote Command and Control
Sending and Receiving Large Binary Objects
Serial-Over-I2C Protocol
Understanding Environment Variables
The 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

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.

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

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.

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
_dfu_enabledEnable DFU downloads based on Notecard voltage. Use a boolean 1 (on) or 0 (off) for each source/voltage level: usb:<1/0>;high:<1/0>;normal:<1/0>;low:<1/0>;dead:0. For example, with usb:1;0;, DFU downloads would occur when USB-powered, but not in any other state.stringdfu.status/vvalue
_dfu_periodA period within which to enable automatic Notecard Outboard Firmware Updates. The value provided must be in the form "0000000,00,0", where a value of "1010000,20,5" allows firmware updates to occur on Sundays and Tuesdays, starting at 20:00 local time, for 5 hours.stringN/A
_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_download_always_enabledSet to 1 to override host behavior and allow Notehub to force DFU to be enabled, preventing a host bug from permanently disabling DFU.intN/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_hostIf set or updated, the Notecard performs a controlled restart of a connected host. Suggest setting to the current UNIX Epoch time when setting/updating.stringN/A
_restart_host_every_hoursIf set, the Notecard restarts a connected host at the configured interval.intN/A
_restart_host_no_activity_hoursIf set, the Notecard restarts a connected host after no activity has been detected for the provided number of hours.intN/A
_restart_host_use_attnIf set, the Notecard will restart a connected host by pulsing its ATTN pin low. If not set, the Notecard will restart a connected host using the AUX3 and AUX4 pins.booleanN/A
_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
Can we improve this page? Send us feedback
© 2023 Blues Inc.
© 2023 Blues Inc.
TermsPrivacy
Notecard Disconnected
Having trouble connecting?

Try changing your 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