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 an RSA public key. Used when encrypting the Note body for transport. Only applies to Notecard requests.
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.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 Notefiles 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.
{
"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.template
usage 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.
{
"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.
{
"bytes": 40
}