Projeto Arduino não funciona? Uma ordem de diagnóstico em 10 minutos

Se o seu projeto Arduino não está funcionando, não procure a falha puxando fios ao acaso. Trabalhe de fora para dentro: primeiro a alimentação (a placa liga?), depois o carregamento (o código chegou mesmo à placa?), depois as ligações (o GND é comum, cada fio está no pino certo?), depois a orientação e o valor das peças (o LED está invertido, o resistor é o certo?), depois o código (números dos pinos e lógica) e, por fim, o sensor e o ambiente (luz, distância, tensão de alimentação). Faça um teste por camada e mude só uma coisa por vez. Seguindo essa ordem, você encontra a maioria das falhas em 10 minutos, porque os erros mais comuns ficam nas camadas externas, que são as mais baratas de verificar.

Este post não lista mensagens de erro uma por uma; ele dá a você um método de diagnóstico. Primeiro você vai ver as duas regras do método e, depois, uma tabela de fluxo com o sintoma, um teste de 1 minuto e a causa provável de cada camada. Em seguida vêm um sketch de teste curto que divide o circuito em partes usando o Blink e o Monitor Serial, 4 verificações com multímetro (mais alternativas com LED e Monitor Serial se você não tiver um), o diagnóstico passo a passo de uma falha em um projeto grátis do BlueGrays, uma tabela de consulta rápida por sintoma e um checklist de diagnóstico de 8 pontos para a sala de aula.

As duas regras do diagnóstico: de fora para dentro, uma variável por vez

A lógica de ir de fora para dentro é simples: as camadas internas dependem das externas. Se a placa não tem alimentação, não importa se o código está certo; se o código nunca chegou à placa, corrigir as ligações não muda nada. As camadas externas também são as mais rápidas de verificar: olhar o LED de alimentação leva 5 segundos e ler a mensagem de carregamento leva 10, mas achar um erro de lógica no código pode levar minutos. A segunda regra é a da variável única. Se você trocar o fio, o resistor e o limite no código de uma vez só, não vai saber o que resolveu, mesmo que o projeto comece a funcionar; e, se não funcionar, você pode ter criado uma falha nova. Faça uma mudança, teste, anote o resultado e só então passe para a próxima.

• Escreva o sintoma em uma frase: “Quando coloco a mão sobre o LDR, espero que o LED acenda, mas ele nunca acende.” “Não funciona” não é um sintoma; quando você escreve separadamente o que esperava e o que aconteceu, a camada a verificar muitas vezes fica óbvia.
• Desconecte o USB enquanto mexe nas ligações: se a placa continuar alimentada enquanto você muda as conexões, um toque errado pode causar um curto-circuito. Faça a mudança, confira visualmente e depois conecte de novo.
• Troque por uma peça que você sabe que funciona: substituir o LED, o fio ou o sensor suspeito por um que comprovadamente funciona é o teste mais forte que dá para fazer sem medidor.
• Faça anotações: notas curtas como “passei o fio do 7 para o 8, nada mudou” evitam que você repita o mesmo teste e viram um resumo pronto se você perguntar em um fórum ou ao seu professor.
• Simplifique: se o projeto for grande, tire os módulos um por um. Primeiro só a placa, depois a placa com a parte de saída e então a parte de entrada. Ver qual parte faz tudo parar mostra onde está a falha.

A tabela de fluxo de diagnóstico em 10 minutos

Leia a tabela abaixo de cima para baixo e não desça para a próxima camada até o teste atual passar. Cada teste leva cerca de um minuto, então as seis camadas ficam prontas em 6–10 minutos. Na maioria dos testes, bastam seus olhos, os LEDs da placa e o Monitor Serial da Arduino IDE; um multímetro acelera as coisas, mas não é obrigatório. A coluna “Causa provável” lista os primeiros lugares a olhar quando um teste falha, mais ou menos na ordem de frequência.

Camadas 1 e 2: alimentação e carregamento

