Skip to content

Update remote firmware over LoRa

Connect a source radio by USB, Wi-Fi, or Bluetooth, choose the remote device, then prepare and start its update. Keep the browser open until the new firmware is verified. This updater is experimental. USB requires Chrome or Edge on a computer with a Companion or compatible Repeater. Wi-Fi requires a compatible Companion on the same local network as your phone or computer. Bluetooth requires a compatible Companion with Bluetooth OTA support. On Android, use Chrome.

Connect your source radio to get started.

1. Connect and choose the remote device

USB connection options

The source radio sends the update over LoRa. Choose the remote device and enter its admin password if needed.

Connect your source radio to choose the remote device.

2. Prepare firmware

Select the remote device, then choose Find matching firmware.

Use a local file or an installed firmware image

Get firmware from GitHub releases

To make a smaller differential update, also select the exact firmware currently installed on the target.

A staged update is discarded only if you choose Replace and install update.

Prepare update checks the firmware and link, and finds a fitting update path. Intermediate updates, when needed, run automatically.

Checking this browser's transfer compression options...

After radio2 is verified, radio1 floods pause. Older firmware pauses forwarding on both profiles. Keep this page open until forwarding is restored.

Update path options

On first use, a two-second local test chooses a suitable default and saves it in this browser. You can change the choice at any time.

Zopfli prepares every block before the transfer and may take a long time for large updates, especially on older phones. It is used when the target supports compressed blocks. Path estimates use fast compression and are approximate.

Deep search compares every page-aligned rewrite workspace and published bridge candidate for these exact images. Every patch must fit and reconstruct its complete firmware. Estimates exclude retries.

3. Update the remote device

The selected firmware will be sent over LoRa, installed and verified automatically.

Separate transfer, resume and install controls

Advanced settings and diagnostics
Update channel and manual radio setup

Prepare update configures both radios and tests the link. The target's normal radio2 may pause during the update; its saved settings return after reboot or temporary-window expiry. Primary-channel fallback starts with a two-minute trial. Saved radio settings stay unchanged.

When both devices support it and their temporary radio settings are free, the default uses a 120-minute radio2 window 200 kHz above the current primary channel. Existing temporary settings can be reused when compatible; mismatched settings may require manual attention. Choose a region or edit the settings to override the automatic choice. Regional defaults and limits.

Update channel options

Detected from recognized radio settings. Choose a region to override.

Setup turns automatic OTA fetch/install off and sets OTA hops to 0. These OTA preferences are saved; any changes appear in the diagnostic log. RX power saving stays unchanged.

Connect and choose the remote device first.

Manual setup and older firmware

No manual channel commands are needed for direct updates with supported source radio controls. Firmware without those controls needs a Companion update for automatic setup.

For manual setup, apply the command on the target first, then the source radio. Every relay also needs matching settings; automatic route preparation is not supported.

Choose the update frequency to show the temporary command.
Advanced connection and firmware options

Repeater forwarding

Optionally change forwarding on the source or target. The radio flood settings leave direct-route messages enabled; all forwarding controls both. These saved settings need firmware that supports them. A relay used by the selected route must keep forwarding on. To manage a different repeater, connect with that repeater as the target first. Restore the setting afterward if needed.

Multi-version nRF52 update

If you reopen this page during a multi-version update, connect the same source and select Resume saved update. If browser storage was unavailable, reselect the exact original firmware files and planning settings, then choose Compare paths and Resume saved path.

For nRF52 internal staging, choose the exact installed firmware above, the final firmware above, and optionally up to six intermediate images below. Each intermediate must contain OTA receiver evidence; the actual node is checked after every reboot. Prepared packages are unsigned. Use the single-update controls above for ESP32 or nRF52 with external storage.

For supported RAK3401 and RAK4631 internal-storage OTAFIX builds, the browser simulates every selected differential using the identified bootloader. The simulation does not replace testing intermediates on the actual hardware. Full-package intermediate steps are not yet modeled.

Estimates exclude retries, status polls and congestion. Use the single-update controls for an actual update.

Diagnostic log

  

Resume an interrupted update

The browser remembers your connection, target and update choices. When you start a transfer, it also tries to save the selected firmware files in this browser. After reopening the page, connect the same source and select Resume saved update. The updater checks the target and saved package before offering the next step. It does not save your admin password; leave it blank when the source already has access through the target's ACL.

