Troubleshooting Notecard

This guide provides a systematic approach to troubleshooting Blues Notecard devices and their connectivity to Notehub. It's divided into two parts based on the level of access you have to the device:

• Local Device Troubleshooting: You have a physical serial or USB connection to Notecard (via the In-Browser Terminal, Notecard CLI, or your host MCU) and you can issue any Notecard API request directly.
• Remote Device Troubleshooting: The device is deployed in the field and you have no physical access. You must rely on Notehub's dashboard, environment variables, and system Notefiles like _health.qo and _log.qo to diagnose issues.

Local Device Troubleshooting

When you have direct serial or USB access to Notecard, you can issue API requests and receive responses. This gives you the most complete view of device state and is the fastest way to diagnose issues.

Local: Initial Diagnostics

Start every local troubleshooting session by collecting basic device information, and potentially updating Notecard firmware if yours is out of date.

• Verify Notecard Firmware Version
• Check Device Status
• Validate Notecard's Time

Verify Notecard Firmware Version

Use card.version to identify the Notecard firmware version, capabilities, and SKU:

{"req":"card.version"}

{
 "version": "notecard-11.1.1.17494",
 "device": "dev:861059067916902",
 "name": "Blues Wireless Notecard",
 "sku": "NOTE-NBGLN",
 "ordering_code": "EB0WT1N0AXBA",
 "board": "5.13",
 "cell": true,
 "gps": true,
 "body": {
  "org": "Blues Wireless",
  "product": "Notecard",
  "target": "u5",
  "version": "notecard-u5-11.1.1",
  "ver_major": 11,
  "ver_minor": 1,
  "ver_patch": 1,
  "ver_build": 17494,
  "built": "Dec 8 2025 10:13:37"
 }
}

action

Confirm the device is running the latest Developer release (or a recent LTS release) of Notecard firmware.

Check Device Status

Use card.status to get a summary of the device's current state:

{"req":"card.status"}

For example, check the connected field to determine if the device has an active Notehub session. This also reports USB power status, storage usage, and current time.

{
  "status": "{normal}",
  "usb": true,
  "storage": 8,
  "time": 1599684765,
  "connected": true,
  "cell": true,
  "sync": true,
  "inbound": 60,
  "outbound": 360
}

Validate Notecard's Time

Use card.time to verify the device has a valid time reference:

{"req":"card.time"}

A valid time is essential for proper operation. If time is unavailable, this tells us the device has not yet completed its first successful Notehub connection.

{
  "time": 1599769214,
  "area": "Beverly, MA",
  "zone": "CDT,America/New York",
  "minutes": -300,
  "lat": 42.5776,
  "lon": -70.87134,
  "country": "US"
}

action

If the device is returning an unknown or invalid time, issue a hub.sync request to force a network connection and update the time on the device.

Local: Connectivity Diagnostics

Use these commands to diagnose potential cellular signal issues, verify radio transport and Notehub configuration, and confirm your Notecard's connection status.

• Check Cellular Signal Strength
• Verify Transport Configuration
• Look at Notehub Connection Status
• Validate Notehub Configuration

Check Cellular Signal Strength

If using a cellular-enabled Notecard, use card.wireless to check the cellular radio status and signal quality:

{"req":"card.wireless"}

When reviewing the response, there are some key signal quality metrics to keep in mind:

{
  "status": "{modem-off}",
  "count": 1,
  "net": {
    "iccid": "00000000000000000000",
    "imsi": "000000000000000",
    "imei": "000000000000000",
    "modem": "EG91NAXGAR07A03M1G_BETA0415_01.001.01.001",
    "band": "LTE BAND 2",
    "rat": "lte",
    "rssir": -69,
    "rssi": -70,
    "rsrp": -105,
    "sinr": -3,
    "rsrq": -17,
    "bars": 1,
    "mcc": 310,
    "mnc": 410,
    "lac": 28681,
    "cid": 211150856,
    "updated": 1599225076
  }
}

action

