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 WiFi 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 event 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 event credit charges.

note

Troubleshooting brown-out & hard reset events: A brown-out & hard reset in _health.qo means the Notecard lost power unexpectedly.

Do not repeatedly power-cycle or reset Notecard to save power. Notecard is designed to be continuously powered. Its idle draw is already very low, and power-cycling it at runtime incurs a startup cost (i.e. re-registering with the network, reacquiring time, etc.) that dwarfs any power savings. Leave VIO powered at all times.

If you're seeing brown-out & hard reset events unexpectedly, ensure your power supply meets the peak current requirements during modem transmit. See the Power Information section of your Notecard's datasheet for voltage and current specifications.

_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!"
}

_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 event 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". The body element contains exactly three possible fields:

  • why: A string giving more detailed information on why the event was created. Present on both session.begin and session.end.

  • opened: true on a session.begin event. Absent otherwise.

  • closed: true on a session.end event. Absent otherwise.

For example:

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

Common why Values

The why string reports why a Session was opened or closed.

For session.begin events, a single Session can be opened for several reasons at once. Reasons are joined with a semicolon followed by a space. If the Session was triggered by pending changes in one or more Notefiles, the Notefile names are appended in parentheses, separated by spaces — for example explicit sync request; periodic outbound sync due (sensors.qo _health.qo). The parenthesised list is omitted until the Notecard has completed its first sync.

Common session.begin reasons include:

  • <notefile>.qo requested sync (or N files requested sync) — One or more outbound Notefiles contain pending Notes that were added with "sync": true.
  • explicit sync request — The host issued a hub.sync request.
  • modified — Notefiles were modified, with no other trigger. Reported when the parenthesised Notefile list is the only reason for the Session.
  • first sync — The Notecard's first sync after a restart or factory reset.
  • continuous connection mode — The Notecard is in continuous mode and has established (or re-established) its connection to Notehub.
  • periodic inbound sync due / periodic outbound sync due — A scheduled sync from the Notecard's inbound / outbound interval in hub.set has come due.
  • web requests — A pending web.* request needs to be transmitted.
  • excessive pending changes in notefile — A Notefile accumulated enough pending changes to force a sync ahead of its normal interval.
  • file system full — Storage pressure forced the Notecard to drain pending Notes.
  • TIME — The Notecard needs to set its clock.
  • GPS / need gps refresh — GPS/GNSS work requires the network, or the current fix is stale.
  • DFU check / firmware update work is due / firmware image is ready to install — Firmware update work is pending.

Common session.end reasons include:

  • notecard ended the session — The Notecard closed its side of the connection normally (the most common reason).
  • notehub determined that the notecard session has ended — Notehub detected that the Notecard is no longer present on the session.
  • session closed because the notecard has opened a newer session — The Notecard reconnected and Notehub closed the old session in favor of the new one.
  • device has been administratively disabled — The device was disabled in Notehub.

A session.end why can also carry a transport error, such as notehub error reading request: wire read: can't read version, when the Session ended abnormally.

For Notecard for LoRa and Starnote devices, the Session itself is a Notehub-side construct: a _session.qo Note is created when there is new activity from the device, and the Session is then automatically closed after a period of inactivity. There is no explicit "open session" request for these device types — the next outbound Note or inbound delivery from the device starts a new Session.

Session Fields

Beyond req and body, a _session.qo event carries a set of fields describing the device and its connection at the time of the Session. Which fields are present depends on whether the event denotes a Session start or a Session end, and on the Notecard itself — a field is omitted when it does not apply, so the cellular signal fields are absent on a Notecard for WiFi, and the WiFi fields are absent on a cellular Notecard.

All of the fields documented below sit at the top level of the event, alongside req, and not inside body.

Session Start

