Glossary

A • B • C • D • E • F • G • H • I • J • K • L • M • N • O • P • Q • R • S • T • U • V • W • X • Y • Z •

Account

Metadata (email, role(s), etc.) maintained by a Notehub for an individual who has access to that Notehub for use in developing or operating Notecard-based applications.

AppUID

A globally-unique string identifier for a given Notehub application in the following format:

app:00000000-0000-0000-0000-000000000000

AppUID and ProjectUID refer to the same value.

A JSON object containing data needed by an application. The contents of this object are up to the developer and can include any keys, values and nested objects required, as long as the object is valid JSON.

"body":{"temp":34.2,"alert":true,"particle":{"mass":[5.1,12.32],"count":[124,1800]}}

COBS

Consistent Overhead Byte Stuffing (COBS) is an algorithm used to replace byte values in a block of data with other byte values, specifically to eliminate delimiters. It's commonly employed in serial communication to ensure that certain values don't appear in the data, allowing them to be used as control characters.

Connectivity Assurance

Connectivity Assurance ensures your Notecards stay online. When an individual Notecard's cellular data balance drops below 100MB, Connectivity Assurance automatically adds 500MB to its SIM data plan with no manual intervention required.

This feature is enabled by default if your Notehub Organization has a payment method on file. The added 500MB is valid for up to 10 years and costs $10 for North America Notecards (e.g. NBNA and WBNA) and $15 for international Notecards (e.g. NBGL and WBEX).

Customer

The entity or individual accountable for development of a product within which the Notecard is embedded.

Device

A product containing a Notecard. This may be the Notecard by itself, a Notecard on a Notecarrier, or embedded in a customer design.

DeviceUID

A globally-unique string identifier factory-assigned to the Notecard, such as the following.

dev:000000000000000

Note: This value is laser-engraved onto the Notecard; any customer wishing to use this as a part of their own product's serial number may easily do so as a part of their manufacturing process.

Environment Variable

Environment Variables are a state and settings management feature that allows for various levels of control for variables that apply to a Device, across a Fleet, or to all devices in a Project.

These values are key-value pairs and can be set in Notehub or via the Notehub API. They propagate to devices using the same synchronization mechanism used for Notes and Notefiles.

For more information, please see Understanding Environment Variables.

Event

Each time Notehub receives or sends a Note, it creates a single event. An event consists of the Note's JSON payload combined with metadata appended by Notehub.

Events can be forwarded to external cloud applications or services using a Route. Routing an event does not affect billing.

Each event ingested by Notehub counts as one event credit against your event capacity, regardless of how many Routes it is sent to. Platform Events do not consume event credits.

More information is available on our pricing page.

Event Capacity

Event capacity is the total number of events a Notehub Organization can ingest, determined by the number of event credits currently available to the account. For Organizations on the Essentials plan, if the remaining capacity falls below 5,000 event credits, it is topped up to 5,000 at the beginning of the next month.

Essentials-plan Organizations can enable auto-recharge to automatically purchase a set number of event credits when their balance falls below a chosen threshold. They can also configure alerts to notify admins when remaining event capacity falls below a specified threshold. See Understanding Event Credits.

More information is available on our pricing page.

Event Credit

An event credit is the unit used to measure and consume event capacity.

Notehub charges one event credit for:

Each event ingressed (i.e. each event that it receives).
Each megabyte of data uploaded via web transactions.

Platform Events do not consume event credits. All other events do, including events that carry your environment variable changes out to devices.

More information is available on our pricing page.

EventUID

A globally-unique string identifier for a given Notehub event in the following format:

00000000-0000-0000-0000-000000000000

Fleet

An arbitrary, customer-defined grouping of one or more Devices in a Notehub. Fleets can be used to define groups of Devices for uniform management, updates, and more.

FleetUID

A globally-unique string identifier assigned to a fleet, such as the following.

fleet:00000000-0000-0000-0000-000000000000

Host MCU

