Caso práctico: Brillo LED por PWM con Pico-ICE iCE40UP5K

Objetivo y caso de uso

Qué construirás: Controlar el brillo de un LED utilizando PWM en la placa Pico-ICE con Raspberry Pi mediante MicroPython.

Para qué sirve

• Iluminación ajustable en proyectos de domótica utilizando Raspberry Pi y Pico-ICE.
• Control de brillo en pantallas LED para aplicaciones de señalización.
• Prototipos de dispositivos que requieren variación de intensidad lumínica.
• Experimentos educativos sobre control de hardware y programación en MicroPython.

Resultado esperado

• Brillo del LED ajustable en un rango del 0% al 100% mediante señales PWM.
• Latencia de respuesta al cambio de brillo menor a 100 ms.
• Consumo de energía del LED medido en mA, optimizado para diferentes niveles de brillo.
• Mensajes de estado enviados a través de MQTT indicando el nivel de brillo actual.

Público objetivo: Principiantes en programación y electrónica; Nivel: Básico

Arquitectura/flujo: Raspberry Pi como host controlando el RP2040 en la Pico-ICE mediante MicroPython.

Nivel: basico

Prerrequisitos

Sistema operativo y entorno

• Raspberry Pi OS Bookworm 64‑bit (versión estable 2023–2025; kernel 6.x). Verifica:
• uname -a debe reportar arquitectura aarch64.
• lsb_release -a debe indicar Debian 12 (bookworm).
• Python 3.11 (Bookworm incluye 3.11.2 o superior). Verifica:
• python3 --version → 3.11.x

Toolchain y versiones exactas que usaremos

Para este caso práctico básico vamos a programar el microcontrolador RP2040 que se monta en la placa Pico‑ICE para generar la señal PWM que controlará el brillo del LED. Usaremos MicroPython en el RP2040 y Python 3.11 en la Raspberry Pi como host.

• Firmware del dispositivo:
• MicroPython para RP2040 (Raspberry Pi Pico): v1.22.2
  • Archivo: rp2-pico-20231005-v1.22.2.uf2
• Herramientas en el host (Raspberry Pi):
• mpremote 1.22.2 (cliente para desplegar código a MicroPython por USB)
• pyserial 3.5 (si deseas una app host para enviar comandos al dispositivo)
• minicom 2.8 (opcional, para depuración serie)
• Utilidades del sistema (host):
• usbutils (para lsusb)
• python3-venv (para entorno virtual)
• git (opcional)

Nota sobre coherencia de hardware: el modelo exacto de la placa base es “Pico‑ICE (Lattice iCE40UP5K)”. En este nivel básico, usaremos el RP2040 (módulo Raspberry Pi Pico) que se monta en Pico‑ICE para generar PWM, y un LED externo conectado a los pines del encabezado tipo Pico. El FPGA Lattice iCE40UP5K está presente en la placa, pero no lo configuraremos en esta práctica básica.

Habilitar interfaces en la Raspberry Pi (host)

• No es necesario habilitar SPI/I2C/UART para usar USB‑CDC con MicroPython (el Pico aparece como /dev/ttyACM0). Aun así, te indico cómo habilitar interfaces típicas por si luego las usas en variantes:
• sudo raspi-config
• Interfacing Options:
  • I2C: Enable (opcional)
  • SPI: Enable (opcional)
  • Serial Port:
  • Login shell over serial: No
  • Serial port hardware: Yes (opcional; no afecta USB‑CDC)
• Finaliza y reinicia si cambiaste algo.
• Asegúrate de pertenecer al grupo dialout para acceder a /dev/ttyACM0:
• sudo usermod -aG dialout,plugdev $USER
• Cierra sesión y vuelve a entrar (o reinicia).

Preparar entorno Python en el host

Usaremos un entorno virtual con Python 3.11:
– sudo apt update
– sudo apt install -y python3-venv python3-pip usbutils minicom git
– python3 -m venv ~/picoice-venv
– source ~/picoice-venv/bin/activate
– pip install --upgrade pip
– pip install mpremote==1.22.2 pyserial==3.5

