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.

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]}}

Customer

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

Developer

See, Customer

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.

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. A Device may only belong to a single fleet at a time.

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

COPY
{
  "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.

COPY
{
  "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, payload, and its associated metadata:

{
  "body": {
    "temp": 24.6875,
    "voltage": 4.99763
  },
  "payload": "ewogICAgInRlbXAiOiAyMy4xMzQKfQ==",
  "req": "note.add",
  "when": 1591213144,
  "routed": 1591232138,
  "file": "data.qo",
  "tower_country": "US",
  "tower_location": "Beverly, MA",
  "tower_timezone": "America/New York",
  "tower_lat": 42.577600,
  "tower_lon": -70.871340,
  "tower_id": "310,410,28681,211474960",
  "device": "dev:00000000000000",
  "product": "product:com.veritas.cooler",
  "session": "9a55b550-31e4-492d-9dfb-959f3b363853",
  "event": "3be4d522-0172-4da6-95d2-1338dfd081b9",
  "reply": "http://api.notefile.net:80/req?product="product:com.veritas.cooler"&device="dev:000000000000000"",
  "tls": true
}

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.

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="}

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.

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.

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.