Blog
esptool: comandos, flags y arreglos
esptool es la herramienta que todo dueño de un ESP32 acaba ejecutando a mano tarde o temprano — el Arduino IDE la esconde, PlatformIO la esconde, y un día el flasheo falla y estás tecleando Python en un terminal. Comandos, flags y los errores que no tienen sentido hasta que los has visto una vez.
¿Qué es esptool?
esptool es la herramienta oficial de línea de comandos de Espressif para hablar con los chips ESP32 por serie — flashear, borrar, leer memoria, sacar la identidad. Todo camino de flasheo pasa por ella: el Arduino IDE la incluye, PlatformIO la incluye, los instaladores web la ejecutan. Conocerla es la hora de depuración que nunca repites.
¿Cómo compruebo que esptool está instalado?
Ejecuta esptool.py version. Un número de versión (5.x, 4.7, lo que esté vigente) significa que estás listo. “Command not found” significa pip install esptool — Python 3.7+ es el único requisito.
¿Cuáles son los comandos de esptool más útiles?
Los comandos centrales de esptool son cinco: chip_id identifica el chip, flash_id lee el flash, read_mac imprime la MAC de fábrica, erase_flash lo borra todo, y write_flash escribe un binario en una dirección — el 90% del uso diario. merge_bin combina varios binarios en una sola imagen para entregársela a alguien.
¿Cómo flasheo firmware con esptool?
Una línea basta: esptool.py write_flash 0x0 firmware.bin, con --port COM3 añadido en la mayoría de máquinas. El offset importa más de lo que la gente cree: 0x0 es donde arranca una imagen de fábrica, mientras que las apps de ESP-IDF van a 0x10000. Flashear en el offset equivocado y la placa arranca en nada, que es cómo muchas placas “bricked” resultan estar mal flasheadas. El FAQ de flasheo cubre offsets y layouts de particiones.
¿Cómo borro el flash del ESP32?
esptool.py erase_flash limpia todo el chip en segundos. El aviso que todo el mundo se salta: también quita el bootloader, así que una placa que corría firmware de fábrica no arrancará hasta que le flashees algo. Borrar arregla una tabla de particiones corrupta y los boot loops — trátalo como un reset, no como una reparación.
¿Puedo hacer una copia de seguridad del flash antes de tocarlo?
esptool.py read_flash 0x0 0x400000 backup.bin vuelca los primeros 4 MB a un archivo — el movimiento estándar de pánico-antes-de-actualizar; restaurar es write_flash en el mismo offset. Un aviso: una copia normal no se restaura en una placa con cifrado de flash activado — lo aprendí por las malas la primavera pasada.
¿Qué hacen –port, –baud y los demás flags?
--port elige el puerto serie (COM3 en Windows, /dev/ttyUSB0 en Linux, /dev/cu.usbserial-XXXX en macOS); --baud fija la velocidad — 460800 es una opción rápida segura, y algunos chips USB tartamudean por encima de 921600, así que depende del chip puente de tu placa; --chip fuerza el target si la autodetección falla. El resto puedes ignorarlos hasta que un error nombre uno.
¿Por qué me sale “Failed to Connect to ESP32: Timed Out Waiting for Packet Header”?
El chip no está en modo boot. esptool necesita el bootloader de ROM escuchando, y las causas clásicas son: un circuito de auto-reset que no está cableado (módulos pelados), el puerto equivocado, o algo más ocupando la línea serie — una vez perseguí este error exacto durante una hora porque el Serial Monitor seguía abierto. Mantén BOOT, toca EN, suelta BOOT, reintenta. En módulos pelados, ata GPIO0 a tierra al encender. El FAQ de depuración tiene más.
¿Por qué el flasheo se cuelga al 100%?
Los datos están escritos y la placa resetea al firmware nuevo, quedándose en silencio — normal cuando el firmware no tiene salida serie. Un boot loop en su lugar significa que la imagen apunta a un tamaño de flash o un chip equivocado. Confirma con esptool.py chip_id, revisa flash_id, re-flashea.
¿Funciona esptool igual en Windows, Linux y Mac?
Sí — mismos comandos, flags y offsets, porque es un script Python en todas las plataformas. Solo cambian el nombre del puerto y los drivers; nuestra KB tiene las notas de drivers para cada SO.
Los proyectos de este tema se ejecutan directamente en el simulador gratuito de sensbench: circuito preconectado, firmware incluido, sin cuenta y sin instalación.