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
• Getting Assistance from Blues

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 cable from its onboard 6-pin JST connector to a Notecard in another Notecarrier. 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":"an external NTN module can't be connected to this type of notecard {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, a no NTN module is connected {no-ntn-module} error means the Starnote isn't being detected — see Check the Satellite Module Status.

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 versions).

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 reports only Notecard's own firmware version; it doesn't tell you anything about the firmware on a paired Starnote. To read the Starnote's version, send an ntn.config request to the Notecard it's paired with, and check the version field in the response body:

{"req":"ntn.config"}

"version":"starnote-s-11.3.2.17807"

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

If hub.sync.status returns a time field, Notecard has completed at least one sync, and completed tells you how many seconds ago the last one finished.

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 (cell, or wifi on Notecard WiFi), 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. Without one, note.add succeeds and the sync appears to complete normally, but the data never reaches Notehub. No error is reported, making this issue difficult to diagnose.

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. Each Notefile needs its own port.

{"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}

A correctly configured NTN Notefile responds with "template":true, a format of compact, and the port you assigned:

{"template":true,"format":"compact","port":55,"body":{"temp":14.1,"humidity":14.1}}

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

If a Note exceeds the size of a single packet, Notecard drops it without transmitting it or reporting an error. Make sure your template stays within the packet size limits to avoid silent data loss.

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.

Note that the maximum supported figures above are the size of the whole on-air packet, not the space available to your data. Notecard spends a few bytes of every packet on framing (a flag byte, a message port, and a connection ID when one is in use), so a Skylo packet with a 256-byte maximum carries a slightly smaller payload. A trace log shows you the real number for your device — the fraction in the packet lines is bytes used out of bytes available:

S07:00.65 ntn: moved 9-byte note (port 55) into packet (17/254)

If a single Note is larger than that available space, it can never be packed into a packet, and Notecard drops it rather than retrying forever. When this happens, the trace shows ntn: IGNORING note that is too large for packet. Splitting the data across two smaller Notes, or trimming fields from the template, is the fix.

If a note.add Returns an Error in NTN Mode

By default, Notecard rejects a note.add to keep the device from filling with data it cannot send. This happens only when all three of the following are true:

1. The Notefile has a template.
2. That template has no port.
3. NTN is the active transport.

{"err":"adding notes to a non-uplinked port is not allowed when in packet mode"}

If that error is what brought you here, it's working as designed. The fix is to give the template a port (see What an NTN-Compatible Template Requires) and sync again over cellular or WiFi.

To store the Notes anyway, accepting that they will not be sent over satellite, pass "allow":true to card.transport. Note that allow is only read when the same request also specifies a transport method or passes "set":true, so sending allow by itself has no effect. It also means any later card.transport request with a method or "set":true turns allow back off unless you include "allow":true again:

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

warning

If a Notefile's template was created with "delete":true, Notecard can delete its queued Notes without sending them:

• Before a cellular or WiFi sync, it deletes Notes in NTN-compatible Notefiles (compact, with a port).
• Before a satellite sync, it deletes Notes in all other delete:true Notefiles.

If Notes are disappearing without being sent, check for delete:true.

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). A Skylo radio must know where it is before it can register with a satellite. How it gets that location differs between the two products.

Notecard for Skylo

On Notecard for Skylo the satellite radio and the GPS/GNSS receiver are part of the same module. By default, the module gets its own GPS/GNSS fix while it registers, so no location configuration is required.

What the module does need is a working GPS/GNSS antenna:

• Make sure the GPS/GNSS antenna is attached to the GPS connector.
• Give the GPS/GNSS antenna the same clear view of the sky as the main antenna. A module that can't get a fix can't register.

card.location.mode does not change this behavior. It controls the location Notecard reports in your data (card.location, _track.qo), not how the module locates itself for NTN, so enabling periodic mode won't help a device that is failing to register.

Optional: Use a Fixed Location for Faster Registration

