Generated from notecard-schema version 0.1.1 (API Version: 9.1.1)

API Reference

The Notecard accepts requests in JSON format. Each request object must contain a req or cmd field specifying the request type. E.g. {"req": "card.status"} or {"cmd": "card.status"}

Warning

If you are looking for the Notecard API Reference, please visit blues.dev. This site intended for LLM agents and may lack complete documentation.

card.attn

Version Information

Schema Version: 0.1.2 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Configure hardware notification from the Notecard to MCU host.

NOTE: Requires a connection between the Notecard ATTN pin and a GPIO pin on the host MCU.

Parameters:

Parameter Type Description Default
files array A list of Notefiles to watch for file-based interrupts. -
mode string A comma-separated list of one or more of the following keywords. Some keywords are only supported on certain types of Notecards.

Allowed Values:
  • "": Fetches currently pending events in the "files" collection. (CELL, CELL+WIFI, WIFI)
  • "arm": Clear "files" events and cause the ATTN pin to go LOW. After an event occurs or "seconds" has elapsed, the ATTN pin will then go HIGH (a.k.a. "fires"). If "seconds" is 0, no timeout will be scheduled. If ATTN is armed, calling arm again will disarm (briefly pulling ATTN HIGH), then arm (non-idempotent). (CELL, CELL+WIFI, LORA, WIFI)
  • "auxgpio": When armed, causes ATTN to fire if an AUX GPIO input changes. Disable by using -auxgpio. (CELL, CELL+WIFI, LORA, WIFI)
  • "connected": When armed, will cause ATTN to fire whenever the module connects to cellular. Disable with -connected. (CELL, CELL+WIFI, WIFI)
  • "disarm": Causes ATTN pin to go HIGH if it had been LOW. Passing both "disarm" and "-all" clears all ATTN monitors currently set. (CELL, CELL+WIFI, LORA, WIFI)
  • "env": When armed, causes ATTN to fire if an environment variable changes on the Notecard. Disable by using -env. (CELL, CELL+WIFI, LORA, WIFI)
  • "files": When armed, will cause ATTN to fire if any of the "files" are modified. Disable by using -files. (CELL, CELL+WIFI, LORA, WIFI)
  • "location": When armed, will cause ATTN to fire whenever the Notecard GPS module makes a position fix. Disable by using -location. (CELL, CELL+WIFI, WIFI)
  • "motion": When armed, will cause ATTN to fire whenever the accelerometer detects module motion. Disable with -motion. (CELL, CELL+WIFI, WIFI)
  • "motionchange": When armed, will cause ATTN to fire whenever the card.motion.mode changes from "moving" to "stopped" (or vice versa). Learn how to configure this feature in this guide. (CELL, CELL+WIFI, WIFI)
  • "rearm": Will arm ATTN if not already armed. Otherwise, resets the values of mode, files, and seconds specified in the initial arm or rearm request (idempotent). (CELL, CELL+WIFI, WIFI)
  • "signal": When armed, will cause ATTN to fire whenever the Notecard receives a signal. (CELL, CELL+WIFI, WIFI)
  • "sleep": Instruct the Notecard to pull the ATTN pin low for a period of time, and optionally keep a payload in memory. Can be used by the host to sleep the host MCU. (CELL, CELL+WIFI, WIFI)
  • "usb": When armed, will enable USB power events firing the ATTN pin. Disable with -usb. (CELL, CELL+WIFI, LORA, WIFI)
  • "watchdog": Not an "arm" mode, rather will cause the ATTN pin to go from HIGH to LOW, then HIGH if the notecard fails to receive any JSON requests for "seconds." In this mode, "seconds" must be >= 60. (CELL, CELL+WIFI, WIFI)
  • "wireless": Instruct the Notecard to fire the ATTN pin whenever the card.wireless status changes. (CELL, CELL+WIFI, WIFI)
 -
off boolean When true, completely disables ATTN processing and sets the pin OFF. This setting is retained across device restarts. -
on boolean When true, enables ATTN processing. This setting is retained across device restarts. -
payload string When using sleep mode, a payload of data from the host that the Notecard should hold in memory until retrieved by the host. -
seconds integer To set an ATTN timeout when arming, or when using sleep. NOTE: When the Notecard is in continuous mode, the seconds timeout is serviced by a routine that wakes every 15 seconds. You can predict when the device will wake, by rounding up to the nearest 15 second interval._ -
start boolean When using sleep mode and the host has reawakened, request the Notecard to return the stored payload. -
verify boolean When true, returns the current attention mode configuration, if any. -

Examples:

Configure the Notecard to perform an interrupt on a successful connection to Notehub.

{
  "req": "card.attn",
  "mode": "arm,connected"
}

Configure the Notecard to perform an interrupt on the data.qi and my-settings.db Notefiles.

{
  "req": "card.attn",
  "mode": "arm,files",
  "files": [
    "data.qi",
    "my-settings.db"
  ]
}

Configure the Notecard to perform an interrupt when the Notecard makes a position fix.

{
  "req": "card.attn",
  "mode": "arm,location"
}

Configure the Notecard to perform an interrupt when the Notecard detects motion.

{
  "req": "card.attn",
  "mode": "arm,motion"
}

Configure the Notecard to perform an interrupt when the Notecard receives a signal.

{
  "req": "card.attn",
  "mode": "arm,signal"
}

Configure the Notecard to function as a watchdog timer with a 60 second timeout.

{
  "req": "card.attn",
  "mode": "watchdog",
  "seconds": 60
}

Configure the Notecard to instruct the host MCU to sleep for a period of time.

{
  "req": "card.attn",
  "mode": "sleep",
  "seconds": 3600,
  "payload": "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ=="
}

Retrieve a payload from the Notecard after sleep.

{
  "req": "card.attn",
  "start": true
}

Disarm all interrupts.

{
  "req": "card.attn",
  "mode": "disarm,-all"
}

Response

No description available.

Parameters:

Parameter Type Description Default
set boolean Reflects the state of the attention pin. The set field is true when the attention pin is HIGH, otherwise the set field will not be present when the attention pin is LOW. -
files array A list of files changed since file attention mode was set. In addition, this field will include keywords to signify the occurrence of other attention mode triggers: -
payload string When using sleep mode with a payload, the payload provided by the host to the Notecard. -
time integer When using sleep mode with a payload, the time (UNIX Epoch time) that the payload was stored by the Notecard. -
off boolean This field is present and set to true if ATTN processing has been disabled with the off argument. -

Examples:

Example Response

{
  "files": [
    "data.qi",
    "modified"
  ],
  "set": true
}

card.aux

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Configure various uses of the general-purpose I/O (GPIO) pins AUX1-AUX4 on the Notecard edge connector for tracking applications and simple GPIO sensing and counting tasks.

Parameters:

Parameter Type Description Default
mode string The AUX mode. Must be one of the following keywords. Some keywords are only supported on certain types of Notecards.

Allowed Values:
  • "dfu": Enable the Notecard's AUX1 pin for Outboard Firmware Updates. When enabled, AUX1 is active LOW when a DFU is in progress, and HIGH otherwise. (CELL, CELL+WIFI, WIFI)
  • "gpio": Configure the Notecard for GPIO mode with AUX1 OFF, AUX2 as an output LOW, AUX3 as an output HIGH, and AUX4 as an input. (CELL, CELL+WIFI, LORA, WIFI)
  • "led": When wiring LEDs to the Notecard's AUX pins (as is done when using monitor mode), use this mode along with the card.led API to manually enable/disable individual red, green, and/or yellow LEDs. (CELL, CELL+WIFI, WIFI)
  • "monitor": If you plan to place your Notecard in an enclosure, monitor mode can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity. (CELL, CELL+WIFI, WIFI)
  • "motion": Supplement autonomous tracking with digital inputs and a status output. (CELL, CELL+WIFI, WIFI)
  • "neo": When wiring a NeoPixel or NeoPixel strip to the Notecard's AUX2 pin (as is done when using neo-monitor mode), use this mode along with the card.led API to manually enable/disable a single NeoPixel. (CELL, CELL+WIFI, WIFI)
  • "neo-monitor": Similar to monitor mode, neo-monitor mode supports NeoPixel LEDs that can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity. (CELL, CELL+WIFI, LORA, WIFI)
  • "off": Disable AUX mode. (CELL, CELL+WIFI, LORA, WIFI)
  • "track": Enhance Notes in the _track.qo Notefile with temperature, pressure, and humidity readings from a connected BME280 sensor. (CELL, CELL+WIFI, WIFI)
  • "track-monitor": Combines the functionality of the track and monitor AUX modes. (CELL, CELL+WIFI, WIFI)
  • "track-neo-monitor": Combines track and monitor modes while also supporting NeoPixel LEDs that allow for monitoring Notecard activity. (CELL, CELL+WIFI, WIFI)
  • "-": Resets the AUX mode to its default value (off). (CELL, CELL+WIFI, LORA, WIFI)
 -
usage array An ordered list of pin modes for each AUX pin when in GPIO mode.

