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. Like cellular-based Notecards, which include prepaid cellular data and service, Starnote includes satellite uplink and downlink data in 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 - Notecard for 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 on the back of the board for use with the included Skylo-certified flexible antennas.

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 >= v9.1.1.

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:
  - A Skylo-certified external LTE antenna (i.e. the flexible antenna that ships with Starnote).
  - An external GPS/GNSS antenna (though the Starnote can use fixed location coordinates for testing).
A Notecarrier XS.

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.

warning

For a Note synced with Starnote for Skylo, the minimum packet size is 50 bytes and the maximum packet size is 256 bytes. You are billed based on that packet size.

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.
```
{"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.
```
{"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.
```
{"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.
```
{"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.
```
{"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.
```
{"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. 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.
```
{"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.
```
{"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.

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.

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.
```
{"req":"card.transport","method":"-"}
```

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.

warning

When you integrate a host MCU to communicate with Notecard/Starnote after completing this guide, please note that your host must interface with Notecard using I2C or AUX UART, as Starnote connects to your Notecard via standard UART.

Learn more about how to interface with a Notecard from a host in Notecard Interfaces.

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.

notecarrier xs

Disconnect the USB cable from your Notecarrier XS, if still connected from the previous section.
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:

Disconnect the USB cable from your Notecarrier XS, if still connected from the previous section.
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 pair a Starnote to a Notecard.

Pairing a Starnote

When a Notecard first detects a connected Starnote it will pair with the module. Once paired, a Notecard will look for its paired Starnote every time it restarts, and will report errors if it can’t connect. The pairing process happens automatically when you power on a Notecard and it's connected to a Starnote via UART (as shown in the previous section).

Let’s look at how it works.

Re-connect a USB cable from the Notecarrier's USB port to your computer's USB port, and re-open the In-Browser Terminal.
After Starnote is powered on, run a hub.sync request over cellular or Wi-Fi. This will ensure that any additional templates and this new association between Notecard and Starnote are communicated with Notehub.
```
{"req":"hub.sync"}
```
After the sync is completed, run a ntn.status request, which will report on the status of any connected NTN modules. If all went well, you should see {ntn-idle} in the response, which indicates that your Starnote has paired and is idle.
>
```
{"req":"ntn.status"}
```
```
{"status":"{ntn-idle}{ntn-unknown-location}"}
```

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.

Sending Data Over Satellite

Now that you have your Starnote paired, let's use it to send your first data over a satellite connection.

Starnote needs to know its location so that it can find overhead satellites. Although Starnote will determine its location during its first transmission using its onboard GPS module, you can (optionally) expedite this process by manually providing a location.

(Optional) To provide a fixed location, use the Notecard's card.location.mode API and substitute your current latitude and longitude for the lat and lon arguments.
```
{"req":"card.location.mode","mode":"fixed","lat":12.3,"lon":45.6}
```
If you take this approach, you'll also need to use the Notecard's ntn.gps request to tell the Notecard to use its internal GPS data (which in this case has the hardcoded location), instead of using the GPS data from the connected Starnote.
```
{"req":"ntn.gps","on":true}
```
Issue another trace +req command in the In-Browser Terminal to watch serial communications.
```
trace +req
```
warning
If you notice from your log that your Notecard is actively syncing data over cellular or Wi-Fi, please wait for it to finish before proceeding to the next step.
After that, turn on NTN mode with the card.transport API.
```
{"req":"card.transport","method":"ntn"}
```

Next, queue a new Note onto the Notecard using the note.add request.

{"req":"note.add","file":"sat.qo","body":{"temp":45.6,"humidity":78.9}}

After that, 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.
```
{"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! 🛰️

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.

Having trouble connecting?

Satellite communications are notoriously difficult to get right, due to all of the variables involved. Here are some of the more common issues to be aware of:

Give it time. It can take multiple minutes for Starnote to find and communicate with Skylo's GEO satellites that sit above the equator. Double check that your antenna is free from obstructions and has a clear view of the southern sky (from the northern hemisphere) or northern sky (from the southern hemisphere).
Make sure you have successfully synced any and all templates with Notehub over cellular or Wi-Fi before attempting NTN communications with Starnote.
Likewise, after physically connecting Starnote to your Notecard, be sure to perform a sync over cellular or Wi-Fi before attempting to use NTN mode.
Due to the nature of satellite communications, sometimes packets are simply lost. If a single Note appears to have been sent (according to your Notecard) but does not appear in Notehub, this could be the case.

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.
```
trace off
```
Next, if you used hardcoded GPS coordinates for your device's location during testing, you'll likely want to reset the ntn.gps request so that you use the GPS location from your Starnote moving forward.
```
{"req":"ntn.gps","off":true}
```
Lastly, set your Notecard's transport method to an appropriate value for your product, so you don't send any more data over satellite until you're ready. For example:
```
{"req":"card.transport","method":"wifi-cell-ntn"}
```

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.