No Arduino Uno, dois LEDs dão a primeira pista para essas duas camadas. O LED ON mostra que a placa está alimentada; se estiver apagado, troque primeiro o cabo USB, porque alguns cabos só carregam e não transmitem dados. Se o ON acende, mas o som de conexão USB do computador falha quando você conecta a placa, ou o LED pisca, pode haver um curto no circuito: desconecte o USB, acompanhe as linhas de 5V e GND e procure um módulo encaixado ao contrário ou um fio ligando as duas trilhas. Uma peça que esquenta é sempre um sinal sério; não alimente a placa de novo até retirá-la. Se você usa motor, servo ou relé, o USB pode não fornecer corrente suficiente; nesse caso, o sintoma costuma não ser “nada funciona”, e sim reinicializações aleatórias ou tremedeira. Para opções com bateria e adaptador, veja como alimentar o Arduino com bateria.

Na camada de carregamento, você responde a uma única pergunta: o código que está na placa é o código que você vê na tela? Quando um carregamento termina, a Arduino IDE avisa na área de saída, embaixo; se houver linhas vermelhas, o código nunca chegou à placa e ela continua rodando o programa antigo. Isso engana, porque você vai achar que a sua correção não funcionou. Para erros de avrdude, de porta e de driver, erro ao carregar código no Arduino explica cada mensagem e, se você travou na compilação, veja erros de compilação. Há também um teste simples de prova: mude um delay no código de 100 para 1000 e carregue. Se o ritmo do LED não mudar, o problema está na camada de carregamento. Algumas placas ESP32 precisam que o botão BOOT fique pressionado durante o carregamento; em um Raspberry Pi Pico, confira se o interpretador MicroPython está selecionado no canto inferior direito do Thonny.

Camada 3: ligações, GND e pinos

Com a placa alimentada e o código carregado, é a vez dos fios. Os dois erros mais comuns são esquecer o GND comum e ler a protoboard errado. Mesmo que um sensor ou módulo tenha alimentação própria, o GND dele precisa ser ligado ao GND do Arduino; caso contrário, a tensão do sinal fica sem referência. Na protoboard, o canal central separa as duas metades e, em protoboards compridas, as trilhas de alimentação nas bordas podem ser divididas no meio; ligar 5V em uma metade da trilha e supor que ela alimenta uma peça na outra metade é um erro muito comum. O melhor método nesta camada é a comparação um a um com o esquema: conte cada fio, nas duas pontas, e aponte com o dedo o correspondente no esquema. O digital 2 trocado pelo analógico A2, o 5V confundido com o VIN ou um fio deslocado uma fileira aparecem na hora. Se os símbolos do esquema parecerem estranhos, como ler um esquema de circuito mostra como passá-lo para a protoboard.

Camada 4: orientação e valor das peças

Se as ligações estão certas, mas uma peça ainda não responde, olhe a própria peça. A perna longa do LED (ânodo) deve ir pelo resistor até o pino, e a perna curta (cátodo) ao GND; um LED invertido geralmente não queima, só fica apagado. Os resistores são as peças mais confundidas: o de 220 Ω tem faixas vermelho-vermelho-marrom, e o de 10 kΩ, marrom-preto-laranja. Coloque 10 kΩ ao lado de um LED e ele brilha tão fraco que você nem percebe; coloque 220 Ω ao lado de um LDR ou de um botão e as leituras deixam de fazer sentido. Você pode ler as faixas com a calculadora de código de cores de resistores e achar o valor certo para um LED com a calculadora de resistor para LED. Um botão de pressão de quatro pernas girado 90 graus será lido como sempre pressionado ou nunca pressionado. Nos módulos, a ordem de VCC, GND e sinal varia de fabricante para fabricante, então leia os rótulos dos pinos na própria placa, e não em uma foto da internet. Peças de três pernas, como transistores e reguladores de tensão, também têm ordens de pinos diferentes conforme o modelo.

Camada 5: código (números dos pinos e lógica)

