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.
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.
body
object (optional)
A JSON object to be enqueued. A Note must have either a body
or a payload
, and can have both.
file
string (optional, 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
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.
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.
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
.
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.
payload
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}
.
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);
NoteRequest(req);
req = {"req": "note.add"}
req["file"] = "sensors.qo"
req["sync"] = True
rsp = card.Transaction(req)
Add a Note with JSON body data and trigger immediate sync.
Response Members
note
string
The generated unique Note ID when note
parameter was set to "?".
template
boolean
true
when a template is active on the Notefile.
total
integer
The total number of Notes in the Notefile.
{
"total": 12
}
note.changes CellCell+WiFiWiFi
Used to incrementally retrieve changes within a specific Notefile.
delete
boolean (optional)
true
to delete the Notes returned by the request.
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*
).
file
string (optional)
The Notefile ID.
max
integer (optional)
The maximum number of Notes to return in the request.
reset
boolean (optional)
true
to reset a change tracker.
start
boolean (optional)
true
to reset the tracker to the beginning.
stop
boolean (optional)
true
to delete the tracker.
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.
{
"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)
Check changes in a Notefile with a tracker starting from the beginning.
{
"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)
Retrieve and delete up to 2 changes from a Notefile.
{
"req": "note.changes",
"file": "data.db"
}
J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "data.db");
NoteRequest(req);
req = {"req": "note.changes"}
req["file"] = "data.db"
rsp = card.Transaction(req)
Get changes from a Notefile without a tracker.
{
"req": "note.changes",
"file": "events.db",
"tracker": "event-tracker",
"reset": true
}
J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "events.db");
JAddStringToObject(req, "tracker", "event-tracker");
JAddBoolToObject(req, "reset", true);
NoteRequest(req);
req = {"req": "note.changes"}
req["file"] = "events.db"
req["tracker"] = "event-tracker"
req["reset"] = True
rsp = card.Transaction(req)
Reset a change tracker to start from the beginning.
{
"req": "note.changes",
"file": "config.db",
"tracker": "config-tracker",
"deleted": true
}
J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "config.db");
JAddStringToObject(req, "tracker", "config-tracker");
JAddBoolToObject(req, "deleted", true);
NoteRequest(req);
req = {"req": "note.changes"}
req["file"] = "config.db"
req["tracker"] = "config-tracker"
req["deleted"] = True
rsp = card.Transaction(req)
Retrieve changes including deleted notes from database.
{
"req": "note.changes",
"file": "logs.db",
"tracker": "log-tracker",
"stop": true
}
J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "logs.db");
JAddStringToObject(req, "tracker", "log-tracker");
JAddBoolToObject(req, "stop", true);
NoteRequest(req);
req = {"req": "note.changes"}
req["file"] = "logs.db"
req["tracker"] = "log-tracker"
req["stop"] = True
rsp = card.Transaction(req)
Delete a change tracker when finished.
Response Members
changes
integer
The number of pending changes in the Notefile.
notes
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.
total
integer
The total number of Notes in the Notefile.
{
"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
}
}
}
Response showing changes with Note details and timestamps.
{
"changes": 0,
"total": 10,
"notes": {}
}
Response when no changes are available.
{
"changes": 1,
"total": 5,
"notes": {
"config-update": {
"body": {
"brightness": 75,
"volume": 50
},
"time": 1609459200
}
}
}
Response with a single Note change.
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 (optional)
The Notefile from which to delete a Note. Must be a Notefile with a .db
or .dbx
extension.
note
string (optional)
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"
rsp = card.Transaction(req)
Delete a specific Note by ID from a database Notefile.
{
"req": "note.delete",
"file": "config.db",
"note": "display-settings",
"verify": true
}
J *req = NoteNewRequest("note.delete");
JAddStringToObject(req, "file", "config.db");
JAddStringToObject(req, "note", "display-settings");
JAddBoolToObject(req, "verify", true);
NoteRequest(req);
req = {"req": "note.delete"}
req["file"] = "config.db"
req["note"] = "display-settings"
req["verify"] = True
rsp = card.Transaction(req)
Delete a Note and write to flash immediately for a templated Notefile.
{
"cmd": "note.delete",
"file": "temp-data.db",
"note": "sensor-reading"
}
J *req = NoteNewRequest("note.delete");
JAddStringToObject(req, "file", "temp-data.db");
JAddStringToObject(req, "note", "sensor-reading");
NoteRequest(req);
req = {"cmd": "note.delete"}
req["file"] = "temp-data.db"
req["note"] = "sensor-reading"
card.Transaction(req)
Delete a Note using command syntax (no response expected).
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.
decrypt
boolean (optional)
true
to decrypt encrypted inbound Notefiles.
delete
boolean (optional)
true
to delete the Note after retrieving it.
deleted
boolean (optional)
true
to allow retrieval of a deleted Note.
file
string (optional, 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.
{
"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)
Retrieve and delete a Note from an inbound queue file.
{
"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)
Read a specific Note from a database Notefile.
{
"req": "note.get"
}
J *req = NoteNewRequest("note.get");
NoteRequest(req);
req = {"req": "note.get"}
rsp = card.Transaction(req)
Retrieve from the default data.qi
Notefile.
{
"req": "note.get",
"file": "config.db",
"note": "old-setting",
"deleted": true
}
J *req = NoteNewRequest("note.get");
JAddStringToObject(req, "file", "config.db");
JAddStringToObject(req, "note", "old-setting");
JAddBoolToObject(req, "deleted", true);
NoteRequest(req);
req = {"req": "note.get"}
req["file"] = "config.db"
req["note"] = "old-setting"
req["deleted"] = True
rsp = card.Transaction(req)
Retrieve a deleted Note from a .db
Notefile.
{
"req": "note.get",
"file": "secure.qis",
"decrypt": true
}
J *req = NoteNewRequest("note.get");
JAddStringToObject(req, "file", "secure.qis");
JAddBoolToObject(req, "decrypt", true);
NoteRequest(req);
req = {"req": "note.get"}
req["file"] = "secure.qis"
req["decrypt"] = True
rsp = card.Transaction(req)
Retrieve and decrypt an encrypted inbound Note.
Response Members
body
object
The JSON body, if contained in the Note.
payload
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.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.
body
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.
delete
boolean (optional)
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.
file
string (optional)
The name of the Notefile to which the template will be applied.
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.
port
integer (optional)
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.
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");
NoteRequest(req);
req = {"req": "note.template"}
req["file"] = "readings.qo"
rsp = card.Transaction(req)
Provide a template schema for the readings.qo Notefile with sample data.
{
"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");
JAddStringToObject(req, "format", "compact");
JAddNumberToObject(req, "port", 50);
NoteRequest(req);
req = {"req": "note.template"}
req["file"] = "readings.qo"
req["format"] = "compact"
req["port"] = 50
rsp = card.Transaction(req)
Set up a compact template for LoRa transmission on port 50 to reduce bandwidth usage.
{
"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");
JAddStringToObject(req, "format", "compact");
JAddNumberToObject(req, "port", 50);
NoteRequest(req);
req = {"req": "note.template"}
req["file"] = "readings.qo"
req["format"] = "compact"
req["port"] = 50
rsp = card.Transaction(req)
Set up a compact template including location and timestamp fields for comprehensive sensor data.
{
"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)
Retrieve the current template configuration for the readings.qo Notefile.
Response Members
body
object
If the verify
argument is provided and the Notefile has an active template, the template body
.
bytes
integer
The number of bytes that will be transmitted to Notehub, per Note, before compression.
length
integer
If the verify
argument is provided and the Notefile has an active template with a payload, the payload length.
template
boolean
true
if an active template exists on the Notefile.
{
"bytes": 40
}
Response when template is successfully set, showing bytes per note.
{
"template": true,
"body": {
"temperature": 14.1,
"humidity": 11
},
"bytes": 40
}
Response when verifying existing template with all fields.
{
"template": true,
"format": "compact",
"bytes": 25
}
Response showing compact format template.
note.update CellCell+WiFiLoRaWiFi
Updates a Note in a DB Notefile by its ID, replacing the existing body
and/or payload
.
body
object (optional)
A JSON object to add to the Note. A Note must have either a body
or payload
, and can have both.
file
string (optional)
The name of the DB Notefile that contains the Note to update.
note
string (optional)
The unique Note ID.
payload
string (optional)
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");
NoteRequest(req);
req = {"req": "note.update"}
req["file"] = "my-settings.db"
req["note"] = "measurements"
rsp = card.Transaction(req)
Update a Note with new JSON body content.
{
"req": "note.update",
"file": "data.db",
"note": "sensor-1",
"payload": "SGVsbG8gV29ybGQ="
}
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "data.db");
JAddStringToObject(req, "note", "sensor-1");
JAddStringToObject(req, "payload", "SGVsbG8gV29ybGQ=");
NoteRequest(req);
req = {"req": "note.update"}
req["file"] = "data.db"
req["note"] = "sensor-1"
req["payload"] = "SGVsbG8gV29ybGQ="
rsp = card.Transaction(req)
Update a Note with new base64 payload data.
{
"req": "note.update",
"file": "config.db",
"note": "device-config",
"body": {
"enabled": true
},
"payload": "YWRkaXRpb25hbERhdGE="
}
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "config.db");
JAddStringToObject(req, "note", "device-config");
JAddStringToObject(req, "payload", "YWRkaXRpb25hbERhdGE=");
NoteRequest(req);
req = {"req": "note.update"}
req["file"] = "config.db"
req["note"] = "device-config"
req["payload"] = "YWRkaXRpb25hbERhdGE="
rsp = card.Transaction(req)
Update a Note with both body and payload.
{
"req": "note.update",
"file": "template.db",
"note": "user-setting",
"body": {
"theme": "dark"
},
"verify": true
}
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "template.db");
JAddStringToObject(req, "note", "user-setting");
JAddBoolToObject(req, "verify", true);
NoteRequest(req);
req = {"req": "note.update"}
req["file"] = "template.db"
req["note"] = "user-setting"
req["verify"] = True
rsp = card.Transaction(req)
Update a Note in a templated Notefile with immediate flash write.
{
"cmd": "note.update",
"file": "cache.db",
"note": "temp-data",
"body": {
"status": "updated"
}
}
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "cache.db");
JAddStringToObject(req, "note", "temp-data");
NoteRequest(req);
req = {"cmd": "note.update"}
req["file"] = "cache.db"
req["note"] = "temp-data"
card.Transaction(req)
Update a Note using command syntax (no response expected).
Response Members
{}
means success.