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.

env.default

Supported on
CellCell+WiFiLoRaSkyloWiFi

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

On Notecard for LoRa, you must define the variable with env.template first. Defaults set with env.default on Notecard for LoRa also 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

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

sync

boolean (optional)

Set to true to trigger an immediate sync.

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

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

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

Set a default environment variable and trigger an immediate sync.

Response Members

time

UNIX Epoch time

The time the Notecard's environment variables were last modified. Omitted if they have never been modified.

Example Response
{
  "time": 1605814493
}
Related Articles

env.get

Supported on
CellCell+WiFiLoRaSkyloWiFi

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

note

Before using the env.get API on Notecard for LoRa, Notecard for Skylo in NTN mode, or a Notecard paired with 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)

Use to fetch variables only when something has changed. Pass the time from a previous env.get or env.modified response. If no environment variable has changed since then, the request returns an {env-not-modified} error.

{
  "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 the environment has changed since 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 name was not specified, an object containing the requested variables (those listed in names, or all variables) as name/value pairs.

text

string

If name was specified, the value of the environment variable. Omitted if the variable is not set.

time

UNIX Epoch time

The time of the most recent change to any environment variable on the Notecard, not just to the variables returned. This field is only included when neither name nor names was specified in the request.

Example Response
{
  "text": "on"
}

Response for a single environment variable request.

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

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.

Related Articles

env.modified

Supported on
CellCell+WiFiLoRaSkyloWiFi

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

Arguments

time

UNIX Epoch time (optional)

Cell Cell+WiFi Skylo WiFi

The time from a previous env.modified or env.get response. If no environment variable has changed since then, the request returns an {env-not-modified} error instead of a new 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
}
Related Articles

env.set

Supported on
CellCell+WiFiSkyloWiFi

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

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.

Response Members

time

UNIX Epoch time

The time the Notecard's environment variables were last modified.

Example Response
{
  "time": 1605814493
}
Related Articles

env.template

Supported on
CellCell+WiFiLoRaSkyloWiFi

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 for LoRa, Notecard for Skylo in NTN mode, 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");
J *body = JAddObjectToObject(req, "body");
JAddNumberToObject(body, "env_var_int", 11);
JAddStringToObject(body, "env_var_string", "10");

NoteRequest(req);
req = {"req": "env.template"}
req["body"] = {"env_var_int": 11, "env_var_string": "10"}
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");
J *body = JAddObjectToObject(req, "body");
JAddBoolToObject(body, "enabled", true);
JAddNumberToObject(body, "temperature", 23.5);
JAddNumberToObject(body, "count", 42);
JAddStringToObject(body, "name", "sensor");

NoteRequest(req);
req = {"req": "env.template"}
req["body"] = {"enabled": true, "temperature": 23.5, "count": 42, "name": "sensor"}
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
}
Related Articles
dfu Requests file Requests