Diagnosing Satellite Connectivity Issues

Satellite (NTN) connectivity is generally less ubiquitous and less forgiving than cellular or WiFi. For that reason, this guide should be treated as a development/testing checklist for ensuring reliable satellite communication for your product.

This guide covers all three Blues satellite products: Starnote for Skylo, Notecard for Skylo, and Starnote for Iridium. Several requirements differ by product and network, so start with "Identify Your Satellite Setup" and carry that answer through the rest of the guide.

tip

Most satellite connectivity issues can be traced to a single missed setup step, e.g. a device that has not yet synced with Notehub over cellular or WiFi, a Notefile without a template, or a device tested only indoors.

• Identify Your Satellite Setup
• Verify Notecard and Starnote Firmware
• Confirm an Initial Sync Over Cellular or WiFi
• Get a Clear View of the Sky
• Confirm Satellite Coverage
• Verify Notefile Templates
• Provide a Valid Location for Skylo
• Read Notecard Satellite Diagnostics
• Other Issues and Solutions

Identify Your Satellite Setup

Blues offers satellite (NTN) connectivity across three products on two different networks, and the requirements are not interchangeable. Nearly every section in this guide depends on knowing which product you are using:

If you're still choosing between networks, see Choosing Between Skylo and Iridium.

Notecarrier Requirements

Both Starnote products use the same M.2 connector as Notecard, but the position of the mounting hole means they will not mount on Notecarriers built for Notecards alone.

• Starnote for Skylo requires either a Notecarrier XS or a 6-pin JST connector to connect to a paired Notecard. The XS has labeled sockets for both a Starnote and a Notecard, and both the Ignion-antenna and u.FL variants of Starnote for Skylo fit it.
• Starnote for Iridium requires a Notecarrier XI and is not intended for use with any other Notecarrier. The XI carries the supercapacitors that feed the Iridium modem during transmit bursts.
• Notecard for Skylo has no such Notecarrier requirements. Because its satellite radio is integrated, it works on its own in any Blues Notecarrier.

Don't Mix Integrated and External NTN

Notecard for Skylo already has a satellite radio, so it should never be paired with a Starnote. If you send an ntn.status request to a Notecard for Skylo, you'll get an error rather than a status, because that request reports on a paired external module:

{"err":"no NTN module is connected {no-ntn-module}"}

On a Notecard for Skylo this response is expected and is not a fault. On a Notecard that is supposed to have a Starnote attached, the same response means the Starnote isn't being detected — see Other Issues and Solutions.

Verify Notecard and Starnote Firmware

Improvements to satellite support land in nearly every Notecard and Starnote firmware release. Before spending time on deeper diagnosis, rule out a bug that has already been fixed. We highly recommend updating your Notecard and Starnote devices to the latest releases (LTS or Developer verions).

If you're using a Starnote, note that Notecard and Starnote carry separate firmware, and each is checked and updated its own way. Updating one does not update the other.

Checking Notecard Firmware

Check what Notecard is running with card.version:

{"req":"card.version"}

Compare the result against Notecard Firmware Releases — the latest LTS release for production deployments, or the latest Developer release for the newest features and fixes.

note

Notecard for Skylo is updated as a Notecard, not as a Starnote. Its satellite radio is integrated, so there is no separate Starnote firmware and the Notecard releases page is the only one you need.

Checking Starnote Firmware

A card.version request sent to Notecard reports only Notecard's own firmware version, it does not tell you anything about the firmware on a paired Starnote.

To read a Starnote's version, you have to talk to the Starnote itself:

1. Connect a serial terminal application (for example CoolTerm or Tera Term) directly to your Starnote over UART, configured for 115200 8N1 — 115200 baud, 8 bit data, no parity, 1-bit stop bit.

2. Issue a card.version request over that connection. The version field in the response identifies the device as a Starnote:

   COPY

   {"req":"card.version"}

   COPY

   "version":"starnote-11.2.1.17584"

