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.get CellCell+WiFiLoRaWiFi
Retrieves the current Notehub configuration for the Notecard.
{
"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.
{
"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 CellCell+WiFiWiFi
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.
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
{}
means success.hub.set CellCell+WiFiLoRaWiFi
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 (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. Explicit
syncs (e.g. using hub.sync
) do not affect this cadence.
When in periodic
or continuous
mode this argument is required, otherwise the
Notecard will function as if it is in minimum
mode as it pertains to syncing
behavior.
Use -1
to
reset
the value back to its default of 0
.
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. Use "-"
to clear this value.
NOTE: Setting voltage-variable values is not supported on the Notecard XP.
inbound
integer (optional)
The max wait time, in minutes, to sync inbound data from Notehub. Explicit syncs
(e.g. using hub.sync
) do not affect this cadence.
When in periodic
or continuous
mode this argument is required, otherwise the
Notecard will function as if it is in minimum
mode as it pertains to syncing
behavior.
Use -1
to
reset
the value back to its default of 0
.
vinbound
string (optional)
Overrides inbound
with a voltage-variable value. Use "-"
to clear this
value.
NOTE: Setting voltage-variable values is not supported on the Notecard XP.
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
boolean (optional)
If in periodic
mode, used to temporarily switch the Notecard to continuous
mode to perform a
web transaction.
Ignored if the Notecard is already in continuous
mode or if the Notecard is
NOT performing a web transaction.
seconds
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
boolean (optional)
Set to true
to manually instruct the Notecard to resume periodic mode after
a web transaction has completed.
uperiodic
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
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
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.
details
JSON object (optional)
When using Notecard LoRa you can use this argument to provide information about an
alternative LoRaWAN server or service you would like the Notecard to use. The argument
you provide must be a JSON object with three keys, "deveui"
, "appeui"
, and "appkey"
,
all of which are hexadecimal strings with no leading 0x. For example:
{"deveui":"0080E11500088B37","appeui":"6E6F746563617264","appkey":"00088B37"}
The LoRaWAN details you send to a Notecard become part of its permanent configuration,
and survive factory resets. You can reset a Notecard's LoRaWAN details to its default
values by providing a "-"
for the details
argument.
{
"req": "hub.set",
"product": "com.your-company.your-name:your_product",
"sn": "my-device"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "product", "com.your-company.your-name:your_product");
JAddStringToObject(req, "sn", "my-device");
NoteRequest(req);
req = {"req": "hub.set"}
req["product"] = "com.your-company.your-name:your_product"
req["sn"] = "my-device"
card.Transaction(req)
Change your device's ProductUID to "com.your-company.your-name:your_product"
and serial number to "my-device"
.
{
"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)
Place your device in periodic mode, performing outbound synchronizations with Notehub every 90 minutes and inbound synchronizations every 240 minutes.
{
"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)
Place your device in continuous mode, performing outbound synchronizations with
Notehub every 30 minutes and inbound synchronizations every 60 minutes.
Setting the duration
to 240
tells the Notecard to begin a new session every
240 minutes, and setting sync
to true
tells the Notecard to automatically and
immediately sync each time an inbound change is detected on Notehub.
{
"req": "hub.set",
"mode": "minimum"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "minimum");
NoteRequest(req);
req = {"req": "hub.set"}
req["mode"] = "minimum"
card.Transaction(req)
Place your device in minimum mode. In minimum mode, a Notecard only performs
synchronizations when it receives an explicit hub.sync
request.
{
"req": "hub.set",
"mode": "off"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "off");
NoteRequest(req);
req = {"req": "hub.set"}
req["mode"] = "off"
card.Transaction(req)
Place your device in "off" mode. In off mode, all network communication on the Notecard is disabled.
{
"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)
Configure the Notecard to use an alternative Notehub service.
{
"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)
Using voutbound
and vinbound
allows you to define synchronization
periods that are dependent on the voltage of the device. This is most commonly
used to synchronize more frequently when a device is on USB power, and less
frequently when a device is low on battery. Learn more in
Voltage-Variable Sync Behavior.
Response Members
{}
means success.hub.signal CellCell+WiFiWiFi
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.
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
}
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.
seconds
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.
{
"body": {
"example-key": "example-value"
},
"connected": true
}
hub.status CellCell+WiFiLoRaWiFi
Displays the current status of the Notecard's connection to Notehub.
{"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 transport (e.g. cellular, Wi-Fi, LoRa) connection status.
Use connected
(below) to check if the Notecard is connected to
Notehub.
connected
boolean
true
if the Notecard is connected to Notehub.
{
"status": "connected (session open) {connected}",
"connected": true
}
hub.sync CellCell+WiFiLoRaWiFi
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
).
out
boolean
Set to true
to only sync pending outbound Notefiles.
in
boolean
Set to true
to only sync pending inbound Notefiles. Required when using
NTN mode with Starnote to check for inbound Notefiles.
{"req": "hub.sync"}
J *req = NoteNewRequest("hub.sync");
NoteRequest(req);
req = {"req": "hub.sync"}
card.Transaction(req)
Response Members
{}
means success.hub.sync.status CellCell+WiFiLoRaWiFi
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.
{
"req": "hub.sync.status"
}
J *req = NoteNewRequest("hub.sync.status");
NoteRequest(req);
req = {"req": "hub.sync.status"}
rsp = card.Transaction(req)
Response Members
status
string
The status of the current or previous sync. Refer to
this listing
for the meaning of the various status codes returned (e.g. {sync-end}
).
mode
string
The current state of the wireless connectivity module in use.
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
integer
If the Notecard is in a Penalty Box, the number of seconds until the penalty condition ends.
scan
boolean
Returns true
if triangulation data was sent to Notehub in the most recent
sync.
{
"status": "completed {sync-end}",
"mode": "{modem-off}",
"time": 1598367163,
"alert": true,
"sync": true,
"completed": 1648
}