Blog
esptool: comandos, flags e correções
O esptool é a ferramenta que todo dono de ESP32 acaba rodando na mão um dia — a Arduino IDE esconde, o PlatformIO esconde, e então um dia a gravação falha e você está digitando Python num terminal. Comandos, flags e os erros que não fazem sentido até você vê-los uma vez.
O que é o esptool?
O esptool é a ferramenta oficial de linha de comando da Espressif para conversar com chips ESP32 pela serial — gravar, apagar, ler memória, puxar identidade. Todo caminho de gravação passa por ele: a Arduino IDE embute, o PlatformIO embute, instaladores web rodam. Conhecê-lo é a hora de debug que você nunca repete.
Como verificar se o esptool está instalado?
Rode esptool.py version. Um número de versão (5.x, 4.7, o que estiver atual) significa que você está pronto. “Command not found” significa pip install esptool — Python 3.7+ é o único requisito.
Quais são os comandos mais úteis do esptool?
Os comandos centrais são cinco: chip_id identifica o chip, flash_id lê o flash, read_mac imprime o MAC de fábrica, erase_flash apaga tudo e write_flash grava um binário num endereço — 90% do uso diário. O merge_bin combina vários binários numa imagem só para entregar a outra pessoa.
Como gravar firmware com o esptool?
Uma linha resolve: esptool.py write_flash 0x0 firmware.bin, com --port COM3 adicionado na maioria das máquinas. O offset importa mais do que a galera pensa: 0x0 é onde uma imagem de fábrica começa, enquanto apps ESP-IDF vão para 0x10000. Grave no offset errado e a placa inicia sem nada, que é como muitas placas “tijoladas” na real são placas mal gravadas. O FAQ de gravação cobre offsets e layouts de partição.
Como apagar o flash do ESP32?
esptool.py erase_flash apaga o chip inteiro em segundos. O aviso que todo mundo pula: ele remove também o bootloader, então uma placa que rodava firmware de fábrica não inicia até você gravar algo de volta. Apagar conserta tabela de partição corrompida e boot loops — trate como um reset, não um conserto.
Dá para fazer backup do flash antes de mexer?
esptool.py read_flash 0x0 0x400000 backup.bin despeja os primeiros 4 MB num arquivo — o movimento padrão de pânico-antes-de-atualizar; restaurar é write_flash no mesmo offset. Uma ressalva: um backup simples não restaura numa placa com criptografia de flash ativada — aprendi isso do jeito difícil na primavera passada.
O que fazem –port, –baud e as outras flags?
--port escolhe a porta serial (COM3 no Windows, /dev/ttyUSB0 no Linux, /dev/cu.usbserial-XXXX no macOS); --baud define a velocidade — 460800 é uma escolha rápida e segura, e alguns chips USB gaguejam acima de 921600, então depende do chip de ponte da sua placa; --chip força o alvo se a autodetecção falhar. O resto você ignora até um erro nomear uma.
Por que recebo “Failed to Connect to ESP32: Timed Out Waiting for Packet Header”?
O chip não está em modo boot. O esptool precisa do bootloader da ROM escutando, e as causas clássicas são: um circuito de auto-reset que não está ligado (módulos puros), a porta errada, ou outra coisa segurando a linha serial — eu uma vez persegui esse erro exato por uma hora porque o Serial Monitor ainda estava aberto. Segure BOOT, toque EN, solte BOOT, tente de novo. Em módulos puros, amarre GPIO0 no terra ao ligar. O FAQ de debug tem mais.
Por que a gravação trava em 100%?
Os dados foram escritos e a placa resetou para o firmware novo, ficando em silêncio — normal quando o firmware não tem saída serial. Um boot loop no lugar disso significa que a imagem mira o tamanho de flash ou o chip errado. Confirme com esptool.py chip_id, cheque flash_id, regrave.
O esptool funciona igual no Windows, Linux e Mac?
Sim — mesmos comandos, flags e offsets, porque é um script Python em toda plataforma. Só os nomes de porta e os drivers mudam; nossa base de conhecimento tem as notas de driver para cada SO.