Primeiros passos com MicroPython na ESP32

Toda placa de microcontrolador começa do mesmo jeito: um LED piscando. Parece pouco, mas por trás dessas duas linhas de código estão quase todas as ideias que você vai usar daqui para a frente — o que é um pino, o que significa "saída", como o programa espera o tempo passar e como o texto que você escreve vira corrente elétrica num fio. Este artigo é o mapa do começo da caminhada com MicroPython na ESP32 DevKit V1, a placa que o PyPlaca simula. Vamos entender o que roda dentro da placa, escrever os primeiros programas, montar um LED de verdade na protoboard e, no fim, ver como levar o mesmo main.py para uma ESP32 de verdade.

Todos os números deste texto vêm da documentação do projeto (os documentos de hardware e as fichas de cada peça) ou da documentação oficial do MicroPython. Quando um valor ainda não foi medido numa placa do laboratório, o PyPlaca avisa — e este artigo também.

O que é o MicroPython

Python é uma linguagem de programação conhecida por ser fácil de ler. Normalmente ela roda num computador com gigabytes de memória e um sistema operacional por baixo. O MicroPython é uma reimplementação do Python 3 feita para caber em microcontroladores: chips pequenos, com poucas centenas de kilobytes de memória, sem sistema operacional e feitos para conversar com o mundo físico — botões, LEDs, sensores, motores.

A diferença mais importante para quem está começando é onde o programa roda. Em Arduino, por exemplo, você escreve C++ no computador, um compilador transforma tudo em código de máquina e esse código é gravado na placa. No MicroPython, o que é gravado na placa uma única vez é o interpretador: o próprio MicroPython, num arquivo de firmware. Depois disso, a placa passa a entender Python. Você manda arquivos de texto (main.py, boot.py e os seus módulos) e o interpretador lê e executa linha por linha, ali mesmo, dentro do chip.

Isso traz duas vantagens enormes para o aprendizado. A primeira é o REPL, o "prompt" >>> que aparece no terminal serial: você digita uma linha de Python e a placa responde na hora. Dá para acender um LED digitando Pin(2, Pin.OUT).on() sem salvar nem gravar nada. A segunda é que os erros aparecem em texto, com o número da linha e o tipo do problema, em vez de a placa simplesmente "não fazer nada".

O PyPlaca usa como referência o MicroPython v1.29.0, na versão oficial para a ESP32 comum (o firmware ESP32_GENERIC). O simulador reproduz a API, as mensagens de erro e até os detalhes curiosos dessa versão: a ideia é que o seu main.py funcione igual quando for para a placa de verdade.

A placa: ESP32 DevKit V1

A DevKit V1 de 30 pinos é uma das placas de ESP32 mais comuns em laboratórios de escola. No meio dela fica o módulo ESP32-WROOM-32, uma caixinha de metal com o chip ESP32 (dois núcleos, Wi-Fi e Bluetooth), a memória flash e a antena desenhada na própria placa de circuito. Em volta do módulo, a DevKit coloca o que falta para usar o chip com facilidade: o conector USB, o conversor USB-serial, o regulador de tensão, dois botões e dois LEDs.

Alguns fatos sobre a placa que vão aparecer o tempo todo:

• os pinos trabalham com 3,3 V. Um pino em nível alto fica com 3,3 V; em nível baixo, com 0 V;
• a tensão máxima que um pino aguenta é 3,6 V. Acima disso o chip pode ser danificado — e é por isso que sensores de 5 V pedem cuidado (há um artigo inteiro sobre isso nesta série);
• são 30 pinos, 15 de cada lado. Nem todos são GPIOs: há o 3V3, o VIN (os 5 V da USB), dois GND e o EN, que reinicia a placa;
• o LED azul da placa está ligado ao GPIO2. É ele que o primeiro programa pisca;
• o botão EN reinicia o chip; o botão BOOT está ligado ao GPIO0 e, apertado na hora de ligar, coloca a placa no modo de gravação de firmware;
• com o MicroPython, a CPU roda a 160 MHz (valor conferido numa DevKit V1 do laboratório).

Os pinos aparecem na placa com nomes como D2, D18 ou D34. O número depois do D é o número do GPIO (General Purpose Input/Output, entrada e saída de uso geral), e é esse número que o MicroPython usa. Escrever Pin('D2') não funciona: o certo é Pin(2). O mapa de pinos do PyPlaca mostra cada um dos 30 pinos com o que ele pode fazer e os cuidados de cada um.

Pinos que pedem atenção

A ESP32 tem algumas regras de fábrica que pegam iniciantes de surpresa. Não é preciso decorar agora, mas vale saber que existem:

• os GPIOs 34 a 39 são somente entrada: Pin(34, Pin.OUT) dá ValueError: pin can only be input. Eles também não têm resistor de pull interno;
• os GPIOs 6 a 11 são usados pela memória flash do módulo e nem aparecem no conector da DevKit V1 de 30 pinos;
• os GPIOs 1 e 3 são a porta serial do REPL. Usá-los como pino comum desliga o terminal;
• os GPIOs 0, 2, 5, 12 e 15 são pinos de strapping: o chip lê o nível deles no instante em que liga para decidir como dar a partida. Ligar coisas que forcem nível nesses pinos pode impedir a placa de iniciar.

O simulador conhece essas regras e mostra um aviso didático na aba Avisos quando o seu programa ou o seu circuito esbarra numa delas, mesmo nos casos em que a placa real falharia em silêncio.

O primeiro programa: piscar o LED do GPIO2

Para controlar um pino, o MicroPython usa a classe Pin, que fica no módulo machine (o módulo que reúne tudo o que é específico do hardware). Criamos um objeto dizendo o número do pino e o modo: Pin.OUT para saída, Pin.IN para entrada. Depois, on() coloca o pino em 3,3 V e off(), em 0 V.

from machine import Pin
import time

led = Pin(2, Pin.OUT)   # o LED azul da DevKit V1

for i in range(10):
    led.on()
    time.sleep_ms(500)  # meio segundo aceso
    led.off()
    time.sleep_ms(500)  # meio segundo apagado

print('fim: o LED piscou 10 vezes')

Clique em Abrir no simulador e depois em Executar. O código vai para o main.py da IDE livre (o que estava lá antes volta com Ctrl+Z) e o LED azul da placa simulada pisca dez vezes. Abra a aba Pinos: ela desenha o GPIO2 como um analisador lógico, uma onda quadrada subindo e descendo a cada meio segundo.

Repare em três detalhes do código:

1. from machine import Pin traz a classe Pin; import time traz o módulo de tempo;
2. Pin(2, Pin.OUT) configura o pino uma vez só, fora do laço. Chamar Pin(2) de novo devolve o mesmo objeto (é assim no MicroPython da ESP32), então não há problema em fazer isso, mas também não há ganho;
3. led.on() e led.off() têm equivalentes: led.value(1), led.value(0) e led.toggle(), que inverte o nível atual. Use o que deixar o programa mais legível.

Na placa real, um programa com while True: roda para sempre — é o normal num microcontrolador, que existe para fazer a mesma tarefa continuamente. Para parar, você aperta Ctrl+C no terminal (que gera um KeyboardInterrupt) ou reinicia a placa. No simulador, o botão de parar faz o mesmo papel.

O tempo no MicroPython

O módulo time tem três jeitos de esperar, que diferem só na unidade:

• time.sleep(1) espera em segundos (aceita frações, como 0.5);
• time.sleep_ms(500) espera em milissegundos;
• time.sleep_us(100) espera em microssegundos.

Enquanto espera, o programa fica parado naquela linha. Para medir quanto tempo passou, o MicroPython oferece um relógio que começa a contar quando a placa liga: time.ticks_ms(), em milissegundos (também existe time.ticks_us(), em microssegundos). A diferença entre duas leituras se calcula com time.ticks_diff(fim, inicio) — e não com uma subtração simples.

import time

inicio = time.ticks_ms()
time.sleep_ms(250)
fim = time.ticks_ms()
print('passaram', time.ticks_diff(fim, inicio), 'ms')

print(10 / 3)   # a placa usa float de 32 bits

Por que ticks_diff? Porque o contador dos ticks dá a volta: no MicroPython da ESP32 ele conta até 2^30 milissegundos e recomeça do zero, o que acontece depois de pouco mais de doze dias com a placa ligada. Nessa hora, fim - inicio daria um número negativo enorme, enquanto ticks_diff faz a conta certa. É um hábito que vale criar desde o primeiro programa: tempo de placa se compara com ticks_diff e se soma com ticks_add.

A última linha do exemplo mostra outra diferença em relação ao Python do computador: a ESP32 usa números de ponto flutuante de 32 bits. Por isso 10 / 3 aparece como 3.3333332 e não como 3.3333333333333335. Foi assim que uma DevKit V1 do laboratório imprimiu, e o simulador traduz linha a linha o código do MicroPython que formata os números para mostrar exatamente o mesmo texto.

O relógio do simulador

