Rate this page Â
- ★★
- ★★
- ★★
- ★★
- ★★
Can we improve this page? Send us feedbackRate this page
- ★★
- ★★
- ★★
- ★★
- ★★
The hub set of requests provide a variety of ways for a developer to configure
and monitor the connection between the Notecard and Notehub.
warningThe hub.device.signal API has been deprecated in favor of the
Send Device Signal Notehub API.
Send a signal from Notehub to a Notecard.
noteA 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.
It can also accept a serial number by prefixing the serial number with sn:. Please note that the serial number must be URL encoded.
Response Members
connected
boolean
true if the Notecard is connected to Notehub.
{ "connected": true }
Retrieves the current Notehub configuration for the Notecard.
None
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. Setting true will also
remove the Notecard from certain types of
penalty boxes.
Response Members
None: an empty object
{} 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)
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)
boolean (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.
Response Members
None: an empty object
{} means success.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.
warningA Notecard must be in continuous mode and have its sync argument set to
true to receive signals.
{ "req": "hub.set", "mode": "continuous", "sync": true }
noteSee 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.
None
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.
{ "body": { "example-key": "example-value" }, "connected": true }
Displays the current status of the Notecard's connection to Notehub.
None
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 certain types of
penalty boxes
(the default is false).
Response Members
None: an empty object
{} 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 }