homechevron_rightDocschevron_rightStarnotechevron_rightStarnote Best Practices

Starnote Best Practices

Building a product around Starnote provides enhanced connectivity versus cellular or Wi-Fi 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 Starnote, while minimizing unnecessary usage of your satellite data allocation.

Optimize Use of Compact Templates

All communications over NTN (satellite) require you to use templated Notefiles and templated environment variables. Templates are defined on the Starnote's paired 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 Wi-Fi) 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 Starnote.

Define NTN vs non-NTN Templates

The 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 Wi-Fi), or both.

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

warning

Starnote will always use at least 50 bytes of your data allocation when performing a sync with Notehub, regardless whether or not there are Notes queued for syncing. For reference, the minimum data payload size is 50 bytes and the maximum payload size is 256 bytes.

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, Wi-Fi, or satellite)."

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

  1. Using a .qo/.qos/.qi/.qis extension in the file argument (.db/.dbs Notefiles are not supported over NTN).
  2. 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 communications (e.g. cellular or Wi-Fi)."

To define a Notefile template that will only sync data when using cellular or Wi-Fi, 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 communications (e.g. satellite)."

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 Wi-Fi).

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

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:

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

Always Sync with Notehub First

As outlined in the Starnote Quickstart, Starnote will not function until a non-NTN (cellular or Wi-Fi) connection has first been established with Notehub.

This action is required to sync any newly-defined Notefile templates. Be sure to perform a non-NTN sync any time you define a new Notefile template.

Use a Fixed GPS location

When in testing or development (or if Starnote will be deployed to a fixed location), you can specify a "fixed" set of GPS coordinates for the Notecard. When using a fixed location, Starnote will skip the time-consuming step of using its GPS/GNSS module to ascertain its location 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 the Notecard's default behavior, send another card.location.mode with the mode argument set to -.

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

Minimize Unnecessary Data Syncs

It's important to note that using NTN mode with Starnote 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, Wi-Fi, 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": 604800) or manually initiate inbound sync requests in your firmware using the hub.sync API.

Unlike other Notecards, using NTN mode with Starnote 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 Starnote 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}