HaloKeymind/docs/firmware_picker.md

Firmware picker

Each result now includes Restore your settings after flashing. Its commands follow the selected logging mode and the exact image's verified role/hardware controls. Click On, Off, or Check to view and copy the commands; Companion MQTT and GPS show their app/WebConfig steps instead. See feature switches by role for the full reference. The USB web console works with the default ASCII terminal on USB Companion and infrastructure roles.

Pick the choices in any order. Every selection narrows all the other controls to firmware combinations that were actually built in the current release set. The optional chip-family filter (ESP32, nRF52, RP2040, or STM32) can narrow the hardware list first. You can skip it: picking hardware fills it in automatically. Chip family and hardware are the only dropdowns. All remaining choices use buttons. Firmware profile combines OTA support, Full/standard, and sensor or storage differences in one choice.

The picker reads public release metadata from GitHub. It does not upload device information. Hardware names, target names, and download links come directly from the published firmware assets.

Current release set

Loading release information...

For a new installation, choose the exact board and role, prefer a FULL / complete profile when it is available, and select Full install / layout migration (merged .bin). Narrower profiles remain available when their reduced transport or feature set is intentional.

Upgrading an existing ESP32 infrastructure node from a smaller partition layout? The selected Full result links directly to its exact board and role partition-expansion ZIP when published. Follow its included README to check the installed OTA target and source layout for a supported Wi-Fi or LoRa route. If no unique matching ZIP is available, the picker links to the utility release to check availability. USB installation uses the matching merged image instead. An app-only .bin cannot change the partition table. If the installed firmware supports it, run get storage.layout to see the live flash size and OTA slots. Firmware version alone does not prove the installed layout.

Pick in any order. Use Any to clear one choice, or clear everything with the button below. The address bar updates with your choices; copy its URL to reopen or share the same selection.

Optional: chip family

Skip this if you know your board. Picking hardware selects its chip family automatically. Choose Any to clear this filter.

Chip family Any chip family - skip this filter

<div class="firmware-picker-control firmware-picker-select-control">
  <label for="firmware-picker-hardware-family">Hardware</label>
  <select id="firmware-picker-hardware-family" data-field="hardwareFamily" disabled>
    <option value="">Loading hardware...</option>
  </select>
</div>

<fieldset class="firmware-picker-control firmware-picker-radio-control firmware-picker-wide" data-radio-field="hardware" data-role="hardware-variant-control" disabled hidden>
  <legend>Hardware variant</legend>
  <div class="firmware-picker-radio-options" data-field="hardware">
    Choose hardware first
  </div>
</fieldset>

<fieldset class="firmware-picker-control firmware-picker-radio-control firmware-picker-wide" data-radio-field="install" disabled>
  <legend>Install operation</legend>
  <div class="firmware-picker-radio-options" data-field="install">
    Loading install choices...
  </div>
</fieldset>

<fieldset class="firmware-picker-control firmware-picker-radio-control" data-radio-field="role" disabled>
  <legend>Firmware role</legend>
  <div class="firmware-picker-radio-options" data-field="role">
    Loading roles...
  </div>
</fieldset>

<fieldset class="firmware-picker-control firmware-picker-radio-control" data-radio-field="logging" disabled>
  <legend>Logging / MQTT</legend>
  <div class="firmware-picker-radio-options" data-field="logging">
    Loading logging choices...
  </div>
</fieldset>

<fieldset class="firmware-picker-control firmware-picker-radio-control firmware-picker-wide" data-radio-field="firmwareProfile" aria-describedby="firmware-picker-profile-help" disabled>
  <legend>Firmware profile</legend>
  <p id="firmware-picker-profile-help" class="firmware-picker-control-help">Each button combines OTA support with the feature, sensor, and storage choices for that image. Reduced optional sensors means fewer environmental/ranging drivers; I2C and supported board peripherals remain available.</p>
  <div class="firmware-picker-radio-options" data-field="firmwareProfile">
    Loading firmware profiles...
  </div>
</fieldset>

<fieldset class="firmware-picker-control firmware-picker-radio-control firmware-picker-wide" data-radio-field="mode" disabled>
  <legend>Connection / bridge mode</legend>
  <div class="firmware-picker-radio-options" data-field="mode">
    Loading modes...
  </div>
</fieldset>

<div class="firmware-picker-form-actions firmware-picker-wide">
  <button type="reset" data-action="clear" disabled>Clear all choices</button>
  <button type="button" data-action="copy-link" disabled>Copy link to settings</button>
  <a data-role="share-link" hidden>Link to these settings</a>
  <p data-role="link-status" aria-live="polite"></p>
