homechevron_rightDocschevron_rightAPI Referencechevron_rightSystem Notefiles

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 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:

_button.qo

The _button.qo Notefile is created when Notecard is configured to autonomously report AUX GPIO input changes by using the card.aux API. On subsequent AUX pin state changes, _button.qo Notes will be sent to Notehub.

Depending on the card.aux mode argument in use, the body of the _button.qo Note may contain the following elements:

{
    "power": true,
    "state": [
        {
            "low": true
        },
        {
            "high": true
        },
        {
            "low": true
        },
        {
            "high": true
        }
    ]
}

The "power": true element indicates that USB power is supplied to the Notecard. The state array identifies the state of each AUX pin (in order from 1 to 4) at the time of the recorded GPIO input change.

For more information on the _button.qo Notefile, consult the guide on using the Notecard's AUX pins.

_geolocate.qo

The _geolocate.qo Notefile is created when triangulation is enabled on the Notecard. _geolocate.qo Notes are 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
        },
        ...

Events from the _geolocate.qo Notefile are considered Platform Events, and are not subject to consumption credit charges.

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

Events from the _health.qo Notefile are considered Platform Events, and are not subject to consumption credit charges.

_health_host.qo

_health_host.qo Notes are created on the Notecard when using the hub.log API.

The body element of a _health_host.qo Note will contain the text string provided in the initial hub.log request.

For example, the following request:

{
  "req": "hub.log",
  "text": "something is wrong!",
  "alert": true,
  "sync": true
}

...will result in this body element in the _health_host.qo Notefile in Notehub:

"body": {
  "alert": true,
  "text": "something is wrong!"
}

Events from the _health_host.qo Notefile are considered Platform Events, and are not subject to consumption credit charges.

_log.qo

The _log.qo Notefile is created on a Notecard if you activate debugging with the _log reserved environment variable. The body element of a _log.qo Note contains a text parameter that explains why the event was created. For example:

{"text": "gpsmax: NMEA data being received"}

Events from the _log.qo Notefile are considered Platform Events, and are not subject to consumption credit charges.

_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

A new _session.qo Note is created each time a Session between a Notecard and Notehub begins and ends.

The req element of a _session.qo Note indicates whether the event denotes a session start "session.begin" or end "session.end", and the body element contains a why field that gives more detailed information on why the event was created. For example:

{
  "req": "session.begin",
  "body": {
    "why":"opened: sensors.qo requested sync (sensors.qo)"
  },
  ...
}
{
  "req": "session.end",
  "body": {
    "why": "closed: notecard ended the session"
  },
  ...
}

Additional elements in _session.qo Notes provide more detailed information about the device, the connection, and data usage.

Session Start

The _session.qo Note that denotes a Session start includes the following fields:

  • sku: The SKU of the Notecard that started the Session. See Notecard Product Family for a list of possible SKUs.

  • ordering_code: The Notecard's alphanumeric ordering code.

  • bearer: The tunnel used to connect the device to Packet Data Networks (PDNs).

  • cellid: The Cell ID used when initiating the Session.

  • bssid: The "Basic Service Set Identifier" of the Wi-Fi network used to initiate the Session.

  • ssid: The SSID ("Service Set Identifier"), or name of the Wi-Fi network used to initiate the Session.

  • iccid: The "Integrated Circuit Card Identifier" of the SIM on the device.

  • apn: The "Access Point Name" for Notehub.

  • rssi: The "Received Signal Strength Indicator" value (with 0 being the best possible signal strength).

  • sinr: The "Signal to Interference and Noise Ratio" value (the higher the value the better the signal strength).

  • rsrp: The "Reference Signal Received Power" value (the higher the value the stronger the power).

  • rsrq: The "Reference Signal Received Quality" value (the higher the value the better the signal quality).

  • rat: The "Radio Access Technology" (i.e. the underlying connection method for the cellular network).

  • bars: A general measure of the quality and strength of the cellular connection (with 4 being the highest quality).

  • voltage: The voltage of the attached power source.

  • temp: The temperature (in Celsius) as reported by the Notecard's onboard temperature sensor.

  • moved: A timestamp that indicates the last time motion was detected during this Session.

  • orientation: The physical orientation of the Notecard.

Session End

The _session.qo Note that denotes a Session end includes the following fields:

  • hub_last_work_done: A timestamp that indicates the last time Notehub did work related to this Session.

  • hub_events_routed: The number of events Notehub routed during the Session.

  • hub_rcvd_bytes: The number of bytes Notehub received during the Session.

  • hub_sent_bytes: The number of bytes sent out from Notehub during the Session.

  • hub_tls_sessions: The number of TLS sessions initiated during the Session.

  • hub_sent_notes: The number of Notes sent to Notehub during the Session.

Events from the _session_.qo Notefile are considered Platform Events, and are not subject to consumption credit charges.

_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",

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

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 "triangulated" or "tower" in situations where no GPS/GNSS fix can be made, and the Notecard has a more recent location available.

note

You can learn more about how Notehub selects a best location in Data Notehub Appends to Events.

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 .

  • lux: The illuminance value from an attached OPT3001 ambient light sensor.

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