Pular para o conteúdo principal

Laboratório 02

Checklist — ambiente de desenvolvimento (parte 2): PlatformIO, Wokwi e Docker​

  • Extensões PlatformIO IDE e Wokwi Simulator no perfil ESP32IO, com o pio no Path (Parte 1)
  • Projeto PlatformIO na versão mais recente da plataforma (registrada na evidência), compilando, sem a .pio/ no repositório (T1)
  • Licença do Wokwi ativada, wokwi.toml + diagram.json e o pisca-LED simulado no VS Code (T2)
  • Pisca sem delay() (com millis()) e um breakpoint do GDB parando o firmware no Wokwi (T3)
  • Docker funcionando, Dockerfile + compose.yaml e o firmware compilado dentro do container (T4)
  • Firmware simulado pelo wokwi-cli no container, com teste automático do serial (T5)
  • Previsões P1–P3 respondidas no README.md
  • Nenhum token no repositório; nenhum push --force; cada tarefa num commit Tn:
  • Logout do Git e do gh no computador do laboratório
Pontuação

T1…T5 = 100 pts (esta aula não tem desafios): T1 15 · T2 20 · T3 15 · T4 20 · T5 30. O autograder normaliza para 0–10. Vale o commit Tn: mais recente de cada tarefa.

Antes de começar

Confira o ambiente (faça a configuração uma vez por máquina; a verificação, a cada aula):

Verificação rápida das versões instaladas:

git -v & gh --version & code -v & py --version & pio --version & wokwi-cli -V & wsl --version & docker --version

Verificação rápida de autenticação e alias:

git config --get-regexp "^(user|alias)\." & gh auth status & code --list-extensions --profile "ESP32IO"

Adicionar o comando git conferir:

git config --global alias.conferir "!f() { r=$(pwd -W 2>/dev/null || pwd); echo raiz do repositorio: $r; test -z $GIT_PREFIX || echo ATENCAO: o terminal esta em $GIT_PREFIX, fora da raiz. Antes do git add, rode: cd /d $r; test $# -eq 0 && return; for a in $@; do if [ -e $a ]; then echo ok $a; else echo FALTA $a; fi; done; echo == mudancas desde o ultimo commit:; git status --short --ignored -- $@; }; f"

Configuração do ambiente de desenvolvimento​

O Git é a ferramenta de gerenciamento de código-fonte mais utilizada por desenvolvedores profissionais.

  • O Git é um sistema de controle de versão distribuído gratuito e de código aberto, projetado para lidar com tudo, desde projetos pequenos até muito grandes, com rapidez e eficiência.

    winget install --id Git.Git -e --source winget
  • Configurações do git:

    git config --list --show-origin

No Lab 01, o grupo passou a usar o Git e o GitHub. Agora entra o firmware: o PlatformIO compila o código do ESP32, e o Wokwi o roda num ESP32 simulado dentro do VS Code, com LED, monitor serial e depurador (GDB). E entra a última ferramenta do ambiente, o Docker: o mesmo build e a mesma simulação passam a rodar num container Linux, igual em qualquer computador, sem depender do que está instalado no Windows. É exatamente o que o CI do Lab 11 vai fazer a cada push. O MQTT fica para o Lab 04.

Objetivos​

  • Instalar o PlatformIO e o Wokwi no VS Code e fazer o primeiro build do ESP32.
  • Configurar um projeto PlatformIO e registrar a versão da plataforma que o build usou.
  • Ativar o Wokwi no VS Code e ligar o firmware do PlatformIO ao circuito (wokwi.toml, diagram.json).
  • Trocar o delay() por millis(), o padrão que todos os labs seguintes usam, e depurar o firmware simulado com o GDB.
  • Instalar o Docker, escrever um Dockerfile e um compose.yaml, e compilar e simular o firmware num container com o wokwi-cli.

Material​

  • O ambiente do Lab 01: Windows 11, VS Code, Git, gh, Python, e o terminal do VS Code no Prompt de Comando (cmd).
  • ~6 GB livres: o toolchain do ESP32 (~300 MB no Windows e de novo no container) e a imagem do Docker.
  • Uma conta no Wokwi (gratuita): a licença do simulador no VS Code e o token de CI do wokwi-cli.
  • Docker Desktop com WSL 2 (aba Docker da configuração do ambiente).
  • Nenhuma placa. A Parte 6 mostra como gravar uma placa real, para quem tiver.
Abas da configuração do ambiente usadas hoje

PlatformIO, Wokwi (extensão e licença), Docker (WSL 2 e Docker Desktop) e, só para quem tiver placa, Drivers. As demais já foram feitas no Lab 01. O wokwi-cli não precisa ser instalado no Windows: ele roda dentro do container.

Por que simular?

O Wokwi simula o ESP32 (incluindo o Wi-Fi), LEDs, potenciômetros, o DHT22, o display SSD1306 e um analisador lógico. Todo o semestre roda nele: ninguém depende da bancada, do cabo USB ou do driver da placa, e o mesmo circuito (diagram.json) vai para o repositório junto com o código. No Lab 11, o mesmo simulador roda sem interface, dentro do CI, com os mesmos comandos (pio run e wokwi-cli) que você roda hoje no container.

Clonar o repositório do grupo​

1. Crie e entre na pasta-mãe da disciplina:

mkdir "%USERPROFILE%\ELT85BN21" & cd /d "%USERPROFILE%\ELT85BN21"

2. Clone e entre no repositório do laboratório:

git clone https://github.com/ELT85B-N21-2026-2/lab02-grupo-a.git && cd lab02-grupo-a

3. Abra o conteúdo do repositório no perfil ESP32IO do VS Code e compile:

cd /d "%USERPROFILE%\ELT85BN21\lab02-grupo-a" && code . --profile "ESP32IO"