Se o hardware está em ordem, confira se o código diz o mesmo que o circuito. A primeira verificação são os números dos pinos: se o LED está fisicamente no 8, mas o código diz digitalWrite(9, HIGH), tudo parece perfeito e nada acontece. A segunda é o pinMode: se pinMode(pin, OUTPUT) estiver faltando no setup(), digitalWrite(pin, HIGH) não transforma o pino em saída, só ativa o resistor de pull-up interno, e o LED brilha muito fraco. Fora o resistor, essa é a causa mais comum de “LED fraco”. A terceira é a lógica: escrever if (value = 100) não compara nada; isso atribui 100 à variável e a condição fica sempre verdadeira; a forma correta é ==. Limites e delays também pertencem a esta camada: com um limite que não combina com o seu ambiente, nada dispara nunca, mesmo com um sensor funcionando perfeitamente. Em projetos que usam bibliotecas, confira também se a biblioteca certa está instalada; os detalhes estão em como instalar uma biblioteca no Arduino.

Camada 6: sensor e ambiente

A última camada cobre condições externas que estragam o resultado mesmo quando o circuito e o código estão certos. O valor de um LDR depende da luz do ambiente; um limite que funciona perto da janela durante o dia pode falhar sob uma lâmpada à noite. O HC-SR04 não recebe eco de superfícies macias, como tecido, e não mede a menos de 2 cm. Os sensores de gás da série MQ precisam de alguns minutos de aquecimento antes de medir. O DHT11 retorna erros se você o ler mais de uma vez por segundo. Os pinos do ESP32 e do Raspberry Pi Pico trabalham com 3,3 V; ligar diretamente um sensor com saída de 5 V pode dar leituras erradas e danificar o pino. Fios longos, ruído de motores e entradas flutuantes também fazem os valores pularem. A melhor ferramenta desta camada é o Monitor Serial: observe o valor bruto do sensor e mude as condições de propósito. Se um display ou sensor I2C não responde de jeito nenhum, o sketch scanner em O que é I2C? mostra o endereço dele.

Dividir para conquistar: confira a placa com o Blink e as etapas com o Monitor Serial

A forma mais rápida de passar pelas camadas é dividir o circuito e o código em partes. A primeira parte é a própria placa: sem nada conectado, carregue um código que pisca o LED L da placa. Se o L piscar, alimentação, carregamento e placa estão bem e, a partir daí, você procura o problema fora da placa. A segunda parte é a saída: faça o LED externo piscar no mesmo código. A terceira parte é a entrada: mostre o valor do sensor no Monitor Serial. O sketch abaixo faz as três coisas e mostra um ponto de verificação numerado no Monitor Serial a cada etapa. Ligue o LED externo ao pino 9 por um resistor de 220 Ω e o sinal do sensor analógico que você está testando ao A0, e configure o Monitor Serial para 9600 baud.

1const int LED_PIN = 9;       // Harici LED pini / External LED pin
2const int SENSOR_PIN = A0;   // Analog sensör pini / Analog sensor pin
3
4void setup() {
5  Serial.begin(9600);                  // Seri monitör de 9600 olmalı / Serial Monitor must be 9600 too
6  pinMode(LED_BUILTIN, OUTPUT);        // Karttaki L ışığı / On-board L LED
7  pinMode(LED_PIN, OUTPUT);            // Harici LED çıkış / External LED as output
8  Serial.println("1) setup bitti");    // Kontrol noktası 1 / Checkpoint 1
9}
10
11void loop() {
12  digitalWrite(LED_BUILTIN, HIGH);     // Kart canlı mı? / Is the board alive?
13  digitalWrite(LED_PIN, HIGH);         // Harici LED açık / External LED on
14  Serial.println("2) LED acik");       // Kontrol noktası 2 / Checkpoint 2
15  delay(500);
16
17  digitalWrite(LED_BUILTIN, LOW);
18  digitalWrite(LED_PIN, LOW);          // Harici LED kapalı / External LED off
19  Serial.println("3) LED kapali");     // Kontrol noktası 3 / Checkpoint 3
20  delay(500);
21
22  int value = analogRead(SENSOR_PIN);  // 0-1023 arası okuma / Reading from 0 to 1023
23  Serial.print("4) A0 = ");
24  Serial.println(value);               // Sensör değeri / Sensor value
25}