Materiales

• 1x Placa base Pico‑ICE (Lattice iCE40UP5K) — modelo exacto: “Pico‑ICE (Lattice iCE40UP5K)”.
• 1x Módulo Raspberry Pi Pico (RP2040) con cabeceras soldadas (sirve como “cerebro”/programador en la Pico‑ICE).
• 1x Raspberry Pi (4B/3B+/5) con Raspberry Pi OS Bookworm 64‑bit.
• 1x LED difuso rojo/verde/azul (cualquiera; en ejemplos se asume LED rojo).
• 1x Resistencia 330 Ω (1/4 W típica).
• 2x Cables dupont hembra‑hembra (o macho‑hembra según el zócalo).
• 1x Cable micro‑USB o USB‑C (según tu Pico) para conectar el Pico a la Raspberry Pi.
• 1x Protoboard pequeña (opcional, aunque con dos cables puedes conectar directo al header).

Recomendaciones:
– Evita conectar el LED directamente sin resistencia.
– Usa siempre un pin GND de la placa como retorno.

Preparación y conexión

Ensamblado básico

• Inserta el módulo Raspberry Pi Pico en el zócalo/headers de la Pico‑ICE. Asegúrate de alinear la orientación de modo que los pines etiquetados GPx coincidan con los serigrafiados del zócalo.

Elección de pin PWM

• Usaremos el pin GP15 del RP2040 (Pico). Razones:
• Es un pin estándar del header del Pico (fácil acceso).
• Soporta PWM (slice 7, canal B del PWM del RP2040).
• Conexión del LED:
• Ánodo del LED → pin GP15
• Cátodo del LED → GND (a través de una resistencia de 330 Ω en serie, preferiblemente en el lado del ánodo para facilitar el cableado).

Tabla de conexión y referencia de pines

Indicaciones:
– Identifica el pad rotulado “GP15” en el header de la Pico‑ICE (coincide con la serigrafía del footprint del Pico).
– Usa un GND cercano para minimizar lazos.

Código completo

A continuación incluimos dos piezas de software:
1) Código MicroPython que corre en el RP2040 (en la Pico‑ICE) y genera la PWM. Además, expone un puerto USB‑CDC para que el host le envíe el nivel de brillo en tiempo real.
2) Un script Python (host) opcional para enviar comandos de brillo desde la Raspberry Pi.

1) Firmware MicroPython para el RP2040 (archivo main.py)

Características:
– Frecuencia PWM estable (1 kHz).
– Resolución de 16 bits (0–65535).
– Comandos por USB‑CDC:
– “Bxxx” o “Bxxx%” para brillo en % (0–100).
– “Fxxxx” para fijar frecuencia en Hz (ej.: F500).
– “GON”/“GOFF” para activar/desactivar corrección gamma (perceptual).
– “INFO” para imprimir estado.
– Mensajes de confirmación vía USB para depuración.

Copia y pega el siguiente código en un archivo llamado main.py:

# main.py — MicroPython v1.22.2 (RP2040, Raspberry Pi Pico) en Pico-ICE
from machine import Pin, PWM, USB_VCP
import time

# Configuración de pin y PWM
PWM_PIN = 15  # GP15 en RP2040
DEFAULT_FREQ_HZ = 1000
MAX_DUTY = 65535

p = PWM(Pin(PWM_PIN))
p.freq(DEFAULT_FREQ_HZ)

# Estado
gamma_enabled = True
current_percent = 30  # brillo inicial en %

# Tabla gamma simple (perceptual): mapea 0–100% a 0–65535
# Aproximación usando potencia ~2.2; pre-calculamos por rapidez.
def build_gamma_table(gamma=2.2):
    table = [0]*101
    for i in range(101):
        linear = i / 100.0
        corrected = pow(linear, gamma)
        table[i] = int(round(corrected * MAX_DUTY))
    return table

gamma_table = build_gamma_table(2.2)