Repositório do Grupo A para Laboratório 02:

  1. Copie o link do repositório acima.
  2. Abra a página de envio da atividade no Moodle (botão abaixo).
  3. Clique em Adicionar envio.
  4. Cole o link no campo Texto online.
  5. Clique em Salvar mudanças.
  6. Confira se o status mudou para Enviado para avaliação.
Abrir envio no Moodle
Avaliação por commits

Cada cartão Ponto de commit é uma tarefa: faça-a, copie o comando do cartão e rode. A mensagem começa com o código (T1:, T2:…) — é como a correção identifica sua entrega. Um commit por tarefa; pode refazer (vale o mais recente); e não esqueça o git push. Detalhes em Como funciona a avaliação.

Mapa de tarefas — 5 tarefas · 100 pts

O repositório nasce do lab02-template, com o README.md e o .gitignore:

Estrutura de Arquivos do Projeto (no fim da aula)
📂 lab02-grupo-x/
  • ├── 📄.gitignore👈 Edite Aqui
  • ├── 📄.dockerignore👈 Criar Aqui
  • ├── 📂.vscode
    • ├── 🔧settings.json👈 Verificar
    • └── 🔧launch.json👈 Criar Aqui
  • ├── 📄Dockerfile👈 Criar Aqui
  • ├── 🚀compose.yaml👈 Criar Aqui
  • ├── 📝README.md👈 Edite Aqui
  • ├── 🔧platformio.ini👈 Criar Aqui
  • ├── 📂src
    • └── 📄main.cpp👈 Criar Aqui
  • ├── 📂include
    • └── 📄README👈 Criar Aqui
  • ├── 📂lib
    • └── 📄README👈 Criar Aqui
  • ├── 📂test
    • └── 📄README👈 Criar Aqui
  • ├── 🔧wokwi.toml👈 Criar Aqui
  • ├── 🔧diagram.json👈 Criar Aqui
  • └── 📂evidencias
    • ├── 📄t1-ambiente.txt👈 Criar Aqui
    • ├── 📄t1-build.txt👈 Criar Aqui
    • ├── 📄t2-serial.txt👈 Criar Aqui
    • ├── 📄t2-wokwi.png👈 Criar Aqui
    • ├── 📄t3-serial.txt👈 Criar Aqui
    • ├── 📄t3-gdb.png👈 Criar Aqui
    • ├── 📄t4-docker.txt👈 Criar Aqui
    • ├── 📄t4-build-docker.txt👈 Criar Aqui
    • ├── 📄t5-wokwi.txt👈 Criar Aqui
    • └── 📄t5-serial.txt👈 Criar Aqui

Parte 1 — PlatformIO: instalação e projeto​

1.1 Instalar as extensões​

Siga as abas PlatformIO e Wokwi da configuração do ambiente. As extensões vão para o perfil ESP32IO do VS Code (--profile "ESP32IO"), o mesmo em que você abriu o repositório no Lab 01:

Terminal (cmd)
code --install-extension platformio.platformio-ide --profile "ESP32IO"
code --install-extension wokwi.wokwi-vscode --profile "ESP32IO"

Abra o repositório do grupo nesse perfil e confira que o terminal é o cmd (o .vscode/settings.json do Lab 01; se o template não o trouxer, crie-o de novo):

Terminal (cmd)
cd lab02-grupo-x
code --profile "ESP32IO" .

Na primeira vez que o VS Code abrir com a extensão do PlatformIO, ela instala o PlatformIO Core (barra de status: Installing PlatformIO Core). Espere terminar e recarregue a janela quando ele pedir. É essa instalação que cria a pasta %USERPROFILE%\.platformio\penv\Scripts\, que a aba PlatformIO manda pôr no Path. Depois de pôr, feche e abra o VS Code e confira:

Terminal do VS Code (cmd)
pio --version
call code --list-extensions --profile "ESP32IO"

Se aparecer 'pio' não é reconhecido como um comando interno, falta o Path; se a pasta não existir, o PlatformIO Core ainda não terminou de instalar.

1.2 Criar o projeto​

No terminal do VS Code, na raiz do repositório:

Terminal do VS Code (cmd)
pio project init -b esp32dev -O "framework=arduino" -O "monitor_speed=115200"
Saída esperada
The following files/directories have been created in C:\...\lab02-grupo-x
include - Put project header files here
lib - Put project specific (private) libraries here
src - Put project source files here
platformio.ini - Project Configuration File
Resolving esp32dev dependencies...
Project has been successfully initialized!

O pio project init cria platformio.ini, src/, include/, lib/ e test/, e não apaga o README.md nem o .vscode/settings.json. (A aba PlatformIO mostra o mesmo comando com --ide vscode --sample-code: o primeiro gera arquivos de configuração do VS Code, o segundo um main.cpp de exemplo. Aqui você escreve o seu.)

1.3 Versão da plataforma​

O pio project init escreve platform = espressif32, sem versão: o PlatformIO usa a versão mais recente da plataforma (e, com ela, do core Arduino e do toolchain). É o padrão desta disciplina, e vale também para as bibliotecas dos labs seguintes. O preço é que o mesmo código pode se comportar diferente quando sai uma versão nova; por isso a versão usada fica registrada na evidência do build (as linhas PLATFORM: e PACKAGES: no início do pio run). Para trazer a versão nova de algo já instalado: pio pkg update.

platformio.ini
[env:esp32dev]
platform = espressif32 ; sem versão: a mais recente
board = esp32dev
framework = arduino
monitor_speed = 115200 ; o mesmo valor do Serial.begin()

1.4 Pisca-LED e primeiro build​

Crie src/main.cpp:

src/main.cpp
#include <Arduino.h>

#define LED_PIN 2 // GPIO2 (o LED do circuito da Parte 2)