Compare that against Starnote Firmware Releases, which includes binaries for both Starnote for Skylo and Starnote for Iridium.

Confirm an Initial Sync Over Cellular or WiFi

note

This is the single most common cause of satellite connectivity failures!

Blues satellite products will not function until a non-NTN (cellular or WiFi) connection has first been established with Notehub. That initial sync is what registers the device with your Notehub project and uploads your Notefile templates.

Verify the Sync Happened

Ask Notecard whether it has ever synced, using the hub.status and hub.sync.status APIs:

{"req":"hub.status"}

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

Then confirm the device appears in your Notehub project's Devices page and has at least one event on the Events page. If the device isn't in Notehub at all, it has never completed a sync, and no amount of satellite troubleshooting will help until it does.

To force the sync, put the device somewhere with working cellular or WiFi, set a terrestrial transport, and sync:

{"req":"card.transport","method":"cell"}

{"req":"hub.sync"}

Wait for the sync to complete before switching back to a satellite transport.

warning

Watch for a sync that is still in progress. If you switch transports or trigger an NTN sync while cellular or WiFi work is still pending, the satellite attempt can fail for reasons that have nothing to do with satellite. Confirm the response from hub.sync.status reports the sync has completed.

Re-sync After Any Template Change

The initial sync isn't a one-time box to tick. Any time you create or change a Notefile template, you must sync over cellular or WiFi again before that template can be used over satellite. This includes changes as small as editing a port number.

Re-sync After Physically Attaching a Starnote

If you're using either Starnote product, perform a cellular or WiFi sync after physically connecting Starnote to your Notecard, and let that sync finish before switching to NTN mode. Pairing information is exchanged during that sync.

tip

These settings persist across restarts. Once a template is created and synced over cellular or WiFi, the configuration is saved on the device. A Notecard or Starnote reboot does not require you to re-sync, only a template change does.

Also, be aware that a Starnote can only be paired with one Notecard at a time, and the association is fixed until it is manually reset on the original Notecard. See Pairing Starnote with a Different Notecard for more information.

Get a Clear View of the Sky

NTN connectivity needs line-of-sight to satellites in the sky. Unlike cellular, there is no reflected or indirect path to fall back on, so an indoor test will not work, and testing near a window is usually not enough either.

Move the device outdoors, away from buildings, tree cover, vehicles, and metal structures. Keep the satellite antenna clear of anything that would shadow it, and away from metal surfaces that can detune it.

Where to Point

Skylo (both Starnote for Skylo and Notecard for Skylo) uses geostationary satellites parked above the equator. They don't move relative to your device, so you either have line-of-sight or you don't:

• In the northern hemisphere, you need an unobstructed view of the southern sky.
• In the southern hemisphere, you need an unobstructed view of the northern sky.

Because the target never moves, Skylo is comparatively forgiving of partial sky view, meaning a device on a wall or window sill can work as long as the view toward the equator is clear.

Iridium uses a low Earth orbit constellation in constant motion, and the satellite in view at any moment is usually low on the horizon rather than overhead. Starnote for Iridium therefore needs a more open view of the sky in multiple directions than Skylo does. A device tucked against a wall may have to wait for a well-positioned satellite to pass.

Give It Time

Satellite connections are slow to establish, and a test abandoned too early looks identical to a failure. The satellite modem is given a bounded window:

Plan on several minutes per attempt, especially on a device's first-ever satellite transmission. For the full retry and fallback algorithm, see Connection Retry and Fallback Behaviors.

Confirm Satellite Coverage

Skylo: Regional Coverage

Skylo is available in a growing set of supported regions, but it is not global and coverage is not uniform worldwide. If your device is outside a supported region, no satellite connection is possible.

Check your deployment location(s) against Skylo's coverage map before troubleshooting further.

Iridium: Global Coverage

Iridium provides truly global, pole-to-pole coverage: land, sea, air, and polar regions. If you're using Starnote for Iridium, coverage is not the limiting factor and there is no map to consult.

