--- title: System Notefiles description: System Notefiles are created on Notehub in response to system events and can be routed. source_url: https://dev.blues.io/api-reference/system-notefiles/ canonical_url: https://dev.blues.io/api-reference/system-notefiles/ markdown_url: https://dev.blues.io/api-reference/system-notefiles.md --- # System Notefiles A [Notefile](https://dev.blues.io/api-reference/glossary.md#notefile) is a JSON file that contains one or more [Notes](https://dev.blues.io/api-reference/glossary.md#note). 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](https://dev.blues.io/notehub/notehub-walkthrough.md#routing-data-with-notehub). > **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`](https://dev.blues.io/api-reference/system-notefiles.md#button-qo) - [`_geolocate.qo`](https://dev.blues.io/api-reference/system-notefiles.md#geolocate-qo) - [`_health.qo`](https://dev.blues.io/api-reference/system-notefiles.md#health-qo) - [`_health_host.qo`](https://dev.blues.io/api-reference/system-notefiles.md#healthhost-qo) - [`_log.qo`](https://dev.blues.io/api-reference/system-notefiles.md#log-qo) - [`_motion.qo`](https://dev.blues.io/api-reference/system-notefiles.md#motion-qo) - [`_session.qo`](https://dev.blues.io/api-reference/system-notefiles.md#session-qo) - [`_temp.qo`](https://dev.blues.io/api-reference/system-notefiles.md#temp-qo) - [`_track.qo`](https://dev.blues.io/api-reference/system-notefiles.md#track-qo) **Ask Your Product Questions in Plain Language** Try Notehub IQ, our new intelligence layer for Notehub that you can use from your own AI agent. [Learn more about Notehub IQ →](https://dev.blues.io/notehub/notehub-walkthrough.md#notehub-iq) [Video: System Notefiles](https://www.youtube-nocookie.com/embed/dRq3BuDcP6M) ## \_button.qo The `_button.qo` Notefile is created when Notecard is configured to autonomously report [AUX GPIO input changes](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-aux1-aux2-aux3-and-aux4) by using the [card.aux API](https://dev.blues.io/api-reference/notecard-api/card-requests/latest.md#card-aux). 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: ```json { "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](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-aux1-aux2-aux3-and-aux4). ## \_geolocate.qo The `_geolocate.qo` Notefile is created when [triangulation](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#using-cell-tower-and-wifi-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: ```json "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: ```json "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](https://dev.blues.io/api-reference/glossary.md#platform-event), and are not subject to [event credit](https://dev.blues.io/notehub/notehub-walkthrough.md#understanding-event-credits) 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: ```json {"text":"boot (brown-out & hard reset [15117])"} ``` The number in brackets represents the build number of the [Notecard's firmware version](https://dev.blues.io/notecard/notecard-firmware-releases.md). 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](https://dev.blues.io/api-reference/glossary.md#platform-event), and are not subject to [event credit](https://dev.blues.io/notehub/notehub-walkthrough.md#understanding-event-credits) 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](https://dev.blues.io/datasheets/notecard-datasheet.md) for voltage and current specifications. ## \_health\_host.qo `_health_host.qo` Notes are created on the Notecard when using the [hub.log API](https://dev.blues.io/api-reference/notecard-api/hub-requests/latest.md#hub-log). 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: ```json { "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: ```json "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](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md#reserved-environment-variables). The `body` element of a `_log.qo` Note contains a `text` parameter that explains why the event was created. For example: ```json {"text": "gpsmax: NMEA data being received"} ``` Events from the `_log.qo` Notefile are considered [Platform Events](https://dev.blues.io/api-reference/glossary.md#platform-event), and are not subject to [event credit](https://dev.blues.io/notehub/notehub-walkthrough.md#understanding-event-credits) charges. ## \_motion.qo If you activate the Notecard's motion tracking using [`card.motion.sync`](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-motion-sync) or [`card.motion.track`](https://dev.blues.io/api-reference/notecard-api/card-requests.md#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](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md#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"`, `"portrait-down"`, and `"angled"` (tilted, but not clearly in any of the other orientations). See [Motion Monitoring](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md#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](https://dev.blues.io/api-reference/glossary.md#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: ```json { "req": "session.begin", "body": { "opened": true, "why": "sensors.qo requested sync (sensors.qo)" }, ... } ``` ```json { "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: - `.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`](https://dev.blues.io/api-reference/notecard-api/hub-requests/latest.md#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`](https://dev.blues.io/api-reference/notecard-api/hub-requests/latest.md#hub-set) has come due. - `web requests` — A pending [`web.*`](https://dev.blues.io/api-reference/notecard-api/web-requests/latest.md) 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](https://dev.blues.io/api-reference/notehub-api/device-api.md#disable-device) 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](https://dev.blues.io/lora.md) and [Starnote](https://dev.blues.io/starnote.md) 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](https://dev.blues.io/notecard/notecard-product-family.md) 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](https://en.wikipedia.org/wiki/GSM_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](https://dev.blues.io/api-reference/glossary.md#platform-event), and are not subject to [event credit](https://dev.blues.io/notehub/notehub-walkthrough.md#understanding-event-credits) charges. ## \_temp.qo If you enable periodic temperature reporting using a [card.temp request](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-temp) 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. ```json { "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](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-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](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-location-track), the Notecard will create a `_track.qo` Notefile to store location data. Here is an example `_track.qo` Note. ```json { "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](https://dev.blues.io/notehub/notehub-walkthrough.md#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](https://en.wikipedia.org/wiki/Dilution_of_precision_\(navigation\)#Interpretation). - `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 `humidity` 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. - `humidity`: A humidity reading from the connected ENS210 sensor, taken at the time of the tracking event.