</div>

nRF52 bootloader

Loading the current firmware catalog...

Exact firmware match

Recommended download

No exact firmware matched

Browse all firmware releases

Advanced: search current release filenames

Use this for uncommon board suffixes or expert recovery. A filename match is not a board-identity check.

Filename contains

What the choices mean

Choice	Use
Companion	A phone, computer, or host application controls the radio
Repeater	Standalone mesh relay
Room Server	Hosts room conversations and history
Sensor / telemetry	Publishes supported sensor data
Terminal Chat	Standalone serial-terminal interface
USB logging / USB-connected MQTT	Node remains attached to a computer over a data-capable USB cable
Wi-Fi MQTT observer	Firmware connects directly to MQTT over Wi-Fi; this is not USB logging
USB logging + Wi-Fi MQTT	Unified FULL image sends to both paths; avoid two publishers aimed at the same broker unless messages are deduplicated
No logging	Normal standalone operation without the dedicated logging/MQTT profile
Receives LoRa OTA	Repeater, room server, or sensor image that can stage an exact matching update received over LoRa; any sensor/storage tradeoff appears on the same Firmware profile button
Receives LoRa OTA - Reduced optional sensors	Compact OTA image that omits selected optional environmental/ranging drivers while retaining generic I2C and supported board peripherals
LoRa OTA source only	Full Companion serving a host-supplied update to another node without self-installing it

Connection and bridge choices depend on the selected role. Companion firmware may offer Full, combined USB + Bluetooth, Bluetooth, USB, Wi-Fi, serial, or Ethernet transports. Normal repeater firmware includes runtime-controlled RS-232 support where the board has room; use set bridge.enabled on after configuring bridge.uart and bridge.baud. The Wio-E5 remains the capacity exception and offers a separate RS-232 image. Choose Wi-Fi MQTT under Logging / MQTT; it is an output mode, not a second connection choice. Repeaters may still offer separate ESP-NOW or Ethernet bridge firmware because those paths use different compiled drivers.

For commands and option explanations, follow the ESP-NOW bridge setup guide.

An ESP-NOW bridge target keeps LoRa as its primary mesh radio. Expanded ESP32 Full repeater and room-server images combine ESP-NOW with WiFi MQTT in the same firmware. MQTT and ESP-NOW are independent runtime transports: use set mqtt.enabled on|off for MQTT and set bridge.enabled on|off (or set espnow.enabled on|off) for ESP-NOW, so either or both can run. Both use one 2.4 GHz radio, so when both are enabled the ESP-NOW bridge channel must match the connected WiFi access point's fixed channel. ESP-NOW-only mode does not require WiFi credentials. Its runtime bridge.format setting chooses the peer protocol: wrapped (the backward-compatible bridge-to-bridge default using bridge.secret) or raw (direct MeshCore ESP-NOW LR frames for Generic_ESPNOW, SenseCapIndicator-ESPNow, and other primary-ESP-NOW nodes). This is one firmware choice, not two board images. Match bridge.channel to the primary nodes' espnow.channel before selecting set bridge.format raw. For Heltec V4 specifically, companion_radio_full is still a LoRa-primary Companion; choose the existing heltec_v4_repeater_bridge_espnow firmware to make that board the LoRa/ESP-NOW gateway. Use its exact merged artifact when changing roles or partition layouts.

Share a selection

Select any combination of choices, then copy the address bar or use Copy link to settings. Opening the link restores those choices after the release catalog loads. Partial selections work too, so you can share a board and role while leaving other choices open. Clear all choices removes the picker parameters from the URL. Changes update the current browser-history entry without reloading the page or adding a Back-button entry for every click.

For example, RAK3401 repeater with internal storage preselects that board, role, OTA capability, and storage profile.

The query parameters are chipFamily, hardwareFamily, hardware, role, logging, ota, mode, feature, variant, and install. Values use the picker's internal identifiers rather than the displayed labels. One Firmware profile button sets ota, feature, and variant together. Existing links with only some of those choices still work and show their partial selection. The generated link also records chipAuto so automatic chip-family selection or an explicit Any choice behaves the same after reopening. Existing section anchors and unrelated query parameters are preserved.

Links use the current release catalog. If a linked choice is no longer available or conflicts with another choice, the picker identifies it and asks you to review the remaining selections. The downloadable HTML's Copy link to settings button creates a public website link that other people can open.

FULL versus standard

For a new installation, use the FULL / complete profile when it exists and the board has enough flash. FULL profiles keep the complete supported feature set and CLI. Standard profiles remain useful for boards without a FULL build, for an intentionally narrower transport, or when retaining an existing compatible partition layout.

