note Requests
+The note requests enable the quick creation and management of
+Notes in
+Notefiles.
The requests in this section are available on the Notecard API. Consult the +Notehub Device API to manage inbound and DB +Notefiles from Notehub.
+ +note.add CellCell+WiFiLoRaWiFi
+Adds a Note to a Notefile, creating the Notefile if it doesn't yet exist.
+If a Notefile name is specified, the file must either be a DB Notefile or
+outbound queue file (see file argument below).
file
string (Default: data.qo)
The name of the Notefile.
On Notecard LoRa this argument is required. On all other Notecards this field is
+optional and defaults to data.qo if not provided.
When using this request on the Notecard the Notefile name must end in one of:
.qo for a queue outgoing (Notecard to Notehub) with plaintext transport
.qos for a queue outgoing with encrypted transport
.db for a bidirectionally synchronized database with plaintext transport
.dbs for a bidirectionally synchronized database with encrypted transport
.dbx for a local-only database
note
string (optional)
If the Notefile has a .db/.dbs/.dbx extension, specifies a unique Note ID.
If note string is "?", then a random unique Note ID is generated and returned
+as {"note":"xxx"}.
If this argument is provided for a .qo Notefile, an error is returned.
body
JSON object (optional)
A JSON object to be enqueued. A note must have either a body or a payload,
+and can have both.
payload
base64 string (optional)
A base64-encoded binary payload. A note must have either a body or a
+payload, and can have both. If a
+Note template is not
+in use, payloads are limited to 250 bytes.
sync
boolean (optional)
Set to true to sync immediately. Only applies to outgoing Notecard
+requests, and only guarantees syncing the specified Notefile. Auto-syncing
+incoming Notes from Notehub is set on the Notecard with
+{"req": "hub.set", "mode":"continuous", "sync": true}.
key
string (optional)
The name of an environment variable in your Notehub.io project that contains +the contents of a public key. Used when +encrypting the Note body for transport.
verify
boolean (optional)
If set to true and using a templated Notefile, the Notefile will be written to
+flash immediately, rather than being cached in RAM and written to flash later.
binary
boolean (optional)
If true, the Notecard will send all the data in the binary buffer to Notehub.
Learn more in this guide on +Sending and Receiving Large Binary Objects.
live
boolean (optional)
If true, bypasses saving the Note to flash on the Notecard. Required to be set
+to true if also using "binary":true.
full
boolean (optional)
If set to true, and the Note is using a
+Notefile Template,
+the Note will bypass usage of
+omitempty
+and retain null, 0, false, and empty string "" values.
limit
boolean (optional)
If set to true, the Note will not be created if Notecard is in a
+penalty box.
max
integer (optional)
Defines the maximum number of queued Notes permitted in the specified Notefile
+("file"). Any Notes added after this value will be rejected. When used with
+"sync":true, a sync will be triggered when the number of pending Notes matches
+the max value.
{
+ "req": "note.add",
+ "file": "sensors.qo",
+ "body": { "temp": 72.22 },
+ "sync": true
+}J *req = NoteNewRequest("note.add");
+JAddStringToObject(req, "file", "sensors.qo");
+JAddBoolToObject(req, "sync", true);
+
+J *body = JCreateObject();
+JAddNumberToObject(body, "temp", 72.22);
+JAddItemToObject(req, "body", body);
+
+NoteRequest(req);req = {"req": "note.add"}
+req["file"] = "sensors.qo"
+req["body"] = {"temp": 72.22 }
+req["sync"] = True
+rsp = card.Transaction(req)Response Members
total
The total number of Notes in the Notefile.
template
true when a template is active on the Notefile.
{ "total": 12 }note.changes CellCell+WiFiWiFi
+Used to incrementally retrieve changes within a specific Notefile.
+file
string
The Notefile ID.
tracker
string (optional)
The change tracker ID. This value is developer-defined and can be used
+across both the note.changes and file.changes requests.
max
integer (optional)
The maximum number of Notes to return in the request.
start
boolean (optional)
true to reset the tracker to the beginning.
stop
boolean (optional)
true to delete the tracker.
deleted
boolean (optional)
true to return deleted Notes with this request. Deleted notes are only
+persisted in a database notefile (.db/.dbs) between the time of note deletion
+on the Notecard and the time that a sync with notehub takes place. As such, this
+boolean will have no effect after a sync or on queue notefiles (.q*).
delete
boolean (optional)
true to delete the Notes returned by the request.
reset
boolean (optional)
true to reset a change tracker.
{
+ "req": "note.changes",
+ "file": "my-settings.db",
+ "tracker": "inbound-tracker",
+ "start": true
+}J *req = NoteNewRequest("note.changes");
+JAddStringToObject(req, "file", "my-settings.db");
+JAddStringToObject(req, "tracker", "inbound-tracker");
+JAddBoolToObject(req, "start", true);
+
+NoteRequest(req);req = {"req": "note.changes"}
+req["file"] = "my-settings.db"
+req["tracker"] = "inbound-tracker"
+req["start"] = True
+rsp = card.Transaction(req){
+ "req": "note.changes",
+ "file": "my-settings.db",
+ "tracker": "inbound-tracker",
+ "start": true,
+ "delete": true,
+ "max": 2
+}J *req = NoteNewRequest("note.changes");
+JAddStringToObject(req, "file", "my-settings.db");
+JAddStringToObject(req, "tracker", "inbound-tracker");
+JAddBoolToObject(req, "start", true);
+JAddBoolToObject(req, "delete", true);
+JAddNumberToObject(req, "max", 2);
+
+NoteRequest(req);req = {"req": "note.changes"}
+req["file"] = "my-settings.db"
+req["tracker"] = "inbound-tracker"
+req["start"] = True
+req["delete"] = True
+req["max"] = 2
+rsp = card.Transaction(req)Response Members
total
integer
The total number of Notes in the Notefile.
changes
integer
The number of pending changes in the Notefile.
notes
JSON object
An object with a key for each Note (the Note ID in a DB Notefile or an
+internally-generated ID for .qo and .qi Notes) and value object with the
+body of each Note and the time the Note was added.
{
+ "changes": 4,
+ "total": 4,
+ "notes": {
+ "setting-one": { "body": { "foo": "bar" }, "time": 1598918235 },
+ "setting-two": { "body": { "foo": "bat" }, "time": 1598918245 },
+ "setting-three": { "body": { "foo": "baz" }, "time": 1598918225 },
+ "setting-four": { "body": { "foo": "foo" }, "time": 1598910532 }
+ }
+}note.delete CellCell+WiFiLoRaWiFi
+Deletes a Note from a DB Notefile by its Note ID. To delete
+Notes from a .qi Notefile, use note.get or note.changes with
+delete:true.
file
string
The Notefile from which to delete a Note. Must be a Notefile with
+a .db or .dbx extension.
note
string
The Note ID of the Note to delete.
verify
boolean (optional)
If set to true and using a templated Notefile, the Notefile will be written to
+flash immediately, rather than being cached in RAM and written to flash later.
{
+ "req": "note.delete",
+ "file": "my-settings.db",
+ "note": "measurements"
+}J *req = NoteNewRequest("note.delete");
+JAddStringToObject(req, "file", "my-settings.db");
+JAddStringToObject(req, "note", "measurements");
+
+NoteRequest(req);req = {"req": "note.delete"}
+req["file"] = "my-settings.db"
+req["note"] = "measurements"
+card.Transaction(req)Response Members
{} means success.note.get CellCell+WiFiLoRaWiFi
+Retrieves a Note from a Notefile. The file must either be a DB Notefile or
+inbound queue file (see file argument below).
.qo/.qos Notes must be read from the Notehub event table using the
+Notehub Event API.
file
string (Default: data.qi)
The Notefile name must end in .qi (for plaintext transport), .qis (for
+encrypted transport), .db or .dbx (for local-only DB Notefiles).
note
string (optional)
If the Notefile has a .db or .dbx extension, specifies a unique Note ID. Not
+applicable to .qi Notefiles.
delete
boolean (optional)
true to delete the Note after retrieving it.
deleted
boolean (optional)
true to allow retrieval of a deleted Note.
decrypt
boolean (optional)
true to decrypt
+encrypted inbound Notefiles.
{
+ "req": "note.get",
+ "file": "requests.qi",
+ "delete": true
+}J *req = NoteNewRequest("note.get");
+JAddStringToObject(req, "file", "requests.qi");
+JAddBoolToObject(req, "delete", true);
+
+NoteRequest(req);req = {"req": "note.get"}
+req["file"] = "requests.qi"
+req["delete"] = True
+rsp = card.Transaction(req){
+ "req": "note.get",
+ "file": "my-settings.db",
+ "note": "measurements"
+}J *req = NoteNewRequest("note.get");
+JAddStringToObject(req, "file", "my-settings.db");
+JAddStringToObject(req, "note", "measurements");
+
+NoteRequest(req);req = {"req": "note.get"}
+req["file"] = "my-settings.db"
+req["note"] = "measurements"
+rsp = card.Transaction(req)Response Members
body
JSON object
The JSON body, if contained in the Note.
payload
base64 string
The payload, if contained in the Note.
time
UNIX Epoch time
The time the Note was added to the Notecard or Notehub.
{
+ "body": {
+ "api-key1": "api-val1"
+ },
+ "time": 1598909219
+}note.update CellCell+WiFiLoRaWiFi
+Updates a Note in a DB Notefile by its ID, replacing the existing body
+and/or payload.
file
string
The name of the DB Notefile that contains the Note to update.
note
string
The unique Note ID.
body
JSON object
A JSON object to add to the Note. A Note must have either a body or payload,
+and can have both.
payload
base64 string
A base64-encoded binary payload. A Note must have either a body or payload,
+and can have both.
verify
boolean (optional)
If set to true and using a templated Notefile, the Notefile will be written to
+flash immediately, rather than being cached in RAM and written to flash later.
{
+ "req": "note.update",
+ "file": "my-settings.db",
+ "note": "measurements",
+ "body": { "interval": 60 }
+}J *req = NoteNewRequest("note.update");
+JAddStringToObject(req, "file", "my-settings.db");
+JAddStringToObject(req, "note", "measurements");
+
+J *body = JCreateObject();
+JAddNumberToObject(body, "interval", 60);
+JAddItemToObject(req, "body", body);
+
+NoteRequest(req);req = {"req": "note.update"}
+req["file"] = "my-settings.db"
+req["note"] = "measurements"
+req["body"] = {"interval": 60 }
+card.Transaction(req)Response Members
{} means success.note.template CellCell+WiFiLoRaWiFi
+By using the note.template request with any .qo/.qos Notefile,
+developers can provide the Notecard with a schema of sorts to apply to
+future Notes added to the Notefile. This template acts as a hint to
+the Notecard that allows it to internally store data as fixed-length binary
+records rather than as flexible JSON objects which require much more
+memory. Using templated Notes in place of regular Notes increases the storage
+and sync capability of the Notecard by an order of magnitude.
Read about +Working with Note Templates +for additional information.
+++See examples of
+note.templateusage in +these accelerator projects.
file
string
The name of the Notefile to which the template will be applied.
body
JSON object (optional)
A sample JSON body that specifies field names and values as +"hints" for the data type. Possible data types are: boolean, integer, float, +and string. +See Understanding Template Data Types +for an explanation of type hints and explanations.
length
integer (optional)
The maximum length of a payload (in bytes) that can be sent in Notes for the
+template Notefile. As of v3.2.1 length is not required, and
+payloads can be added to any template-based Note without specifying the payload
+length.
verify
boolean (optional)
If true, returns the current template set on a given Notefile.
format
string (optional)
By default all Note templates automatically include metadata, including a +timestamp for when the Note was created, various fields about a device's +location, as well as a timestamp for when the device's location was determined.
By providing a format of "compact" you tell the Notecard to omit this
+additional metadata to save on storage and bandwidth. The use of
+format: "compact" is required for Notecard LoRa and a Notecard paired with
+Starnote.
When using "compact" templates, you may include the following keywords in
+your template to add in fields that would otherwise be omitted: _lat, _lon,
+_ltime, _time. See
+Creating Compact Templates
+to learn more.
port
integer
This argument is required on Notecard LoRa and a Notecard paired with Starnote, +but ignored on all other Notecards.
A port is a unique integer in the range 1–100, where each unique number represents +one Notefile. This argument allows the Notecard to send a numerical reference to +the Notefile over the air, rather than the full Notefile name.
The port you provide is also used in the “frame port” field on LoRaWAN gateways.
delete
boolean
Set to true to delete all pending Notes using the template if one of the
+following scenarios is also true:
Connecting via non-NTN (e.g. cellular or Wi-Fi) communications, but attempting +to sync NTN-compatible Notefiles.
or
Connecting via NTN (e.g. satellite) communications, but attempting to sync +non-NTN-compatible Notefiles.
Read more about this feature in +Starnote Best Practices.
{
+ "req": "note.template",
+ "file": "readings.qo",
+ "body": {
+ "new_vals": true,
+ "temperature": 14.1,
+ "humidity": 11,
+ "pump_state": "4"
+ }
+}J *req = NoteNewRequest("note.template");
+JAddStringToObject(req, "file", "readings.qo");
+
+J *body = JCreateObject();
+JAddBoolToObject(body, "new_vals", true);
+JAddNumberToObject(body, "temperature", 14.1);
+JAddNumberToObject(body, "humidity", 11);
+JAddStringToObject(body, "pump_state", "4");
+JAddItemToObject(req, "body", body);
+
+NoteRequest(req);req = {"req": "note.template"}
+req["file"] = "readings.qo"
+req["body"] = {
+ "new_vals": True,
+ "temperature": 14.1,
+ "humidity": 11,
+ "pump_state": "4"
+ }
+rsp = card.Transaction(req){
+ "req": "note.template",
+ "file": "readings.qo",
+ "body": {
+ "new_vals": true,
+ "temperature": 14.1,
+ "humidity": 11,
+ "pump_state": "4"
+ },
+ "format": "compact",
+ "port": 50
+}J *req = NoteNewRequest("note.template");
+JAddStringToObject(req, "file", "readings.qo");
+
+J *body = JCreateObject();
+JAddBoolToObject(body, "new_vals", true);
+JAddNumberToObject(body, "temperature", 14.1);
+JAddNumberToObject(body, "humidity", 11);
+JAddStringToObject(body, "pump_state", "4");
+JAddItemToObject(req, "body", body);
+
+JAddStringToObject(req, "format", "compact");
+JAddNumberToObject(req, "port", 50);
+
+NoteRequest(req);req = {"req": "note.template"}
+req["file"] = "readings.qo"
+
+req["body"] = {
+ "new_vals": True,
+ "temperature": 14.1,
+ "humidity": 11,
+ "pump_state": "4"
+}
+
+req["format"] = "compact"
+req["port"] = 50
+
+rsp = card.Transaction(req){
+ "req": "note.template",
+ "file": "readings.qo",
+ "body": {
+ "temperature": 14.1,
+ "_lat": 14.1,
+ "_lon": 14.1,
+ "_ltime": 14,
+ "_time": 14
+ },
+ "format": "compact",
+ "port": 50
+}J *req = NoteNewRequest("note.template");
+JAddStringToObject(req, "file", "readings.qo");
+
+J *body = JCreateObject();
+JAddNumberToObject(body, "temperature", 14.1);
+JAddNumberToObject(body, "_lat", 14.1);
+JAddNumberToObject(body, "_lon", 14.1);
+JAddNumberToObject(body, "_ltime", 14);
+JAddNumberToObject(body, "_time", 14);
+JAddItemToObject(req, "body", body);
+
+JAddStringToObject(req, "format", "compact");
+JAddNumberToObject(req, "port", 50);
+
+NoteRequest(req);req = {"req": "note.template"}
+req["file"] = "readings.qo"
+req["format"] = "compact"
+req["port"] = 50
+req["body"] = {
+ "new_vals": True,
+ "temperature": 14.1,
+ "_lat": 14.1,
+ "_lon": 14.1,
+ "_ltime": 14,
+ "_time": 14
+}
+rsp = card.Transaction(req){
+ "req": "note.template",
+ "file": "readings.qo",
+ "verify": true
+}J *req = NoteNewRequest("note.template");
+JAddStringToObject(req, "file", "readings.qo");
+JAddBoolToObject(req, "verify", true);
+
+NoteRequest(req);req = {"req": "note.template"}
+req["file"] = "readings.qo"
+req["verify"] = True
+rsp = card.Transaction(req)Response Members
bytes
integer
The number of bytes that will be transmitted to Notehub, per Note, before +compression.
template
boolean
true if an active template exists on the Notefile.
body
If the verify argument is provided and the Notefile has an active template,
+the template body
length
If the verify argument is provided and the Notefile has an active template
+with a payload, the payload length.
format
If the format argument is provided, this represents the format applied to the
+template.
{
+ "bytes": 40
+}