Código Arduino explicado paso a paso: entenderlo y modificarlo

Entender el código es la pestaña de la sección Código Fuente de cada página de proyecto de BlueGrays que explica paso a paso el código de Arduino ya hecho. Para descubrir qué hace de verdad el código que copiaste y subiste, sigue este orden: primero lee el resumen ¿Qué hace este código?, luego busca en el código completo cada fragmento de la sección Paso a paso junto con su explicación, mira Si te atascas si el circuito no se comporta como esperabas y, por último, usa la tarea Pruébalo tú para cambiar una sola cosa del código y ver el resultado en la placa. Estas cuatro secciones son el camino más corto entre «funciona, pero no sé por qué» y «sé qué pasa si cambio esta línea».

En este artículo recorremos Entender el código de principio a fin con el contenido real de un proyecto real: el proyecto número 10, Encender y apagar un LED con un botón. Es gratuito, de nivel Principiante y además tiene vista de bloques, así que cualquiera puede abrir la explicación tanto del código como de los bloques. Encontrarás las secciones de la pestaña, un método para emparejar el código con la explicación, una rutina de estudio de 15 minutos, una estrategia para resolver las tareas Pruébalo tú, qué cambio enseña cada concepto, la vista Entiende los bloques, la diferencia entre Si te atascas y Solución de problemas, e ideas para docentes que quieran usarlo en clase.

¿Dónde está Entender el código y quién puede usarlo?

Cuando abres un proyecto y bajas hasta la sección Código Fuente, verás arriba un selector con dos pestañas: Código y Entender el código. La pestaña Código muestra el programa completo y ahí están los botones Copiar y Copiar enlace. Si pasas a Entender el código, se abre la versión comentada del mismo programa. Cada uno de los 200+ proyectos tiene esta pestaña, y funciona igual en los proyectos de Arduino, ESP32 y Raspberry Pi Pico. La regla de acceso es sencilla: en los 60 proyectos gratuitos (20 por plataforma), Entender el código está abierto para todos; incluso con una cuenta gratuita ves el resumen, todos los pasos, Si te atascas y la tarea Pruébalo tú con su solución. En los proyectos Premium aparece una tarjeta de bloqueo en lugar de la pestaña: «Desbloquea con Premium la explicación del código paso a paso.» Es decir, puedes aplicar el método de este artículo en Parpadeo de LED, Semáforo, Luces de policía LED y los proyectos con botón sin pagar nada.

Las secciones: para qué sirve cada una

El orden de las secciones es intencionado: primero la idea general, luego las piezas, después los errores y al final tu propio experimento. Los fragmentos no son el programa entero, solo las líneas que explica ese paso; la llave de cierre de un bloque abierto en un paso puede aparecer en el siguiente. Por eso rinde más leer todos los pasos en orden que mirar solo uno. La pista está visible justo debajo del texto de la tarea, mientras que la solución sigue oculta hasta que tocas Ver solución. Así tienes espacio para pensar antes de ver la respuesta.

Ejemplo: Entender el código en el proyecto Encender y apagar un LED con un botón

El proyecto usa un pulsador y un LED. Un lado del pulsador va a 5V y el lado opuesto al pin 13 de la placa; ese mismo pin se lleva a GND con una resistencia de 10 kΩ. La pata larga del LED va al pin 7 y la corta a GND a través de una resistencia de 330 Ω. El resumen de Entender el código describe el programa así: cada vez que pulsas el botón, el LED invierte su estado una vez, se enciende si estaba apagado y se apaga si estaba encendido; aunque mantengas el botón pulsado, el LED cambia solo una vez, y una espera de 50 ms ignora los rebotes del botón. Aquí tienes el programa completo, con comentarios en dos 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}

Al leer los pasos, fíjate en que la explicación no solo te dice qué pasa, sino también qué pasaría sin esa línea. El paso 1 recuerda que ledState empieza en 0 y que por eso el LED está apagado al encender la placa. De ahí sale una buena pregunta: si lo pones en 1, ¿el LED arranca encendido? No, porque esa línea solo cambia la variable; setup() no escribe nada en el LED, así que empieza apagado, y en la primera pulsación ledState vuelve a 0, de modo que sigue apagado. El valor de una variable y el estado real de un pin son cosas distintas. El paso 2 relaciona el uso de INPUT en el botón con la resistencia de 10 kΩ del circuito: cuando no pulsas, la resistencia lleva el pin a GND y se lee 0. Si quitas la resistencia, el pin queda al aire y lee valores aleatorios; el síntoma «el LED se enciende y apaga solo» de Si te atascas corresponde justo a eso.

