Document ESP32 partition migration in picker and catalogs
This commit is contained in:
1 parent
0d9732f2f2
commit
dbf387b681
9 files changed
+1488
-1386
No files matched your search
@@ -1043,6 +1043,23 @@
|
||||
}, 0) >= 0;
|
||||
}
|
||||
|
||||
function isExpandedEsp32Infrastructure(profile) {
|
||||
return profile && profile.controls &&
|
||||
profile.controls.platform === "ESP32_PLATFORM" &&
|
||||
["repeater", "room", "sensor"].includes(profile.role) &&
|
||||
/-full-(?:logging|usb-wifi)$/i.test(profile.target);
|
||||
}
|
||||
|
||||
function migrationReleaseUrl(profile, asset) {
|
||||
if (!isExpandedEsp32Infrastructure(profile) ||
|
||||
!profile.releaseFamily || !asset || !asset.releaseUrl) return "";
|
||||
const url = asset.releaseUrl.replace(
|
||||
/\/releases\/tag\/[^/]+$/,
|
||||
"/releases/tag/utility-" + encodeURIComponent(profile.releaseFamily)
|
||||
);
|
||||
return url !== asset.releaseUrl && isSafeGithubUrl(url) ? url : "";
|
||||
}
|
||||
|
||||
function installSteps(profile, kind) {
|
||||
const common = [
|
||||
"Verify that the hardware name and every displayed variant match the physical board.",
|
||||
@@ -1087,6 +1104,11 @@
|
||||
],
|
||||
};
|
||||
const extra = [];
|
||||
if (isExpandedEsp32Infrastructure(profile) && kind === "bin") {
|
||||
extra.push(
|
||||
"If the node still has a smaller layout, first flash the matching merged image over USB or, if listed, use the exact board/role migration ZIP from the utility release and follow its README. Never send this app-only image across a partition change."
|
||||
);
|
||||
}
|
||||
if (profile.variant.includes("w25q16")) {
|
||||
extra.push(
|
||||
"Requires the external W25Q16 storage board, its exact documented wiring, and the matching storage-aware OTAFIX bootloader."
|
||||
@@ -1422,6 +1444,12 @@
|
||||
const release = createElement("a", "Open release notes");
|
||||
release.href = asset.releaseUrl;
|
||||
actions.appendChild(release);
|
||||
const migrationUrl = migrationReleaseUrl(profile, asset);
|
||||
if (migrationUrl) {
|
||||
const migration = createElement("a", "Check exact ESP32 migration ZIP");
|
||||
migration.href = migrationUrl;
|
||||
actions.appendChild(migration);
|
||||
}
|
||||
card.appendChild(actions);
|
||||
|
||||
const steps = createElement("div");
|
||||
@@ -1884,6 +1912,7 @@
|
||||
runtimeDirections: runtimeDirections,
|
||||
renderRuntimeDirections: renderRuntimeDirections,
|
||||
installSteps: installSteps,
|
||||
migrationReleaseUrl: migrationReleaseUrl,
|
||||
humanizeHardware: humanizeHardware,
|
||||
humanizeVariant: humanizeVariant,
|
||||
labelFor: labelFor,
|
||||
|
||||
+27
-14
@@ -27,6 +27,13 @@ from the published firmware assets.
|
||||
<strong>Full install / layout migration (merged .bin)</strong>. Narrower profiles
|
||||
remain available when their reduced transport or feature set is intentional.
|
||||
</p>
|
||||
<p>
|
||||
Upgrading an existing ESP32 infrastructure node from a smaller partition
|
||||
layout? The selected Full result links to the utility release. If an
|
||||
exact board and role migration ZIP is listed, follow its included README
|
||||
for a supported Wi-Fi or LoRa route. USB installation uses the matching
|
||||
merged image instead. An app-only .bin cannot change the partition table.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<p class="firmware-picker-order-note">
|
||||
@@ -229,9 +236,12 @@ 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 the exact-board
|
||||
merged image over USB. A running application cannot safely move its own active
|
||||
and inactive partitions.
|
||||
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](https://github.com/mikecarper/MeshCore/releases/tag/utility-v1.17.1.7-halo-keymind-cascade-dev-2d03e098).
|
||||
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.
|
||||
|
||||
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
|
||||
@@ -353,12 +363,16 @@ See the [two-profile setup guide](radio_profiles.md#companion-messages-on-both-p
|
||||
| --- | --- |
|
||||
| <code>-merged.bin</code> | Erase/fresh install, recovery, role migration, or partition-profile change on ESP32 over USB |
|
||||
| Non-merged <code>.bin</code> | Update an existing same-board, same-role, same-partition installation |
|
||||
| <code>.zip</code> | Native nRF52 Serial DFU update package; it is not an extra archive |
|
||||
| <code>*-migration.zip</code> | Exact ESP32 board and role staged partition migration; follow its included README for Wi-Fi or LoRa steps |
|
||||
| Other <code>.zip</code> firmware shown by the picker | Native nRF52 Serial DFU update package; it is not an extra archive |
|
||||
| <code>.uf2</code> | UF2 bootloader drag-and-drop install or update |
|
||||
| <code>.hex</code> | Erase/recovery flash with a supported wired programmer |
|
||||
|
||||
Never send a merged ESP32 image through browser OTA or LoRa OTA. Back up the
|
||||
node configuration and verify every filename suffix before flashing.
|
||||
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
|
||||
|
||||
@@ -420,15 +434,14 @@ 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 canonical Full image with a larger partition table. Their Full image keeps
|
||||
the ordinary target identity for future mOTA updates, but the first install is
|
||||
always its exact `-merged.bin` over USB: LoRa mOTA intentionally rejects a
|
||||
package whose partition signature differs from the running layout. During this
|
||||
transition the portable artifact remains published for already-installed
|
||||
nodes. The current migration set is LilyGo T3S3 SX1262/SX1276 repeater and
|
||||
room-server roles, Station G2 repeater and room-server roles, and ThinkNode M2
|
||||
repeater and room-server roles. Station G2 moves to two 6.25 MiB slots;
|
||||
the 4 MiB T3S3 and ThinkNode M2 boards move to two 1984 KiB slots.
|
||||
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
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ The release family contains 536 qualified firmware profiles on five GitHub relea
|
||||
## Installation
|
||||
|
||||
- Match the exact board and radio variant. Use the application image only with a compatible bootloader and partition layout.
|
||||
- For an ESP32 that needs the expanded Full layout, use its exact board and role package from the utility release page. The 94 migration packages and complete migration bundle are included there. Read the package README before installation.
|
||||
- For an ESP32 that needs the expanded Full layout, flash the exact merged image over USB, or use a supported exact board and role migration ZIP from the utility release for a staged Wi-Fi or LoRa route. The 94 migration packages and complete bundle are included there. Read the package README before installation; the bridge writes the partition table and a power loss can require cable recovery. Do not send a loose app-only Full image directly to an older layout.
|
||||
- nRF52 application UF2 and DFU packages do not install a bootloader. Use the matching OTAFIX 2.4.8 bootloader where required.
|
||||
- The RAK 3x72, Tiny Relay, Wio-E5 Mini, and Wio-E5 USB Companion images retain their framed USB transport and 32 KiB LittleFS area. Packet diagnostics are omitted on these four 256 KiB STM32WL targets to keep the application within flash.
|
||||
|
||||
|
||||
Reference in new issue
Block a user