Primeros pasos con MicroPython en la ESP32

Toda placa de microcontrolador empieza de la misma manera: un LED que parpadea. Parece poco, pero detrás de esas dos líneas de código están casi todas las ideas que vas a usar de aquí en adelante: qué es un pin, qué significa "salida", cómo el programa espera a que pase el tiempo y cómo el texto que escribes se convierte en corriente eléctrica en un cable. Este artículo es el mapa del comienzo del camino con MicroPython en la ESP32 DevKit V1, la placa que simula PyPlaca. Vamos a entender qué se ejecuta dentro de la placa, escribir los primeros programas, montar un LED de verdad en la protoboard y, al final, ver cómo llevar el mismo main.py a una ESP32 real.

Todos los números de este texto vienen de la documentación del proyecto (los documentos de hardware y las fichas de cada pieza) o de la documentación oficial de MicroPython. Cuando un valor todavía no se ha medido en una placa del laboratorio, PyPlaca lo avisa, y este artículo también.

Qué es MicroPython

Python es un lenguaje de programación conocido por ser fácil de leer. Normalmente se ejecuta en un computador con gigabytes de memoria y un sistema operativo debajo. MicroPython es una reimplementación de Python 3 hecha para caber en microcontroladores: chips pequeños, con unos pocos cientos de kilobytes de memoria, sin sistema operativo y hechos para conversar con el mundo físico: botones, LEDs, sensores, motores.

La diferencia más importante para quien está empezando es dónde se ejecuta el programa. En Arduino, por ejemplo, escribes C++ en el computador, un compilador lo transforma todo en código de máquina y ese código se graba en la placa. En MicroPython, lo que se graba en la placa una sola vez es el intérprete: el propio MicroPython, en un archivo de firmware. Después de eso, la placa pasa a entender Python. Tú envías archivos de texto (main.py, boot.py y tus módulos) y el intérprete los lee y los ejecuta línea por línea, allí mismo, dentro del chip.

Esto trae dos ventajas enormes para el aprendizaje. La primera es el REPL, el "prompt" >>> que aparece en la terminal serial: escribes una línea de Python y la placa responde al instante. Se puede encender un LED escribiendo Pin(2, Pin.OUT).on() sin guardar ni grabar nada. La segunda es que los errores aparecen en texto, con el número de línea y el tipo del problema, en lugar de que la placa simplemente "no haga nada".

PyPlaca usa como referencia MicroPython v1.29.0, en la versión oficial para la ESP32 común (el firmware ESP32_GENERIC). El simulador reproduce la API, los mensajes de error e incluso los detalles curiosos de esa versión: la idea es que tu main.py funcione igual cuando pase a la placa de verdad.

La placa: ESP32 DevKit V1

La DevKit V1 de 30 pines es una de las placas de ESP32 más comunes en los laboratorios de las escuelas. En el centro está el módulo ESP32-WROOM-32, una cajita de metal con el chip ESP32 (dos núcleos, Wi-Fi y Bluetooth), la memoria flash y la antena dibujada en la propia placa de circuito. Alrededor del módulo, la DevKit añade lo que falta para usar el chip con facilidad: el conector USB, el conversor USB-serial, el regulador de tensión, dos botones y dos LEDs.

Algunos datos sobre la placa que van a aparecer todo el tiempo:

• los pines trabajan con 3,3 V. Un pin en nivel alto queda con 3,3 V; en nivel bajo, con 0 V;
• la tensión máxima que aguanta un pin es 3,6 V. Por encima de eso el chip puede dañarse, y por eso los sensores de 5 V piden cuidado (hay un artículo entero sobre esto en esta serie);
• son 30 pines, 15 de cada lado. No todos son GPIO: están el 3V3, el VIN (los 5 V del USB), dos GND y el EN, que reinicia la placa;
• el LED azul de la placa está conectado al GPIO2. Es el que parpadea el primer programa;
• el botón EN reinicia el chip; el botón BOOT está conectado al GPIO0 y, si se pulsa en el momento de encender, pone la placa en el modo de grabación de firmware;
• con MicroPython, la CPU funciona a 160 MHz (valor comprobado en una DevKit V1 del laboratorio).

Los pines aparecen en la placa con nombres como D2, D18 o D34. El número después de la D es el número del GPIO (General Purpose Input/Output, entrada y salida de uso general), y es ese número el que usa MicroPython. Escribir Pin('D2') no funciona: lo correcto es Pin(2). El mapa de pines de PyPlaca muestra cada uno de los 30 pines con lo que puede hacer y las precauciones de cada uno.

Pines que piden atención

