ESP32 固件为什么装不下？读懂 Flash、分区表和 OTA 空间

idf.py -B build -D SDKCONFIG=build/sdkconfig -D SDKCONFIG_DEFAULTS=sdkconfig.defaults build
idf.py -B build size
python3 tools/budget.py --build build --flash-bytes 8388608 --flash-source planned-N8R8-not-measured --reserve-bytes 65536
python3 host/budget_test.py

idf.py -B build-bad -D SDKCONFIG=build-bad/sdkconfig -D 'SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.bad.defaults' build

python -m esptool --chip esp32s3 -p REPLACE_PORT flash_id
# 只有已核对实际8MiB才读这个长度；其它容量换用对应计划
mkdir -p backups
python -m esptool --chip esp32s3 -p REPLACE_PORT read_flash 0x0 0x800000 backups/flash-original.bin
python -m esptool --chip esp32s3 -p REPLACE_PORT read_flash 0x8000 0x1000 backups/partitions-original.bin
python "$IDF_PATH/components/partition_table/gen_esp32part.py" backups/partitions-original.bin backups/partitions-original.csv
python -c 'import hashlib,pathlib; p=pathlib.Path("backups/flash-original.bin"); print(p.stat().st_size,hashlib.sha256(p.read_bytes()).hexdigest())'

python -m esptool --chip esp32s3 -p REPLACE_PORT write_flash --flash_mode keep --flash_freq keep --flash_size keep 0x0 backups/flash-original.bin
python -m esptool --chip esp32s3 -p REPLACE_PORT verify_flash 0x0 backups/flash-original.bin

// ---- main/main.c ----
/* SPDX-License-Identifier: MIT */
#include <stdio.h>
#include <inttypes.h>
#include "esp_flash.h"
#include "esp_partition.h"
#include "esp_ota_ops.h"
#include "esp_app_desc.h"
#include "nvs_flash.h"
#include "nvs.h"
void app_main(void){
 uint32_t physical=0,available=0;esp_err_t e=esp_flash_get_physical_size(NULL,&physical);
 if(e!=ESP_OK){printf("E09 STOP flash size read: %s\n",esp_err_to_name(e));return;}
 e=esp_flash_get_size(NULL,&available);if(e!=ESP_OK){printf("E09 STOP available/header size read: %s\n",esp_err_to_name(e));return;}
 printf("E09 detected_physical_flash_bytes=%"PRIu32" available_header_flash_bytes=%"PRIu32" plan_bytes=8388608\n",physical,available);
 if(physical!=8388608||available!=8388608){puts("E09 STOP actual chip is not this 8MiB plan; do not infer capacity from PSRAM or a module nickname");return;}
 const esp_partition_t *running=esp_ota_get_running_partition(),*next=esp_ota_get_next_update_partition(NULL);
 const esp_app_desc_t *app=esp_app_get_description();
 printf("E09 version=%s project=%s IDF=%s running=%s next_slot=%s; this example does NOT perform OTA\n",app->version,app->project_name,app->idf_ver,running?running->label:"NONE",next?next->label:"NONE");
 esp_partition_iterator_t it=esp_partition_find(ESP_PARTITION_TYPE_ANY,ESP_PARTITION_SUBTYPE_ANY,NULL);
 while(it){const esp_partition_t *p=esp_partition_get(it);printf("E09 PART,%s,type=%u,subtype=%u,offset=0x%08"PRIx32",capacity_bytes=%"PRIu32"\n",p->label,p->type,p->subtype,p->address,p->size);it=esp_partition_next(it);}
 /* Iterator automatically released when next() returns NULL. Do not erase NVS
  * on init failure: this tutorial is about preserving existing device data. */
 e=nvs_flash_init();if(e!=ESP_OK){printf("E09 NVS_INIT=%s; no automatic erase\n",esp_err_to_name(e));return;}
 nvs_handle_t handle;e=nvs_open("e09",NVS_READONLY,&handle);
 if(e==ESP_ERR_NVS_NOT_FOUND){puts("E09 namespace missing: expected on clean flash; no write performed");return;}
 if(e!=ESP_OK){printf("E09 nvs_open=%s\n",esp_err_to_name(e));return;}
 uint32_t marker=0;e=nvs_get_u32(handle,"marker",&marker);nvs_close(handle);
 if(e==ESP_ERR_NVS_NOT_FOUND)puts("E09 marker missing; no default write or migration performed");
 else printf("E09 marker_read=%s marker=%"PRIu32"; compare only with your saved pre-migration record\n",esp_err_to_name(e),marker);
}


