ESP8266 Legacy OTA Migration: Audit Both Layouts and the Copy-Back Mode

Moving an installed ESP8266 from a pre-v3 RTOS or Non-OS SDK to the IDF-style RTOS SDK is more than replacing an application image. The compatibility path packages new boot and partition information inside an image accepted by the old updater, then transforms the flash layout. An ordinary two-slot OTA checklist does not describe all of those writes.

There is an immediate release gate: in ESP8266 RTOS SDK v3.4, the ESP8266-specific Kconfig labels the old-SDK migration and related copy features as unreleased. Their presence in an example is not a production-support promise. This review uses commit 89a3f254b63819035f65d9c5dcdae8864f1a6a8a and reports no firmware build, migration or power-interruption test.

Establish the legacy fleet before selecting a package

Inventory the actual flash capacity, old SDK and bootloader, application-slot arrangement, updater format and reserved system-parameter region. Separate distinct hardware and firmware populations. A nominally identical module can still carry a different installed layout, so a product name alone is insufficient for deciding update compatibility.

Preserve an authorized recovery image and a verified serial-recovery procedure for the development units used to qualify migration. Do not begin with the only device holding irreplaceable provisioning or calibration data. The question is not simply whether the new application fits somewhere; it is whether every intermediate boot and copy operation preserves what the next stage needs.

Original review diagram. It does not claim atomic migration, rollback or successful power-loss recovery.

Read the conversion guide alongside the actual CSV

Espressif's migration guide describes staging the new bootloader, partition table and application in an old application partition. The new bootloader then unpacks the payload and copies its components to their target locations. The first migration boot therefore performs work absent from an ordinary subsequent application update.

The guide's illustrative map is not a universal address specification. Compare it with the selected example's CSV and the generated artifacts. In the 1 MB compatibility example, comments reserve boot space from 0x1000 to 0x5000 and place the partition table at 0x5000. Its ota_0 begins at 0x7000.

The 2 MB example instead reserves boot space through 0x8000, places the table there and starts ota_0 at 0x10000. Copying a single offset from a generic diagram into both builds would be wrong.

Both CSVs reserve the final four sectors for legacy-update and parameter handling. With their stated slot sizes, the second slot ends at 0xFC000 in the 1 MB example and 0x1FC000 in the 2 MB example. Those are source-derived address calculations, not permission to reuse the remaining space. Review every generated partition and reserved range as half-open intervals and retain the old layout beside the new one.

The 1 MB option changes later update behavior too

The same Kconfig selects ESP8266_BOOT_COPY_APP when old-SDK migration is enabled for a 1 MB flash configuration. Its description says an OTA1 application is copied to OTA0 and executed there. This is a meaningful lifecycle distinction, not merely a smaller pair of interchangeable slots.

Consequently, two partition names do not prove conventional A/B rollback. Identify where the currently usable image resides before, during and after copy-back. Determine which failures the actual boot path can recover from and which require physical service. Do not infer those guarantees from the appearance of ota_0 and ota_1 in a CSV.

Review first migration and subsequent updates as separate cases. They exercise different transformations, and a successful first conversion does not qualify every future update. Conversely, repeatedly testing an already converted device omits the original legacy-to-new transition entirely.

Keep credentials and RF parameters in separate migration checks

The compatibility application example contains a path for reading old connection information through esp_get_old_sysconf_addr and an old_sysconf structure. That is version-specific parsing, not a universal guarantee that every customized legacy configuration will survive.

Inspect the deployed structure layout, indices and lengths before importing anything. Keep credentials out of test logs. Separately review whether the fleet uses customized RF initialization data and whether the selected migration path preserves it. Treat connectivity restoration, retained calibration and application settings as independent acceptance results.

Verify the produced artifact without turning a demo into a rollout

The 1 MB example README identifies the compatibility output as a v2_to_v3 OTA binary and describes its HTTP server as demonstration infrastructure. Record the generated filename, hash, tool versions and embedded component addresses. An ordinary app binary is not equivalent merely because both files end in .bin.

The README also includes whole-flash erasure for setting up its serial demonstration. That action destroys existing content and cannot serve as evidence that remote migration preserves field data. Production transport authentication and image authorization need their own verified design; a demo download or packaging checksum does not establish either.

Proposed qualification covers interruption during download, initial unpacking, subsequent copy-back and retained-data import, using recoverable test hardware. Record the boot destination and preserved data after each case rather than reporting only that the device eventually reconnects. Current vendor support must also be assessed separately from this historical implementation.

The decision to ship should follow those results and the explicit unreleased-feature gate. Until then, the useful deliverable is a reproducible two-layout migration review, not a promise that an old fleet can safely accept a renamed firmware file.