Allowed Values:
  • "": to leave the pin unchanged. (CELL, CELL+WIFI, LORA, WIFI)
  • "off": to disable the pin. (CELL, CELL+WIFI, LORA, WIFI)
  • "high": to set the pin as a HIGH output. (CELL, CELL+WIFI, LORA, WIFI)
  • "low": to set the pin as a LOW output. (CELL, CELL+WIFI, LORA, WIFI)
  • "input": to set the pin as an input. (CELL, CELL+WIFI, LORA, WIFI)
  • "input-pulldown": to set the pin as a pull-down input. (CELL, CELL+WIFI, LORA, WIFI)
  • "input-pullup": to set the pin as a pull-up input. (CELL, CELL+WIFI, LORA, WIFI)
  • "count": to set the pin as an input (interrupt) that increments a counter for each rising edge pulse on the pin. It is up to the device's designer to make sure that the signal is either HIGH or LOW at any time, and is never left floating. (CELL, CELL+WIFI, WIFI)
  • "count-pulldown": Same as count usage, but a pull-down resistor internal to the Notecard will automatically keep the pin from floating. (CELL, CELL+WIFI, WIFI)
  • "count-pullup": Same as count usage, but a pull-up resistor internal to the Notecard will automatically keep the pin from floating and falling edges of pulses are counted. (CELL, CELL+WIFI, WIFI)
 -
seconds integer When in gpio mode, if an AUX pin is configured as a count type, the count of rising edges can be broken into samples of this duration. Passing 0 or omitting this field will total into a single sample. -
max integer When in gpio mode, if an AUX pin is configured as a count type, the maximum number of samples of duration seconds, after which all subsequent counts are added to the final sample. Passing 0 or omitting this value will provide a single incrementing count of rising edges on the pin. -
start boolean When in gpio mode, if an AUX pin is configured as a count type, set to true to reset counters and start incrementing. -
gps boolean If true, along with "mode":"track" the Notecard supports the use of an external GPS module. This argument is deprecated. Use the card.aux.serial request with a mode of "gps" instead. -
rate integer The AUX UART baud rate for debug communication over the AUXRX and AUXTX pins.. Allowed values: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600 115200
sync boolean If true, for pins set as input by usage, the Notecard will autonomously report any state changes as new notes in file. For pins used as counter, the Notecard will use an interrupt to count pulses and will report the total in a new note in file unless it has been noted in the previous second. -
file string The name of the Notefile used to report state changes when used in conjunction with "sync": true. Default Notefile name is _button.qo. -
connected boolean If true, defers the sync of the state change Notefile to the next sync as configured by the hub.set request. -
limit boolean If true, along with "mode":"track" and gps:true the Notecard will disable concurrent modem use during GPS tracking. -
sensitivity integer When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this controls the brightness of NeoPixel lights, where 100 is the maximum brightness and 1 is the minimum. -
ms integer When in gpio mode, this argument configures a debouncing interval. With a debouncing interval in place, the Notecard excludes all transitions with a shorter duration than the provided debounce time, in milliseconds. This interval only applies to GPIOs configured with a usage of count, count-pulldown, or count-pullup. -
count integer When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this controls the number of NeoPixels to use in a strip. Possible values are 1, 2, or 5.. Allowed values: 1, 2, 5 -
offset integer When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this is the 1-based index in a strip of NeoPixels that determines which single NeoPixel the host can command. -

Note

Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's serial data interfaces.

Examples:

Configure AUX pins for GPIO usage.

{
  "req": "card.aux",
  "mode": "gpio",
  "usage": [
    "input",
    "high",
    "low",
    "count"
  ]
}

Configure AUX for NeoPixel monitoring with custom brightness and count.

{
  "req": "card.aux",
  "mode": "neo-monitor",
  "sensitivity": 50,
  "count": 5,
  "offset": 1
}

Set AUX to track mode for location tracking.

{
  "cmd": "card.aux",
  "mode": "track"
}

Turn off AUX functionality.

{
  "cmd": "card.aux",
  "mode": "off"
}

Response

No description available.

Parameters:

Parameter Type Description Default
mode string The current AUX mode, or off if not set. -
state array When in AUX gpio mode, the state of each AUX pin. -
time integer When in AUX gpio mode, and if count is enabled on an AUX pin, the time that counting started. -
seconds integer When in AUX gpio mode, and if count is enabled on an AUX pin, the number of seconds per sample. -
power boolean If true, indicates the Notecard has USB (main) power. This parameter only appears in the body of the Note in Notehub if using "sync":true. -

Examples:

Example response showing GPIO mode configuration with pin states.

{
  "mode": "gpio",
  "state": [
    {},
    {
      "low": true
    },
    {
      "high": true
    },
    {
      "count": [
        3
      ]
    }
  ],
  "time": 1592587637,
  "seconds": 2
}

card.aux.serial

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Configure various uses of the AUXTX and AUXRX pins on the Notecard's edge connector.

Parameters:

Parameter Type Description Default
mode string The AUX mode. Must be one of the following. Allowed values: req, gps, notify, notify,accel, notify,signals, notify,env, notify,dfu -

Response

No description available.

No specific parameters defined.

card.binary

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

View the status of the binary storage area of the Notecard and optionally clear any data and related card.binary variables.

Parameters:

Parameter Type Description Default
delete boolean Clear the COBS area on the Notecard and reset all related arguments previously set by a card.binary request -

Response

No description available.

Parameters:

Parameter Type Description Default
cobs integer The size of COBS-encoded data stored in the reserved area -
connected boolean Returns true if the Notecard is connected to the network -
err string If present, a string describing the error that occurred during transmission -
length integer The length of the binary data -

card.binary.get

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Returns binary data stored in the binary storage area of the Notecard. The response to this API command first returns the JSON-formatted response object, then the binary data.

Parameters:

Parameter Type Description Default
cobs integer The size of the COBS-encoded data you are expecting to be returned (in bytes) -
offset integer Used along with length, the number of bytes to offset the binary payload from 0 when retrieving binary data from the Notecard -
length integer Used along with offset, the number of bytes to retrieve from the binary storage area of the Notecard -

Response

No description available.

Parameters:

Parameter Type Description Default
status string The MD5 checksum of the data returned, after it has been decoded -
err string If present, a string describing the error that occurred during transmission -

card.binary.put

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Adds binary data to the binary storage area of the Notecard. The Notecard expects to receive binary data immediately following the usage of this API command.

Parameters:

Parameter Type Description Default
offset integer The number of bytes to offset the binary payload from 0 when appending the binary data to the binary storage area of the Notecard -
cobs integer The size of the COBS-encoded data (in bytes) -
status string The MD5 checksum of the data, before it has been encoded -

Response

No description available.

Parameters:

Parameter Type Description Default
err string If present, a string describing the error that occurred during transmission -

card.carrier

Version Information

Schema Version: 0.2.2 | API Version: 9.1.1

Request

Uses the AUX_CHARGING pin on the Notecard edge connector to notify the Notecard that the pin is connected to a Notecarrier that supports charging, using open-drain.

Once set, {"charging":true} will appear in a response if the Notecarrier is currently indicating that charging is in progress.

Parameters:

Parameter Type Description Default
mode string The AUX_CHARGING mode. Set to "charging" to tell the Notecard that AUX_CHARGING is connected to a Notecarrier that supports charging on AUX_CHARGING. Set to "-" or "off" to turn off the AUX_CHARGING detection.. Allowed values: charging, -, off -

Examples:

Set the AUX_CHARGING mode to charging

{
  "req": "card.carrier",
  "mode": "charging"
}

Response

No description available.

Parameters:

Parameter Type Description Default
mode string The current AUX_CHARGING mode, or off if not set -
charging boolean Will display true when in AUX_CHARGING charging mode -

Examples:

Get the AUX_CHARGING mode

{
  "mode": "charging",
  "charging": true
}

card.contact

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Used to set or retrieve information about the Notecard maintainer. Once set, this information is synched to Notehub.

Parameters:

Parameter Type Description Default
name string Set the name of the Notecard maintainer -
org string Set the organization name of the Notecard maintainer -
role string Set the role of the Notecard maintainer -
email string Set the email address of the Notecard maintainer -

Examples:

Set Contact Information

{
  "req": "card.contact",
  "name": "Tom Turkey",
  "org": "Blues",
  "role": "Head of Security",
  "email": "tom@blues.com"
}

Response

No description available.

Parameters:

Parameter Type Description Default
name string Name of the Notecard maintainer -
org string Organization name of the Notecard maintainer -
role string Role of the Notecard maintainer -
email string Email address of the Notecard maintainer -

Examples:

Get Contact Information

{
  "name": "Tom Turkey",
  "org": "Blues",
  "role": "Head of Security",
  "email": "tom@blues.com"
}

card.dfu

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Used to configure a Notecard for Notecard Outboard Firmware Update.

Parameters:

Parameter Type Description Default
name string One of the supported classes of host MCU. Supported MCU classes are 'esp32', 'stm32', 'stm32-bi', '-'. Allowed values: esp32, stm32, stm32-bi, - -
on boolean Set to true to enable Notecard Outboard Firmware Update -
off boolean Set to true to disable Notecard Outboard Firmware Update from occurring -
seconds integer When used with 'off':true, disable Notecard Outboard Firmware Update operations for the specified number of seconds -
stop boolean Set to true to disable the host RESET that is normally performed on the host MCU when the Notecard starts up -

Response

No description available.

No specific parameters defined.

card.illumination

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

This request returns an illumination reading (in lux) from an OPT3001 ambient light sensor connected to Notecard's I2C bus. If no OPT3001 sensor is detected, this request returns an “illumination sensor is not available” error.

Examples:

Example

{
  "req": "card.illumination"
}

Response

No description available.

Parameters:

Parameter Type Description Default
value number An illumination reading (in lux) from the attached OPT3001 sensor. -

Examples:

Example Response

{
  "value": 8806.4
}

card.io

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

Request

Can be used to override the Notecard's I2C address from its default of 0x17 and change behaviors of the onboard LED and USB port.

Parameters:

Parameter Type Description Default
i2c integer The alternate address to use for I2C communication. Pass -1 to reset to the default address -
mode string -

Allowed Values:
  • "-usb": Set to "-usb" to disable the Notecard's USB port. Re-enable the USB port with "usb" or "+usb".
  • "+busy": If set to "+busy", the Notecard's LED will be on when the Notecard is awake, and off when the Notecard goes to sleep.
  • "-busy": Resets "+busy" to its default, making the onboard LED blink only during Notecard flash memory operations.
  • "i2c-master-disable": Disables Notecard acting as an I2C master. Re-enable by using "i2c-master-enable".
 -

Examples:

Change I2C Address

{
  "req": "card.io",
  "i2c": 24
}

Keep LED On While Notecard Awake.

{
  "req": "card.io",
  "mode": "+busy"
}

Disable Notecard Acting As I2C Master.

{
  "req": "card.io",
  "mode": "i2c-master-disable"
}

Response

No description available.

No specific parameters defined.

card.led

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Used along with the card.aux API to turn connected LEDs on/off (not supported by Notecard LoRa), or to manage a single connected NeoPixel.

Parameters:

Parameter Type Description Default
mode string Used to specify the color of the LED to turn on or off. Possible values for LEDs are 'red', 'green', 'yellow'. For NeoPixels, possible values are 'red', 'green', 'blue', 'yellow', 'cyan', 'magenta', 'orange', 'white', 'gray'. Allowed values: red, green, yellow, blue, cyan, magenta, orange, white, gray -
on boolean Set to true to turn the specified LED or NeoPixel on -
off boolean Set to true to turn the specified LED or NeoPixel off -

Response

No description available.

No specific parameters defined.

card.location

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Retrieves the last known location of the Notecard and the time at which it was acquired. Use card.location.mode to configure location settings.

Response

No description available.

Parameters:

Parameter Type Description Default
status string The current status of the Notecard GPS/GNSS connection -
mode string The GPS/GNSS connection mode. Will be continuous, periodic, or off. Allowed values: continuous, periodic, off -
lat number The latitude in degrees of the last known location -
lon number The longitude in degrees of the last known location -
time integer Unix epoch time in seconds -
max integer Maximum number of seconds to wait for a GPS fix -

card.location.mode

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Sets location-related configuration settings. Retrieves the current location mode when passed with no argument.

Parameters:

Parameter Type Description Default
mode string Must be one of: empty string to retrieve the current mode, 'off' to turn location mode off, 'periodic' to sample location at a specified interval, 'continuous' to enable the Notecard's GPS/GNSS module for continuous sampling, or 'fixed' to report the location as a fixed location. Allowed values: `,off,periodic,continuous,fixed` -
seconds integer When in periodic mode, location will be sampled at this interval, if the Notecard detects motion -
vseconds string In periodic mode, overrides seconds with a voltage-variable value -
lat number Used with fixed mode to specify the latitude coordinate -
lon number Used with fixed mode to specify the longitude coordinate -
max integer Maximum number of seconds to wait for a GPS fix -

Response

No description available.

Parameters:

Parameter Type Description Default
mode string The GPS/GNSS connection mode. Will be continuous, periodic, or off. Allowed values: continuous, periodic, off, fixed -
seconds integer When in periodic mode, location will be sampled at this interval, if the Notecard detects motion -
lat number The latitude in degrees of the last known location -
lon number The longitude in degrees of the last known location -
max integer Maximum number of seconds to wait for a GPS fix -

card.location.track

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Store location data in a Notefile at the periodic interval, or using a specified heartbeat.

Parameters:

Parameter Type Description Default
start boolean Set to true to start Notefile tracking -
heartbeat boolean When start is true, set to true to enable tracking even when motion is not detected -
hours integer If heartbeat is true, add a heartbeat entry at this hourly interval. Use a negative integer to specify a heartbeat in minutes instead of hours -
sync boolean Set to true to perform an immediate sync to the Notehub each time a new Note is added -
stop boolean Set to true to stop Notefile tracking -
file string The name of the Notefile to store location data in track.qo

Response

No description available.

No specific parameters defined.

card.monitor

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

When a Notecard is in monitor mode, this API is used to configure the general-purpose AUX1-AUX4 pins to test and monitor Notecard activity.

Parameters:

Parameter Type Description Default
mode string Can be set to one of green, red or yellow to temporarily override the behavior of an AUX pin LED. See Using Monitor Mode for additional details.. Allowed values: green, red, yellow -
count integer The number of pulses to send to the overridden AUX pin LED. Set this value to 0 to return the LED to its default behavior. -
usb boolean Set to true to configure LED behavior so that it is only active when the Notecard is connected to USB power. False

Note

Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's M.2 connector.

Examples:

Example

{
  "req": "card.monitor",
  "mode": "green",
  "count": 5
}

Response

No description available.

No specific parameters defined.

card.motion

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Returns information about the Notecard accelerometer's motion and orientation. Motion tracking must be enabled first with card.motion.mode. Otherwise, this request will return {}.

Parameters:

Parameter Type Description Default
minutes integer Amount of time to sample for buckets of accelerometer-measured movement -

Response

No description available.

Parameters:

Parameter Type Description Default
count integer The number of accelerometer motion events since the last card.motion request was made -
status string The current status of the Notecard accelerometer -
alert boolean If true, the Notecard's accelerometer detected a free-fall since the last request to card.motion -
motion integer Time of the last accelerometer motion event -
seconds integer Number of seconds since the last motion event -
movements string String with motion counts in each bucket -

card.motion.mode

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Configures accelerometer motion monitoring parameters used when providing results to card.motion.

Parameters:

Parameter Type Description Default
start boolean Set to true to enable the Notecard accelerometer and start motion tracking -
stop boolean Set to true to disable the Notecard accelerometer and stop motion tracking -
seconds integer Period for each bucket of movements to be accumulated when minutes is used with card.motion -
sensitivity integer Used to set the accelerometer sample rate -

Response

No description available.

No specific parameters defined.

card.motion.sync

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Configures automatic sync triggered by Notecard movement.

Parameters:

Parameter Type Description Default
start boolean Set to true to start motion-triggered syncing -
stop boolean Set to true to stop motion-triggered syncing -
minutes integer The maximum frequency at which sync will be triggered -
count integer The number of most recent motion buckets to examine -
threshold integer The number of buckets that must indicate motion in order to trigger a sync -

Response

No description available.

No specific parameters defined.

card.motion.track

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Configures automatic capture of Notecard accelerometer motion in a Notefile.

Parameters:

Parameter Type Description Default
start boolean Set to true to start motion capture -
stop boolean Set to true to stop motion capture -
minutes integer The maximum period to capture Notes in the Notefile -
count integer The number of most recent motion buckets to examine -
threshold integer The number of buckets that must indicate motion in order to capture -
file string The Notefile to use for motion capture Notes _motion.qo
now boolean Set to true to trigger the immediate creation of a motion.qo event if the orientation of the Notecard changes -

Response

No description available.

No specific parameters defined.

card.power

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

The card.power API is used to configure a connected Mojo device or to manually request power consumption readings in firmware.

Parameters:

Parameter Type Description Default
minutes integer How often, in minutes, Notecard should log power consumption in a _log.qo Note. The default value is 720 (12 hours). 720
reset boolean Set to true to reset the power consumption counters back to 0. -

Examples:

Get Latest Power Consumption Reading

{
  "req": "card.power"
}

Set Cadence of Readings

{
  "req": "card.power",
  "minutes": 60
}

Reset Counters

{
  "cmd": "card.power",
  "reset": true
}

Response

No description available.

Parameters:

Parameter Type Description Default
temperature number The temperature from Notecard's onboard sensor in degrees centigrade, including the calibration offset. -
voltage number The current voltage. -
milliamp_hours number The cumulative number of milliamp hours (mAh) consumed. You can reset this number with this request's reset argument. -

