Mi proyecto Arduino no funciona: diagnóstico en 10 minutos

Si tu proyecto Arduino no funciona, no busques el fallo quitando y poniendo cables al azar. Ve de fuera hacia dentro: primero la alimentación (¿enciende la placa?), luego la carga (¿el código llegó de verdad a la placa?), después el cableado (¿la GND es común, cada cable está en el pin correcto?), luego la orientación y el valor de las piezas (¿el LED está al revés, la resistencia es la correcta?), después el código (números de pin y lógica) y por último el sensor y el entorno (luz, distancia, tensión de alimentación). Haz una sola prueba por capa y cambia solo una cosa cada vez. Siguiendo este orden encontrarás la mayoría de las averías en 10 minutos, porque los errores más comunes están en las capas exteriores, y son las más baratas de comprobar.

Este artículo no enumera mensajes de error sueltos: te da un método de diagnóstico. Primero verás las dos reglas del método y luego una tabla de flujo con el síntoma, una prueba de 1 minuto y la causa probable de cada capa. Después vienen un sketch de prueba corto que divide el circuito en partes con Blink y el monitor serie, 4 mediciones con multímetro (y sus alternativas con LED y monitor serie si no tienes uno), el diagnóstico paso a paso de una avería en un proyecto gratuito de BlueGrays, una tabla rápida por síntoma y una lista de diagnóstico de 8 puntos para la clase.

Las dos reglas del diagnóstico: de fuera hacia dentro y una sola variable

La lógica de ir de fuera hacia dentro es sencilla: las capas interiores dependen de las exteriores. Si la placa no recibe alimentación, da igual que el código esté bien; si el código nunca llegó a la placa, corregir el cableado no cambia nada. Además, las capas exteriores son las más rápidas de comprobar: mirar el LED de encendido lleva 5 segundos y leer el mensaje de carga 10, pero encontrar un error de lógica en el código puede llevar minutos. La segunda regla es la de una sola variable. Si cambias a la vez el cable, la resistencia y el umbral del código, no sabrás qué lo arregló aunque el proyecto empiece a funcionar; y si no funciona, puede que hayas añadido un fallo nuevo. Haz un cambio, prueba, anota el resultado y pasa al siguiente.

• Escribe el síntoma en una frase: "Cuando tapo la LDR con la mano espero que el LED se encienda, pero nunca se enciende." "No funciona" no es un síntoma; al escribir por separado lo que esperabas y lo que pasa, la capa que hay que revisar suele quedar clara por sí sola.
• Desconecta el USB mientras cableas: Si la placa sigue alimentada mientras cambias conexiones, un contacto equivocado puede provocar un cortocircuito. Haz el cambio, revísalo a simple vista y vuelve a conectar.
• Cambia por una pieza que sabes que funciona: Sustituir el LED, el cable o el sensor sospechoso por uno que sabes que funciona es la prueba más potente que puedes hacer sin instrumentos.
• Toma notas: Notas cortas como "pasé el cable del 7 al 8, sin cambios" evitan que repitas la misma prueba y te sirven de resumen si preguntas en un foro o a tu docente.
• Simplifica: Si el proyecto es grande, quita los módulos uno a uno. Primero solo la placa, luego la placa con la parte de salida y después la parte de entrada. Ver al añadir qué pieza deja de funcionar te muestra dónde está la avería.

Tabla de flujo para un diagnóstico en 10 minutos

Lee la tabla de arriba abajo y no bajes a la siguiente capa hasta que la prueba de la actual haya salido bien. Cada prueba lleva un minuto aproximadamente, así que las seis capas se terminan en 6–10 minutos. Para la mayoría de las pruebas bastan tus ojos, los LED de la placa y el monitor serie del Arduino IDE; un multímetro acelera las cosas, pero no es obligatorio. La columna "Causa probable" indica los primeros sitios donde mirar cuando falla una prueba, más o menos en orden de frecuencia.

