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.
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
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).
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.
"note": "device_vars", "body": { "_tags": "", "polltime": "30" }
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:
"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:
"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:
{"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 betrue
if you use thecard.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"
, andportrait-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:
"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.
{ "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 totrue
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. Thejcount
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.