Introduction

This tutorial should take approximately 40–50 minutes to complete.

This guide will introduce you to Starnote for Iridium, an affordable satellite IoT fallback device. Like cellular-based Notecards, which include prepaid cellular data and service, Starnote for Iridium includes satellite uplink and downlink data in the cost of the device.

Starnote for Iridium 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 for Iridium is a cost-optimized "Notecard accessory" and must be paired with a Notecard device to function (specifically a Notecard Cellular, Notecard Cell+WiFi, or Notecard WiFi - Notecard for LoRa is not supported for use with Starnote for Iridium).

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 Notecard handles communications between itself and Starnote.

Before You Begin

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 or Microsoft Edge.

• A free Notehub.io account.

• A Notecard Cellular, Notecard Cell+WiFi, or Notecard WiFi device on firmware version >= v10.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.

• A Starnote for Iridium.

• A Notecarrier XI.

• A LiPo battery.

Understanding NTN Transport Mode

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

For satellite, Notecard also supports a transport mode called NTN (Non-Terrestrial Networks), which enables communication via Iridium’s satellite network.

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 a Starnote device. 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 Iridium 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.

Here's what the connection looks like using a Notecard Cellular.

1. Connect a USB cable from the Notecarrier's USB port to your computer's USB port.

2. 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.

   

3. Reset your Notecard's transport method to its default mode with the card.transport API.

   COPY

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

4. 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.

   COPY

   {"req":"card.wifi","ssid":"your-network-name","password":"your-network-password"}

5. 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.

   COPY

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

6. 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.

   COPY

   {"req":"note.template","file":"config.qi","format":"compact","port":44,"body":{"cmd":"*"}}

7. 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.

   COPY

   {"req":"hub.set","product":"com.your.domain:product","mode":"minimum"}

8. 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.

   COPY

   {"req":"hub.sync"}

   note

   These configuration settings persist across both Starnote and Notecard restarts. This means that once you create or update a template and perform a single sync over cellular or Wi-Fi, the changes are retained. If the device restarts, you do not need to re-establish a new cellular or Wi-Fi connection with Notehub as the stored configuration remains in effect.

9. Watch the progress bar in the In-Browser Terminal for updates on the syncing process.

   warning

   You must wait for your Notecard to complete a full sync with Notehub before you proceed to the next step!

   

10. Once the sync with Notehub is complete, turn on NTN mode with the card.transport API.

    COPY

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

    warning

    We do not recommend using "method":"ntn" in production. When using a physical Starnote, NTN mode will force Notecard to send all data over satellite, which may inadvertently consume your data allocation.

11. Add a Note to a templated Notefile. For example:

    COPY

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

12. Next, enable trace mode on your Notecard.

    COPY

    trace +req

    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 requests to and from Notecard and Starnote.

13. Send a hub.sync request to sync data over NTN, using the out argument to only sync pending outbound data.

    COPY

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

14. If you need to instruct your Notecard and Starnote to check for inbound data, you must use the in argument of the hub.sync API.

    COPY

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

15. 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.

    COPY

    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

16. IMPORTANT: Be sure to disable trace mode by sending the trace off command in the In-Browser Terminal.

    COPY

    trace off

17. 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.

18. At this point you can reset the transport mode of your Notecard to restore it to prioritizing cellular or Wi-Fi communications.

    COPY

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

Connecting a Starnote

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

Starnote for Iridium must be connected to a Notecard via UART, and the easiest way to make this connection is through a Notecarrier XI. Complete the following steps to connect the two.

1. Remove the remaining screw on your Notecarrier XI and insert your Starnote for Iridium into the M.2 connector.

2. Attach the included Iridium satellite antenna to the u.FL connector on your Starnote for Iridium. When seated properly, you will feel the connector "click" into place.

3. Connect a LiPo battery to the Notecarrier XI's LIPO JST connector. The LiPo battery must remain connected even when also powering the Notecarrier XI via USB, as the Starnote for Iridium modem can draw up to 8.5A during transmission.

Now that you have everything connected, let's look at how to pair a Starnote for Iridium 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.

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

2. After Notecard and Starnote power 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.

   COPY

   {"req":"hub.sync"}

3. 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.

   COPY

   >

   {"req":"ntn.status"}

   {"status":"{ntn-idle}{ntn-unknown-location}"}

Sending Data Over Satellite

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

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

1. (Optional) To provide a fixed location, use Notecard's card.location.mode API and substitute your current latitude and longitude for the lat and lon arguments.

   COPY

   {"req":"card.location.mode","mode":"fixed","lat":12.3,"lon":45.6}

   If you take this approach, you'll also need to use Notecard's ntn.gps request to tell 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 for Iridium.

   COPY

   {"req":"ntn.gps","on":true}

2. Issue another trace +req command in the In-Browser Terminal to watch serial communications.

   COPY

   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.

3. After that, turn on NTN mode with the card.transport API.

   COPY

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

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

   COPY

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

5. 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.

6. When you're ready to go, trigger an outbound sync with a {"req":"hub.sync","out":true} request. Notecard will again use NTN mode to send your data, but this time—because you have a Starnote for Iridium connected—your Notecard will use Starnote for Iridium to send data over a satellite connection.

   COPY

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

7. Watch the serial communications in the In-Browser Terminal, as it gives detailed information on steps Starnote for Iridium 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! 🛰️

   COPY

   S10:44.01 sync: sync triggered by explicit sync request
   S10:44.02 sync: work: begin (anything pending) {sync-begin}
   S10:44.08 sync: work to be done:
   S10:44.09       upload sat.qo
   S10:44.11 ntn: enqueueing 9-byte note from sat.qo (port 55)
   S10:44.11 sync: work: upload sat.qo (1 changes) {sync-get-local-changes}
   S10:44.12 purge sat.qo:
   S10:44.12     1 notes (0 stable, 0 queued, 1 tombstones)
   S10:44.12  -> 0 notes (0 stable, 0 queued, 0 tombstones)
   S10:44.14 sync: work to be done:
   S10:44.15       upload sat.qo
   S10:44.16 deleting /data/sat-qo.000
   S10:44.16 sync: work: completed {sync-end}
   S10:44.17 sync: advancing last sync time from 20:11:30Z to 20:19:41Z
   S10:44.28 ntn: moved 9-byte note (port 55) into packet (11/338)
   S10:44.29 packet: sending 9 bytes (encoded as 11 bytes on-air)
   << {"cmd":"ntn.uplink","id":17,"time":1767730781,"ltime":1767730288,"lat":...,"lon":...,"payload":"ADeAZmY2Qs3MnUI="}
   S10:44.55 ntn: sent 9-byte packet containing 1 notes

   note

   The website iridiumwhere.com displays a real-time map of the Iridium satellite constellation, and can tell you how many satellites should be in view at your location. If you’re having trouble transmitting you may need to wait until more satellites are visible.

8. 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 for Iridium to find and communicate with Iridium's LEO satellites. Double check that your antenna is free from obstructions.

• Make sure you have successfully synced any and all templates with Notehub over cellular or Wi-Fi before attempting NTN communications with Starnote for Iridium.

• Likewise, after physically connecting Starnote for Iridium 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.

1. First, be sure to disable trace mode by sending the trace off command in the In-Browser Terminal.

   COPY

   trace off

2. 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 for Iridium moving forward.

   COPY

   {"req":"ntn.gps","off":true}

3. 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:

   COPY

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

Next Steps

The power of Starnote for Iridium 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 for Iridium, 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 for Iridium. At any time, if you find yourself stuck, please reach out on the community forum.