Rate this page  

When building an embedded application with the Notecard, there are a number of essential API requests to know.

Every Notecard must be configured for your project before it can sync data to Notehub. The hub.set request is used to:

  • Assign a Notehub ProductUID to the Notecard.
  • Optionally set a Serial Number for the Notecard.
  • Configure the synchronization mode between the Notecard and Notehub.

Most of the time, your first request to the Notecard in a new application will be to set the ProductUID. This is done with the hub.set request and product argument, which will correspond to a ProductUID pre-configured in Notehub. If the Notecard attempts to sync with a missing ProductUID, the device will be rejected by Notehub.

{
 "req": "hub.set",
 "product": "org.coca-cola.soda.vending-machine.v2"
}

Optionally, you can associate your product’s serial number (as an arbitrary string) with the Notecard by using hub.set with the sn argument. This arbitrary field can be used to more easily identify devices in Notehub or your own cloud applications.

{
 "req": "hub.set",
 "product": "org.coca-cola.soda.vending-machine.v2",
 "sn": "your-serial-number"
}

The Notecard's connection to Notehub is configurable, and can be adjusted based on the battery and data needs of your application. The mode field of hub.set accepts the following values:

  • periodic - (Default) "On demand" mode. The Notecard will periodically power-on the modem and connect to Notehub whenever it needs to synchronize with the service, and will then power-off the modem when not in use.
  • continuous - The Notecard will keep the cellular modem continuously powered-on and connected to Notehub.
  • minimum - Disables automatic connection to Notehub. In this mode, you will need to manually send a hub.sync request to trigger a sync.
  • off - Disables both automatic and manual connection to Notehub. This is, in essence, the Notecard’s "airplane mode" which ensures that the modem will not power-on under any circumstances.
{
 "req": "hub.set",
 "mode": "minimum"
}

In the case of both periodic and continuous sync modes, the Notecard will periodically synchronize both outbound and inbound data with Notehub using a timing algorithm set by the configured outbound and inbound "sync times" (see below). If your application is using continuous mode and is expecting inbound data from the service where responsiveness is key, adding the sync flag will cause inbound data from Notehub to be synchronized to the Notecard as soon as it is detected.

{
 "req": "hub.set",
 "mode": "continuous",
 "sync": true
}

After setting the synchronization mode, tune the frequency of outbound and inbound sync requests using the outbound and inbound arguments. These values are required if operating in periodic or continuous mode.

The outbound argument configures the max wait time (in minutes) to sync outbound data, such as new Notes added by the host application. Data may sync more frequently, but the Notecard will never wait longer than this amount of time to initiate a sync, if data is awaiting upload. The value passed into this field must be an integer.

{
 "req": "hub.set",
 "outbound": 60
}

The inbound field configures the max wait time (in minutes) to sync inbound data, such as environment variables or inbound Notes from Notehub. Data may sync more frequently, but the Notecard will never wait longer than this amount of time to initiate a sync. The value passed into this field must be an integer.

{
 "req": "hub.set",
 "inbound": 120
}

When the Notecard establishes a new session with Notehub, it syncs information (for example, signal strength and device location) that is not included in every individual Note. When operating in continuous mode, the Notecard maintains a connection to Notehub and does not end or start new sessions as long as the device is powered. If you need to obtain session-specific data on a periodic basis, use the duration argument, and provide an integer value to represent the session duration, in minutes.

{
 "req": "hub.set",
 "duration": 240
}

Once set, after the duration period elapses, the Notecard will gracefully drop the current session and immediately establish a new one to sync session information.

note

Combining Requests

The prior requests, and the majority of requests in this guide, do not need to be performed separately. For instance, it's common for a host application to set the ProductUID, mode and wait options on boot. This can be performed with the following request:

{
 "req": "hub.set",
 "product": "org.coca-cola.soda.vending-machine.v2",
 "sn": "SuperChiller0001",
 "mode": "continuous",
 "outbound": 60,
 "inbound": 120,
 "sync": true
}

The result of all hub.set requests, if successful, is an empty JSON object ({}).

When you're ready to add data to your Notecard for synchronization, do so with the note.add request. This request adds a single Note with an arbitrary body or payload to a Notefile, which is an outbound queue of data to synchronize to Notehub.

By default, all Notes are added to the data.qo Notefile. The qo extension signifies that this is an outbound queue Notefile.

{
 "req": "note.add",
 "body": {
  "foo": "bar"
 }
}

The body field of a note.add request must be a valid JSON object. The contents of that object are up to you and can be fully customized for your application.

{
 "req": "note.add",
 "body": {
  "temp": 23.134,
  "active": true,
  "timestamp": 1598304729
 }
}

If you wish to organize your Notes by function or type of data being captured, you can use the file field to specify a Notefile ID of your choosing, ending in a .qo extension.