La ESP32 tiene algunas reglas de fábrica que sorprenden a los principiantes. No hace falta memorizarlas ahora, pero conviene saber que existen:

• los GPIO 34 a 39 son solo de entrada: Pin(34, Pin.OUT) da ValueError: pin can only be input. Tampoco tienen resistencia de pull interna;
• los GPIO 6 a 11 los usa la memoria flash del módulo y ni siquiera aparecen en el conector de la DevKit V1 de 30 pines;
• los GPIO 1 y 3 son el puerto serial del REPL. Usarlos como pin común apaga la terminal;
• los GPIO 0, 2, 5, 12 y 15 son pines de strapping: el chip lee su nivel en el instante en que se enciende para decidir cómo arrancar. Conectar cosas que fuercen un nivel en esos pines puede impedir que la placa inicie.

El simulador conoce estas reglas y muestra un aviso didáctico en la pestaña Avisos cuando tu programa o tu circuito choca con una de ellas, incluso en los casos en que la placa real fallaría en silencio.

El primer programa: parpadear el LED del GPIO2

Para controlar un pin, MicroPython usa la clase Pin, que está en el módulo machine (el módulo que reúne todo lo que es específico del hardware). Creamos un objeto indicando el número del pin y el modo: Pin.OUT para salida, Pin.IN para entrada. Después, on() pone el pin en 3,3 V y off(), en 0 V.

from machine import Pin
import time

led = Pin(2, Pin.OUT)   # el LED azul de la DevKit V1

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

print('fin: el LED parpadeó 10 veces')

Haz clic en Abrir en el simulador y después en Ejecutar. El código va al main.py de la IDE libre (lo que estaba antes vuelve con Ctrl+Z) y el LED azul de la placa simulada parpadea diez veces. Abre la pestaña Pines: dibuja el GPIO2 como un analizador lógico, una onda cuadrada que sube y baja cada medio segundo.

Fíjate en tres detalles del código:

1. from machine import Pin trae la clase Pin; import time trae el módulo de tiempo;
2. Pin(2, Pin.OUT) configura el pin una sola vez, fuera del bucle. Llamar de nuevo a Pin(2) devuelve el mismo objeto (así es en el MicroPython de la ESP32), de modo que no hay problema en hacerlo, pero tampoco hay ganancia;
3. led.on() y led.off() tienen equivalentes: led.value(1), led.value(0) y led.toggle(), que invierte el nivel actual. Usa el que deje el programa más legible.

En la placa real, un programa con while True: se ejecuta para siempre, y es lo normal en un microcontrolador, que existe para hacer la misma tarea continuamente. Para detenerlo, pulsas Ctrl+C en la terminal (que genera un KeyboardInterrupt) o reinicias la placa. En el simulador, el botón de detener cumple el mismo papel.

El tiempo en MicroPython

El módulo time tiene tres maneras de esperar, que se diferencian solo en la unidad:

• time.sleep(1) espera en segundos (acepta fracciones, como 0.5);
• time.sleep_ms(500) espera en milisegundos;
• time.sleep_us(100) espera en microsegundos.

Mientras espera, el programa se queda parado en esa línea. Para medir cuánto tiempo ha pasado, MicroPython ofrece un reloj que empieza a contar cuando la placa se enciende: time.ticks_ms(), en milisegundos (también existe time.ticks_us(), en microsegundos). La diferencia entre dos lecturas se calcula con time.ticks_diff(fim, inicio), y no con una resta simple.

import time

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

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

¿Por qué ticks_diff? Porque el contador de ticks da la vuelta: en el MicroPython de la ESP32 cuenta hasta 2^30 milisegundos y vuelve a empezar desde cero, lo que ocurre después de poco más de doce días con la placa encendida. En ese momento, fim - inicio daría un número negativo enorme, mientras que ticks_diff hace la cuenta correcta. Es un hábito que conviene crear desde el primer programa: el tiempo de la placa se compara con ticks_diff y se suma con ticks_add.

La última línea del ejemplo muestra otra diferencia con respecto al Python del computador: la ESP32 usa números de punto flotante de 32 bits. Por eso 10 / 3 aparece como 3.3333332 y no como 3.3333333333333335. Así lo imprimió una DevKit V1 del laboratorio, y el simulador traduce línea a línea el código de MicroPython que formatea los números para mostrar exactamente el mismo texto.

El reloj del simulador