// Protótipo: em C/C++ uma função precisa ser declarada antes de ser usada
void piscar(uint8_t pino, uint16_t meioPeriodoMs);

void setup() {
Serial.begin(115200); // o mesmo valor do monitor_speed do platformio.ini
pinMode(LED_PIN, OUTPUT);
Serial.println("ESP32 inicializado! Lab 02, grupo X");
}

void loop() {
piscar(LED_PIN, 500);
}

void piscar(uint8_t pino, uint16_t meioPeriodoMs) {
digitalWrite(pino, HIGH);
delay(meioPeriodoMs);
digitalWrite(pino, LOW);
delay(meioPeriodoMs);
}

O primeiro build baixa a plataforma espressif32, o toolchain Xtensa e o core Arduino (~300 MB). Pode levar de 5 a 15 minutos; os seguintes levam segundos. Rode o primeiro na tela, para acompanhar o download, e o segundo gravando a evidência:

Terminal do VS Code (cmd)
pio run
if not exist evidencias mkdir evidencias
(echo == ambiente %DATE% %TIME% & pio --version & call code --list-extensions --profile "ESP32IO") > evidencias\t1-ambiente.txt 2>&1
pio run > evidencias\t1-build.txt 2>&1
type evidencias\t1-build.txt
evidencias/t1-build.txt (final; os números variam)
RAM: [= ] 6.5% (used 21360 bytes from 327680 bytes)
Flash: [== ] 20.4% (used 267525 bytes from 1310720 bytes)
Building .pio/build/esp32dev/firmware.bin
========================= [SUCCESS] Took 41.27 seconds =========================
Os botões do PlatformIO

A barra de status do VS Code tem os mesmos comandos: ✓ Build (pio run), → Upload (pio run -t upload), 🔌 Serial Monitor (pio device monitor) e 🗑 Clean. O terminal é melhor para gerar evidências, porque o > arquivo 2>&1 grava a saída direto num arquivo. O segundo pio run não recompila nada, mas imprime de novo o uso de RAM e Flash.

1.5 O que vai para o repositório​

O git status mostra a pasta .pio/? Não deveria: o .gitignore do template a ignora. Ela guarda o build inteiro (dezenas de MB, confira com dir /s .pio), muda a cada compilação e é refeita por qualquer um com pio run. Nem o firmware.bin vai: ele é gerado a partir do código, e no Lab 11 vai para outro lugar, uma release. Faça o commit só do que é código e configuração:

Terminal do VS Code (cmd)
git status
git add .vscode/settings.json platformio.ini src include lib test evidencias/t1-ambiente.txt evidencias/t1-build.txt
git commit -m "T1: projeto PlatformIO"
git push
📂 lab02-grupo-x/
  • ├── 📂.vscode
    • └── 🔧settings.json👈 Criar Aqui
  • ├── 🔧platformio.ini👈 Criar Aqui
  • ├── 📂src
    • └── 📄main.cpp👈 Criar Aqui
  • └── 📂evidencias
    • ├── 📄t1-ambiente.txt👈 Criar Aqui
    • └── 📄t1-build.txt👈 Criar Aqui
git conferir .vscode/settings.json platformio.ini src/main.cpp evidencias/t1-ambiente.txt evidencias/t1-build.txt
Ponto de commit · T1 (15 pts) #

Projeto PlatformIO

1. Conferir os arquivos
git conferir .vscode/settings.json platformio.ini src/main.cpp evidencias/t1-ambiente.txt evidencias/t1-build.txt
2. Commit T1 e push
git add .vscode/settings.json platformio.ini src/main.cpp evidencias/t1-ambiente.txt evidencias/t1-build.txt && git commit -m "T1: Projeto PlatformIO" && git push
3. Conferir o commit e o envio
git status -sb && git log -1 --stat --oneline