def percent_to_duty(pct):
    if pct <= 0:
        return 0
    if pct >= 100:
        return MAX_DUTY
    if gamma_enabled:
        return gamma_table[pct]
    else:
        return int((pct / 100.0) * MAX_DUTY)

def apply_brightness(pct):
    global current_percent
    current_percent = max(0, min(100, int(pct)))
    p.duty_u16(percent_to_duty(current_percent) & 0xFFFF)

def set_freq(hz):
    hz = max(10, min(20000, int(hz)))  # limitamos entre 10 Hz y 20 kHz
    p.freq(hz)
    return hz

# Inicializamos brillo por defecto
apply_brightness(current_percent)

# Interfaz USB-CDC para control desde host
vcp = USB_VCP()

def info():
    return "BRI:{:3d}% FREQ:{}HZ GAMMA:{}".format(current_percent, p.freq(), "ON" if gamma_enabled else "OFF")

def handle_command(cmd):
    global gamma_enabled
    c = cmd.strip().upper()
    if c.startswith(b"B"):
        # Bxx o Bxx%  -> brillo en %
        try:
            if c.endswith(b"%"):
                val = int(c[1:-1])
            else:
                val = int(c[1:])
            apply_brightness(val)
            vcp.write(b"OK " + info().encode() + b"\n")
        except:
            vcp.write(b"ERR BAD_B\n")
    elif c.startswith(b"F"):
        # Fxxxx -> frecuencia en Hz
        try:
            hz = int(c[1:])
            hz = set_freq(hz)
            apply_brightness(current_percent)
            vcp.write(b"OK " + info().encode() + b"\n")
        except:
            vcp.write(b"ERR BAD_F\n")
    elif c == b"GON":
        gamma_enabled = True
        apply_brightness(current_percent)
        vcp.write(b"OK " + info().encode() + b"\n")
    elif c == b"GOFF":
        gamma_enabled = False
        apply_brightness(current_percent)
        vcp.write(b"OK " + info().encode() + b"\n")
    elif c == b"INFO":
        vcp.write(info().encode() + b"\n")
    else:
        vcp.write(b"ERR UNKNOWN\n")

# Bucle principal
last_ping = time.ticks_ms()
while True:
    # Si hay datos, procesamos línea a línea
    if vcp.any():
        line = vcp.readline()
        if line is not None:
            handle_command(line)
    # Ping/keepalive de ejemplo cada 5 s (opcional)
    if time.ticks_diff(time.ticks_ms(), last_ping) > 5000:
        # vcp.write(b"# alive " + info().encode() + b"\n")
        last_ping = time.ticks_ms()
    # Pequeña espera para ceder CPU
    time.sleep_ms(5)

Explicación breve de partes clave:
– Selección del pin y PWM:
– PWM_PIN = 15: coincide con GP15 del RP2040 en la Pico‑ICE.
– p.freq(DEFAULT_FREQ_HZ): fija 1 kHz, que evita parpadeo visible.
– Conversión de brillo:
– gamma_table implementa una corrección perceptual simple; el ojo no responde linealmente a la luz. Se puede desactivar con “GOFF”.
– Protocolo por USB‑CDC:
– Comandos humanos y fáciles de recordar (B, F, GON/GOFF, INFO).
– Se responde con “OK …” o “ERR …” para facilitar el diagnóstico en el host.

2) Script Python (host) para enviar brillo (control_brilho_host.py)

Este script se ejecuta en la Raspberry Pi y abre el puerto USB‑CDC (/dev/ttyACM0). Permite:
– Fijar brillo por porcentaje.
– Cambiar frecuencia.
– Encender/apagar gamma.
– Hacer un barrido (“fade”) de demostración.

# control_brilho_host.py — Python 3.11 (host) para controlar el RP2040 en Pico-ICE
import sys
import time
import serial  # pyserial

PORT = "/dev/ttyACM0"
BAUD = 115200

HELP = """
Comandos:
  b <0-100>     -> brillo en %
  f <hz>        -> frecuencia PWM
  gon|goff      -> gamma on/off
  info          -> estado
  fade [sec]    -> degradado up/down (sec total opcional, ej. 3.0)
  quit          -> salir
"""

