Código Arduino explicado passo a passo: entenda e depois mude

Entenda o código é a aba da seção Código-fonte de cada página de projeto do BlueGrays que explica passo a passo o código Arduino pronto. Para descobrir o que o código que você copiou e carregou realmente faz, siga esta ordem: primeiro leia o resumo O que este código faz?, depois encontre no código completo cada trecho da seção Passo a passo junto com a explicação, consulte o Se precisar de ajuda se o circuito não se comportar como esperado e, por fim, use a tarefa Experimente você mesmo para mudar uma coisa no código e ver o resultado na placa. Essas quatro seções são o caminho mais curto de “funciona, mas não sei por quê” até “sei o que acontece se eu mudar esta linha”.

Neste post percorremos a aba Entenda o código do início ao fim usando o conteúdo real de um projeto real: o projeto número 10, Ligar e desligar um LED com botão. Ele é grátis, tem nível Iniciante e também tem visualização em blocos, então qualquer pessoa pode abrir a explicação tanto do código quanto dos blocos. Você vai encontrar as seções da aba, um método para ligar o código à explicação, uma rotina de estudo de 15 minutos, uma estratégia para resolver as tarefas Experimente você mesmo, qual mudança ensina qual conceito, a visualização Entenda os blocos, a diferença entre Se precisar de ajuda e Solução de problemas e ideias para professores usarem na sala de aula.

Onde fica a aba Entenda o código e quem pode usar?

Quando você abre um projeto e desce até a seção Código-fonte, vê no topo um seletor com duas abas: Código e Entenda o código. A aba Código mostra o programa completo, e é nela que estão os botões Copiar e Copiar link. Passe para o Entenda o código e abre a versão comentada do mesmo programa. Todos os 200+ projetos têm essa aba, e ela funciona do mesmo jeito nos projetos de Arduino, ESP32 e Raspberry Pi Pico. O acesso é simples: nos 60 projetos grátis (20 por plataforma), o Entenda o código é aberto para todos, então mesmo com uma conta grátis você vê o resumo, todos os passos, o Se precisar de ajuda e a tarefa Experimente você mesmo com a solução. Nos projetos Premium, no lugar da aba fica um cartão de bloqueio: “Desbloqueie a explicação do código passo a passo com o Premium.” Ou seja, você pode usar o método deste post no LED piscante, no Semáforo, nas Luzes de polícia com LEDs e nos projetos com botão sem pagar nada.

As seções: para que serve cada uma

A ordem das seções é proposital: primeiro o quadro geral, depois as partes, depois os erros e, por fim, o seu próprio experimento. Os trechos de código não são o programa inteiro, só as linhas que aquele passo explica; a chave de fechamento de um bloco aberto em um passo pode aparecer no seguinte. Por isso, ler todos os passos na ordem funciona melhor do que dar uma olhada em um só. A dica fica visível logo abaixo do texto da tarefa, enquanto a solução continua escondida até você tocar em Ver solução. Essa disposição dá espaço para pensar antes de ver a resposta.

Exemplo: o Entenda o código no projeto Ligar e desligar um LED com botão

O projeto usa um botão de pressão e um LED. Um lado do botão vai ao 5V e o lado oposto ao pino 13 da placa; o mesmo pino é puxado para o GND por um resistor de 10 kΩ. A perna longa do LED vai ao pino 7 e a curta ao GND por um resistor de 330 Ω. O resumo do Entenda o código descreve o programa assim: cada vez que você aperta o botão, o LED inverte o estado uma vez, acendendo se estava apagado e apagando se estava aceso; mesmo que você segure o botão, o LED muda só uma vez, e uma espera de 50 ms ignora o repique do botão. Aqui está o programa completo, com comentários em dois idiomas.

1int ledState = 0;     // LED durumu: 0 sönük, 1 yanık / LED state: 0 = off, 1 = on
2int lastButton = 0;   // Butonun önceki okuması / Previous button reading
3
4void setup() {
5  pinMode(13, INPUT);   // Buton girişi, harici pull-down / Button input, external pull-down
6  pinMode(7, OUTPUT);   // LED çıkışı / LED output
7}
8
9void loop() {
10  int button = digitalRead(13);   // Butonu oku / Read the button
11  if (button != lastButton) {     // Buton durumu değişti / Button state changed
12    if (button == 1) {            // Yalnız basış anında (LOW -> HIGH) / Only at the press (LOW -> HIGH)
13      ledState = !ledState;       // Durumu tersine çevir / Flip the state
14      digitalWrite(7, ledState);  // Yeni durumu LED'e yaz / Write the new state to the LED
15    }
16    delay(50);                    // Sıçramayı atlamak için kısa bekleme / Short wait to skip the bounce
17    lastButton = button;          // Bu okumayı sakla / Store this reading
18  }
19}