Los pasos 3 y 5 hay que leerlos juntos. La comparación del paso 3 solo funciona si lastButton se actualiza después de cada cambio, y esa actualización es la línea lastButton = button del paso 5. Al emparejar los dos pasos aparece la idea central del programa: el código no mira si el botón está pulsado, sino si su estado ha cambiado. Mientras lo mantienes pulsado, cada vuelta lee 1, pero lastButton también vale 1, la comparación es falsa y el LED no cambia. El operador ! del paso 4 es un interruptor de encendido y apagado en dos líneas. El paso 5 termina con un aviso: si la espera es demasiado corta, el LED puede cambiar a veces más de una vez por pulsación. Eso te sugiere un primer experimento antes de la tarea: baja 50 a 5, pulsa varias veces y observa si el LED cambia dos veces de vez en cuando; el resultado depende de la calidad del botón. Para saber más sobre el antirrebote, lee cómo conectar un pulsador a Arduino.

La sección Si te atascas de este proyecto recoge cinco síntomas: el LED no se enciende nunca; el LED cambia solo sin tocar el botón; al pulsar no pasa nada; el botón se comporta como si estuviera siempre pulsado; el código no se sube. Cada síntoma viene con una comprobación concreta. Para «siempre pulsado», por ejemplo, explica que si las patas del pulsador están colocadas en la dirección equivocada, D13 queda conectado a 5V todo el tiempo y debes girar el pulsador 90 grados. La tarea Pruébalo tú es esta: que el LED cambie al soltar el botón y no al pulsarlo. La pista recuerda que la variable button pasa a 1 en el momento de pulsar y a 0 en el momento de soltar. La solución es un cambio de un solo carácter: la línea if (button == 1) pasa a ser if (button == 0). Esta pequeña tarea comprueba si de verdad entendiste la detección de flanco del paso 3.

Método de lectura: resumen, emparejar, probar

1. Lee el resumen y escríbelo en una frase: Lee ¿Qué hace este código? y luego escribe el programa en una frase en tu cuaderno sin mirar el móvil. Para el proyecto del botón: «Cada pulsación enciende o apaga el LED una vez».
2. Empareja el código con los pasos de arriba abajo: Abre el código en el Arduino IDE (Copiar enlace en Código Fuente lo facilita), busca el fragmento de cada paso en el código completo y añade el número de paso junto a la línea como comentario. Los pasos siguen el orden del código: variables globales, setup(), loop().
3. Marca las líneas sin pareja: Si queda una línea que no aparece en ningún paso (normalmente solo quedan llaves de cierre), piensa por qué no se explica; si no es una llave, búscala de nuevo en las explicaciones.
4. Pruébalo en el circuito: Sube el código y prueba una a una las conductas del resumen. En el proyecto del botón bastan tres pruebas: una pulsación, mantenerlo pulsado y pulsaciones rápidas seguidas. Antes de cada prueba, di en voz alta qué va a pasar.

Emparejar es el paso que más se salta y el que más aporta. Cuando escribes los números de paso junto a las líneas, el esqueleto del código se hace visible: qué línea se ejecuta una vez y cuál sin parar, dónde se lee cada variable y dónde se escribe. En el proyecto del botón, lastButton aparece en dos sitios: se declara en el paso 1 y se actualiza en el paso 5. Verlo con tus propios ojos se queda mucho mejor que leer «una variable es una caja». Si quieres estudiar aparte variables, bucles y funciones, lee fundamentos de programación de Arduino.

Rutina de 15 minutos con Entender el código

Esta rutina es para un proyecto con el circuito ya montado. Si montas el circuito por primera vez, dale 10–15 minutos más o deja la rutina para el día siguiente. Los dos últimos minutos son la parte más valiosa: hacer tu propio pequeño cambio después de ver la solución pone a prueba la idea que entendiste, no la respuesta que memorizaste. En el proyecto del botón podrías, por ejemplo, pasar el LED a otro pin o subir la espera de 50 ms a 300 ms y ver qué pasa con las pulsaciones rápidas. Un proyecto al día a este ritmo significa terminar en una semana cinco proyectos gratuitos entendiéndolos de verdad. Si quieres un plan más largo, mira la hoja de ruta de 30 días para Arduino.