Una pregunta justa: si el simulador se ejecuta en el navegador, ¿cómo sabe cuánto vale medio segundo "en la placa"? PyPlaca mantiene un reloj virtual, el tiempo de simulación que aparece en la parte superior del banco de trabajo. A velocidad 1×, avanza junto con el reloj de verdad. En Turbo, el simulador no espera: el programa termina casi al instante, pero el reloj de la placa sigue contando el tiempo correcto: un ticks_diff después de sleep_ms(250) da 250 en los dos modos. Esto es útil para comprobar programas largos sin quedarse mirando el LED parpadear.

Un LED de verdad en la protoboard

El LED azul de la placa es práctico, pero casi todos los proyectos usan piezas fuera de la placa. El paso siguiente es montar un LED en una protoboard y conectarlo a un GPIO. Antes de conectar cualquier cable, hay que entender dos cosas: el LED y la resistencia.

El LED (diodo emisor de luz) solo deja pasar la corriente en un sentido: del ánodo (la pata más larga, el lado positivo) al cátodo (la pata corta, del lado biselado del cuerpo). Al revés, simplemente no se enciende. Cuando se enciende, mantiene una tensión casi fija entre las patas, la tensión directa (Vf). Para LEDs de 5 mm, los valores típicos son de unos 2,0 V en el rojo, 2,1 V en el amarillo, 2,2 V en el verde y 3,1 V en el azul y en el blanco. La corriente máxima típica es de unos 20 mA.

La resistencia es lo que impide que el LED pida demasiada corriente. Sin ella, lo único que limitaría la corriente serían las resistencias internas del pin y del LED, demasiado pequeñas para proteger a cualquiera de los dos. Con una resistencia en serie, la cuenta es simple: la tensión que sobra en la resistencia es la del pin menos la del LED, y la corriente es esa diferencia dividida por la resistencia (ley de Ohm).

La tabla muestra una sorpresa común: el LED azul, con la misma resistencia de 220 Ω, queda mucho más débil. Con 3,3 V en el pin, solo sobran unos 0,2 V para la resistencia, y la corriente baja a cerca de 1 mA. No es un defecto: es la física del LED. El simulador muestra este efecto y, cuando la corriente queda muy baja, avisa de que el LED está débil.

La protoboard por dentro

La protoboard de 830 puntos es la base de montaje de casi todos los circuitos de la serie. Por dentro, cada columna tiene dos tiras de metal: los cinco agujeros de arriba (a a e) están conectados entre sí, y los cinco de abajo (f a j) también, separados por el canal del medio. En los bordes corren las barras de alimentación + y −, conectadas a lo largo de todo el largo, que suelen llevar la alimentación y el GND. Dos patas insertadas en la misma columna (del mismo lado del canal) están conectadas, aunque no haya ningún cable entre ellas: así es como la resistencia "toca" el LED.

Un detalle práctico de la DevKit V1: es ancha. Encajada sobre una protoboard de 830 puntos, ocupa casi todo el ancho y deja solo una fila libre de uno de los lados. Por eso, en muchos montajes del laboratorio (y del simulador), la placa queda al lado de la protoboard y los pines llegan por cables, o se usan dos protoboards una al lado de la otra.

El circuito de la lección del LED externo hace este camino: del pin D18 (GPIO18) sale un cable hasta la columna de la resistencia de 220 Ω; la otra pata de la resistencia comparte columna con el ánodo del LED; el cátodo queda en una columna propia, conectada por un cable negro a la barra de GND, que a su vez está conectada al GND de la placa. La corriente sale del pin, pasa por la resistencia, por el LED y vuelve por el GND. Si falta cualquier tramo de ese camino, no se enciende nada.

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 ejemplo se abre ya con el circuito montado. Ejecútalo y mira el LED parpadear en la pestaña Circuito. Después, prueba a romper el circuito a propósito: selecciona el cable negro, bórralo con Supr y ejecuta de nuevo. Sin camino hasta el GND, el LED no se enciende, exactamente como en el banco de trabajo. Ctrl+Z trae el cable de vuelta. Cambia también la resistencia de 220 Ω por una de 1 kΩ en el panel de la pieza: la corriente baja a cerca de una quinta parte y el LED queda más débil.

Errores que el simulador ayuda a encontrar

Montar circuitos es la parte en la que más se falla al principio, y casi siempre por los mismos motivos. PyPlaca verifica el circuito y muestra avisos con el nombre del problema:

• LED sin resistencia: el LED conectado directamente entre el pin y el GND. Sin resistencia, la corriente superaría el límite del LED y del pin;
• LED invertido: el ánodo del lado de menor tensión. La pata larga va al positivo;
• cortocircuito: el 3V3 o el VIN conectados directamente al GND. En la placa real, el regulador se apagaría o se quemaría;
• cable desconectado: una punta del cable sin ningún pin. No participa en el circuito y el resto queda incompleto.