def send(ser, s):
    if not s.endswith("\n"):
        s += "\n"
    ser.write(s.encode("ascii"))
    line = ser.readline().decode(errors="ignore").strip()
    if line:
        print("DEV:", line)

def main():
    print("Abriendo", PORT, "a", BAUD, "baudios")
    with serial.Serial(PORT, BAUD, timeout=1) as ser:
        time.sleep(0.3)
        print(HELP)
        while True:
            try:
                cmd = input("> ").strip()
                if cmd == "":
                    continue
                if cmd == "quit":
                    break
                elif cmd.startswith("b "):
                    _, v = cmd.split()
                    send(ser, "B"+v)
                elif cmd.startswith("f "):
                    _, v = cmd.split()
                    send(ser, "F"+v)
                elif cmd == "gon":
                    send(ser, "GON")
                elif cmd == "goff":
                    send(ser, "GOFF")
                elif cmd == "info":
                    send(ser, "INFO")
                elif cmd.startswith("fade"):
                    parts = cmd.split()
                    total = float(parts[1]) if len(parts) > 1 else 3.0
                    steps = 100
                    dt = total/(2*steps)
                    # subida
                    for i in range(0,101):
                        send(ser, f"B{i}")
                        time.sleep(dt)
                    # bajada
                    for i in range(100,-1,-1):
                        send(ser, f"B{i}")
                        time.sleep(dt)
                else:
                    print("Comando no reconocido.")
                    print(HELP)
            except KeyboardInterrupt:
                break

if __name__ == "__main__":
    main()

Notas:
– Por defecto MicroPython USB‑CDC funciona bien a 115200 baudios; los datos van por USB, por lo que la velocidad no es crítica.
– Si tu dispositivo aparece como /dev/ttyACM1, cambia PORT.

Compilación/flash/ejecución

Vamos a instalar el firmware MicroPython en el RP2040, copiar el main.py y probar el control desde el host.

1) Descargar firmware MicroPython v1.22.2 para Pico

• cd ~
• wget https://micropython.org/resources/firmware/rp2-pico-20231005-v1.22.2.uf2 -O micropython-pico-v1.22.2.uf2

Verifica que el archivo existe:
– ls -lh micropython-pico-v1.22.2.uf2

2) Poner el RP2040 en modo BOOTSEL y flashear UF2

• Conecta el cable USB de la Pico‑ICE (al puerto del módulo Pico) a la Raspberry Pi.
• Mantén pulsado el botón BOOTSEL del Pico mientras conectas el USB (o mientras reseteas).
• La Raspberry Pi montará una unidad USB llamada RPI-RP2 (en /media/pi/RPI-RP2 o similar).
• Copia el firmware:
• cp ~/micropython-pico-v1.22.2.uf2 /media/$USER/RPI-RP2/
• La unidad se desmontará sola; el Pico se reinicia y expone un puerto serie USB‑CDC.

Comprueba que aparece el puerto:
– ls /dev/ttyACM*
– Deberías ver /dev/ttyACM0 (o similar).

Si no aparece, prueba:
– dmesg | tail -n 50
– lsusb (deberías ver un dispositivo Raspberry Pi RP2 o MicroPython)

3) Crear y activar entorno virtual en el host (si no lo hiciste)

• python3 -m venv ~/picoice-venv
• source ~/picoice-venv/bin/activate
• pip install --upgrade pip
• pip install mpremote==1.22.2 pyserial==3.5

4) Copiar el programa main.py al RP2040 con mpremote

• Guarda el contenido anterior de main.py en un archivo local, por ejemplo:
• nano ~/main.py (pega el código y guarda)
• Copia el archivo al sistema de ficheros de MicroPython:
• mpremote connect /dev/ttyACM0 fs put ~/main.py
• Reinicia el dispositivo para ejecutar automáticamente main.py:
• mpremote connect /dev/ttyACM0 reset

Comprobación rápida con minicom (opcional):
– minicom -b 115200 -o -D /dev/ttyACM0
– Escribe INFO y pulsa Enter; deberías ver estado.

