homechevron_rightDocschevron_rightQuickstartchevron_rightStarnote Quickstart

Starnote Quickstart

Introduction

This tutorial should take approximately 40–50 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:

notecard starnote data flow

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

note

New to the Notecard? We recommend reviewing the Notecard Quickstart before proceeding to better understand how the Notecard operates.

To complete this guide you must have access to the following:

A computer with an available USB port.
A browser that supports the Web Serial API, like Chrome, Microsoft Edge, or Opera.
A free Notehub.io account.
A Notecard Cellular, Notecard Cell+WiFi, or Notecard WiFi device on firmware version >= v7.2.2.

To complete the final sections of this guide, Connecting a Starnote and Sending Data Over Satellite, you must additionally have the following hardware (all of which is available in a Starnote Starter Kit).

A Starnote (either the u.FL or Ignion antenna version).
- If you have the Starnote with u.FL connectors you will also need:
  - An external LTE antenna.
  - An external GPS/GNSS antenna (though the Starnote can use fixed location coordinates for testing).
A Notecarrier XS.

When testing a physical Starnote you must have a clear of the sky. If you are using the Starnote with u.FL connectors and would like to test indoors, you may place an external antenna outdoors and run a cable to your device. If you're taking this approach you will additionally need:

An LTE-capable antenna that can be placed outdoors and oriented towards the sky (example).
A u.FL to SMA adapter (example).
An SMA-terminated extension cable (example).

Understanding NTN Transport Mode

Transport modes on the Notecard (part of the card.transport API) allow developers to configure which Radio Access Technology (RAT) the Notecard should use, and enable the Notecard to fallback from one RAT to another, such as falling back from Wi-Fi to cellular.

With the release of Starnote, we've added a new transport mode to the Notecard 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 attempts to send as little data as possible over the network. NTN mode is compatible with all variants of Notecard Cellular, Notecard Cell+WiFi, and Notecard WiFi.

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.

Let's start the hands-on portion of this tutorial by looking at how to use these modes on a Notecard.

Using NTN Mode

In this section of the guide you'll set your Notecard to use NTN mode and send your first Note over NTN mode to Notehub. To complete this section you must have a Notecard Cellular, Notecard Cell+WiFi, or Notecard WiFi connected to a compatible Notecarrier. If you are unsure how to do this refer to the Notecard quickstart.

If you're using a Starnote Starter Kit, you can complete this section by connecting your Notecard WiFi to the appropriate M.2 connector on your Notecarrier XS.

A Notecard WiFi connected to a Notecarrier XS

warning

Do NOT hook up Starnote yet. The Notecard automatically detects the presence of Starnote and will start using it when your Notecard is in NTN mode.