O que observar ao ler os passos é que a explicação não diz só o que acontece, mas também o que aconteceria sem aquela linha. O passo 1 mostra que ledState começa em 0, então o LED fica apagado quando a placa liga. Isso leva a uma boa pergunta: se você puser 1, o LED começa aceso? Não, porque essa linha só muda a variável; o setup() não escreve nada no LED, então ele começa apagado, e no primeiro toque ledState volta a 0, então ele continua apagado. O valor de uma variável e o estado real de um pino são duas coisas diferentes. O passo 2 liga o uso de INPUT no botão ao resistor de 10 kΩ do circuito: quando o botão não está apertado, o resistor puxa o pino para o GND e ele lê 0. Tire o resistor e o pino fica flutuando e lê valores aleatórios; o sintoma “o LED acende e apaga sozinho” do Se precisar de ajuda corresponde exatamente a isso.

Os passos 3 e 5 devem ser lidos juntos. A comparação do passo 3 só funciona se lastButton for atualizado depois de cada mudança, e essa atualização é a linha lastButton = button do passo 5. Quando você liga os dois passos, a ideia central do programa fica clara: o código não verifica se o botão está apertado, ele verifica se o estado mudou. Enquanto você segura, cada volta lê 1, mas lastButton também é 1, então a comparação é falsa e o LED não muda. O operador ! do passo 4 é um interruptor liga/desliga de duas linhas. O passo 5 termina com um aviso: se a espera for curta demais, às vezes o LED pode mudar mais de uma vez por toque. Isso sugere o seu primeiro experimento antes da tarefa: baixe 50 para 5, aperte algumas vezes e veja se o LED às vezes inverte duas vezes; o resultado depende da qualidade do botão. Para saber mais sobre debounce, veja como ligar um botão no Arduino.

A seção Se precisar de ajuda deste projeto lista cinco sintomas: o LED nunca acende; o LED muda sozinho sem tocar no botão; nada acontece quando você aperta o botão; o botão se comporta como se estivesse sempre apertado; o código não carrega. Cada sintoma vem com uma verificação concreta. Para o sintoma “sempre apertado”, por exemplo, ela explica que, quando as pernas do botão são encaixadas do jeito errado, o D13 fica ligado ao 5V o tempo todo e você precisa girar o botão 90 graus. A tarefa Experimente você mesmo é esta: fazer o LED mudar quando você solta o botão, e não quando aperta. A dica lembra que a variável button vira 1 no momento do aperto e 0 no momento em que você solta. A solução é uma mudança de um caractere: a linha if (button == 1) vira if (button == 0). Essa pequena tarefa testa se você entendeu de verdade a ideia de detecção de borda do passo 3.

Como ler: resumo, ligação, teste

1. Leia o resumo e escreva em uma frase: leia o O que este código faz? e depois escreva o programa em uma frase no caderno, sem olhar o celular. Para o projeto do botão: “Cada toque acende ou apaga o LED uma vez.”
2. Ligue o código aos passos de cima para baixo: abra o código no Arduino IDE (o Copiar link do Código-fonte facilita isso), encontre o trecho de cada passo no código completo e acrescente o número do passo ao lado da linha como comentário. Os passos seguem a ordem do código: variáveis globais, setup(), loop().
3. Marque as linhas sem par: se uma linha não é tratada por nenhum passo (geralmente só sobram chaves de fechamento), pense por que ela não é explicada; se não for uma chave, procure-a de novo nas explicações.
4. Teste no circuito: carregue o código e teste um por um os comportamentos do resumo. Três testes bastam para o projeto do botão: um toque só, segurar apertado e toques rápidos repetidos. Diga em voz alta o que vai acontecer antes de cada teste.

A etapa de ligação é a que as pessoas mais pulam, e é a que mais compensa. Quando você escreve os números dos passos ao lado das linhas, o esqueleto do código fica visível: qual linha roda uma vez e qual roda sem parar, onde cada variável é lida e onde é escrita. No projeto do botão, lastButton aparece em dois lugares: é declarada no passo 1 e atualizada no passo 5. Ver isso com os próprios olhos fixa muito melhor do que ler “uma variável é uma caixa”. Se quiser estudar variáveis, laços e funções separadamente, veja fundamentos de programação Arduino.

Uma rotina de 15 minutos com o Entenda o código