Capas 1 y 2: alimentación y carga

En un Arduino Uno, dos LED te dan la primera pista para estas dos capas. El LED ON indica que la placa recibe alimentación; si está apagado, cambia primero el cable USB, porque algunos cables solo cargan y no transmiten datos. Si ON está encendido pero el sonido USB del ordenador se corta al conectar o el LED parpadea, puede haber un cortocircuito en el circuito: desconecta el USB, sigue las líneas de 5V y GND y busca un módulo conectado al revés o un cable que una las dos líneas. Una pieza que se calienta siempre es una señal seria; no vuelvas a alimentar la placa hasta quitarla. Si usas un motor, un servo o un relé, puede que la corriente del USB no baste; en ese caso el síntoma no suele ser "no funciona nada", sino reinicios aleatorios o temblores. Para alimentar con pilas o adaptador, consulta alimentar Arduino con pilas.

En la capa de carga buscas la respuesta a una sola pregunta: ¿el código que hay en la placa es el que ves en la pantalla? Al terminar la carga, el Arduino IDE lo indica en el área de salida inferior; si aparecen líneas rojas, el código nunca llegó a la placa y esta sigue ejecutando su programa anterior. Es una trampa, porque pensarás que tu corrección no ha funcionado. Para los errores de avrdude, puerto y driver, Arduino no sube el código explica cada mensaje, y si te atascas al compilar, mira errores de compilación. También hay una prueba sencilla: cambia una espera del código de 100 a 1000 y súbelo. Si el ritmo del LED no cambia, el problema está en la carga. Algunas placas ESP32 piden mantener pulsado el botón BOOT durante la carga; en la Raspberry Pi Pico, comprueba que el intérprete MicroPython esté seleccionado en la esquina inferior derecha de Thonny.

Capa 3: cableado, GND y pines

Con la placa alimentada y el código cargado, les toca a los cables. Los dos errores más frecuentes son olvidar la GND común y leer mal la protoboard. Aunque un sensor o un módulo tenga su propia alimentación, su GND debe ir a la GND del Arduino; si no, la tensión de la señal no tiene referencia. En la protoboard, el canal central separa las dos mitades, y en las protoboards largas las líneas de alimentación de los bordes pueden estar cortadas por la mitad; dar 5V a una mitad y creer que alimentas una pieza de la otra es un error muy común. El mejor método en esta capa es comparar uno a uno con el diagrama: cuenta cada cable con sus dos extremos y señala con el dedo su correspondiente en el diagrama. Confundir el digital 2 con el analógico A2, 5V con VIN o un cable desplazado una fila aparece enseguida en este recuento. Si los símbolos te resultan extraños, cómo leer un esquema eléctrico explica paso a paso cómo pasarlo a la protoboard.

Capa 4: orientación y valor de las piezas

Si el cableado está bien pero una pieza sigue sin responder, mira la pieza en sí. La pata larga del LED (ánodo) va a través de la resistencia al pin y la corta (cátodo) a GND; un LED al revés normalmente no se daña, simplemente no se enciende. Las resistencias son las piezas que más se confunden: la de 220 Ω tiene bandas rojo-rojo-marrón y la de 10 kΩ marrón-negro-naranja. Si pones 10 kΩ junto al LED, brillará tan poco que no lo notarás; si pones 220 Ω junto a una LDR o un pulsador, las lecturas dejan de tener sentido. Puedes leer las bandas con la calculadora de código de colores y encontrar el valor adecuado para un LED con la calculadora de resistencia para LED. Un pulsador de cuatro patas girado 90 grados parecerá siempre pulsado o nunca pulsado. En los módulos, el orden de VCC, GND y señal cambia según el fabricante; lee las etiquetas de los pines en la propia placa, no en una imagen de internet. En piezas de tres patas como transistores y reguladores de tensión, el orden de las patas también cambia según el modelo.