If you know where the device is, for example while testing or for a stationary installation, you can hand the module a fixed location. The module then skips its own GPS/GNSS fix, which speeds up registration.

1. Look up the precise latitude and longitude of the device's 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 pass that location to the module with ntn.gps. A fixed location has no effect on NTN without this step.

   COPY

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

While ntn.gps is on, Notecard passes the module whatever location it currently holds. Normally that's your fixed location, but it can also be a location from cell tower or WiFi triangulation, or from environment variables. If Notecard doesn’t have a location, the module waits for one and registration cannot proceed. To avoid this, we recommend always providing a fixed location when using ntn.gps.

To return to the default, where the module gets its own fix, turn both settings back off. Do this if the device will move:

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

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

Starnote for Skylo

Starnote for Skylo determines its own location using its GPS/GNSS module during its first transmission, but that acquisition is slow. It's why Starnote's connection window extends from 120 to 900 seconds when its location is unknown. Providing a location up front removes that delay.

Option A: Fixed Location (Recommended for Testing)

A fixed location lets Starnote skip GPS acquisition entirely, which makes iterating much faster. Set it with the same two requests used for Notecard for Skylo above:

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

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

When you're finished testing, return both settings to their defaults:

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

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

Note that on a Starnote, ntn.gps supplements rather than replaces the module's own GPS/GNSS. Starnote keeps sampling and adopts whichever location is newer.

Option B: Periodic GPS (Recommended for Production)

When paired with a Starnote, Notecard uses Starnote's GPS/GNSS module as its location source (see Use Starnote as an External GPS). Notecard's location mode is off by default, so a deployed device with no location configuration may pay the 900-second penalty on attempts that need 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.

If the Location is Still Unknown

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

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

Check the current location with a card.location request.

If Notecard knows a location but Starnote does not, enable ntn.gps so Notecard passes it along. This is worth trying even when you haven't set a fixed location: Notecard may hold a position derived from cell tower or WiFi triangulation, or supplied through environment variables, and any of those will satisfy Skylo.

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

If Notecard reports no location either, set a fixed location and enable ntn.gps as described in Option A above.

tip

GPS acquisition works best with the same clear view of the sky that a satellite link needs, so on either product 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.

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 the current or most recent sync is in progress, completed, or failed:

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

{
 "status": "completed {sync-end}",
 "time": 1791984000,
 "completed": 42
}

status describes what the sync is doing or how it ended, and completed is the number of seconds since the last sync finished. Two other fields are worth noting: sync is true when Notecard still has unsynced Notes pending, and seconds appears when Notecard is in a penalty box and counts down until it will retry.

hub.sync.status doesn't reliably tell you which transport a sync used. To confirm a sync actually went out over satellite, watch a trace as described in Watch a Live Trace.

The status field can also carry a message prefixed with ntn:. The most common one is:

{"status":"ntn: satellite module not responding {network}","sync":true}

This means the Notecard went too long without a status update from its paired Starnote and timed out waiting. It is a report about the link between the Notecard and the satellite module, and not a report of poor satellite signal or a failed satellite connection. Check that the Starnote is fully seated in its M.2 socket, that it is paired to this Notecard and no other, and that the module has stable power.

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 packet: sending and ntn: sent lines at the end 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 an ntn: enqueueing line for your Note, 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.

When the Notecard is paired with a Starnote, the trace also shows a << {"cmd":"ntn.uplink",...} line between packet: sending and ntn: sent. That's the command Notecard sends to tell the Starnote to transmit the packet. You can also run trace +star to forward the Starnote's own trace output into the Notecard's trace stream. Those lines are prefixed with star:.

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?
  • The Starnote for Iridium modem can draw up to 8.5A during transmission. The Notecarrier XI's supercapacitor bank supplies those bursts, and a LiPo battery on the XI's LIPO JST connector keeps the bank topped up, so the battery must stay connected at all times — including when the board is powered from USB or a supply wired to VBAT or VMAIN. 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 comes from ntn.config. 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.