Examples:

Example Response

{
  "temperature": 26.028314208984398,
  "voltage": 4.200970458984375,
  "milliamp_hours": 3.9566722000000007
}

card.random

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Obtain a single random 32 bit unsigned integer modulo count or count bytes of random data from the Notecard hardware random number generator.

Parameters:

Parameter Type Description Default
mode string Accepts a single value "payload" and, if specified, uses the count value to determine the number of bytes of random data to generate and return to the host. -
count integer If the mode argument is excluded from the request, the Notecard uses this as an upper-limit parameter and returns a random unsigned 32 bit integer between zero and the value provided. If "mode":"payload" is used, this argument sets the number of random bytes of data to return in a base64-encoded buffer from the Notecard. -

Examples:

Get a Random Number.

{
  "req": "card.random",
  "count": 100
}

Get a Buffer of Random Numbers

{
  "req": "card.random",
  "mode": "payload",
  "count": 100
}

Response

No description available.

Parameters:

Parameter Type Description Default
count integer A random number generated by the Notecard's onboard hardware random number generator. -
payload string If using "mode":"payload", a base64-encoded string with random values, the length of which is specified by the count argument. -

Examples:

Example Response

{
  "count": 86
}

card.restart

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Performs a firmware restart of the Notecard.

Response

No description available.

No specific parameters defined.

card.restore

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Performs a factory reset on the Notecard and restarts.

Sending this request without either of the optional arguments below will only reset the Notecard's file system, thus forcing a re-sync of all Notefiles from Notehub.

On Notecard LoRa there is no option to retain configuration settings, and providing "delete": true is required. The Notecard LoRa retains LoRaWAN configuration after factory resets.

Parameters:

Parameter Type Description Default
connected boolean Set to true to reset the Notecard on Notehub. This will delete and deprovision the Notecard from Notehub the next time the Notecard connects. This also removes any Notefile templates used by this device. Conversely, if connected is false (or omitted), the Notecard's settings and data will be restored from Notehub the next time the Notecard connects to the previously used Notehub project. -
delete boolean Set to true to reset most Notecard configuration settings. Note that this does not reset stored Wi-Fi credentials or the alternate I2C address (if previously set) so the Notecard can still contact the network after a reset. The Notecard will be unable to sync with Notehub until the ProductUID is set again. -

Response

No description available.

No specific parameters defined.

card.sleep

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

WIFI

Request

Only valid when used with Notecard WiFi v2.

Allows the ESP32-based Notecard WiFi v2 to fall back to a low current draw when idle (this behavior differs from the STM32-based Notecards that have a STOP mode where UART and I2C may still operate). Note that the Notecard WiFi v2 will not enable a "sleep" mode while plugged in via USB.

Read more in the guide on using Deep Sleep Mode on Notecard WiFi v2.

Parameters:

Parameter Type Description Default
on boolean Set to true to enable the Notecard WiFi v2 to sleep once it is idle for >= 30 seconds. -
off boolean Set to true to disable the sleep mode on the Notecard WiFi v2. -
seconds integer The number of seconds the Notecard will wait before entering sleep mode (minimum value is 30). -
mode string Set to 'accel' to wake from deep sleep on any movement detected by the onboard accelerometer. Set to '-accel' to reset to the default setting.

Allowed Values:
  • "accel": Wake from deep sleep on any movement detected by the onboard accelerometer.
  • "-accel": Reset to the default setting.
 -

Note

Only valid for Notecard WiFi v2. Sleep mode will not activate while USB-connected.

Examples:

Enable sleep mode with default settings.

{
  "req": "card.sleep",
  "on": true
}

Enable sleep mode with accelerometer wake functionality.

{
  "req": "card.sleep",
  "on": true,
  "mode": "accel"
}

Set custom wait time before entering sleep mode.

{
  "req": "card.sleep",
  "seconds": 60
}

Disable sleep mode functionality.

{
  "cmd": "card.sleep",
  "off": true
}

Response

No description available.

Parameters:

Parameter Type Description Default
on boolean true if sleep mode is enabled. -
off boolean true if sleep mode is disabled. -
seconds integer The number of seconds the Notecard will wait before entering sleep mode (only included if default settings are overridden). -
mode string Returns "accel" if the Notecard is configured to wake from deep sleep on any movement detected by the onboard accelerometer. -

Examples:

Example response showing current sleep configuration.

{
  "seconds": 10,
  "mode": "accel",
  "on": true
}

card.status

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

Request

Returns general information about the Notecard's operating status.

Examples:

Get Notecard Status

{
  "req": "card.status"
}

Response

No description available.

Parameters:

Parameter Type Description Default
status string General status information -
usb boolean true, if the Notecard is being powered by USB -
storage integer The percentage of storage in use on the Notecard -
time integer The UNIX Epoch Time of approximately when the Notecard was first powered up -
connected boolean true, if the Notecard is connected to the Notehub -
cell boolean true, if the Notecard has a cellular connection -
gps boolean true, if Notecard's GPS module is currently powered on -
wifi boolean true, if the Notecard's Wi-Fi radio is currently powered on -
sync boolean true, if the Notecard is currently syncing with the Notehub -
inbound integer The effective inbound synchronization period being used by the device -
outbound integer The effective outbound synchronization period being used by the device -

Note

See Configuring Synchronization Modes for details on how Notecard synchronization modes work regarding the inbound and outbound fields.

Examples:

Get Notecard Status Response

{
  "status": "{normal}",
  "usb": true,
  "storage": 8,
  "time": 1599684765,
  "connected": true,
  "cell": true,
  "sync": true,
  "inbound": 60,
  "outbound": 360
}

card.temp

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Get the current temperature from the Notecard's onboard calibrated temperature sensor.

Parameters:

Parameter Type Description Default
minutes integer If specified, creates a templated _temp.qo file that gathers Notecard temperature value at the specified minutes interval -
status string Overrides minutes with a voltage-variable value -
stop boolean If set to true, the Notecard will stop logging the temperature value at the interval specified with the minutes parameter -
sync boolean If set to true, the Notecard will immediately sync any pending _temp.qo Notes created with the minutes parameter -

Response

No description available.

Parameters:

Parameter Type Description Default
temperature number Temperature in degrees C -
humidity number Relative humidity percentage (when using BME280 or ENS210 sensor) -
pressure number Barometric pressure in hPa (when using BME280 or ENS210 sensor) -

card.time

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

Request

Retrieves current date and time information in UTC (UNIX timestamp). Upon power-up, the Notecard must complete a sync to Notehub in order to obtain time and location data. Before the time is obtained, this request will return {"zone":"UTC,Unknown"}.

Examples:

Gets current date and time information in UTC (UNIX timestamp).

{
  "req": "card.time"
}

Response

No description available.

Parameters:

Parameter Type Description Default
time integer The current time in UTC (UNIX timestamp). Will only populate if the Notecard has completed a sync to Notehub to obtain the time. -
area string The geographic area of the Notecard, if the cell tower is recognized -
zone string The time zone of the Notecard, if the cell tower is recognized. -
minutes integer Number of minutes East of GMT, if the cell tower is recognized. -
lat number Latitude of the Notecard, if the cell tower is recognized. -
lon number Longitude of the Notecard, if the cell tower is recognized. -
country string The country where the Notecard is located, if the cell tower is recognized. -

Examples:

Returns the current date and time information in UTC (UNIX timestamp).

{
  "time": 1599769214,
  "area": "Beverly, MA",
  "zone": "CDT,America/New York",
  "minutes": -300,
  "lat": 42.5776,
  "lon": -70.87134,
  "country": "US"
}

card.transport

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Specifies the connectivity protocol to prioritize on the Notecard Cell+WiFi, or when using NTN mode with Starnote and a compatible Notecard.

Parameters:

Parameter Type Description Default
method string The connectivity method to enable on the Notecard.

Allowed Values:
  • "-": Resets the transport mode to the device default. (CELL, CELL+WIFI, WIFI)
  • "cell": Enables cellular only on the device. (CELL, CELL+WIFI)
  • "cell-ntn": Prioritizes cellular connectivity while falling back to NTN if a cellular connection cannot be established. (CELL, CELL+WIFI)
  • "dual-wifi-cell": Deprecated form of "wifi-cell" ⚠️ DEPRECATED (CELL+WIFI)
  • "ntn": Enables NTN (Non-Terrestrial Network) mode on the device for use with Starnote. (CELL, CELL+WIFI, WIFI)
  • "wifi": Enables Wi-Fi only on the device. (CELL+WIFI, WIFI)
  • "wifi-cell": Prioritizes Wi-Fi connectivity while falling back to cellular if a Wi-Fi connection cannot be established. This is the default behavior on Notecard Cell+WiFi. (CELL+WIFI)
  • "wifi-cell-ntn": Prioritizes Wi-Fi connectivity while falling back to cellular, and lastly to NTN. (CELL+WIFI)
  • "wifi-ntn": Prioritizes Wi-Fi connectivity while falling back to NTN if a Wi-Fi connection cannot be established. (CELL+WIFI, WIFI)
 -