Changing between standard and FULL ESP32 layouts requires a partition migration. Use the exact-board merged image over USB, or a supported exact board and role staged migration ZIP from the utility release. Read that ZIP's README before choosing the Wi-Fi or LoRa route. Do not send a loose app-only Full .bin directly to an older layout: the running application cannot move its own active and inactive partitions. Run get storage.layout on the installed firmware if available. It reports the live partition table; a version-based guess cannot confirm the installed layout. See the partition lookup guide when the old firmware lacks that command.

Current full-usb-wifi profiles use one binary for no external output, USB packet logging/USB-connected MQTT, direct WiFi MQTT, or both. The picker shows that same exact binary for each compatible logging choice; select the saved runtime mode with set logging.output off|usb|wifi|both. A FULL logging-fallback profile is listed only when no WiFi MQTT sibling exists; it appears for both the no-output and USB choices because set usb.logging off|on is persistent. On a fresh unified FULL install with no saved SSID, the setup AP and WiFi radio remain available for 30 minutes per boot, then turn off automatically until the next reboot or power cycle. An explicit administrator start webconfig remains available as an override. A saved SSID switches to the normal indefinite reconnect behavior instead.

Full Companion profiles use one binary for USB, BLE, ordinary Wi-Fi on ESP32, source-only LoRa OTA, Terminal Chat, optional USB packet logging, and any board-qualified serial or Ethernet Companion transport. Bulk builds therefore omit separate attached-transport, Terminal Chat, and USB-logging artifacts whenever the exact Full recipe exists. RAK4631 repeater and room-server Ethernet images remain separate roles. Fresh installs default to logging off. Heltec V3 and base OLED V4 Full images also contain the former direct Wi-Fi MQTT Companion capability, configured at runtime through WebConfig, so their separate companion_radio_wifi_mqtt artifacts are omitted from canonical builds as well.

When Full Companion does not fit but a matching USB Companion does, that USB artifact also supplies Terminal Chat and replaces its standalone release image. Heltec E290 and T190 now publish one Full USB + BLE + WiFi Companion; their old combined and single-transport names are explicit-build compatibility aliases. SSD1306 Full Companion builds use set display.rotation 90|180|270; 0 restores the board default, so a separate rotated release image is not recommended.

Ordinary non-OTA roles also use one artifact for normal operation and USB logging. On ESP32 1.17.1.5, run set powersaving off before set usb.logging on. Select the saved mode with set usb.logging off|on; no -logging- artifact is emitted. KISS, BLE-only Companion, and constrained LoRa OTA repeater images retain their protocol/partition contracts and do not inherit plaintext USB logging.

nRF52 Full Companion keeps the multi-role primary interface on 00; it starts as an ASCII terminal and automatically hands a complete < frame to Binary Companion. set usb.logging on reboot adds its plaintext interface 02.

Every ESP32 Full Companion instead exposes one USB TTY. Logging is off by default, so the TTY serves the ASCII/Binary Companion switcher. On 1.17.1.5, run these two text commands to enable USB logging:

set powersaving off
set usb.logging on

The second command turns that same TTY into an input-capable plaintext CLI/logging stream; framed Binary Companion is unavailable on USB while logging owns it. set usb.logging off stops the logs and leaves the TTY in the normal ASCII terminal, matching a fresh Full installation. Send +++MESHCORE-TERM-STOP, or let a Companion app send a valid framed probe, to switch from there to Binary Companion. BLE and Wi-Fi Companion remain usable while the USB TTY is logging. ESP32 Full builds use the repository's Arduino-ESP32 2.x base where the board supports it; RC32 and ESP32-C6 retain their board-required Arduino 3.x platform but still expose only one USB TTY. A second ESP32 CDC interface is not part of the release profile.

The picker includes the power-saving workaround when selecting USB or USB + WiFi logging on ESP32 1.17.1.5. WiFi/MQTT-only logging does not need it while the Repeater/Room Server bridge is running; check get mqtt.running. The workaround is not added to nRF52 directions. See logging by role for the saved settings and the original firmware's USB sleep issue.

Companion USB terminal on Linux

Full, USB and USB + Bluetooth Companion results include Companion USB terminal (Linux / Bash) under Restore your settings after flashing, with copyable connection and recovery commands.

Updated 1.17.1.6 USB Companions default to ASCII at boot and after an observable USB session reset. picocom -b 115200 /dev/ttyACM0 is sufficient for a fresh session. A valid framed app command automatically selects Binary Companion. The command below also works with older firmware or a port left in Binary mode.