For a manually assembled multi-version path, Resume saved update restores the saved plan and offers Resume saved path. If the browser could not save the plan, reselect the original firmware files and planning settings, then use Compare paths and Resume saved path.

Browser storage can be unavailable, cleared, or full. If the firmware cannot be saved, the updater warns you to keep the original files so you can select them again. Saved choices and firmware stay on this device and are not synced to another browser or phone. Forgetting saved firmware does not cancel the target's update. A shared automatic-path cache may remain in this browser.

Bluetooth Companion connection

Turn on Bluetooth and disconnect the Companion from other apps. Select Bluetooth Companion, then Connect Bluetooth Companion and choose the radio. On Android, open this page in Chrome. Allow Bluetooth access if prompted.

The Companion must have firmware that supports Bluetooth OTA. Bluetooth updates require a direct, zero-hop LoRa connection between the Companion and the remote device. Keep the phone near the Companion and leave the browser open during the update.

Wi-Fi Companion connection

Connect your phone and the Companion to the same trusted Wi-Fi network. Select Wi-Fi Companion above, enter the Companion's private IPv4 address, and connect. No computer or local bridge is required. You can also scan one private /24 network using Find a Wi-Fi Companion. Your browser may ask for local-network access; allow it to connect or scan. If the prompt appears during a scan, scan again after allowing access. A scan sends a read-only discovery request and does not change device settings. Disconnect other apps from the Companion for the duration of the update.

Direct Wi-Fi requires a Companion built with the browser Wi-Fi OTA endpoint; older USB-only or bridge-only builds need a firmware update first. Repeater sources use USB. To enable Wi-Fi and find the Companion's address, see Wi-Fi Companion setup. The local connection is not encrypted; use a trusted network. Browser support for local network access varies; on Android, try current Chrome if your browser blocks local access. iPhone browser support has not yet been verified. A failed scan can also mean that the network prefix or device address is wrong, or the browser blocked local network access.

If the connection drops, reconnect the same source and check its state before continuing. The update is not automatically restarted or installed again.

Compatibility and advanced update details

Automatic intermediate updates

Prepare update compares compatible published application bridges automatically. Update remote firmware transfers, installs and verifies each selected step, then prepares the next radio window. Progress shows the current step. After an interruption, use Prepare update and Continue firmware update; the exact plan and completed steps are saved in this browser.

A connection failure before step 1 creates its transfer record can still be recovered. The browser rechecks the exact starting image and package, confirms the target has no staged download, and then starts that same first step. A missing record never authorizes replacing staged data or repeating an uncertain install. Existing mismatched or unreadable recovery records are retained and reported as local saved-state errors.

If an explicitly requested replacement was cancelled before a connection failure, the same saved step can continue once fresh checks prove the original firmware and an idle target. Cancellation is not sent again to guess its result.

Under Update path options, choose fewer installs or less radio data. Deep search also checks every page-aligned workspace that could fit. It takes longer and can be stopped before uploading firmware. Estimates exclude retries and other mesh traffic. The comparison covers the published candidates for the two exact images; it does not guarantee the best possible route through all firmware ever built.

The initial published bridge bank covers the GAT562 30S Mesh Kit repeater from the original 1.18.0.1 Full image to 1.18.0.2 Full. Its hybrid staging requires confirmed retained-RAM support. These are application updates; the bootloader and saved settings are retained.

Bootloader RAM staging cutoff

OTAFIX 2.4.6 introduced the extra 64 KiB of retained RAM for normal internal-storage nRF52840 bootloaders. It holds part of the update package across a software reset; removing power loses that part of the transfer.

Installed bootloader Retained-RAM staging
Stock Adafruit or OTAFIX 2.4.5 and earlier Not available from the version alone.
Official stable OTAFIX 2.4.6 through 2.4.12, normal internal-storage profile Available; the browser checks the version and live internal-storage identity.
External-only QSPI or SD profile Uses its storage backend; the version does not establish a RAM arena.
Custom, preview, unknown or another release family Requires an explicit ota ram capability or an exact verified bootloader identity.

The browser reads ota ram first. When older application firmware does not provide it, the browser uses get bootloader.ver with ota bootloader status. The version fallback requires a reviewed stable 2.4.6-2.4.12 version, ABI 3, internal profile caps=0A, and a hybrid application with expanded ED000 staging. Normal adaptive RAK3401/RAK4631 2.4.10 and later also report that internal profile. SD/internal combined profiles still require the explicit RAM capability or exact identity check.