Capa 5: código (números de pin y lógica)

Si el hardware está bien, comprueba que el código dice lo mismo que el circuito. Lo primero son los números de pin: si el LED está físicamente en el 8 pero el código dice digitalWrite(9, HIGH), todo parece perfecto y no pasa nada. Lo segundo es pinMode: si falta pinMode(pin, OUTPUT) en setup(), digitalWrite(pin, HIGH) no convierte el pin en salida, solo activa la resistencia pull-up interna, y el LED brilla muy débilmente. Aparte de la resistencia, es la causa más frecuente de un "LED tenue". Lo tercero es la lógica: escribir if (valor = 100) no compara nada, asigna 100 a la variable y la condición siempre es verdadera; lo correcto es ==. Los umbrales y las esperas también pertenecen a esta capa: un umbral que no encaja con tu entorno hace que nada se active, aunque el sensor funcione perfectamente. En proyectos con librerías, comprueba también que esté instalada la correcta; los detalles están en instalar librerías en Arduino.

Capa 6: sensor y entorno

La última capa son las condiciones externas que estropean el resultado aunque el circuito y el código estén bien. El valor de una LDR depende de la luz de la habitación; un umbral que funciona junto a la ventana de día puede fallar por la noche bajo una lámpara. Un HC-SR04 no recibe eco de superficies blandas como la tela y no mide a menos de 2 cm. Los sensores de gas de la serie MQ necesitan unos minutos de calentamiento antes de medir. Un DHT11 da error si lo lees más de una vez por segundo. Los pines del ESP32 y de la Raspberry Pi Pico trabajan a 3,3 V; conectar directamente un sensor con salida de 5 V puede dar lecturas erróneas y dañar el pin. Los cables largos, el ruido de los motores y las entradas al aire también hacen que los valores salten. La mejor herramienta en esta capa es el monitor serie: observa el valor en bruto del sensor y cambia las condiciones a propósito. Si una pantalla o un sensor I2C no responde en absoluto, el sketch escáner de qué es I2C muestra su dirección.

Divide y vencerás: comprueba la placa con Blink y los pasos con el monitor serie

La forma más rápida de recorrer las capas es dividir el circuito y el código en partes. La primera parte es la propia placa: sin nada conectado, sube un código que haga parpadear el LED L de la placa. Si L parpadea, la alimentación, la carga y la placa están bien, y a partir de ahí buscas el problema fuera de la placa. La segunda parte es la salida: haz parpadear también el LED externo en el mismo código. La tercera es la entrada: imprime el valor del sensor en el monitor serie. El sketch de abajo hace las tres cosas y escribe un punto de control numerado en el monitor serie en cada paso. Conecta el LED externo al pin 9 con una resistencia de 220 Ω y la señal del sensor analógico que quieras probar a A0, y pon el monitor serie a 9600 baudios.

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}

La verdadera fuerza de este sketch son sus puntos de control. Usa el mismo método en tu proyecto: añade un Serial.println() corto al final de setup() y después de cada paso importante de loop(), por ejemplo "boton pulsado" o "umbral superado". El último mensaje que aparece en el monitor serie te dice dónde se ha atascado el programa. Para saber por qué una condición no se cumple nunca, imprime justo antes el valor que comparas; si "valor < 50" nunca es verdadero, verás ahí mismo que el valor nunca baja de 50. En proyectos grandes, aplica la misma lógica: comenta temporalmente una parte del código y prueba las piezas una a una. Para ajustes del monitor serie como los baudios, el fin de línea y el trazador, consulta cómo usar el monitor serie de Arduino.

4 mediciones con multímetro (o con LED y monitor serie si no tienes)