Run this in Bash on the Linux computer connected to your radio:

picocom -b 115200 --imap spchex \
  --initstring $'\r+++MESHCORE-TERM-START\r' \
  /dev/ttyACM0

Replace /dev/ttyACM0 with your radio's port, such as /dev/ttyACM1 or /dev/ttyUSB0. Use the primary USB data interface (00 when multiple interfaces appear), and close other apps using it. The init string requests the ASCII CLI; its leading carriage return clears an unfinished input line. --imap spchex displays binary control bytes safely during the transition.

If the terminal display is scrambled, exit picocom with Ctrl+A, then Ctrl+X, run reset in your Linux shell, then reconnect with the command above. At the radio prompt, run version and board to identify the node. See the Companion USB mode guide.

Companion tempradio2 transmit settings

LoRa Companion results for 1.17.1.6 and newer include Companion tempradio2: transmit on both under Restore your settings after flashing. After configuring tempradio2 in rxtx mode, choose Transmit on both to copy:

set radio2.cross on

This copies new messages to both radio and tempradio2. The setting is saved, outlasts the temporary session and reboot, and also allows OTA traffic to cross profiles. Default isolation copies set radio2.cross auto; Check shows the temporary profile, crossing policy and per-profile transmit counters. See the two-profile setup guide.

Installation methods

File	Use
-merged.bin	Erase/fresh install, recovery, role migration, or partition-profile change on ESP32 over USB
Non-merged .bin	Update an existing same-board, same-role, same-partition installation
*-migration.zip	Exact ESP32 board and role staged partition migration; follow its included README for Wi-Fi or LoRa steps
Other .zip firmware shown by the picker	Native nRF52 Serial DFU update package; it is not an extra archive
.uf2	UF2 bootloader drag-and-drop install or update
.hex	Erase/recovery flash with a supported wired programmer

Never send a merged ESP32 image through browser OTA or LoRa OTA. Back up the node identity, configuration, keys, and radio settings, and verify every filename suffix before flashing. A staged migration writes the partition table; power loss during that write can require cable recovery. The package README states what each route preserves and which older layouts it accepts.

LoRa OTA and OTAFIX

A LoRa OTA capable build can receive and stage updates for its role. A later LoRa update still needs an exact target identity, compatible partition signature, matching radio settings, and the correct update package.

Selecting an nRF52 board shows its direct Bootloader UF2, Bootloader DFU ZIP, and Bootloader HEX (SWD) downloads, when an exact published profile is available. ESP32 and other chip families do not show this section. The web picker checks the latest stable OTAFIX release; the downloadable picker includes the bootloader release named in its saved catalog. If a board has no verified mapping or a file is missing, the picker explains that instead of offering another board's bootloader. MeshTower internal and microSD remain separate; RAK3401 and RAK4631 each use their adaptive storage bootloader.

Board mappings and file names, URLs, sizes and SHA-256 hashes come from bootloader-manifest.json in the OTAFIX release. Application UF2 and DFU files do not install a bootloader. Follow the bootloader release's migration instructions if the installed version needs a recovery bridge.

nRF52 LoRa OTA requires an OTAFIX bootloader built for the exact board and storage layout. Select the hardware-matched HEX, Serial DFU ZIP, or bootloader-update UF2 for the application image being installed.

Hardware and variant names

Hardware families with multiple released targets get Hardware variant buttons. They separate revisions, display type, expansion kit, radio/PA layout, pin map, and other physical differences without crowding the Hardware dropdown. Firmware profile buttons combine OTA support, Full/standard, and choices that need a different image or wiring, such as serial port or external storage. The legacy no_external_sensors profile is labeled Receives LoRa OTA - Reduced optional sensors on the same button. On RAK3401 and RAK4631 this compact profile uses internal storage without an external storage board. The reduction does not disable generic I2C or unrelated board-integrated peripherals. Reduced RAK3401 and RAK4631 targets retain INA219/INA226/INA260/INA3221 as voltage/current entries in the optional sensor table. They are not the only I2C users: the SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 GPS remain separate I2C peripherals in compatible recipes. RAK12501/L76K GPS uses Serial1 instead. The explicit RAK4631 Serial1 bridge omits the combined GPS provider because its bridge owns the RAK12501 UART, so that legacy image does not expose RAK12500 either. The firmware-configured INA3221 and RAK12500 addresses are both 0x42; to install both, keep RAK12500 at 0x42, strap INA3221 A0 to SCL for 0x43, and use a build with -DTELEM_INA3221_ADDRESS=0x43. Companion power saving, controllable FEM receive gain, and radio-chip receive gain are saved settings rather than separate recommended firmware files. Do not substitute a similarly named physical target.

