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.

Notecard Firmware Version:

hub.get CellCell+WiFiLoRaWiFi

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)

Retrieve the current Notehub configuration for the Notecard.

Response Members

device

string

The DeviceUID for the Notecard.

host

string

The URL of the Notehub host.

inbound

integer

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

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.

product

string

The ProductUID to which the Notecard is registered.

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.

vinbound

string

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

voutbound

string

If outbound is overridden with a voltage-variable value.

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 CellCell+WiFiWiFi

Add a "device health" log message to send to Notehub on the next sync via the _health_host.qo Notefile.

Arguments

alert

boolean (optional)

true if the message is urgent. This doesn't change any functionality, but rather alert is provided as a convenient flag to use in your program logic.

sync

boolean (optional)

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

text

string (optional)

Text to log.

{
  "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
rsp = card.Transaction(req)

Log an urgent health alert and sync immediately.

{
  "req": "hub.log",
  "text": "System status: normal"
}
J *req = NoteNewRequest("hub.log");
JAddStringToObject(req, "text", "System status: normal");

NoteRequest(req);
req = {"req": "hub.log"}
req["text"] = "System status: normal"
rsp = card.Transaction(req)

Log a simple text message.

Response Members
None: an empty object {} means success.

hub.set CellCell+WiFiLoRaWiFi

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

Arguments

align

boolean (optional)

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

details

string or object (optional)

LoRa

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.

duration

integer (optional)

When in continuous mode, the amount of time, in minutes, of each session (the minimum allowed value is 15). 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.

host

string (optional)

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

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.

A value of 0 means that the Notecard will never sync inbound data unless explicitly told to do so (e.g. using hub.sync).

mode

string (optional)

The Notecard's synchronization mode.

"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. OTA DFU updates are not available when using this mode.

"off": Disables automatic and manual syncs. hub.sync requests will be ignored in this mode. OTA DFU updates are not available when using this mode.

"dfu": Puts the Notecard in DFU mode for IAP host MCU firmware updates. This mode is effectively the same as off in terms of the Notecard's network and Notehub connections.

off

boolean (optional)

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

on

boolean (optional)

If in periodic mode, used to temporarily switch the Notecard to continuous mode to perform a web transaction.\n\nIgnored if the Notecard is already in continuous mode or if the Notecard is NOT performing a web transaction.

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.

A value of 0 means that the Notecard will never sync outbound data unless explicitly told to do so (e.g. using hub.sync).

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.

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.

sn

string (optional)

The end product's serial number.

sync

boolean (optional)

Cell Cell+WiFi WiFi

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

NOTE: The sync argument is not supported when a Notecard is in NTN mode.

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.

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.

version

string or object (optional)

The version of your host firmware. The value provided will appear on your device in Notehub under the "Host Firmware" tab.

You may pass a simple version number string (e.g. "1.0.0.0"), or an object with detailed information about the firmware image. If you provide an object it must take the following form.

{"org":"my-organization","product":"My Product","description":"A description of the image","version":"1.2.4","built":"Jan 01 2025 01:02:03","ver_major":1,"ver_minor":2,"ver_patch":4,"ver_build": 5,"builder":"The Builder"}

If your project uses Notecard Outboard Firmware Update, you can alternatively use the dfu.status request to set your host firmware version.

vinbound

string (optional)

Cell Cell+WiFi WiFi

Overrides inbound with a voltage-variable value. Use "-" to clear this value.

NOTE: Setting voltage-variable values is not supported on Notecard XP.

voutbound

string (optional)

Cell Cell+WiFi WiFi

Overrides outbound with a voltage-variable value. Use "-" to clear this value.

NOTE: Setting voltage-variable values is not supported on Notecard XP.

{
  "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"
rsp = card.Transaction(req)

Change device ProductUID and serial number.

{
  "req": "hub.set",
  "mode": "periodic",
  "product": "com.your-company.your-name:your_product",
  "outbound": 90,
  "inbound": 240
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "periodic");
JAddStringToObject(req, "product", "com.your-company.your-name:your_product");
JAddNumberToObject(req, "outbound", 90);
JAddNumberToObject(req, "inbound", 240);

NoteRequest(req);
req = {"req": "hub.set"}
req["mode"] = "periodic"
req["product"] = "com.your-company.your-name:your_product"
req["outbound"] = 90
req["inbound"] = 240
rsp = card.Transaction(req)

Configure periodic mode with outbound and inbound sync timing.

{
  "req": "hub.set",
  "mode": "continuous",
  "product": "com.your-company.your-name:your_product",
  "outbound": 30,
  "inbound": 60,
  "duration": 240,
  "sync": true
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "continuous");
JAddStringToObject(req, "product", "com.your-company.your-name:your_product");
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["product"] = "com.your-company.your-name:your_product"
req["outbound"] = 30
req["inbound"] = 60
req["duration"] = 240
req["sync"] = True
rsp = card.Transaction(req)

Configure continuous mode with session duration and automatic sync.

{
  "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"
rsp = card.Transaction(req)

Configure voltage-dependent synchronization periods.

{
  "req": "hub.set",
  "version": "1.2.3"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "version", "1.2.3");

NoteRequest(req);
req = {"req": "hub.set"}
req["version"] = "1.2.3"
rsp = card.Transaction(req)

Set host firmware version using a simple string.

{
  "req": "hub.set",
  "version": {
    "org": "my-organization",
    "product": "My Product",
    "description": "A description of the image",
    "version": "1.2.4",
    "built": "Jan 01 2025 01:02:03",
    "ver_major": 1,
    "ver_minor": 2,
    "ver_patch": 4,
    "ver_build": 5,
    "builder": "The Builder"
  }
}
J *req = NoteNewRequest("hub.set");

NoteRequest(req);
req = {"req": "hub.set"}
rsp = card.Transaction(req)

Set host firmware version using detailed object information.

{
  "req": "hub.set",
  "details": {
    "deveui": "0080E11500088B37",
    "appeui": "6E6F746563617264",
    "appkey": "00088B3700112233445566778899AABB"
  }
}
J *req = NoteNewRequest("hub.set");

NoteRequest(req);
req = {"req": "hub.set"}
rsp = card.Transaction(req)

Set alternative LoRaWAN server details for Notecard LoRa.

{
  "req": "hub.set",
  "details": "-"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "details", "-");

NoteRequest(req);
req = {"req": "hub.set"}
req["details"] = "-"
rsp = card.Transaction(req)

Reset LoRaWAN details to default values using dash.

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

NoteRequest(req);
req = {"req": "hub.set"}
req["umin"] = True
rsp = card.Transaction(req)

Configure USB/line power variable sync to minimum mode.

{
  "req": "hub.set",
  "on": true,
  "seconds": 300
}
J *req = NoteNewRequest("hub.set");
JAddBoolToObject(req, "on", true);
JAddNumberToObject(req, "seconds", 300);

NoteRequest(req);
req = {"req": "hub.set"}
req["on"] = True
req["seconds"] = 300
rsp = card.Transaction(req)

Temporarily switch to continuous mode for web transactions.

Response Members
None: an empty object {} 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.

warning

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

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

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)

Check for an inbound signal from Notehub.

{
  "req": "hub.signal",
  "seconds": 30
}
J *req = NoteNewRequest("hub.signal");
JAddNumberToObject(req, "seconds", 30);

NoteRequest(req);
req = {"req": "hub.signal"}
req["seconds"] = 30
rsp = card.Transaction(req)

Check for an inbound signal with custom timeout.

Response Members

body

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
}

Response when a signal is received from Notehub.

{
  "connected": true,
  "signals": 0
}

Response when no signals are available.

{
  "body": {
    "data": "signal-data"
  },
  "connected": true,
  "signals": 3
}

Response with remaining queued signals.

hub.status CellCell+WiFiLoRaWiFi

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)

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