A Host Microcontroller Unit (or Host MCU) is a Customer programmed and managed device that is used to send requests to and receive responses from a Notecard. The Host MCU is typically the main processor in a Customer product, connects to and controls other sensors, and facilitates communications to and from a connected Notecard.

Journey

A discrete trip—an uninterrupted period during which a device's location is changing—captured by a Notecard's GPS/GNSS location tracking. A journey is made up of the _track.qo Events that share the same journey value, a UNIX Epoch timestamp that marks when the journey started and uniquely identifies it.

Notecard tracks journeys when card.location.mode is set to periodic and tracking is started with card.location.track. A journey begins when the Notecard's accelerometer detects movement, and ends after the device has been stationary for 5 minutes (300 seconds) by default. When the Notecard detects that the device has started moving again, it starts a new journey with a new journey timestamp. You can change the inactivity timeout with the _gps_journey_secs reserved environment variable.

Journeys can be retrieved from Notehub with the Get Device Journeys and Get Device Journey API endpoints.

JSON

JavaScript Object Notation (or JSON) is, according to json.org, "a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate." The Notecard exclusively uses JSON for inbound and outbound communication because it provides a schema-less, human readable, machine parseable format that doesn't add more overhead than needed to network traffic.

JSON objects are stored as Notes in Notefiles, and JSON is also how a host talks to Notecard: each Request and Response is a single line of JSON terminated by a newline (\n). Because a raw newline ends a request, newlines can't appear unescaped inside a request. Use the escaped \n sequence within string values instead.

Note

A JSON object containing a developer-provided body and/or payload, as well as associated metadata managed by the Notecard itself, such as: the time the Note was added, cell tower information, product, and device info.

The body must also be a valid JSON object and is set by sending a note.add request to the Notecard.

{
  "req": "note.add",
  "body": {
    "temp": 24.6875,
    "voltage": 4.99763
  }
}

In addition, if an application has pre-existing binary data that needs to be synchronized, that data can be Base64-encoded and specified as a payload. A Note can contain both a body and payload, if needed.

{
  "req": "note.add",
  "payload": "ewogICAgInRlbXAiOiAyMy4xMzQKfQ=="
}

When added, a Note is annotated with time, location, product, and session data and stored in a Notefile before it is synchronized with Notehub.

Here's an example of the Event Notehub creates when a Note with a custom body syncs, including the metadata Notehub appends:

{
  "event": "df9f5e04-7aa4-44d1-bd7f-068b6b576ffc",
  "session": "6facb2b9-b4af-4790-bc70-a8c3b566c1f3",
  "best_id": "dev:868050040247343",
  "device": "dev:868050040247343",
  "product": "product:com.blues.name:project",
  "app": "app:911ee04e-cd6d-469a-8379-de05062aa5f3",
  "received": 1670791362.736713,
  "req": "note.add",
  "when": 1670790603,
  "file": "data.qo",
  "body": {
    "count": 104,
    "temp": 6.6360182762146
  },
  "best_location_type": "tower",
  "best_location_when": 1670791362,
  "best_lat": 41.83748,
  "best_lon": -89.183298,
  "best_location": "Shorewood Hills WI",
  "best_country": "US",
  "best_timezone": "America/Chicago",
  "tower_when": 1670791362,
  "tower_lat": 41.83748,
  "tower_lon": -89.183298,
  "tower_country": "US",
  "tower_location": "Shorewood Hills WI",
  "tower_timezone": "America/Chicago",
  "tower_id": "310,410,17169,77315594"
}

Note ID

The unique identifier of a Note in a Notefile. For .qi and .qo Notefiles these are system-generated. They are never needed in a request, but may be returned in the response body of some commands, like note.changes. In .db files, where Notes are meant to be long-lived and replicated between the Notecard and Notehub, the identifiers are developer-specified so that specific notes within the .db file can be read, updated and deleted.

For example, when requesting changes from a DB Notefile, like so:

{
 "req": "note.changes",
 "file": "my-settings.db",
 "tracker": "inbound-tracker",
 "start": true
}

The Notes returned are keyed by their Note ID ("setting-one", "setting-two", etc). This Note ID value is also used with the note.delete and note.update requests to delete or update Notes in a DB Notefile.