seconds integer The amount of time a Notecard will spend on any fallback transport before retrying the first transport specified in the method. The default is 3600 or 60 minutes. 3600
allow boolean Set to true to allow adding Notes to non-compact Notefiles while connected over a non-terrestrial network. See Define NTN vs non-NTN Templates. False
umin boolean Set to true to force a longer network transport timeout when using Wideband Notecards. False

Examples:

Example

{
  "req": "card.transport",
  "method": "wifi-cell"
}

Response

No description available.

Parameters:

Parameter Type Description Default
method string The connectivity method currently enabled on the device. -

Examples:

Response for card.transport with method set to wifi-cell.

{
  "method": "wifi-cell"
}

card.triangulate

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Enables or disables a behavior by which the Notecard gathers information about surrounding cell towers and/or Wi-Fi access points with each new Notehub session.

Parameters:

Parameter Type Description Default
mode string The triangulation approach to use for determining the Notecard location. The following keywords can be used separately or together in a comma-delimited list, in any order.

Allowed Values:
  • "cell": Enables cell tower scanning to determine the position of the Device.
  • "wifi": Enables the use of nearby Wi-Fi access points to determine the position of the Device. To leverage this feature, the host will need to provide access point information to the Notecard via the text argument in subsequent requests.
  • "-": Clear the currently-set triangulation mode.
 -
on boolean true to instruct the Notecard to triangulate even if the module has not moved. Only takes effect when set is true. False
usb boolean true to perform triangulation only when the Notecard is connected to USB power. Only takes effect when set is true. False
set boolean true to instruct the module to use the state of the on and usb arguments. False
minutes integer Minimum delay, in minutes, between triangulation attempts. Use 0 for no time-based suppression. 0
text string When using Wi-Fi triangulation, a newline-terminated list of Wi-Fi access points obtained by the external module. Format should follow the ESP32's AT+CWLAP command output. -
time integer When passed with text, records the time that the Wi-Fi access point scan was performed. If not provided, Notecard time is used. -

Note

See Using Cell Tower & Wi-Fi Triangulation for more information.

Examples:

Enable triangulation using cell towers only.

{
  "req": "card.triangulate",
  "mode": "cell",
  "on": true,
  "set": true
}

Enable triangulation using both Wi-Fi and cell towers when connected to USB power.

{
  "req": "card.triangulate",
  "mode": "wifi,cell",
  "on": true,
  "usb": true,
  "set": true
}

Send a newline-terminated list of Wi-Fi access points to the Notecard for triangulation.

{
  "req": "card.triangulate",
  "text": "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)\n+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)\n+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)\n+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)\n+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\n\n"
}

Disable triangulation mode.

{
  "req": "card.triangulate",
  "mode": "-"
}

Response

Response containing triangulated location information and triangulation settings.

Parameters:

Parameter Type Description Default
motion integer UNIX Epoch time of last detected Notecard movement. -
time integer UNIX Epoch time of last triangulation scan. -
mode string A comma-separated list indicating the active triangulation modes. -
on boolean true if triangulation scans will be performed even if the device has not moved. -
usb boolean true if triangulation scans will be performed only when the device is USB-powered. -
length integer The length of the text buffer provided in the current or a previous request. -

Examples:

Response showing triangulation configuration and status.

{
  "usb": true,
  "mode": "wifi,cell",
  "length": 443,
  "on": true,
  "time": 1606755042,
  "motion": 1606757487
}

card.usage.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

Request

Returns the card's network usage statistics.

Parameters:

Parameter Type Description Default
mode string The time period to use for statistics.

Allowed Values:
  • "total": All stats since the Notecard was activated.
 total
offset integer The number of time periods to look backwards, based on the specified mode. To accurately determine the start of the calculated time period when using offset, use the time value of the response. Likewise, to calculate the end of the time period, add the seconds value to the time value. -

Note

Usage data is updated by the Notecard at the end of each network connection. If connected in continuous mode, usage data will not be updated until the current session ends, which you can configure with the hub.set duration argument.

Examples:

Example

{
  "req": "card.usage.get",
  "mode": "1day",
  "offset": 5
}

Response

No description available.

Parameters:

Parameter Type Description Default
seconds integer Number of seconds in the analyzed period. -
time integer Start time (Unix epoch seconds) of the analyzed period or, if mode="total", the time of activation. -
bytes_sent integer Number of bytes sent by the Notecard to Notehub. -
bytes_received integer Number of bytes received by the Notecard from Notehub. -
notes_sent integer Approximate number of Notes sent by the Notecard to Notehub. -
notes_received integer Approximate number of Notes received by the Notecard from Notehub. -
sessions_standard integer Number of standard Notehub sessions. -
sessions_secure integer Number of secure Notehub sessions. -

Examples:

Example Response

{
  "seconds": 1291377,
  "time": 1598479763,
  "bytes_sent": 163577,
  "bytes_received": 454565,
  "notes_sent": 114,
  "notes_received": 26,
  "sessions_standard": 143,
  "sessions_secure": 31
}

card.usage.test

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Request schema for card.usage.test API command.

Parameters:

Parameter Type Description Default
days integer Number of days to use for the test. -
hours integer If you want to analyze a period shorter than one day, the number of hours to use for the test. -
megabytes integer The Notecard lifetime data quota (in megabytes) to use for the test. 1024

Examples:

Example

{
  "req": "card.usage.test",
  "days": 7,
  "megabytes": 500
}

Response

No description available.

Parameters:

Parameter Type Description Default
max integer The days of projected data available based on test. -
days integer The number of days used for the test. -
bytes_per_day integer Average bytes per day used during the test period. -
seconds integer Number of seconds in the analyzed period. -
time integer Time of device activation (UNIX Epoch time). -
bytes_sent integer Number of bytes sent by the Notecard to Notehub. -
bytes_received integer Number of bytes received by the Notecard from Notehub. -
notes_sent integer Number of notes sent by the Notecard to Notehub. -
notes_received integer Number of notes received by the Notecard from Notehub. -
sessions_standard integer Number of standard Notehub sessions. -
sessions_secure integer Number of secure Notehub sessions. -

Examples:

Example Response

{
  "max": 12730,
  "days": 7,
  "bytes_per_day": 41136,
  "seconds": 1291377,
  "time": 1598479763,
  "bytes_sent": 163577,
  "bytes_received": 454565,
  "notes_sent": 114,
  "notes_received": 26,
  "sessions_standard": 143,
  "sessions_secure": 31
}

card.version

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Returns firmware version information for the Notecard.

Parameters:

Parameter Type Description Default
api integer Host expected major version of the Notecard API -

Response

No description available.

Parameters:

Parameter Type Description Default
api integer Major version of the Notecard API -
board string Notecard hardware version number -
body object An object containing Notecard firmware details for programmatic access -
cell boolean Notecard supports cellular connectivity -
device string DeviceUID of the Notecard -
gps boolean Notecard has an onboard GPS module -
name string Official name of the device -
sku string Notecard Stock Keeping Unit (SKU) -
version string Complete firmware version of the Notecard -
wifi boolean Notecard supports Wi-Fi connectivity -

card.voltage

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Provides the current V+ voltage level on the Notecard, and provides information about historical voltage trends. When used with the mode argument, configures voltage thresholds based on how the device is powered.

Parameters:

Parameter Type Description Default
hours integer The number of hours to analyze, up to 720 (30 days) -
mode string Used to set voltage thresholds based on how the Notecard will be powered. Allowed values: default, lipo, li, alkaline, tad, lic -
vmax number Maximum voltage threshold -
vmin number Minimum voltage threshold -

Response

No description available.

Parameters:

Parameter Type Description Default
mode string The current voltage threshold mode -
usb boolean Whether the Notecard is being powered by USB -
value number Current voltage in volts -
vref number Reference voltage in volts -
vmax number Maximum voltage threshold -
vmin number Minimum voltage threshold -
vhigh number High voltage threshold -
vnormal number Normal voltage threshold -
vlow number Low voltage threshold -
vdead number Dead voltage threshold -

card.wifi

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL+WIFI WIFI

Request

Sets up a Notecard WiFi to connect to a Wi-Fi access point.

Parameters:

Parameter Type Description Default
ssid string The SSID of the Wi-Fi access point. Alternatively, use - to clear an already set SSID. -
password string The network password of the Wi-Fi access point. Alternatively, use - to clear an already set password or to connect to an open access point. -
name string By default, the Notecard creates a SoftAP (software enabled access point) under the name "Notecard". You can use the name argument to change the name of the SoftAP to a custom name. If you include a - at the end of the name (for example "name": "acme-"), the Notecard will append the last four digits of the network's MAC address (for example acme-025c). This allows you to distinguish between multiple Notecards in SoftAP mode. -
org string If specified, replaces the Blues logo on the SoftAP page with the provided name. -
start boolean Specify true to activate SoftAP mode on the Notecard programmatically. -
text string A string containing an array of access points the Notecard should attempt to use. The access points should be provided in the following format: ["FIRST-SSID","FIRST-PASSWORD"],["SECOND-SSID","SECOND-PASSWORD"]. You may need to escape any quotes used in this argument before passing it to the Notecard. For example, the following is a valid request to pass to a Notecard through the In-Browser Terminal. {"req":"card.wifi", "text":"[\"FIRST-SSID\",\"FIRST-PASSWORD\"]"} -

