Satellite Best Practices

Building a product around satellite provides enhanced connectivity versus cellular or WiFi alone, but does require the awareness of additional considerations when writing firmware.

What follows are a set of tips to help you build a solution that maximizes the utility of satellite, while minimizing unnecessary usage of your data allocation.

note

Troubleshooting a satellite connection that isn't working? This page covers satellite (NTN) development best practices. To diagnose a specific failure, consult Diagnosing Satellite Connectivity Issues, which walks through common failure points across Starnote for Skylo, Notecard for Skylo, and Starnote for Iridium.

Update Notecard and Starnote Firmware
Optimize Use of Compact Templates
Define NTN vs non-NTN Templates
Always Sync with Notehub First
Use a Fixed GPS Location
Develop and Test Without Satellite Coverage
Minimize Unnecessary Data Syncs
Pairing Starnote with a Different Notecard
Designing Starnote Into Your Carrier Board

Update Notecard and Starnote Firmware

Blues regularly updates both Notecard firmware and Starnote firmware with feature additions and bug fixes. If you're experiencing an issue with satellite connectivity and you're using either a Notecard for Skylo, a Starnote for Skylo, or a Starnote for Iridium device, we highly recommend updating to the latest available firmware releases on all of your Blues devices.

note

Notecard for Skylo is considered a Notecard for firmware update purposes.

Optimize Use of Compact Templates

All communications over NTN (satellite) require you to use templated Notefiles and templated environment variables. Templates are defined on Notecard and must include two additional arguments: "format":"compact" and "port":<1-100>.

For example, the following request creates a templated Notefile that is compatible with both NTN and non-NTN (i.e. cellular and WiFi) communications.

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

The "format":"compact" argument removes certain pieces of metadata from the Note, including a timestamp for when the Note was created, information about the device's location, as well as a timestamp for when the device's location was determined. You can read more about "format":"compact" in Creating Compact Templates.

If you need to restore individual pieces of metadata to added Notes, include a reference to the field(s) in the body of the template. In the following example, _time represents a timestamp for when the Note was created. The other available field names are documented here.

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

note

Consult our guide on Setting Environment Variable Templates to learn how to use templated environment variables with NTN.

Define NTN vs non-NTN Templates

Notecard can only tell you which RAT (radio access technology) was used on the previous sync, not which RAT will be used on the next sync. Therefore, when defining Notefile templates, you can include arguments that let you define if the Note should be synced over NTN (satellite), non-NTN (cellular or WiFi), or both.

For instance, if you are regularly syncing "large" Notes over cellular or WiFi, when falling back to NTN you may want to only sync a "small" version of the Note with a similar structure (to minimize usage of satellite data).

warning

For a Note synced with Starnote for Iridium, satellite packets have a minimum billable size of 10 bytes and a maximum supported size of 10,000 bytes. Packets smaller than 10 bytes are billed as 10 bytes. Packets exceeding 10,000 bytes are not transmitted, are ignored by the satellite network, and result in the Note being deleted. Billing is based on the packet size.
For a Note synced with Notecard for Skylo or Starnote for Skylo, satellite packets have a minimum billable size of 50 bytes and a maximum supported size of 256 bytes. Packets smaller than 50 bytes are billed as 50 bytes. Packets exceeding 256 bytes are not transmitted, are ignored by the satellite network, and result in the Note being deleted. Billing is based on the packet size.

Usage Scenarios

The following scenarios can help you understand when and how data is synced over NTN vs non-NTN communications.

I want this Note to be synced regardless of RAT in use (cellular, WiFi, or NTN)

Create a Notefile template that is compatible with both NTN and non-NTN communications by:

Using a .qo/.qos/.qi/.qis extension in the file argument (.db/.dbs Notefiles are not supported over NTN).
Using both "format":"compact" and "port":<1-100> arguments.

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

I only want this (large) Note to be synced when using non-NTN (e.g. cellular or WiFi)

To define a Notefile template that will only sync data when using cellular or WiFi, omit the format and port arguments.

