# nRF52 repeater LoRa OTA with external QSPI For **1.17.1.5**, use the exact board/storage profile from [OTAFIX 2.4.6](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.11.0-OTAFIX2.4.6) for nRF52 OTAFIX installations. New internal-flash hybrid receivers require its 64 KiB retained-RAM handoff; QSPI and microSD targets require their own matching bootloader profiles. Earlier preview versions mentioned below describe compatibility/migration history, not the current recommended download. Full Companion is a MOTA source and normally updates itself over USB. Selected nRF52840 repeater builds use their dedicated external QSPI NOR flash as a raw LoRa OTA staging device. This removes the internal-flash staging conflict: the complete `.mota` stays off-chip, and the bootloader can use the entire internal application region while it installs either a full image or an in-place delta. This is a matched application-and-bootloader feature. A board merely having an nRF52840, free RAM, or pins named QSPI is not enough. Both halves must use the exact flash wiring, and `ota self` must confirm the store and bootloader before an update is downloaded. ## Supported repeater families QSPI staging is enabled only for explicitly matched repeater-role environments (and RS232 bridge variants that directly inherit one of those repeater targets) on these currently matched families: - Seeed XIAO nRF52840 and XIAO nRF52840 Sense modules, including the `Xiao_nrf52`, SolarXiao 30S/33S, and XIAO-module Ikoka handheld, Nano, and Stick repeaters - original LilyGo T-Echo - Elecrow ThinkNode M1 and M6 - Seeed Wio Tracker L1 - Seeed SenseCAP Solar Node P1 - RAK4631 with a RAK15001 in WisBlock sensor slot C, using the dedicated `RAK_4631_repeater_rak15001_slot_c_lora_ota` application and matching `wiscore_rak4631_board_rak15001_slot_c` OTAFIX bootloader - RAK4631 with an externally wired Winbond W25Q16JV breakout on RAK19007, using `RAK_4631_repeater_w25q16_lora_ota` - RAK3401 with its RAK13302 1 W radio and the same externally wired W25Q16JV breakout on RAK19007, using `RAK_3401_repeater_rak13302_w25q16_lora_ota` Heltec T114 is intentionally not in this list. Its public V1, V2.0, and V2.1 schematics show U9 (MX25R1635F) as an optional QSPI footprint, so standard T114 application and bootloader targets do not assume that external NOR is populated. The XIAO-module derivatives use the matching XIAO or XIAO Sense OTAFIX bootloader shown by the module's `INFO_UF2.TXT`. Do not substitute a similar bootloader for a board with different QSPI pins. For example, the T-Echo Card and T-Echo Lite have different flash wiring and are not enabled by the original T-Echo target. Companion builds are intentionally excluded. Some companion targets use the same external QSPI as a LittleFS message/data store, where raw OTA staging would corrupt the filesystem; other companions simply do not assign that chip to OTA. Room-server, sensor, and KISS roles are unchanged. Raw QSPI OTA is scoped to the explicitly matched repeater-derived environments. ### RAK15001 placement and module conflicts [RAK15001](https://docs.rakwireless.com/product-categories/wisblock/rak15001/datasheet/) is a 2 MiB GD25Q16C **standard SPI** module, not a quad-I/O flash. The dedicated RAK4631 target uses the nRF52840 QSPI peripheral in its single-data-line FAST_READ/page-program modes at 8 MHz and accepts only the module's exact `C8 40 15` JEDEC ID. `ota self` reports `QSPI store:2048K` only when the expected module responds. An empty slot or a different SPI device reports `QSPI store:ERR 0K`, and install is refused. The module is electrically usable in sensor slot A-D because those slots share the SPI signals and RAK15001 has onboard 10 kOhm pull-ups on WP# and HOLD#. The supported MeshCore/OTAFIX combination nevertheless requires **slot C**. It is the placement that remains safe when a [RAK12501 GNSS](https://docs.rakwireless.com/product-categories/wisblock/rak12501/datasheet/) is fitted in either of its supported slots, A or D: slot C avoids the GNSS PPS/reset nets on IO1/IO2 and IO5/IO6. In particular, GPS in A plus flash in B would share IO1/IO2 through the modules' auxiliary pins. Only one device that uses the shared WisBlock SPI chip-select may be fitted. Do not combine this target with RAK13800 Ethernet, RAK15002 SD, or another SPI module. RAK13800 and RAK15001 cannot coexist because they use the same SPI chip-select. Update a RAK13800 Ethernet build locally over USB using the release's **Manual UF2** or **Serial DFU (.zip)** download; it cannot use this RAK15001 LoRa-OTA staging target. RAK3401 with RAK13302 remains incompatible with **RAK15001**. The 1 W radio uses the same WisBlock SPI clock/data pins **and the same chip-select** as RAK15001. Firmware cannot independently select or detect those two chips, so a stock RAK3401 + RAK15001 assembly cannot provide reliable OTA staging without a hardware chip-select rework. This restriction does not apply to the separate-CS W25Q16 wiring below. ### One W25Q16 wiring for RAK4631 or RAK3401 + RAK13302 An external Winbond W25Q16JV breakout can remain attached to a RAK19007 while the core is changed between RAK4631 and RAK3401 + RAK13302. It shares only the WisBlock SPI clock/data nets and has its own chip-select on AIN1: | W25Q16 breakout | RAK19007 connection | nRF52840 / Arduino pin | | --- | --- | --- | | `CLK` | IO connector pin 26, `SPI_CLK` | P0.03 / `3` | | `DO` / MISO | IO connector pin 27, `SPI_MISO` | P0.29 / `29` | | `DI` / MOSI | IO connector pin 28, `SPI_MOSI` | P0.30 / `30` | | `CS` | J11 `AIN1` | P0.31 / `31` | | `VCC` | J12 `VDD` | regulated 3.3 V | | `GND` | J12 `GND` | ground | Fit a physical approximately 10 kOhm pull-up from `CS` to J12 `VDD`. That keeps the flash deselected during reset, bootloader entry, and a core-module swap. Power the breakout only from J12 `VDD`; **never use J11 `VBAT`**, which can exceed the flash's supply rating. The six-pin breakout does not expose WP#/IO2 or HOLD#/IO3; do not add nRF IO2/IO3 wiring. A breakout with an onboard power LED works, but that LED draws continuously and is undesirable for low-power or solar operation. This arrangement consumes no WisBlock sensor slot. However, `SPI_CLK`, `SPI_MISO`, and `SPI_MOSI` are not available on the easy 2.54 mm J10/J11/J12 headers. Those three signals require a short underside-pad tap or a suitable IO-connector interposer at pins 26-28. J11 and J12 alone are not sufficient. GPS remains supported in sensor slot A. RAK12500 uses I2C, while RAK12501/L76K uses UART plus its auxiliary control signals; neither uses the shared SPI clock/data bus. On RAK4631 the built-in SX1262 has a separate private SPI bus. On RAK3401 the RAK13302 and flash share clock/data, but have independent chip-selects: RAK13302 NSS is P0.26 and flash CS is P0.31. The matched firmware holds the radio NSS high while it temporarily hands the bus to the flash, then restores the radio SPI interface. The breakout target accepts only a 2 MiB W25Q16 with JEDEC ID `EF 40 15` and runs it at 8 MHz in standard single-data-line SPI mode. A substituted W25Q32, W25Q64, or W25Q128 fails closed instead of being treated as the OTA store. Use the complete application/bootloader identity row that matches the fitted core: | Core and radio | PlatformIO environment | MOTA hardware identity | OTAFIX board / DFU device name | | --- | --- | --- | --- | | RAK4631 built-in SX1262 | `RAK_4631_repeater_w25q16_lora_ota` | `RAK4631_W25Q16` | `wiscore_rak4631_w25q16` / `4631_W25Q16_DFU` | | RAK3401 + RAK13302 1 W | `RAK_3401_repeater_rak13302_w25q16_lora_ota` | `RAK3401_RAK13302_W25Q16` | `wiscore_rak3401_rak13302_w25q16` / `3401_W25Q16_DFU` | The physical flash wiring is identical, but the two application and bootloader pairs are not interchangeable. ### Header-only W25Q16 wiring for the unified RAK images The unified RAK repeater images and matching OTAFIX 2.4.10 compatible bootloaders also support a W25Q16 through the RAK19007 2.54 mm headers. This arrangement does not need an IO-connector interposer or underside SPI solder points: | W25Q16 breakout | RAK19007 header | nRF52840 / Arduino pin | | --- | --- | --- | | `CLK` | J10 `TX1` | P0.16 / `16` | | `DO` / MISO | J10 `RX1` | P0.15 / `15` | | `DI` / MOSI | J11 `IO1` | P0.17 / `17` | | `CS` | J11 `AIN1` | P0.31 / `31` | | `VCC` | J12 `VDD` | regulated 3.3 V | | `GND` | J12 `GND` | ground | Keep the approximately 10 kOhm `CS`-to-`VDD` pull-up. This mapping gives up the UART1 GPS and PPS pins while the flash is fitted. The unified firmware detects the exact `EF4015` device before GPS discovery and leaves I2C sensor pins `SDA` and `SCL` available. RAK4631 can still use its UART2 bridge; its UART1 bridge is unavailable with header flash. RAK3401 retains its 1 W radio and shared sensor/radio power rail. Do not substitute `SCL` for flash clock or use `SWCLK`, which is the debug clock. The older dedicated W25Q16 images above expect the WisBlock SPI connector wiring and do not use this header mapping. ## One-time prerequisite Install a QSPI-capable OTAFIX 2.4.1 preview.9 or newer bootloader for the exact board from the [OTAFIX releases](https://github.com/mikecarper/Adafruit_nRF52_Bootloader_OTAFIX/releases) before using LoRa OTA. The release notes must explicitly list that board's QSPI mode. Also install the SoftDevice version expected by that target. The application refuses the install handoff when the bootloader does not advertise QSPI support. For the external W25Q16 option, install the corresponding bootloader once before installing its MeshCore application: `wiscore_rak4631_w25q16` (`DEVICE_NAME=4631_W25Q16_DFU`) for RAK4631, or `wiscore_rak3401_rak13302_w25q16` (`DEVICE_NAME=3401_W25Q16_DFU`) for RAK3401 plus RAK13302. Use only a release that explicitly names that exact pairing. Do not substitute the RAK15001 bootloader or swap the two W25Q16 bootloaders merely because the base-board wiring is the same. For the first migration from the ordinary `wiscore_rak4631_board` bootloader to `wiscore_rak4631_board_rak15001_slot_c`, use Nordic serial DFU or a compatible BLE DFU client with the exact slot-C OTAFIX **combined bootloader + SoftDevice DFU package** (or use SWD), then reinstall the slot-C MeshCore application. The release filename has this form: ```text wiscore_rak4631_board_rak15001_slot_c_bootloader-_s140_6.1.1.zip ``` Do not copy the slot-C bootloader-update UF2 onto the stock UF2 drive. The stock loader is bound to `DEVICE_NAME=4631_DFU`, while the slot-C image is bound to `4631_15001C_DFU`, so that UF2 is intentionally rejected. After the one-time DFU/SWD migration, later canonical slot-C bootloader UF2 files work normally. The combined OTAFIX package above is not the MeshCore application's Serial DFU `.zip`; an application package does not migrate the bootloader. After installing the repeater application, check: ```text get bootloader.ver ota self ota status ota qspi ``` A ready RAK15001 target reports all of the following: ```text QSPI store:2048K bootloader: QSPI apply OK bl:QSPI QSPI jedec=C84015 size=2048K sr1=00 stage=jedec ``` A ready external W25Q16 target instead identifies the Winbond part: ```text QSPI store:2048K bootloader: QSPI apply OK bl:QSPI QSPI jedec=EF4015 size=2048K sr1=00 stage=jedec ``` Other supported boards can report a capacity different from 2048K; the RAK15001 and W25Q16 targets must report exactly 2048K and their respective exact JEDEC IDs. `QSPI store:ERR 0K`, `NO QSPI`, or `bl:NO-QSPI` means the flash wiring, flash power, chip-select pull-up, application, or bootloader does not match. Do not start an install in that state. `ota qspi` is a read-only diagnostic probe available on QSPI OTA builds. It reports the exact JEDEC ID, status-register byte, last store stage, and the first latched storage error. Run it after an immediate `storage error` before starting another pull; later capacity probes preserve that failure detail. ## Capacity and package types The store reads the JEDEC capacity at runtime and accepts supported 1 MiB through 16 MiB devices using 24-bit addressing. QSPI capacity is not the final firmware limit. The reconstructed application, including its 56-byte `EndF` trailer, must fit its build's linked application region: | SoftDevice layout | Application region | Maximum image | | --- | --- | --- | | S140 v7, boot-update-capable XIAO module | `0x27000..0xE0000` | `0xB9000` (757,760 bytes) | | S140 v7, app base `0x27000` | `0x27000..0xED000` | `0xC6000` (811,008 bytes) | | S140 v6, app base `0x26000` | `0x26000..0xED000` | `0xC7000` (815,104 bytes) | The XIAO limit is deliberately 52 KiB smaller. Its linker and post-link record cap every ordinary application at `0xE0000`; OTAFIX reserves `0xE0000..0xEA000` as a 40 KiB self-update scratch bank, with the remaining gap left unused before InternalFS. Full and delta application packages for these targets derive their effective application end from that `0xE0000` record and are rejected if their reconstructed image or detools geometry crosses it. A full package needs only the new raw `firmware.hex` or non-merged application image. An in-place delta still needs the exact image currently running. The automation uses a conservative `0xC6000` detools workspace for external nRF52 staging so one package setting is safe for both layouts. For online automation, QSPI is detected from `ota self` or `ota status`. For offline preparation, identify it explicitly: ```bash ./tools/lora_ota/lora_ota.sh ./release.zip target-name \ --prepare-only \ --platform nrf52 \ --nrf-qspi \ --target-id 12345678 \ --target-hw Xiao_nrf52 ``` Use the real target ID and hardware identity from the destination. A ready full `.mota` normally uses that target ID for discovery and routing. An operator can deliberately override the routing target for a role change, so `target_id` is not an apply-time safety assertion; the destination still enforces the package's hardware identity before approval. ## Explicit XIAO bootloader updates over LoRa This section documents the deployed XIAO raw-QSPI layout. Curated nRF52840 targets without external staging use a separate internal-flash layout with the same explicit operator safety model; see [nRF52 bootloader updates over LoRa](ota_nrf52_bootloader_update.md). Bootloader delivery is available only when all of these are already true: - the application is an `OTA_QSPI_BOOTLOADER_UPDATE` XIAO-module repeater build linked below `0xE0000`; - `ota bootloader` shows a CRC-valid installed `XIAO_DFU` embedded identity for board ID `28860044` (base) or `28860045` (Sense); - the installed OTAFIX marker reports ABI 3 or newer and both QSPI (`0x04`) and boot-update (`0x08`) capability bits; - the package is the exact signed v3/40-KiB/1-KiB-block profile for that board, and its signer is already in `ota key`'s trusted allowlist. This is not part of normal automation. Bootloader catalog rows are labelled `bootloader`; even a capable node never autofetches or autoinstalls them, and ordinary `ota install` rejects them in every application backend. The `tools/lora_ota` deployment runner also refuses v3 packages. Fetch and arm one only with the explicit flow: ```text ota ls ota pull flash # wait for ota status to report the same bootloader download as ready ota bootloader # copy the exact mid= and hash= values printed above ota bootloader install ``` The pull command is only transport intent; it does not authorize an install. The final command must reproduce both the complete staged manifest ID and the first eight bytes of its signed image hash. Before approval the application again checks package/root/payload/image hashes, Ed25519 signature and trusted allowlist, exact signed `XIAO_BL_...` ID, installed and incoming embedded manifest/CRC/name/board identity, vector table, ABI-3 QSPI+boot-update marker, and the adjacent CRC-covered `BLM2`/`SOFT` continuity extension at the exact final-image offset `0x9FB4`. The embedded boot version must equal the signed outer package version, the SoftDevice family/FWID/application base/layout ABI must match the running platform, and a successor to installed BLM2 must be strictly newer. Low-byte-zero and all-ones versions are invalid. Remote rollback is refused; use local DFU/SWD. After the reply drains, GPREGRET `0x6B` and GPREGRET2 `0x51` enter the special OTAFIX path. `APRV` carries the app's signature/allowlist and explicit operator authorization decision. OTAFIX independently rechecks the strict structure, identity/capabilities, vectors, payload SHA, embedded CRC, and copy hashes before using the reserved scratch bank to replace its own `0xF4000..0xFE000` region. The running application remains preserved; a rejected candidate returns to it unchanged. Post-reboot `ota status` reports bootloader-update diagnostics as `blup:C0` to `blup:CF` (`blup:C8` is success), separately from ordinary application `blrc`. This feature cannot update a stock or old bootloader that lacks the capability marker: perform the first exact-board combined bootloader+SoftDevice migration over USB/BLE DFU or SWD. Do not attempt to bootstrap it with a v3 package. ## Storage ownership and recovery The QSPI store is raw, not a file inside LittleFS. It owns the flash from offset zero, erases 4 KiB sectors as blocks arrive, writes data before progress metadata, and verifies every programmed page. A previously interrupted download is reopened only when its header and trailer are valid; every claimed block is re-hashed before it is trusted. Between a probe, transfer operation, or checkpoint, firmware puts the NOR into deep power-down, deactivates the nRF QSPI peripheral, and turns off a board-provided flash power-enable pin. The next operation powers the chip, shifts the NOR's `0xAB` wake command over GPIO, then activates the nRF QSPI peripheral and identifies the flash. Waking it before peripheral activation is required because a flash in deep power-down ignores the activation traffic itself. Merely running `ota self` therefore does not leave QSPI drawing active-mode current or prevent the following operation from reactivating it. Installing a QSPI repeater build over a former companion build therefore repurposes the external flash and destroys companion filesystem data as OTA sectors are written. Back up anything important first. Returning to a companion build may require formatting its external data store. Before changing internal application flash, the application verifies package integrity, hardware identity, signature policy, and bootloader capabilities. The target ID selects discovery/fetch routing and can be deliberately overridden; it is not a second hardware gate. The bootloader then verifies a full payload before its first application erase. For a delta, the application rejects invalid detools geometry before approval and the bootloader independently repeats the base and geometry checks before applying it. It clears the one-shot approval marker before invalidating the running image. If power is lost after application writes begin, the bank remains invalid and OTAFIX enters USB/BLE recovery rather than booting a partial image. See [Easy firmware updates over LoRa](ota_easy.md) for the transfer commands and [the OTA protocol](ota_protocol.md) for the container and handoff details.