Uma pergunta justa: se o simulador roda no navegador, como ele sabe quanto vale meio segundo "na placa"? O PyPlaca mantém um relógio virtual, o tempo de simulação que aparece no topo da bancada. Em velocidade 1×, ele anda junto com o relógio de verdade. Em Turbo, o simulador não espera: o programa termina quase na hora, mas o relógio da placa continua contando o tempo certo — um ticks_diff depois de sleep_ms(250) dá 250 nos dois modos. Isso é útil para conferir programas longos sem ficar olhando o LED piscar.

Um LED de verdade na protoboard

O LED azul da placa é prático, mas quase todo projeto usa peças fora da placa. O passo seguinte é montar um LED numa protoboard e ligá-lo a um GPIO. Antes de ligar qualquer fio, é preciso entender duas coisas: o LED e o resistor.

O LED (diodo emissor de luz) só deixa a corrente passar num sentido: do ânodo (a perna mais longa, o lado positivo) para o cátodo (a perna curta, do lado chanfrado do corpo). Ao contrário, ele simplesmente não acende. Quando acende, segura uma tensão quase fixa entre as pernas, a tensão direta (Vf). Para LEDs de 5 mm, os valores típicos são cerca de 2,0 V no vermelho, 2,1 V no amarelo, 2,2 V no verde e 3,1 V no azul e no branco. A corrente máxima típica é de uns 20 mA.

O resistor é o que impede o LED de pedir corrente demais. Sem ele, a única coisa limitando a corrente seriam as resistências internas do pino e do LED — pequenas demais para proteger qualquer um dos dois. Com um resistor em série, a conta fica simples: a tensão que sobra no resistor é a do pino menos a do LED, e a corrente é essa sobra dividida pela resistência (lei de Ohm).

A tabela mostra uma surpresa comum: o LED azul, com o mesmo resistor de 220 Ω, fica bem mais fraco. Com 3,3 V no pino, sobram só uns 0,2 V para o resistor, e a corrente cai para perto de 1 mA. Não é defeito — é a física do LED. O simulador mostra esse efeito e, quando a corrente fica muito baixa, avisa que o LED está fraco.

A protoboard por dentro

A protoboard de 830 pontos é a base de montagem de quase todos os circuitos da série. Por dentro, cada coluna tem duas tiras de metal: os cinco furos de cima (a a e) são ligados entre si, e os cinco de baixo (f a j) também, separados pelo canal do meio. Nas bordas correm os barramentos + e −, ligados ao longo de todo o comprimento, que costumam levar a alimentação e o GND. Duas pernas encaixadas na mesma coluna (do mesmo lado do canal) estão ligadas, mesmo sem fio nenhum entre elas — é assim que o resistor "encosta" no LED.

Um detalhe prático da DevKit V1: ela é larga. Encaixada sobre uma protoboard de 830 pontos, ocupa quase toda a largura e deixa só uma fileira livre de um dos lados. Por isso, em muitas montagens do laboratório (e do simulador), a placa fica ao lado da protoboard e os pinos chegam por fios, ou se usam duas protoboards lado a lado.

O circuito da lição do LED externo faz este caminho: do pino D18 (GPIO18) sai um fio até a coluna do resistor de 220 Ω; a outra perna do resistor divide a coluna com o ânodo do LED; o cátodo fica numa coluna própria, ligada por um fio preto ao barramento de GND, que por sua vez está ligado ao GND da placa. A corrente sai do pino, passa pelo resistor, pelo LED e volta pelo GND. Se qualquer trecho desse caminho faltar, nada acende.

from machine import Pin
import time

led = Pin(18, Pin.OUT)

for i in range(5):
    led.on()
    time.sleep_ms(300)
    led.off()
    time.sleep_ms(300)

Este exemplo abre já com o circuito montado. Rode e veja o LED piscar na aba Circuito. Depois, experimente quebrar o circuito de propósito: selecione o fio preto, apague com Delete e rode de novo. Sem caminho até o GND, o LED não acende — exatamente como na bancada. Ctrl+Z traz o fio de volta. Troque também o resistor de 220 Ω por um de 1 kΩ no painel da peça: a corrente cai para cerca de um quinto e o LED fica mais fraco.

Erros que o simulador ajuda a achar

Montar circuitos é a parte em que mais se erra no começo, e quase sempre pelos mesmos motivos. O PyPlaca verifica o circuito e mostra avisos com o nome do problema:

• LED sem resistor: o LED ligado direto entre o pino e o GND. Sem resistor, a corrente passaria do limite do LED e do pino;
• LED invertido: o ânodo do lado de menor tensão. A perna longa vai no positivo;
• curto-circuito: o 3V3 ou o VIN ligados direto ao GND. Na placa real, o regulador desligaria ou queimaria;
• fio desconectado: uma ponta do fio sem pino nenhum. Ele não participa do circuito e o resto fica incompleto.