Só faça o commit se o passo 1 não mostrar ATENCAO (terminal fora da raiz do repositório) nem FALTA. Nas mudanças, ?? é arquivo novo e M, modificado: os dois entram no commit. !! é arquivo bloqueado pelo .gitignore, e o git add vai falhar. Um arquivo que não aparece ali já está no Git e não mudou desde o último commit. No passo 3, a primeira linha não pode ter [ahead (commit ainda não enviado), e a lista tem de trazer os arquivos da T1.


Parte 2 — Wokwi no VS Code​

2.1 Ativar a licença​

Na aba Wokwi da configuração do ambiente, use o link Gerar uma licença pessoal de 30 dias (ou, no VS Code, F1 → Wokwi: Request a New License). O navegador abre o site do Wokwi: entre com a sua conta e confirme, e o navegador devolve a licença ao VS Code. Quando ela vencer, o VS Code avisa, e você repete o passo.

2.2 Ligar o firmware ao simulador​

O Wokwi precisa de dois arquivos na raiz do projeto:

  • wokwi.toml: qual firmware rodar (o que o PlatformIO acabou de compilar);
  • diagram.json: o circuito (placa, componentes, fios).
wokwi.toml
[wokwi]
version = 1
firmware = '.pio/build/esp32dev/firmware.bin'
elf = '.pio/build/esp32dev/firmware.elf'

Use / nos caminhos, mesmo no Windows: o arquivo vai para o repositório e precisa funcionar nos computadores de todos e no container Linux da Parte 4.

diagram.json
{
"version": 1,
"author": "ELT85B - Lab 02",
"editor": "wokwi",
"parts": [
{
"type": "board-esp32-devkit-c-v4",
"id": "esp",
"top": 0,
"left": 0,
"attrs": {}
},
{
"type": "wokwi-resistor",
"id": "r1",
"top": 130,
"left": 120,
"attrs": { "value": "220" }
},
{
"type": "wokwi-led",
"id": "led1",
"top": 80,
"left": 220,
"attrs": { "color": "red", "label": "GPIO2" }
}
],
"connections": [
["esp:TX", "$serialMonitor:RX", "", []],
["esp:RX", "$serialMonitor:TX", "", []],
["esp:2", "r1:1", "green", []],
["r1:2", "led1:A", "green", []],
["led1:C", "esp:GND.2", "black", []]
],
"dependencies": {}
}
LinhaO que liga
esp:TX → $serialMonitor:RX (e o inverso)a UART0 do ESP32 ao monitor serial do Wokwi (o Serial.println)
esp:2 → resistor → led1:Ao GPIO2 ao anodo do LED, passando por 220 Ω (limita a corrente em ~6 mA)
led1:C → esp:GND.2o catodo do LED ao terra

Abra o diagram.json no VS Code: o editor do Wokwi mostra o circuito ao lado, e você pode arrastar as peças. Os labs seguintes acrescentam componentes a este mesmo arquivo.

2.3 Simular​

  1. Compile (pio run): o Wokwi roda o último firmware.bin compilado.
  2. F1 → Wokwi: Start Simulator (ou clique no diagram.json e em ▶).
  3. O LED pisca, e o monitor serial (abaixo do circuito) mostra ESP32 inicializado!.

Salve o monitor serial em evidencias/t2-serial.txt (selecione o texto e copie) e uma captura do VS Code com o circuito e o serial em evidencias/t2-wokwi.png.

Preveja antes de rodar

P1: (a) você mudou o LED_PIN para 4 e iniciou o simulador sem compilar de novo. O que o Wokwi mostra: o código novo ou o antigo? Por quê? (b) No canto do simulador aparece a porcentagem de tempo real (ex.: 98%). Se ela cair para 50 %, o LED pisca mais devagar na tela? E o millis() do ESP32: conta o tempo simulado ou o do relógio da parede?

📂 lab02-grupo-x/
  • ├── 🔧wokwi.toml👈 Criar Aqui
  • ├── 🔧diagram.json👈 Criar Aqui
  • └── 📂evidencias
    • ├── 📄t2-serial.txt👈 Criar Aqui
    • └── 📄t2-wokwi.png👈 Criar Aqui
git conferir wokwi.toml diagram.json evidencias/t2-serial.txt evidencias/t2-wokwi.png
Ponto de commit · T2 (20 pts) #

Wokwi no VS Code

1. Conferir os arquivos
git conferir wokwi.toml diagram.json evidencias/t2-serial.txt evidencias/t2-wokwi.png
2. Commit T2 e push
git add wokwi.toml diagram.json evidencias/t2-serial.txt evidencias/t2-wokwi.png && git commit -m "T2: Wokwi no VS Code" && git push
3. Conferir o commit e o envio
git status -sb && git log -1 --stat --oneline

Só faça o commit se o passo 1 não mostrar ATENCAO (terminal fora da raiz do repositório) nem FALTA. Nas mudanças, ?? é arquivo novo e M, modificado: os dois entram no commit. !! é arquivo bloqueado pelo .gitignore, e o git add vai falhar. Um arquivo que não aparece ali já está no Git e não mudou desde o último commit. No passo 3, a primeira linha não pode ter [ahead (commit ainda não enviado), e a lista tem de trazer os arquivos da T2.


Parte 3 — Pisca com millis() e depuração com GDB​

3.1 Sem delay()​

Com delay(500), o ESP32 fica parado meio segundo e não faz mais nada: não lê a serial, não atende o Wi-Fi, não confere um botão. Os labs seguintes fazem várias coisas "ao mesmo tempo", então o padrão é outro: o loop() gira o tempo todo e cada tarefa confere se já deu a hora.

src/main.cpp (T3)
#include <Arduino.h>

#define LED_PIN 2
#define MEIO_PERIODO 500 // ms aceso, ms apagado
#define RELATORIO_MS 2000 // a cada 2 s, uma linha no serial

unsigned long tLed = 0, tRelatorio = 0;
bool ledAceso = false;
uint32_t voltas = 0; // quantas vezes o loop() rodou

void setup() {
Serial.begin(115200);
pinMode(LED_PIN, OUTPUT);
Serial.println("ESP32 inicializado! Lab 02, grupo X");
}

void loop() {
unsigned long agora = millis();
voltas++;

if (agora - tLed >= MEIO_PERIODO) { // já deu a hora de trocar o LED?
tLed += MEIO_PERIODO;
ledAceso = !ledAceso;
digitalWrite(LED_PIN, ledAceso ? HIGH : LOW);
}

if (agora - tRelatorio >= RELATORIO_MS) { // e a do relatório?
tRelatorio += RELATORIO_MS;
Serial.printf("[%7lu ms] LED %s · %lu voltas do loop() em 2 s\r\n",
agora, ledAceso ? "aceso " : "apagado", (unsigned long)voltas);
voltas = 0;
}
}
Monitor serial (trecho; o número de voltas varia)
ESP32 inicializado! Lab 02, grupo X
[ 2000 ms] LED aceso · 1032915 voltas do loop() em 2 s
[ 4000 ms] LED aceso · 1035522 voltas do loop() em 2 s
[ 6000 ms] LED aceso · 1035519 voltas do loop() em 2 s

O loop() roda centenas de milhares de vezes por segundo, e o LED continua piscando no ritmo certo. Com o pisca de delay da T1, seriam 2 voltas a cada 2 s.

Preveja antes de rodar

P2: (a) o millis() é um unsigned long de 32 bits e volta a zero depois de ~49,7 dias. Por que agora - tLed >= MEIO_PERIODO continua certo na virada, mas agora >= tLed + MEIO_PERIODO não? Teste a conta com números de 32 bits: tLed = 4294967000, agora = 200. (b) Por que tLed += MEIO_PERIODO e não tLed = agora? O que acontece com o ritmo do LED em cada caso, se uma volta do loop() atrasar 3 ms?

Evidência: pelo menos 5 linhas do monitor serial em evidencias/t3-serial.txt.

3.2 Depurar com GDB no Wokwi​

O Serial.printf mostra o que você mandou imprimir. O GDB para o firmware numa linha (breakpoint) e mostra todas as variáveis naquele instante, sem mudar o código. O Wokwi abre um servidor GDB na porta 3333, e o VS Code se conecta a ele.

  1. Extensão C/C++ (fornece o depurador cppdbg do VS Code):

    Terminal (cmd)
    code --install-extension ms-vscode.cpptools --profile "ESP32IO"
  2. wokwi.toml: acrescente a porta do servidor GDB.

    wokwi.toml
    [wokwi]
    version = 1
    firmware = '.pio/build/esp32dev/firmware.bin'
    elf = '.pio/build/esp32dev/firmware.elf'
    gdbServerPort = 3333
  3. .vscode/launch.json: diz ao VS Code qual GDB usar (o do toolchain do ESP32, baixado pelo PlatformIO), qual .elf tem os símbolos e onde está o servidor.

    .vscode/launch.json
    {
    "version": "0.2.0",
    "configurations": [
    {
    "name": "Wokwi GDB",
    "type": "cppdbg",
    "request": "launch",
    "program": "${workspaceFolder}/.pio/build/esp32dev/firmware.elf",
    "cwd": "${workspaceFolder}",
    "MIMode": "gdb",
    "miDebuggerPath": "${userHome}/.platformio/packages/toolchain-xtensa-esp32/bin/xtensa-esp32-elf-gdb.exe",
    "miDebuggerServerAddress": "localhost:3333"
    }
    ]
    }

    Confira que o GDB existe nesse caminho:

    Terminal do VS Code (cmd)
    dir "%USERPROFILE%\.platformio\packages\toolchain-xtensa-esp32\bin\*gdb*"
  4. Depurar. Compile (pio run), depois F1 → Wokwi: Start Simulator and Wait for Debugger: o simulador abre parado, esperando o GDB. Clique na margem à esquerda da linha ledAceso = !ledAceso; (aparece um ponto vermelho) e aperte F5 (configuração Wokwi GDB).

  5. O firmware para no breakpoint. No painel Run and Debug, a seção Variables mostra agora, e Watch aceita expressões (tLed, voltas, ledAceso). F5 continua até a próxima parada, F10 executa uma linha, F11 entra na função, Shift+F5 encerra.

Salve uma captura do VS Code parado no breakpoint, com as variáveis à vista, em evidencias/t3-gdb.png.

Variáveis optimized out

O build padrão do PlatformIO é otimizado (-Os): o compilador guarda variáveis em registradores ou as elimina, e o GDB mostra <optimized out>. Para depurar, acrescente build_type = debug ao [env:esp32dev] do platformio.ini e compile de novo; retire-o depois. Enquanto o firmware está parado no GDB, o tempo simulado também para: o millis() não avança, e o LED não troca (compare com o P1-b).

📂 lab02-grupo-x/
  • ├── 📂src
    • └── 📄main.cpp👈 Edite Aqui
  • ├── 🔧wokwi.toml👈 Edite Aqui
  • ├── 📂.vscode
    • └── 🔧launch.json👈 Criar Aqui
  • └── 📂evidencias
    • ├── 📄t3-serial.txt👈 Criar Aqui
    • └── 📄t3-gdb.png👈 Criar Aqui
git conferir src/main.cpp wokwi.toml .vscode/launch.json evidencias/t3-serial.txt evidencias/t3-gdb.png
Ponto de commit · T3 (15 pts) #

Pisca com millis e GDB

1. Conferir os arquivos
git conferir src/main.cpp wokwi.toml .vscode/launch.json evidencias/t3-serial.txt evidencias/t3-gdb.png
2. Commit T3 e push
git add src/main.cpp wokwi.toml .vscode/launch.json evidencias/t3-serial.txt evidencias/t3-gdb.png && git commit -m "T3: Pisca com millis e GDB" && git push
3. Conferir o commit e o envio
git status -sb && git log -1 --stat --oneline

Só faça o commit se o passo 1 não mostrar ATENCAO (terminal fora da raiz do repositório) nem FALTA. Nas mudanças, ?? é arquivo novo e M, modificado: os dois entram no commit. !! é arquivo bloqueado pelo .gitignore, e o git add vai falhar. Um arquivo que não aparece ali já está no Git e não mudou desde o último commit. No passo 3, a primeira linha não pode ter [ahead (commit ainda não enviado), e a lista tem de trazer os arquivos da T3.


Parte 4 — Docker: o ambiente num container​

Até aqui, o build depende do seu Windows: da versão do PlatformIO, do Path, do perfil do VS Code. Um container é um Linux mínimo, descrito num arquivo de texto (Dockerfile), que roda igual em qualquer computador com Docker. Se o firmware compila no container, compila no computador do colega, no do professor e no CI.

PeçaO que é
Dockerfilea receita da imagem: sistema base + o que instalar (PlatformIO, wokwi-cli)
imagemo resultado do docker compose build: um "molde" pronto, guardado no Docker
containeruma execução da imagem; com --rm, é apagado quando o comando termina
compose.yamlcomo rodar: qual imagem, quais pastas montar, quais variáveis, qual comando de cada serviço
bind mounta pasta do repositório aparece dentro do container em /projeto: o que ele grava, você vê
volume nomeadouma pasta guardada pelo Docker entre execuções: aqui, o cache do PlatformIO (~300 MB)

4.1 Instalar e conferir o Docker​

Siga a aba Docker da configuração do ambiente: primeiro o WSL 2 (o wsl --install pede para reiniciar o computador), depois o Docker Desktop. Abra o Docker Desktop, aceite os termos e espere a baleia ficar parada na bandeja. Se ele reclamar de virtualização, ative-a na BIOS/UEFI (Intel VT-x ou AMD-V).

Confira no terminal do VS Code e grave a evidência:

Terminal do VS Code (cmd)
(wsl --version & docker --version & docker compose version & docker run --rm hello-world) > evidencias\t4-docker.txt 2>&1
type evidencias\t4-docker.txt

O hello-world baixa uma imagem minúscula, cria um container, imprime Hello from Docker! e o container é apagado (--rm). O wsl --version escreve em UTF-16, e por isso pode aparecer com espaços entre as letras no arquivo: tudo bem.

4.2 O Dockerfile​

Na raiz do repositório, crie o Dockerfile (sem extensão):

Dockerfile
# ELT85B - ambiente de build e simulação do ESP32 (os mesmos comandos do CI do Lab 11)
FROM python:3-slim

# curl: baixar o wokwi-cli · git: bibliotecas do PlatformIO vindas de repositórios
RUN apt-get update \
&& apt-get install -y --no-install-recommends curl ca-certificates git \
&& rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir platformio

# wokwi-cli: um único executável Linux, publicado no GitHub do Wokwi
RUN curl -fsSL -o /usr/local/bin/wokwi-cli \
https://github.com/wokwi/wokwi-cli/releases/latest/download/wokwi-cli-linuxstatic-x64 \
&& chmod +x /usr/local/bin/wokwi-cli \
&& wokwi-cli --version

WORKDIR /projeto
CMD ["pio", "--version"]

Cada RUN vira uma camada da imagem. O Docker guarda as camadas em cache: se você mudar só a última linha, ele não instala o PlatformIO de novo. Por isso o que muda menos fica em cima. Sem versão no Dockerfile, o build pega o Python, o PlatformIO e o wokwi-cli mais recentes; para atualizar uma imagem já construída, use docker compose build --no-cache.

O contexto do build é a pasta inteira, enviada ao Docker antes de começar. O .dockerignore tira dele o que a imagem não usa (e o .env da T5, que nunca deve entrar numa imagem):

.dockerignore
.git
.pio
.vscode
evidencias
.env

4.3 O compose.yaml​

O docker compose guarda num arquivo os parâmetros que, com o docker run, você teria de digitar a cada vez. Os três serviços usam a mesma imagem; muda só o comando:

compose.yaml
# Configuração comum aos serviços (âncora YAML: &esp32 define, <<: *esp32 reutiliza)
x-esp32: &esp32
build: .
image: elt85b/esp32-dev:lab02
working_dir: /projeto
volumes:
- .:/projeto # o repositório, dentro do container
- platformio:/root/.platformio # cache do toolchain entre execuções
environment:
WOKWI_CLI_TOKEN: ${WOKWI_CLI_TOKEN:-} # vem do arquivo .env (T5), nunca do Git

services:
pio: # compilar
<<: *esp32
command: pio run

wokwi: # simular e testar o serial
<<: *esp32
command: >
wokwi-cli --timeout 10000 --expect-text "voltas do loop"
--serial-log-file evidencias/t5-serial.txt .

ci: # compilar e simular, como o CI do Lab 11
<<: *esp32
command: sh -c "pio run && wokwi-cli --timeout 10000 --expect-text 'voltas do loop' ."

volumes:
platformio:

4.4 Construir a imagem e compilar no container​

Terminal do VS Code (cmd)
docker compose build
docker compose run --rm pio
docker compose run --rm -T pio > evidencias\t4-build-docker.txt 2>&1
type evidencias\t4-build-docker.txt
  1. docker compose build monta a imagem a partir do Dockerfile (alguns minutos, na primeira vez).
  2. O primeiro docker compose run --rm pio baixa a plataforma espressif32 e o toolchain para Linux (~300 MB, de novo: o do Windows não serve no container) e guarda tudo no volume platformio.
  3. O segundo grava a evidência. O -T desliga o terminal interativo, que atrapalha quando a saída vai para um arquivo.

O firmware.bin aparece na sua pasta .pio/build/esp32dev/, porque o container escreve no bind mount. O build do Windows e o do container usam a mesma .pio/, mas caminhos diferentes (C:\... × /projeto): na primeira vez que você alternar entre os dois, cada lado recompila tudo. Um build dentro do container, numa pasta do Windows, também é mais lento que o do VS Code: é o preço do WSL 2 cruzar os dois sistemas de arquivos.

Terminal do VS Code (cmd)
git add Dockerfile .dockerignore compose.yaml evidencias/t4-docker.txt evidencias/t4-build-docker.txt
git commit -m "T4: build do firmware no Docker"
git push
📂 lab02-grupo-x/
  • ├── 📄Dockerfile👈 Criar Aqui
  • ├── 📄.dockerignore👈 Criar Aqui
  • ├── 🚀compose.yaml👈 Criar Aqui
  • └── 📂evidencias
    • ├── 📄t4-docker.txt👈 Criar Aqui
    • └── 📄t4-build-docker.txt👈 Criar Aqui
git conferir Dockerfile .dockerignore compose.yaml evidencias/t4-docker.txt evidencias/t4-build-docker.txt
Ponto de commit · T4 (20 pts) #

Docker: build no container

1. Conferir os arquivos
git conferir Dockerfile .dockerignore compose.yaml evidencias/t4-docker.txt evidencias/t4-build-docker.txt
2. Commit T4 e push
git add Dockerfile .dockerignore compose.yaml evidencias/t4-docker.txt evidencias/t4-build-docker.txt && git commit -m "T4: Docker: build no container" && git push
3. Conferir o commit e o envio
git status -sb && git log -1 --stat --oneline

Só faça o commit se o passo 1 não mostrar ATENCAO (terminal fora da raiz do repositório) nem FALTA. Nas mudanças, ?? é arquivo novo e M, modificado: os dois entram no commit. !! é arquivo bloqueado pelo .gitignore, e o git add vai falhar. Um arquivo que não aparece ali já está no Git e não mudou desde o último commit. No passo 3, a primeira linha não pode ter [ahead (commit ainda não enviado), e a lista tem de trazer os arquivos da T4.


Projeto integrador — simular no container com o wokwi-cli​

O Wokwi do VS Code precisa de alguém olhando a tela. O wokwi-cli roda a mesma simulação sem interface: envia o firmware.bin e o diagram.json para o simulador do Wokwi (na nuvem), recebe o monitor serial e termina com um código de saída: 0 se o texto esperado apareceu no serial a tempo, diferente de 0 se não. É um teste automático do firmware, e é o que o CI do Lab 11 roda a cada push.

Requisitos​

  1. Token de CI. Em wokwi.com/dashboard/ci, entre com a sua conta e gere um token. Ele é pessoal: quem tem o token usa a sua cota de simulação.

  2. .env, fora do Git. Primeiro, garanta que o Git ignora o .env; depois, crie-o pelo VS Code (Explorer → novo arquivo .env):

    Terminal do VS Code (cmd)
    echo .env>> .gitignore
    git check-ignore -v .env
    .env (NÃO vai para o repositório)
    WOKWI_CLI_TOKEN=cole_aqui_o_seu_token

    O git check-ignore tem de responder .gitignore:N:.env .env. O docker compose lê o .env sozinho e passa o token ao container pelo ${WOKWI_CLI_TOKEN:-} do compose.yaml. Confira com git status: o .env não pode aparecer.

  3. Simular. Com o firmware da T3 já compilado (T4):

    Terminal do VS Code (cmd)
    docker compose run --rm wokwi
    echo %ERRORLEVEL%
    Saída (trecho; as mensagens do wokwi-cli variam com a versão)
    Wokwi CLI v0.x.x
    Starting simulation...
    ESP32 inicializado! Lab 02, grupo X
    [ 2000 ms] LED aceso · 1032915 voltas do loop() em 2 s
    Expected text found: "voltas do loop"
    TEST PASSED.
    0

    O --expect-text encerra a simulação assim que o texto aparece; o --timeout 10000 é o limite, em milissegundos simulados; o --serial-log-file grava o serial em evidencias/t5-serial.txt.

  4. Ver o teste falhar. Rode com um texto que o firmware nunca imprime (o comando depois do nome do serviço substitui o do compose.yaml):

    Terminal do VS Code (cmd)
    docker compose run --rm wokwi wokwi-cli --timeout 5000 --expect-text "texto que nunca aparece" .
    echo %ERRORLEVEL%

    O código de saída não é 0. É isso que faz o CI marcar o push em vermelho.

  5. Tudo de uma vez. O serviço ci compila e simula na sequência, como o Lab 11 fará:

    Terminal do VS Code (cmd)
    docker compose run --rm -T ci > evidencias\t5-wokwi.txt 2>&1
    echo exit=%ERRORLEVEL%>> evidencias\t5-wokwi.txt
    type evidencias\t5-wokwi.txt

    O echo fica numa linha separada de propósito: dentro de parênteses, o cmd trocaria o %ERRORLEVEL% pelo valor de antes do comando.

  6. Evidências: evidencias/t5-wokwi.txt (saída do serviço ci, terminando em exit=0) e evidencias/t5-serial.txt (gravado pelo serviço wokwi no passo 3).

  7. No README.md: as respostas de P1, P2 e P3.

Terminal do VS Code (cmd)
git status
git add .gitignore evidencias/t5-wokwi.txt evidencias/t5-serial.txt README.md
git commit -m "T5: firmware simulado no Docker com o wokwi-cli"
git push
O token não vai para o Git

Nem no compose.yaml, nem no README.md, nem numa evidência. Se ele for parar num commit, apagar o arquivo depois não resolve: o token continua no histórico. Revogue-o em wokwi.com/dashboard/ci e gere outro. No Lab 11, ele vai para os secrets do GitHub.

Preveja antes de rodar

P3: (a) o primeiro docker compose run --rm pio levou minutos, e o segundo, segundos. Se o container é apagado a cada execução (--rm), onde ficou guardado o toolchain? O que aconteceria depois de um docker compose down -v? (b) O firmware.bin compilado no container pode ser simulado pelo Wokwi do VS Code, no Windows? Por quê (pense no bind mount e no que o firmware.bin contém)? (c) Por que um teste com --expect-text e código de saída serve para o CI, e um print do monitor serial não serve?

📂 lab02-grupo-x/
  • ├── 📄.gitignore👈 Edite Aqui
  • ├── 📂evidencias
    • ├── 📄t5-wokwi.txt👈 Criar Aqui
    • └── 📄t5-serial.txt👈 Criar Aqui
  • └── 📝README.md👈 Edite Aqui
git conferir .gitignore evidencias/t5-wokwi.txt evidencias/t5-serial.txt README.md
Ponto de commit · T5 (30 pts) #

Simulação no container com o wokwi-cli

1. Conferir os arquivos
git conferir .gitignore evidencias/t5-wokwi.txt evidencias/t5-serial.txt README.md
2. Commit T5 e push
git add .gitignore evidencias/t5-wokwi.txt evidencias/t5-serial.txt README.md && git commit -m "T5: Simulação no container com o wokwi-cli" && git push
3. Conferir o commit e o envio
git status -sb && git log -1 --stat --oneline

Só faça o commit se o passo 1 não mostrar ATENCAO (terminal fora da raiz do repositório) nem FALTA. Nas mudanças, ?? é arquivo novo e M, modificado: os dois entram no commit. !! é arquivo bloqueado pelo .gitignore, e o git add vai falhar. Um arquivo que não aparece ali já está no Git e não mudou desde o último commit. No passo 3, a primeira linha não pode ter [ahead (commit ainda não enviado), e a lista tem de trazer os arquivos da T5.


Parte 6 — Placa real (opcional)​

Quem tiver um ESP32 DevKit pode gravar o mesmo firmware: o código não muda.

Antes, siga a aba Drivers da configuração do ambiente: a placa tem de aparecer como uma porta COM no Gerenciador de Dispositivos, e o esptool chip-id tem de responder. Depois, no terminal do VS Code (a gravação é feita pelo Windows, não pelo container, que não enxerga as portas COM):

Terminal do VS Code (cmd)
pio device list
pio run -t upload
pio device monitor

O pio device list mostra as portas (COM3, COM4...). O upload compila e grava, e o monitor abre o serial a 115200 (Ctrl+C sai). Feche o monitor antes de gravar de novo: a porta COM só atende um programa por vez.

ProblemaO que tentar
A porta não apareceoutro cabo (muitos só carregam), outra USB, driver CP210x ou CH340
Failed to connect to ESP32segure BOOT quando aparecer Connecting....
Caracteres estranhos no serialmonitor_speed diferente do Serial.begin()
could not open port 'COM4': PermissionErroroutro programa está com a porta (um monitor serial aberto, outro terminal): feche-o

Referência rápida​

Para…Comando
Compilarpio run
Limpar o buildpio run -t clean
SimularF1 → Wokwi: Start Simulator (compile antes)
DepurarF1 → Wokwi: Start Simulator and Wait for Debugger → F5 (Wokwi GDB)
Construir a imagemdocker compose build
Compilar no containerdocker compose run --rm pio
Simular no containerdocker compose run --rm wokwi
Compilar e simular (CI)docker compose run --rm ci
Outro comando na mesma imagemdocker compose run --rm pio <comando> (ex.: pio run -t clean)
Gravar a saída num arquivodocker compose run --rm -T <serviço> > arquivo.txt 2>&1
Código de saída do último comandoecho %ERRORLEVEL%
Ver imagens / volumesdocker images · docker volume ls
Apagar o cache do PlatformIOdocker compose down -v
Fluxo de entregaramo → commit Tn: → push → PR → revisão → merge (Lab 01)
Atalho do depuradorAção
F9liga/desliga o breakpoint na linha
F5inicia / continua
F10 · F11próxima linha · entra na função
Shift+F5encerra a depuração
ProblemaO que fazer
'pio' não é reconhecido como um comando internoponha %USERPROFILE%\.platformio\penv\Scripts\ no Path (aba PlatformIO) e abra um terminal novo. Se a pasta não existir, o PlatformIO Core ainda não terminou de instalar
code abre o VS Code sem as extensõesabra no perfil: code --profile "ESP32IO" .
O primeiro pio run demora muitoé o download do toolchain (~300 MB): deixe terminar. Os builds seguintes levam segundos
O Wokwi pede licençalink da aba Wokwi, ou F1 → Wokwi: Request a New License (vence a cada 30 dias)
firmware.bin not found no Wokwicompile antes (pio run) e confira os caminhos do wokwi.toml
O Wokwi roda o código antigoele roda o último build: compile de novo
Configured debug type 'cppdbg' is not supportedfalta a extensão C/C++ (ms-vscode.cpptools) no perfil ESP32IO
GDB: Unable to start debugging / localhost:3333inicie antes o Wokwi: Start Simulator and Wait for Debugger, e confira o gdbServerPort = 3333 no wokwi.toml
GDB: miDebuggerPath inválidoo caminho do launch.json tem de bater com o dir ...\toolchain-xtensa-esp32\bin\*gdb* (3.2)
Breakpoint cinza ou variável <optimized out>build_type = debug no platformio.ini e compile de novo
docker: error during connecto Docker Desktop está fechado ou iniciando: abra-o e espere
'docker' não é reconhecido como um comando internoo Docker Desktop terminou de instalar depois que o VS Code abriu: feche e abra o VS Code
docker compose build falha no curl do wokwi-clisem acesso ao GitHub (proxy ou rede): tente de novo em outra rede
no configuration file provided: not foundrode o docker compose na raiz do repositório, onde está o compose.yaml
wokwi-cli: token ausente ou inválidofalta o .env na raiz, com WOKWI_CLI_TOKEN=... sem espaços nem aspas; ou o token foi revogado
wokwi-cli: firmware.bin não encontradocompile antes: docker compose run --rm pio (ou use o serviço ci)
wokwi-cli termina por timeouto texto do --expect-text não apareceu no serial: confira o firmware gravado (é o da T3?) e as maiúsculas
Build no container muito lentoé a pasta do Windows vista pelo WSL 2; o segundo build, com o cache, é bem mais rápido
O terminal abre como PowerShellfalta o .vscode/settings.json (Lab 01, 1.1): crie-o e abra um terminal novo

Logout do seu ambiente dev, git e gh​

Para o git "esquecer" suas informações salvas:

git credential-manager erase && cmdkey /list | findstr "github" && gh auth logout
Ao terminar — máquina de laboratório

Antes de sair, faça logout para não deixar sua conta do GitHub ativa nesta máquina. Rode os comandos abaixo no Prompt de Comando (cmd), não no PowerShell.

1. Apague a credencial do GitHub salva pelo git, encerre a sessão do gh e remova seu nome e e-mail da configuração global:

(echo protocol=https&echo host=github.com) | git credential reject
gh auth logout --hostname github.com
git config --global --unset user.name
git config --global --unset user.email

Para conferir, este comando não deve mostrar nada:

cmdkey /list | findstr /i github

2. Pare os containers do lab:

for /f "delims=" %i in ('docker compose ls -q') do docker compose -p %i down

3. No navegador, saia da sua conta em github.com e feche todas as janelas.