Commander1024/ESP32_Serial_Swiss_Army_Knife
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add custom dual-OTA flash partition layout

Browse Source 
Document the 16 MiB flash layout and one-time migration procedure.
This commit is contained in:
Commander1024
2026-08-23 00:07:23 +02:00
parent 2524f43fac
commit 6793f6bcc2
3 changed files with 44 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+33
View File
@@ -18,6 +18,39 @@ The firmware has completed **Phase 0 hardware characterization** and the **Phase
See [`wiring.md`](wiring.md) for the hardware profile, GPIO assignments, loopback diagrams, safety notes, and the recommended test sequence. The initial profile covers the ESP32-S3-DevKitC-1 N16R8 and the Adafruit MAX3243 full-pinout RS-232 breakout.
## Flash partition layout
The N16R8 target has 16 MiB flash and 8 MiB octal PSRAM. PlatformIO uses the custom [`partitions.csv`](partitions.csv) layout:
| Partition | Offset | Size | Purpose |
|---|---:|---:|---|
| `nvs` | `0x009000` | 512 KiB | Serial configuration and future Wi-Fi/provisioning data |
| `otadata` | `0x089000` | 8 KiB | Active OTA-slot selection metadata |
| `phy_init` | `0x08B000` | 4 KiB | Optional PHY initialization data |
| `nvs_key` | `0x08C000` | 4 KiB | Reserved for future encrypted-NVS keys |
| `coredump` | `0x08D000` | 128 KiB | Reserved for flash core dumps |
| `ota_0` | `0x0B0000` | 4 MiB | Primary application/OTA slot |
| `ota_1` | `0x4B0000` | 4 MiB | Alternate application/OTA slot |
| `storage` | `0x8B0000` | 7488 KiB | Future LittleFS web assets, certificates, logs, and files |
Application offsets are aligned to the ESP32-S3's required 64 KiB boundary. The final storage partition ends at `0x1000000`, exactly the end of the 16 MiB flash chip.
The partition table reserves OTA and LittleFS space but does not by itself implement OTA downloads, rollback confirmation, core-dump handling, NVS encryption, or filesystem mounting. Those features will be enabled deliberately in later phases.
### One-time migration from the default partition table
The previous 1 MiB factory application began at `0x10000`, which is now inside the enlarged NVS address range. A normal upload does not erase all stale bytes there. Perform a full flash erase once when first switching to this layout:
```sh
pio run --target erase
pio run --target upload
pio device monitor -b 115200
```
This erases the currently saved serial configuration and all other flash contents. The firmware will boot with safe serial defaults and recreate NVS. Subsequent ordinary uploads do not require another full erase.
PlatformIO's application-size report should now use the 4 MiB `ota_0` slot instead of the previous 1 MiB factory partition.
## Build
```sh
partitions.csv
+10
View File
@@ -0,0 +1,10 @@
# ESP32-S3-WROOM-1-N16R8: dual-OTA layout for 16 MiB flash
# Name, Type, SubType, Offset, Size, Flags
nvs, data, nvs, 0x9000, 0x80000,
otadata, data, ota, 0x89000, 0x2000,
phy_init, data, phy, 0x8B000, 0x1000,
nvs_key, data, nvs_keys, 0x8C000, 0x1000, encrypted
coredump, data, coredump, 0x8D000, 0x20000,
ota_0, app, ota_0, 0xB0000, 0x400000,
ota_1, app, ota_1, 0x4B0000, 0x400000,
storage, data, littlefs, 0x8B0000, 0x750000,
1 # ESP32-S3-WROOM-1-N16R8: dual-OTA layout for 16 MiB flash
2 # Name, Type, SubType, Offset, Size, Flags
3 nvs, data, nvs, 0x9000, 0x80000,
4 otadata, data, ota, 0x89000, 0x2000,
5 phy_init, data, phy, 0x8B000, 0x1000,
6 nvs_key, data, nvs_keys, 0x8C000, 0x1000, encrypted
7 coredump, data, coredump, 0x8D000, 0x20000,
8 ota_0, app, ota_0, 0xB0000, 0x400000,
9 ota_1, app, ota_1, 0x4B0000, 0x400000,
10 storage, data, littlefs, 0x8B0000, 0x750000,
platformio.ini
+1
View File
@@ -9,6 +9,7 @@ framework = espidf
board_build.flash_mode = qio
board_build.flash_size = 16MB
board_upload.flash_size = 16MB
board_build.partitions = partitions.csv
monitor_speed = 115200
monitor_filters = esp32_exception_decoder