Learn how to get started with Cellular, Wi-Fi, LoRa, and Satellite using Blues Notecard on September 25th

Blues Developers
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Button IconHelp
Notehub StatusVisit our Forum
Button IconSign In
Docs Home
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
API Reference
Glossary
System Notefiles
Notecard API
Introduction
card Requests
dfu Requests
env Requests
env.defaultenv.getenv.modifiedenv.setenv.template
file Requests
hub Requests
note Requests
ntn Requests
var Requests
web Requests
Notehub API
API Introduction
Authorization API
Billing Account API
Device API
Event API
Monitor API
Project API
Route API
homechevron_rightDocschevron_rightAPI Referencechevron_rightNotecard APIchevron_rightenv Requests - API Reference

env Requests

Environment variables are key-value pairs that can be set on a device, project, or fleet.

Notecard Firmware Version:
4.x LTS

env.default CellCell+WiFiLoRaWiFi

Used by the Notecard host to specify a default value for an environment variable until that variable is overridden by a device, project or fleet-wide setting at Notehub.

note

Environment variables set with env.default on Notecard LoRa do not propagate up to Notehub. If looking for a simple way to share a variable from a Notecard to Notehub, please refer to var.set.

Arguments

name

string (optional)

The name of the environment variable (case-insensitive).

text

string (optional)

The value of the variable. Pass "" or omit from the request to delete it.

{
  "req": "env.default",
  "name": "monitor-pump",
  "text": "on"
}
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "monitor-pump");
JAddStringToObject(req, "text", "on");

NoteRequest(req);
req = {"req": "env.default"}
req["name"] = "monitor-pump"
req["text"] = "on"
rsp = card.Transaction(req)

Set a default value for an environment variable.

{
  "req": "env.default",
  "name": "monitor-pump"
}
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "monitor-pump");

NoteRequest(req);
req = {"req": "env.default"}
req["name"] = "monitor-pump"
rsp = card.Transaction(req)

Clear the default value for an environment variable by omitting text.

{
  "req": "env.default",
  "name": "debug-mode",
  "text": ""
}
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "debug-mode");
JAddStringToObject(req, "text", "");

NoteRequest(req);
req = {"req": "env.default"}
req["name"] = "debug-mode"
req["text"] = ""
rsp = card.Transaction(req)

Set an environment variable default to an empty string.

{
  "req": "env.default",
  "name": "sample-rate",
  "text": "60"
}
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "sample-rate");
JAddStringToObject(req, "text", "60");

NoteRequest(req);
req = {"req": "env.default"}
req["name"] = "sample-rate"
req["text"] = "60"
rsp = card.Transaction(req)

Set a default value for a numeric environment variable.

Response Members
None: an empty object {} means success.

env.get CellCell+WiFiLoRaWiFi

Returns a single environment variable, or all variables according to precedence rules.

note

Before using the env.get API on Notecard for LoRa or Starnote, you must create an environment variable template using the env.template API.

Arguments

name

string (optional)

The name of the environment variable (case-insensitive). Omit to return all environment variables known to the Notecard.

names

array of string (optional)

A list of one or more variables to retrieve, by name (case-insensitive).

time

UNIX Epoch time (optional)

Request a modified environment variable or variables from the Notecard, but only if modified after the time provided.

{
  "req": "env.get",
  "name": "monitor-pump-one"
}
J *req = NoteNewRequest("env.get");
JAddStringToObject(req, "name", "monitor-pump-one");

NoteRequest(req);
req = {"req": "env.get"}
req["name"] = "monitor-pump-one"
rsp = card.Transaction(req)

Retrieve a specific environment variable by name.

{
  "req": "env.get",
  "name": "monitor-pump-one",
  "time": 1656315835
}
J *req = NoteNewRequest("env.get");
JAddStringToObject(req, "name", "monitor-pump-one");
JAddNumberToObject(req, "time", 1656315835);

NoteRequest(req);
req = {"req": "env.get"}
req["name"] = "monitor-pump-one"
req["time"] = 1656315835
rsp = card.Transaction(req)

Retrieve a variable only if modified after the specified time.

{
  "req": "env.get",
  "names": [
    "monitor-pump-one",
    "monitor-pump-two"
  ]
}
J *req = NoteNewRequest("env.get");
J *names = JAddArrayToObject(req, "names");
JAddItemToArray(names, JCreateString("monitor-pump-one"));
JAddItemToArray(names, JCreateString("monitor-pump-two"));

NoteRequest(req);
req = {"req": "env.get"}
req["names"] = ["monitor-pump-one", "monitor-pump-two"]
rsp = card.Transaction(req)

Retrieve multiple environment variables by name.

{
  "req": "env.get"
}
J *req = NoteNewRequest("env.get");

NoteRequest(req);
req = {"req": "env.get"}
rsp = card.Transaction(req)

Retrieve all environment variables known to the Notecard.

Response Members

body

object

If a name was not specified, an object with name and value pairs for all environment variables.

text

string

If a name was specified, the value of the environment variable.

time

UNIX Epoch time

The time of the Notecard variable or variables change.

