Tabla de particiones ESP32: mapa de la flash y OTA

Qué es la tabla de particiones del ESP32, cómo leer las columnas de partitions.csv, los esquemas de Arduino-ESP32 con sus tamaños y qué significa N16R8.

Publicado
Tiempo de lectura
11 min
Categoría
Guías
Un maker con gafas mete un bloque azul app0 en un hueco de una larga barra de flash hecha de bloques nvs, app1 y spiffs, con un pequeño icono de chip a la izquierda.

En resumen

La tabla de particiones del ESP32 está en 0x8000 y reparte la flash en nvs, otadata, app y sistema de archivos. El archivo huge_app.csv de OpenGizmo da un solo slot de app de 3 MB y sin OTA.

La tabla de particiones del ESP32 es un pequeño mapa guardado en la flash en el offset 0x8000 que le dice al bootloader dónde están la app, el almacén de ajustes (nvs), los datos OTA y el sistema de archivos. La eliges con un archivo partitions.csv o con un esquema incluido como default.csv o huge_app.csv. Si la tabla se pasa del tamaño real de la flash, la documentación de esptool de Espressif advierte que el chip no funcionará correctamente.

Esta guía lee ese mapa como lo hace el chip: las columnas del CSV, los esquemas de Arduino-ESP32 con sus tamaños en KB, por qué el offset del bootloader cambia según el chip y qué significa N16R8 en el nombre de un módulo para tu distribución. El ejemplo real es el Gizmo Ticker: decodifiqué el release-partitions.bin que escribe su flasher y lo comprobé con la documentación de Espressif y con los archivos CSV de Arduino-ESP32.

¿Qué es la tabla de particiones del ESP32?

Una tabla de particiones divide el chip de flash externa en regiones con nombre, tipo, offset y tamaño. La guía de tablas de particiones de Espressif dice que por defecto se flashea en 0x8000, ocupa un sector de 4 KB y mide 0xC00 bytes, porque admite como máximo 95 entradas, seguidas de una suma MD5 que el bootloader usa para comprobar su integridad.

Un maker sostiene una placa XIAO junto a una tira de papel doblada con secciones de colores rotuladas nvs y app0, como un mapa de su flash

El bootloader es el primer programa que se ejecuta desde la flash. La página del bootloader de ESP-IDF enumera sus tareas: elegir la partición de aplicación que se va a arrancar según la tabla de particiones y ota_data, si existe, cargar la imagen en RAM y cederle el control. Así que la tabla no es un ajuste dentro de tu app: es un archivo en la flash que existe antes que tu código.

Una tabla típica tiene cuatro tipos de particiones:

  • nvs: almacén clave-valor para ajustes y datos de Wi-Fi, que usa la librería Preferences
  • otadata: guarda qué slot de app OTA arrancar, 0x2000 bytes
  • slots de app (factory, ota_0, ota_1): las imágenes del firmware
  • particiones de datos como spiffs o coredump: un sistema de archivos, volcados de fallos o tus propios bytes

El mapa de la flash del Gizmo Ticker para huge_app.csv en una placa de 8 MB: bootloader, tabla, nvs, otadata, un app0 de 3 MB, 896 KB de spiffs, coredump y 4 MB sin partición

¿Cómo es un archivo partitions.csv?

El CSV tiene seis columnas: name, type, subtype, offset, size y flags. Los espacios se ignoran, las líneas que empiezan con # son comentarios y los tamaños pueden ir en hexadecimal, en decimal o con K y M. Un nombre mide como máximo 16 bytes, incluido el terminador. Esta es la tabla real de todos los firmwares de OpenGizmo, del huge_app.csv del core Arduino-ESP32, tal como estaba el 14 de noviembre de 2026 (aquí falta su línea de comentario con los nombres de las columnas):

huge_app.csv
huge_app.csv
nvs,      data, nvs,     0x9000,  0x5000,
otadata,  data, ota,     0xe000,  0x2000,
app0,     app,  ota_0,   0x10000, 0x300000,
spiffs,   data, spiffs,  0x310000,0xE0000,
coredump, data, coredump,0x3F0000,0x10000,
Lín. 5, col. 1UTF-8csv

Tres reglas explican casi todos los números, todas de la guía de ESP-IDF. Los offsets son múltiplos de 4 KB (0x1000), el tamaño del sector de la flash. Una partición app debe empezar en un múltiplo de 64 KB (0x10000): por eso la primera app está en 0x10000 y la zona de 0x9000 a 0xFFFF, antes de ella, solo tiene pequeñas particiones de datos. Y si dejas un offset en blanco, la partición empieza justo después de la anterior, y las de app se alinean solas.

