homechevron_rightDocschevron_rightAPI Referencechevron_rightNotecard APIchevron_righthub Requests - API Reference

hub Requests

The hub set of requests provide a variety of ways for a developer to configure and monitor the connection between the Notecard and Notehub.

hub.device.signal This request can be performed using the Notehub API.Notehub

warning

The hub.device.signal API has been deprecated in favor of the Send Device Signal Notehub API.

Send a signal from Notehub to a Notecard.

note

A Notecard can receive a signal with the hub.signal request.

Arguments

body

JSON object (optional)

The JSON object to send.

product

string

The ProductUID from a Notehub project.

device

string

The globally-unique DeviceUID of a device that currently exists within the specified ProductUID.

You may alternatively provide a device serial number by prefixing this argument with sn:, for example sn:my-device.

token

string

A Notehub API session token. Please note this authentication option is deprecated.

curl -L 'https://api.notefile.net/req?product=com.product.name'
    -d '{"req":"hub.device.signal","device":"dev:000000000000000", "body":{"key":"value"}}'
    -H 'X-Session-Token: <token>'
Response Members

connected

boolean

true if the Notecard is connected to Notehub.

Example Response
{
  "connected": true
}

hub.get This request is available on all versions of Notecard Cellular.CellThis request is available on Notecard Cell+WiFi.Cell+WiFiThis request is available on Notecard LoRa.LoRaThis request is available on all versions of Notecard WiFi.WiFi

Retrieves the current Notehub configuration for the Notecard.

Arguments
None
{
  "req": "hub.get"
}
J *req = NoteNewRequest("hub.get");

NoteRequest(req);
req = {"req": "hub.get"}
rsp = card.Transaction(req)
Response Members

device

string

The DeviceUID for the Notecard.

product

string

The ProductUID to which the Notecard is registered.

mode

string

The current operating mode of the Notecard, as defined in hub.set.

outbound

integer

The max wait time, in minutes, to sync outbound data from the Notecard.

voutbound

string

If outbound is overridden with a voltage-variable value.

inbound

integer

The max wait time, in minutes, to sync inbound data from Notehub.

vinbound

string

If inbound has been overridden with a voltage-variable value.

host

string

The URL of the Notehub host.

sn

string

The serial number of the device, if set.

sync

boolean

true if the device is in continuous mode and set to sync every time a change is detected.

Example Response
{
  "device": "dev:000000000000000",
  "product": "com.your-company.your-name:your_product",
  "mode": "periodic",
  "outbound": 60,
  "inbound": 240,
  "host": "a.notefile.net",
  "sn": "your-serial-number"
}

hub.log This request is available on all versions of Notecard Cellular.CellThis request is available on Notecard Cell+WiFi.Cell+WiFiThis request is available on all versions of Notecard WiFi.WiFi

Add a "device health" log message to send to Notehub on the next sync.

See hub.log in action as part of the Cold Chain Monitor accelerator project.

Arguments

text

string

alert

boolean

true if the message is urgent.

sync

boolean

true if a sync should be initiated immediately. Setting true will also remove the Notecard from certain types of penalty boxes.

{
  "req": "hub.log",
  "text": "something is wrong!",
  "alert": true,
  "sync": true
}
J *req = NoteNewRequest("hub.log");
JAddStringToObject(req, "text", "something is wrong");
JAddBoolToObject(req, "alert", true);
JAddBoolToObject(req, "sync", true);

NoteRequest(req);
req = {"req": "hub.log"}
req["text"] = "something is wrong!"
req["alert"] = True
req["sync"] = True
card.Transaction(req)
Response Members
None: an empty object {} means success.
More information:

hub.set This request is available on all versions of Notecard Cellular.CellThis request is available on Notecard Cell+WiFi.Cell+WiFiThis request is available on Notecard LoRa.LoRaThis request is available on all versions of Notecard WiFi.WiFi

The hub.set request is the primary method for controlling the Notecard's Notehub connection and sync behavior.

Arguments

product

string (optional)

A Notehub-managed unique identifier that is used to match Devices with Projects. This string is used during a device's auto-provisioning to find the Notehub Project that, once provisioned, will securely manage the device and its data.

host

string (optional)

The URL of the Notehub service. Use "-" to reset to the default value.

mode

string enumeration (optional)

The Notecard's synchronization mode. Must be one of:

periodic

Periodically connect to the Notehub. This is the default value set on each Notecard after a factory reset.

continuous

Enables an always-on network connection, for high power devices. Outbound data still syncs periodically, unless specified in a Note or File request.