An explicit hybrid=0 is never overridden by the version. A bare 0.11.0 (base), missing reply, or timeout does not establish support. The exact published GAT562 OTAFIX 2.4.12 identity and CRC remains a fallback when the older version reader cannot identify it. A larger version in another OTAFIX lineage is not assumed compatible.

Preparation failures include the installed and selected filenames, versions, full firmware hashes, retained-RAM check, search result and flash budget in the diagnostic log. Passwords and local file paths are omitted.

About guarded OTA

Guarded OTA keeps update replies separate from normal messages and checks the source radio during the update. The updater selects it automatically when the Companion supports it. Both modes verify the target's public key before updating.

Older USB Companions use their shared message queue. Unrelated pending messages may be saved in this browser and cannot be restored to the Companion. Wi-Fi requires guarded OTA and cannot use this older shared-queue path. Keep other apps disconnected and avoid changing radio settings during the update.

Older Keymind Cascade Full Companions can use their existing USB mOTA firmware-source mode. The page selects it automatically when the older 176-byte command limit prevents raw-packet updates, then restores Binary Companion mode for status checks and when finished. No manual mode change or Companion firmware update is needed when that capability is available.

Newer Companions can send complete OTA packets directly when get usb.raw.max reports 188. A Companion without either capability needs updated firmware; the page checks before changing the target. Older remote devices remain supported when their firmware includes compatible LoRa OTA.

For generated nRF52 hybrid internal-storage updates larger than one flash page, the updater checks the target's bootloader RAM capability before starting and checks it again for each intermediate update. If the running firmware cannot confirm that capability, those updates are unavailable; smaller updates are not affected by this check.

Setup and advanced details

Regional update defaults and limits

Fast profiles use SF5, CR7; known SX127x radios use SF7. Auto matches the saved frequency, bandwidth, spreading factor and coding rate against a checked snapshot of the MeshCore community suggestions. These identify suggested profiles, not a device's country or certification. Choose Region under Update channel options to override the suggestion.

Area Update MHz / BW kHz Operating limits and reference
EU / UK, including the matching Swiss profile 869.525 / 250 500 mW ERP; 10% duty cycle or the applicable compliant channel-access alternative. EU decision, UK IR 2030, Swiss RIR1008-09.
EU / UK 433 MHz 433.925 / 250 10 mW ERP and 10% duty cycle for this operating category. EU decision, UK IR 2030.
US / Canada 909.950 / 500 The fixed-channel DTS category requires measured 6 dB bandwidth of at least 500 kHz; nominal BW500 alone does not establish equipment compliance. Power, spectral density and antenna limits also apply. FCC §15.247, ISED RSS-247.
Costa Rica 909.950 / 250 This segment permits up to 24 dBm conducted / 30 dBm EIRP, subject to equipment approval. 2026 decree, Table 22.
Australia 921.500 / 250 Digital modulation: up to 1 W EIRP and 25 mW per 3 kHz radiated peak power density. LIPD 2025, Table 8 / clause 43.
Brazil 921.500 / 500 New fixed-channel digital certifications require measured 6 dB bandwidth of at least 500 kHz, plus power and spectral-density limits. Previously approved equipment can retain its original requirements. Ato 14448, 2026 transition.
Thailand 921.500 / 250 Fixed-channel duty limits depend on EIRP: 1% below 50 mW, 10% above 50 mW; higher powers can require an operating licence. NBTC standard, authorization rules.
Vietnam 921.500 / 250 Licence-exempt LPWAN: up to 25 mW ERP, 1% endpoint / 10% qualifying access-station duty cycle. A repeater is not automatically a qualifying gateway. 2025 consolidated rules, Appendix 19.

The shared Australia/Brazil community preset selects 921.500 / 500; choosing Australia explicitly selects BW250. New Zealand and unknown custom profiles retain their saved settings: the full conditions of the current New Zealand SRD licence were not verified for a new fast profile.

Profiles select the update channel. Existing power and airtime settings are retained; the browser does not raise them or certify antenna gain, actual emissions or equipment approval. Both radios must already satisfy the applicable power and duty-cycle limits. Limits checked 10 November 2026.

Direct updates were tested over LoRa with a released 1.18.0.1 Full Companion: transfer recovery, automatic window extension, stopping, replacing firmware, installation and post-reboot verification passed. See the Mercerwood test results. Repeater-source and multi-hop hardware tests remain unverified. This updater is experimental.