Verify Notefile Templates

All data sent over satellite must use a templated, compact Notefile. This can catch developers by surprise, because the failure is quiet as the note.add request succeeds, the sync appears to run, and yet no no event ever arrives in Notehub.

Notes queued without a Notefile template will never sync in NTN mode.

What an NTN-Compatible Template Requires

1. A .qo, .qos, .qi, or .qis extension. .db and .dbs Notefiles are not supported over NTN.
2. Both "format":"compact" and a "port" value between 1 and 100.

{"req":"note.template","file":"sat.qo","format":"compact","port":55,"body":{"temp":14.1,"humidity":14.1}}

Remember that defining a template is only half the job, as it must then be synced over cellular or WiFi before it can be used over satellite. See Confirm an Initial Sync Over Cellular or WiFi.

Check What Template is Actually Set

Rather than assuming, ask Notecard what template it currently holds for a Notefile by passing "verify":true in a note.template request:

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

Confirm the response comes back with the format and port you expect. If it returns no template, or a template without "format":"compact" and a port, that Notefile will not sync over satellite.

Separately, you can also confirm that this template matches what Notehub has stored for your project. In Notehub, open your device, select the Notefiles tab, find the Notefile in question, and view its template. If Notehub shows no template, or one that differs from what Notecard reports, the template hasn't been successfully synced yet, and Notes sent over satellite won't be decoded as you expect.

Check Your Packet Sizes

A Note that exceeds the network's maximum packet size is not transmitted, is ignored by the satellite network, and the Note is deleted. This is silent data loss, so it's worth checking your template against the limits.

Packets smaller than the minimum are billed at the minimum, and billing is based on packet size. See Optimize Use of Compact Templates for how to get the most out of each byte.

If You're Adding to Non-Compact Notefiles

By default, Notecard refuses to add Notes to a non-compact Notefile while connected over NTN, to keep the device from filling with data it cannot send. The attempt returns:

{"err":"'port' is only supported for a 'format' of 'compact'"}

If that error is what brought you here, it's working as designed. To allow it anyway, pass "allow":true to card.transport:

{"req":"card.transport","allow":true}

warning

If your templates use "delete":true, be aware that before every sync Notecard clears the queues that don't match the active transport: on a cellular or WiFi connection all NTN-compatible Notefiles are cleared, and on a satellite connection all non-NTN-compatible Notefiles are cleared. If Notes are disappearing without being sent, check whether delete is doing this intentionally.

The full set of patterns for splitting data across transports is covered in Define NTN vs non-NTN Templates.

Provide a Valid Location for Skylo

This section applies to Skylo hardware only (Notecard for Skylo and Starnote for Skylo). Skylo devices must know where they are before they can find an overhead satellite, so a device with no location will not connect.

Skylo hardware will determine its own location using its GPS/GNSS module during its first transmission, but that acquisition is slow — it's why the connection window extends from 120 to 900 seconds when the location is unknown. Providing a location up front removes that delay.

Option A: Fixed Location (Recommended for Testing)

A fixed location lets Notecard skip GPS acquisition entirely, which makes iterating much faster.

1. Look up the precise latitude and longitude of your test location, and set it with card.location.mode:

   COPY

   {"req":"card.location.mode","mode":"fixed","lat":11.111111,"lon":22.222222}

2. Then tell Notecard to use that location for NTN purposes with ntn.gps:

   COPY

   {"req":"ntn.gps","on":true}

   On a Starnote, this is what overrides Starnote's own GPS/GNSS module with the location known to the paired Notecard. Without it, Starnote keeps using its own module and your fixed coordinates are ignored.

   ntn.gps matters just as much on Notecard for Skylo, where the satellite radio is built into the cellular modem. By default Notecard does not pass its location to that modem. {"req":"ntn.gps","on":true} tells Notecard to supply a location it already knows as part of connecting, so the modem does not have to establish its own position first.