You'll hook up Starnote in a later step after you've learned how NTN mode works.

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.
Code
```
{"req":"card.transport","method":"-"}
```
If you're using a Notecard WiFi, connect to a 2.4 GHz network using the card.wifi request (as shown below), or by using the device's AP button.
JSON
```
{"req":"card.wifi","ssid":"your-network-name","password":"your-network-password"}
```
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 the format and port arguments in the note.template API documentation.
Code
```
{"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 the file argument.
Code
```
{"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 below. Setting the request's "mode" to "minimum" instructs the Notecard to only connect to Notehub during explicit hub.set requests, which will help us manage satellite data usage in later sections.
JSON
```
{"req":"hub.set","product":"com.your.domain:product","mode":"minimum"}
```
Run a hub.sync request. It is required that the Notecard first syncs with Notehub over a non-NTN connection to copy all of your generated templates to your Notehub project before they may be used by Starnote.
Code
```
{"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.
Code
```
{"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:

Code

{"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.
Code
```
trace +req
```
This enables trace mode on the Notecard and displays all requests to/from the Notecard and Starnote. For now you'll use trace mode to verify NTN mode is working as expected, and in later sections you'll use it to display all requests to and from the Notecard and Starnote.
Send a hub.sync request to sync data over NTN, using the out argument to only sync pending outbound data.
Code
```
{"req":"hub.sync","out":true}
```
If you need to instruct the Notecard and Starnote to check for inbound data, you must use the in argument of the hub.sync API.
Code
```
{"req":"hub.sync","in":true}
```
note
You can still use the inbound and outbound arguments in the hub.set API to specify a cadence of syncing with Notehub. However, a best practice is to either set a relatively high inbound argument or manually manage inbound connections as detailed here.

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.

Code

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.
Code
```
trace off
```
Finally, head to your Notehub project to look for the Note you just sent.

note
Events sent over NTN will not have a location, by default, because location is not included in compact Notefile templates. You can add fields that would be otherwise omitted by using a handful of reserved keywords. See Creating Compact Templates.
At this point you can reset the transport mode of your Notecard to restore it to prioritizing cellular or Wi-Fi communications.
Code
```
{"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 an ntn.reset request.

Connecting a Starnote

Now that you've seen how NTN mode works, let's connect a Starnote and see how to send data over a real satellite connection.

Starnote must be connected to a Notecard via UART, either using the Starnote's M.2 pins or the 6-pin JST connector on the front of the device.

The easiest way to connect Starnote to a Notecard is via the Notecarrier XS, which was specially built to accommodate both a Starnote and a Notecard. Alternatively, you may use your own cable to connect Starnote to a Notecard via male jumper wires inserted into the header pins on the Notecarrier F or Notecarrier A.

Using Notecarrier XS

The Notecarrier XS includes an M.2 connector for both a Starnote and a Notecard Cellular, Notecard WiFi, or Notecard Cell+WiFi device. Both are clearly labeled and the screw connectors are aligned such that each device will only fit in the correct M.2 slot.
Insert a Starnote into the M.2 connector labeled "Starnote" and secure the mounting screw. Both the Starnote with Ignion Antennas and Starnote with u.FL Connectors are compatible with the Notecarrier XS.
Insert a Notecard Cellular, Notecard WiFi, or Notecard Cell+WiFi device into the M.2 connector labeled "Notecard" and secure the mounting screw.

While not pictured here, be sure to attach any required cellular and/or Wi-Fi antennas to the u.FL connectors on the Notecard as well.
If using a Starnote with u.FL Connectors, connect the provided external u.FL antennas. The larger antenna should be connected to the SAT connector and the smaller antenna to the GPS connector.

Using 6-Pin JST Connector

To use the 6-pin JST connector on the front of the Starnote, you'll need a cable that breaks out each of the six pins into its own wire, such as this one. Insert the male connector into the 6-pin JST connector on the face of the Starnote, and then follow this wiring guide for wiring to a Notecarrier F or Notecarrier A:

Connect one or both of the GND wires from the connector to GND on the Notecarrier A or F.
Connect the TX wire to RX on the Notecarrier A, or to N_RX on the Notecarrier F.
Connect the RX wire to TX on the Notecarrier A, or to N_TX on the Notecarrier F.
Connect the VMAIN wire to VMAIN on the Notecarrier A or F.
Connect the VIO wire to VIO on the Notecarrier A, or to N_VIO on the Notecarrier F.

notecard starnote cable connection

Now that you have everything connected, let's look at how to use Starnote to send data.

Sending Data Over Satellite

In this section you'll send your first data over a satellite connection using Starnote.

Re-connect a USB cable from the Notecarrier's USB port to your computer's USB port, and re-open the In-Browser Terminal.

Issue another trace +req command in the In-Browser Terminal to watch serial communications. You should see a series of ntn.* commands similar to the ones shown below, which indicate the Notecard has discovered the Starnote and "paired" with it.

Text

>> {"cmd":"ntn.hello","id":1,"body":{"sku":"NTN-SKY1","ordering_code":"ZZ","apn":"blues.prod","device":"skylo:901980060002842","modem":"CC660DLSAAR01A03_01.001.01.001","iccid":"89901980100600028422","imsi":"901980060002842","imei":"860952060048395","policy":"10TPM","mtu":256,"band":"0","channel":"0","org":"Blues Inc","product":"Starnote","version":"st... (459)
R00:06.18 ntn: skylo:901980060002842
R00:06.19 *** UPDATING PERMANENT CONFIG ***
R00:06.20 config: writing permanent configuration
R00:06.27 packet policy: TPM set to 10
<< {"cmd":"ntn.hello","id":1,"ltime":1717428925,"lat":...,"lon":...}
>> {"cmd":"ntn.status","id":2,"status":"{ntn-idle}"}

(OPTIONAL) Starnote needs to know its location so that it can find overhead satellites. Although Starnote will determine its location during its first transmission, you can expedite testing by manually providing a location. To do so, use the Notecard's card.location.mode request and substitute your current latitude and longitude for the lat and lon arguments.
JSON
```
{"req": "card.location.mode","mode":"fixed","lat":12.3,"lon":45.6}
```
Next, queue a new Note onto the Notecard using the note.add request.
JSON
```
{"req":"note.add","file":"sat.qo","body":{"temp":45.6,"humidity":78.9}}
```
After that, unless you are using external outdoor antenna (see Before You Begin), you need to take your device to a location that has a clear view of the sky, away from buildings and overhead tree cover.

If you are testing outdoors you will also need to bring a laptop that is capable of connecting to the Notecard, sending a hub.sync request, and watching the serial logs. Depending on your setup this might be a bit of a hassle, but remember—you're about to send data to space! It'll all be worth it.
When you're ready to go, trigger an outbound sync with a {"req":"hub.sync","out":true} request. The Notecard will again use NTN mode to send your data, but this time—because you have a Starnote connected—the Notecard will use Starnote to send data over a satellite connection.
JSON
```
{"req":"hub.sync","out":true}
```

Watch the serial communications in the In-Browser Terminal, as it gives detailed information on steps Starnote takes to connect to satellites and send your data. The process may take a few minutes, but when you see an ntn.uplink command you'll know everything worked! 🛰️

Text

S49:31.96 sync: sync triggered by explicit sync request; NTN
S49:31.96 sync: work: begin (anything pending) {sync-begin}
S49:32.02 sync: work to be done:
S49:32.02       upload sat.qo
S49:32.05 ntn: enqueueing note len:11 (port 55)
S49:32.05 sync: work: upload sat.qo (1 changes) {sync-get-local-changes}
S49:32.05 purge sat.qo:
S49:32.05     1 notes (0 stable, 0 queued, 1 tombstones)
S49:32.06  -> 0 notes (0 stable, 0 queued, 0 tombstones)
S49:32.09 sync: work to be done:
S49:32.09       upload sat.qo
S49:32.10 deleting /data/sat-qo.000
S49:32.10 sync: work: completed {sync-end}
S49:32.11 sync: advancing last sync time from 18:57:23Z to 18:57:50Z
S49:32.27 ntn: dequeueing 11-byte note (port 55) into packet (13/254)
S49:32.27 packet: sending 11 bytes (encoded as 13 bytes on-air)
<< {"cmd":"ntn.uplink","id":21,"time":1717441070,"ltime":1717428925,"lat":...,"lon":...,payload":"ADcACwBmZjZCzcydQg=="}
S49:32.47 ntn: sent 11-byte packet containing 1 notes

Return to the Events page in your Notehub project. You should see your data listed in a new Event.

Congratulations! You just sent your first data to space using Starnote. Before we wrap up let's reset a few things.

First, be sure to disable trace mode by sending the trace off command in the In-Browser Terminal.
Code
```
trace off
```
And finally, reset your Notecard's transport method to its default, so that you don't send any more data over satellite until you're ready.
JSON
```
{"req":"card.transport","method":"-"}
```

Next Steps

The power of Starnote is just how easy it makes satellite connectivity, and in this tutorial you saw this ease of use in action.

You learned how Notecard transport methods work, how to use the Notecard's NTN mode, how to connect a physical Starnote, and how to send your first data using satellite connectivity.

Now that you know the basics, 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.