A verdadeira força deste sketch são os pontos de verificação. Use o mesmo método no seu projeto: acrescente um Serial.println() curto no final do setup() e depois de cada etapa importante do loop(), por exemplo “botão pressionado” ou “limite ultrapassado”. A última mensagem que aparece no Monitor Serial mostra onde o programa travou. Para descobrir por que uma condição nunca dispara, mostre o valor comparado logo antes da condição; se “value < 50” nunca é verdadeiro, você vai ver ali mesmo que o valor nunca fica abaixo de 50. Em projetos maiores, use a mesma lógica: comente temporariamente uma parte do código e teste as partes uma por uma. Para configurações do Monitor Serial como baud rate, final de linha e o plotter, veja Monitor Serial do Arduino.

4 verificações com multímetro (ou com LED e Monitor Serial, se não tiver um)

O multímetro transforma o diagnóstico de adivinhação em medição, e só quatro medições cobrem a maioria das falhas no Arduino. Antes de medir, coloque o aparelho no modo certo: DC V (tensão contínua) para tensão, bipe (continuidade) para conferir fios e fileiras, Ω para resistência. Faça sempre as verificações de continuidade e de resistência com o USB desconectado. Se você não tem multímetro, os métodos da última coluna dão uma resposta mais grosseira, mas suficiente, para a mesma pergunta. As escalas do aparelho e em que bornes vão as pontas de prova estão explicadas com imagens em como usar um multímetro.

Exemplo resolvido: o LED não acende no projeto Luz noturna com LDR

Vamos testar o método em um projeto grátis do BlueGrays: Luz noturna com LDR. No circuito, uma ponta do LDR vai ao 5V e a outra ao A0; um resistor de 10 kΩ fica entre o A0 e o GND, e os dois formam um divisor de tensão. O LED se liga ao pino 13 por um resistor de 330 Ω. O código lê o A0 e, se o valor estiver abaixo de 50, considera que o ambiente está escuro e acende o LED. O sintoma: “Cubro o LDR com a mão e o LED nunca acende.” Em vez de trocar fios ao acaso, vamos passar pelas camadas em ordem.

1. Alimentação: o LED ON está aceso e nada está quente. Siga em frente.
2. Carregamento: o carregamento terminou sem erros. Para ter certeza, mude temporariamente o 50 do código para 2000 e carregue; como o analogRead retorna no máximo 1023, a condição fica sempre verdadeira e o LED deve ficar aceso.
3. Ligações e o LED L: o pino 13 também está ligado ao LED L da placa. Se o L acende com o limite de 2000, mas o LED externo não, o código está rodando e o problema está no caminho do LED. A perna longa do LED vai ao 13 pelo resistor de 330 Ω e a perna curta ao GND?
4. Orientação e valor das peças: o LED não está invertido, mas, se houver um resistor de 10 kΩ ao lado dele em vez do de 330 Ω, ele brilha fraco demais para perceber. Diferencie os dois resistores pelas cores.
5. Código e sensor: se o LED externo acende com o limite de 2000, volte para 50. Agora, para ver os valores reais, carregue no mesmo circuito o código do projeto Medição da intensidade da luz com LDR; ele usa a mesma ligação do LDR e mostra o A0 no Monitor Serial a cada meio segundo.
6. Leia os valores: digamos que você veja cerca de 600 com o LDR descoberto e cerca de 120 quando o cobre com a mão. O valor nunca fica abaixo de 50, então o LED nunca acende. Volte ao código da luz noturna e aumente o limite para algo entre 200 e 300.
7. Identifique o comportamento invertido: se o valor sobe em vez de cair quando você cobre o LDR, o LDR e o resistor de 10 kΩ trocaram de lugar. Se o valor pula aleatoriamente com a mão parada, o fio do A0 não está encaixado na fileira onde o LDR e o resistor se encontram.

O que encontrou a falha neste exemplo não foi um conhecimento novo, e sim a ordem: primeiro provamos que o próprio LED conseguia acender, depois olhamos o que o sensor realmente lê. No app, a seção Se precisar de ajuda da aba Entenda o código deste projeto já traz cinco desses sintomas como pares de sintoma e solução: o LED externo que nunca acende no escuro, o LED que acende no claro e apaga no escuro, o que não acende nem coberto com a mão, o que fica sempre aceso ou piscando, e um erro de carregamento. A seção Solução de problemas do projeto traz um checklist geral de 10 passos que começa na alimentação e passa por carregamento, números dos pinos, protoboard, jumpers, GND, LED e resistor. Como você deve ter notado, essa ordem é quase igual às camadas do início deste post.