El bootloader y las librerías buscan el tipo y el subtipo, no el nombre. Según la misma guía, la partición nvs por defecto es la que tiene tipo data y subtipo nvs, y otadata tiene subtipo ota. La tabla binaria que escribe el flasher los guarda como números. Decodifiqué el archivo que se distribuye con unas pocas líneas de Python: nvs es data/0x02, otadata es data/0x00, app0 es app/0x10 (ota_0), spiffs es data/0x82 y coredump es data/0x03.

¿Qué tabla de particiones usan los firmwares de OpenGizmo?

Los tres definen board_build.partitions = huge_app.csv en platformio.ini, por ejemplo en el archivo del Ticker, con el comentario "One 3 MB app slot (no wireless updates), the same in every OpenGizmo firmware". Los release-partitions.bin del Ticker v1.2.0, del Reolink Switch v1.2.0 y de la Camera v1.0.0, tal como los sirvió la CDN el 14 de noviembre de 2026, son idénticos byte a byte (3.072 bytes) y se decodifican exactamente en el CSV de arriba.

¿Qué significa eso para el hardware?

  • Un solo slot de app, sin OTA. Hay un único slot ota_0 de 3 MB (3.072 KB) y ningún segundo slot, así que una imagen nueva no tiene dónde escribirse mientras la vieja se ejecuta. La comparativa de métodos OTA explica por qué eso descarta las actualizaciones por Wi-Fi y compara el tamaño de los slots con el de la app real.
  • Espacio para crecer. La app del Ticker v1.2.0 pesa 1.796.736 bytes, cerca del 57% del slot. La del Reolink Switch pesa 1.778.336 bytes y la de la Camera 1.722.192 bytes, sacados del tamaño de los archivos de la release.
  • Los ajustes están a salvo. La librería Preferences guarda los datos en la partición NVS, y tanto el storage.cpp del Ticker como el del Reolink Switch usan Preferences. El flasher escribe el bootloader, la tabla, boot_app0 y la app, y ninguno se solapa con 0x9000-0xDFFF, como describe la guía de flasheo desde el navegador.
  • Un sistema de archivos sin usar. La partición spiffs de 896 KB está declarada, pero al buscar LittleFS, SPIFFS y spiffs en el código de microcontroller/ de los tres firmwares no aparece nada. La librería compartida gizmo-common no entra en esa búsqueda. La partición coredump de 64 KB es donde la función de core dump de ESP-IDF escribe los datos de los fallos, y si estos firmwares la activan es algo que no comprobé.

Hay un detalle más que se pasa por alto fácil. La XIAO ESP32-S3 tiene 8 MB de flash (el modelo Plus tiene 16 MB) según la wiki de Seeed, y el archivo de placa de PlatformIO apunta a default_8MB.csv. El cambio de OpenGizmo a huge_app.csv termina en 0x400000, así que los 4 MB superiores de esa flash no tienen ninguna partición. Dejarlos vacíos no cuesta nada, y el comentario del platformio.ini del firmware dice justo que se usa la misma tabla en todos los firmwares de OpenGizmo, incluida la ESP32-CAM de 4 MB.

¿Cuáles son los esquemas de particiones por defecto de Arduino-ESP32?

El core Arduino-ESP32 trae decenas de tablas ya hechas en su carpeta tools/partitions: el 14 de noviembre de 2026 tenía más de 50 archivos. En Arduino IDE son el menú Herramientas, Partition Scheme; en PlatformIO pones el nombre del archivo en board_build.partitions, como muestra la documentación de PlatformIO para Espressif 32. Estos son los que más te vas a encontrar:

Archivo del esquemaFlash necesaria (MB)Slots de appCada slot de app (KB)Sistema de archivos (KB)
default.csv42 (OTA)1.2801.408
min_spiffs.csv42 (OTA)1.920128
no_ota.csv412.0481.920
huge_app.csv413.072896
default_8MB.csv82 (OTA)3.2641.536
default_16MB.csv162 (OTA)6.4003.456

Calculé los valores en KB a partir de los offsets y tamaños de cada CSV (default.csv, min_spiffs.csv, no_ota.csv, default_8MB.csv y default_16MB.csv). La columna "Flash necesaria" es donde termina la última partición, un coredump de 64 KB: 0x400000, 0x800000 o 0x1000000. Estos archivos cambian entre versiones del core, así que revisa la que usas para compilar.

El patrón es el trueque en el que gira toda la tabla. La flash es un presupuesto fijo, y cada slot de app, el sistema de archivos y los datos OTA compiten por ella. Una tabla con dos slots de app reduce a la mitad el espacio de cada uno. Por eso una app de 1,7 MB como la del Ticker no cabe en los slots de 1.280 KB de default.csv, y por eso huge_app.csv renuncia al segundo slot para tener uno grande.