If the Notefile template has a compact, NTN-compatible, "sister" template AND you don't want the large Notes to sync after their compact counterparts have been uploaded over NTN, add the "delete":true argument to the large Notefile template. The "delete":true argument tells the Notecard to clear out all queued Notes using this template if the Notecard is connecting using NTN (satellite).

{"req":"note.template","file":"climate-large.qo","delete":true,"body":{"temp":14.1,"humidity":14.1,"reading":14.1,"alert":true}}

note

It's also important to remember that Notes queued on the Notecard without a Notefile template will never be synced in NTN mode.

One final note: by default the Notecard does not allow you to add to non-compact Notefiles while connected over a non-terrestrial network. This is to prevent the Notecard from filling with data that it cannot synchronize.

For example, if you were to attempt to add to the "climate-large.qo" Notefile while your device has an NTN connection, you would receive the following error.

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

If you wish to allow adding to non-compact Notefiles during NTN connections, you can pass allow: true to the card.transport request.

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

I only want this (small) Note to be synced when using NTN

To define a Notefile template that will only sync data when using satellite, create an NTN-compatible Notefile (see example above), but also include the "delete":true argument. This will tell the Notecard to clear out all queued Notes using this template if the Notecard is connecting using non-NTN communications (cellular or WiFi).

{"req":"note.template","file":"climate-small.qo","format":"compact","port":11,"delete":true,"body":{"temp":14.1,"alert":true}}

I want to send this Note more frequently over non-NTN than over NTN

A common use case is to capture the same type of reading (e.g. water height, temperature) more frequently when on cellular or WiFi, but less frequently when falling back to satellite in order to reduce NTN data costs. Because Notecard cannot predict which RAT will be used for the next sync, the recommended pattern is to define two Notefile templates (one for each RAT) both using "delete":true and let your host firmware add Notes to each at its own cadence.

In the following example, water height is captured every 5 minutes over cellular or WiFi, but only every 30 minutes over NTN.

First, define a non-NTN-compatible template (no format or port) with "delete":true so queued Notes are discarded if Notecard ends up connecting via NTN:

{"req":"note.template","file":"water-cell.qo","delete":true,"body":{"height":14.1}}

Then define a matching compact, NTN-compatible template, also with "delete":true, so queued Notes are discarded if Notecard ends up connecting via cellular or WiFi:

{"req":"note.template","file":"water-ntn.qo","format":"compact","port":12,"delete":true,"body":{"height":14.1}}

In your host firmware, send a note.add request to water-cell.qo every 5 minutes and to water-ntn.qo every 30 minutes. At sync time, Notecard will discard whichever queue does not match the active transport, and only sync the Notes that do.

note

This pattern lets Notecard decide which Notes are appropriate for the current transport. Avoid designing host firmware that inspects the previously-used transport and then decides what to send next, because the next sync may end up using a different RAT and you could end up sending too much data over satellite (or vice-versa).

Understanding note.template/delete:true

Only NTN-compatible Notefiles will sync over NTN (satellite), whereas any type of Notefile will sync over non-NTN communications unless you specify the "delete":true argument when defining the template.

If using the "delete":true argument when defining a Notefile template, be aware that before every sync:

If you are connected via non-NTN (cellular or WiFi), all NTN-compatible Notefiles will be cleared out.
If you are connected via NTN (satellite), all non-NTN-compatible Notefiles will be cleared out.

Always Sync with Notehub First

All Blues satellite products will not function until a non-NTN (cellular or WiFi) connection has first been established with Notehub.

This action is required to sync any newly defined or updated Notefile templates. Even if something as simple as the port number is updated in a template, it must be re-synced over a non-NTN connection.

note

Should you need to sync data with the _temp.qo or _track.qo System Notefiles over NTN, you will need to issue the appropriate command (e.g. using the card.temp or card.location.track APIs) and sync with Notehub prior to the device switching to NTN mode.