Un multímetro convierte el diagnóstico de suposición en medición, y solo cuatro medidas cubren la mayoría de las averías de Arduino. Antes de medir, pon el aparato en el modo adecuado: V de continua para tensión, pitido (continuidad) para cables y filas, Ω para resistencias. Haz siempre las pruebas de continuidad y de resistencia con el USB desconectado. Si no tienes multímetro, los métodos de la última columna dan una respuesta más tosca pero suficiente a la misma pregunta. Los rangos del aparato y dónde van las puntas se explican con imágenes en cómo usar un multímetro.

Ejemplo: el LED no se enciende en el proyecto Luz nocturna con LDR

Probemos el método con un proyecto gratuito de BlueGrays: Luz nocturna con LDR. En el circuito, un extremo de la LDR va a 5V y el otro a A0; entre A0 y GND hay una resistencia de 10 kΩ, y ambas forman un divisor de tensión. El LED va al pin 13 a través de una resistencia de 330 Ω. El código lee A0 y, si el valor es menor que 50, considera que está oscuro y enciende el LED. El síntoma: "Tapo la LDR con la mano y el LED no se enciende nunca." En lugar de cambiar cables al azar, recorramos las capas en orden.

1. Alimentación: El LED ON está encendido y nada se calienta. Siguiente.
2. Carga: La carga terminó sin errores. Para asegurarte, cambia temporalmente el 50 del código por 2000 y súbelo; como analogRead devuelve como máximo 1023, la condición siempre se cumple y el LED debería quedarse encendido.
3. Cableado y LED L: El pin 13 también está conectado al LED L de la placa. Si con el umbral 2000 se enciende L pero no el LED externo, el código funciona y el problema está en el camino del LED. ¿La pata larga del LED va al 13 a través de 330 Ω y la corta a GND?
4. Orientación y valor: El LED no está al revés, pero si a su lado hay 10 kΩ en lugar de 330 Ω, brilla demasiado poco para notarlo. Distingue las dos resistencias por sus colores.
5. Código y sensor: Si el LED externo se enciende con el umbral 2000, vuelve a ponerlo en 50. Ahora, para ver los valores reales, sube al mismo circuito el código del proyecto Medir la intensidad de luz con LDR; usa el mismo cableado de la LDR y escribe A0 en el monitor serie cada medio segundo.
6. Lee los valores: Supongamos que ves unos 600 al descubierto y unos 120 al taparla con la mano. El valor nunca baja de 50, así que el LED nunca se enciende. Vuelve al código de la luz nocturna y sube el umbral a un valor entre 200 y 300.
7. Detecta el comportamiento invertido: Si al taparla el valor sube en lugar de bajar, la LDR y la de 10 kΩ están intercambiadas. Si el valor salta al azar con la mano quieta, el cable de A0 no está bien metido en la fila donde se unen la LDR y la resistencia.

En este ejemplo, lo que encontró la avería no fue un conocimiento nuevo, sino el orden: primero demostramos que el LED podía encenderse y luego miramos qué leía realmente el sensor. En la app, la sección Si te atascas de la pestaña Entender el código de este mismo proyecto ya recoge cinco de estos síntomas como pares de síntoma y solución: el LED externo no se enciende nunca a oscuras, el LED se enciende con luz y se apaga a oscuras, no se enciende ni tapándolo con la mano, se queda encendido o parpadea, y un error de carga. La sección Solución de problemas del proyecto ofrece una lista general de 10 pasos que empieza por la alimentación y sigue con la carga, los números de pin, la protoboard, los cables puente, la GND, el LED y la resistencia. Como habrás notado, ese orden es casi el mismo que el de las capas del principio de este artículo.

Ayuda en la app: dónde mirar cuando un proyecto no funciona

