Skip to main content

Send BoatKit alerts over Meshtastic LoRa

BoatKit can copy vessel notifications to a Meshtastic LoRa channel without an internet connection. A Meshtastic radio connected to the dedicated BoatKit device transmits the messages. A second Meshtastic radio connected to your iPhone, iPad, or Android device receives them, and the BoatKit app turns messages for that vessel into local notifications.

BoatKit uses Meshtastic's shared client protocol, so the integration is not a separate driver for each radio board. A device must run compatible Meshtastic firmware and expose its standard USB serial or Bluetooth LE interface. The Heltec WiFi LoRa 32 V4 is the initial vessel-side target; the SenseCAP T1000-E and Heltec Mesh Node T1 are initial mobile-receiver targets. Confirm behavior with the firmware version and regional radio configuration you plan to use before relying on a particular installation.

The connection also provides a narrow, read-only fallback view when the normal LAN or internet path is unavailable. This is a supplemental awareness path, not a distress, fire, security, or certified marine alarm system. LoRa delivery depends on radio power, antenna installation, terrain, interference, regional airtime rules, and the mesh between the radios. BoatKit does not receive a delivery guarantee from the recipient phone.

Before you start​

You need:

  • A dedicated BoatKit device with an available USB data port.
  • A Meshtastic radio for the boat, with a suitable antenna, USB data cable, and reliable power.
  • A Bluetooth-capable Meshtastic radio carried with the phone or tablet.
  • The official Meshtastic app for the initial radio configuration.
  • The BoatKit native app on iOS, iPadOS, or Android. A normal browser cannot maintain the required Bluetooth receiver connection.

Both Meshtastic radios must use the correct regulatory region and the same channel slot and channel key. Set these on the radios with the official Meshtastic app. BoatKit deliberately does not copy or store the channel key.

Configure the radios​

  1. Install current compatible Meshtastic firmware on both radios by following the Meshtastic device instructions.
  2. In the official Meshtastic app, set the correct regulatory region on each radio.
  3. Configure the same private channel in the same channel slot on each radio.
  4. Confirm that an ordinary text message sent by either radio appears on the other before introducing BoatKit.
  5. Disconnect or close the official app's active Bluetooth session to the phone-side receiver. The BoatKit app needs that Bluetooth connection while it is listening.

Do not transmit without the correct antenna attached. Follow Meshtastic's regional configuration guidance and all applicable radio rules.

Connect the boat radio​

  1. Connect the boat radio to the dedicated BoatKit device with a USB data cable. A charge-only cable will power the radio but will not expose it to BoatKit.
  2. In BoatKit, open Settings > Integrations > Add Integration.
  3. Choose Radios & LoRa, then Meshtastic LoRa.
  4. Under Boat Radio, select the USB Meshtastic radio.
  5. Select the zero-based channel slot that you configured on the radios. Channel 0 means the first Meshtastic channel.
  6. Enable Meshtastic LoRa.
  7. Confirm that Connection Status changes to Connected.

BoatKit reserves the selected serial interface while the integration is enabled so another integration cannot open the same radio.

Choose what BoatKit sends​

Under Alert Messages, choose which normalized BoatKit severities should be copied to LoRa. Warnings and alarms are enabled by default; routine notifications are disabled by default to reduce radio traffic.

BoatKit sends each event as an ordinary Meshtastic text message. The visible text remains readable in a standard Meshtastic client. It also includes a compact BoatKit marker so the native BoatKit app can associate it with the selected vessel and choose the matching notification severity.

Under Scheduled Reports, you can also select a report interval and include:

  • The current GPS latitude and longitude, when a valid position is available.
  • The current distance from the anchor point and anchor-alarm state, when the anchor alarm is enabled and position is valid.

Use the longest interval that meets your needs. LoRa capacity and permitted airtime are limited, and scheduled reports share the same channel with alerts and other Meshtastic traffic.

Read BoatKit stores over LoRa​

While the integration is connected, BoatKit sends filtered Restream full-state keyframes on Meshtastic's private application port. These are the same compact generated binary states used by the normal Viewer, wrapped with a small LoRa header for vessel and session identity, sequence, fragmentation, checksum, and optional zlib compression. This first protocol version is read-only and never carries RPCs or control commands.

The transport is deliberately hybrid:

  • Once per minute, the vessel broadcasts filtered VesselInfo, AnchorAlarm, and active Alarm state. This baseline needs no return path and repairs packet loss with the next complete keyframe.
  • When the phone can transmit back to the vessel, it sends a short subscription request for an allowlisted extra store that the open Viewer actually uses. The first extra store is PowerSystem, reduced to recognizable enabled items, slow measurements, and operating state. Source identities, device registers, alert thresholds, and management configuration are omitted.
  • Subscribed updates are directed to that Meshtastic node, request the radio's normal routing acknowledgement, and receive a BoatKit application ACK after the native app has reassembled and validated the state. The first response is a full keyframe; later responses use BoatKit's generated Restream partial encoding when it is smaller, based only on application-acknowledged state. Subscription renewal periodically forces another full keyframe. A missing uplink does not stop the broadcast baseline.

The native receiver continuously collects keyframes, and the Viewer drains them while it is running. A healthy authenticated LAN or BoatKit Cloud connection remains authoritative and LoRa states are discarded. When that path fails, the Viewer requests a fresh subscribed-store keyframe and will not apply partials until it has accepted that LoRa full-state base. It then applies LoRa bytes through the same generated Restream decoders. A normal full snapshot automatically takes authority again after reconnect.