{
 "changes": 4,
 "total": 4,
 "notes": {
  "setting-one": {
   "body": {
    "foo": "bar"
   },
   "time": 1598918235
  },
  "setting-two": {
   "body": {
    "foo": "bat"
   },
   "time": 1598918245
  },
  "setting-three": {
   "body": {
    "foo": "baz"
   },
   "time": 1598918225
  },
  "setting-four": {
   "body": {
    "foo": "foo"
   },
   "time": 1598910532
  }
 }
}

Notefile

A named JSON file that contains one or more Notes. These files are automatically created when the first Note is added, are persisted to Notecard flash, and are managed by the Notecard's synchronization policies. Notefile names are arbitrary and developers can create multiple Notefiles for an application based on their needs, for example a Notefile for environmental sensor data and a Notefile for actuator readings.

The Notefile extension determines how the file is treated during transport and synchronization, as well as when it is persisted.

Files with the .db extension operate as a database of JSON records that is fully replicated between the Notecard and a Notehub. These files are persisted between syncs and are useful for maintaining configuration and status information relevant to your app.
Files with the .qo extension represent a queue that is considered outbound-only from the Notecard to a Notehub. Notes are added to these files between synchronizations, and are deleted once synchronization to a Notehub is complete.
Files with the .qi extension represent a queue that is considered inbound-only from a Notehub to the Notecard. These files are created on a Notehub and are deleted from the hub once transferred to a Notecard. On the Notecard, inbound Notes remain until the host deletes them (for example, with note.get and "delete": true).
Files with the .dbx extension are local-only databases that are never synced with Notehub.
Files with the .dbs, .qos, and .qis extension are secure variants of the .db, .qo, and .qi types. By default, cellular Notecards in periodic or minimum mode sync over unencrypted sessions to save bandwidth. For sensitive data, however, using these extensions ensures that the data is always sent over encrypted TLS sessions.

NTN (Non-Terrestrial Networks)

Non-terrestrial networks (NTNs) are communication networks that rely on elements located outside the Earth's atmosphere, such as satellites or airborne platforms, to provide internet and telecommunications services, especially in remote or underserved areas. This infrastructure is designed to complement terrestrial networks, extending connectivity to cover a global scale.

NTN Mode

The byte-constrained transport mode Notecard uses to communicate over NTN (satellite), either through a paired Starnote or with Notecard for Skylo. Enable it with the method argument of card.transport, using ntn on its own or as a fallback (for example, cell-ntn).

To keep data usage low, NTN mode works differently than cellular or WiFi:

Notefiles and environment variables must use compact templates.
A bare hub.sync only sends outbound data. Add "in":true to also check for inbound data (see Minimize Unnecessary Data Syncs).

See Understanding NTN Transport Mode to get started.

Organization

A Notehub Organization is the top-level administrative home for a team in Notehub. It sits above projects and devices and is where you manage members, projects, contact information, and your plan and billing details. Organizations were previously called Billing Accounts.

As the billing entity, an Organization groups one or more projects under a single pool of event credits and payment methods. All event charges generated by projects are billed against the Organization they belong to, making it the system of record for pricing, credits, and invoices.

Each project in Notehub belongs to exactly one Organization at any given time, and an Organization may contain multiple projects. Members hold organization-level roles, while people who can access an organization's projects without belonging to the organization itself are surfaced as guests.

Payload

A base64-encoded string of binary data needed by an application. As with a Body, the contents of this object are up to the developer and can include any binary data up to a maximum length of 256 bytes. To send larger binary data, see Sending and Receiving Large Binary Objects.

For example, this binary data:

\x01\x23\x45\x67\x89\xAB\xCD\xEF

Can be encoded and passed like so:

{"payload":"ASNFZ4mrze8="}

Platform Event

An Event from one of the following System Notefiles: _health.qo, _log.qo, _session.qo, _geolocate.qo.

Notecard and Notehub use Platform Events to communicate vital system and administrative information, such as signal strengths and health statuses. Platform Events do not consume event credits when ingested by Notehub.