Para salir de minicom: Ctrl+A, luego X.

5) Probar desde Python (host)

• Guarda el script de host:
• nano ~/control_brilho_host.py (pega el código y guarda)
• Ejecuta:
• python ~/control_brilho_host.py
• Prueba comandos:
• info → debe responder con brillo, frecuencia y gamma.
• b 10 → brillo 10% (LED débil).
• b 90 → brillo 90% (LED intenso).
• fade 4 → barrido suave en 4 s.

Validación paso a paso

1) Verificación física:
– ¿LED con polaridad correcta? El ánodo (patilla larga) hacia GP15 a través de la resistencia de 330 Ω; cátodo a GND.
– ¿Conexión firme y sin falsos contactos?

2) Verificación del dispositivo:
– Conecta Pico‑ICE a la Raspberry Pi. Espera unos segundos.
– ls /dev/ttyACM* → ¿aparece /dev/ttyACM0?
– Si no aparece, revisa cable USB y firmware UF2.

3) Verificación de programa en MicroPython:
– mpremote connect /dev/ttyACM0 repl
– Escribe import os; os.listdir() → debería listar main.py.
– Escribe Ctrl+D para soft reset y ver si main.py arranca (sin errores).

4) Prueba manual de comandos con minicom:
– minicom -b 115200 -o -D /dev/ttyACM0
– Escribe INFO → respuesta con estado actual.
– B50 → LED debe quedar en brillo medio.
– B0 → LED apagado.
– B100 → LED al máximo.
– F500 → baja la frecuencia; visualmente no cambia, pero si tienes un osciloscopio, mide GP15.

5) Validación con script de host:
– Ejecuta python ~/control_brilho_host.py.
– Comando fade 3 → observa el LED aumentar y disminuir suavemente.
– Cambia gamma:
– goff → el cambio de brillo parecerá más “lineal” (a veces menos natural).
– gon → restablece corrección gamma.

6) Medición simple (opcional):
– Puedes medir la caída de tensión promedio en la resistencia con un multímetro en DC; debería subir con el porcentaje de PWM.
– Si dispones de osciloscopio, mide GP15 para confirmar el ciclo de trabajo (duty) y la frecuencia.

Criterios de éxito:
– El LED responde a cambios de brillo en tiempo real.
– No hay parpadeo visible a 1 kHz.
– Los comandos INFO y Bxx/Fxxxx/GON/GOFF operan con respuestas “OK …”.

Troubleshooting

1) No aparece /dev/ttyACM0
– Causas:
– Firmware MicroPython no flasheado o USB en modo BOOTSEL.
– Cable USB solo de carga (sin datos).
– Permisos de usuario.
– Soluciones:
– Repite el copiado UF2 con BOOTSEL pulsado.
– Usa otro cable USB “data”.
– sudo usermod -aG dialout,plugdev $USER y reinicia sesión.

2) mpremote no encuentra el dispositivo
– Causa: Nombre de dispositivo distinto (/dev/ttyACM1, etc.) o venv no activado.
– Solución: ls /dev/ttyACM* y ajusta mpremote connect /dev/ttyACM1 ...; source ~/picoice-venv/bin/activate.

3) LED no enciende
– Causas:
– Polaridad invertida.
– Resistencia en mal lugar o valor extremo (ej., 10 kΩ).
– Pin incorrecto (no es GP15).
– Soluciones:
– Verifica ánodo/cátodo y GND.
– Sustituye por 330 Ω (o entre 220–1 kΩ).
– Asegúrate de estar en el pad serigrafiado como GP15.

4) LED siempre encendido al máximo
– Causas:
– Cortocircuito entre GP15 y 3V3.
– Código no corre o PWM no se aplica.
– Soluciones:
– Desconecta y revisa conexiones con multímetro.
– mpremote repl → verifica que p.freq() y p.duty_u16() responden sin error.