{
 "req": "note.add",
 "file": "sensors.qo",
 "body": {
  "foo": "bar"
 }
}

If you want to ensure that Notes are sent over encrypted TLS to Notehub, use the .qos extension. qos signifies that the Notefile is a secure outbound queue.

{
 "req": "note.add",
 "file": "sensors.qos",
 "body": {
  "foo": "bar"
 }
}

In some "retrofit" applications, the Notecard is used to upload data generated by pre-existing host firmware that already encodes data in a binary format. These applications can easily attach the Base64-encoded binary data to a Note by using the payload field.

{
 "req": "note.add",
 "file": "sensors.qos",
 "payload": "ewogICAgInRlbXAiOiAyMy4xMzQKfQ=="
}

It's also possible to send both a body and a payload as a single Note.

{
 "req": "note.add",
 "file": "sensors.qos",
 "body": {
  "user": "me@blues.io"
 },
 "payload": "wogICAgInBhc3N3b3JkIjogIm5pY2UtdHJ5ISIKfQ=="
}

Finally, if you want to initiate a sync immediately after adding a note, set the sync field to true.

{
 "req": "note.add",
 "file": "sensors.qos",
 "body": {
  "foo": "bar"
 },
 "sync": true
}

The result of all note.add requests, if successful, is the total number of Notes pending sync in the specified or default Notefile.

{"total":3}
note

Use Templates for your production apps

Working with ad-hoc Notes is a great way to get started with and build your Notecard-based prototypes. However, as your project gets closer to deployment, and as you're working with more data, you'll want to use Templates for Notes and Notefiles. Templates allow you to define a schema for Notes, which the Notecard then uses to store data in smaller chunks for storage and transfer.

In IoT applications, many products require configuration variables or settings that can be used on an end device, but managed and updated once the product is deployed in the field. In addition, these products often need the ability to manage these values at multiple levels, from the device to a fleet or even an entire product and all of its deployed devices.

Environment variables are a Notecard and Notehub feature that enables settings synchronization that "just work," with no special setup or configuration needed. These variables are key-value pairs, can be set in Notehub and propagate to devices in a project or fleet, or set on a Notecard directly using the same synchronization mechanism used for Notes and Notefiles.

On the Notecard, env.get is used to obtain one or more environment variables and env.set is used to set a variable on that Notecard only, overriding any Notehub setting of that variable. env.default is used to set default values, on that Notecard, that are overwritten if that variable is also set at Notehub. Finally, env.modified is used to determine if any environment variables have changed.

Use the env.get request to retrieve all variables or a single variable, by name. To get all variables, simply send an env.get request with no arguments.

{"req": "env.get"}

When requesting all variables, the Notecard returns each key-value pair in the body of the response object.

{
  "body": {
    "monitor-pump":"true",
    "_tags":"office"
  }
}

To retrieve a single environment variable, use the name field to specify the variable you want.

{
 "req": "env.get",
 "name": "monitor-pump"
}

When requesting a single variable, the Notecard returns an object with a key of text and value corresponding to the variable name provided.

{"text": "true"}

If the name provided does not match a known variable, or if no variables exist on the Notecard or Notehub, an empty JSON object ({}) is returned.

note

The Hierarchy of Environment Variables

Environment variables can be defined in a number of locations, from the Notecard, to Notehub device settings, the device's Fleet, and the Notehub project. Variables set at different levels of this hierarchy can override one another. When obtaining an environment variable, the Notecard uses the following priority order, where the fist matched result is returned:

  1. The value set on that Notecard with the env.set request.
  2. The value set in Notehub directly on Notehub's record for the Device.
  3. The value set in Notehub on a Fleet to which the Device belongs.
  4. The value set in Notehub on the Project to which the Device belongs.
  5. The value set on that Notecard with the env.default request.

Use the env.default request to set a default value for the host. Once this value is set, it will be returned as defined by env.get unless the variable has been overridden by another env.set request or the Notehub.

For instance, assume that you need to create a variable to determine whether your Host MCU should monitor a connected pump, and that you want to be able to override this value from your Notehub project. To set a default, you'd send the following request:

{
 "req": "env.default",
 "name": "monitor-pump",
 "text": "true"
}

Then, your host can obtain this value using env.get:

{
 "req": "env.get",
 "name": "monitor-pump"
}

Which returns the following:

{"text": "true"}

If, in the future, a Notehub administrator wishes to disable monitoring without having to directly update the Notecard, they can do so by setting the monitor-pump variable directly in the Notehub UI. After the next sync, a env.get request will return this overridden value, and your host MCU can respond accordingly.

{
 "req": "env.get",
 "name": "monitor-pump"
}

Which returns the following:

{"text": "false"}

env.default can also be used to remove environment variables. Simply provide the variable name, but omit the text field, and the variable will be removed from the Notecard's internal storage.