# ---- partitions.csv ----
# Name,Type,SubType,Offset,Size,Flags
nvs,data,nvs,0x9000,0x6000,
otadata,data,ota,0xf000,0x2000,
phy_init,data,phy,0x11000,0x1000,
ota_0,app,ota_0,0x20000,0x200000,
ota_1,app,ota_1,0x220000,0x200000,
model,data,0x40,0x420000,0x180000,
logs,data,spiffs,0x5a0000,0x260000,


# ---- partitions.bad.csv ----
# Deliberate overlap fixture; NEVER flash
# Name,Type,SubType,Offset,Size,Flags
nvs,data,nvs,0x9000,0x6000,
otadata,data,ota,0xf000,0x2000,
ota_0,app,ota_0,0x20000,0x200000,
ota_1,app,ota_1,0x210000,0x200000,

# ---- tools/budget.py ----
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Read actual build outputs and compute byte capacity, never flash anything.
Scope: this example's unencrypted/unsigned S3 table at0x8000, MD5 enabled.
A fitting image is not a valid OTA transaction, valid model, or available RAM.
"""
import argparse,hashlib,json,pathlib,struct

def read_table(path,flash_bytes):
 raw=pathlib.Path(path).read_bytes();parts=[];md5=hashlib.md5();verified=False;ended=False
 if len(raw)%32:raise ValueError('table length must be a multiple of32')
 for at in range(0,len(raw),32):
  record=raw[at:at+32]
  if record==b'\xff'*32:
   if raw[at:]!=b'\xff'*(len(raw)-at):raise ValueError('nonempty data after table terminator')
   ended=True;break
  if record[:2]==b'\xeb\xeb':
   if verified or record[:16]!=b'\xeb\xeb'+b'\xff'*14 or record[16:]!=md5.digest():raise ValueError('partition MD5 mismatch/duplicate')
   verified=True;continue
  if verified:raise ValueError('partition record after MD5')
  magic,kind,subtype,offset,size,label,flags=struct.unpack('<2sBBII16sI',record)
  if magic!=b'\xaa\x50':raise ValueError('invalid partition magic')
  label=label.split(b'\0',1)[0].decode('ascii')
  if not label or offset<0x9000 or offset%4096 or not size or size%4096:raise ValueError('invalid example partition offset/size/alignment')
  if kind==0 and offset%65536:raise ValueError('app must be64KiB aligned')
  if offset+size>flash_bytes:raise ValueError('partition exceeds declared Flash')
  if flags:raise ValueError('this unsigned/unencrypted budget does not accept partition flags')
  if any(x['name']==label for x in parts):raise ValueError('duplicate label')
  parts.append({'name':label,'type':kind,'subtype':subtype,'offset_bytes':offset,'capacity_bytes':size,'end_bytes':offset+size});md5.update(record)
 if not parts or not verified or not ended:raise ValueError('missing entries/MD5/end marker')
 for a,b in zip(sorted(parts,key=lambda p:p['offset_bytes']),sorted(parts,key=lambda p:p['offset_bytes'])[1:]):
  if a['end_bytes']>b['offset_bytes']:raise ValueError('partition overlap')
 return parts

def assess(parts,app_bytes,model_bytes,reserve_bytes):
 if min(app_bytes,reserve_bytes)<0 or app_bytes==0 or model_bytes<0:raise ValueError('positive app and nonnegative reserve/model required')
 slots=[p for p in parts if p['type']==0 and p['subtype'] in [16,17]]
 if len(slots)!=2 or {p['subtype'] for p in slots}!={16,17}:raise ValueError('two distinct ota_0/ota_1 slots required')
 ota=[p for p in parts if p['type']==1 and p['subtype']==0]
 if len(ota)!=1 or ota[0]['capacity_bytes']<8192:raise ValueError('otadata requires at least two4KiB sectors')
 model=next((p for p in parts if p['name']=='model' and p['type']==1),None)
 if model is None or model_bytes>model['capacity_bytes']:raise ValueError('model asset exceeds dedicated data partition')
 for p in slots:
  if app_bytes+reserve_bytes>p['capacity_bytes']:raise ValueError('app+declared reserve exceeds OTA slot '+p['name'])
 return {'app_image_bytes':app_bytes,'declared_reserve_bytes':reserve_bytes,'minimum_ota_capacity_bytes':min(p['capacity_bytes'] for p in slots),'minimum_ota_headroom_after_reserve_bytes':min(p['capacity_bytes'] for p in slots)-app_bytes-reserve_bytes,'model_asset_bytes':model_bytes,'model_capacity_bytes':model['capacity_bytes'],'model_headroom_bytes':model['capacity_bytes']-model_bytes,'scope':'file/partition byte budget only; no OTA download/switch/rollback, no model validity/RAM guarantee'}

def inspect(build,flash_bytes,flash_source,reserve,model_bin=None):
 build=pathlib.Path(build).resolve()
 if flash_bytes!=8388608:raise ValueError('this fixed N8R8 plan requires8388608 declared bytes; do not change the physical part by editing this number')
 description=json.loads((build/'project_description.json').read_text());flasher=json.loads((build/'flasher_args.json').read_text())
 app=(build/description['app_bin']).resolve();application=(build/flasher['app']['file']).resolve()
 if app!=application or int(flasher['app']['offset'],0)!=0x20000:raise ValueError('app metadata mismatch; do not pass a merged/full Flash image as an app')
 table=(build/flasher['partition-table']['file']).resolve()
 if int(flasher['partition-table']['offset'],0)!=0x8000:raise ValueError('this example supports table offset0x8000 only')
 parts=read_table(table,flash_bytes);model_bytes=pathlib.Path(model_bin).stat().st_size if model_bin else 0
 if app.read_bytes()[:1]!=b'\xe9':raise ValueError('not the expected app image header')
 result=assess(parts,app.stat().st_size,model_bytes,reserve)
 result.update(declared_flash_bytes=flash_bytes,flash_capacity_basis=flash_source,partitions=parts,app_path=str(app),app_sha256=hashlib.sha256(app.read_bytes()).hexdigest(),table_sha256=hashlib.sha256(table.read_bytes()).hexdigest(),outside_app_data_partition_bytes=flash_bytes-sum(p['capacity_bytes'] for p in parts),outside_partition_note='includes bootloader/table and alignment gaps; NOT all free or writable',model_path=str(model_bin) if model_bin else None)
 return result
if __name__=='__main__':
 p=argparse.ArgumentParser();p.add_argument('--build',required=True);p.add_argument('--flash-bytes',required=True,type=int);p.add_argument('--flash-source',choices=['planned-N8R8-not-measured','measured-by-user-esptool-flash-id'],required=True);p.add_argument('--reserve-bytes',type=int,default=65536);p.add_argument('--model-bin');a=p.parse_args()
 try:print(json.dumps(inspect(a.build,a.flash_bytes,a.flash_source,a.reserve_bytes,a.model_bin),indent=2))
 except (ValueError,KeyError,OSError) as e:p.exit(2,'BUDGET_REJECTED: '+str(e)+'\n')