¿Por qué cambian los offsets de la flash entre chips?

La tabla está en 0x8000 tanto en el ESP32 clásico como en el ESP32-S3, pero el bootloader se mueve. Las páginas del bootloader de ESP-IDF dicen que el bootloader de segunda etapa está en 0x1000 en el ESP32 y en 0x0 en el ESP32-S3, el ESP32-C3 y el ESP32-C6. Los manifiestos de OpenGizmo muestran el efecto:

ParteGizmo Camera (ESP32)Gizmo Ticker (ESP32-S3)Tamaño (bytes)
bootloader0x1000 (4096)0x0 (0)23.520 en ESP32, 19.968 en S3
tabla de particiones0x8000 (32768)0x8000 (32768)3.072
boot_app00xE000 (57344)0xE000 (57344)8.192
app0x10000 (65536)0x10000 (65536)1.722.192 en Camera, 1.796.736 en Ticker

Los manifiestos están en cdn.opengizmo.dev y los tamaños salen de los archivos que enumeran. Fíjate en que boot_app0 mide 8.192 bytes en 0xE000, que es justo el offset y el tamaño de otadata en la tabla de arriba. Su primer sector empieza con el valor 1 y por lo demás está lleno de 0xFF salvo unos pocos bytes, y el segundo sector empieza con 0. Eso encaja con una imagen inicial de datos OTA que selecciona el primer slot de app, pero no lo comprobé en el código fuente de ESP-IDF, así que tómalo como una inferencia. Si diseñas tu propia tabla, mantén ese offset alineado con el lugar donde pongas otadata, o revisa qué escribe tu herramienta de compilación.

El offset de la propia tabla tampoco es fijo: ESP-IDF lo define con CONFIG_PARTITION_TABLE_OFFSET y dice que, si lo cambias, actualices los offsets fijos de tu CSV. El artículo sobre flasheo desde el navegador muestra cómo esos offsets acaban en un manifest.json.

¿Qué significan N16R8 y N8R2?

En el nombre de un módulo de Espressif, N es el tamaño de la flash en megabytes y R el de la PSRAM en megabytes. La hoja de datos del ESP32-S3-WROOM-1 de Espressif (versión 1.8) los enumera en sus tablas comparativas. La PSRAM es RAM adicional en un die aparte, así que nunca aparece en la tabla de particiones. Solo cuenta el número de la flash.

El código del módulo N16R8 partido en dos: N16 son 16 MB de flash quad SPI que aloja la tabla de particiones, R8 son 8 MB de PSRAM octal que es RAM y usa de GPIO35 a GPIO37

MóduloFlash (MB)PSRAM (MB)Tabla que encaja
ESP32-S3-WROOM-1-N8R28, quad SPI2, quad SPIdefault_8MB.csv
ESP32-S3-WROOM-1-N8R88, quad SPI8, octal SPIdefault_8MB.csv
ESP32-S3-WROOM-1-N16R816, quad SPI8, octal SPIdefault_16MB.csv

Detrás de esa tabla hay dos puntos prácticos. Primero, la hoja de datos dice que en los módulos con PSRAM octal (las series R8 y R16V) los pines IO35, IO36 e IO37 están conectados a la PSRAM y no están disponibles para otros usos, así que un N16R8 pierde tres GPIO que un N8R2 conserva. Segundo, "Tabla que encaja" es un emparejamiento mío, no de Espressif: sirve cualquier tabla mientras termine dentro del tamaño de la flash. La documentación de esptool advierte que las particiones deben caber en el tamaño configurado, o el ESP32 no funcionará correctamente.

La XIAO ESP32-S3 es una placa, no un módulo WROOM, pero la wiki de Seeed da el mismo par de datos: el chip ESP32-S3R8 con 8 MB de PSRAM y 8 MB de flash. Para saber qué chip comprar en primer lugar, mira ¿Qué ESP32 deberías comprar? y la comparativa de XIAO.

¿Cómo dimensionar las particiones de app, OTA y sistema de archivos?

Parte del tamaño de la app hacia afuera y anota la tabla antes de flashearla.

  1. Mide la app. Compila el firmware y mira el tamaño del .bin. Por ejemplo, el del Ticker es de 1.796.736 bytes.
  2. Decide si quieres OTA. Para actualizar por Wi-Fi necesitas otadata más dos slots de app, según la documentación OTA de ESP-IDF resumida en la comparativa OTA. Cada slot debe tener sitio para la app con margen para crecer.
  3. Sé realista con nvs. La documentación de NVS da 12 KiB (0x3000) como mínimo para un uso normal de lectura y escritura. Las tablas de Arduino usan 0x5000 (20 KB).
  4. Gasta el resto en un sistema de archivos, o quítalo. Si nadie lo monta, un spiffs sin usar es espacio desperdiciado que podrías dar a los slots de app.
  5. Revisa la suma. La última partición debe terminar en el tamaño de la flash o antes, y todo offset de app debe ser múltiplo de 0x10000.