Estrategia para resolver las tareas Pruébalo tú

Las tareas Pruébalo tú son cortas pero están elegidas con cuidado: cada una pide un único cambio y el resultado se ve o se oye. Mantener este orden al resolverlas duplica lo que aprendes:

1. Predice: Lee la tarea y di primero qué línea vas a tocar y qué verás después del cambio. Escribir la predicción evita luego la ilusión de «ya lo sabía».
2. Cambia: Cambia una sola cosa. Si cambias dos líneas a la vez, no sabrás qué cambio produjo qué.
3. Sube: Sube el código a la placa y espera el mensaje que indica que la subida terminó. Si aparece un error de compilación, revisa el punto y coma y los paréntesis de la línea que cambiaste.
4. Observa: Compara el resultado con tu predicción. En las tareas de tiempo cuenta los segundos; en las de sonido escucha el sonido antiguo y el nuevo uno detrás de otro.
5. Mira la pista: Si tu predicción falló o no encuentras qué línea tocar, lee la pista. Como está visible justo debajo de la tarea, taparla con la mano en la primera lectura ayuda.
6. Abre la solución al final: Toca Ver solución solo después de tu propio intento. Si coincide con la tuya, piensa por qué es correcta; si es distinta, piensa por qué los dos caminos dan resultados diferentes.

Otra ventaja de este orden es que convierte los errores en aprendizaje. Imagina que en la tarea del proyecto Semáforo quieres alargar a 1,5 segundos el amarillo que va después del verde, pero cambias por error la primera línea delay(300). En lugar de lo que esperabas, verás que se alarga el amarillo que va después del rojo. Ese error te enseña mucho mejor que la solución que el código tiene dos fases amarillas distintas y que loop() se ejecuta línea por línea. La solución de la tarea lo dice así: la línea delay(300) del final de loop() pasa a ser delay(1500), y el amarillo después del rojo se queda en 0,3 segundos.

Tipos de cambio: ¿qué concepto enseña cada uno?

Si miras las tareas de los proyectos gratuitos, verás que cada una pertenece a uno de pocos tipos. Reconocer el tipo también te ayuda a plantearte tu propia tarea en un proyecto nuevo. Los ejemplos de la tabla salen de tareas Pruébalo tú reales de proyectos gratuitos; la fila de cambiar un pin es un experimento que puedes hacer tú en el mismo proyecto.

Entiende los bloques: la misma explicación con bloques

Los proyectos con vista de bloques tienen el interruptor Ver en bloques en la sección Código Fuente. Al activarlo, el mismo programa aparece como bloques en el idioma de la app en lugar de como código, y la pestaña de al lado pasa de Entender el código a Entiende los bloques. En esta vista, el resumen, Si te atascas y la tarea no cambian; lo que cambia es la sección Paso a paso: cada paso muestra sus propios bloques en lugar del fragmento de código, y al tocar la imagen se abre a pantalla completa. Más de 100 proyectos tienen vista de bloques, entre ellos más de 30 de los gratuitos. Los bloques son solo para leer; en la app no se editan ni se suben a la placa, y a la placa siempre va el código real.

La mejor forma de usar Entiende los bloques es alternar entre las dos vistas. En el proyecto del botón, los bloques del paso 3 son un bloque «establecer button a leer pin 13» y dos bloques «si» anidados; en código son la línea int button = digitalRead(13); y dos if anidados. El bloque «establecer ledState a no ledState» del paso 4 es exactamente la línea ledState = !ledState;. Lee primero el bloque y di qué hace, luego desactiva el interruptor y mira el fragmento de código del mismo paso. Emparejar bloques y código así es la manera más sólida de pasar de la programación por bloques al código en texto; si quieres empezar el tema desde el principio, lee qué es la programación por bloques y el artículo sobre el bloque si.

Si te atascas frente a Solución de problemas

En la práctica, el orden es este: cuando el circuito no funciona, describe el síntoma en una frase y búscalo en Si te atascas. Si tu síntoma aparece, la solución suele ser un solo cable, una resistencia o una línea. Si no aparece, o la solución propuesta no ha servido, recorre en orden los pasos de Solución de problemas; es probable que encuentres una comprobación básica que te saltaste (alimentación de la placa, puerto correcto, GND común). Si te atascas al subir el código, te ayudará Arduino no sube el código, y para los errores de compilación, errores de compilación de Arduino.