Response Members

connected

boolean

true if the Notecard is connected to Notehub.

status

string

Details about the Notecard's transport (e.g. cellular, Wi-Fi, LoRa) connection status.

Use connected to check if the Notecard is connected to Notehub.

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

Response when Notecard is connected to Notehub.

{
  "status": "disconnected",
  "connected": false
}

Response when Notecard is not connected to Notehub.

hub.sync CellCell+WiFiLoRaWiFi

Manually initiates a sync with Notehub.

Arguments

allow

boolean (optional)

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

in

boolean (optional)

Set to true to only sync pending inbound Notefiles. Required when using NTN mode with Starnote to check for inbound Notefiles.

out

boolean (optional)

Set to true to only sync pending outbound Notefiles.

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

NoteRequest(req);
req = {"req": "hub.sync"}
rsp = card.Transaction(req)

Initiate a manual sync with Notehub.

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

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

Sync and remove Notecard from penalty boxes.

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

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

Sync only pending outbound Notefiles.

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

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

Sync only pending inbound Notefiles (required for NTN mode).

Response Members
None: an empty object {} means success.

hub.sync.status CellCell+WiFiLoRaWiFi

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"
}
J *req = NoteNewRequest("hub.sync.status");

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

Check the status of a recent or previous sync.

{
  "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)

Check sync status and auto-initiate sync if there is pending outbound data.

Response Members

alert

boolean

true if an error occurred during the most recent sync.

completed

integer

Number of seconds since the last sync completion.

mode

string

The current state of the wireless connectivity module in use.

requested

integer

Number of seconds since the last explicit sync request.

scan

boolean

Returns true if triangulation data was sent to Notehub in the most recent sync.

seconds

integer

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

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}).

sync

boolean

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

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.

Example Response
{
  "status": "completed {sync-end}",
  "mode": "{modem-off}",
  "time": 1598367163,
  "alert": true,
  "sync": true,
  "completed": 1648
}

Response showing sync status with completion time and alert.

{
  "status": "waiting {network-down}",
  "mode": "{modem-off}",
  "sync": false,
  "seconds": 300
}

Response when Notecard is in penalty box.

{
  "status": "completed {sync-end}",
  "mode": "{modem-off}",
  "time": 1598367163,
  "sync": false,
  "completed": 45,
  "scan": true
}

Response showing recent sync with scan data.