Pasar el ratón sobre un agujero de la protoboard resalta todo lo que está conectado a él, lo que ayuda a ver si dos patas están de verdad en la misma columna. Es el equivalente a seguir el cable con el dedo en el banco de trabajo.

Los archivos de la placa: boot.py y main.py

Cuando la ESP32 con MicroPython se enciende (o se reinicia), busca dos archivos en su sistema de archivos interno y los ejecuta en este orden: primero el boot.py, después el main.py. El boot.py suele quedar casi vacío; en él van configuraciones que tienen que ocurrir antes que todo. El main.py es el programa de verdad. Cuando el main.py termina (o cuando lo interrumpes), la placa vuelve al REPL y se queda esperando comandos.

El simulador sigue la misma idea. El proyecto de la IDE tiene el main.py y el boot.py, y puedes crear otros archivos .py para organizar el código en módulos, importándolos normalmente con import. Cuando el programa termina, el panel Serial se convierte en el REPL, con el prompt >>>, conectado a las variables del programa que acaba de ejecutarse: se puede preguntar cuánto vale una variable o llamar a una función sin volver a ejecutarlo todo.

El botón EN de la placa simulada también se comporta como el de verdad: al soltarlo, la placa se reinicia y ejecuta el boot.py y el main.py otra vez.

Leer los errores como los muestra la placa

Los errores son parte del proceso, y MicroPython tiene el mérito de explicarlos en texto. Cuando algo sale mal, la placa imprime un traceback: el archivo, la línea y el tipo del error. Por ejemplo, usar una variable que no existe muestra NameError: name 'total' isn't defined. El simulador imprime exactamente el mismo texto de la placa (el mensaje de MicroPython es un poco distinto del del Python del computador, que dice "is not defined") y, justo debajo, una explicación en portugués de lo que suele causar ese error.

Algunos errores que todo principiante encuentra en la ESP32:

• ValueError: invalid pin: un número de pin que el chip no tiene, como 24 o 40;
• ValueError: pin can only be input: intentar usar uno de los GPIO 34 a 39 como salida;
• IndentationError: un bloque con sangría distinta. En Python, los cuatro espacios al comienzo de la línea son parte del código;
• ImportError: no module named ...: un módulo que no existe en el firmware ni en el proyecto.

Leer el traceback de abajo hacia arriba, empezando por el tipo del error y después por la línea indicada, resuelve la mayoría de los casos en pocos segundos.

Del simulador a la placa real

PyPlaca se pensó para que el código salga del navegador y vaya a una ESP32 de verdad sin cambios. Lo que se exporta es siempre el texto Python del alumno: el main.py original, las bibliotecas y los módulos del proyecto. La pestaña Placa real reúne los caminos:

• Exportar .zip o Descargar main.py: para grabar con la herramienta que ya usas (Thonny, mpremote u otra);
• Lista de materiales (CSV): las piezas del circuito, para separarlas en el banco de trabajo;
• Grabar en la placa: en Chrome o en Edge, por Web Serial, la IDE conversa con la ESP32 conectada al USB, graba los archivos (el main.py al final) y reinicia la placa para ejecutar el programa nuevo;
• Instalar MicroPython: para una placa nueva, sin el intérprete. El propio alumno descarga el firmware oficial ESP32_GENERIC de la versión 1.29.0 desde el sitio de MicroPython; la IDE comprueba que el chip es una ESP32 común con flash de al menos 4 MB, borra la memoria, graba el firmware en la dirección 0x1000 y verifica el resultado antes de reiniciar.

En el banco de trabajo, el camino del circuito es el mismo de la pantalla: los mismos pines, la misma resistencia, el LED con la pata larga del lado de la resistencia. La diferencia es que, en la placa real, un error de montaje puede estropear una pieza, una razón más para probar primero en el simulador.

Una hoja de ruta para los próximos pasos

Con el LED parpadeando, ya usaste las tres ideas que sostienen todo lo demás: configurar un pin, cambiar su nivel y controlar el tiempo. Los próximos artículos de esta serie profundizan en cada una:

• GPIO, pull-up y el pin flotante: el pin como entrada, los botones y por qué un pin suelto no es confiable;
• PWM en la práctica: brillo, sonido y movimiento con la modulación por ancho de pulso;
• El ADC de la ESP32: cómo medir tensiones y por qué la lectura no llega a 3,3 V.

En las rutas, cada uno de estos temas se convierte en lecciones cortas con circuito listo y desafíos con corrección automática. La primera ruta rehace exactamente el camino de este artículo, del LED de la placa al primer circuito montado por ti, y termina con un semáforo.