5) LED parpadea o zumba
– Causas:
– Frecuencia PWM demasiado baja (visible).
– Cableado largo captando ruido.
– Soluciones:
– F2000 o F5000 para 2–5 kHz.
– Acortar cables, usar GND cercano.

6) Comandos no responden “OK …”
– Causas:
– Escribes “b 50” en minicom y no “B50” (nuestro parser admite ambas, pero cuidado con espacios/líneas).
– Terminador de línea no llega.
– Soluciones:
– En minicom, pulsa Enter. En script host, send() ya agrega “
”.

7) “Permission denied” al acceder a /dev/ttyACM0
– Causas:
– Usuario fuera de dialout/plugdev.
– Soluciones:
– sudo usermod -aG dialout,plugdev $USER y reinicia sesión.

8) El Pico entra de nuevo en RPI-RP2 al copiar UF2
– Causa: Sigues en modo bootloader (eso es normal al copiar).
– Solución: Espera 3–5 s; se reinicia solo. Si no, pulsa el botón RUN/RESET (si presente) o reconecta USB.

Mejoras/variantes

• Botones para subir/bajar brillo:
• Conecta un pulsador entre GP14 y GND (con pull‑up interno en código) para “+5%” y otro en GP13 para “-5%”.

• Amplía el main.py para leer entradas y ajustar current_percent.

• Curva gamma avanzada:

• Implementa una tabla de 0–255 pasos si prefieres mandar brillo en 8 bits desde host.

• Sustituye la tabla por una aproximación exponencial más fina o una LUT calibrada por sensor.

• Rampas suaves y animaciones:

• Implementa interpolación con time.ticks_ms() para animaciones temporizadas sin jitter.

• Variar la frecuencia y medir EMI:

• Prueba F10000 (10 kHz) si alimentas etapas analógicas cercanas para alejar ruido audible.

• Uso de múltiples canales PWM:

• Añade un segundo LED en GP14 (PWM slice 7, canal A) y sincroniza ambos.

• Integración con GUI:

• Crea una interfaz gráfica (PyQt5/PySide) que envíe “Bxx” al puerto serie; útil para demos.

• Variante FPGA (nivel siguiente):

• Como evolución, puedes mover la generación PWM al iCE40UP5K y manejar el duty desde el RP2040 por una interfaz simple (p. ej., SPI). Para ello, en otra práctica instalarías una toolchain OSS CAD Suite (Yosys/nextpnr/icestorm) específica y un bitstream que exponga un registro de 8/16 bits para el duty. Esta práctica básica se centra en RP2040 para reducir la complejidad inicial.

Checklist de verificación

Marca cada ítem cuando lo completes:

• [ ] Raspberry Pi OS Bookworm 64‑bit operativo; Python 3.11 verificado (python3 --version).
• [ ] Usuario agregado a grupos dialout/plugdev y sesión reiniciada.
• [ ] Entorno virtual creado y activado (source ~/picoice-venv/bin/activate).
• [ ] mpremote 1.22.2 y pyserial 3.5 instalados (pip list).
• [ ] Firmware MicroPython v1.22.2 copiado al Pico (modo BOOTSEL) y /dev/ttyACM0 visible.
• [ ] main.py copiado al dispositivo con mpremote y reinicio realizado.
• [ ] LED conectado: ánodo a GP15 a través de 330 Ω; cátodo a GND.
• [ ] Comando INFO responde con estado (por minicom o script host).
• [ ] B10 y B90 modifican brillo como se espera.
• [ ] fade 3 produce un barrido suave de brillo.
• [ ] No hay parpadeo visible a 1 kHz (si lo hay, subiste a 2–5 kHz y se solucionó).
• [ ] Documentaste en tus notas la versión exacta de firmware y scripts utilizados.

Con esto, has logrado un control robusto de brillo por PWM en tu Pico‑ICE usando el módulo RP2040, con una interfaz de control cómoda desde tu Raspberry Pi host. Este enfoque es ideal para nivel básico, y te prepara para, en una siguiente práctica, trasladar la lógica PWM al FPGA iCE40UP5K si deseas profundizar en diseño digital con HDL y toolchains de síntesis.