• Solución de problemas: Una lista ordenada en la página del proyecto que empieza con "Si su proyecto no funciona, revise los siguientes pasos." Está en más de 170 proyectos y se abre con Premium; en los proyectos gratuitos esta sección también se ve con Premium. Si no tienes ni idea de qué falla, es el sitio para revisarlo todo de principio a fin.
• Entender el código > Si te atascas: Pares de síntoma y solución propios del código y el circuito de ese proyecto. Abierto a todos en los proyectos gratuitos y con Premium en los proyectos Premium. Si puedes escribir tu síntoma en una frase, mira aquí primero. Toda la sección se explica en el artículo Entender el código.
• Vuelve a los pasos de Hagámoslo juntos: En el modo guiado, regresa a 2. Monta el circuito y monta el circuito de nuevo con el cable USB de la placa desconectado; en 3. Sube el código, revisa otra vez la placa y el puerto en el menú Herramientas del Arduino IDE. El modo recuerda el paso en el que estabas. Cómo funciona se explica en tu primer proyecto Arduino.
• Amplía el diagrama del circuito: Amplía con dos dedos el Diagrama de Circuito y compara tu cableado conexión por conexión; si quieres, guárdalo con Guardar en Galería y marca los cables que ya revisaste. Así se detectan la mayoría de los fallos de la capa 3.
• La pregunta correcta en el foro: Si lo has probado todo y sigue sin funcionar, abre un tema en la categoría Pregunta en Aprende › Foro. Indica la placa, el código completo, las conexiones, el comportamiento esperado y el real y qué capas has revisado, y añade una foto clara del circuito. Cómo redactarlo está en preguntar en el foro.

Consulta rápida por síntoma

Para docentes: una lista de diagnóstico de 8 puntos

Supongamos que tienes una clase de 24 con 8 grupos montando circuitos a la vez y en los primeros 15 minutos seis grupos levantan la mano diciendo "no funciona". Pon la lista de abajo en la mesa de cada grupo y deja clara la regla desde el principio: antes de levantar la mano, recorred la tarjeta de arriba abajo y escribid en el reverso en qué punto os habéis atascado y qué habéis cambiado. Así ganas tiempo y el alumnado adquiere hábitos de resolución de problemas; además, las notas de diagnóstico son una evidencia del proceso que puedes usar en la evaluación. Para organizar grupos en una clase numerosa, consulta clase de Arduino con muchos alumnos, y para calificar el proceso, la rúbrica de evaluación.

1. Síntoma: ¿Qué esperábamos y qué pasa? Escribidlo en una frase.
2. Alimentación: ¿Está encendido el LED ON? Desconectad el USB: ¿hay alguna pieza caliente?
3. Carga: ¿La carga terminó sin errores? ¿Placa y puerto son correctos en el menú Herramientas?
4. Placa: Al subir Blink, ¿parpadea el LED L de la placa?
5. Cableado: Ampliad el diagrama y contad cada cable por sus dos extremos. ¿La GND es común, los cables están en el pin y la fila correctos?
6. Pieza: ¿La pata larga del LED va al pin? ¿Las bandas de la resistencia coinciden con el valor de la lista? ¿VCC y GND están bien en el módulo?
7. Código: ¿Los números de pin del código coinciden con el circuito? Al imprimir puntos de control en el monitor serie, ¿cuál aparece el último?
8. Sensor y siguiente paso: ¿El valor del sensor en el monitor serie tiene sentido y cambia cuando cambian las condiciones? Si sigue sin resolverse, mirad Si te atascas y Solución de problemas, y después llamad al docente. Cambiad una sola cosa cada vez y tomad notas.

Diagnosticar es una habilidad y se vuelve más rápida con cada avería: una búsqueda que en tu primer proyecto lleva 20 minutos baja a 3 en el quinto, porque empiezas a adivinar la capa a partir del síntoma. La próxima vez que un proyecto no funcione, abre este orden antes de quitar cables y avanza de arriba abajo. Los proyectos pequeños como la luz nocturna de este artículo son ideales para practicar; en la app BlueGrays, cada uno de los 60 proyectos gratuitos trae su diagrama de circuito, su código y la sección Entender el código, así que en la próxima avería ya sabrás dónde mirar.