Connection Retry and Fallback Behaviors

Notecard includes a robust retry and fallback system designed to preserve battery life and maintain connectivity across multiple radio access technologies (RATs). When its primary transport cannot establish or sustain a connection, Notecard automatically retries its connection or falls back to alternative transports based on its capabilities and configuration. Understanding how Notecard defines connection attempts, tracks failures, and chooses subsequent transports can help you predict behavior in remote deployments.

This guide explains how Notecard manages connection retries across cellular, Wi-Fi, LoRa, and satellite/NTN, and fallback behaviors as defined in the card.transport API:

• cell-ntn: Cellular with satellite fallback.
• wifi-cell: Wi-Fi with cellular fallback.
• wifi-cell-ntn: Wi-Fi primary, cellular secondary, and satellite fallback.
• wifi-ntn: Wi-Fi with satellite fallback.

Each Notecard radio type (e.g. Wi-Fi, cellular, LoRa, and satellite/NTN) has its own definition of a connection attempt. These attempts determine when failure thresholds are met and when a radio fallback is triggered (if available).

Cellular

Establishing a cellular connection using any cellular-enabled Notecard involves:

1. Powering on the modem.
2. Registering with the cellular network (which depends on the SIM in use, defaulting to the onboard eSIM).
3. Acquiring an IP address.

If any step fails, the entire attempt is considered a failure. What happens next depends on the type of Notecard in use:

• If using Notecard Cellular, after four consecutive failures it will be placed in a network registration penalty box.
• If using Notecard Cellular or Notecard Cell+WiFi paired with a Starnote, and the device is configured to fallback to NTN, then after two consecutive failures it will proceed to attempt a satellite/NTN connection.

Wi-Fi

A Wi-Fi connection attempt using either Notecard Cell+WiFi or Notecard WiFi involves:

1. Scanning for available Wi-Fi access points (APs).
2. Joining the configured AP.
3. Acquiring an IP address from the AP.

If any step fails, the entire attempt is considered a failure. Notecard will automatically retry its Wi-Fi connection or fallback depending on the Notecard in use:

• If using Notecard WiFi only, after four consecutive failures it will be placed in a Wi-Fi penalty box for 60 minutes to prevent unnecessary battery drain (reduced to 5 minutes if USB-powered).
• If using Notecard Cell+WiFi and it is configured to fallback to cellular (the default behavior), it will proceed to attempt a cellular connection after one failure.
• If using Notecard WiFi paired with a Starnote, and the device is configured to fallback to NTN, then after two consecutive failures it will proceed to attempt a satellite/NTN connection.

LoRa

A Notecard for LoRa connection attempt involves connecting to a compatible LoRaWAN gateway, pending any applicable duty cycle restrictions. If no gateway is available, the connection is considered a failure.

After ten consecutive failed attempts to join a LoRaWAN gateway, the device will enter a penalty box and automatically attempt to rejoin 60 minutes later to prevent unnecessary battery drain.

note

There are no supported radio fallback capabilities for Notecard for LoRa.

Satellite

Satellite/NTN connectivity operates differently from traditional networks. Rather than establishing persistent connections, NTN uses a packet-based policy model which involves:

1. Powering on the satellite modem.
2. Waiting for satellite visibility and lock (this can take multiple minutes, depending upon satellite visibility).
3. Sending data packets when a satellite is available.

Notecard will automatically retry Wi-Fi and/or cellular at the next sync opportunity after the penalty box period has expired. The length of time Notecard waits to retry Wi-Fi or cellular is 60 minutes, unless overridden with the card.transport seconds argument.

For example, when using the following request:

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

If the device establishes a successful NTN connection 60 seconds after failing over from cellular, all subsequent sync attempts during the next 840 seconds will continue over NTN. After the full 900 second window expires, Notecard will remain in NTN mode until the next scheduled sync, at which point it will retry cellular.

NTN-Only Retry Behavior

Though not recommended for production applications, Starnote can be used in NTN-only mode:

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

In this scenario, there are no "automatic retries" like you see with cellular and Wi-Fi. Instead, if there are still Notes to sync at the next sync opportunity, Notecard will retry satellite/NTN at that time.

Fallback Summary and Monitoring Tips

The following table summarizes how each transport fallback configuration functions, depending on the Notecard and Starnote in use.

note

You can use the following Notecard APIs to monitor the health of the transport currently in use:

1. Use the card.wireless API to get the last known signal strength and connection status.
2. Use the card.wireless.penalty API to view the current penalty box state.
3. Use the hub.status API to monitor the status of the Notecard's connection to Notehub.
4. Use the hub.sync.status API to check the status of the most recent sync with Notehub.