homechevron_rightDocschevron_rightAPI Referencechevron_rightGlossary

Glossary

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

Body

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.

Read more about COBS on Wikipedia .

Consumption Credit

A Consumption Credit is a unit of measure used to pay for Notehub services. One Consumption Credit is used for each Event ingested into Notehub. Platform Events do not consume consumption credits.

More information is available on our pricing page .

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.io 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

Every time Notehub sends or receives a Note it creates an event. An event contains the JSON contents of the Note combined with Notehub-appended metadata.

Events can be sent to an external cloud or service using a Route.

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.

JSON

JavaScript Object Notation (or JSON) is, according to json.org a "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 using the Newline Delimited JSON format , which separates each valid JSON object with a line separator \n. Because of this, newline characters (\r and \n) are not allowed in developer-defined JSON bodies.

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 a Note with a custom body and its associated metadata:

{
  "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-de05062aa5r3",
  "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",
  "status": "success"
}

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.
  • Files with the .dbs, .qos, and .qis extension are secure variants of the types enumerated above. By default, communication sessions between a Notecard and Notehub are sent un-encrypted to save bandwidth. For sensitive data, however, using these extensions ensure 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.

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 250 bytes.

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: _geolocate.qo, _health.qo, _health_host.qo, _log.qo, _session.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 Consumption 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.

The ProductUID is an arbitrary string chosen by the customer. Once claimed by a Customer on a Notehub, devices using hub.set with that given ProductUID will automatically be assigned to that Project.

The * character can be used as a wildcard to reserve all ProductUIDs in a namespace, like so:

com.tesla.*

Once reserved, an individual Project might use a ProductUID like com.tesla.model-s.p85d for associated devices.

See also: Finding the ProductUID of a Notehub Project

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.

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, LoRa, and Wi-Fi.

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 from a Host MCU (or a serial terminal connection from a development PC) in response to a Request. Each Request 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 a single Fleet or all devices. 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. The 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 _session.qo Notefile.

SessionUID

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

00000000-0000-0000-0000-000000000000

Signal

A special type of Note designed for low-latency network communication. Signals are sent from Notecard to Notehub, and vice versa, as soon as they are created.

Signals are only supported when a Notecard is in continuous mode.