Ajuda no app: onde olhar quando um projeto não funciona

• Solução de problemas: um checklist ordenado na página do projeto, que começa com “Se seu projeto não estiver funcionando, confira os passos abaixo.” Está disponível em mais de 170 projetos e é liberado com o Premium; nos projetos grátis, esta seção também aparece com o Premium. Se você não faz ideia do que está quebrado, este é o lugar para percorrer do começo ao fim.
• Entenda o código > Se precisar de ajuda: pares de sintoma e solução específicos do código e do circuito daquele projeto. Aberto a todos nos projetos grátis e com o Premium nos projetos Premium. Se você consegue escrever o seu sintoma em uma frase, olhe aqui primeiro. A seção inteira é explicada no post Entenda o código.
• Volte aos passos do Vamos montar juntos: no modo guiado, volte a 2. Monte o circuito e refaça o circuito do zero com o cabo USB da placa desconectado; em 3. Carregue o código, confira de novo a placa e a porta no menu Ferramentas da Arduino IDE. O modo lembra o passo em que você estava. Como ele funciona está explicado em seu primeiro projeto Arduino.
• Amplie o esquema do circuito: faça o gesto de pinça para ampliar o Esquema do circuito e compare a sua montagem conexão por conexão; se quiser, salve-o com Salvar na galeria e marque os fios que já conferiu. Isso pega a maioria das falhas da camada 3.
• Faça a pergunta certa no fórum: se você tentou tudo isso e ainda não funciona, abra um tópico na categoria Pergunta em Aprender › Fórum. Informe a placa, o código completo, as conexões, o comportamento esperado e o real e quais camadas você já verificou, e adicione uma foto nítida do circuito. Como escrever está em como perguntar no fórum.

Consulta rápida por sintoma

Para professores: checklist de diagnóstico de 8 pontos

Imagine uma turma de 24 alunos com 8 grupos montando circuitos ao mesmo tempo e, nos primeiros 15 minutos, seis grupos levantando a mão para dizer “não funciona”. Coloque o checklist abaixo na mesa de cada grupo e defina a regra desde o início: antes de levantar a mão, o grupo percorre o cartão de cima para baixo e escreve no verso em que ponto travou e o que mudou. Isso libera o seu tempo e cria nos alunos o hábito de resolver problemas; as anotações de diagnóstico também são evidências do processo que você pode usar na avaliação. Para organizar os grupos em uma turma grande, veja como ensinar Arduino a uma turma grande e, para avaliar o processo, a rubrica de avaliação.

1. Sintoma: o que esperávamos e o que acontece? Escreva em uma frase.
2. Alimentação: o LED ON está aceso? Desconecte o USB: alguma peça está quente?
3. Carregamento: o carregamento terminou sem erros? Placa e porta estão certas no menu Ferramentas?
4. Placa: depois de carregar o Blink, o LED L da placa pisca?
5. Ligações: amplie o esquema do circuito e conte cada fio nas duas pontas. O GND é comum? Os fios estão no pino certo e na fileira certa?
6. Peça: a perna longa do LED vai para o pino? As faixas do resistor batem com o valor da lista de peças? VCC e GND estão certos no módulo?
7. Código: os números dos pinos no código batem com o circuito? Quando você mostra pontos de verificação no Monitor Serial, qual aparece por último?
8. Sensor e próximo passo: o valor do sensor no Monitor Serial faz sentido e muda quando as condições mudam? Se ainda não resolveu, confira Se precisar de ajuda e Solução de problemas e só então chame o professor. Mude uma coisa por vez e faça anotações.

Diagnosticar falhas é uma habilidade, e ela fica mais rápida a cada falha: uma busca que leva 20 minutos no seu primeiro projeto cai para 3 minutos no quinto, porque você começa a adivinhar a camada pelo sintoma. Da próxima vez que um projeto não funcionar, abra esta ordem antes de puxar qualquer fio e siga de cima para baixo. Projetos pequenos como a luz noturna deste post são ideais para praticar; no app BlueGrays, cada um dos 60 projetos grátis vem com esquema do circuito, código e a seção Entenda o código, então na próxima falha você já vai saber onde olhar.