View this page on MeshCore Docs.
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
Turn on Bluetooth, disconnect other apps from the Companion, and select Connect Bluetooth Companion to choose your device. The Companion needs firmware with Bluetooth OTA support.
On iPhone or iPad, install Bluefy, then open this updater in Bluefy. If the link does not open it, copy https://mikecarper.github.io/MeshCore/browser_lora_ota/?connection=bluetooth#ota-connect into Bluefy's address bar.
Scan your local network, or enter the Companion's Wi-Fi address. Wi-Fi setup instructions.
Find a Wi-Fi Companion
The browser will try to suggest your private network. If it cannot, enter your phone's Wi-Fi IPv4 address, such as 192.168.1.20, or its /24 prefix, such as 192.168.1.0/24. Browsers may hide the address for privacy.
Use this phone or computer's Wi-Fi IPv4 address to choose the network prefix; it is not the Companion's IP address. The scan covers one /24 network.
Example networks: choose one that matches the first three numbers of your Wi-Fi address.
Hotspot examples (the address can vary by phone):
USB connection options
The source radio sends the update over LoRa. Choose the remote device and enter its admin password if needed.
This source needs updated firmware for this OTA workflow. If it is still connected here, disconnect it before opening the flasher. Update source firmware
Connect your source radio to choose the remote device.
Device to update
Saved paths can be out of date. Incoming advert paths show how a recent advertisement reached this Companion; they are not verified return routes. The recent-advert cache is limited and clears on restart. Neither path confirms current reachability. Wi-Fi and Bluetooth Companion updates need a direct (zero-hop) connection; select Find matching firmware to contact the device and check compatibility.
Leave blank to use existing ACL access or an active session.Enter a public key manually
For a USB Repeater source, enter the remote device key here.
This Companion requires the remote device to be saved as a contact. Discover or add it in the MeshCore app, then reconnect here.
Checking the device reads this Companion's shared message queue. Pending unrelated messages will move from the Companion to this browser and cannot be restored to the Companion. They are stored unencrypted in this browser profile and can be downloaded below. Closing the browser while a message is being received can lose that message.
Keep other apps disconnected while using this Companion.
Device check details
Messages saved in this browser
After downloading, you can clear these browser copies, including interrupted or possibly lost message records. They cannot be restored to the Companion.
2. Prepare firmware
This Companion uses its shared message queue and raw packets.
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.