System Notefiles

A Notefile is a JSON file that contains one or more Notes. Notefiles can be created either on the Notecard or on Notehub, and then may be automatically synced with the other party.

System Notefiles are created automatically on the Notecard and/or on Notehub and, with the exception of _env.dbs, can be synced with a cloud application using Notehub Routes.

warning

System Notefiles names always start with an underscore ("_"). Therefore we recommend avoiding the use of underscores at the beginning of custom Notefile names in order to eliminate the possibility of a conflict.

Also, the structure of System Notefiles is not consistent and subject to change without notice, so we don't advise building app-level functionality around specific data elements.

This reference covers the following System Notefiles:

• _env.dbs
• _geolocate.qo
• _health.qo
• _motion.qo
• _session.qo
• _track.qo

_env.dbs

The _env.dbs Notefile is a .dbs (secure database) Notefile that is used to sync environment variables and other coordination data between the Notecard and Notehub (most notably for DFU).

note

Instead of inspecting the body element of _env.dbs, we recommend using the env API to set and retrieve environment variables.

The body element of _env.dbs in Notehub contains detailed information about the specific data being synced, and may include the scope of any environment variables in the note parameter:

• device_vars are device-level environment variables.
• fleet_vars are fleet-level environment variables.
• project_vars are project-level environment variables.
• _state_vars_net includes details about the radio in use on the Notecard.

COPY
"note": "device_vars",
"body": {
    "_tags": "",
    "polltime": "30"
}

note

Unlike other System Notefiles, _env.dbs cannot be routed. However, individual environment variables can be routed by using JSONata and the $ variable syntax. Consult the Using JSONata to Transform JSON guide for more details.

_geolocate.qo

The _geolocate.qo Notefile is created when triangulation is enabled on the Notecard. _geolocate.qo Notes are not actually created on the Notecard - they are Notes created by Notehub when it triangulates the Notecard's location based on data submitted during the connection of a new session.

The data elements in a _geolocate.qo Notefile include detailed information about the location of the Notecard, including the "best" location data, which is Notehub's calculation of which location is most accurate between GPS, triangulation, and cell tower locations. For example:

COPY
"best_location_type": "triangulated",
"best_location_when": 1665334721,
"best_lat": 42.52201,
"best_lon": -70.907806,
"best_location": "Salem MA",
"best_country": "US",
"best_timezone": "America/New_York",

Likewise, the triangulate parameter in the _geolocate.qo Notefile contains an array of cell towers and/or Wi-Fi SSIDs used for the triangulation request. For example:

