env Requests
Environment variables are key-value pairs that can be set on a device, project, or fleet.
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 (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
{}
means success.env.get CellCell+WiFiLoRaWiFi
Returns a single environment variable, or all variables according to precedence rules.
Before using the env.get
API on Notecard for LoRa or Starnote, you must create an environment variable template using the env.template API.
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)
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.
{
"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.
{
"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": 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.
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.
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": 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.
The env.template
request is required for using environment variables on Notecard LoRa and a Notecard paired with Starnote.
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.
{
"bytes": 22
}