Note

Updates to Notecard WiFi credentials cannot occur while Notecard is in continuous mode, as a new session is required to change the credentials. If you have a Notecard WiFi in continuous mode, you must change to another mode such as periodic or off, using a hub.set request before calling card.wifi.

Examples:

Set Wi-Fi SSID and password

{
  "req": "card.wifi",
  "ssid": "MyWiFiNetwork",
  "password": "MyPassword123"
}

Start SoftAP mode with custom name

{
  "req": "card.wifi",
  "name": "MyNotecard-",
  "start": true
}

Configure multiple access points using text parameter

{
  "req": "card.wifi",
  "text": "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]"
}

Clear existing Wi-Fi credentials

{
  "req": "card.wifi",
  "ssid": "-",
  "password": "-"
}

Response

Response containing Wi-Fi connection status and configuration information from the Notecard.

Parameters:

Parameter Type Description Default
secure boolean true means that the Wi-Fi access point is using Management Frame Protection. -
version string The Silicon Labs WF200 Wi-Fi Transceiver binary version. -
ssid string The SSID of the Wi-Fi access point. -
security string The security protocol the Wi-Fi access point uses. -

Examples:

Wi-Fi connection status and configuration information

{
  "secure": true,
  "version": "3.12.3",
  "ssid": "<ssid name>",
  "security": "wpa2-psk"
}

card.wireless

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

View the last known network state, or customize the behavior of the modem. Note: Be careful when using this mode with hardware not on hand as a mistake may cause loss of network and Notehub access.

Parameters:

Parameter Type Description Default
mode string Network scan mode. Allowed values: -, auto, m, nb, gprs -
apn string Access Point Name (APN) when using an external SIM -
method string Used when configuring a Notecard to failover to a different SIM. Allowed values: -, dual-primary-secondary, dual-secondary-primary, primary, secondary -

Response

No description available.

Parameters:

Parameter Type Description Default
status string Current network status -
count integer Number of networks found -
net array Array of networks found -

card.wireless.penalty

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

View the current state of a Notecard Penalty Box, manually remove the Notecard from a penalty box, or override penalty box defaults.

Parameters:

Parameter Type Description Default
reset boolean Set to true to remove the Notecard from certain types of penalty boxes. -
set boolean Set to true to override the default settings of the Network Registration Failure Penalty Box. -
rate number The rate at which the penalty box time multiplier is increased over successive retries. Used with the set argument to override the Network Registration Failure Penalty Box defaults. 1.25
add integer The number of minutes to add to successive retries. Used with the set argument to override the Network Registration Failure Penalty Box defaults. 15
max integer The maximum number of minutes that a device can be in a Network Registration Failure Penalty Box. Used with the set argument to override the Network Registration Failure Penalty Box defaults. 4320
min integer The number of minutes of the first retry interval of a Network Registration Failure Penalty Box. Used with the set argument to override the Network Registration Failure Penalty Box defaults. 15

Warning

The misuse of this feature may result in the cellular carrier preventing the Notecard from future connections because it's effectively "spamming" the network. The cellular carrier may blacklist devices that it thinks are attempting to connect too frequently.

Examples:

Check Penalty Box State.

{
  "req": "card.wireless.penalty"
}

Remove from Penalty Box.

{
  "req": "card.wireless.penalty",
  "reset": true
}

Override Default Penalty Box Settings.

{
  "req": "card.wireless.penalty",
  "set": true,
  "rate": 2.0,
  "add": 10,
  "max": 720,
  "min": 5
}

Response

No description available.

Parameters:

Parameter Type Description Default
minutes integer The time since the first network registration failure. -
count integer The number of consecutive network registration failures. -
status string If the Notecard is in a Penalty Box, this field provides the associated Error and Status Codes. -
seconds integer If the Notecard is in a Penalty Box, the number of seconds until the penalty condition ends. -

Examples:

Penalty Box Status with Active Penalty.

{
  "seconds": 3324,
  "minutes": 69,
  "status": "network: can't connect (55.4 min remaining) {registration-failure}{network}{extended-network-failure}",
  "count": 6
}

dfu.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

Request

Retrieves downloaded firmware data from the Notecard for use with IAP host MCU firmware updates.

Parameters:

Parameter Type Description Default
length integer The number of bytes of firmware data to read and return to the host. Set to 0 to verify that the Notecard is in DFU mode without attempting to retrieve data. -
offset integer The offset to use before performing a read of firmware data. -

Note

This request is functional only when the Notecard has been set to dfu mode with a hub.set, mode:dfu request.

Examples:

Retrieves 32 bytes of firmware data from the Notecard, with an offset of 32 bytes.

{
  "req": "dfu.get",
  "length": 32,
  "offset": 32
}

Response

No description available.

Parameters:

Parameter Type Description Default
payload string A base64 string containing firmware data of the provided length. -

Examples:

Returns a base64 string containing firmware data of the provided length.

{
  "payload": "AAAAAAAAAAAAAAAAcy8ACIEvAAgAAAAAjy8ACJ0vAAg="
}

dfu.status

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Gets and sets the background download status of MCU host or Notecard firmware updates.

Parameters:

Parameter Type Description Default
name string Determines which type of firmware update status to view. Allowed values: user, card -
stop boolean Clear DFU state and delete the local firmware image from the Notecard -
status string Optional string synchronized to Notehub, which can be used for informational or diagnostic purposes -
version ['string', 'object'] Version information on the host firmware to pass to Notehub -
vvalue string A voltage-variable string that controls, by Notecard voltage, whether or not DFU is enabled -
on boolean Allow firmware downloads from Notehub -
off boolean Disable firmware downloads from Notehub -
err string Sets the host DFU to an error state with the specified string -

Response

No description available.

Parameters:

Parameter Type Description Default
mode string Current DFU mode -
status string Status of the DFU process -
on boolean Whether firmware downloads from Notehub are allowed -
off boolean Whether firmware downloads from Notehub are disabled -
pending boolean Whether a firmware update is pending -
body object Additional information about the DFU status -

env.default

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Used by the Notecard host to specify a default value for an environment variable until that variable is overridden by a device, project or fleet-wide setting at Notehub.

Parameters:

Parameter Type Description Default
name string Name of the environment variable -
text string Default value for the environment variable -

Response

No description available.

Parameters:

Parameter Type Description Default
name string Name of the environment variable -
text string Default value for the environment variable -

env.get

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Returns a single environment variable, or all variables according to precedence rules.

Parameters:

Parameter Type Description Default
name string Name of the environment variable to get -
names array Array of environment variable names to get -
time boolean Return the time when the environment variable was last modified -

Response

No description available.

Parameters:

Parameter Type Description Default
name string Name of the environment variable -
text string Value of the environment variable -
body object Object containing environment variables and their values -
time integer Time when the environment variable was last modified -

env.modified

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Get the time of the update to any environment variable managed by the Notecard.

Parameters:

Parameter Type Description Default
time integer Request whether the Notecard has detected an environment variable change since a known epoch time -

Response

No description available.

Parameters:

Parameter Type Description Default
time integer Time when the environment variables were last modified -

env.set

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

deprecatedThe env.set API is deprecated as of v7.2.2. We recommend setting environment variables in Notehub using either the Notehub user interface or Notehub API. You may also use the env.default API to provide a default value for an environment variable, until that variable is overridden by a value from Notehub.

Parameters:

Parameter Type Description Default
name string Name of the environment variable to set -
text string Value to set for the environment variable -

Response

No description available.

Parameters:

Parameter Type Description Default
name string Name of the environment variable -
text string Value of the environment variable -
time integer The logged time of the variable change -

env.template

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

The env.template request allows developers to provide a schema for the environment variables the Notecard uses. The provided template allows the Notecard to store environment variables as fixed-length binary records rather than as flexible JSON objects that require much more memory.

Parameters:

Parameter Type Description Default
body object Template object with environment variable placeholders -

Response

No description available.

Parameters:

Parameter Type Description Default
bytes integer Size of the processed template in bytes -

file.changes

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Used to perform queries on a single or multiple files to determine if new Notes are available to read, or if there are unsynced Notes in local Notefiles.

Parameters:

Parameter Type Description Default
files array One or more files to obtain change information from -
tracker string ID of a change tracker to use to determine changes to Notefiles -

Response

No description available.

Parameters:

Parameter Type Description Default
total integer Total number of files -
changes integer Number of files that have changed -
info object Information about the changes -

file.changes.pending

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Returns info about file changes that are pending upload to Notehub.

Response

No description available.

Parameters:

Parameter Type Description Default
total integer The total of unsynced notes across all Notefiles -
changes integer The number of changes across all files -
pending boolean Whether there are pending changes -
info object Information about changes for each Notefile -

file.delete

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Deletes Notefiles and the Notes they contain.

Parameters:

Parameter Type Description Default
files array Array of files to delete -

Response

No description available.

Parameters:

Parameter Type Description Default
result object Empty object returned on success -

file.stats

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Gets resource statistics about local Notefiles.

Parameters:

Parameter Type Description Default
file string Optional file to get stats for -

Response

No description available.

Parameters:

Parameter Type Description Default
total integer Total number of notes in the file -
changes integer Number of changes to the file -
sync boolean Whether the file is synced with Notehub -

hub.get

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Retrieves the current Notehub configuration for the Notecard.

Response

No description available.

Parameters:

Parameter Type Description Default
device string The DeviceUID for the Notecard -
product string Product identifier -
mode string Hub mode (periodic, continuous, minimum) -
outbound integer Outbound data period in seconds -
voutbound string Voltage-variable outbound period -
inbound integer Inbound data period in seconds -
vinbound string Voltage-variable inbound period -
host string Host address -
sn string Serial number -
sync boolean Whether sync is enabled -

hub.log

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

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

Parameters:

Parameter Type Description Default
text string Text to log -
alert boolean Whether this is an alert message -
sync boolean Whether to sync this log message immediately -

Response

No description available.

No specific parameters defined.

hub.set

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

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

Parameters:

Parameter Type Description Default
product string Product identifier -
host string Host address -
mode string Hub mode (periodic, continuous, minimum, off). Allowed values: continuous, periodic, minimum, off -
sn string Serial number -
outbound integer Outbound data period in seconds -
duration integer Duration of the outbound period in seconds -
voutbound string Voltage-variable outbound period -
inbound integer Inbound data period in seconds -
vinbound string Voltage-variable inbound period -
align boolean Whether to align the inbound and outbound periods -
sync boolean Whether to sync immediately -
on boolean Whether to turn on the hub -
seconds integer Number of seconds to wait before turning off -
off boolean Whether to turn off the hub -
uperiodic integer Microseconds for periodic mode -
umin integer Microseconds for minimum mode -
uoff integer Microseconds for off mode -
details boolean Whether to include details in the response -
version ['string', 'object'] Version information -

Response

No description available.

Parameters:

Parameter Type Description Default
result object Empty object returned on success -

hub.signal

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

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

Parameters:

Parameter Type Description Default
seconds integer Number of seconds to wait for a signal -

Response

No description available.

Parameters:

Parameter Type Description Default
body object Signal information -
connected boolean Whether the Notecard is connected to the network -
signals array Array of signal information -

hub.status

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

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

Response

No description available.

Parameters:

Parameter Type Description Default
status string Hub connection status -
connected boolean Whether the Notecard is connected to the hub -

hub.sync

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Manually initiates a sync with Notehub.

Parameters:

Parameter Type Description Default
allow boolean Whether to allow the sync to proceed -
out boolean Whether to sync outbound data -
in boolean Whether to sync inbound data -

Response

No description available.

Parameters:

Parameter Type Description Default
result object Empty object returned on success -

hub.sync.status

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

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

Parameters:

Parameter Type Description Default
sync boolean Whether to sync immediately -

Response

No description available.

Parameters:

Parameter Type Description Default
status string Status of the sync operation -
mode string Current sync mode -
time integer Time of the last sync -
alert string Alert message -
sync boolean Whether a sync is in progress -
completed boolean Whether the sync has completed -
requested boolean Whether a sync has been requested -
seconds integer Number of seconds since the last sync -
scan boolean Whether a scan is in progress -

note.add

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Adds a Note to a Notefile, creating the Notefile if it doesn't yet exist.

Parameters:

Parameter Type Description Default
file string Name of the notefile to add the note to -
note object Note data to add -
body object Note body data -
payload string Binary payload data -

Response

No description available.

Parameters:

Parameter Type Description Default
note string ID of the added note -

note.changes

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Used to incrementally retrieve changes within a specific Notefile.

Parameters:

Parameter Type Description Default
file string Name of the notefile to check for changes -
tracker string Tracker ID for monitoring changes -

Response

No description available.

Parameters:

Parameter Type Description Default
changes boolean Whether there are changes -
notes array Array of note IDs that have changed -
tracker string Tracker ID for monitoring changes -

note.delete

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Deletes a Note from a DB Notefile by its Note ID. To delete Notes from a .qi Notefile, use note.get or note.changes with delete:true.

Parameters:

Parameter Type Description Default
file string Name of the notefile to delete notes from -
note string ID of the note to delete -
notes array Array of note IDs to delete -

Response

No description available.

Parameters:

Parameter Type Description Default
success boolean Whether the deletion was successful -

note.get

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Retrieves a Note from a Notefile. The file must either be a DB Notefile or inbound queue file (see file argument below).

Parameters:

Parameter Type Description Default
file string Name of the notefile to get the note from -
note string ID of the note to get -
delete boolean Whether to delete the note after getting it -

Response

No description available.

Parameters:

Parameter Type Description Default
note string ID of the note -
body object Note body data -
payload string Binary payload data -

note.template

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

By using the note.template request with any .qo/.qos Notefile, developers can provide the Notecard with a schema of sorts to apply to future Notes added to the Notefile. This template acts as a hint to the Notecard that allows it to internally store data as fixed-length binary records rather than as flexible JSON objects which require much more memory. Using templated Notes in place of regular Notes increases the storage and sync capability of the Notecard by an order of magnitude.

Parameters:

Parameter Type Description Default
file string The name of the Notefile to which the template will be applied. -
body object A sample JSON body that specifies field names and values as "hints" for the data type. Possible data types are: boolean, integer, float, and string. See Understanding Template Data Types for an explanation of type hints and explanations. -
length integer The maximum length of a payload (in bytes) that can be sent in Notes for the template Notefile. As of v3.2.1 length is not required, and payloads can be added to any template-based Note without specifying the payload length. -
verify boolean If true, returns the current template set on a given Notefile. -
format string By default all Note templates automatically include metadata, including a timestamp for when the Note was created, various fields about a device's location, as well as a timestamp for when the device's location was determined. By providing a format of "compact" you tell the Notecard to omit this additional metadata to save on storage and bandwidth. The use of format: "compact" is required for Notecard LoRa and a Notecard paired with Starnote. When using "compact" templates, you may include the following keywords in your template to add in fields that would otherwise be omitted: _lat, _lon, _ltime, _time. See Creating Compact Templates to learn more. -
port integer This argument is required on Notecard LoRa and a Notecard paired with Starnote, but ignored on all other Notecards. A port is a unique integer in the range 1–100, where each unique number represents one Notefile. This argument allows the Notecard to send a numerical reference to the Notefile over the air, rather than the full Notefile name. The port you provide is also used in the "frame port" field on LoRaWAN gateways. -
delete boolean Set to true to delete all pending Notes using the template if one of the following scenarios is also true: Connecting via non-NTN (e.g. cellular or Wi-Fi) communications, but attempting to sync NTN-compatible Notefiles. or Connecting via NTN (e.g. satellite) communications, but attempting to sync non-NTN-compatible Notefiles. Read more about this feature in Starnote Best Practices. -

Note

Read about Working with Note Templates for additional information.

Note

See examples of note.template usage in these accelerator projects.

Examples:

Response

No description available.

Parameters:

Parameter Type Description Default
bytes integer The number of bytes that will be transmitted to Notehub, per Note, before compression. -
template boolean true if an active template exists on the Notefile. -
body object If the verify argument is provided and the Notefile has an active template, the template body. -
length integer If the verify argument is provided and the Notefile has an active template with a payload, the payload length. -
format string If the format argument is provided, this represents the format applied to the template. -

Examples:

note.update

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Updates a Note in a DB Notefile by its ID, replacing the existing body and/or payload.

Parameters:

Parameter Type Description Default
file string Name of the notefile to update the note in -
note string ID of the note to update -
body object Updated note body data -
payload string Updated binary payload data -

Response

No description available.

Parameters:

Parameter Type Description Default
success boolean Whether the update was successful -

ntn.gps

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Determines whether a Notecard should override a paired Starnote's GPS/GNSS location with its own GPS/GNSS location. The paired Starnote uses its own GPS/GNSS location by default.

Parameters:

Parameter Type Description Default
mode string GPS mode. Allowed values: continuous, periodic, off -

Response

No description available.

Parameters:

Parameter Type Description Default
mode string Current GPS mode -

ntn.reset

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Once a Notecard is connected to a Starnote device, the presence of a physical Starnote is stored in a permanent configuration that is not affected by a card.restore request. This request clears this configuration and allows you to return to testing NTN mode over cellular or Wi-Fi.

Response

No description available.

Parameters:

Parameter Type Description Default
success boolean Whether the reset was successful -

ntn.status

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Displays the current status of a Notecard's connection to a paired Starnote.

Response

No description available.

Parameters:

Parameter Type Description Default
status string Status of the Notehub connection -
connected boolean Whether the Notecard is connected to Notehub -
time integer Current time (Unix epoch seconds) -

var.delete

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Delete a Note from a DB Notefile by its name. Provides a simpler interface to the note.delete API.

Parameters:

Parameter Type Description Default
name string Name of the variable to delete -

Response

No description available.

Parameters:

Parameter Type Description Default
success boolean Whether the variable was successfully deleted -

var.get

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Retrieves a Note from a DB Notefile. Provides a simpler interface to the note.get API.

Parameters:

Parameter Type Description Default
name string Name of the variable to get -

Response

No description available.

Parameters:

Parameter Type Description Default
name string Name of the variable -
text string Value of the variable -

var.set

Version Information

Schema Version: 0.1.1 | API Version: 9.1.1

Request

Adds or updates a Note in a DB Notefile, replacing the existing body with the specified key-value pair where text, value, or flag is the key. Provides a simpler interface to the note.update API.

Parameters:

Parameter Type Description Default
name string Name of the variable to set -
text string Value to set for the variable -

Response

No description available.

Parameters:

Parameter Type Description Default
name string Name of the variable -
text string Value of the variable -

web

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

Request

JSON description of the web API

Parameters:

Parameter Type Description Default
route string Alias for a Proxy Route in Notehub. -
method string The HTTP method of the request. Must be one of GET, PUT, POST, DELETE, PATCH, HEAD, OPTIONS, TRACE, or CONNECT.. Allowed values: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE -
name string A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /getLatest?id=1). -
content string The MIME type of the body or payload of the response. Default is application/json. -

Note

Please see the additional argument options available for GET, POST, PUT, and DELETE requests in the documentation provided.

Examples:

Get the current time

{
  "req": "web",
  "method": "GET",
  "route": "weatherInfo",
  "name": "/getLatest"
}

Response

No description available.

Parameters:

Parameter Type Description Default
result integer The HTTP Status Code -
body object The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes. -
payload string A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes. -
length integer The length of the returned binary payload (in bytes). -
cobs integer The size of the COBS-encoded data (in bytes). -

Examples:

Response from a web request

{
  "result": 200,
  "body": {
    "temp": 75,
    "humidity": 49
  }
}

web.delete

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Performs a simple HTTP or HTTPS DELETE request against an external endpoint, and returns the response to the Notecard.

Parameters:

Parameter Type Description Default
route string Alias for a Proxy Route in Notehub. -
name string A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /deleteReading?id=1). -
content string The MIME type of the body or payload of the response. Default is application/json. application/json
seconds integer If specified, overrides the default 90 second timeout. 90
async boolean If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub. -
file string The name of the local-only Database Notefile (.dbx) to be used if the web request is issued asynchronously and you wish to store the response. -
note string The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above). -

Examples:

Example

{
  "req": "web.delete",
  "route": "SensorService",
  "name": "/deleteReading?id=1"
}

Response

No description available.

Parameters:

Parameter Type Description Default
result integer The HTTP Status Code -
body object The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes. -
payload string A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes. -
status string If a payload is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption. -

Examples:

Example Response

{
  "result": 204
}

web.get

Version Information

Schema Version: 0.3.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Performs a simple HTTP or HTTPS GET request against an external endpoint, and returns the response to the Notecard.

Parameters:

Parameter Type Description Default
route string Alias for a Proxy Route in Notehub. -
name string A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /getLatest?id=1). -
body object The JSON body to send with the request. -
content string The MIME type of the body or payload of the response. Default is application/json. -
seconds integer If specified, overrides the default 90 second timeout. -
async boolean If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub. -
binary boolean If true, the Notecard will return the response stored in its binary buffer. -
offset integer Used along with binary:true and max, sent as a URL parameter to the remote endpoint. Represents the number of bytes to offset the binary payload from 0 when retrieving binary data from the remote endpoint. -
max integer Used along with binary:true and offset, sent as a URL parameter to the remote endpoint. Represents the number of bytes to retrieve from the binary payload segment. -
file string The name of the local-only Database Notefile (.dbx) to be used if the web request is issued asynchronously and you wish to store the response. -
note string The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above). -

Note

Learn more in this guide on Sending and Receiving Large Binary Objects.

Warning

The Notecard must have an active connection to Notehub while performing any web.* request. Please consult this guide for more information.

Examples:

Performs a simple HTTP or HTTPS GET request and returns the response.

{
  "req": "web.get",
  "route": "weatherInfo",
  "name": "/getLatest"
}

Response

No description available.

Parameters:

Parameter Type Description Default
result integer The HTTP Status Code. -
body object The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes. -
payload string A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes. -
length integer The length of the returned binary payload (in bytes). -
cobs integer The size of the COBS-encoded data (in bytes). -

Examples:

Response body from HTTP GET request to the external service.

{
  "result": 200,
  "body": {
    "temp": 75,
    "humidity": 49
  }
}

web.post

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Performs a simple HTTP or HTTPS POST request against an external endpoint, and returns the response to the Notecard.

Parameters:

Parameter Type Description Default
route string Alias for a Proxy Route in Notehub. -
name string A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /addReading?id=1). -
body object The JSON body to send with the request. -
payload string A base64-encoded binary payload. A web.post may have either a body or a payload, but may NOT have both. Be aware that Notehub will decode the payload as it is delivered to the endpoint. Learn more about sending large binary objects with the Notecard. -
content string The MIME type of the body or payload of the response. Default is application/json. application/json
seconds integer If specified, overrides the default 90 second timeout. 90
total integer When sending large payloads to Notehub in fragments across several web.post requests, the total size, in bytes, of the binary payload across all fragments. -
offset integer When sending payload fragments, the number of bytes of the binary payload to offset from 0 when reassembling on the Notehub once all fragments have been received. -
status string A 32-character hex-encoded MD5 sum of the payload or payload fragment. Used by Notehub to perform verification upon receipt. -
max integer The maximum size of the response from the remote server, in bytes. Useful if a memory-constrained host wants to limit the response size. -
verify boolean true to request verification from Notehub once the payload or payload fragment is received. Automatically set to true when status is supplied. -
async boolean If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub. -
binary boolean If true, the Notecard will send all the data in the binary buffer to the specified proxy route in Notehub. Learn more in this guide on Sending and Receiving Large Binary Objects. -
file string The name of the local-only Database Notefile (.dbx) to be used if the web request is issued asynchronously and you wish to store the response. -
note string The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above). -

Examples:

Example

{
  "req": "web.post",
  "route": "SensorService",
  "name": "/addReading",
  "body": {
    "temp": 72.32,
    "humidity": 32.2
  }
}

Response

No description available.

Parameters:

Parameter Type Description Default
result integer The HTTP Status Code. -
body object The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes. -
payload string A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes. -
status string If a payload is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption. -
cobs integer If the web transaction returns a binary payload, cobs is the size of the COBS-encoded payload (in bytes). -
length integer If the web transaction returns a binary payload, length is the size of the unencoded payload (in bytes). -

Examples:

Example Response

{
  "result": 201
}

web.put

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Performs a simple HTTP or HTTPS PUT request against an external endpoint, and returns the response to the Notecard.

Parameters:

Parameter Type Description Default
route string Alias for a Proxy Route in Notehub. -
name string A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /updateReading?id=1). -
body object The JSON body to send with the request. -
payload string A base64-encoded binary payload. A web.put may have either a body or a payload, but may NOT have both. Be aware that Notehub will decode the payload as it is delivered to the endpoint. Learn more about sending large binary objects with the Notecard. -
content string The MIME type of the body or payload of the response. Default is application/json. application/json
seconds integer If specified, overrides the default 90 second timeout. 90
total integer When sending large payloads to Notehub in fragments across several web.put requests, the total size, in bytes, of the binary payload across all fragments. -
offset integer When sending payload fragments, the number of bytes of the binary payload to offset from 0 when reassembling on the Notehub once all fragments have been received. -
status string A 32-character hex-encoded MD5 sum of the payload or payload fragment. Used by Notehub to perform verification upon receipt. -
max integer The maximum size of the response from the remote server, in bytes. Useful if a memory-constrained host wants to limit the response size. Default (and maximum value) is 8192. 90
verify boolean true to request verification from Notehub once the payload or payload fragment is received. Automatically set to true when status is supplied. -
async boolean If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub. -
file string The name of the local-only Database Notefile (.dbx) to be used if the web request is issued asynchronously and you wish to store the response. -
note string The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above). -

Examples:

Performs a simple HTTP or HTTPS PUT request and returns the response.

{
  "req": "web.put",
  "route": "SensorService",
  "name": "/updateReading",
  "body": {
    "id": 1234,
    "temp": 72.32,
    "humidity": 32.2
  }
}

Response

No description available.

Parameters:

Parameter Type Description Default
result integer The HTTP Status Code. -
body object The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes. -
payload string A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes. -
status integer If a payload is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption. -

Examples:

Example Response

{
  "result": 204
}