When you're finished testing, return both settings to their defaults so the device resumes using real GPS data:

{"req":"ntn.gps","off":true}

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

Option B: Periodic GPS (Recommended for Production)

Notecard's GPS/GNSS module is off by default, so a deployed device with no location configuration will pay the 900-second penalty on every attempt that needs a fresh fix.

For production, enable periodic mode with a seconds interval. The example below performs a daily lookup:

{"req":"card.location.mode","mode":"periodic","seconds":86400}

Once Notecard has a location, it won't try for another one unless its onboard accelerometer detects movement — so a stationary device acquires its location once and then stops spending power on it. This makes periodic a good default even for fixed installations.

tip

Because a Skylo device needs both a GPS fix and a satellite link, and GPS acquisition works best with the same clear view of the sky, a device that can't get a location and a device that can't find a satellite often have the same root cause. If you're stuck here, revisit Get a Clear View of the Sky.

If the Location is Still Unknown

An ntn.status response containing {ntn-unknown-location} means the module could not get a location from either source:

{"status":"{ntn-idle}{ntn-unknown-location}"}

Check the current location with a card.location request, then use ntn.gps to switch which GPS the Starnote relies on. If Starnote's own antenna has a poor view but the Notecard's does not, {"req":"ntn.gps","on":true} may resolve it outright.

Read Notecard Satellite Diagnostics

If you've worked through the checks above and satellite still isn't working, stop guessing and read what the device is reporting. These three requests, plus a trace log, will tell you where in the process things are stalling.

Confirm the Active Transport

First, verify Notecard is actually configured to use NTN mode. Send a card.transport request with no arguments to read the current setting:

{"req":"card.transport"}

For isolating a satellite problem, ntn forces satellite only and removes cellular and WiFi as variables:

{"req":"card.transport","method":"ntn"}

warning

"method":"ntn" is a testing configuration. It is not recommended for production, because there is no other transport to fall back to. When you're done diagnosing, set the method back to what your product actually uses (for example cell-ntn or wifi-cell-ntn). If you aren't sure what the original value was, {"req":"card.transport","method":"-"} resets the transport to the device's default.

Check the Satellite Module Status

The ntn.status request reports Notecard's view of a paired Starnote:

{"req":"ntn.status"}

{"status":"{ntn-idle}"}

A status of {ntn-idle} on its own is not an error; it means the Starnote is powered and healthy but not currently transmitting, which is what you should see between syncs.

If instead of a status you get an error like this, the Notecard cannot see a Starnote at all, so recheck the pairing and the Notecarrier connections:

{"err":"no NTN module is connected {no-ntn-module}"}

For a list of all error and status codes and what they mean, see Notecard Error and Status Codes.

note

The ntn.status request describes an external module, therefore it isn't available on Notecard for Skylo.

Check Sync Progress

hub.sync.status tells you whether a sync is in progress, completed, or failed, and makes it clear whether Notecard is using cellular or NTN:

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

{
 "status": "connecting {ntn-connecting}",
 "mode": "{ntn-connecting}",
 "sync": true
}

The two fields to read are status (what the sync is doing) and mode (the state of the radio being used). NTN activity shows up as the same {ntn-*} codes listed above, so a mode of {modem-off} or a status full of {cell-*} codes means the sync went out over cellular, not satellite. Two other fields are worth noting: sync is true when the Notecard still has unsynced Notes pending, and seconds appears when the Notecard is in a penalty box and counts down until it will retry.

Watch a Live Trace

A trace log is the highest-value diagnostic for NTN connectivity. Enable it with trace mode:

trace +req

Then trigger an outbound sync and watch:

{"req":"hub.sync","out":true}

A successful satellite transmission looks like this, and the ntn.uplink and packet: sending lines are what you're waiting for:

S07:00.22 sync: sync triggered by explicit sync request; GPS; NTN outbound
S07:00.22 sync: work: begin (anything pending) {sync-begin}
S07:00.29 sync: work to be done:
S07:00.30       upload sat.qo
S07:00.32 ntn: enqueueing 9-byte note from sat.qo (port 55)
S07:00.32 sync: work: upload sat.qo (1 changes) {sync-get-local-changes}
S07:00.48 sync: work: completed {sync-end}
S07:00.65 ntn: adding downlink request note into packet (6/254)
S07:00.65 ntn: moved 9-byte note (port 55) into packet (17/254)
S07:00.65 packet: sending 17 bytes (encoded as 19 bytes on-air)
S07:00.78 ntn: sent 17-byte packet containing 2 notes

If you never see a line enqueueing your Note into a packet, the problem is upstream of the radio, most likely a missing or unsynced template (see Verify Notefile Templates). If the Note is enqueued but the packet never sends, the radio isn't reaching a satellite, which points back to sky view, coverage, or antennas.

Turn trace mode off when you're done:

trace off

Other Issues and Solutions

A handful of other issues account for most of what's left once the checks above pass.

• Is a Starnote paired to more than one Notecard?
  • A Starnote can only be paired with one Notecard at a time, and the association is fixed until it is manually reset on the original Notecard. This one is deceptive: the new pairing may appear to sync over NTN, but no Notes arrive in Notehub, because the old Notecard reasserts ownership the next time it syncs. Issue an ntn.reset on the old Notecard, then sync the new one over cellular or WiFi. See Pairing Starnote with a Different Notecard.
• Is the satellite antenna the right one, and fully seated?
  • Starnote for Iridium requires an Iridium-certified antenna — a generic LTE or GPS antenna will not work. Notecard for Skylo needs a Skylo-certified antenna on MAIN plus a GPS/GNSS antenna on GPS. On any u.FL connection, push until you feel the connector click; a partially seated u.FL blocks all signal. Consult the Antenna Guide for satellite antenna specifications.
• Is the device receiving adequate power during transmit?
  • Satellite modems draw far more current than cellular. The Starnote for Iridium modem can draw up to 8.5A during transmission, which is why a LiPo battery must stay connected to the Notecarrier XI's LIPO JST connector at all times — including when powering over USB. USB alone cannot source those bursts. A brownout during transmit presents as an unexplained failure partway through a sync.
• Is Notecard in a penalty box?
  • After repeated failures, Notecard deliberately stops attempting connections to conserve power, so a device may look dead when it is simply waiting. See Understanding Notecard Penalty Boxes.
• Are you expecting _temp.qo or _track.qo data over satellite?
  • System Notefiles need their template synced like any other. Issue the relevant request (for example card.temp or card.location.track) and sync over cellular or WiFi before the device switches to NTN mode.
• Have you simply not waited long enough?
  • It bears repeating, because it's the most common false alarm. Finding and communicating with a satellite can take multiple minutes. Confirm the antenna is unobstructed and give each attempt its full window before concluding it failed.

Getting Assistance from Blues

If you've worked through this guide and still can't establish or maintain a satellite connection, Blues can help. Gather the following before reaching out:

1. DeviceUID and Notecard SKU — available from card.version or the device page in Notehub.
2. Firmware versions for both devices. Notecard's comes from card.version; if you're using a Starnote, its version must be read over a direct serial connection to the Starnote. See Verify Notecard and Starnote Firmware.
3. Which satellite product and network you're using, from Identify Your Satellite Setup.
4. A trace log captured during a failing satellite sync attempt. See Read Notecard Satellite Diagnostics and Using Notecard Trace Mode.
5. The output of card.transport, ntn.status, and hub.sync.status taken at the time of the failure.
6. Your Notefile templates, including the note.template ... verify:true response for the Notefiles that aren't syncing.
7. The device's physical location and sky view — the country or region, and a description or photo of the antenna's view of the sky.
8. Confirmation that the device has synced over cellular or WiFi, and when.

The general guidance in Getting Additional Help also applies, and lists the available support channels.