These configuration settings persist across Starnote and Notecard restarts. Once you create or update a template and perform a single sync over cellular or WiFi, the changes are saved. Even if the device restarts, there's no need to re-establish a new connection with Notehub.

Use a Fixed GPS Location

When testing Skylo-based hardware, such as Notecard for Skylo or Starnote for Skylo, you can specify a fixed set of GPS coordinates for Notecard. Because communicating with Skylo satellites requires a GPS location, using a fixed location allows Notecard to skip the time-consuming process of determining its location with its GPS/GNSS module before attempting to connect via satellite.

To use a fixed location, look up the precise latitude and longitude you want to use and set the lat and lon arguments in a card.location.mode request.

{"req":"card.location.mode","mode":"fixed","lat":42.56517983068798,"lon":-70.78359819291745}

To reset this to Notecard's default behavior, send another card.location.mode with the mode argument set to -.

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

Develop and Test Without Satellite Coverage

Satellite is the hardest transport to test with during development. You may not have Starnote hardware yet, your region may have no Skylo coverage, or you may simply be at a desk without a clear view of the sky. None of that has to block progress on your firmware.

Notecard can exercise the NTN code path using a cellular or WiFi connection instead of a real satellite link. Your Notes travel over the internet, but Notecard applies the same byte-constrained NTN rules it would over satellite, so you can verify how your device behaves before satellite hardware or coverage is available.

note

These techniques require a Notecard with no satellite radio of its own (e.g. Notecard Cellular, Notecard Cell+WiFi, or Notecard WiFi). Notecard for Skylo has an integrated NTN radio and will use the real Skylo network rather than simulating it.

All features described in this section also require modern Notecard firmware. If a request below returns an error, update to a current release from Notecard Firmware Releases.

First, Unpair Any Previously Connected Starnote

Skip this if the Notecard has never had a Starnote attached.

When a Notecard is paired with a Starnote, that pairing is stored in permanent configuration that a card.restore request does not clear. A Notecard that still believes it has a Starnote will keep trying to reach it, so clear the pairing first:

Physically disconnect the Starnote from the Notecard.
Clear the stored NTN configuration with ntn.reset:
```
{"req":"ntn.reset"}
```
Restart Notecard with card.restart or by power-cycling it:
```
{"req":"card.restart"}
```

Simulate NTN Transmission

To exercise the NTN path itself (i.e. use compact templates, port numbers, packet size limits, and how your firmware reacts to them) force Notecard into NTN-only mode:

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

With no Starnote attached, Notecard applies its NTN behavior but carries the traffic over cellular or WiFi. To confirm you're actually in simulation mode, sync a Note and inspect the event in Notehub. The transport field will read ntn:udp rather than ntn:skylo or ntn:iridium:

`transport` value	Meaning
`ntn:udp`	UDP via NTN simulation mode
`ntn:skylo`	A real Skylo satellite link
`ntn:iridium`	A real Iridium satellite link

When you're finished, return the transport to your device's default:

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

Or set it to whatever your product actually ships with, for example:

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

Force NTN Fallback

Simulating NTN transmission tells you what happens once Notecard is on satellite. It doesn't tell you whether your fallback configuration behaves correctly when a terrestrial network goes away.

Instead, tell Notecard to treat its terrestrial transports as already failed.

Configure the fallback method your product will use:
```
{"req":"card.transport","method":"cell-ntn"}
```
Depending on the radios available on your Notecard, wifi-ntn and wifi-cell-ntn are also valid.
Force the fallback with a card.io request:
```
{"req":"card.io","mode":"+fallback"}
```
Using this mode, WiFi and cellular automatically fail over and all traffic goes through NTN.
When you're done testing, restore normal behavior:
```
{"req":"card.io","mode":"-fallback"}
```
Using this mode (the default), fallback then happens only when cellular or WiFi genuinely aren't available.

warning

+fallback persists across Notecard restarts. That is deliberate — it lets you configure a device on the bench and then install it in an enclosure for field testing without re-issuing the request.