ProductUID

A Notehub-managed, globally-unique identifier that is used to match Devices with Projects. This string value is specified upon Project creation, must be unique across all Projects on a Notehub, and can be reserved by a Customer in advance. The value is used during a device's auto-provisioning process to find the Notehub Project that will securely manage the device and its data.

When you create a Project, Notehub builds its ProductUID from your email address and a name you choose, for example com.your-company.your-name:your-product. Devices using hub.set with that ProductUID will automatically be assigned to that Project.

Organizations can also reserve a ProductUID prefix that uses the * character as a wildcard, like so:

com.example.*

Once reserved, an individual Project might use a ProductUID like com.example.sensor-v2 for associated devices.

Product SN

A Product Serial Number (or Product SN) is an optional string assigned by a Customer to a Device that enables them to correlate a given DeviceUID to a customer-manufactured product. The Product SN (and ProductUID) may either be assigned to the Notecard using a Request during Notecard initialization by the Host MCU, or may be programmed at the Customer's point of manufacturing by sending a Request on the USB, UART, AUX or I2C interface of the Notecard.

Project

A customer-defined entity that is associated with:

Accounts belonging to a Customer's designated fleet operators and developers.
Fleets containing auto-provisioned Devices.
Routes assigned to fleets which transfer Device Notes to external APIs and Services.

Project Secret

An encrypted, project-scoped key/value pair used to inject credentials into Routes at runtime without storing them in plaintext. Secret names are referenced from Route fields using the [$$SECRET_NAME] placeholder syntax. Values are encrypted at rest in Notehub, decrypted in-memory only at the moment an outbound Route fires, and are never returned by the Notehub API or shown in the UI after they are saved.

See Project Secret Placeholders for full usage details.

ProjectUID

A globally-unique string identifier assigned to a Notehub project, such as the following:

app:00000000-0000-0000-0000-000000000000

The ProjectUID can be found in the Settings tab of a project in Notehub.

RAT

Radio Access Technology (RAT) is the underlying technology that allows devices to connect to a wireless network. It's the framework that governs how data is transmitted and received between a device and the network infrastructure, which includes the access point or cellular tower.

Different Notecards use different types of RATs, such as Cat-1, LTE-M, NB-IoT, GSM, satellite (NTN), LoRa, and WiFi.

Request

In the context of the Notecard, a Request refers to a newline-delimited JSON object that is transmitted to the Notecard from a Host MCU (or a serial terminal connection from a development PC). Every request to the Notecard should take this form:

{"req":"request-type", ...request-fields...}

Where req is provided with every request and request-type corresponds to a valid request name as specified in this guide, and request-fields corresponds to one or more valid key-value pairs specific to a request-type.

Response

In the context of the Notecard, a Response refers to a newline-delimited JSON object that is transmitted from the Notecard to a Host MCU (or a serial terminal connection from a development PC) in response to a Request. Each Request sent with req will cause a single Response, and only a single Request will be outstanding at any given time.

The expected Response object will vary based on the Request type. An empty JSON object {} should be interpreted as a Request acknowledgement, and any Request that results in an error will receive a response that takes the following form:

{"err":"reason-for-error", ...response-fields...}

Route

An external API or Server location that should be forwarded Notes for a Device or Fleet upon receipt. Routes are defined in a Notehub for a Project, and can target all devices or one or more Fleets. A Project can have multiple routes defined and active at any one time.

Learn more about routing data with Notehub.

RouteUID

A globally-unique string identifier assigned to a Notehub route, such as the following:

route:8d65a087d5d290ce5bdf03aeff2becc0

Serial Number

See Product Serial Number.

Session

A Session captures each unique connection between a Notecard and Notehub. Notecard creates a new Session each time it makes a new connection to Notehub, whether in minimum, periodic, or continuous mode.

Each Session provides information about the device, the device's last-known location, the cell tower used (for Cellular Notecards), and the signal strength of the Notecard. This information is available in the Notehub user interface, as well as in the _session.qo Notefile.