This source arbitration does not make the complete Viewer available over LoRa. Pages may still show disconnected status, RPCs remain unavailable, and only the explicit projected stores have fresh data. Text alerts continue alongside the binary stream so alarm-severity events can wake the native app and use the critical-alert presentation without waiting for the next keyframe.

BoatKit also listens to the radio's transmit-queue status. If that small queue fills, routine store frames pause and each peer/store keeps only its newest unsent update. This makes delay turn into lower update frequency instead of a growing backlog of stale vessel data.

Pair the receiver with this phone​

This setting belongs only to the current phone and the selected vessel. Repeat it on each phone that should listen through its own Meshtastic receiver.

  1. Open the BoatKit native app and connect to the vessel whose Meshtastic integration you configured.
  2. Return to Settings > Integrations > Meshtastic LoRa.
  3. Under This Phone's Receiver, select Scan and allow Bluetooth or nearby-device access when prompted.
  4. Choose the nearby receiver and allow BoatKit notifications. On iOS or iPadOS, also allow Critical Alerts so alarm-severity LoRa messages can sound through silent mode and Focus.
  5. Keep the receiver powered, nearby, and configured on the same Meshtastic channel as the boat radio.

BoatKit ignores ordinary Meshtastic conversation in its notification path. It surfaces only BoatKit-marked messages for the vessel selected when the receiver was paired.

iPhone and iPad behavior​

BoatKit uses iOS's standard Bluetooth-central background mode. Adding this mode does not require a special Apple entitlement or approval. When the receiver is connected, a matching LoRa message can wake the app in the background long enough to post a local notification.

The user must grant Bluetooth and notification permission. BoatKit requests Critical Alerts permission when the receiver is paired. An alarm-severity LoRa message uses BoatKit's approved Critical Alerts capability when the user has allowed it, including BoatKit's critical alarm sound. Warnings remain time sensitive, and routine notifications remain active. If Critical Alerts are not authorized, an alarm falls back to a time-sensitive notification rather than being discarded.

If the user force-quits BoatKit, iOS will not relaunch it for Bluetooth events until the app is opened again.

Android behavior​

Android keeps the paired receiver connection in a foreground connected-device service. Android shows a persistent low-priority service notification while BoatKit is listening. Alarm-severity LoRa messages use BoatKit's Critical vessel alarms channel when its Do Not Disturb access and sound are enabled, with the normal alarm channel as a fallback. The user must grant nearby-device and notification permission, and device-specific battery restrictions can still interrupt the connection.

Test the complete path​

Avoid creating an unsafe condition just to test an alarm.

  1. Temporarily enable Send notifications under Alert Messages if the notification test will use the routine notification level.
  2. Use BoatKit's delivery test on the Notifications settings page.
  3. Confirm that the text appears in a standard Meshtastic client on the receiver.
  4. Lock the phone and confirm that BoatKit posts and sounds a local notification.
  5. Open the notification and confirm that BoatKit selects the intended vessel.

Repeat the test at the real separation and with the antenna installation you intend to use. A successful bench test does not establish range at a marina, through buildings, or across changing terrain.

Backups, privacy, and offline operation​

The selected boat-side serial identity, channel slot, alert policy, and report schedule are vessel configuration and are included in BoatKit's portable backup. Channel keys stay on the radios and are not included. The phone-side receiver pairing is local to that mobile app installation and is not part of a vessel backup.

Messages travel through the selected Meshtastic channel, not through BoatKit Cloud. Internet access is not required for this message path after the vessel and radios are configured. Normal BoatKit device registration still applies.

Troubleshooting​

The boat radio does not appear​

  • Confirm that the cable carries data, not only power.
  • Confirm that the radio runs Meshtastic firmware and exposes its USB serial interface.
  • Disconnect other programs that may have opened the same serial port.
  • Reconnect the radio, then reopen the integration settings and look for the device again.

BoatKit reports a handshake or reconnect error​

  • Confirm that the selected serial device is the Meshtastic radio.
  • Confirm that another Meshtastic client is not holding the USB connection.
  • Restart only the radio, then allow BoatKit to reconnect. Do not erase its channel configuration unless you intend to configure both radios again.
  • Record the BoatKit and Meshtastic firmware versions if the error continues.

The phone does not find the receiver​

  • Keep the receiver awake, powered, and close to the phone during the scan.
  • Disconnect the receiver from the official Meshtastic app or another phone.
  • Confirm that Bluetooth is on and BoatKit has Bluetooth or nearby-device permission.
  • On iOS, reopen BoatKit after a force-quit.

Text arrives in Meshtastic but BoatKit shows no notification​

  • Confirm that the receiver was paired while BoatKit was connected to the intended vessel.
  • Confirm that BoatKit notification permission is enabled in system settings.
  • Check Focus, silent, and per-app notification settings on iOS, or notification and battery settings on Android.
  • Confirm that the received message ends with a BoatKit marker. Ordinary Meshtastic text is intentionally not turned into a BoatKit notification.

No message arrives on the receiving radio​

  • Recheck the region, channel slot, and channel key on both radios.
  • First test ordinary text between the radios with the official Meshtastic app.
  • Check power, antenna connection and placement, distance, terrain, and nearby radio interference.
  • Confirm that BoatKit reports Connected and shows a recent Last Message time after it transmits.

Meshtastic is a third-party project and trademark. BoatKit is not certified or endorsed by Meshtastic.