It also means the setting is easy to leave enabled by accident. On a device with real satellite hardware, a forgotten +fallback sends all traffic over satellite and can incur unexpectedly high data costs, so it is not recommended for production deployments. Send -fallback as part of your manufacturing or provisioning process.

Minimize Unnecessary Data Syncs

Using NTN mode will continue to utilize the outbound/inbound sync cadence you specify in your hub.set request. For instance, in the following request (regardless if you are using cellular, WiFi, or satellite) the Notecard will attempt an outbound sync (but only if data is pending) every 15 minutes and an inbound sync every 60 minutes.

{
  "req": "hub.set",
  "mode": "periodic",
  "outbound": 15,
  "inbound": 60
}

This is key because inbound syncs must ping Notehub to check if there are any Notes or environment variables pending syncing. This action alone uses approximately 50 bytes of data.

A best practice is to either use a relatively large inbound argument (e.g. once per week with "inbound": 10080, since inbound is in minutes) or manually initiate inbound sync requests in your firmware using the hub.sync API.

tip

If you need a different sync cadence for NTN than for cellular or WiFi, use the _sync_outbound_mins_ntn and _sync_inbound_mins_ntn reserved environment variables. When the Notecard is using NTN (satellite) transport, these take precedence over the outbound and inbound values configured via hub.set.

For example, if hub.set has outbound set to 60, and your Notecard has a _sync_outbound_mins_ntn environment variable set to 180, Notecard will sync outbound data every 1 hour over cellular and every 3 hours over satellite — with no firmware changes required.

When using NTN mode on a Notecard with a paired Starnote, or when using NTN mode on Notecard for Skylo, Notecard will NOT automatically perform both outbound and inbound syncing of Notefiles and environment variables via a single hub.sync request. In order to minimize data usage, you need to request syncs specific to outbound (from Notecard/Starnote) or inbound (to Notecard/Starnote) usage.

For example, to only sync pending outbound data, use the "out":true argument (noting that Notecard will not even attempt an outbound sync if there is nothing pending to be sent).

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

Likewise, you can specifically request a check for inbound data from Notehub by using the "in":true argument:

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

Pairing Starnote with a Different Notecard

When using Starnote for Iridium or Starnote for Skylo, it's important to know that a Starnote can only be paired with one Notecard at a time. When a Starnote is paired with a Notecard, that association is fixed until the pairing is manually reset on the old/original Notecard.

If you don't reset the old Notecard, a new Starnote/Notecard pairing may appear to sync successfully over NTN, but no Notes will appear in Notehub. What's happening is that the old Notecard reasserts ownership of Starnote the next time it syncs with Notehub, effectively reclaiming it from the new Notecard.

To pair Starnote with a different Notecard:

On the old Notecard, issue an ntn.reset request to unpair the Starnote.
On the new Notecard, perform a sync over cellular or WiFi to establish the new pairing.

Designing Starnote Into Your Carrier Board

Most of this page is about firmware and configuration, but one satellite decision is made in hardware. If you choose to move from a Blues Notecarrier to a custom carrier board, remember that a Starnote design always has two devices on it: a Starnote and its companion Notecard, each in its own M.2 Key E connector.

note

While specific to Notecard-based designs, see our article on Integrating Notecard into a Product for help on making the decision to spin your own custom carrier board.

We recommend you:

Use a Blues-provided Notecarrier if at all possible.
If not, base your design off of one of our open source Notecarrier designs and consult with one of our trusted partners and/or utilize our complimentary Blues Design Review service.

Consult the Starnote Carrier Board Design Guide for information on Starnote's mounting and footprint, the Notecard-to-Starnote link, power, and satellite antenna requirements. Likewise, read the Notecard Carrier Board Design Guide for everything to know about designing in everything on the Notecard side (e.g. host intefaces, power, SIM, GPS, AUX pins, and DFU).

note

Notecard for Skylo is a Notecard for design purposes. Its satellite radio is integrated, so there is no second device to mount and no Notecard-to-Starnote link to route.

Can we improve this page? Send us feedback