Guarded mode requires a custom Keymind Cascade Full Companion built from commit bede4d85f or later with both guarded features enabled. The 1.18.0.1 release and published 1.18.0.2 previews do not have both features.

Investigation retries unanswered checks. Download, install and cancel commands are not automatically repeated after an uncertain reply. Older targets validate the staged image with ota install, but cannot bind the full container hash before installation. The updater checks the reported firmware identity and body hash after reboot. For direct updates, it reads the target's saved channel before installing and automatically reconnects there after reboot. Any source retune is temporary; saved radio channels are unchanged.

The source needs a compatible Companion with raw packet support, or a USB Repeater with ota.peer and USB folder support. Wi-Fi also requires the guarded OTA support described above. Older USB Companions use their shared message queue: unrelated messages moved into the browser can be downloaded, but cannot be restored to the Companion. The page prepares the update channel and required OTA preferences automatically on compatible direct connections. Once data transfer starts, long updates can extend temporary windows that this browser set up and can still verify. Existing or unverified windows retain their original deadline. The required OTA policy changes remain saved and are listed in the diagnostic log. RX power saving is not changed or required to be off; radio2 handles its own receive mode. Missing setting acknowledgements are checked automatically before setup continues. On older Companions with USB radio controls, the page automatically aligns both temporary channels with the Companion's saved settings. It tests primary channels with a two-minute window before extending them; temporary radio2 uses the full window. With compatible devices and no existing temporary primary or radio2 window, the default first prepares temporary radio2 on the current primary channel, then shifts it 200 kHz above that channel before serving blocks. It verifies the target and both radio settings, and leaves primary reception available. A 200 kHz offset may overlap wider channels; the setup log reports this. A missing USB reply during setup stops the operation and requires reconnecting. With a Companion that can select temporary radio2, the page first sends the target's temporary-channel request over the already-proven primary link. Only afterward does it enable source radio2 and test the requested channel. This avoids changing the source's receive scanning and automatic preamble before the target is ready. A lost request reply is checked on the requested channel, not blindly sent again. An adopted matching target window is checked on its current update channel; the browser does not require it to answer on an old channel it has left. Probe timeouts account for radio airtime and allow at least five seconds for a reply. Read-only Companion CLI checks use up to seven attempts before a target response and eleven after one is confirmed. The channel handoff still has one 90-second deadline, which can stop those reads sooner. Only read-only identity and state checks are retried; a target switch still requires a fresh full-key proof on the original channel. Failures retain the command, stage and selected radio, rather than hiding the underlying timeout. The log shows the cached saved and temporary target settings and labels each CLI check as original primary or temporary OTA radio2. A temporary primary window can make a target unreachable on its saved channel until the window expires; remote silence alone does not prove the processor has hung. The browser checks the requested channel first, then checks the original settings after missed replies. If the target still answers on the original channel without a pending switch, setup can send another switch request, with a pause and a bounded number of attempts. It continues only after verifying the target on the new channel. Other setup paths wait up to 35 seconds for matching temporary-radio readbacks; errors show the requested and reported settings, including preamble. New windows use a 368-symbol preamble at both ends when either endpoint uses radio2. Primary-only setup uses its separate preamble setting. Recovery keeps the verified preamble of an existing window until that window is replaced.

When the target already has a saved radio2 profile, setup can temporarily use that profile for the update instead of changing the saved tuple or disabling it permanently. Its normal radio2 traffic pauses while the temporary update profile is active. The saved profile returns when the target reboots after installation or when the temporary window expires. The browser verifies restoration before reporting the update complete and keeps the original profile in the update's recovery record. Existing temporary radio2 sessions, radio2 schedules and automatically owned runtime profiles are not replaced. This is a temporary frequency override on the same transceiver, not a second physical radio.

During an active download, an unanswered temporary-window getter leaves file serving active and retries after a pause while the last verified window remains valid. Identity changes, USB failures and uncertain renewal writes still stop the session. Stopping does not cancel the target's staged download; prepare the same update again to resume its retained blocks. If the window has expired, setup can prepare a new one after matching both devices, the saved package's full hash and the target's staged download ID. Automatic update steps keep their own recovery records, which are also used after refreshing the page or reconnecting USB.

Installer capability is checked on the working channel before radio setup. An explicit earlier result is reused only on the same connection, source, authenticated target and installed firmware identity. Changing hardware, version or the installed body hash requires another check. A timeout never authorizes a weaker installer. The final install command and post-reboot image verification are still required.