Example Response
{
  "monitor-pump-one": "on",
  "time": 1656315835
}

Response for a single environment variable request.

{
  "body": {
    "monitor-pump-one": "on",
    "monitor-pump-two": "off"
  },
  "time": 1656315835
}

Response for multiple environment variables request.

{
  "body": {
    "monitor-pump-one": "on",
    "monitor-pump-two": "off",
    "monitor-pump-three": "on"
  },
  "time": 1656315835
}

Response for all environment variables request.

env.modified CellCell+WiFiLoRaWiFi

Get the time of the update to any environment variable managed by the Notecard.

Arguments

time

UNIX Epoch time (optional)

Request whether the Notecard has detected an environment variable change since a known epoch time.

{
  "req": "env.modified"
}
J *req = NoteNewRequest("env.modified");

NoteRequest(req);
req = {"req": "env.modified"}
rsp = card.Transaction(req)

Get the timestamp of the last environment variable change.

{
  "req": "env.modified",
  "time": 1605814400
}
J *req = NoteNewRequest("env.modified");
JAddNumberToObject(req, "time", 1605814400);

NoteRequest(req);
req = {"req": "env.modified"}
req["time"] = 1605814400
rsp = card.Transaction(req)

Check if environment variables have been modified since a specific time.

Response Members

time

UNIX Epoch time

Timestamp indicating the last time any environment variable was changed on the device.

Example Response
{
  "time": 1605814493
}

env.set CellCell+WiFiWiFi

Sets a local environment variable on the Notecard. Local environment variables cannot be overridden by a Notehub variable of any scope.

deprecated

The env.set API is deprecated as of v7.2.2. We recommend setting environment variables in Notehub using either the Notehub user interface or Notehub API. You may also use the env.default API to provide a default value for an environment variable, until that variable is overridden by a value from Notehub.

Arguments

name

string (optional)

The name of the environment variable (case-insensitive).

text

string (optional)

The value of the variable. Pass "" or omit from the request to delete it.

{
  "req": "env.set",
  "name": "monitor-pump",
  "text": "on"
}
J *req = NoteNewRequest("env.set");
JAddStringToObject(req, "name", "monitor-pump");
JAddStringToObject(req, "text", "on");

NoteRequest(req);
req = {"req": "env.set"}
req["name"] = "monitor-pump"
req["text"] = "on"
rsp = card.Transaction(req)

Set a local environment variable on the Notecard.

{
  "req": "env.set",
  "name": "monitor-pump"
}
J *req = NoteNewRequest("env.set");
JAddStringToObject(req, "name", "monitor-pump");

NoteRequest(req);
req = {"req": "env.set"}
req["name"] = "monitor-pump"
rsp = card.Transaction(req)

Clear a local environment variable by omitting text.

{
  "req": "env.set",
  "name": "debug-mode",
  "text": ""
}
J *req = NoteNewRequest("env.set");
JAddStringToObject(req, "name", "debug-mode");
JAddStringToObject(req, "text", "");

NoteRequest(req);
req = {"req": "env.set"}
req["name"] = "debug-mode"
req["text"] = ""
rsp = card.Transaction(req)

Set an environment variable to an empty string.

Response Members

time

UNIX Epoch time

The logged time of the variable change.

Example Response
{
  "time": 1605814493
}

env.template CellCell+WiFiLoRaWiFi

The env.template request allows developers to provide a schema for the environment variables the Notecard uses. The provided template allows the Notecard to store environment variables as fixed-length binary records rather than as flexible JSON objects that require much more memory.

Using templated environment variables also allows the Notecard to optimize the network traffic related to sending and receiving environment variable updates.

note

The env.template request is required for using environment variables on Notecard LoRa and a Notecard paired with Starnote.

Arguments

body

object (optional)

A sample JSON body that specifies environment variables names and values as "hints" for the data type. Possible data types are: boolean, integer, float, and string. See Understanding Template Data Types for a full explanation of type hints.

{
  "req": "env.template",
  "body": {
    "env_var_int": 11,
    "env_var_string": "10"
  }
}
J *req = NoteNewRequest("env.template");

NoteRequest(req);
req = {"req": "env.template"}
rsp = card.Transaction(req)

Provide a schema with data type hints for environment variables.

{
  "req": "env.template",
  "body": {
    "enabled": true,
    "temperature": 23.5,
    "count": 42,
    "name": "sensor"
  }
}
J *req = NoteNewRequest("env.template");

NoteRequest(req);
req = {"req": "env.template"}
rsp = card.Transaction(req)

Template with multiple data types including boolean and float.

{
  "req": "env.template"
}
J *req = NoteNewRequest("env.template");

NoteRequest(req);
req = {"req": "env.template"}
rsp = card.Transaction(req)

Clear the environment variable template by omitting the body.

Response Members

bytes

integer

The maximum number of bytes that will be used when environment variables are communicated or stored, so long as the variables do not include variable-length strings.

Example Response
{
  "bytes": 22
}
dfu Requests file Requests
Can we improve this page? Send us feedback
© 2025 Blues Inc.
© 2025 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 the Notecard's API on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up