Starnote Quickstart
Introduction
This tutorial should take approximately 20-30 minutes to complete.
This guide will introduce you to Starnote, an affordable satellite IoT fallback device. Much like the cellular-based Notecards include prepaid cellular data and service, Starnote includes satellite uplink and downlink data with the cost of the device.
Starnote communicates through a paired Notecard, so developers continue to use the Notecard's JSON-based programming interface. This allows developers to send and receive data over NTN (Non-Terrestrial Networks) using straightforward, accessible semantics.
Starnote is a cost-optimized "Notecard accessory" and must be paired with a Notecard device to function (specifically Notecard Cellular, Notecard Cell+WiFi, or Notecard WiFi - the Notecard LoRa is not supported for use with Starnote).
In a nutshell, you use the Notecard API to specify the mode of operations for when to fallback to satellite and what data to sync, and the Notecard handles communications between itself and Starnote, as depicted in the flowchart below:
Starnote is offered in two variants. One with onboard satellite and GPS/GNSS antennas from Ignion and one with u.FL connectors for external antennas on the back of the boards.
Starnote with Ignion Antennas | Starnote with u.FL Connectors |
---|---|
Before You Begin
New to the Notecard? We recommend reviewing the Notecard Quickstart before proceeding to better understand how the Notecard operates.
You do not need to have a physical Starnote device on-hand to complete this guide as all of the specified Notecard requests may be used without a Starnote. This process allows for easier development and testing for later incorporation of Starnote, as you will not be using up your satellite data allocation.
Understanding NTN Transport Mode
With the release of Starnote, we've added a new transport mode called NTN (Non-Terrestrial Networks). NTN is the 3GPP standard for satellite-based interaction with cellular networks as provided by Skylo, our connectivity partner for Starnote.
The Notecard's NTN mode is a byte-constrained mode that uses UDP to send packets over the network in an effort to use as little data as is possible. NTN mode is compatible with all variants of Notecard Cellular, Notecard Cell+WiFi, and Notecard WiFi.
Transport modes (part of the card.transport API) allow developers to configure the Notecard for communicating across multiple Radio Access Technologies (RATs), like falling back from cellular, to Wi-Fi, and lastly to NTN.
During phases of application development and testing, NTN mode can be used without the presence of Starnote. This means you can develop and debug firmware using cellular or Wi-Fi without using satellite data. Once your firmware is complete and ready for deployment, your application will be able to use Starnote for satellite fallback without any firmware changes.
The NTN-related card.transport
method
arguments are as follows:
-
{"req":"card.transport","method":"ntn"}
to always use NTN for network communications (useful for testing NTN mode over cellular or Wi-Fi, not recommended for production deployments). -
{"req":"card.transport","method":"wifi-ntn"}
to prefer Wi-Fi and fallback to NTN. -
{"req":"card.transport","method":"cell-ntn"}
to prefer cellular and fallback to NTN -
{"req":"card.transport","method":"wifi-cell-ntn"}
to prefer Wi-Fi, then fallback to Cellular, and lastly to NTN. -
{"req":"card.transport","method":"-"}
to reset the transport mode to the device default.
NTN Basics
It's important to keep in mind that Starnote is a fallback connectivity option, managed by its paired Notecard. This means the Notecard will dictate how and when to send data to Starnote for syncing over satellite. You have the ability to dictate what data is sent over satellite, but the Notecard will determine when to use Starnote (it will always prioritize cellular or Wi-Fi unless you explicitly override those settings).
The rest of this guide assumes you have a Notecard Cellular, Notecard Cell+WiFi, or Notecard WiFi connected to a compatible Notecarrier.
Use of a wired Starnote is not recommended until you fully understand how to use NTN mode.
-
Connect a USB cable from the Notecarrier's USB port to your computer's USB port.
-
Locate the panel on the right-hand side of your browser window, which we call the In-Browser Terminal. Within the In-Browser Terminal, click the USB Notecard button.
-
Reset your Notecard's transport method to its default mode with the
card.transport
API.{"req":"card.transport","method":"-"}
-
All NTN communications require use of templated Notefiles and templated environment variables to help reduce usage of satellite data.
For example, to create a Notefile template for use with NTN, define the template with the
"format":"compact"
and"port":<1-100>
arguments. Read more about theformat
andport
arguments in the note.template API documentation.{"req":"note.template","file":"sat.qo","format":"compact","port":55,"body":{"temp":14.1,"humidity":14.1}}
-
Likewise, if you wanted to set an inbound Notefile template you would use the same format, but with a
.qi
extension on thefile
argument.{"req":"note.template","file":"config.qi","format":"compact","port":44,"body":{"cmd":"*"}}
-
After all of your Notefile templates are defined, set your Notecard to your Notehub project's ProductUID with the
hub.set
request, and perform a sync withhub.sync
. It is required that the Notecard first syncs with Notehub over a non-NTN connection to copy all of your generated templates to the Notehub project before they may be used by Starnote.{"req":"hub.set","product":"com.your.domain:product","mode":"minimum"} {"req":"hub.sync"}
-
Watch the progress bar in the In-Browser Terminal for updates on the syncing process.
warning You must wait for the Notecard to complete a full sync with Notehub before you proceed to the next step!
-
Once the sync with Notehub is complete, turn on NTN mode with the
card.transport
API.{"req":"card.transport","method":"ntn"}
warning We do not recommend using
"method":"ntn"
in production. When using a physical Starnote, NTN mode will force the Notecard to send all data over satellite, which may inadvertently consume your data allocation. -
Add a Note to a templated Notefile. For example:
{"req":"note.add","file":"sat.qo","body":{"temp":12.3,"humidity":45.6}}
-
Next, watch serial communications from Starnote by issuing the
trace +req
command in the In-Browser Terminal.trace +req
This enables trace mode on the Notecard and displays all requests to/from the Notecard and Starnote. When enabled, messages from Starnote to Notecard show up as
"cmd":"ntn.*
, for example:{"cmd":"ntn.hello","id":6,"body":{"sku":"NTN-SKY1","ordering_code":"ZZ","apn":"blues.prod","device":"skylo:901980060003003","modem":"CC660DLSAAR01A03_01.001.01.001","iccid":"89901980100600030030","imsi":"901980060003003","imei":"860952060011179","policy":"10TPM","mtu":256,"band":"0","channel":"0","org":"Blues Inc","product":"Starnote","version":"st... (438) R00:28.53 ntn: skylo:901980060003003 {"cmd":"ntn.hello","id":6,"ltime":259154,"lat":30.522045368734993,"lon":-97.615997784658149} {"cmd":"ntn.status","id":7,"status":"powering up {ntn-connecting}{ntn-power}{ntn-gps}"} {"cmd":"ntn.status","id":8,"status":"initializing modem {ntn-connecting}{ntn-power}{ntn-gps}"} {"cmd":"ntn.status","id":9,"status":"waiting for satellite network (0/120 secs) {ntn-connecting}{ntn-power}{ntn-gps}"}
-
Send a
hub.sync
request to sync data over NTN, using theout
argument to only sync pending outbound Notes.{"req":"hub.sync","out":true}
-
Watch for the sync with Notehub to complete in the In-Browser Terminal. Eventually you may notice a fragment of text like the following, which details the size of each Note and total packet size transported over UDP.
S03:05.53 ntn: enqueueing note len:15 (port 55) S03:05.53 ntn: enqueueing note len:15 (port 55) S03:05.53 ntn: enqueueing note len:15 (port 55) S03:05.54 sync: work: upload sat.qo (3 changes) {sync-get-local-changes} S03:05.54 purge sat.qo: S03:05.55 1 notes (0 stable, 0 queued, 1 tombstones) S03:05.55 -> 0 notes (0 stable, 0 queued, 0 tombstones) S03:05.59 sync: work to be done: S03:05.59 upload sat.qo S03:05.60 deleting /data/sat-qo.000 S03:05.63 sync: work: completed {sync-end} S03:05.64 sync: advancing last sync time from 14:08:26Z to 14:09:04Z S03:05.76 ntn: adding downlink request note into packet (6/248) S03:05.77 ntn: dequeueing 15-byte note (port 55) into packet (23/248) S03:05.77 ntn: dequeueing 15-byte note (port 55) into packet (40/248) S03:05.77 ntn: dequeueing 15-byte note (port 55) into packet (57/248) S03:05.78 packet: sending 57 bytes (encoded as 61 bytes on-air) S03:05.78 to 216.245.146.112:8089 S03:05.78 ntn: sent 57-byte packet containing 4 notes
-
IMPORTANT: Be sure to disable trace mode by sending the
trace off
command in the In-Browser Terminal.trace off
-
Finally, head to your Notehub project to look for the Note you just sent.
-
At this point you can reset the transport mode of your Notecard to restore it to prioritizing cellular or Wi-Fi communications.
{"req":"card.transport","method":"-"}
warning Once you’ve connected your Notecard to Starnote, the presence of a physical Starnote is stored in a permanent configuration that is not affected by a
card.restore
request.If you'd like to reset this so you can go back to testing NTN over cellular or Wi-Fi, issue a ntn.reset request to the Notecard.
Connecting a Starnote
Full instructions for connecting a physical Starnote device are coming soon!
Next Steps
Congratulations! You've now queued data on a Notecard and delivered that data to the cloud using NTN mode!
Your next step is to review the Starnote Best Practices guide to better understand how to build a product around Starnote.
At any time, if you find yourself stuck, please reach out on the community forum.