Pause normal forwarding is enabled by default for direct updates once radio2 has been verified. It pauses primary-profile floods when radio.flood is supported; an explicit unsupported reply permits the older global repeat control, which pauses forwarding on both profiles. Locally addressed admin commands and the target's own OTA traffic remain enabled. An originally off setting is never turned on. This option does not change multi-hop relays. This is optional: if preparation cannot establish the original setting and safe recovery storage, the updater skips the pause, warns, and continues the firmware checks. Older sources without bounded optional checks skip this optimization. A pause whose outcome is uncertain retains its recovery record.

Forwarding settings persist across reboot. Before changing one, the browser saves its original value and full source/target identities in a local recovery record, without a password. It checks restoration after the final update and tries restoration after Stop, an error or Disconnect when the source is healthy and idle. Keep the page open until restoration is confirmed. If interrupted, reconnect the same source, select the same target and use Restore forwarding. Firmware DONE means the running target identity and image were verified. An optional forwarding or normal-radio2 check cannot turn that success into a failed firmware update. Pending cleanup stays visible as a warning; its recovery record remains until verification succeeds. An unconfirmed setting write is not silently repeated. Keep the page open if cleanup is still pending.

The source's five-minute admin lease is checked before reusing cached access. When this page's exact session has expired, it reacquires access and proves the target again before continuing; an active unknown session is not taken over. Read retries are not multiplied after the transport exhausts its 7/11 attempts.

If a Companion USB command times out, the page tries reopening that same USB port once and confirms the source's complete identity. This is a per-command acknowledgement timeout, not a USB inactivity limit. It does not restart the update or replay an unanswered install, pull or settings command. Select Prepare update afterward to read the target's current state.

On that same-page reconnect, the browser can close its own abandoned local reply mailbox without waiting for its five-minute lease to expire. It cannot take over an unrecognized session. A surviving radio2 update channel is reselected only after its exact local temporary settings are confirmed; the target must still prove its full identity before forwarding is restored. An unconfirmed mailbox close is checked by reads, never automatically repeated.

Firmware without the required USB radio readbacks cannot be configured or checked automatically; the page identifies the missing command and links to a Companion update. Some firmware accepts raw OTA packets from USB but suppresses their transmission without an active temporary radio. After a USB timeout, select Reconnect USB source, then Prepare update. After a Wi-Fi interruption, select Reconnect Wi-Fi Companion, then Prepare update; the page checks the same source identity before continuing. The selected target and firmware are kept. A matching interrupted download can be resumed or restarted from this browser's saved update record. To abandon it, choose different firmware and prepare again. Replace and install update discards the unfinished download and starts the selected image; preparation alone does not discard anything. Replacement rechecks the staged download before clearing it. An unanswered cancel is not sent again automatically. Source folders must be cleared first. If the source clock is wrong, set it before connecting. Multi-version updates require a supported identified RAK bootloader and successful simulation of every step.

For multi-hop, enter each relay's full public key in order from the source to the destination. The source must already have ACL access to every relay and the destination. This selects the administrative route; the firmware still floods OTA data and does not restrict bulk traffic to these relays. Every participant must use the same saved and temporary radio settings, with radio2 and crossing off; relays must have repeat on. Set OTA hops high enough for the route on every participant. These checks are experimental and have not yet been verified over LoRa.

Alternatively, connect with the admin-route field empty, enter the full keys of candidate repeaters, and select Find admin route. The search checks cached neighbor reports from reachable ACL-authorized nodes. It favors fewer relays among paths meeting the selected SNR floor, then the strongest weakest link. Reports can be stale and do not identify which radio profile heard them. This is a hint for the admin route; it does not select the OTA data flood path.

Choose a firmware .bin or Nordic DFU .zip to create a full package in the browser, or a prebuilt .mota package. Differential packages also require the exact new firmware .bin; the target's existing firmware must match the package's base hash. A signed package requires its full trusted signing key, which must also already be trusted by the target. The target makes the final full-key check.

To create a differential package in the browser, select the new .bin and the exact old .bin currently installed on the target. The browser reconstructs the generated patch and checks it against the new image; the target also checks it during installation. nRF52 generation requires a supported embedded layout and confirmed internal or QSPI staging; unsupported nRF52 layouts can use a compatible prebuilt .mota. Preparing a differential for a large image can use substantial browser memory; if preparation fails, remove the old image to use a full package instead.