The _session.qo Note that denotes a Session start includes the following fields. All of them are absent from session.end events.

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

  • firmware_notecard: The version of the Notecard firmware. This is read from Notehub's record of the device rather than from the Session handshake, so it reflects what Notehub understands to be installed and may briefly lag a just-completed firmware update.

  • firmware_host: The version of the host firmware, as last reported by the host. Empty if the host has never reported a version.

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

  • cellid: The Cell ID used when initiating the Session, formatted as mcc,mnc,lac,cellid. Notehub derives the event's tower_* fields from this value.

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

  • ssid: The SSID ("Service Set Identifier"), or name of the WiFi 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, in dBm. Values are negative, so a value closer to 0 indicates a stronger signal.

  • sinr: The "Signal to Interference and Noise Ratio" value, in dB (the higher the value the better the signal quality).

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

  • rsrq: The "Reference Signal Received Quality" value, in dB (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. Absent on Notecards without one.

  • moved: A timestamp that indicates the last time motion was detected by the Notecard. This is not scoped to the Session — it reports the most recent motion the Notecard is aware of, which may predate the start of the Session.

  • orientation: The physical orientation of the Notecard.

  • power_charging: true if the Notecard detected that its power source was charging.

  • power_usb: true if USB power was detected.

  • power_primary: true if the Notecard is configured for a primary (non-rechargeable) battery.

  • power_mah: The cumulative milliamp-hours the Notecard estimates it has consumed. This value only increases over the life of the device, so compare two Sessions to get consumption over an interval.

Session End

The _session.qo Note that denotes a Session end includes the following fields. All of them are reported by Notehub, not by the Notecard, and all are absent from session.begin events.

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

  • hub_duration_secs: The duration of the Session in seconds. Only present when it differs from the duration Notehub has already recorded for the Session, so this field is frequently absent.

  • 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_tcp_sessions: The number of TCP sessions initiated during the Session.

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

  • hub_rcvd_notes: The number of Notes received during the Session — the inbound counterpart to hub_sent_notes.

  • 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 event credit charges.

_temp.qo

If you enable periodic temperature reporting using a card.temp request with a minutes (or status) argument, Notecard will create a templated _temp.qo Notefile and add a Note to it at the specified interval.

Here is an example body of a _temp.qo Note.

{
  "count": 46,
  "temperature": 24.457228,
  "voltage": 5.1953125
}

The body of a _temp.qo Note may contain the following elements:

  • temperature: A temperature reading in Celsius. By default this is taken from the Notecard's onboard temperature sensor.

  • voltage: The measured voltage at the time of the reading.

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

  • count: An incrementing counter of the number of _temp.qo readings taken since the Notecard last began reporting.

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

If you have a BME280 sensor on the I2C bus and are using card.aux track mode, the Notecard will add humidity, pressure, and sn fields to the body of _temp.qo Notes.

  • humidity: A humidity reading from the connected BME280 sensor, taken at the time of the reading.

  • pressure: An atmospheric pressure reading from the connected BME280 sensor, in pascals, taken at the time of the reading.

  • sn: The serial number (ID) of the attached BME280 sensor.

note

To immediately sync any pending _temp.qo Notes, send a card.temp with "sync": true. To stop temperature reporting, send a card.temp request with "stop": true.

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

note

Journey lifecycle: A journey begins when the Notecard's accelerometer detects motion while card.location.track is enabled. A journey ends after the device has been stationary—no accelerometer motion detected—for 5 minutes (300 seconds) by default. The next motion event after that timeout starts a new journey with a new journey timestamp. You can change the inactivity timeout by setting the _gps_journey_secs environment variable on the device in Notehub (for example, _gps_journey_secs=600 extends the timeout to 10 minutes).

The journey is a reliable key for grouping _track.qo Notes into discrete trips: all Notes that share the same journey value belong to the same uninterrupted period of motion.

If you have a BME280 sensor on the I2C bus, Notecard will add temperature, pressure, and humidity fields to the body of _track.qo Notes.

  • temperature: A temperature reading from the connected BME280 sensor, in Celsius, taken at the time of the tracking event.

  • humidity: A humidity reading from the connected BME280 sensor, taken at the time of the tracking event.

  • pressure: An atmospheric pressure reading from the connected BME280 sensor, in pascals, taken at the time of the tracking event.

If you have an ENS210 sensor on the I2C bus, Notecard will add temperature and pressure fields to the body of _track.qo Notes.

  • temperature: A temperature reading from the connected ENS210 sensor, in Celsius, taken at the time of the tracking event.

  • pressure: An atmospheric pressure reading from the connected ENS210 sensor, in pascals, taken at the time of the tracking event.