Passar o mouse sobre um furo da protoboard destaca tudo o que está ligado a ele, o que ajuda a enxergar se duas pernas estão mesmo na mesma coluna. É o equivalente a seguir o fio com o dedo na bancada.

Os arquivos da placa: boot.py e main.py

Quando a ESP32 com MicroPython liga (ou reinicia), ela procura dois arquivos no seu sistema de arquivos interno e executa nesta ordem: primeiro o boot.py, depois o main.py. O boot.py costuma ficar quase vazio; nele vão configurações que precisam acontecer antes de tudo. O main.py é o programa de verdade. Quando o main.py termina (ou quando você o interrompe), a placa volta para o REPL e fica esperando comandos.

O simulador segue a mesma ideia. O projeto da IDE tem o main.py e o boot.py, e você pode criar outros arquivos .py para organizar o código em módulos, importando-os normalmente com import. Quando o programa termina, o painel Serial vira o REPL, com o prompt >>>, ligado às variáveis do programa que acabou de rodar: dá para perguntar quanto vale uma variável ou chamar uma função sem rodar tudo de novo.

O botão EN da placa simulada também se comporta como o de verdade: ao soltá-lo, a placa reinicia e roda o boot.py e o main.py outra vez.

Lendo os erros como a placa mostra

Erros são parte do processo, e o MicroPython tem o mérito de explicá-los em texto. Quando algo dá errado, a placa imprime um traceback: o arquivo, a linha e o tipo do erro. Por exemplo, usar uma variável que não existe mostra NameError: name 'total' isn't defined. O simulador imprime exatamente o mesmo texto da placa (a mensagem do MicroPython é um pouco diferente da do Python do computador, que diz "is not defined") e, logo abaixo, uma explicação em português do que costuma causar aquele erro.

Alguns erros que todo iniciante encontra na ESP32:

• ValueError: invalid pin: um número de pino que o chip não tem, como 24 ou 40;
• ValueError: pin can only be input: tentar usar um dos GPIOs 34 a 39 como saída;
• IndentationError: um bloco com recuo diferente. Em Python, os quatro espaços no começo da linha são parte do código;
• ImportError: no module named ...: um módulo que não existe no firmware nem no projeto.

Ler o traceback de baixo para cima, começando pelo tipo do erro e depois pela linha indicada, resolve a maioria dos casos em poucos segundos.

Do simulador para a placa real

O PyPlaca foi pensado para que o código saia do navegador e vá para uma ESP32 de verdade sem mudanças. O que é exportado é sempre o texto Python do aluno: o main.py original, as bibliotecas e os módulos do projeto. A aba Placa real reúne os caminhos:

• Exportar .zip ou Baixar main.py: para gravar com a ferramenta que você já usa (Thonny, mpremote ou outra);
• Lista de materiais (CSV): as peças do circuito, para separar na bancada;
• Gravar na placa: no Chrome ou no Edge, pelo Web Serial, a IDE conversa com a ESP32 ligada na USB, grava os arquivos (o main.py por último) e reinicia a placa para rodar o programa novo;
• Instalar MicroPython: para uma placa nova, sem o interpretador. O próprio aluno baixa o firmware oficial ESP32_GENERIC da versão 1.29.0 no site do MicroPython; a IDE confere que o chip é uma ESP32 comum com flash de pelo menos 4 MB, apaga a memória, grava o firmware no endereço 0x1000 e confere o resultado antes de reiniciar.

Na bancada, o caminho do circuito é o mesmo da tela: os mesmos pinos, o mesmo resistor, o LED com a perna longa no lado do resistor. A diferença é que, na placa real, um erro de montagem pode estragar uma peça — razão a mais para testar primeiro no simulador.

Um roteiro para os próximos passos

Com o LED piscando, você já usou as três ideias que sustentam todo o resto: configurar um pino, mudar o nível dele e controlar o tempo. Os próximos artigos desta série aprofundam cada uma:

• GPIO, pull-up e o pino flutuante: o pino como entrada, botões e por que um pino solto não é confiável;
• PWM na prática: brilho, som e movimento com a modulação por largura de pulso;
• O ADC da ESP32: como medir tensões e por que a leitura não chega a 3,3 V.

Nas trilhas, cada um desses assuntos vira lições curtas com circuito pronto e desafios com correção automática. A primeira trilha refaz exatamente o caminho deste artigo, do LED da placa ao primeiro circuito montado por você — e termina com um semáforo.