Esta rotina é para um projeto cujo circuito já está montado. Se você vai montar o circuito pela primeira vez, acrescente 10–15 minutos ou deixe a rotina do Entenda o código para o dia seguinte. Os dois últimos minutos são a parte mais valiosa: fazer a sua própria pequena mudança depois de ver a solução testa a ideia que você entendeu, não a resposta que você decorou. No projeto do botão, você poderia, por exemplo, passar o LED para outro pino ou subir a espera de 50 ms para 300 ms e ver o que acontece com os toques rápidos. Um projeto por dia nesse ritmo significa terminar cinco projetos grátis em uma semana, entendendo-os de verdade. Para um plano mais longo, veja o roteiro de Arduino em 30 dias.

Uma estratégia para resolver as tarefas Experimente você mesmo

As tarefas Experimente você mesmo são curtas, mas escolhidas com cuidado: cada uma pede uma única mudança, e o resultado é algo que você consegue ver ou ouvir. Seguir esta ordem ao resolvê-las dobra o que você aprende:

1. Preveja: leia a tarefa e diga em qual linha do código você vai mexer e o que vai ver depois da mudança. Anotar a previsão evita depois a ilusão de “eu sabia desde o começo”.
2. Mude: mude só uma coisa. Se você mudar duas linhas de uma vez, não dá para saber qual mudança causou o quê.
3. Carregue: carregue o código na placa e espere a mensagem de que o carregamento terminou. Se der erro de compilação, confira os pontos e vírgulas e os parênteses da linha que você mudou.
4. Observe: compare o resultado com a sua previsão. Nas tarefas de tempo, conte os segundos; nas de som, ouça o som antigo e o novo um depois do outro.
5. Veja a dica: se a previsão falhou ou você não achou em qual linha mexer, leia a dica. Como a dica fica visível logo abaixo da tarefa, cobri-la com a mão na primeira leitura ajuda.
6. Abra a solução por último: toque em Ver solução só depois de fazer a sua tentativa. Se a solução bater com a sua, pense por que ela está certa; se for diferente, pense por que as duas abordagens dão resultados diferentes.

Outra vantagem dessa ordem é que ela torna os erros úteis. Digamos que na tarefa do Semáforo você queira esticar o amarelo depois do verde para 1,5 segundo, mas muda por engano a primeira linha delay(300). Em vez do que esperava, você vai ver o amarelo depois do vermelho ficar mais longo. Esse erro ensina que o código tem duas fases de amarelo separadas e que o loop() roda linha por linha muito melhor do que a solução ensinaria. A solução da tarefa diz exatamente isso: a linha delay(300) bem no fim do loop() vira delay(1500), enquanto o amarelo depois do vermelho continua em 0,3 segundo.

Tipos de mudança: qual ensina qual conceito?

Olhe as tarefas dos projetos grátis e você vai ver que cada uma se encaixa em um de poucos tipos. Reconhecer o tipo também facilita criar a sua própria tarefa em um projeto novo. Os exemplos da tabela vêm de tarefas Experimente você mesmo reais dos projetos grátis; a linha da troca de pino é um experimento que você pode fazer sozinho no mesmo projeto.

Entenda os blocos: a mesma explicação com blocos

Os projetos com visualização em blocos têm uma chave Ver em blocos na seção Código-fonte. Ligue-a e o mesmo programa aparece em blocos no idioma do app no lugar do código, e a aba ao lado muda de Entenda o código para Entenda os blocos. Nessa visualização, o resumo, o Se precisar de ajuda e a tarefa continuam iguais; o que muda é a seção Passo a passo: cada passo mostra os próprios blocos no lugar do trecho de código, e tocar na imagem abre em tela cheia. Mais de 100 projetos têm visualização em blocos, incluindo mais de 30 dos grátis. Os blocos são só para leitura; não dá para editá-los no app nem carregá-los na placa, e o que vai para a placa é sempre o código de verdade.

O melhor jeito de usar o Entenda os blocos é alternar entre as duas visualizações. No projeto do botão, os blocos do passo 3 são um bloco “definir button como ler pino 13” mais dois blocos “se” aninhados; no código, isso é a linha int button = digitalRead(13); e dois if aninhados. O bloco “definir ledState como não ledState” do passo 4 é exatamente a linha ledState = !ledState;. Leia primeiro o bloco e diga o que ele faz, depois desligue a chave e olhe o trecho de código do mesmo passo. Ligar blocos a código desse jeito é a forma mais sólida de passar da programação em blocos para o código em texto; para começar o assunto do início, veja o que é programação em blocos e o bloco se.

Se precisar de ajuda ou Solução de problemas?