If RSSI is below -85 dBm, the Notecard may struggle to maintain a connection. Consider improving antenna placement or using a different antenna. Poor SINR (i.e. below 0 dB) indicates potential radio interference. See Diagnosing Cellular Connectivity Issues for detailed signal troubleshooting tips.

Verify Transport Configuration

Use card.transport to view the active communication method and its configuration (on Notecards that support more than one radio):

{"req":"card.transport"}

This shows the current transport method, which confirms which radio interface is primary and which are the fallback(s).

{
  "method": "wifi-cell"
}

The method values are ordered by priority, so wifi-cell means WiFi is attempted first and cellular is the fallback.

Note that after falling back, Notecard stays on the fallback transport for the duration set by the seconds argument (3600 by default) before retrying the primary.

action

Read the guide on Connection Retry and Fallback Behaviors for more information.

Look at Notehub Connection Status

Use hub.status to check whether Notecard is actively connected to Notehub:

{"req":"hub.status"}

Check the status and connected fields.

{
  "status": "connected (session open) {connected}",
  "connected": true
}

When the device is not connected, status is typically prefixed with idle and carries the {disconnected} status tag. This is normal between sync intervals in periodic or minimum modes.

{
  "status": "idle {disconnected}",
  "connected": false
}

Validate Notehub Configuration

Verify Notecard's connection configuration with Notehub using hub.get:

{"req":"hub.get"}

The response will show which Notehub project the device is attached to (product) and the sync cadence (mode with outbound and inbound arguments).

{
  "device": "dev:000000000000000",
  "product": "com.your-company.your-name:your_product",
  "mode": "periodic",
  "outbound": 60,
  "inbound": 240,
  "host": "a.notefile.net",
  "sn": "your-serial-number"
}

action

Confirm the product field matches your Notehub project's ProductUID and that mode is correct. For example:

• periodic: Connects at regular intervals (set by outbound/inbound minutes).
• continuous: Maintains a persistent connection. Outbound data still syncs periodically unless a request specifies otherwise.
• minimum: Only syncs when explicitly triggered by a hub.sync request. OTA DFU updates are not available in this mode.
• off: Disables syncing entirely.

Local: Data Flow and Environment

Use these commands to verify sync behavior, test the full Notecard-to-Notehub data path, check Note templates, and inspect local environment variables.

• Sync Status and Forcing a Sync
• Test the Full Pipeline
• Verify Note Templates
• Utilize Health Logging
• Examine Local Environment Variables

Sync Status and Forcing a Sync

Use hub.sync.status to see any pending outbound and/or inbound Notes:

{"req":"hub.sync.status"}

To force an immediate sync:

{"req":"hub.sync"}

After issuing hub.sync, you can repeatedly issue hub.sync.status requests to observe the sync progressing.

action

If the status field contains an error message (e.g., not connected to network or modem not active), this indicates a connectivity issue. Cross-reference with card.wireless to check signal quality.

Test the Full Pipeline

Add a test outbound Note and force a sync to verify the complete data path:

{"req":"note.add","file":"data.qo","body":{"test":true}}

At this point it can be useful to start generating a trace log locally prior to and during the sync to help identify potential issues.

{"req":"hub.sync"}

action

After syncing, verify the test event appears in Notehub under your project's Events tab. If it does not appear, the issue is between the Notecard and Notehub (connectivity). If it does appear, the Notecard-to-Notehub path is working and the issue is likely on the host MCU side.

Verify Note Templates

If your application uses Note templates, verify the template configuration with note.template:

{"req":"note.template","file":"readings.qo","verify":true}

Check the data type values in use. A mismatched template can prevent Notes from being processed correctly.

note

You can also use the Notefile explorer in Notehub to verify that your templates have been applied correctly.

action

If you suspect a data type mismatch, create a new Notefile Template, then retry your note.add operation.

Utilize Health Logging

While not an active troubleshooting step, using custom logging information generated on your device can be useful to create an audit trail in Notehub. Use hub.log to add device health log messages that will be transmitted to Notehub during the next sync via the _health_host.qo system Notefile:

{"req":"hub.log","text":"System status: normal"}

For urgent issues, use the alert flag to mark the message and sync:true to trigger an immediate sync (which also removes the Notecard from certain penalty box states):

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

The response is an empty JSON object {} on success.

action

Use hub.log in your host firmware to surface critical events to Notehub. This creates a remotely visible audit trail in the _health_host.qo Notefile that you can monitor from the Notehub Events tab. This is especially useful for deployed devices where you cannot view local serial output.

Examine Local Environment Variables

If you suspect an issue with an invalid or missing environment variable on the device, you can always read environment variable values with env.get:

{"req":"env.get","names":["monitoring"]}

You can set a default value for a variable locally with env.default. This value applies until overridden by a device, project, or fleet-level setting in Notehub:

{"req":"env.default","name":"monitoring","text":"on"}

Check if variables have been updated since the last check with env.modified:

{"req":"env.modified"}

note

Locally-set environment variables will be overwritten by Notehub values on the next sync if the same variable is defined in Notehub!

Local: Location, Power, and Hardware

Use these commands to troubleshoot GPS and location tracking, check voltage and temperature readings, review attention/wake configuration, and verify host firmware update status.

• Check Location Tracking Mode
• Retrieve Current Location
• Monitor Voltage
• Check Firmware Update Status
• Perform a Factory Reset

Check Location Tracking Mode

If your Notecard is not reporting location data as expected, start by confirming the GPS mode is configured correctly. Check the current GPS configuration with card.location.mode:

{"req":"card.location.mode"}

{
  "mode": "periodic",
  "seconds": 3600,
  "max": 100,
  "lat": 42.5776,
  "lon": -70.87134,
  "minutes": 2,
  "threshold": 4
}

Common modes are periodic (GPS at the interval set by seconds), continuous (always-on), fixed (hardcoded lat/lon), and off (disabled). If live location data is expected, verify the mode is set to periodic or continuous.

note

Notecard cannot use the internal GPS at the same time it has a data connection to Notehub. If both GPS and cellular are configured for high-frequency usage, they may interfere with each other. See Diagnosing GPS Issues for details.

Retrieve Current Location

If the tracking mode looks correct but location data is still missing or stale, check whether the Notecard has an active GPS fix. Retrieve the most recent GPS fix with card.location:

{"req":"card.location"}

{
  "status": "GPS updated (58 sec, 41dB SNR, 9 sats) {gps-active} {gps-signal} {gps-sats} {gps}",
  "mode": "periodic",
  "lat": 42.5776,
  "lon": -70.87134,
  "time": 1598554399,
  "max": 25
}

action

If no fix is available, try moving the device outdoors with a clear sky view and retry. Also confirm a GPS antenna is connected if using an external antenna.

Consider falling back on Cell Tower & WiFi Triangulation as an alternative (if fine-grained location is not required) and consult Diagnosing GPS Issues for additional suggestions.

action

In periodic mode, GPS is only sampled at the seconds interval if Notecard detects motion from its onboard accelerometer. If you’re not seeing new GPS data, try moving a stationary device.

Monitor Voltage

Insufficient power is one of the most common causes of connectivity failures and unexpected behavior. Check the power supply with card.voltage:

{"req":"card.voltage"}

{
  "mode": "normal",
  "value": 3.85
}

The value field is the voltage in volts, and mode reports which threshold bucket that reading falls into (usb, high, normal, low, or dead).

For example, when using a LiPo battery:

action

If voltage is below 3.2V, the Notecard may not have enough power to start the modem. Replace or recharge the battery before continuing troubleshooting. Use a Blues Mojo in your hardware design to continually monitor power draw.

Check Firmware Update Status

If a host firmware update (DFU) was initiated and the device is not behaving as expected, verify whether the update completed successfully. Check current DFU status with dfu.status:

{"req":"dfu.status","name":"user"}

