O conjunto de ferramentas
Qual versão do ESP-IDF o bot precisa e por quê, como compilar as duas placas na imagem Docker da Espressif e gravá-las a partir do Windows, onde o Docker não alcança as portas USB.
O que faz
As duas placas são programadas com o ESP-IDF, o framework oficial da Espressif para os chips ESP32. Este guia monta um único conjunto de ferramentas que compila a barriga (ESP32-P4, Xiaozhi) e a cabeça (ESP32-S3, o nosso próprio firmware), e explica como o firmware vai do seu PC para cada placa.
A versão curta:
- Uma versão do ESP-IDF para as duas placas: o branch
release/v6.1. - A compilação acontece no Docker, na imagem
espressif/idf:release-v6.1da Espressif, de modo que nada além do Docker é instalado no PC. - A gravação acontece no próprio Windows, porque um contêiner Docker no Windows não enxerga as portas seriais USB.
Se você prefere um editor com botões, a extensão ESP-IDF para o VS Code faz o mesmo trabalho de forma nativa, e este guia também trata dela.
Como funciona por dentro
Duas versões documentadas, uma escolha
As duas fontes para a barriga discordam sobre a versão:
- A Waveshare recomenda o ESP-IDF V5.3.1 ou posterior para a ESP32-P4-WIFI6-Touch-LCD-4.3 na sua página de ESP-IDF, e o seu passo a passo usa a V5.5.2.
- O Xiaozhi (78/xiaozhi-esp32) diz no seu README que o projeto agora exige o ESP-IDF v6.0.1 ou posterior, recomenda o branch
release/v6.1e afirma que o ESP-IDF 5.x não é mais suportado.
O bot segue o Xiaozhi, porque o Xiaozhi é o firmware que roda na barriga. Um conjunto de ferramentas 5.x não consegue compilá-lo de jeito nenhum, enquanto a placa em si não se importa: o próprio pacote de suporte de placa da Waveshare declara idf: '>=5.4', então a 6.x está dentro da sua faixa. A 5.3.1 da Waveshare é um piso para os seus exemplos, não um teto.
O Xiaozhi recomenda o branch, e não a tag v6.1, por um motivo concreto: o seu README aponta para a issue #2344, em que a tag v6.1 traz uma biblioteca de Wi-Fi do ESP32-C3 que não corresponde ao seu próprio cabeçalho. A própria CI do Xiaozhi compila cada placa na imagem espressif/idf:release-v6.1, então o bot usa exatamente essa imagem. Depois de trocar de revisão do ESP-IDF, o README pede idf.py fullclean no projeto antes de compilar de novo.
A cabeça roda o nosso próprio firmware pequeno, então não tem exigência de versão própria. Ela é compilada com a mesma imagem, o que significa um conjunto de ferramentas, um conjunto de hábitos e um cache.
Compilar no Docker
A Espressif publica o ESP-IDF como uma imagem Docker, documentada no guia IDF Docker Image. As suas tags seguem três padrões: latest acompanha o master, vX.Y corresponde a uma versão e release-vX.Y acompanha o branch dessa versão. O contêiner tem o ESP-IDF, os compiladores e o Python prontos; a pasta do seu projeto é montada dentro dele.
O comando documentado, a partir da pasta do projeto, é:
docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp espressif/idf idf.py build
--rmremove o contêiner quando a compilação termina.-v $PWD:/projectmonta a sua pasta em/project, de modo que o resultado da compilação cai na sua pasta.-w /projectcomeça nessa pasta.-u $UID(Linux e macOS) mantém os arquivos de saída como seus, e não do root.-e HOME=/tmpdá aoidf.pyum lugar para guardar o seu cache.
O guia também documenta -e IDF_GIT_SAFE_DIR='/project' para o caso em que o git informa “dubious ownership” (propriedade duvidosa) do repositório montado, o que acontece com facilidade num disco do Windows.
Alvos: esp32p4 e esp32s3
O ESP-IDF compila para um chip de cada vez, escolhido com idf.py set-target. Os comandos do guia de início para Windows da Espressif são:
idf.py set-target esp32p4
idf.py menuconfig
idf.py build
idf.py -p PORT flash
idf.py -p PORT monitor
A cabeça usa idf.py set-target esp32s3. O guia de placa personalizada do Xiaozhi define o alvo “first time, or when switching targets” (na primeira vez, ou ao trocar de alvo), não antes de cada compilação. Para sair do monitor, pressione Ctrl+].
Para a barriga, o Xiaozhi reúne esses passos em scripts/build.py, que lê o config.json da placa, define o alvo e as opções da placa, compila e junta tudo em build/merged-binary.bin. O guia 3 o usa.
Por que o Docker não consegue gravar no Windows
O guia IDF Docker diz isso com clareza: os comandos que conversam com a placa, como idf.py flash e idf.py monitor, precisam que a porta serial seja passada para o contêiner. No Linux, a opção de dispositivo do Docker faz isso. No Windows, o guia diz “currently, this is not possible with Docker for Windows” (atualmente, isso não é possível com o Docker for Windows), e a mesma limitação vale para o Docker for Mac.
Por isso o bot divide o trabalho: o Docker compila, o Windows grava. Há duas formas de fazer a segunda metade, ambas da documentação da Espressif.
A partir do host com o esptool. O esptool é a ferramenta de gravação da Espressif. Um binário mesclado, como o merged-binary.bin do Xiaozhi, vai no offset 0x0; a página de comandos básicos do esptool mostra a forma esptool --port COM4 write-flash 0x1000 my_app-0x01000.bin e diz que um arquivo mesclado é gravado com write-flash 0x0. Ela também observa que --chip é opcional ao gravar, porque o esptool detecta o chip quando se conecta. No Windows, o esptool vem como um executável pronto no ZIP da versão do esptool; no Linux ou no macOS, pip install esptool.
Por uma ponte serial (RFC2217). A solução alternativa do guia IDF Docker: rodar o esp_rfc2217_server no Windows para compartilhar a porta COM pela rede, e apontar o idf.py dentro do contêiner para ela. host.docker.internal é o nome que o Docker dá ao host. Isso mantém o idf.py flash funcionando para qualquer projeto, inclusive a cabeça, que não tem binário mesclado.
Portas USB e drivers no Windows
No Windows, as portas seriais se chamam COM seguido de um número. O guia de conexão serial da Espressif dá a forma mais simples de encontrar a certa: abra o Gerenciador de Dispositivos, desconecte a placa, conecte-a de novo, e a porta que desaparece e volta é a sua. Ele também diz que os drivers USB-serial normalmente vêm com o sistema operacional e se instalam sozinhos.
Para cada placa:
- A barriga é gravada pela sua porta Type-C marcada “USB to UART”, que a Waveshare descreve como a porta de alimentação, programação e depuração. A página de ESP-IDF da Waveshare recomenda instalar os drivers pelo ESP-IDF Installation Manager (EIM).
- A cabeça tem um chip USB-serial CH343P (WCH), listado na página de produto da Waveshare.
Se uma placa não entrar sozinha no modo de download, ou na sua primeira gravação, o guia da Espressif dá a forma manual: segure BOOT, pressione RESET uma vez, solte BOOT.
A alternativa: VS Code
A página Get Started da Espressif recomenda dois caminhos de instalação: o ESP-IDF Installation Manager (EIM) e uma IDE, seja o Espressif-IDE ou o VS Code com a extensão ESP-IDF. A página de ESP-IDF da Waveshare percorre o EIM mais a extensão do VS Code no Windows: instale o ESP-IDF com o EIM (num caminho sem espaços) e depois a extensão, que a partir da versão 2.0 detecta a instalação sozinha. A barra de ferramentas inferior passa então a ter botões para escolher a porta COM, definir o alvo (esp32p4), compilar, gravar e abrir o monitor.
Uma instalação nativa grava diretamente, sem ponte. O custo é uma instalação grande no PC, e você precisa instalar o mesmo branch release/v6.1 que o Xiaozhi pede, e não a versão que o EIM oferecer primeiro.
Como foi pedido à IA
A questão do conjunto de ferramentas veio de uma decisão anterior. Quando a IA perguntou o que a barriga deveria rodar para dar uma voz à Narsil, a pessoa autora respondeu:
yo pensaba hacerlo con Xiaozhi
Tradução para o português: “eu pensava em fazer com o Xiaozhi”.
A IA então leu o README do Xiaozhi, encontrou a sua exigência, ESP-IDF 6.0.1 ou posterior, e a colocou ao lado da 5.3.1 documentada pela Waveshare. Ela registrou a diferença como um risco no documento de tarefas, junto com o plano de compilar na imagem Docker da Espressif e deixar a gravação e as conferências na tela para a pessoa que tem as placas. A regra que aplicou é a deste guia: o firmware que roda decide a versão, e a documentação da placa só define um mínimo.
A segunda decisão que molda o conjunto de ferramentas é onde o código vive. Perguntada sobre a casa do firmware, a pessoa autora escolheu:
repo propio como fork
Tradução para o português: “repositório próprio, como fork”.
Depois, perguntada se ele deveria ser público ou privado desde o início, a pessoa autora respondeu “1”, a primeira opção oferecida: público desde o início. É por isso que as duas placas são compiladas a partir de um único repositório, davshn/narsil-bot, e por isso o conjunto de ferramentas precisa lidar com dois alvos numa única árvore.
Um prompt que você pode usar
O prompt a seguir foi escrito para este guia como sugestão. Não é a conversa usada para configurar o bot.
Eu compilo firmware de ESP32 no Windows com Docker e não quero o ESP-IDF instalado de forma nativa. O meu projeto é um fork de 78/xiaozhi-esp32 para uma placa ESP32-P4, mais um pequeno app ESP-IDF para um ESP32-S3 numa subpasta. Leia o README e o workflow de CI do Xiaozhi e o guia IDF Docker Image da Espressif, e depois me diga: qual tag de
espressif/idfusar e por quê, o comandodocker runexato para compilar cada alvo a partir do PowerShell, e como gravar e monitorar cada placa a partir do Windows, dado que o Docker não consegue repassar portas seriais USB. Cite a documentação para cada versão e comando.
O código mínimo
Compilar a barriga, a partir da raiz do fork no PowerShell (${PWD} é a pasta atual do PowerShell; a flag -u $UID é para Linux e macOS e fica de fora aqui):
docker run --rm -v ${PWD}:/project -w /project -e HOME=/tmp -e IDF_GIT_SAFE_DIR=/project `
espressif/idf:release-v6.1 `
python scripts/build.py waveshare/esp32-p4-wifi6-touch-lcd --name esp32-p4-wifi6-touch-lcd-4.3 --language es-ES
O guia 3 explica a pasta da placa, o --name e o idioma. Compilar a cabeça, a partir da sua pasta:
docker run --rm -v ${PWD}:/project -w /project/head -e HOME=/tmp -e IDF_GIT_SAFE_DIR=/project `
espressif/idf:release-v6.1 `
sh -c "idf.py set-target esp32s3 && idf.py build"
Gravar a barriga a partir do Windows com o esptool, usando um nome de porta inventado:
esptool --port COM5 write-flash 0x0 build/merged-binary.bin
Gravar a cabeça pela ponte serial. Num terminal, compartilhe a porta:
esp_rfc2217_server -v -p 4000 COM6
Em outro, grave a partir do contêiner:
docker run --rm -v ${PWD}:/project -w /project/head -e HOME=/tmp -e IDF_GIT_SAFE_DIR=/project `
espressif/idf:release-v6.1 `
idf.py --port "rfc2217://host.docker.internal:4000?ign_set_control" flash
Para o monitor, o mesmo --port funciona com idf.py monitor; acrescente -it ao docker run para que o contêiner tenha um terminal onde desenhar.
Erros comuns e como testar
- Compilar o Xiaozhi com o ESP-IDF 5.x. O README do Xiaozhi é explícito: a 5.x não é mais suportada. Se você seguiu a página de configuração da Waveshare e instalou a 5.5.2, a barriga não vai compilar; use
release-v6.1. - Misturar pastas de compilação depois de uma troca de versão. O README do Xiaozhi pede
idf.py fullcleandepois de trocar de revisão do ESP-IDF. Uma pastabuildantiga de outra versão dá erros que parecem não ter relação. - Tentar
--deviceno Windows. Funciona só no Linux. No Windows, grave a partir do host ou peloesp_rfc2217_server. - “dubious ownership” (propriedade duvidosa) do git dentro do contêiner. Passe
-e IDF_GIT_SAFE_DIR=/project, como o guia IDF Docker documenta. - Nenhuma porta COM aparece. Desconecte e conecte de novo olhando o Gerenciador de Dispositivos. Se nada mudar, tente outro cabo: um cabo USB só de carga não tem linhas de dados.
- A porta errada na barriga. Grave pela porta Type-C marcada “USB to UART”, não pela USB OTG.
- A placa não responde ao esptool. Segure BOOT, pressione RESET, solte BOOT e grave de novo.
Para testar o conjunto de ferramentas antes do Xiaozhi, compile o exemplo hello_world do ESP-IDF para cada alvo no contêiner, grave-o e procure a sua saída no monitor. Se as duas placas imprimirem, o conjunto de ferramentas, os drivers e os cabos estão todos certos.
Para ir além
docker runcom-ite sem comando abre um shell no contêiner, onde você pode rodaridf.py menuconfige os outros comandos de forma interativa, como o guia IDF Docker mostra.- Fixe a imagem por digest em vez de por tag se quiser que cada compilação do bot use exatamente o mesmo commit do ESP-IDF;
release-v6.1se move conforme o branch se move. - O
scripts/build.py --list-boardsdo Xiaozhi imprime cada placa e variante que ele conhece, o que é uma forma rápida de conferir o nome de uma placa antes de uma compilação longa. - A referência completa de comandos do ESP-IDF fica na documentação da Espressif para cada chip; troque o chip na URL (
esp32p4,esp32s3) para ver as páginas dele.
Este guia ajudou?
Todos os guias são gratuitos. Se este poupou seu tempo, você pode me pagar um café.
Me pague um café