COPY
"triangulate": {
    "cellTowers": [
        {
            "cellId": 229037316,
            "locationAreaCode": 22003,
            "mobileCountryCode": 311,
            "mobileNetworkCode": 490,
            "psc": 344,
            "radioType": "lte",
            "signalStrength": -100,
            "time": 1665334721
        },
        ...

_health.qo

_health.qo Notes are created on the Notecard to record significant health-related events (e.g. errors or hard faults) that may occur on the Notecard.

The body element of a _health.qo Note contains the text parameter that explains the details of why the event was created. For example:

COPY
{"text":"boot (brown-out & hard reset [15117])"}

The number in brackets represents the build number of the Notecard's firmware version. Other information in _health.qo Notefiles may contain diagnostic data that can be useful for Blues technical support if they need to help debug an issue.

_motion.qo

If you activate the Notecard's motion tracking using card.motion.sync or card.motion.track requests, the Notecard will create a _motion.qo Notefile to store motion data.

The fields in the body of _motion.qo Notes provide information about the motion event.

• alert: A boolean that indicates whether the Notecard immediately performed a sync of this Note. This will be true if you use the card.motion.sync request to set up automatic synching based on Notecard movement.

• motion: The number of times the Notecard detected motion since the previous _motion.qo Note.

• movements: A string of base-36 characters, where each character represents the number of movements in a "bucket" during the sample duration. Each character will be a digit 0-9, A-Z to indicate a count of 10-35, or * to indicate a count greater than 35. For details, see Retrieving Motion Results Over a Time Period.

• orientation: A string that represents the orientation of the Notecard in space. Possible values are "face-up", "face-down", "landscape-right, "landscape-left, "portrait-up", and portrait-down. See Motion Monitoring for details.

• temperature: A temperature reading from the Notecard, in Celsius, at the time of the motion event.

• tilt: The number of orientation changes detected since the previous _motion.qo Note.

• voltage: The measured voltage at the time of the motion event.

_session.qo

The _session.qo Notefile is created each time the Notecard makes a new connection to Notehub - whether in minimum, periodic, or continuous mode.

The body element of a _session.qo Note contains the why parameter that explains the reason the event was created. For example:

COPY
"why": "first sync; continuous connection mode (TLS)"

Additional elements in _session.qo provide information about the device, the device's last known location, the cell tower used, and the signal strength of the cellular connection. These data elements are documented in the Notehub Fleet Administrator's Guide and can also be mapped to data elements found in the "Get Sessions" Notehub API.

_track.qo

If you activate the Notecard's GPS/GNSS tracking using a card.location.track request, the Notecard will create a _track.qo Notefile to store location data.

Here is an example _track.qo Note.

COPY
{
    "body": { ... },

    "best_location_type": "gps",
    "best_olc": "86JQQ972+FQ2H",
    "best_when": 1674749529,
    "best_lat": 42.2636375,
    "best_lon": -84.24809765624,
    "best_location": "Lansing MI",
    "best_country": "US",
    "best_timezone": "America/Detroit",

    "tower_when": 1674749229,
    "tower_lat": 42.839274,
    "tower_lon": -84.9275739,
    "tower_country": "US",
    "tower_location": "Waverly MI",
    "tower_timezone": "America/Detroit",
    "tower_id": "310,410,1034,15892745",

    "where_olc": "86JQQ972+FQ2H",
    "where_when": 1674749529,
    "where_lat": 42.2636375,
    "where_lon": -84.24809765624,
    "where_location": "Lansing MI",
    "where_country": "US",
    "where_timezone": "America/Detroit",
}

In a _track.qo Note, the where_* fields provide location information acquired by the Notecard's GPS/GNSS receiver, and the tower_* fields provide location information from the cell tower that received the event.

The Note's best_location_type will be set to the device's most accurate location, which will be "gps" if the Notecard has made a recent GPS/GNSS fix, and "tower" in rare situations where no GPS/GNSS fix can be made, and the Notecard receives an updated tower location. The remaining best_* fields are populated according to the best_location_type.

All _track.qo Notes provide additional information about each tracking event in their body.

• dop: The dilution of precision for the reading, where lower numbers indicate higher confidence.

• motion: The number of motion events captured since the previous _track.qo Note.

• seconds: The integer number of seconds that have elapsed since the previous tracking event.

• temperature: A temperature reading from the Notecard, in Celsius, at the time of the tracking event.

• time: The UNIX Epoch timestamp that indicates the last time the Notecard made a GPS/GNSS fix.

• usb: A boolean that is set to true if the Notecard was powered by a USB connection at the time of the tracking event.

• voltage: The measured voltage at the time of the tracking event.

If you set card.location.mode to "mode": "continuous", or you set card.location.mode to "mode": "periodic" with a "seconds" that is less than 300, the Notecard additionally tracks journeys. When tracking journeys, the Notecard captures additional information in the body of _track.qo Notes.

• bearing: The compass bearing from absolute north, in degrees, relative to the previous tracking event's coordinates.

• distance: The distance between the current location and the previously reported location, as the crow flies, in meters.

• jcount: The number of GPS/GNSS location updates that have occurred in the current journey. The jcount field starts at 1.

• journey: A UNIX Epoch timestamp that indicates when the journey started. This timestamp uniquely identifies the journey and will used in subsequent _track.qo Notes if the journey continues.

• velocity: A calculation of the speed the Notecard has traveled at since the previous tracking event, determined by dividing distance traveled (as the crow flies) by time, and measured in meters per second.