name accepts user (host firmware, the default) or card (Notecard firmware). If you are troubleshooting a Notecard firmware update rather than a host update, request "name":"card" instead.

action

If a DFU has failed, check power stability, connection quality, and that the firmware image is correct for the hardware SKU. Retry the update after resolving any underlying issues.

Perform a Factory Reset

If other troubleshooting steps have not resolved the issue, a factory reset clears most configuration values and returns Notecard to its default state. As a last resort, restore Notecard to factory defaults with card.restore:

{"req":"card.restore","delete":true}

The scope of the reset depends on the arguments you pass:

warning

Every form of card.restore erases pending Notes and stored data. With "delete":true the device will need to be reconfigured afterwards, including setting the ProductUID again before it can sync. Only use this as a last resort!

Remote Device Troubleshooting

When a device is deployed in the field and you cannot physically connect to it, you must use Notehub and Notecard's built-in remote management capabilities. This section covers the tools available for diagnosing issues without direct device access.

Remote: Notehub Diagnostics

The Notehub dashboard is your primary tool for remote troubleshooting. Navigate to your project, locate the device by its DeviceUID, and use the following views.

• Device Summary
• Session History
• Events View
• Route Logs
• Health Monitoring with _health.qo
• Connectivity Analysis with _session.qo

Device Summary

The device overview page shows the device's Location and Last Online time, alongside identifying details like its Device UID, SKU, Ordering Code, IMEI, Product UID, and assigned fleets. This is your starting point for understanding a device's current state.

action

If the device's last connection time is older than expected based on your configured sync interval, the device may be offline. Check voltage and signal trends in _health.qo events to understand why.

Session History

Each time Notecard establishes a new connection with Notehub, it creates a session. The session history shows connection patterns, durations, and errors.

Key things to look for:

• Regular session intervals matching the configured sync mode.
• Unexpected gaps in session history (may indicate power loss or connectivity failure).
• Session duration anomalies (very short sessions may indicate connection instability).
• Session metadata including RAT (Radio Access Technology), Notes received, and bytes used.

action

Compare the actual session frequency against your expected outbound/inbound configuration. If sessions are less frequent than expected, the device is likely struggling to connect. If sessions are more frequent, check for unexpected triggers like host-initiated syncs separate from the sync cadence set in your hub.set request.

Events View

The Events tab shows all events in reverse chronological order.

Check this view for:

• Recent events with expected timestamps and data fields.
• Repeated error events or unusual patterns.
• Errors with routing attempts.
• _health.qo events with health telemetry.
• _session.qo events showing connection/disconnection cycles.

Route Logs

If events reach Notehub but do not appear in your downstream service, check your Route configuration. Notehub provides route logs showing delivery attempts, HTTP status codes, and error messages. Verify the route is enabled, the endpoint URL is correct, and any JSONata transformation expressions are valid.

action

If route logs show HTTP errors (4xx or 5xx), the issue is between Notehub and your downstream service, not the device. Check your endpoint availability and authentication credentials.

Health Monitoring with _health.qo

Notecard automatically sends health telemetry to Notehub via the _health.qo system Notefile. This is one of your most valuable remote troubleshooting tools because it requires no device-side configuration.

Example _health.qo body:

{
  "method": "boot",
  "text": "boot (brown-out & hard reset [17494])",
  "voltage": 4.6992188,
  "voltage_mode": "usb"
}

The method field categorizes the event (boot, dfu, modem, or power), text carries the human-readable detail, and voltage_mode reports the power threshold bucket in effect (usb, high, normal, low, or dead).

To view _health.qo events in Notehub, navigate to your device and filter events by the _health.qo Notefile. Look for trends over time rather than single data points to identify developing issues.

action

Configure a Notehub Route to forward relevant health data to your monitoring system. This can enable automated alerts when voltage drops below a threshold or signal strength degrades.

Connectivity Analysis with _session.qo

Every time Notecard establishes or closes a connection with Notehub, it creates a _session.qo event with detailed connection metadata. Key fields to examine:

action

Consult the Diagnosing Cellular Connectivity Issues guide for antenna and signal troubleshooting steps.

Remote: Logging and Configuration

The _log.qo system Notefile captures diagnostic log messages from Notecard and sends them to Notehub. Unlike _health.qo, logging must be explicitly enabled using the _log reserved environment variable.

• Enabling Remote Logging
• Using a Diagnostic Logging Window
• Viewing _log.qo Events
• Setting Environment Variables in Notehub
• Reserved Environment Variables for Troubleshooting

Enabling Remote Logging

Set the _log environment variable in Notehub (at the device, fleet, or project level) to one of the following values:

You can combine categories with commas, for example modem,power.

To enable logging, go to your device (or fleet) in Notehub, open the Environment tab, and add the _log variable with your desired value. The change takes effect after the next sync.

warning

Remote logging increases cellular data usage. Enable it only when actively troubleshooting, and delete the _log environment variable when done to revert to normal operation.

Using a Diagnostic Logging Window

For intensive remote debugging sessions, combine _log with other reserved environment variables to create a temporary high-frequency logging window:

_session_mins only takes effect in continuous mode, which is why it is paired with _sync_continuous here: it caps how long a single session stays connected before the device reconnects.

warning

This combination provides comprehensive logging data in 15-minute chunks with continuous connectivity. When done, delete all three variables to revert the device to its normal configuration.

Viewing _log.qo Events

In Notehub, filter events by the _log.qo Notefile. Each event body contains a text field with the diagnostic message.

note

Events from _log.qo are Platform Events and do not consume your Notehub event credits.

Setting Environment Variables in Notehub

Environment variables are your primary mechanism for remotely changing device behavior through Notehub without deploying new firmware. You can set environment variables at three levels in Notehub:

• Project level: Applies to all devices in the project.
• Fleet level: Applies to all devices in a specific fleet.
• Device level: Applies only to a single device (overrides project and fleet values).

Changes propagate to the device on its next sync with Notehub.

action

Review this blog post on Remotely Manage Notecards with Reserved Environment Variables for more information on which environment variables to use.

Reserved Environment Variables for Troubleshooting

Notecard recognizes several reserved environment variables that directly control its behavior. These are powerful remote troubleshooting tools:

note

_restart and _restart_host fire when their value is non-zero and different from the value the device saw last, which is why setting them to the current UNIX epoch time is the recommended convention.

warning

Reserved environment variables directly modify device behavior. Always delete temporary troubleshooting variables (like _log, _sync_continuous, _session_mins) when done to avoid unnecessary data usage and battery drain.

Getting Additional Help

If you are unable to resolve an issue using this guide, Blues can always help!

To expedite the troubleshooting process, gather the following information before reaching out.

1. DeviceUID and Notecard firmware version: Available from card.version or from the device page in Notehub.
2. Notecard SKU: The hardware model (e.g., NOTE-NBGL, NOTE-WBNA).
3. Country where the device is located: Cellular coverage varies by region and Notecard SKU.
4. Whether the device uses an external SIM: If so, include the carrier name and APN.
5. Recent session data: Export or screenshot the last several _session.qo events showing signal quality, voltage, and modem data cycles.
6. Health events: Any _health.qo events from the period when the issue started.
7. Remote diagnostic logs: If you enabled _log, include the relevant _log.qo events.
8. Description of the issue: When it started, whether it is intermittent or persistent, and whether a device reset affects it.
9. Host MCU details: The host MCU platform, communication interface (UART, I2C, USB), and a description of the host application behavior.

Support Channels

• Notehub Status Check the current operational status of Notehub services. If multiple devices across different projects are experiencing connectivity issues simultaneously, check here first.
• Blues Community Forum Community Q&A for the entire Blues ecosystem of products and services. The Blues team and community members actively monitor the forum.
• Blues Paid Support Personalized support from Blues offered via phone, email, a dedicated Slack channel, and portal.