The hub
set of requests provide a variety of ways for a developer to configure
and monitor the connection between the Notecard and Notehub.
Send a signal from Notehub to a Notecard.
A Notecard can receive a signal with the hub.signal
request.
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.
Response Members
connected
boolean
true
if the Notecard is connected to Notehub.
{ "connected": true }
Retrieves the current Notehub configuration for the Notecard.
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.
{ "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" }
Add a "device health" log message to send to Notehub on the next sync.
text
string
alert
boolean
true
if the message is urgent.
sync
boolean
true
if a sync should be initiated immediately.
Response Members
{}
means success.The hub.set
request is the primary method for controlling the Notecard's
Notehub connection and sync behavior.
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)
true
to align syncs onto a regular time-periodic cycle.
sync
boolean (optional)
If in continuous
mode, automatically and immediately sync each time an
inbound Notefile change is detected on Notehub.
unsecure
boolean (optional)
If in continous
mode, connect to Notehub without establishing a TLS
connection (default is false
). Learn more in
Advanced Notecard Configuration.
Response Members
{}
means success.Send and receive signals (near-real-time notes) between a Notecard and Notehub.
Invoking this request with a body
argument sends a signal to Notehub in a _signal.qo
Notefile. Signals are sent immediately, and are not subject to a Notecard’s configured
outbound
interval.
If you invoke this request without a body
argument, you check for inbound signals
from Notehub. If the request finds a signal, it returns the signal’s body and deletes
the signal. If there are multiple signals to receive, this request reads and deletes the
signals in FIFO (first in first out) order.
A Notecard must be in continuous mode to send signals. To receive signals,
the Notecard must additionally have its sync
argument set to true
.
{ "req": "hub.set", "mode": "continuous", "sync": true }
If you’re using the Notecard with a host microcontroller or single-board computer,
you can look for signals by polling hub.signal
, or by having the Notecard perform
an interrupt when it receives an inbound signal—which you can configure with the
card.attn
request.
body
JSON object (optional)
A JSON object to send.
live
boolean (optional, default is false
)
When in live
mode, the Notecard does not store the signal in a Notefile to
reduce latency, and to send signals on the network as fast as possible. Live signals
do not appear as _signal.qo
events in Notehub, but are still routed.
Response Members
body
JSON object
The JSON body of a received signal.
connected
boolean
true
if the Notecard is connected to Notehub.
{ "body": { "example-key": "example-value" }, "connected": true }
Displays the current status of the Notecard's connection to Notehub.
Response Members
status
string
Details about the Notecard's connection status.
connected
boolean
true
if the Notecard is connected to Notehub.
{ "status": "connected (session open) {connected}", "connected": true }
Manually initiates a sync with Notehub.
allow
boolean
Set to true
to remove the Notecard from a network registration
penalty box
(the default is false
).
Response Members
{}
means success.Check on the status of a recently triggered or previous sync.
sync
boolean (optional)
true
if this request should auto-initiate a sync pending outbound data.
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.
{ "status": "completed {sync-end}", "time": 1598367163, "alert": true, "sync": true, "completed": 1648 }