Por ejemplo, una placa de 8 MB con dos slots de 3 MB y un sistema de archivos pequeño podría usar la tabla de abajo. Es aritmética mía, no una tabla que haya construido ni flasheado, así que tómala como plantilla:

partitions.csv
partitions.csv
nvs,      data, nvs,     0x9000,   0x5000,
otadata,  data, ota,     0xe000,   0x2000,
app0,     app,  ota_0,   0x10000,  0x300000,
app1,     app,  ota_1,   0x310000, 0x300000,
spiffs,   data, spiffs,  0x610000, 0x1E0000,
coredump, data, coredump,0x7F0000, 0x10000,
Lín. 6, col. 1UTF-8csv

La última fila termina en 0x800000, justo 8 MB. En Arduino IDE, guárdala como partitions.csv en la carpeta del sketch y la compilación la usará en lugar de las tablas predefinidas, como describe el tutorial de particiones de Arduino-ESP32. En PlatformIO, apunta board_build.partitions al archivo.

Cambiar la tabla tiene un costo. ESP-IDF dice que actualizarla no borra los datos guardados con la tabla vieja. Como cada partición se encuentra por su offset, una partición movida o con otro tamaño leerá los bytes que ahora haya ahí (es mi lectura de cómo funcionan los offsets, no una cita de la documentación). Deja nvs donde está y los ajustes guardados siguen funcionando; si no, cuenta con empezar de cero.

¿Cómo encuentras los offsets y el tamaño de la flash de una placa?

Con tres comandos basta. Los dos primeros leen tu compilación y tu chip, el tercero lee lo que realmente hay en la placa.

Offsets desde la compilación, tamaño de la flash desde el chip
pio project metadata -e release --json-outputesptool flash-idesptool -p /dev/ttyACM0 read-flash 0x8000 0x1000 table.bin
  • pio project metadata imprime las imágenes de flash con sus direcciones y el offset de la aplicación. El package_firmware.py del Ticker lee justo eso para escribir el manifiesto, así que nunca tecleas un offset a mano.
  • esptool flash-id imprime el fabricante, el ID del dispositivo y el "Detected flash size", según los comandos básicos de esptool. Ejecútalo antes de elegir una tabla para una placa que no compraste tú.
  • read-flash copia la tabla fuera de la placa. La guía de ESP-IDF documenta gen_esp32part.py para convertir una tabla binaria otra vez en CSV, y yo decodifiqué los archivos distribuidos con un script corto mío.

Los nombres de los comandos son las formas con guion que usa la documentación actual de esptool; las versiones anteriores los escribían con guion bajo. Ajústalos a la versión que tengas instalada.

¿Qué decide por ti la tabla de particiones?

La tabla de particiones del ESP32 decide cómo se reparte un chip de flash de tamaño fijo entre tu app, una posible segunda app, tus ajustes y un sistema de archivos. Para OpenGizmo la respuesta fue deliberada: huge_app.csv, un solo slot de 3 MB, cerca del 57% ocupado por la app más grande, ajustes en nvs que una actualización por USB nunca toca, y sin OTA.

Conviene decir los límites en voz alta. Leí las tablas y decodifiqué los binarios distribuidos, pero no flasheé una tabla modificada en una placa, así que el CSV personalizado de arriba es pura aritmética, y el papel de boot_app0 es una inferencia a partir de su offset, su tamaño y sus primeros bytes. El siguiente paso útil es la comparativa de métodos OTA, que muestra qué le costaría a este layout un segundo slot, o el artículo Arduino IDE vs PlatformIO si todavía estás decidiendo dónde definir el esquema.

Preguntas frecuentes

Encuentra respuestas rápidas a las preguntas más comunes sobre este tema.

Según la documentación de ESP-IDF, la tabla de particiones del ESP32 se guarda por defecto en la flash, en el offset 0x8000. Ocupa un sector de 4 KB y admite hasta 95 entradas más una suma de comprobación MD5. El bootloader la lee en cada arranque para encontrar las particiones de app y de datos.

Publicado

¿Listo para montar tu propio gizmo?

Elige un proyecto open source con ESP32 y sigue su guía paso a paso, desde la lista de componentes y el cableado hasta el firmware y el primer arranque.

Lee también

Explora las categorías