minimum

Disables periodic connection. The Notecard will not sync until it receives an explicit hub.sync request.

off

Disables automatic and manual syncs. hub.sync requests will be ignored in this mode.

dfu

For putting the Notecard in DFU mode for a host firmware update. This mode is effectively the same as off in terms of the Notecard's network and Notehub connections.

sn

string (optional)

The end product's serial number.

outbound

integer (optional)

The max wait time, in minutes, to sync outbound data from the Notecard.

duration

integer (optional)

When in continuous mode, the amount of time, in minutes, of each session. When this time elapses, the Notecard gracefully ends the current session and starts a new one in order to sync session-specific data to Notehub.

voutbound

string (optional)

Overrides outbound with a voltage-variable value. See Modem Power Management for more information on configuring voutbound.

inbound

integer (optional)

The max wait time, in minutes, to sync inbound data from Notehub.

vinbound

string (optional)

Overrides inbound with a voltage-variable value.

align

boolean (optional)

Use true to align syncs on a regular time-periodic cycle.

For example: Assuming outbound = 15 minutes, with align:true the Notecard will look at UTC time, and when it's an even multiple of 15, it will perform a sync. Without align (the default behavior), it will wait 15 minutes after the previously completed sync.

sync

boolean (optional)

If in continuous mode, automatically and immediately sync each time an inbound Notefile change is detected on Notehub.

on (Added in v.3.4.1)

boolean (optional)

If in periodic mode, temporarily switch to continuous mode so that the host can perform a web transaction. Ignored if the Notecard is already in continuous mode.

seconds (Added in v.3.4.1)

integer (optional)

If in periodic mode and using on above, the number of seconds to run in continuous mode before switching back to periodic mode. If not set, a default of 300 seconds is used. Ignored if the Notecard is already in continuous mode.

off (Added in v.3.4.1)

boolean (optional)

Set to true to manually instruct the Notecard to resume periodic mode after a web transaction has completed.

uperiodic (Added in LTS v.4.1.1)

boolean (optional)

Set to true to use USB/line power variable sync behavior, enabling the Notecard to stay in continuous mode when connected to USB/line power and fallback to periodic mode when disconnected.

umin (Added in LTS v.4.1.1)

boolean (optional)

Set to true to use USB/line power variable sync behavior, enabling the Notecard to stay in continuous mode when connected to USB/line power and fallback to minimum mode when disconnected.

uoff (Added in LTS v.4.1.1)

boolean (optional)

Set to true to use USB/line power variable sync behavior, enabling the Notecard to stay in continuous mode when connected to USB/line power and fallback to off mode when disconnected.

{
  "req": "hub.set",
  "product": "com.your-company.your-name:your_product",
  "sn": "Sprocket123"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "product", "com.your-company.your-name:your_product");
JAddStringToObject(req, "sn", "Sprocket123");

NoteRequest(req);
req = {"req": "hub.set"}
req["product"] = "com.your-company.your-name:your_product"
req["sn"] = "Sprocket123"
card.Transaction(req)
{
  "req": "hub.set",
  "mode": "continuous",
  "outbound": 30,
  "inbound": 60,
  "duration": 240,
  "sync": true
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "continuous");
JAddNumberToObject(req, "outbound", 30);
JAddNumberToObject(req, "inbound", 60);
JAddNumberToObject(req, "duration", 240);
JAddBoolToObject(req, "sync", true);

NoteRequest(req);
req = {"req": "hub.set"}
req["mode"] = "continuous"
req["outbound"] = 30
req["inbound"] = 60
req["duration"] = 240
req["sync"] = True
card.Transaction(req)
{
  "req": "hub.set",
  "mode": "periodic",
  "outbound": 90,
  "inbound": 240
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "periodic");
JAddNumberToObject(req, "outbound", 90);
JAddNumberToObject(req, "inbound", 240);

NoteRequest(req);
req = {"req": "hub.set"}
req["mode"] = "periodic"
req["outbound"] = 90
req["inbound"] = 240
card.Transaction(req)
{
  "req": "hub.set",
  "host": "a.mynotehub.net"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "host", "a.mynotehub.net");

NoteRequest(req);
req = {"req": "hub.set"}
req["host"] = "a.mynotehub.net"
card.Transaction(req)
{
  "req": "hub.set",
  "mode": "periodic",
  "voutbound": "usb:30;high:60;normal:90;low:120;dead:0",
  "vinbound": "usb:60;high:120;normal:240;low:480;dead:0"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "periodic");
