env Requests
Environment variables are key-value pairs that can be set on a device, project, or fleet.
The Hierarchy of Environment Variables
Environment variables can be defined in a number of locations, from the Notecard, to Notehub device settings, the device's 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 local value.
- The value set in Notehub directly on Notehub's record for the Device.
- 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 default value defined with the
env.default
request.
See environment variables in action in these accelerator projects.
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.
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.
name
string
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"
card.Transaction(req)
{
"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"
card.Transaction(req)
Response Members
{}
means success.env.get CellCell+WiFiLoRaWiFi
Returns a single environment variable, or all variables according to precedence rules.
name
string (optional)
The name of the environment variable (case-insensitive). Omit to return all environment variables known to the Notecard.
{
"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)
{
"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)
{
"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)
{
"req": "env.get"
}
J *req = NoteNewRequest("env.get");
NoteRequest(req);
req = {"req": "env.get"}
rsp = card.Transaction(req)
Response Members
text
string
If a name
was specified, the value of the environment variable.
body
JSON object
If a name
was not specified, an object with name
and value
pairs for
all environment variables.
{
"text": "on",
"time": 1656315835
}
{
"err": "environment hasn't been modified {env-not-modified}"
}
{
"body": {
"monitor-pump-one": "on",
"monitor-pump-two": "off"
},
"time": 1656315835
}
{
"body": {
"monitor-pump-one": "on",
"monitor-pump-two": "off",
"monitor-pump-three": "on"
},
"time": 1656315835
}
env.modified CellCell+WiFiLoRaWiFi
Get the time of the update to any environment variable managed by the Notecard.
{
"req": "env.modified"
}
J *req = NoteNewRequest("env.modified");
NoteRequest(req);
req = {"req": "env.modified"}
rsp = card.Transaction(req)
Response Members
time
UNIX Epoch time
Timestamp indicating the last time any environment variable was changed on the device.
{
"time": 1605814493
}
env.set CellCell+WiFiWiFi
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.
Sets a local environment variable on the Notecard. Local environment variables cannot be overridden by a Notehub variable of any scope.
name
string
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"
card.Transaction(req)
{
"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"
card.Transaction(req)
Response Members
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.
The env.template
request is required for using environment variables on
Notecard LoRa and a Notecard paired with Starnote.
body
JSON 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");
J *body = JCreateObject();
JAddNumberToObject(body, "env_var_int", 11);
JAddStringToObject(body, "env_var_string", "10");
JAddItemToObject(req, "body", body);
NoteRequest(req);
req = {"req": "env.template"}
req["body"] = {
"env_var_int": 11,
"env_var_string": "10"
}
rsp = card.Transaction(req)
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.
{
"bytes": 22
}