Para docentes: usar Entender el código en clase

• Lectura compartida con el proyector: Al empezar la clase, proyecta la pantalla del móvil, leed juntos el resumen ¿Qué hace este código? y pide a la clase que resuma el programa en una frase. Luego muestra los mismos pasos con Ver en bloques activado; para quienes empezaron con bloques, es un puente.
• Un grupo por paso: En un proyecto de 5 pasos, divide la clase en 5 grupos; cada grupo lee un paso, busca el fragmento en el código completo y lo explica a la clase en dos minutos. Mientras un grupo explica, los demás preguntan «¿qué pasaría sin esta línea?».
• Papel de predicción: Escribe la tarea Pruébalo tú en la pizarra; cada grupo anota su predicción en un papel antes de hacer el cambio, y después cambia el código y lo sube. Comentar la diferencia entre predicción y resultado enseña más que hacer la tarea.
• Pregunta de salida: En los dos últimos minutos de la clase, todos responden una pregunta. Ejemplos para el proyecto del botón: ¿qué pasaría al mantener pulsado el botón si no existiera lastButton? ¿Qué cambia si borras delay(50)? ¿Por qué el LED puede cambiar solo si quitas la resistencia de 10 kΩ?

Para planificar el acceso, ten en cuenta esto: como Entender el código está abierto para todos en los proyectos gratuitos, tu alumnado puede aplicar este método con Parpadeo de LED, Semáforo, Luces de policía LED y los dos proyectos con botón sin pagar nada. En los proyectos Premium, Entender el código se desbloquea con Premium; si quieres pasar con la clase a proyectos Premium, puedes repartir códigos de los paquetes para educadores en lugar de que cada estudiante se suscriba, como explicamos en una app de Arduino para la clase. Si quieres compartir un circuito diseñado por ti, puedes abrir un tema de Tutorial en el Foro; no incluye pasos de Entender el código ni vista de bloques, así que la explicación la escribes tú en el texto del tema y añades el código con Añadir código (dar clase con tu propio proyecto). La app tampoco tiene un panel que te muestre qué tareas resolvió cada estudiante; compruebas la tarea en clase, mirando el circuito en funcionamiento o con una foto.

Errores frecuentes y soluciones fáciles

• Abrir la solución enseguida: Si tocas Ver solución nada más leer la tarea, aprendes la respuesta pero no la idea. La regla: primero predicción, luego intento, después pista y la solución al final.
• Copiar sin leer los pasos: Coger el código con Copiar y subirlo funciona, pero si pasas al siguiente proyecto sin leer Paso a paso, empiezas de cero cada vez. Después de subirlo, lee al menos el resumen y los pasos.
• Confundir un fragmento con el programa entero: Los fragmentos son solo las líneas de ese paso; si pegas uno solo en el IDE, no compila. Haz los cambios siempre en el código completo.
• Cambiar varias cosas a la vez: Si cambias dos líneas juntas y el resultado te sorprende, no sabrás cuál es la responsable. Un cambio por cada subida.
• Cambiar el número de pin en un solo sitio: Cambiar pinMode y olvidar digitalWrite o el cable es uno de los errores más comunes. Antes de cambiarlo, marca todos los sitios del código donde aparece el número.
• Saltarse Si te atascas y preguntar enseguida en el foro: La respuesta suele estar ya en la lista Si te atascas de ese proyecto. Mira primero ahí, luego en Solución de problemas; si sigue sin resolverse, pregunta en el foro con una foto del circuito y tu código.
• Terminar la tarea y quedarse ahí: Si después de comparar con la solución no haces tu propio pequeño cambio, lo aprendido queda atado a esa tarea. Elige tú un número, un pin o una condición.

Cuando hayas usado Entender el código en este orden en unos cuantos proyectos, el código ya hecho deja de ser una caja cerrada: podrás decir de antemano qué línea controla qué y qué pasará si la cambias. Encender y apagar un LED con un botón es un buen punto de partida para este hábito, porque un código corto muestra a la vez una variable global, la detección de flanco, el toggle y el antirrebote. Si quieres probarlo, abre este proyecto en la app BlueGrays y empieza por la tarea de la pestaña Entender el código; las mismas secciones están en los 60 proyectos gratuitos.