Na prática, a ordem é esta: quando o circuito não funcionar, descreva o sintoma em uma frase e procure-o no Se precisar de ajuda. Se o seu sintoma estiver na lista, a solução geralmente é um único fio, resistor ou linha. Se não estiver, ou se a solução sugerida não resolveu, passe pelos passos da Solução de problemas na ordem; é provável que você pegue uma verificação básica que pulou (alimentação da placa, a porta certa, um GND comum). Se você travou na etapa do carregamento, erro ao carregar código no Arduino ajuda, e para erros de compilação há erros de compilação no Arduino.

Para professores: usando o Entenda o código na sala de aula

• Leitura conjunta no projetor: no início da aula, espelhe a tela do celular, leiam juntos o resumo O que este código faz? e peça que a turma resuma o programa em uma frase. Depois mostre os mesmos passos em blocos com o Ver em blocos ligado; para os alunos que começaram com blocos, isso é uma ponte.
• Um grupo por passo: em um projeto de 5 passos, divida a turma em 5 grupos; cada grupo lê um passo, encontra o trecho no código completo e o explica à turma em dois minutos. Enquanto um grupo explica, os outros perguntam “o que aconteceria sem esta linha?”.
• Papel de previsão: escreva a tarefa Experimente você mesmo na lousa; cada grupo anota a previsão em um papelzinho antes de fazer a mudança e depois muda o código e carrega. Discutir a diferença entre previsão e resultado ensina mais do que fazer a tarefa em si.
• Pergunta de saída: nos dois últimos minutos da aula, todos respondem a uma pergunta. Exemplos para o projeto do botão: o que aconteceria ao segurar o botão se não existisse lastButton? O que muda se você apagar o delay(50)? Por que o LED poderia mudar sozinho se você tirar o resistor de 10 kΩ?

Ao planejar o acesso, lembre-se disto: como o Entenda o código é aberto a todos nos projetos grátis, seus alunos podem usar este método com o LED piscante, o Semáforo, as Luzes de polícia com LEDs e os dois projetos com botão sem pagar nada. Nos projetos Premium, o Entenda o código é liberado com Premium; se quiser levar a turma para os projetos Premium, você pode distribuir códigos dos pacotes para educadores em vez de cada aluno fazer uma assinatura, como explicado em um app de Arduino para a sala de aula. Se quiser compartilhar um circuito que você mesmo projetou, pode abrir uma publicação na categoria Tutorial no Fórum; ela não vem com os passos do Entenda o código nem com visualização em blocos, então você mesmo escreve a explicação no texto da publicação e adiciona o código com Adicionar código (dar aula com o seu próprio projeto). O app também não tem um painel que mostre quais tarefas cada aluno resolveu; você confere a tarefa na aula, olhando o circuito funcionando ou por uma foto.

Erros comuns e soluções fáceis

• Abrir a solução na hora: se você toca em Ver solução assim que lê a tarefa, aprende a resposta, mas não a ideia. A regra: primeiro a previsão, depois uma tentativa, depois a dica e, por último, a solução.
• Copiar sem ler os passos: pegar o código com Copiar e carregar funciona, mas se você passa para o próximo projeto sem ler o Passo a passo, começa do zero toda vez. Depois de carregar, leia pelo menos o resumo e os passos.
• Tratar um trecho de código como o programa inteiro: os trechos são só as linhas daquele passo; cole um sozinho no IDE e ele não compila. Faça as mudanças sempre no código completo.
• Mudar várias coisas de uma vez: se você muda duas linhas juntas e tem um resultado inesperado, não dá para saber qual é a responsável. Uma mudança por carregamento.
• Mudar um número de pino em um lugar só: mudar o pinMode e esquecer o digitalWrite ou o fio é um dos erros mais comuns. Antes de mudar, marque todos os lugares em que o número aparece no código.
• Pular o Se precisar de ajuda e perguntar logo no fórum: a resposta muitas vezes já está na lista Se precisar de ajuda daquele projeto. Veja lá primeiro, depois na Solução de problemas; se continuar sem solução, pergunte no fórum com uma foto do circuito e o seu código.
• Terminar a tarefa e parar por aí: se você não faz a sua própria pequena mudança depois de comparar com a solução, o que aprendeu fica preso àquela tarefa. Escolha você mesmo um número, um pino ou uma condição.

Depois de usar o Entenda o código nessa ordem em alguns projetos, o código pronto deixa de ser uma caixa fechada: você consegue dizer antes qual linha controla o quê e o que vai acontecer se mudá-la. O Ligar e desligar um LED com botão é um bom lugar para criar esse hábito, porque um código curto mostra de uma vez uma variável global, detecção de borda, alternância e debounce. Se quiser experimentar, abra este projeto no app BlueGrays e comece pela tarefa da aba Entenda o código; as mesmas seções estão em todos os 60 projetos grátis.