The header-wired RAK19007 W25Q16 LoRa-OTA recipes are also exact hardware variants, labeled External storage board (W25Q16) in the picker. W25Q16 is the flash-memory part on the added storage board; RAK13302 identifies the radio module, not the storage board. Choose this variant for RAK4631 or for RAK3401 + RAK13302 only when that core/radio combination, the EF4015 flash wiring, and its matching OTAFIX bootloader are all present. The common base-board wiring does not make the two firmware or bootloader identities interchangeable.

The picker recommends one Full Companion image instead of separate USB, BLE, ordinary WiFi, and USB-logging images. On ESP32, logging is off by default so the one USB TTY starts in ASCII and automatically changes to framed Companion when a complete < frame arrives. Enabling logging gives that TTY to the plaintext CLI/logger and disables framed USB Companion until logging is turned off and the normal ASCII-to-binary mode switch occurs. nRF52 Full Companion retains its optional dedicated interface 02. Exact filename search still finds old aliases from earlier releases.

For same-partition ESP32 infrastructure migrations, the picker similarly recommends the ordinary target's exact-identity Full image when it is present. The former observer-named Full image remains available through exact filename search for deployed devices that still use that mOTA identity; it is not shown as a second recommended configuration.

Some normal ESP32 roles begin in the legacy 1.25 MiB dual-OTA layout but have a Full image with larger slots. The 1.17.1.7 utility release contains 94 exact board and role migration ZIPs. Each package checks its source layout and target identity, contains the bridge and Full application files for its supported routes, and documents what saved data it preserves. Use the package's own Full application after the bridge; do not substitute a loose Full image with a different target ID. If no exact package exists, use the matching merged USB image. Once migrated, routine app-only updates still need the same target and partition signature.

Maintaining the runtime directions

The online picker and downloadable HTML use the same command renderer. Hardware-specific controls are enabled only when _data/firmware_controls.json matches the selected release family and exact target. If that metadata is missing or belongs to another release, the picker retains basic role/logging directions and links the complete guide without inventing hardware support. For 1.17.1.6, that JSON also records the verified LoRa OTA role of each image and USB logging modes where the packaged application was checked. Logging metadata is tied to the source hash of its firmware file. The normal iKoka 30 dBm repeater has USB logging and LoRa OTA; its compact no-external-sensors image has LoRa OTA without logging. Capacity directions come from each qualified profile's recorded reductions and are tied to the source hash of the selected download. The older 1.17.1.5 USB sleep workaround stays limited to that release.

After qualifying a new release, resolve its PlatformIO configuration with no other PlatformIO process running, then generate the controls from that source revision and its staged manifests:

pio project config --json-output > /tmp/meshcore-picker-pio-config.json
python3 scripts/generate_picker_controls.py \
  --stage /path/to/staged-release \
  --pio-config /tmp/meshcore-picker-pio-config.json

Refresh the data-controls-url version query when publishing the generated metadata so browsers fetch the new release's controls.

The generated partitionMigrations lookup comes from BOARDS in scripts/package_esp32_partition_migration.py, the same exact board/role table used to build the migration packages. Expanded ESP32 Full results use this lookup (including canonical board/role recipes for Observer profiles), then require one matching published ZIP in the same release family's utility page. Hardware variants and roles remain distinct. Unlisted targets, missing or ambiguous assets, and stale metadata never produce a guessed download link.

For the downloadable version, save the release family's public GitHub release objects as a JSON array, then package the same picker UI and controls:

python3 scripts/package_firmware_picker.py \
  --releases-json /path/to/releases.json \
  --output /path/to/FIRMWARE-PICKER.html

This HTML embeds its catalog and directions, so selections work without an internet connection. Firmware downloads and the USB web console still need network access. When replacing the downloadable picker on release pages, update its entry in each page's SHA256SUMS.txt as well.

Memory-corrected 1.17.1.5 downloads

Corrected downloads retain the 1.17.1.5 release page and use source suffix aa20e927, with 1e4d1e16 for Wireless Paper Full's 350-contact follow-up. The picker accepts replacement source hashes within that exact release version. Its installation directions identify the nRF52 queue-sharing behavior, Wireless Paper Full's 350 contacts with a shared 256/128-slot queue, and the 150-contact limit on the other six affected ESP32 Full profiles. Those notices apply only to the corrected files. See the memory correction details and each replacement's .memory.json report before updating.