{
 "req": "env.default",
 "name": "monitor-pump"
}

The result of all env.default requests, if successful, is an empty JSON object ({}).

Use the env.set request to set an environment variable only on the Notecard. This variable will be returned in env.get requests, and sent to Notehub in the next sync, but cannot be overridden by Notehub.

To set a variable, the name and text fields are used to set the variable name and value, respectively.

{
 "req": "env.set",
 "name": "monitor-pump",
 "text": "false"
}

env.set can also be used to remove environment variables. Simply provide the variable name, but omit the text field, and a locally-defined variable will be removed from the Notecard's internal storage.

{
 "req": "env.set",
 "name": "monitor-pump"
}

The result of all env.set requests, if successful, is an empty JSON object, ({}).

When working with multiple environment variables on a device, it can become cumbersome for the host to continually check each variable to determine which values have changed. In these cases, use env.modified to obtain the time of the last update to any environment variable managed by the Notecard.

{
  "req":  "env.modified"
}

The result, if successful, is an empty JSON object ({}) if the Notecard is not tracking any environment variables, or a UNIX epoch timestamp indicating the last time any environment variable was changed on the device.

{
  "time": 1605814493
}

When performing this request periodically, if the time value is unchanged between requests, it indicates that no environment variables have changed since the last request.

note

env.modified does not indicate which environment variable on the Notecard has changed, only that a local variable has been modified. Use env.get to retrieve the latest variable values after issuing this request, if needed.

In addition to providing interfaces for setting synchronization settings on the Notecard, the hub API provides a number of requests for getting settings, initiating syncs and sending logs to Notehub.

To check all of the current configuration parameters on the Notecard, use the hub.get request:

{"req": "hub.get"}

The Notecard will return an object with the DeviceUID, ProductUID, and Serial number of your Notecard, as well as the Notehub host, mode, outbound, and inbound max sync time values.

{
 "device": "dev:0000000000000000",
 "product": "com.your-company.your-name:your_product",
 "mode": "continuous",
 "outbound": 60,
 "inbound": 120,
 "host": "a.notefile.net",
 "sn": "your-serial-number",
 "sync": true
}

If you want to check on the status of your Notecard's connection to the cellular network and Notehub, use the hub.status request:

{"req": "hub.status"}

This request will return an object with:

  • status - The current status of the Notecard's network connection.
  • connected - A boolean indicating whether the Notecard is connected to Notehub.
{
 "status": "connected (session open) {connected}",
 "connected": true
}

If you need to manually initiate a sync between your Notecard and Notehub, you can do so with the hub.sync request. If your Notecard is set to minimum mode, this request must be issued to trigger a sync. If your Notecard is set to off mode, this request will be ignored.

{"req": "hub.sync"}

The result of a hub.sync request, if successful, is an empty JSON object ({}).

If you wish to check on the status of a recently triggered or previous sync, you can do so with the hub.sync.status request.

{"req": "hub.sync.status"}

In response, the Notecard will return an object that varies based on the conditions of the request.

A sync in-progress will return the status of the sync, and the requested field, which represents the number of seconds since the sync was initiated.

{
 "status": "starting communications {wait-module} {connecting}",
 "requested": 8
}

A successful sync will return the status, along with the Unix epoch time when the sync was completed, and the completed field to represent the number of seconds since the sync completed:

{
 "status": "completed {sync-end}",
 "time": 1598367163,
 "completed": 1648
}

If the sync was triggered manually, the sync field will be returned and set to true:

{
 "status": "completed {sync-end}",
 "time": 1598367163,
 "sync": true,
 "completed": 1648
}

If an error occurs during a sync, the alert field is returned and set to true.

{
 "status": "merge notefile: sensors.qo",
 "time": 1598371227,
 "alert": true,
 "completed": 37
}

You can also trigger a sync through a call to hub.sync.status by setting the sync field to true. This auto-initiates the sync if the Notecard has pending outbound data.

{
 "req": "hub.sync.status",
 "sync": true
}

In response to this variant of hub.sync.request, the Notecard will return a status string and sync field.

{
 "status": "get notebox change summary",
 "sync": true
}

If you need to send log messages from the Notecard to Notehub, you can do so with the hub.log request. These messages are added as Notes in a special _health.qo Notefile and sent to Notehub on the next sync.

{
 "req": "hub.log",
 "text": "Just wanted to say hi"
}

To mark the message as urgent, use the alert field:

{
 "req": "hub.log",
 "text": "something has gone wrong",
 "alert": true
}

If you need to trigger a sync immediately after queueing the message, set the sync field to true:

{
 "req": "hub.log",
 "text": "something has gone wrong",
 "alert": true,
 "sync": true
}

The result of a hub.log request, if successful, is an empty JSON object ({}).