JAddStringToObject(req, "voutbound", "usb:30;high:60;normal:90;low:120;dead:0");
JAddStringToObject(req, "vinbound", "usb:60;high:120;normal:240;low:480;dead:0");

NoteRequest(req);
req = {"req": "hub.set"}
req["mode"] = "periodic"
req["voutbound"] = "usb:30;high:60;normal:90;low:120;dead:0"
req["vinbound"] = "usb:60;high:120;normal:240;low:480;dead:0"
card.Transaction(req)
Response Members
None: an empty object {} means success.
More information:

hub.signal This request is available on all versions of Notecard Cellular.CellThis request is available on Notecard Cell+WiFi.Cell+WiFiThis request is available on all versions of Notecard WiFi.WiFi

Receive a signal (a near-real-time note) from Notehub.

This request checks for an inbound signal from Notehub. If it finds a signal, this request returns the signal's body and deletes the signal. If there are multiple signals to receive, this request reads and deletes signals in FIFO (first in first out) order.

warning

A Notecard must be in continuous mode and have its sync argument set to true to receive signals.

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

See our guide to Using Inbound Signals for more information on how to set up a host microcontroller or single-board computer to receive inbound signals.

Arguments

seconds (Added in v.5.1.1)

integer (optional)

The number of seconds to wait before timing out the request.

{ "req": "hub.signal" }
J *req = NoteNewRequest("hub.signal");

NoteRequest(req);
req = {"req": "hub.signal"}
rsp = card.Transaction(req)
Response Members

body

JSON object

The JSON body of a received signal.

connected

boolean

true if the Notecard is connected to Notehub.

signals

integer

The number of queued signals remaining.

Example Response
{
  "body": {
    "example-key": "example-value"
  },
  "connected": true
}
More information:

hub.status This request is available on all versions of Notecard Cellular.CellThis request is available on Notecard Cell+WiFi.Cell+WiFiThis request is available on Notecard LoRa.LoRaThis request is available on all versions of Notecard WiFi.WiFi

Displays the current status of the Notecard's connection to Notehub.

Arguments
None
{"req": "hub.status"}
J *req = NoteNewRequest("hub.status");

NoteRequest(req);
req = {"req": "hub.status"}
rsp = card.Transaction(req)
Response Members

status

string

Details about the Notecard's connection status.

connected

boolean

true if the Notecard is connected to Notehub.

Example Response
{
  "status":    "connected (session open) {connected}",
  "connected": true
}

hub.sync This request is available on all versions of Notecard Cellular.CellThis request is available on Notecard Cell+WiFi.Cell+WiFiThis request is available on Notecard LoRa.LoRaThis request is available on all versions of Notecard WiFi.WiFi

Manually initiates a sync with Notehub.

Arguments

allow

boolean

Set to true to remove the Notecard from certain types of penalty boxes (the default is false).

{"req": "hub.sync"}
J *req = NoteNewRequest("hub.sync");

NoteRequest(req);
req = {"req": "hub.sync"}
card.Transaction(req)
Response Members
None: an empty object {} means success.

hub.sync.status This request is available on all versions of Notecard Cellular.CellThis request is available on Notecard Cell+WiFi.Cell+WiFiThis request is available on Notecard LoRa.LoRaThis request is available on all versions of Notecard WiFi.WiFi

Check on the status of a recently triggered or previous sync.

Arguments

sync

boolean (optional)

true if this request should auto-initiate a sync pending outbound data.

{
  "req": "hub.sync.status",
  "sync": true
}
J *req = NoteNewRequest("hub.sync.status");
JAddBoolToObject(req, "sync", true);

NoteRequest(req);
req = {"req": "hub.sync.status"}
req["sync"] = True
rsp = card.Transaction(req)
Response Members

status

string

The status of the current or previous sync.

time

UNIX Epoch time

Time of the last sync completion. Will only populate if the Notecard has completed a sync to Notehub to obtain the time.

alert

boolean

true if an error occurred during the most recent sync.

sync

boolean

true if the notecard has unsynchronized notes, or requires a sync to set its internal clock.

completed

integer

Number of seconds since the last sync completion.

requested

integer

Number of seconds since the last explicit sync request.

seconds (Added in LTS v4.1.1)

integer

If the Notecard is in a Penalty Box, the number of seconds until the penalty condition ends.

Example Response
{
  "status": "completed {sync-end}",
  "time": 1598367163,
  "alert": true,
  "sync": true,
  "completed": 1648
}
More information: