Objetivo y caso de uso

Qué construirás: Leer datos de temperatura de un sensor I2C utilizando la placa Pico-ICE con el chip RP2040.

Para qué sirve

• Monitoreo de temperatura en proyectos de domótica utilizando sensores DHT22.
• Control de temperatura en invernaderos mediante integración con sistemas de riego.
• Registro de datos ambientales en estaciones meteorológicas de bajo costo.
• Desarrollo de sistemas de alerta para condiciones extremas de temperatura en laboratorios.

Resultado esperado

• Lectura de temperatura con una precisión de ±0.5 °C.
• Transmisión de datos a través de MQTT con una frecuencia de 1 mensaje por segundo.
• Latencia de respuesta del sensor inferior a 100 ms.
• Capacidad de manejar hasta 10 sensores en un mismo bus I2C sin pérdida de datos.

Público objetivo: Estudiantes y entusiastas de la electrónica; Nivel: Básico

Arquitectura/flujo: Sensor I2C conectado a Pico-ICE, datos procesados en MicroPython y enviados a un servidor mediante MQTT.

Nivel: basico

Prerrequisitos

• Hardware de apoyo:
• Un Raspberry Pi (4B, 400, o 5) funcionando como host de desarrollo.
• Conectividad a Internet en el Raspberry Pi para descargar herramientas y firmware.
• Sistema operativo en el host:
• Raspberry Pi OS Bookworm 64‑bit (basado en Debian 12).
• Python en el host:
• Python 3.11 (Bookworm usa Python 3.11 por defecto; verifícalo con python3 --version, que debería devolver “Python 3.11.x”, típicamente 3.11.2).
• Toolchain y utilidades con versiones concretas (host):
• Entorno virtual de Python: venv de Python 3.11.
• mpremote 1.22.2 (cliente oficial para MicroPython).
• pyserial 3.5 (para lectura serie/CDC desde el host).
• i2c-tools 4.3 (opcional; para validar que el bus I2C del host está habilitado, aunque no lo usaremos para el sensor en este caso).
• Firmware del dispositivo (RP2040 en la Pico-ICE):
• MicroPython 1.22.2 para RP2040 (imagen UF2 para Raspberry Pi Pico — compatible con RP2040 de la Pico-ICE).
• Conocimientos previos:
• Conectar componentes con cables Dupont sobre protoboard.
• Usar la terminal en Linux (Raspberry Pi OS).
• Nivel básico de Python.

Notas importantes de coherencia:
– Este caso práctico usa el modelo “Pico-ICE (Lattice iCE40UP5K)”. Trabajaremos exclusivamente con el microcontrolador RP2040 integrado en la placa para implementar el maestro I2C y leer el sensor de temperatura. La FPGA Lattice iCE40UP5K no se programa en este ejercicio básico.
– El sensor I2C se conecta físicamente a los pines del RP2040 presentes en la Pico‑ICE; no conectes el mismo sensor al bus I2C del Raspberry Pi host para evitar conflictos de múltiples maestros en el mismo bus.

Materiales

• 1x Pico-ICE (Lattice iCE40UP5K) — placa con RP2040 + FPGA iCE40UP5K y conector USB‑C.
• 1x Sensor de temperatura I2C: TMP102 o compatible (dirección por defecto 0x48). Cualquier breakout de TMP102 a 3.3 V (p. ej., con regulador y resistencias de pull-up integradas) funciona.
• 1x Cable USB‑C a USB‑A (o a USB‑C, según el puerto del Raspberry Pi) para alimentar/programar la Pico-ICE.
• Cables Dupont hembra‑hembra (al menos 4) para: SDA, SCL, 3V3, GND.
• 1x Protoboard pequeña (opcional, para organizar conexiones).
• Accesorios para validación:
• Dedo/mano para calentar el sensor con contacto.
• Cubitos de hielo o bolsa fría para observar descensos de temperatura.

Preparación y conexión

Habilitar interfaces y preparar el entorno en Raspberry Pi OS Bookworm 64‑bit

Aunque el sensor I2C no se conectará al bus del Raspberry Pi, es buena práctica habilitar I2C en el host y confirmar que el kernel carga los módulos necesarios. Además, configuraremos el entorno Python 3.11 en un venv e instalaremos herramientas exactas.

1) Actualiza el sistema:
– Abre una terminal en el Raspberry Pi y ejecuta:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

2) Habilita I2C desde raspi-config (recomendado):
– Tras reiniciar:

sudo raspi-config

• Interfaz gráfica de texto:
• 3 Interface Options
• I5 I2C
• Enable → Yes
• Finish → Yes (reinicia si lo pide)

3) Alternativa: habilitar I2C editando /boot/firmware/config.txt (opcional si ya hiciste el paso anterior):

echo "dtparam=i2c_arm=on" | sudo tee -a /boot/firmware/config.txt
sudo reboot

4) Instala dependencias y crea un entorno virtual con Python 3.11:

sudo apt install -y python3-venv python3-pip git curl i2c-tools
python3 --version

• Debe mostrar algo como: Python 3.11.2

5) Crea y activa el venv:

python3 -m venv ~/venv-picoice
source ~/venv-picoice/bin/activate
pip install --upgrade pip

6) Instala las herramientas exactas (versionadas):

pip install mpremote==1.22.2 pyserial==3.5
mpremote --version
python -c "import serial; print(serial.__version__)"

• Debe mostrar:
• mpremote 1.22.2
• 3.5

7) (Opcional pero recomendable) Añade tu usuario al grupo dialout para acceder a /dev/ttyACM0 sin sudo:

sudo usermod -aG dialout $USER
newgrp dialout

8) Descarga la imagen de MicroPython 1.22.2 para RP2040 (UF2):
– Creamos un directorio de trabajo:

mkdir -p ~/pico-ice-i2c-temp && cd ~/pico-ice-i2c-temp

• Descarga (ejemplo de URL para MicroPython 1.22.2 RP2/Pico):

curl -L -o micropython-1.22.2-rp2-pico.uf2 https://micropython.org/resources/firmware/micropython-1.22.2-rp2-pico.uf2
ls -lh micropython-1.22.2-rp2-pico.uf2

Nota: Esta imagen está destinada al RP2040 (Pico). La Pico‑ICE emplea un RP2040 y, para este uso básico, la imagen estándar del Pico funciona correctamente.

Conexión física del sensor TMP102 a la Pico-ICE

Usaremos el bus I2C0 del RP2040 con sus pines por defecto:
– SDA en GP4
– SCL en GP5
– VCC a 3V3
– GND a GND

Muchos breakouts de TMP102 ya incluyen resistencias de pull‑up a 3.3 V, por lo que no se requieren resistencias externas adicionales. No alimentes el sensor con 5 V.

Tabla de mapeo de pines para la conexión:

Consejos:
– Asegura conexiones cortas y firmes, sin invertir SDA/SCL.
– Si tu breakout permite seleccionar la dirección I2C (A0/A1/A2 o ADDR), déjalo en la dirección por defecto 0x48 para seguir el código tal cual.
– La Pico‑ICE se conecta al Raspberry Pi mediante USB‑C; ese mismo cable alimenta el RP2040 y proporciona un puerto serie USB‑CDC para logs.

Código completo (MicroPython sobre RP2040)

Trabajaremos con MicroPython 1.22.2. Subiremos un main.py al sistema de archivos del RP2040 en la Pico‑ICE. El script:
– Inicializa I2C0 a 100 kHz en GP4/GP5.
– Hace un escaneo de dispositivos en el bus para confirmar la presencia del TMP102.
– Lee el registro de temperatura (0x00) del TMP102.
– Convierte la lectura de 12 bits a grados Celsius.
– Imprime una línea por segundo con la temperatura.

main.py (MicroPython)

# main.py - Lectura I2C de sensor TMP102 con Pico-ICE (RP2040) y MicroPython 1.22.2
# Autor: Profesor de Ingeniería Electrónica e Informática
# Objetivo: i2c-lectura-sensor-temperatura

import time
from machine import Pin, I2C

# Configuración I2C para RP2040 (I2C0 en GP4=SDA, GP5=SCL)
I2C_ID = 0
PIN_SDA = 4   # GP4
PIN_SCL = 5   # GP5
I2C_FREQ = 100_000  # 100 kHz (válido para TMP102)

# Dirección por defecto del TMP102 (A0=0 => 0x48)
TMP102_ADDR = 0x48
TMP102_TEMP_REG = 0x00

def tmp102_read_celsius(i2c, addr=TMP102_ADDR):
    # Lee 2 bytes del registro de temperatura (0x00)
    raw = i2c.readfrom_mem(addr, TMP102_TEMP_REG, 2)
    msb = raw[0]
    lsb = raw[1]
    # Formato TMP102: 12 bits de temperatura en complemento a dos,
    # resol. 0.0625 °C. El dato está en bits [15:4] (4 bits LSB descartados).
    temp_raw = ((msb << 4) | (lsb >> 4)) & 0xFFF
    # Ajuste de signo (12 bits)
    if temp_raw & 0x800:  # bit de signo (bit 11)
        temp_raw -= 1 << 12
    temp_c = temp_raw * 0.0625
    return temp_c

def main():
    print("Iniciando: Pico-ICE (RP2040) + TMP102 @ I2C0 (GP4/GP5)")
    i2c = I2C(I2C_ID, scl=Pin(PIN_SCL), sda=Pin(PIN_SDA), freq=I2C_FREQ)

    # Escaneo del bus para diagnóstico
    devices = i2c.scan()
    if not devices:
        print("No se detectan dispositivos I2C. Verifica cableado y alimentación.")
    else:
        print("Dispositivos I2C detectados:", [hex(d) for d in devices])

    # Verifica que el TMP102 esté en la dirección esperada
    if TMP102_ADDR not in devices:
        print("Advertencia: no se encontró TMP102 en 0x48.")
        print("Si usas otra configuración de ADDR (A0/A1/A2), ajusta TMP102_ADDR.")
    else:
        print("TMP102 detectado en 0x48. Iniciando lecturas...")

    # Bucle principal de lectura
    while True:
        try:
            temp_c = tmp102_read_celsius(i2c, TMP102_ADDR)
            print("Temperatura: {:.2f} °C".format(temp_c))
        except OSError as e:
            # Error típico si el dispositivo no responde en el bus
            print("Error I2C/OSError:", e)
        except Exception as e:
            print("Error inesperado:", e)
        time.sleep(1.0)

# Punto de entrada
if __name__ == "__main__":
    main()

Explicación breve de partes clave:
– Inicialización de I2C: I2C(0, sda=Pin(4), scl=Pin(5), freq=100000) configura el bus I2C0 del RP2040 en los pines estándar GP4/GP5, a 100 kHz, compatible con TMP102.
– i2c.scan(): útil para comprobar si la dirección 0x48 aparece en el bus tras conectar el sensor.
– Lectura del registro 0x00 del TMP102: se obtienen 2 bytes y se reconstruye el dato de 12 bits en complemento a dos (resolución 0.0625 °C por LSB).
– Bucle infinito: imprime la temperatura cada segundo. Sirve tanto para validación como para logging en el host.

Script opcional en el host para registrar en CSV (Python 3.11)

Este script usa pyserial 3.5 para abrir el puerto CDC del RP2040 (aparece como /dev/ttyACM0) y copiar todas las líneas recibidas a un CSV con timestamp. Es útil para validación y depuración.

# host_log_temp.py - Registro de lecturas desde /dev/ttyACM0 a CSV
# Requiere: Python 3.11, pyserial==3.5
import csv
import sys
import time
import serial

PORT = "/dev/ttyACM0"
BAUD = 115200
OUT_CSV = "log_temp.csv"

def main():
    print(f"Abriendo {PORT} @ {BAUD}...")
    with serial.Serial(PORT, BAUD, timeout=1) as ser, open(OUT_CSV, "w", newline="") as f:
        writer = csv.writer(f)
        writer.append(["timestamp_epoch_s", "line_raw"])
        print(f"Registrando a {OUT_CSV}. Ctrl+C para detener.")
        while True:
            try:
                line = ser.readline().decode("utf-8", errors="replace").strip()
                if line:
                    writer.writerow([f"{time.time():.3f}", line])
                    f.flush()
                    print(line)
            except KeyboardInterrupt:
                print("\nFin de registro.")
                break
            except Exception as e:
                print("Error:", e, file=sys.stderr)
                time.sleep(0.5)

if __name__ == "__main__":
    main()

Compilación/flash/ejecución

En este caso no compilamos C/C++; cargamos MicroPython 1.22.2 (UF2) y subimos el main.py al RP2040 de la Pico‑ICE.

1) Poner la Pico‑ICE en modo BOOTSEL (montaje masivo):
– Desconecta la Pico‑ICE del Raspberry Pi (si está conectada).
– Mantén pulsado el botón BOOT (si tu versión lo expone; en la Pico‑ICE el RP2040 tiene modo BOOTSEL como el Pico).
– Conecta el cable USB‑C al Raspberry Pi.
– Suelta el botón BOOT tras 1–2 segundos.
– Debe aparecer un dispositivo de almacenamiento masivo llamado RPI-RP2.

2) Copiar MicroPython 1.22.2 (UF2) al RP2040:
– En el host (Raspberry Pi), asumiendo que el sistema montó la unidad en /media/pi/RPI-RP2:

cd ~/pico-ice-i2c-temp
ls /media/pi | grep RPI-RP2
cp micropython-1.22.2-rp2-pico.uf2 /media/pi/RPI-RP2/
sync

• Al terminar la copia, el dispositivo RPI‑RP2 se desmontará automáticamente y la Pico‑ICE reiniciará con MicroPython.

3) Verifica el puerto serie del RP2040:

dmesg | tail -n 20
ls -l /dev/ttyACM*

• Debes ver algo como /dev/ttyACM0.

4) Subir el script main.py con mpremote 1.22.2:
– Crea el archivo local main.py con el código anterior (si no lo has hecho).
– Conecta mpremote:

source ~/venv-picoice/bin/activate
mpremote connect list

• Debe listar /dev/ttyACM0 como dispositivo disponible.
• Sube el archivo:

mpremote connect /dev/ttyACM0 fs put main.py

• Opcional: ejecuta inmediatamente (aunque al reiniciar se ejecutará solo):

mpremote connect /dev/ttyACM0 run main.py

5) Observar la salida en la REPL:
– Abrir REPL y ver emisiones:

mpremote connect /dev/ttyACM0 repl

• Si el script se está ejecutando, verás líneas tipo:
• “Dispositivos I2C detectados: [‘0x48’]”
• “Temperatura: 23.75 °C”

6) Alternativa de logging desde el host con pyserial:
– En otra terminal:

cd ~/pico-ice-i2c-temp
python host_log_temp.py

• Se creará log_temp.csv con las líneas recibidas.

Validación paso a paso

1) Detección del dispositivo I2C:
– Al iniciar, el script imprime el resultado de i2c.scan(). Debe incluir 0x48 si el TMP102 está correctamente cableado.
– Mensaje esperado:
– “Dispositivos I2C detectados: [‘0x48’]”
– “TMP102 detectado en 0x48. Iniciando lecturas…”
– Si no aparece 0x48: revisa cableado y dirección del sensor (ver Troubleshooting).

2) Lectura de temperatura estable:
– Verás lecturas cada segundo, por ejemplo:
– “Temperatura: 22.50 °C”
– “Temperatura: 22.44 °C”
– La temperatura en reposo suele estar entre 20–30 °C según el ambiente.

3) Prueba de calentamiento:
– Toca el sensor con los dedos durante 10–20 s.
– Debe subir al menos 1–3 °C con respecto a la línea base, confirmando que la lectura cambia de forma realista.

4) Prueba de enfriamiento:
– Acerca un cubito de hielo en una bolsa (para evitar agua) a 1–2 cm del sensor, o sopla aire frío.
– Debe observarse un descenso progresivo de la temperatura (1–4 °C o más según el tiempo y proximidad).

5) Verificación del refresco y estabilidad:
– Observa que el intervalo sea de aprox. 1 segundo entre lecturas.
– Si notas lecturas erráticas, comprueba que los cables no sean excesivamente largos y que el breakout tenga pull‑ups integradas. Si no las tiene, añade resistencias de 4.7 kΩ a 3.3 V en SDA y SCL.

6) Validación de persistencia en reinicio:
– Desconecta y reconecta la Pico‑ICE. MicroPython ejecutará main.py automáticamente (si existe en el sistema de archivos interno).
– Debe comenzar a imprimir “Iniciando…” seguido de las lecturas.

Troubleshooting

1) No aparece /dev/ttyACM0 en el host:
– Causas:
– Cable USB defectuoso o solo de carga (sin datos).
– MicroPython no cargó correctamente (no se copió UF2 o copia incompleta).
– Falta de permisos sobre el dispositivo.
– Soluciones:
– Prueba con otro cable USB‑C.
– Repite el proceso BOOTSEL y copia de UF2.
– Añade el usuario al grupo dialout: sudo usermod -aG dialout $USER y vuelve a iniciar sesión.
– Observa dmesg | tail -n 50 para ver mensajes del kernel.

2) i2c.scan() devuelve lista vacía:
– Causas:
– SDA/SCL invertidos.
– Sensor sin alimentación o a 5V por error.
– Cables flojos o pin incorrecto en la Pico‑ICE.
– Falta de pull‑ups en el breakout (poco frecuente si es una placa comercial).
– Soluciones:
– Verifica el mapeo: SDA → GP4, SCL → GP5, VCC → 3V3(OUT), GND → GND.
– Usa cables cortos.
– Asegúrate de que el breakout indica 3.3 V y que VCC está conectado a 3V3 (no a 5V).

3) Dirección I2C distinta a 0x48:
– Causas:
– Pines de dirección (A0/A1/A2 o ADDR) del sensor configurados para otra dirección (0x49–0x4B).
– Soluciones:
– Revisa la hoja de datos y el jumper/soldadura del breakout.
– Cambia TMP102_ADDR = 0x48 en el código a la dirección detectada por i2c.scan().

4) Lecturas inestables o erráticas:
– Causas:
– Cables largos o cercanos a fuentes de ruido.
– Pull‑ups insuficientes si el breakout es “bare”.
– Frecuencia del I2C demasiado alta para la topología del cableado.
– Soluciones:
– Mantén cables cortos.
– Reduce I2C_FREQ a 50 kHz para probar estabilidad.
– Añade resistencias pull‑up de 4.7 kΩ en SDA y SCL a 3.3 V si tu breakout no las tiene.

5) Error OSError: [Errno 5] EIO o similares durante lectura:
– Causas:
– Transacciones interrumpidas por mal contacto.
– Dirección/registros incorrectos para el sensor.
– Soluciones:
– Revisa conexiones físicas.
– Confirma que el sensor es efectivamente un TMP102; si no, adapta el registro y la conversión.

6) El script no arranca automáticamente tras reiniciar:
– Causas:
– main.py no se copió al sistema de archivos del RP2040.
– El archivo se guardó con nombre distinto o en el directorio del host.
– Soluciones:
– Vuelve a subir con mpremote ... fs put main.py.
– Verifica con mpremote ... fs ls que main.py está en la raíz.

7) El host muestra lecturas pero no cambian con el calor/frío:
– Causas:
– Sensor colocado muy lejos o aislado térmicamente.
– Errores de manipulación del dato para otro modelo de sensor.
– Soluciones:
– Toca directamente el encapsulado del sensor (no el plástico del conector).
– Asegúrate de usar el código de conversión correcto para TMP102. Si usas MCP9808 u otro, ajusta la rutina de lectura.

8) Conflicto con I2C del host (Raspberry Pi):
– Causas:
– Conectar el mismo sensor simultáneamente al bus I2C del Pi y al RP2040 en la Pico‑ICE.
– Soluciones:
– No mezclar buses maestros. Mantén el sensor conectado solo a la Pico‑ICE para este ejercicio.

Mejoras/variantes

• Alertas por umbral:
• Usa el pin ALERT del TMP102 para generar una interrupción en un GPIO del RP2040 (p. ej., GP2). Programa el registro de configuración del TMP102 para umbrales de alta/baja y lee el pin en MicroPython para actuar (p. ej., imprimir “ALERTA” o activar una salida digital).
• Filtrado y promediado:
• Implementa un promedio móvil de N muestras para suavizar lecturas. Útil para entornos con ruido.
• Cambio de frecuencia I2C:
• Sube a 400 kHz (fast-mode) si las líneas y el breakout lo soportan, ajustando I2C_FREQ = 400_000. Valida estabilidad.
• Otros sensores I2C:
• MCP9808 (mejor resolución y precisión), BME280/BMP280 (temperatura y presión), SHT31 (humedad y temperatura). Cambia la rutina de lectura y la dirección I2C.
• Registro a CSV con timestamp:
• Extiende host_log_temp.py para añadir marca temporal legible (datetime) y escritura de columnas parseadas (solo el valor °C), facilitando graficado con herramientas como LibreOffice Calc o matplotlib.
• Integración con la FPGA (avanzado):
• En ejercicios posteriores, la iCE40UP5K podría implementarse como coprocesador o temporizador para gestionar otras tareas mientras el RP2040 mantiene el I2C. Este caso básico no usa la FPGA para mantener el foco en I2C y MicroPython.
• Envío de datos por USB o UART a otro sistema:
• El RP2040 ya emite por USB‑CDC; puedes añadir un protocolo simple (CSV o JSON de una línea) para integración con aplicaciones Python en el host.
• Auto‑detección de dirección I2C:
• En lugar de fijar TMP102_ADDR, detecta la dirección leyendo la lista de i2c.scan() y seleccionando una dirección válida entre 0x48–0x4B.

Checklist de verificación

• [ ] Raspberry Pi OS Bookworm 64‑bit actualizado y operativo.
• [ ] Python 3.11 verificado en el host (python3 --version).
• [ ] Entorno virtual creado y activado (~/venv-picoice).
• [ ] mpremote 1.22.2 y pyserial 3.5 instalados y verificados.
• [ ] MicroPython 1.22.2 UF2 descargado en ~/pico-ice-i2c-temp/.
• [ ] Pico‑ICE se monta como RPI‑RP2 en modo BOOTSEL y UF2 copiado con éxito.
• [ ] Puerto serie USB‑CDC disponible en /dev/ttyACM0.
• [ ] Sensor TMP102 cableado: VCC→3V3, GND→GND, SDA→GP4, SCL→GP5.
• [ ] main.py subido al RP2040 con mpremote ... fs put.
• [ ] Salida en serie muestra detección de 0x48 y lecturas razonables de temperatura.
• [ ] La temperatura sube al tocar el sensor y baja con frío.
• [ ] Al reiniciar la Pico‑ICE, main.py se ejecuta automáticamente.
• [ ] No hay errores I2C recurrentes ni lecturas erráticas; si aparecen, revisión de cables/pull‑ups/frecuencia I2C.

Apéndice: Comandos clave agrupados

• Actualización del sistema:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

• Habilitar I2C (método rápido no interactivo):

sudo raspi-config nonint do_i2c 0
sudo reboot

• Preparación de venv y herramientas:

sudo apt install -y python3-venv python3-pip git curl i2c-tools
python3 -m venv ~/venv-picoice
source ~/venv-picoice/bin/activate
pip install --upgrade pip
pip install mpremote==1.22.2 pyserial==3.5

• Descarga de MicroPython 1.22.2 UF2:

mkdir -p ~/pico-ice-i2c-temp && cd ~/pico-ice-i2c-temp
curl -L -o micropython-1.22.2-rp2-pico.uf2 https://micropython.org/resources/firmware/micropython-1.22.2-rp2-pico.uf2

• Copiado de UF2 (modo BOOTSEL):

cp micropython-1.22.2-rp2-pico.uf2 /media/pi/RPI-RP2/
sync

• Detección del puerto serie:

dmesg | tail -n 50
ls -l /dev/ttyACM*

• Subida y ejecución de main.py:

mpremote connect list
mpremote connect /dev/ttyACM0 fs put main.py
mpremote connect /dev/ttyACM0 run main.py
mpremote connect /dev/ttyACM0 repl

Este caso práctico te guía, de principio a fin, para leer un sensor de temperatura I2C usando exactamente el modelo Pico-ICE (Lattice iCE40UP5K), con un enfoque de nivel básico y una toolchain concreta: Raspberry Pi OS Bookworm 64‑bit, Python 3.11, MicroPython 1.22.2 en el RP2040, y mpremote 1.22.2/pyserial 3.5 en el host. Conexiones, código y comandos están alineados para reproducibilidad y validación rápida por parte del alumno.

Objective and use case

What you’ll build: This project involves reading temperature data from an MCP9808 I2C temperature sensor using the Pico-ICE board with the RP2040 microcontroller. You will learn to wire the sensor, program the microcontroller, and stream data to a Raspberry Pi.

Why it matters / Use cases

• Real-time temperature monitoring for environmental control in smart homes.
• Integration with IoT applications to track temperature changes and trigger alerts.
• Educational purposes for understanding I2C communication and sensor data acquisition.
• Prototyping for weather stations that require accurate temperature readings.

Expected outcome

• Continuous temperature readings with an accuracy of ±0.5°C.
• Data streamed at a rate of 1 reading per second over USB serial.
• Successful validation of outputs with less than 5% error margin during tests.
• Ability to troubleshoot common issues such as wiring errors or sensor miscommunication.

Audience: Hobbyists, educators, and IoT developers; Level: Intermediate

Architecture/flow: Wiring the MCP9808 sensor to the Pico-ICE, programming the RP2040 to read data, and sending it to a Raspberry Pi for processing.

Basic Hands‑On Practical Case: Raspberry Pi Family — Pico-ICE (Lattice iCE40UP5K) — i2c-lectura-sensor-temperatura

This step‑by‑step exercise guides you through reading temperature over I2C from a digital sensor using the device model “Pico‑ICE (Lattice iCE40UP5K).” We will program the RP2040 microcontroller on the Pico‑ICE to read an I2C temperature sensor (MCP9808) and stream the measurements over USB serial to a Raspberry Pi running Raspberry Pi OS Bookworm 64‑bit with Python 3.11. You will see exact wiring, firmware, Python/MicroPython code, and terminal commands to build, flash, run, and validate.

The emphasis is on the objective “i2c-lectura-sensor-temperatura”: we wire an I2C temperature sensor, read it continuously, validate outputs, and troubleshoot typical pitfalls. No FPGA configuration is required; the iCE40UP5K remains unused in this basic project.

---

Prerequisites

• A Raspberry Pi SBC (e.g., Raspberry Pi 4 Model B or Raspberry Pi 5) running Raspberry Pi OS Bookworm 64‑bit.
• Terminal access to the Raspberry Pi (screen/keyboard locally or SSH).
• Internet access on the Raspberry Pi to install packages and download firmware.
• A known‑good USB‑C data cable for the Pico‑ICE (beware: some cables are power‑only).
• Basic familiarity with the Linux shell and Python virtual environments.

Why the Raspberry Pi OS requirement? We’ll use it as the development and validation host: enabling interfaces, installing tools, creating a virtual environment, and using Python 3.11 to interact over USB serial. The microcontroller‑side code runs in MicroPython on the RP2040 within the Pico‑ICE board.

---

Materials (exact model)

• 1 × Pico‑ICE (Lattice iCE40UP5K) development board (RP2040 + iCE40UP5K).
  Notes:
• It is pin‑compatible with the Raspberry Pi Pico form factor for the microcontroller I/O.

• We will use the RP2040’s I2C0 pins (GP4: SDA, GP5: SCL), 3V3, and GND.

• 1 × MCP9808 I2C temperature sensor breakout (3.3 V compatible).
  Example: “MCP9808 High Accuracy I2C Temperature Sensor Breakout – 3.3/5 V tolerant” with default I2C address 0x18.

• 4–7 × male‑to‑female (or suitable) jumper wires for connections:

• Required: 3V3, GND, SDA, SCL

• Optional: Connect A0/A1/A2 (address select) to GND for default address 0x18 if your breakout does not hard‑tie them.

• 1 × Raspberry Pi SBC with:

• Raspberry Pi OS Bookworm 64‑bit
• Python 3.11 preinstalled
• Network access via Ethernet/Wi‑Fi

---

Setup/Connection

1) Prepare Raspberry Pi OS and user environment

Run the following on your Raspberry Pi terminal:

sudo apt update
sudo apt full-upgrade -y

# Install core tools
sudo apt install -y git curl wget usbutils minicom screen \
  python3-venv python3-pip python3-dev

# Optional but recommended: reboot after upgrade
sudo reboot

After reboot, verify Python 3.11:

python3 --version
# Expect: Python 3.11.x

Create a working directory and Python virtual environment:

mkdir -p ~/pico-ice-i2c-temp
cd ~/pico-ice-i2c-temp
python3 -m venv .venv
source .venv/bin/activate
python -V   # should show Python 3.11.x from the venv

Install Python packages in the venv. We’ll install mpremote (to copy/run MicroPython files), pyserial (for USB serial monitoring), and—following Raspberry Pi family defaults—gpiozero and smbus2/spidev (even though this project does not use the Pi’s own I2C bus):

pip install --upgrade pip
pip install mpremote pyserial gpiozero smbus2 spidev

Give your user serial port access (for /dev/ttyACM* devices the board will expose):

sudo usermod -aG dialout $USER
# Start a new shell or re-login so the new group applies:
newgrp dialout

2) Enable interfaces on Raspberry Pi (family defaults)

Although the sensor connects to the Pico‑ICE, not the Raspberry Pi’s GPIO header, we show how to enable the I2C interface as requested. You will not use it for this project, but it’s good practice to know.

• Using raspi-config:

sudo raspi-config
# Interface Options -> I2C -> Enable
# Finish and reboot if prompted

• Or manually edit /boot/firmware/config.txt:

sudo nano /boot/firmware/config.txt
# Ensure the following line is present (uncomment or add if missing):
# dtparam=i2c_arm=on
# Optionally set the I2C bus speed:
# dtparam=i2c_arm_baudrate=400000
# Save and exit, then reboot if you changed the file:
sudo reboot

Again, the I2C on the Raspberry Pi header is not used in this tutorial. The I2C we use is on the RP2040 inside the Pico‑ICE.

3) Wire the I2C temperature sensor to the Pico‑ICE

We will use the RP2040’s I2C0 default pins: GP4 (SDA), GP5 (SCL). Power the sensor from 3V3. Ground is common.

• Use short jumper wires. The MCP9808 breakout typically includes 10 kΩ pull‑ups; no external pull‑ups needed if your breakout provides them.
• Ensure the sensor board is 3.3 V compatible (MCP9808 is).

Connection mapping:

Notes:
– On Pico‑form‑factor boards, GP4 and GP5 are the default I2C0 pins. The Pico‑ICE follows this arrangement.
– Do not power the sensor with 5 V; the RP2040 and its I/O are 3.3 V only.

---

Full Code

We’ll implement two pieces of code:

1) MicroPython program that runs on the Pico‑ICE (RP2040) and continuously reads temperature from the MCP9808 via I2C, then prints measurements over USB serial.

2) Optional host Python 3.11 script you can run on the Raspberry Pi to read and log those serial prints to CSV for validation.

1) MicroPython code (main.py) for Pico‑ICE (RP2040)

Save the following as main.py on your Raspberry Pi (we’ll upload it to the board in the next section). It initializes I2C0 on GP4/GP5 at 400 kHz, scans for the sensor at 0x18, validates manufacturer/device ID registers, then reads and prints temperature values every second.

# main.py — MicroPython on RP2040 (Pico-ICE)
# Objective: i2c-lectura-sensor-temperatura using MCP9808 at 0x18

from machine import Pin, I2C
import time
import sys

# Pin mapping for Pico-ICE (RP2040) default I2C0 pins
I2C_SDA_PIN = 4  # GP4
I2C_SCL_PIN = 5  # GP5
I2C_FREQ_HZ = 400000

# MCP9808 default I2C address (A2..A0 = 000)
MCP9808_ADDR = 0x18

# MCP9808 register addresses
REG_CONFIG = 0x01
REG_AMBIENT_TEMP = 0x05
REG_MANUF_ID = 0x06   # Expect 0x0054
REG_DEVICE_ID = 0x07  # Expect 0x0400
REG_RESOLUTION = 0x08  # Resolution settings (0..3 => 0.5, 0.25, 0.125, 0.0625 °C)

# LED indicator (on Pico-compatible boards "LED" alias should be available)
try:
    led = Pin("LED", Pin.OUT)
except:
    # Fallback if the alias is not present
    led = Pin(25, Pin.OUT)

def i2c_init():
    i2c = I2C(0, sda=Pin(I2C_SDA_PIN), scl=Pin(I2C_SCL_PIN), freq=I2C_FREQ_HZ)
    return i2c

def i2c_scan_or_fail(i2c):
    devices = i2c.scan()
    print("I2C scan found:", [hex(d) for d in devices])
    if MCP9808_ADDR not in devices:
        print("ERROR: MCP9808 not found at 0x18. Check wiring and address pins A2..A0.")
        sys.exit(1)

def read16(i2c, addr, reg):
    # Read 16 bits (big-endian) from a register
    i2c.writeto(addr, bytes([reg]))
    data = i2c.readfrom(addr, 2)
    return (data[0] << 8) | data[1]

def write8(i2c, addr, reg, val):
    i2c.writeto(addr, bytes([reg, val & 0xFF]))

def read_temp_c(i2c, addr=MCP9808_ADDR):
    # Datasheet: ambient temp register is 16-bit:
    # Bits 15..13 = flags, bit 12 = sign, bits 11..0 = temp*16
    i2c.writeto(addr, bytes([REG_AMBIENT_TEMP]))
    raw = i2c.readfrom(addr, 2)
    t_upper = raw[0]
    t_lower = raw[1]
    val = ((t_upper & 0x1F) << 8) | t_lower
    # Sign extend if negative (bit 12)
    if t_upper & 0x10:
        # 13-bit two's complement
        val -= 1 << 12
    temp_c = val * 0.0625
    return temp_c

def validate_mcp9808(i2c):
    mid = read16(i2c, MCP9808_ADDR, REG_MANUF_ID)
    did = read16(i2c, MCP9808_ADDR, REG_DEVICE_ID)
    print("Manufacturer ID:", hex(mid), "(expect 0x54)")
    print("Device ID:", hex(did), "(expect 0x400)")

    # Soft-check: 0x0054 and 0x0400 expected
    if mid != 0x0054 or did != 0x0400:
        print("WARNING: Unexpected MCP9808 IDs. Double-check sensor model and address.")

def set_resolution(i2c, level=3):
    # Resolution: 0->0.5°C, 1->0.25°C, 2->0.125°C, 3->0.0625°C
    if level < 0 or level > 3:
        level = 3
    write8(i2c, MCP9808_ADDR, REG_RESOLUTION, level)

def main():
    print("Pico-ICE i2c-lectura-sensor-temperatura (MCP9808 @ 0x18)")
    i2c = i2c_init()
    i2c_scan_or_fail(i2c)
    validate_mcp9808(i2c)
    set_resolution(i2c, 3)

    # Blink LED twice to indicate ready
    for _ in range(2):
        led.value(1)
        time.sleep(0.15)
        led.value(0)
        time.sleep(0.15)

    # Main loop: read & print once per second
    while True:
        try:
            t_c = read_temp_c(i2c)
            t_f = t_c * 9 / 5 + 32
            # Structured, parse-friendly line:
            print({"temp_c": round(t_c, 4), "temp_f": round(t_f, 4), "sensor": "MCP9808", "addr": hex(MCP9808_ADDR)})
            led.toggle()
            time.sleep(1.0)
        except Exception as e:
            print("ERROR during read:", repr(e))
            time.sleep(0.5)

if __name__ == "__main__":
    main()

2) Host-side Python (optional) to log USB serial to CSV

This helper script runs on the Raspberry Pi host and captures lines printed by the MicroPython program, writing them to a CSV file with timestamps. It uses pyserial.

Save as host_read.py:

# host_read.py — Read USB serial from Pico-ICE MicroPython and log to CSV
# Usage:
#   source .venv/bin/activate
#   python host_read.py --port /dev/ttyACM0 --csv temps.csv

import argparse
import csv
import json
import sys
import time
import serial

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--port", default="/dev/ttyACM0", help="Serial port (e.g., /dev/ttyACM0)")
    ap.add_argument("--baud", type=int, default=115200, help="Baud (CDC ACM often ignores but keep default)")
    ap.add_argument("--csv", default="temps.csv", help="CSV output path")
    args = ap.parse_args()

    print(f"Opening {args.port} @ {args.baud}")
    with serial.Serial(args.port, args.baud, timeout=2) as ser, open(args.csv, "a", newline="") as f:
        writer = csv.writer(f)
        # Header if file is empty
        if f.tell() == 0:
            writer.writerow(["timestamp_iso", "temp_c", "temp_f", "sensor", "addr", "raw_line"])
        while True:
            line = ser.readline().decode(errors="ignore").strip()
            if not line:
                continue
            now_iso = time.strftime("%Y-%m-%dT%H:%M:%S", time.localtime())
            # Try to parse dict-like output as JSON after replacing single with double quotes
            try:
                jl = json.loads(line.replace("'", '"'))
                temp_c = jl.get("temp_c")
                temp_f = jl.get("temp_f")
                sensor = jl.get("sensor", "")
                addr = jl.get("addr", "")
            except Exception:
                temp_c = ""
                temp_f = ""
                sensor = ""
                addr = ""
            writer.writerow([now_iso, temp_c, temp_f, sensor, addr, line])
            f.flush()
            print(now_iso, line)

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nStopped.")

---

Build/Flash/Run commands

We’ll flash MicroPython to the RP2040 on the Pico‑ICE, then copy main.py to the device, and finally run/use it.

1) Download and flash MicroPython to Pico‑ICE

• Put the Pico‑ICE into BOOTSEL mode:
• Unplug USB‑C.
• Hold the BOOT (BOOTSEL) button on the Pico‑ICE.
• While holding BOOT, plug the USB‑C into your Raspberry Pi.

• Release BOOT after the board enumerates as a USB mass storage device named RPI-RP2.

• Download a stable MicroPython UF2 for the RP2040 (Raspberry Pi Pico compatible). For example (v1.22.2):

cd ~/pico-ice-i2c-temp
wget https://micropython.org/resources/firmware/rp2-pico-20240222-v1.22.2.uf2 -O micropython-pico.uf2

• Copy the UF2 to the RPI-RP2 drive:

If it automounts (typical Desktop), it may appear as /media/pi/RPI-RP2. Otherwise, check with lsblk and mount accordingly.

# If automounted (most cases on RPi Desktop):
cp micropython-pico.uf2 /media/$USER/RPI-RP2/
# After copy completes, the board reboots into MicroPython automatically.

If you are headless and it doesn’t automount, find the device (e.g., /dev/sda1) and mount:

lsblk
# Find the RPI-RP2 (FAT) partition, e.g., /dev/sda1
sudo mkdir -p /mnt/rpi-rp2
sudo mount /dev/sda1 /mnt/rpi-rp2
sudo cp micropython-pico.uf2 /mnt/rpi-rp2/
sync
sudo umount /mnt/rpi-rp2
# The board will reboot into MicroPython.

After reboot, the board should expose a USB serial device, typically /dev/ttyACM0.

List connected MicroPython devices:

source ~/pico-ice-i2c-temp/.venv/bin/activate
mpremote connect list
# Expect something like: /dev/ttyACM0 ...

2) Copy and run your MicroPython script

Copy main.py to the board:

cd ~/pico-ice-i2c-temp
mpremote connect /dev/ttyACM0 fs cp main.py :main.py

Option A: Run immediately (on RAM) to observe:

mpremote connect /dev/ttyACM0 run main.py

Option B: Let it run at boot by keeping the file on the board as main.py. Power‑cycle/unplug/replug the board to auto‑start.

3) View output via serial

Use either minicom or the host Python logger script.

• minicom:

minicom -b 115200 -D /dev/ttyACM0
# To exit minicom: Ctrl-A, then X (Exit).

• Host logger:

source ~/pico-ice-i2c-temp/.venv/bin/activate
python host_read.py --port /dev/ttyACM0 --csv temps.csv

You should see lines like:

{'temp_c': 24.875, 'temp_f': 76.775, 'sensor': 'MCP9808', 'addr': '0x18'}

---

Step‑by‑step Validation

1) Physical wiring checks
– Confirm GP4 ↔ SDA, GP5 ↔ SCL, 3V3 ↔ VIN, and GND ↔ GND.
– If your MCP9808 breakout exposes A0/A1/A2, ensure they are GND or defaulted to select 0x18.

2) Board enumerates and MicroPython is alive
– After flashing the UF2, you should see a /dev/ttyACM* device.
– Run: mpremote connect list. If nothing appears, try another USB port/cable and reflash.

3) I2C scan indicates the sensor
– When running main.py, the program prints “I2C scan found: [‘0x18’]” among the results.
– If the sensor is not listed, the script exits with an error. Recheck SDA/SCL and power.

4) Manufacturer/Device ID check
– Expect:
– Manufacturer ID: 0x54
– Device ID: 0x400
– A mismatch suggests an incompatible sensor or wrong address configuration.

5) Temperature reading plausibility
– Touch the sensor with your finger: temperature should rise a few degrees Celsius within seconds.
– Remove your finger or place an ice pack nearby: temperature should drop.
– Typical indoor ambient: 20–30 °C.

6) Observe LED feedback
– On each successful reading, the onboard LED toggles (blinks once per second). If it stops blinking, the loop likely encountered an error; check the printed error messages.

7) Host logging verification
– Run the host logger:
– python host_read.py –port /dev/ttyACM0 –csv temps.csv
– Confirm CSV entries are appended with timestamp, temp_c, temp_f.

8) Confirm measurement stability
– Leave the setup running for 2–3 minutes.
– The readings should be stable within sensor resolution (0.0625 °C if resolution=3). Minor jitter is normal.

---

Troubleshooting

• No /dev/ttyACM0 appears
• Use lsusb to verify the RP2040 enumerates (look for Raspberry Pi Pico or MicroPython CDC ACM).
• Try a different USB‑C data cable and/or USB port.
• Re‑flash the UF2 via BOOTSEL mode.

• Ensure your user is in the dialout group (newgrp dialout or re-login).

• I2C scan doesn’t show 0x18

• Check wiring order: GP4 must go to SDA, GP5 to SCL.
• Verify the sensor receives 3.3 V (not 5 V).
• If A0/A1/A2 are pulled high on your breakout, the address may differ (0x19..0x1F). Update MCP9808_ADDR in code accordingly.

• Inspect for loose or reversed wires. Keep wires short.

• Manufacturer/Device ID mismatch

• Some clones or different sensors can share similar footprints but different IDs (e.g., TMP102/BME280). Confirm your sensor is MCP9808.

• If you have a different I2C temp sensor, adapt the register map in code.

• Garbled serial output

• Make sure you aren’t running multiple terminal programs (minicom and host_read.py) on the same port simultaneously.

• Close all serial sessions and retry with one program.

• LED doesn’t blink

• Some Pico‑form‑factor derivatives may not expose the LED as Pin(«LED»). The code falls back to Pin(25). If LED still doesn’t work, it may be absent or on a different pin. This does not affect sensor reading; ignore LED errors.

• mpremote cannot connect

• Use mpremote connect list to see the exact device path.

• If using WSL or a USB hub, port naming may change (e.g., /dev/ttyACM1). Update commands accordingly.

• spidev/gpiozero installation warnings

• The project doesn’t use them directly. They are included to satisfy family defaults. If pip install shows warnings, ensure python3-dev is installed (we installed it above). Alternatively, install system packages via apt (e.g., sudo apt install python3-spidev python3-gpiozero) and skip pip for those.

---

Improvements

• Add on‑board display or status LED pattern

• Drive an external LED or a small I2C SSD1306 OLED to show temperature locally without a serial console.

• Timestamping and averaging

• Compute a moving average to reduce jitter, and print both instantaneous and averaged temperature values.

• Logging enhancements

• The host script can rotate logs daily, or emit Prometheus‑style metrics. Use systemd to run it at boot.

• Calibration and offsets

• Apply a small offset determined by comparison with a reference thermometer if absolute accuracy is important.

• Power optimization

• Reduce I2C frequency or sampling rate; put the MCU in low‑power sleep between reads if powered from battery.

• Use interrupts or alert outputs

• The MCP9808 has alert pins; configure thresholds in REG_CONFIG and related registers to signal over/under‑temperature without constant polling.

• Integrate the FPGA (future intermediate/advanced)

• Use the iCE40UP5K to timestamp events, buffer samples via SPI or PIO bridge, or implement a simple display/driver; then exchange data with RP2040 via PIO/PIO‑SPI/I2C bridging.

• Support multiple I2C sensors

• If you have several MCP9808 devices, set A0/A1/A2 to different addresses (0x18–0x1F), scan them, and print each.

• Alternative sensors

• Adapt code for TMP102, BME280, or SHT31 if those are the devices you have. Pin wiring remains SDA/SCL/3V3/GND; only register maps change.

---

Final Checklist

• Hardware
• Pico‑ICE (Lattice iCE40UP5K) is connected via USB‑C to the Raspberry Pi.
• MCP9808 breakout wired: 3V3 ↔ VIN, GND ↔ GND, GP4 ↔ SDA, GP5 ↔ SCL; A0/A1/A2 defaulted to GND.

• Cables are short and secure; no 5 V to sensor.

• Raspberry Pi OS Bookworm 64‑bit and Python 3.11

• System updated (sudo apt update && sudo apt full-upgrade).
• python3 –version shows Python 3.11.x.

• Virtual environment created and activated in ~/pico-ice-i2c-temp/.venv.

• Packages and interfaces

• pip installed: mpremote, pyserial, gpiozero, smbus2, spidev.
• User added to dialout group (serial access).

• I2C enabled on Raspberry Pi (family default; not used by this project).

• MicroPython flashed

• rp2‑pico MicroPython v1.22.2 UF2 copied to RPI-RP2 via BOOTSEL.

• /dev/ttyACM0 appears; mpremote connect list shows device.

• Application code deployed

• main.py uploaded via mpremote fs cp main.py :main.py.

• Program runs and prints periodic temperature lines.

• Validation complete

• I2C scan shows 0x18.
• Manufacturer ID 0x54 and Device ID 0x400 printed.
• Temperature increases when touching sensor; decreases with cooling.

• Optional host_read.py logs to temps.csv successfully.

• Troubleshooting resolved

• Any serial or wiring issues addressed per the troubleshooting section.

You now have a working i2c-lectura-sensor-temperatura project using the Pico‑ICE (Lattice iCE40UP5K) board, entirely validated with Raspberry Pi OS Bookworm 64‑bit and Python 3.11.

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.

Objective and use case

What you’ll build: Control LED brightness using PWM on the Pico-ICE board with Raspberry Pi, allowing for interactive adjustments from a host device.

Why it matters / Use cases

• Demonstrate real-time control of LED brightness in IoT applications using Raspberry Pi and MicroPython.
• Utilize PWM for efficient LED dimming, which is crucial for energy-saving in smart lighting systems.
• Provide a foundational understanding of GPIO interfacing and PWM signal generation for beginners in embedded systems.
• Enable interactive projects where users can adjust lighting conditions based on environmental factors.

Expected outcome

• Achieve LED brightness control from 0% to 100% with a response time of less than 100ms.
• Validate successful communication between the Raspberry Pi and Pico-ICE via USB-serial interface.
• Measure power consumption reduction when using PWM compared to constant current methods.
• Document troubleshooting steps for common issues encountered during setup and operation.

Audience: Beginners in embedded systems; Level: Basic

Architecture/flow: Raspberry Pi (host) communicates with Pico-ICE (RP2040) via USB-serial to control LED brightness using PWM.

Practical Case: PWM LED Brightness Control (“control-brillo-led-pwm”) on Pico-ICE (Lattice iCE40UP5K)

This hands‑on project uses the Raspberry Pi device family with the exact model Pico‑ICE (Lattice iCE40UP5K). The Pico‑ICE board includes an RP2040 microcontroller in a Raspberry Pi Pico–compatible form factor plus an on‑board Lattice iCE40UP5K FPGA. For this Basic‑level exercise, we’ll drive an LED’s brightness using PWM on the RP2040 and control it interactively from a Raspberry Pi host running Raspberry Pi OS Bookworm 64‑bit and Python 3.11.

You will:

• Flash MicroPython to the Pico‑ICE (RP2040).
• Wire an external LED with a resistor to a single GPIO pin.
• Run MicroPython code that exposes a simple USB‑serial interface for brightness commands (0–100%).
• Validate operation from the Raspberry Pi host using Python and terminal tools.
• Learn how to troubleshoot common issues and extend the design.

Note: In this Basic project we do not program the Lattice iCE40UP5K FPGA; we focus on RP2040 PWM. The FPGA remains unused here and can be explored in the Improvements section later.

---

Prerequisites

• A Raspberry Pi host computer (e.g., Raspberry Pi 4B/400/5) with:
• Raspberry Pi OS Bookworm 64‑bit installed
• Python 3.11
• Internet access

• A free USB‑A port (or a USB‑C hub on Pi 5)

• Comfort with the Linux command line on the Pi.

• Basic breadboarding skills (placing an LED and resistor, making GND and GPIO connections).

• You must be able to connect to your Raspberry Pi:

• Locally with keyboard/monitor, or
• Remotely via SSH.

Verify OS and Python versions

Run these commands on your Raspberry Pi host:

uname -a
cat /etc/os-release
python3 --version

You should see Raspberry Pi OS Bookworm and Python 3.11.x.

Example (versions may differ slightly):
– PRETTY_NAME=»Debian GNU/Linux 12 (bookworm)»
– Python 3.11.2

---

Materials (Exact Model Specified)

• 1× Pico‑ICE (Lattice iCE40UP5K) board (RP2040 + iCE40UP5K, USB‑C)
• 1× USB‑C data cable (to connect Pico‑ICE to Raspberry Pi)
• 1× 5 mm LED (any color)
• 1× 330 Ω resistor (¼ W)
• 1× Breadboard (mini is fine)
• 2–3× Male‑to‑male jumper wires

Optional for debugging:
– USB power meter or a known good USB‑C data cable
– Multimeter

---

Setup/Connection

We’ll use a single RP2040 GPIO pin to drive an LED with PWM. The Pico‑ICE follows the Raspberry Pi Pico header labels; we will use the pin labelled GP15 and any GND pin.

Important notes:
– Always place the resistor in series with the LED to limit current.
– LED polarity matters: the longer lead is the anode (+); the flat side/shorter lead is the cathode (−) to GND.

Wiring Plan (text‑only, no drawings)

• Connect Pico‑ICE GP15 to one leg of the 330 Ω resistor.
• Connect the other leg of the resistor to the LED anode (+).
• Connect the LED cathode (−) to a GND pin on the Pico‑ICE.

Connection Table

If you prefer another GPIO, you can change it later in the code, but keep to a pin that supports PWM (most RP2040 GPIOs do).

---

Enabling Interfaces on Raspberry Pi OS (Bookworm)

This project primarily uses the USB CDC serial interface that MicroPython exposes; it does not require the Pi’s 40‑pin GPIO. However, we’ll show how to enable useful interfaces and SSH for general development.

Using raspi-config

sudo raspi-config

• Interface Options:
• I2C: Enable (optional, not used here)
• SPI: Enable (optional, not used here)
• Serial Port: Enable serial interface but disable login shell over serial (this avoids conflicts on UART; USB CDC is separate, but it’s a good practice)
• SSH: Enable (if you intend to work remotely)

Finish and reboot when prompted.

Alternative: Editing /boot/firmware/config.txt

If you prefer manual configuration, you can add or confirm the following lines (optional features):

sudo nano /boot/firmware/config.txt

Append (only if needed; these are optional and safe):

dtparam=i2c_arm=on
dtparam=spi=on
enable_uart=1

Save and reboot:

sudo reboot

---

Python Environment and Tools on the Raspberry Pi Host

We will:
– Install system tools with apt (picotool, minicom, gpiozero, spidev).
– Create a Python 3.11 virtual environment.
– Install packages with pip (pyserial, mpremote, smbus2).

Run:

sudo apt update
sudo apt install -y python3-venv python3-pip python3-gpiozero python3-spidev picotool minicom curl wget unzip

Create and activate a venv for project scripts:

python3 -m venv ~/picoice-pwm-venv
source ~/picoice-pwm-venv/bin/activate
pip install --upgrade pip
pip install pyserial mpremote smbus2

Note:
– gpiozero and spidev are installed via apt; we won’t use them directly in this project but they are commonly used in Raspberry Pi tutorials.
– smbus2 is installed via pip because it may not be available as a Debian package under the same name. It’s not required for this project but can be useful later.

---

Flash MicroPython onto Pico‑ICE (RP2040)

We’ll install the official MicroPython UF2 for the RP2040 (Raspberry Pi Pico). The Pico‑ICE is Pico‑compatible on the microcontroller side, so use the “rp2-pico” build.

1) Download a known stable MicroPython UF2:

mkdir -p ~/picoice-fw && cd ~/picoice-fw
wget https://micropython.org/resources/firmware/rp2-pico-20240224-v1.22.2.uf2 -O micropython-pico-v1.22.2.uf2

2) Put Pico‑ICE into BOOTSEL mode:
– Unplug the USB‑C cable from Pico‑ICE.
– Press and hold the BOOTSEL button on the board.
– While holding BOOTSEL, plug the USB‑C into the Raspberry Pi.
– Release BOOTSEL after the storage device appears on the Pi (mounted as RPI-RP2).

3) Copy the UF2:

Identify the mount path (usually /media/$USER/RPI-RP2):

ls /media/$USER
ls /media/$USER/RPI-RP2

Copy the firmware:

cp ~/picoice-fw/micropython-pico-v1.22.2.uf2 /media/$USER/RPI-RP2/
sync

The board will automatically reboot into MicroPython; the mass‑storage device will disappear and a USB CDC serial device will appear (typically /dev/ttyACM0).

4) Verify with picotool (optional but recommended):

Unplug and replug the Pico‑ICE normally (no BOOTSEL). Then:

picotool info -a

If picotool can’t read while MicroPython is running, re‑enter BOOTSEL mode temporarily and run picotool; otherwise proceed.

---

Full Code

We will use two small programs:

1) main.py (MicroPython on Pico‑ICE): Sets up PWM on GP15 and listens for brightness commands (0–100) over USB serial. It prints status messages so you can validate from the host.
2) host_send_brightness.py (Python 3 on Raspberry Pi): Sends a sequence of brightness values over /dev/ttyACM0 to demonstrate control.

1) MicroPython firmware (main.py) for Pico‑ICE

Save this as main.py on your Raspberry Pi host (we’ll transfer it to the Pico‑ICE in the next section):

# main.py (MicroPython for RP2040 on Pico-ICE)
# Objective: control-brillo-led-pwm (PWM LED brightness control)
#
# - Uses GP15 as PWM output to drive LED brightness with a 330 ohm resistor to LED anode, LED cathode to GND.
# - Listens for integers 0..100 over USB serial (CDC) and adjusts brightness percentage.
# - If no command is received for a while, it keeps the last brightness.
#
# Tested with MicroPython v1.22.2 (RP2 Pico build).

from machine import Pin, PWM
import sys
import time

PWM_PIN = 15       # GP15
PWM_FREQ = 1000    # 1 kHz is flicker-free for most use cases
MAX_DUTY = 65535

pwm = PWM(Pin(PWM_PIN))
pwm.freq(PWM_FREQ)

def set_brightness(percent: int):
    # clamp to 0..100
    if percent < 0:
        percent = 0
    if percent > 100:
        percent = 100
    duty = int(percent * MAX_DUTY / 100)
    pwm.duty_u16(duty)
    return percent

# Start with low brightness (10%)
current = set_brightness(10)
print("READY: PWM on GP%d at %d Hz. Type 0..100 + Enter to set brightness." % (PWM_PIN, PWM_FREQ))
print("Current brightness: %d%%" % current)
print("Example: 0, 25, 50, 75, 100")

buffer = b""
last_print = time.ticks_ms()

while True:
    # Non-blocking read from stdin; we read one byte at a time
    if sys.stdin in (None,):
        # USB not ready; small delay and continue
        time.sleep(0.05)
        continue

    # Try to read available bytes
    try:
        b = sys.stdin.buffer.read(1)
    except Exception:
        b = None

    if b:
        if b in (b'\r', b'\n'):
            line = buffer.strip().decode('utf-8', errors='ignore')
            buffer = b""
            if line:
                try:
                    val = int(line)
                    current = set_brightness(val)
                    print("OK: brightness set to %d%%" % current)
                except ValueError:
                    print("ERR: invalid input '%s'. Send integer 0..100." % line)
        else:
            buffer += b

    # Periodic heartbeat message every 10 seconds so host can see we are alive
    now = time.ticks_ms()
    if time.ticks_diff(now, last_print) > 10000:
        print("STATUS: brightness=%d%%" % current)
        last_print = now

    time.sleep(0.01)

Key features:
– PWM at 1 kHz on GP15.
– Accepts human‑readable integers (0–100) via USB‑serial.
– Periodic status messages every 10 seconds.

2) Host script (host_send_brightness.py) for Raspberry Pi

This script opens the serial port exposed by MicroPython and sends a deterministic brightness sweep. Save this next to your main.py on the Pi host:

# host_send_brightness.py
# Send brightness percentages to Pico-ICE MicroPython over USB CDC (/dev/ttyACM0)
#
# Requires: pip install pyserial

import sys
import time
import serial

PORT = "/dev/ttyACM0"  # adjust if different
BAUD = 115200          # MicroPython USB CDC ignores baud but pyserial needs a value
TIMEOUT = 1.5

def open_port():
    return serial.Serial(PORT, BAUD, timeout=TIMEOUT)

def read_available(ser):
    # Non-blocking read of any available text
    try:
        text = ser.read(ser.in_waiting or 1).decode(errors='ignore')
        if text:
            sys.stdout.write(text)
            sys.stdout.flush()
    except Exception:
        pass

def send_value(ser, val):
    line = f"{val}\n".encode()
    ser.write(line)
    ser.flush()
    time.sleep(0.2)
    read_available(ser)

def main():
    print(f"Opening serial port {PORT} ...")
    with open_port() as ser:
        # Give device a moment to (re)enumerate
        time.sleep(1.0)
        # Flush any previous prints from the device
        read_available(ser)

        # Sweep: 0, 25, 50, 75, 100, 75, 50, 25, 0
        pattern = [0, 25, 50, 75, 100, 75, 50, 25, 0]
        for val in pattern:
            print(f"\n>>> Sending {val}%")
            send_value(ser, val)
            time.sleep(0.8)

        print("\nDone. Reading a few more messages...")
        for _ in range(10):
            read_available(ser)
            time.sleep(0.25)

if __name__ == "__main__":
    main()

---

Build/Flash/Run Commands

We will use mpremote to copy main.py to the MicroPython filesystem on the Pico‑ICE, then run the host script.

1) Confirm the Pico‑ICE USB device:

Plug the Pico‑ICE into the Raspberry Pi (normal boot, not BOOTSEL). Then:

dmesg | tail -n 20
ls -l /dev/ttyACM*

You should see something like /dev/ttyACM0.

2) List devices with mpremote:

source ~/picoice-pwm-venv/bin/activate
mpremote connect list

Expect a line such as:
– /dev/ttyACM0

3) Copy main.py to the board and reset:

Assuming your main.py is in ~/picoice-fw or current directory:

cd ~/picoice-fw
mpremote connect /dev/ttyACM0 fs cp main.py :main.py
mpremote connect /dev/ttyACM0 reset

After reset, the MicroPython script will auto‑run if it’s named main.py at the root of the device filesystem. The device should start printing “READY…” and “STATUS…” over USB‑serial.

4) Observe output using minicom (optional):

sudo usermod -aG dialout $USER
newgrp dialout
minicom -b 115200 -o -D /dev/ttyACM0

You should see the “READY” banner. Exit with Ctrl‑A, then X, then Yes.

5) Run the host script to send brightness commands:

cd ~/picoice-fw
python3 host_send_brightness.py

Watch the LED change in perceptible steps as the script prints device responses (OK: brightness set to …). If you’re connected via minicom at the same time, close it first so only one program accesses the serial device.

---

Step‑by‑Step Validation

Follow this sequence to validate both the electrical and software paths:

1) Physical wiring check:
– Confirm GP15 is wired to the resistor, resistor to LED anode, LED cathode to GND.
– Confirm the resistor is in series, not parallel.
– Confirm LED orientation (long lead/anode toward GPIO via resistor, short lead/cathode to GND).

2) Power and enumeration:
– Connect Pico‑ICE via USB‑C to the Raspberry Pi.
– Run: ls -l /dev/ttyACM* and confirm a port exists (e.g., /dev/ttyACM0).
– If missing, reseat the cable, try a different port, or try a different cable known to be a data cable.

3) Firmware presence:
– If you see repeated resets or no serial, re‑flash MicroPython UF2 (BOOTSEL method) and try again.
– Optionally validate with picotool info -a while in BOOTSEL.

4) MicroPython program deployment:
– mpremote connect /dev/ttyACM0 fs cp main.py :main.py
– mpremote connect /dev/ttyACM0 reset
– The LED should light dimly at startup (10% default). If it’s dark, try 100% via the host script; if always dark, reverse LED orientation.

5) Serial output:
– Use minicom -b 115200 -o -D /dev/ttyACM0 to confirm the device prints:
– READY: PWM on GP15 at 1000 Hz…
– Current brightness: 10%
– STATUS: brightness=10% every ~10 seconds
– Exit minicom before running the Python host script.

6) Host script test:
– python3 host_send_brightness.py
– Observe LED brightness changes in discrete steps: 0%, 25%, 50%, 75%, 100%, then back down.
– The terminal should show “OK: brightness set to …” messages echoed from the microcontroller.

7) Manual control:
– Use mpremote to interactively send values:
– mpremote connect /dev/ttyACM0 repl
– Press Ctrl‑C to interrupt the script, then type:
– import sys
– sys.stdin won’t be used here since you’re in REPL; instead, exit REPL (Ctrl‑X) and use minicom/host script to send plain integers.

Alternatively, echo a value directly from Linux:
– printf "75
" | sudo tee /dev/ttyACM0
– LED should jump to ~75% brightness.

8) Edge cases:
– Send invalid input (e.g., “hello”) via minicom:
– Expect ERR: invalid input 'hello'. Send integer 0..100.
– Send out‑of‑range (e.g., 150):
– Expect it to clamp to 100% and print OK: brightness set to 100%.

If all the above work, the “control‑brillo‑led‑pwm” objective is met.

---

Troubleshooting

• No /dev/ttyACM0 appears:
• Try a different USB‑C cable (some are power‑only).
• Try a different USB port on the Raspberry Pi.
• Check dmesg | tail -n 50 for USB enumeration errors.
• Reflash MicroPython via BOOTSEL.

• Ensure user is in dialout group: sudo usermod -aG dialout $USER then newgrp dialout.

• minicom cannot open the port:

• Ensure no other process is using /dev/ttyACM0 (only one program can open it).

• Close Thonny, mpremote, or any other serial session.

• LED never lights:

• Reverse LED orientation; double‑check the resistor is in series.
• Verify you used the correct GPIO label (GP15) and not a different pad.

• From the MicroPython REPL (Ctrl‑C), try a quick test:
  from machine import Pin, PWM
p=PWM(Pin(15)); p.freq(1000); p.duty_u16(65535) # full brightness
  If it lights, your hardware is fine; the issue may be with the program not running or serial not sending values.

• LED is always on full brightness or flickers:

• Check for shorts on the breadboard or misplacement of resistor.

• Lower or raise PWM frequency if you observe perceptible flicker:

  • In main.py, change PWM_FREQ to 500 or 2000 and re‑copy.

• mpremote copy fails:

• Confirm the port with mpremote connect list.
• Unplug/replug the device.

• Try mpremote connect /dev/ttyACM0 mount . to run the local file temporarily:
  mpremote connect /dev/ttyACM0 mount .
mpremote connect /dev/ttyACM0 run main.py

• Serial input not recognized:

• Ensure you send a newline ‘
  ’ after the integer (minicom adds it when you press Enter).

• Use the host script which formats the commands correctly.

• Performance and power:

• The LED current should be below 10–12 mA. With 330 Ω and a typical red LED at ~2 V drop, current is about (3.3 V − 2.0 V) / 330 ≈ 3.9 mA, safe for the RP2040 pin.

---

Improvements

• Smooth “breathing” effect:

• Modify main.py to implement a non‑blocking fade when no commands are received. For example, increment duty every 10 ms modulo MAX_DUTY and accept interactive overrides.

• Multiple LEDs on different PWM slices:

• Drive several GPIO pins (e.g., GP14, GP15, GP16) with independent PWM objects to mix colors from separate LEDs.

• Read a potentiometer to control brightness:

• Connect a 10 kΩ potentiometer to an ADC input (e.g., GP26/ADC0) and map the analog value to PWM duty. Use MicroPython’s machine.ADC.

• Tie‑in the FPGA (iCE40UP5K):

• Use the RP2040 to stream duty cycle values to the FPGA and implement PWM generation in programmable logic for deterministic timing or multi‑channel control.

• Program the FPGA via open‑source toolchains (nextpnr‑ice40, yosys) once comfortable. For Basic level, treat this as a future exercise.

• Host UI:

• Build a simple Tkinter or web UI (Flask) on the Raspberry Pi to send brightness commands. The host could provide sliders and store presets.

• Logging and metrics:

• Parse the “STATUS” lines on the host to record usage over time, or extend the protocol to include frequency and duty queries.

• Safety and robustness:

• Add bounds checking, watchdog timers, and a defined reset brightness.
• Implement a CRC or checksum if you expand to structured multi‑byte commands.

---

Final Checklist

• Raspberry Pi host:
• Raspberry Pi OS Bookworm 64‑bit verified.
• Python 3.11 available.
• Interfaces enabled as needed (SSH, Serial disabled login shell).
• Virtual environment created: ~/picoice-pwm-venv.

• Packages installed:

  • apt: python3-venv, python3-pip, python3-gpiozero, python3-spidev, picotool, minicom
  • pip (inside venv): pyserial, mpremote, smbus2

• Pico‑ICE (Lattice iCE40UP5K):

• MicroPython flashed via UF2 (v1.22.2 used in this guide).
• Appears as /dev/ttyACM0 under normal boot.

• main.py deployed to the device via mpremote.

• Hardware connections:

• GP15 → 330 Ω → LED anode; LED cathode → GND.

• USB‑C cable is known good (data‑capable).

• Validation:

• READY and STATUS messages visible via minicom or host script.
• host_send_brightness.py cycles brightness 0–100% correctly.

• Manual values entered in minicom change brightness immediately.

• Troubleshooting performed if needed:

• Checked cable, port, permissions, LED orientation, resistor, and MicroPython state.
• Verified no serial conflicts.

With these steps, you have a working “control‑brillo‑led‑pwm” implementation on the Raspberry Pi family using the exact model Pico‑ICE (Lattice iCE40UP5K), centered on RP2040 PWM control with clear code, connections, and validation workflow.

Objetivo y caso de uso

Qué construirás: Un sistema de comunicación UART entre la FPGA Pico-ICE y una Raspberry Pi, permitiendo el envío de mensajes de bajo consumo.

Para qué sirve

• Intercambio de datos entre dispositivos de bajo consumo en aplicaciones IoT.
• Control de sensores conectados a la Raspberry Pi mediante comandos UART desde la FPGA.
• Implementación de un sistema de eco para pruebas de comunicación en tiempo real.
• Desarrollo de prototipos de comunicación en proyectos de robótica.

Resultado esperado

• Latencia de comunicación menor a 10 ms entre la FPGA y la Raspberry Pi.
• Capacidad de enviar y recibir hasta 115200 bps sin pérdida de datos.
• Consumo de energía inferior a 50 mW durante la operación de transmisión.
• Mensajes de eco recibidos en la Raspberry Pi con un 99% de precisión.

Público objetivo: Desarrolladores y estudiantes de electrónica; Nivel: básico

Arquitectura/flujo: Comunicación UART desde la FPGA Pico-ICE a la Raspberry Pi, utilizando Python para el procesamiento de datos.

Nivel: basico

Prerrequisitos

Sistema operativo y entorno base

• Raspberry Pi OS Bookworm 64-bit (kernel y userland de 64 bits).
• Raspberry Pi 4/400/5 con puertos USB tipo A (host).
• Python 3.11 (incluido en Raspberry Pi OS Bookworm 64-bit).

Asegúrate de que tu sistema está actualizado:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

Toolchain exacta para FPGA y utilidades

Para sintetizar, colocar y enrutar en el iCE40UP5K de la Pico-ICE usaremos la OSS CAD Suite, que trae todo integrado (Yosys, nextpnr-ice40, icestorm):

• OSS CAD Suite (aarch64 / ARM64) versión: 2024-10-01
• yosys (incluido en el bundle 2024-10-01)
• nextpnr-ice40 (incluido en el bundle 2024-10-01)
• icestorm: icepack/iceprog (incluidos en el bundle 2024-10-01)

Instalación en /opt/oss-cad-suite:

# 1) Descarga la OSS CAD Suite (ARM64) 2024-10-01
cd /tmp
curl -LO https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2024-10-01/oss-cad-suite-linux-arm64-20241001.tgz

# 2) Descomprime en /opt (requiere sudo)
sudo mkdir -p /opt
sudo tar -xzf oss-cad-suite-linux-arm64-20241001.tgz -C /opt

# 3) Crea un enlace conveniente
sudo ln -sfn /opt/oss-cad-suite /opt/oss-cad-suite-2024-10-01

# 4) Exporta PATH para la sesión actual
export PATH=/opt/oss-cad-suite-2024-10-01/bin:$PATH

# 5) Opcional: añade a tu ~/.bashrc para que quede persistente:
echo 'export PATH=/opt/oss-cad-suite-2024-10-01/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 6) Verifica versiones
yosys -V
nextpnr-ice40 --version
iceprog -v

Nota: Si cambias la versión en el futuro, actualiza el path simbólico y el PATH en consecuencia.

Habilitar interfaces en Raspberry Pi OS (UART)

En este caso usaremos el UART por GPIO del Raspberry Pi para hablar con la FPGA (eco). Debes:
1) Desactivar la consola por serie.
2) Activar el puerto serie (UART) para uso general.

Con raspi-config:

sudo raspi-config
# Interface Options -> Serial Port
# - "Would you like a login shell to be accessible over serial?" -> No
# - "Would you like the serial port hardware to be enabled?" -> Yes
# Finish -> Reboot

O editando /boot/firmware/config.txt:

sudo nano /boot/firmware/config.txt
# Asegúrate de tener:
enable_uart=1

# Guarda y reinicia
sudo reboot

Después del reinicio, el UART principal estará accesible como /dev/serial0 (en Pi 4/5 suele apuntar a /dev/ttyAMA0 o /dev/ttyS0 según la configuración interna).

Entorno Python 3.11 con venv y librerías

Crearemos un entorno virtual para scripts de validación por serie y, ya que estamos en Raspberry Pi, dejaremos listos paquetes típicos:

sudo apt install -y python3-venv python3-dev python3-pip \
                    minicom screen git
# gpiozero depende de RPi.GPIO o lgpio según el modelo; instalaremos por pip
# (pyserial lo usaremos para la validación UART)
python3 -m venv ~/venvs/picoice
source ~/venvs/picoice/bin/activate

pip install --upgrade pip
pip install pyserial==3.5 gpiozero==1.6.2 smbus2==0.5.3 spidev==3.6

# Verifica
python -c "import sys,serial; print(sys.version); print(serial.__version__)"
deactivate

• Python: 3.11.x (sistema).
• pyserial: 3.5
• gpiozero: 1.6.2
• smbus2: 0.5.3
• spidev: 3.6

Estas librerías no todas se usarán en este caso concreto, pero el entorno queda listo para prácticas futuras (GPIO, I2C, SPI).

Materiales

• 1 × Raspberry Pi 4/400/5 con Raspberry Pi OS Bookworm 64‑bit y acceso a Internet.
• 1 × Tarjeta microSD (≥16 GB) con Raspberry Pi OS Bookworm 64-bit.
• 1 × Placa “Pico-ICE (Lattice iCE40UP5K)”. Modelo exacto: Pico-ICE (FPGA iCE40UP5K).
• 1 × Cable USB-A a Micro‑USB o USB-C (según la revisión de tu Pico-ICE; revisa la serigrafía). Se usa para programación del FPGA a través del RP2040 onboard.
• 3 × Cables Dupont macho‑hembra para conectar UART GPIO del Raspberry Pi a dos pines IO del FPGA + GND.
• Opcional pero recomendable: 1 × Adaptador USB-UART (FT232/CP2102) como alternativa al UART por GPIO del Raspberry Pi.
• 1 × Multímetro básico y/o analizador lógico (opcional) para validación adicional.

Nota: La Pico-ICE integra un RP2040 que actúa como programador del FPGA; no necesitamos JTAG externo.

Preparación y conexión

Disposición general

• USB del Raspberry Pi a la Pico-ICE: para programar el bitstream (iceprog detecta el programador USB del RP2040 de la Pico-ICE).
• UART por GPIO del Raspberry Pi a dos IO de la FPGA:
• TX del Raspberry Pi (GPIO14) → RX del FPGA (señal uart_rx en el diseño).
• RX del Raspberry Pi (GPIO15) → TX del FPGA (señal uart_tx en el diseño).
• GND ↔ GND común.

Asegúrate de que todos los niveles lógicos son 3.3 V (tanto el Raspberry Pi como el iCE40UP5K trabajan a 3.3 V en sus bancos de IO).

Tabla de pines Raspberry Pi para UART

Pines de la Pico-ICE (lado FPGA)

• La Pico-ICE expone IO del iCE40UP5K en cabeceras/PMODs. Consulta la serigrafía de tu placa y el fichero de constraints (PCF) del fabricante.
• Elegiremos dos IO contiguos de un conector (por ejemplo, PMOD A) para UART:
• FPGA: IO_UART_RX (entrada al FPGA) → conéctalo al TX de la Pi (GPIO14).
• FPGA: IO_UART_TX (salida del FPGA) → conéctalo al RX de la Pi (GPIO15).
• GND a GND.

Si tu repositorio de la placa trae un PCF con alias de conector (p. ej., PMODA1, PMODA2), usaremos esos alias para asignar “uart_rx” y “uart_tx” sin tener que recordar nombres de bolas del encapsulado.

Ejemplo de conexión (texto, sin esquema):
– Cable 1: Raspberry Pi Pin 8 (GPIO14, TXD) → Pico-ICE PMOD A pin 1 (IO_UART_RX).
– Cable 2: Raspberry Pi Pin 10 (GPIO15, RXD) → Pico-ICE PMOD A pin 2 (IO_UART_TX).
– Cable 3: Raspberry Pi Pin 6 (GND) → Pico-ICE GND.

Verifica que el conector PMOD y el GND estén claramente identificados en tu placa.

Código completo (HDL para el FPGA iCE40UP5K)

Objetivo “uart-hello-world-eco”:
– Al arrancar, el FPGA envía “Hello, world!” por UART a 115200 baudios, 8N1.
– Después, hace eco de todo lo que recibe (devuelve el mismo byte).
– Opcional: parpadea el LED RGB en cada retorno de línea para validar visualmente.

Notas de reloj/baudio:
– Usaremos el oscilador interno SB_HFOSC del iCE40UP5K.
– Configuraremos el HFOSC a ~12 MHz (dividiendo por 4 el nominal 48 MHz).
– Baudrate: 115200 → divisor ≈ clk/baud = 12e6 / 115200 ≈ 104.166. Usaremos 104 (pequeño error aceptable para 8N1 a 115200).
– Para robustez, el receptor usa muestreo a mitad de bit con un tick a “baud × 16” usando un divisor adicional. Mantendremos una implementación simple y didáctica.

Estructura de archivos:
– rtl/top.v (top-level con HFOSC, UART TX/RX, lógica de eco).
– rtl/uart_tx.v (transmisor UART).
– rtl/uart_rx.v (receptor UART).

rtl/uart_tx.v

// Transmisor UART simple: 8N1, LSB-first
// Genera un tick a "baud" desde un reloj de sistema.
// Entradas:
//  - clk: reloj de sistema
//  - resetn: reset activo en bajo
//  - baud_tick: pulso 1clk a la frecuencia de baudios
//  - data[7:0], data_valid: carga de dato
// Salidas:
//  - tx: línea UART
//  - busy: transmisor ocupado
module uart_tx (
    input  wire clk,
    input  wire resetn,
    input  wire baud_tick,
    input  wire [7:0] data,
    input  wire data_valid,
    output reg  tx,
    output reg  busy
);
    reg [3:0] bit_idx;
    reg [9:0] shifter;

    always @(posedge clk) begin
        if (!resetn) begin
            tx      <= 1'b1; // idle alto
            busy    <= 1'b0;
            bit_idx <= 4'd0;
            shifter <= 10'h3FF;
        end else begin
            if (!busy) begin
                if (data_valid) begin
                    // start(0), 8 datos LSB-first, stop(1)
                    shifter <= {1'b1, data, 1'b0};
                    bit_idx <= 4'd0;
                    busy    <= 1'b1;
                end
            end else begin
                if (baud_tick) begin
                    tx      <= shifter[0];
                    shifter <= {1'b1, shifter[9:1]}; // shift right, relleno con '1' (stop)
                    bit_idx <= bit_idx + 4'd1;
                    if (bit_idx == 4'd9) begin
                        busy <= 1'b0;
                        tx   <= 1'b1; // volver a idle
                    end
                end
            end
        end
    end
endmodule

rtl/uart_rx.v

// Receptor UART simple: 8N1, LSB-first
// Usa "oversampling_tick" 16x para muestrear en el centro de cada bit.
// Entradas:
//  - clk, resetn
//  - oversampling_tick: pulso a "baud*16"
//  - rx: línea UART
// Salidas:
//  - data[7:0], data_ready: byte recibido listo (1 pulso)
module uart_rx (
    input  wire clk,
    input  wire resetn,
    input  wire oversampling_tick,
    input  wire rx,
    output reg  [7:0] data,
    output reg  data_ready
);
    localparam OVERSAMPLE = 16;
    reg [3:0] sample_cnt;
    reg [3:0] bit_idx;
    reg [7:0] rx_shift;
    reg       busy;
    reg       rx_sync;

    // Sincronizar RX a clk
    reg rx_meta;
    always @(posedge clk) begin
        rx_meta <= rx;
        rx_sync <= rx_meta;
    end

    always @(posedge clk) begin
        if (!resetn) begin
            sample_cnt <= 4'd0;
            bit_idx    <= 4'd0;
            rx_shift   <= 8'h00;
            busy       <= 1'b0;
            data       <= 8'h00;
            data_ready <= 1'b0;
        end else begin
            data_ready <= 1'b0; // pulso de un ciclo

            if (!busy) begin
                // Detecta start bit (flanco alto->bajo)
                if (!rx_sync) begin
                    busy       <= 1'b1;
                    sample_cnt <= 4'd0;
                    bit_idx    <= 4'd0;
                end
            end else if (oversampling_tick) begin
                sample_cnt <= sample_cnt + 4'd1;
                if (sample_cnt == (OVERSAMPLE/2)) begin
                    // Muestreo a mitad de bit
                    if (bit_idx == 4'd0) begin
                        // Asegura que seguimos en start bit bajo
                        if (rx_sync) begin
                            // Ruido: cancelar
                            busy <= 1'b0;
                        end
                    end
                end
                if (sample_cnt == (OVERSAMPLE-1)) begin
                    sample_cnt <= 4'd0;
                    bit_idx    <= bit_idx + 4'd1;

                    if (bit_idx >= 4'd1 && bit_idx <= 4'd8) begin
                        rx_shift <= {rx_sync, rx_shift[7:1]}; // LSB-first
                    end else if (bit_idx == 4'd9) begin
                        // stop bit: finalizar
                        data       <= rx_shift;
                        data_ready <= 1'b1;
                        busy       <= 1'b0;
                    end
                end
            end
        end
    end
endmodule

rtl/top.v

// Top: UART hello-world con eco para Pico-ICE (iCE40UP5K)
// - Oscilador interno HFOSC -> ~12 MHz
// - Baud 115200, 8N1
// - Envía "Hello, world!\r\n" al arrancar, luego eco.
// - LED RGB: parpadea (breve) al recibir '\n'

module top (
    input  wire uart_rx,    // desde Raspberry Pi TX (GPIO14)
    output wire uart_tx,    // hacia Raspberry Pi RX (GPIO15)
    output wire led_r,      // LED RGB (anodo/cátodo según placa)
    output wire led_g,
    output wire led_b
);
    // Reset simple: soltar tras unos ciclos
    reg [15:0] rst_cnt = 0;
    wire resetn = rst_cnt[15];
    always @(posedge clk) begin
        if (!resetn) rst_cnt <= rst_cnt + 16'd1;
    end

    // Oscilador interno: HFOSC ~48 MHz / 4 = ~12 MHz
    wire clk;
    SB_HFOSC #(
        .CLKHF_DIV("0b10")   // 00: 48MHz, 01: 24MHz, 10: 12MHz, 11: 6MHz
    ) u_hfosc (
        .CLKHFEN(1'b1),
        .CLKHFPU(1'b1),
        .CLKHF(clk)
    );

    // Divisores para baud y oversampling (16x)
    // Aprox: clk = 12_000_000 Hz
    localparam integer BAUD       = 115200;
    localparam integer BAUD_DIV   = 104; // 12e6 / 115200 ≈ 104.166
    localparam integer OVER_DIV   = BAUD_DIV / 16; // ≈ 6 (redondeo hacia abajo)
    // Implementamos 2 contadores: uno para 16x y otro para 1x.

    reg [7:0] over_cnt = 0;
    reg [7:0] baud_cnt = 0;
    reg       over_tick = 0;
    reg       baud_tick = 0;

    always @(posedge clk) begin
        if (!resetn) begin
            over_cnt  <= 0;
            baud_cnt  <= 0;
            over_tick <= 0;
            baud_tick <= 0;
        end else begin
            // Oversampling (16x)
            over_tick <= 0;
            if (over_cnt == (OVER_DIV-1)) begin
                over_cnt  <= 0;
                over_tick <= 1;
            end else begin
                over_cnt <= over_cnt + 1;
            end

            // Baudrate 1x
            baud_tick <= 0;
            if (baud_cnt == (BAUD_DIV-1)) begin
                baud_cnt  <= 0;
                baud_tick <= 1;
            end else begin
                baud_cnt <= baud_cnt + 1;
            end
        end
    end

    // Instancias UART
    wire       tx_busy;
    reg  [7:0] tx_data;
    reg        tx_valid;

    wire [7:0] rx_data;
    wire       rx_ready;

    uart_tx u_tx (
        .clk        (clk),
        .resetn     (resetn),
        .baud_tick  (baud_tick),
        .data       (tx_data),
        .data_valid (tx_valid),
        .tx         (uart_tx),
        .busy       (tx_busy)
    );

    uart_rx u_rx (
        .clk               (clk),
        .resetn            (resetn),
        .oversampling_tick (over_tick),
        .rx                (uart_rx),
        .data              (rx_data),
        .data_ready        (rx_ready)
    );

    // Máquina para enviar "Hello, world!\r\n" al arranque
    localparam integer MSG_LEN = 15;
    reg [7:0] hello [0:MSG_LEN-1];
    initial begin
        hello[0]  = "H";
        hello[1]  = "e";
        hello[2]  = "l";
        hello[3]  = "l";
        hello[4]  = "o";
        hello[5]  = ",";
        hello[6]  = " ";
        hello[7]  = "w";
        hello[8]  = "o";
        hello[9]  = "r";
        hello[10] = "l";
        hello[11] = "d";
        hello[12] = "!";
        hello[13] = "\r";
        hello[14] = "\n";
    end

    reg [4:0] hello_idx = 0;
    reg       hello_sent = 0;

    // LED sencillo: breve pulso en azul al recibir '\n'
    reg [19:0] led_cnt = 0;
    reg        led_pulse = 0;

    always @(posedge clk) begin
        if (!resetn) begin
            hello_idx  <= 0;
            hello_sent <= 0;
            tx_valid   <= 0;
            tx_data    <= 8'h00;
            led_cnt    <= 0;
            led_pulse  <= 0;
        end else begin
            // Pulso LED
            if (led_pulse) begin
                if (led_cnt == 20'd800000) begin // ~66ms a 12MHz
                    led_pulse <= 0;
                    led_cnt   <= 0;
                end else begin
                    led_cnt <= led_cnt + 1;
                end
            end

            // Envío del mensaje inicial
            if (!hello_sent) begin
                if (!tx_busy && !tx_valid) begin
                    tx_data  <= hello[hello_idx];
                    tx_valid <= 1;
                end else if (tx_valid && tx_busy) begin
                    tx_valid <= 0; // consumido
                    if (hello_idx == (MSG_LEN-1)) begin
                        hello_sent <= 1;
                        hello_idx  <= 0;
                    end else begin
                        hello_idx <= hello_idx + 1;
                    end
                end
            end else begin
                // Modo eco: enviar cualquier byte recibido
                if (rx_ready && !tx_busy && !tx_valid) begin
                    tx_data  <= rx_data;
                    tx_valid <= 1;
                    if (rx_data == 8'h0A) begin
                        // '\n'
                        led_pulse <= 1;
                        led_cnt   <= 0;
                    end
                end else if (tx_valid && tx_busy) begin
                    tx_valid <= 0; // consumido
                end
            end
        end
    end

    // LED RGB (ajusta polaridad según tu placa; muchas UP5K encienden con '0')
    // Suponemos LED activo en 0 (común en iCE40 dev boards)
    assign led_r = 1'b1;            // apagado
    assign led_g = 1'b1;            // apagado
    assign led_b = led_pulse ? 1'b0 : 1'b1; // parpadeo en azul
endmodule

Breve explicación de partes clave:
– SB_HFOSC: oscilador interno, configurado a ~12 MHz para un divisor de baudios fácil.
– uart_tx / uart_rx: Implementan la trama 8N1 a 115200 baudios. El receptor usa oversampling 16x para robustez.
– Máquina de estados en top: Al arrancar envía “Hello, world!
” byte a byte (respetando tx_busy). Después pasa a modo “eco”: cada byte recibido se reenvía. Si detecta ‘
‘, hace un pulso en el LED azul como feedback visual.

Compilación, programación y ejecución

Árbol de proyecto

Usa este layout:

picoice-uart-echo/
├─ rtl/
│  ├─ top.v
│  ├─ uart_tx.v
│  └─ uart_rx.v
├─ constr/
│  └─ pico-ice.pcf        # constraints (lo editaremos)
├─ build/                 # se genera al compilar
└─ scripts/
   └─ test_uart.py        # validación en la Pi

Crea carpetas y coloca los archivos .v en rtl/. El PCF lo preparamos a continuación.

Constraints (PCF) para Pico-ICE

1) Consigue el PCF base de tu Pico-ICE (por ejemplo, del repositorio del fabricante o ejemplos de la placa). Copia ese archivo como constr/pico-ice.pcf.
2) Edita el final del PCF para asignar nuestras señales top-level a pines del conector que vayas a usar. Supongamos que tu PCF define alias de conector “PMODA1, PMODA2, …” (nombres de ejemplo; ajusta a tu archivo real):

# Al final de constr/pico-ice.pcf:
# Asignación UART:
set_io uart_rx PMODA1   # PMOD A pin 1 -> entrada al FPGA (desde TX de la Pi)
set_io uart_tx PMODA2   # PMOD A pin 2 -> salida del FPGA (hacia RX de la Pi)

# LED RGB (ajusta si tu PCF trae alias para el LED)
# Ejemplos genéricos; reemplaza por los alias correctos de tu placa:
set_io led_r LED_R
set_io led_g LED_G
set_io led_b LED_B

Si tu PCF no trae alias de PMOD ni LED, consulta la documentación de la Pico-ICE para mapear a nombres de bola del encapsulado del UP5K y reemplaza PMODA1/PMODA2/LED_* por los pines correctos.

3) Paquete del chip: la Pico-ICE monta iCE40UP5K; el paquete más habitual es SG48. Usaremos “–up5k –package sg48” en nextpnr-ice40. Si tu Pico-ICE usa otro paquete, cámbialo acorde.

Comandos de síntesis, PnR, empaquetado y programación

Desde la raíz del proyecto (picoice-uart-echo/), con la OSS CAD Suite 2024-10-01 en el PATH:

# 0) Prepara carpeta de build
mkdir -p build

# 1) Síntesis con Yosys
yosys -p "read_verilog rtl/uart_tx.v rtl/uart_rx.v rtl/top.v; synth_ice40 -top top -json build/top.json"

# 2) Place & route con nextpnr-ice40 (ajusta --package si aplica)
nextpnr-ice40 --up5k --package sg48 --json build/top.json --pcf constr/pico-ice.pcf --asc build/top.asc

# 3) Empaquetar a bitstream binario
icepack build/top.asc build/top.bin

# 4) Programa la Pico-ICE conectada por USB al Raspberry Pi
#    Conecta la Pico-ICE por USB al Pi y verifica que se enciende.
#    Asegúrate de no tener el puerto serie ocupado antes de programar.
iceprog build/top.bin

Notas:
– Si hay varias placas, puedes usar iceprog -d <device> para especificar.
– Para programar en SPI flash (persistente) usa iceprog -S build/top.bin. Para pruebas en SRAM, usa el comando básico (sin -S).

Conexión física antes de ejecutar

• Conecta el cable USB de la Pico-ICE a un puerto USB del Raspberry Pi (para la programación).
• Conecta los tres cables Dupont:
• Pi Pin 8 (GPIO14, TXD) → PMOD A pin 1 (uart_rx en el PCF).
• Pi Pin 10 (GPIO15, RXD) → PMOD A pin 2 (uart_tx en el PCF).
• Pi GND (Pin 6) → GND Pico-ICE.

Validación paso a paso

1) Verificar el puerto serie en la Pi

Comprueba que /dev/serial0 existe:

ls -l /dev/serial0
# salida esperada -> enlace a /dev/ttyAMA0 o /dev/ttyS0 según la plataforma

Opcional: prueba con minicom:

sudo apt install -y minicom
minicom -b 115200 -o -D /dev/serial0
# -b 115200: baudios
# -o: no inicializar modem
# -D: dispositivo

• Al abrir minicom, si todo está bien, deberías ver “Hello, world!” seguido de retorno de carro y nueva línea.
• Teclea cualquier texto; debería devolverse (eco). Al enviar una línea con Enter (que manda ‘\r’ y/o ‘
  ‘ según configuración), el LED azul hace un pulso breve.

Para salir de minicom: Ctrl-A, X, Enter.

2) Validación con Python (recomendado para scripting)

Activa el venv y ejecuta el script de prueba:

scripts/test_uart.py:

#!/usr/bin/env python3
import time
import serial

PORT = "/dev/serial0"
BAUD = 115200

def main():
    print(f"Abrir {PORT} @ {BAUD} 8N1...")
    with serial.Serial(PORT, BAUD, timeout=1) as ser:
        # Espera el banner
        time.sleep(0.5)
        data = ser.read(64)
        print("Recibido inicial:", data)

        msg = b"ping eco!\r\n"
        print("Enviar:", msg)
        ser.write(msg)

        time.sleep(0.2)
        echo = ser.read(len(msg))
        print("Eco:", echo)

        # Prueba interacción
        for i in range(3):
            payload = f"L{i} hola FPGA\r\n".encode()
            ser.write(payload)
            time.sleep(0.2)
            got = ser.read(len(payload))
            print(f"Eco {i}:", got)

if __name__ == "__main__":
    main()

Ejecución:

source ~/venvs/picoice/bin/activate
python scripts/test_uart.py
deactivate

Resultados esperados:
– Línea “Recibido inicial: b’Hello, world!
‘” (o similar).
– “Eco: b’ping eco!
‘”.
– Tres líneas de eco subsiguientes igual a lo enviado.
– El LED azul parpadea brevemente cada vez que se recibe ‘
‘.

3) Comprobaciones adicionales

• Si tienes un multímetro con medición de frecuencia o un analizador lógico, puedes medir la línea TX del FPGA y comprobar el patrón UART a 115200 8N1.
• Con screen (alternativa a minicom):

screen /dev/serial0 115200
# Para salir: Ctrl-A, K, y

Troubleshooting (5–8 errores típicos y su solución)

1) No aparece “Hello, world!” en minicom/pyserial
– Causas:
– El bitstream no está cargado en la FPGA (error en iceprog).
– PCF no mapea correctamente uart_tx/uart_rx a los pines usados.
– Baud rate/configuración errónea (asegúrate de 115200 8N1 en el host).
– Consola serie del sistema aún activa ocupando /dev/serial0.
– Soluciones:
– Reprograma: iceprog build/top.bin y verifica salida de iceprog.
– Revisa/ajusta constr/pico-ice.pcf; confirma que PMODA1/PMODA2 (o alias correctos) se corresponden a los pines usados.
– Verifica sudo raspi-config → Serial → login por serial desactivado, hardware serial activado.
– Prueba con screen /dev/serial0 115200 para descartar minicom.

2) Caracteres corruptos o eco inestable
– Causas:
– Error de baudios por reloj inexacto o divisor mal calculado.
– Cableado largo o flojo; GND no común.
– Soluciones:
– Asegura HFOSC a 12 MHz y BAUD_DIV=104; recompila.
– Mantén cables cortos, conexiones firmes y GND compartido.
– Prueba bajar a 57600 baudios: ajusta divisor (12e6/57600 ≈ 208) y recompila.

3) No puedo programar la Pico-ICE (iceprog falla)
– Causas:
– Cable USB defectuoso o solo carga.
– Permisos USB (udev) insuficientes.
– La Pico-ICE no entra en modo programable (reconexión necesaria).
– Soluciones:
– Cambia cable USB y puerto del Raspberry Pi.
– Prueba sudo iceprog build/top.bin.
– Desconecta y reconecta la Pico-ICE; verifica con lsusb que aparezca un dispositivo con RP2040/programador.

4) LED no parpadea al recibir ‘
‘
– Causas:
– LED con polaridad distinta (activo en alto vs activo en bajo).
– PCF no mapea correctamente LED_B a la bola del LED.
– Soluciones:
– Invierte la lógica del LED (0 ↔ 1) en top.v o mapea al canal correcto (R/G/B).
– Revisa el PCF/serigrafía para asginar el pin correcto.

5) El Raspberry Pi no muestra /dev/serial0
– Causas:
– UART deshabilitado (enable_uart=0 o sin overlay).
– Conflito con consola por serie.
– Soluciones:
– En /boot/firmware/config.txt: enable_uart=1.
– sudo raspi-config → Interface Options → Serial → login “No”, hardware “Yes”.
– Reinicia y verifica ls -l /dev/serial0.

6) Eco funciona, pero faltan caracteres
– Causas:
– El receptor UART simple pierde bits si llegan muy pegados sin buffering.
– Soluciones:
– Introduce una pequeña pausa al enviar desde el host (timeout o sleeps).
– Añade un FIFO simple en el FPGA si planeas ráfagas largas.

7) nextpnr error: paquete incorrecto
– Causa:
– La Pico-ICE usa un paquete (p. ej., sg48) distinto al usado en el comando.
– Solución:
– Confirma el paquete real de tu Pico-ICE y reemplaza --package sg48 por el adecuado.

8) Minicom muestra CRLF dobles o saltos raros
– Causa:
– Configuración de traducción de retorno de carro/nueva línea en minicom.
– Solución:
– En minicom, ajusta “Serial port setup” → desactiva mapeos LF/CR o usa screen/pyserial.

Mejoras/variantes

• Cambiar baudios: ajusta BAUD y divisores (por ejemplo, 57600, 38400, 9600) y recompila. Para 57600, usa BAUD_DIV ≈ 208; para 9600, ≈ 1250.
• Eco con transformación: convierte minúsculas a mayúsculas antes del eco para validar lógica.
• Buffer FIFO: añade un pequeño FIFO para tolerar ráfagas sin perder datos, o usa handshake XON/XOFF.
• Comandos simples: reconoce comandos “LED ON”, “LED OFF” para controlar el LED por UART.
• Reubicación de pines: mapea el UART a otro PMOD o a pines con hardware específico (si tu placa comparte con otros periféricos).
• Persistencia: programa en SPI flash con iceprog -S build/top.bin para que arranque el bitstream automáticamente al energizar.
• Integración con Python: usa pyserial para crear un pequeño monitor interactivo o un test automatizado que mida latencia de eco.

Checklist de verificación

• [ ] Raspberry Pi con Raspberry Pi OS Bookworm 64-bit actualizado y Python 3.11 operativo.
• [ ] OSS CAD Suite 2024-10-01 instalada en /opt y PATH configurado; yosys -V y nextpnr-ice40 --version funcionan.
• [ ] Interfaz serie del Raspberry Pi habilitada: /dev/serial0 visible; consola por serial desactivada.
• [ ] Entorno virtual Python creado y activable; pyserial 3.5 instalado.
• [ ] Carpeta del proyecto creada con rtl/top.v, rtl/uart_tx.v, rtl/uart_rx.v y constr/pico-ice.pcf editado con las asignaciones correctas (uart_rx/uart_tx y LED).
• [ ] Conexiones físicas: USB del Pi a Pico-ICE; GPIO14 (TX) → uart_rx, GPIO15 (RX) → uart_tx; GND compartido.
• [ ] Flujo de build ejecutado sin errores:
• [ ] Yosys genera build/top.json
• [ ] nextpnr-ice40 genera build/top.asc
• [ ] icepack genera build/top.bin
• [ ] iceprog programa la Pico-ICE
• [ ] En minicom o con scripts/test_uart.py aparece “Hello, world!” al conectar.
• [ ] El eco funciona: lo que escribes/mandas vuelve idéntico.
• [ ] El LED azul parpadea brevemente al enviar ‘
  ‘.
• [ ] Opcional: bitstream persistente en SPI flash con iceprog -S.

Con este caso práctico has completado un flujo básico pero completo: escribir HDL, sintetizar con Yosys, colocar y enrutar con nextpnr-ice40, empaquetar con icepack, programar la Pico-ICE con iceprog, y validar por puerto serie desde una Raspberry Pi con Raspberry Pi OS Bookworm 64‑bit y Python 3.11. El objetivo “uart-hello-world-eco” queda resuelto con materiales, conexión, código y validación coherentes con el modelo “Pico-ICE (Lattice iCE40UP5K)”.

Objective and use case

What you’ll build: This project demonstrates how to send low-power UART messages from a Pico-ICE FPGA (Lattice iCE40UP5K) to a Raspberry Pi using Python and C firmware.

Why it matters / Use cases

• Enable low-power communication between FPGA and Raspberry Pi for IoT applications, reducing energy consumption.
• Facilitate rapid prototyping of embedded systems by utilizing UART for simple data exchange.
• Provide a foundation for more complex FPGA and microcontroller co-designs in future projects.
• Demonstrate effective use of the Pico SDK for developing firmware on the RP2040 microcontroller.

Expected outcome

• Successful transmission of UART messages at a baud rate of 9600, verified by Python script output.
• Reduction in power consumption by running the RP2040 at 12 MHz instead of 125 MHz.
• Validation of UART communication with minimal latency, ensuring timely message delivery.
• Establishment of a reliable 3-wire UART link between the Pico-ICE and Raspberry Pi.

Audience: Embedded systems developers; Level: Basic

Architecture/flow: UART communication from Pico-ICE to Raspberry Pi, utilizing Python for message validation.

Practical Case: Raspberry Pi — Pico-ICE (Lattice iCE40UP5K) — “uart-hello-world-eco”

This hands-on, basic‑level project shows how to send a minimal, low‑power UART message from a Pico‑ICE (Lattice iCE40UP5K) to a Raspberry Pi running Raspberry Pi OS Bookworm 64‑bit, and validate the output using Python 3.11. You will build tiny C firmware for the RP2040 on the Pico‑ICE using the Pico SDK, configure the Raspberry Pi’s serial interface, wire a simple 3‑wire UART link, and verify the “uart-hello-world-eco” message with a short Python script in a virtual environment.

We intentionally keep the microcontroller in a low‑power configuration (“eco”) by:
– Running the RP2040 at a reduced system clock (12 MHz instead of 125 MHz).
– Using UART at a modest baud rate (9600).
– Disabling default stdio backends to avoid unnecessary USB/printf overhead.

The end result is a deterministic, resource‑efficient UART “Hello World” that is easy to reproduce and extends well to more advanced FPGA+MCU co‑designs later.

---

Prerequisites

• A Raspberry Pi 4, 400, or 5 running Raspberry Pi OS Bookworm 64‑bit.
• Internet connectivity for package installation.
• Basic familiarity with the Linux command line (shell), Git, and CMake.
• You have admin rights (sudo) on the Raspberry Pi.
• A clean microSD card with Raspberry Pi OS Bookworm (64‑bit) already flashed.

Verify OS and Python:

lsb_release -a
uname -m
python3 --version

You should see aarch64 (64‑bit) and Python 3.11.x on Bookworm.

---

Materials (with exact model)

• 1x Raspberry Pi 4/400/5 (40‑pin header; running Raspberry Pi OS Bookworm 64‑bit).
• 1x Pico-ICE (Lattice iCE40UP5K) board (RP2040 + iCE40UP5K FPGA).
• 1x USB‑C cable for the Pico‑ICE (data‑capable, not charge‑only).
• 3x Female‑female jumper wires (Dupont) for UART (TX, RX, GND).
• Optional: ESD mat and wrist strap, USB isolator (recommended in lab settings).

---

Setup/Connection

1) Update system and install base tools

Run these commands on the Raspberry Pi to update packages and install build tools needed for the RP2040 firmware:

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y git cmake build-essential \
  gcc-arm-none-eabi libnewlib-arm-none-eabi \
  pkg-config python3-venv python3-pip \
  minicom screen

• gcc-arm-none-eabi and libnewlib-arm-none-eabi: cross toolchain for RP2040.
• minicom and screen: useful for quick serial tests.

2) Enable UART on the Raspberry Pi

We will route the Pi’s primary UART (/dev/serial0) to the 40‑pin header (GPIO14/15). Disable login shell over serial and enable the UART hardware.

Option A — raspi-config:

sudo raspi-config

• Interface Options → Serial Port
• “Login shell accessible over serial?” → No
• “Enable serial port hardware?” → Yes
• Interface Options → I2C → Enable (optional; not used here)
• Interface Options → SPI → Enable (optional; not used here)
• Finish and reboot.

Option B — manual edit:
– Ensure the serial console is not in cmdline:
sudo sed -i 's/console=serial0,[0-9]* //g' /boot/firmware/cmdline.txt
– Ensure UART is enabled via config.txt:
echo 'enable_uart=1' | sudo tee -a /boot/firmware/config.txt
– Reboot:
sudo reboot

After reboot, confirm:

ls -l /dev/serial0

It should exist and link to ttyAMA0 or ttyS0 depending on model.

3) Create a Python 3.11 virtual environment for validation

We will use this venv for the host‑side UART validation script.

python3 -m venv ~/venv-uart-eco
source ~/venv-uart-eco/bin/activate
pip install --upgrade pip
pip install pyserial

Per the Raspberry Pi family defaults, also install these (even if not required for UART):
– System packages with apt:
sudo apt install -y python3-gpiozero python3-smbus python3-spidev
– Or inside the venv (optional via pip; not necessary if apt is used):
pip install gpiozero smbus2 spidev

We will only use pyserial for the validation program, but the others are common Raspberry Pi interfaces useful in later projects.

4) Wiring the UART (3 wires, 3.3 V logic)

Both the Raspberry Pi and Pico‑ICE use 3.3 V logic. Do not connect 5 V to any data pin. We’ll use RP2040 UART0 pins on the Pico‑ICE: GPIO0 (TX) and GPIO1 (RX). These are the standard default UART pins on RP2040 and are presented on the Pico‑style edge castellations of the Pico‑ICE.

Make the following connections:

Notes:
– TX from Pico‑ICE must go to RX on the Raspberry Pi (crossed), and RX to TX.
– Connect the ground line; without a common ground, UART will be unreliable or fail.
– Leave 3V3 and 5V power lines disconnected for UART; we will power the Pico‑ICE via its USB‑C port.

5) Power the Pico‑ICE

• Connect Pico‑ICE to the Raspberry Pi’s USB‑A port using a USB‑C cable.
• The board should power up; a storage device may appear if it is in BOOTSEL mode.

---

Full Code

We provide two pieces of code:

1) RP2040 firmware (C with Pico SDK) to send the eco message over UART0 at 9600 baud, while running the system clock at a reduced 12 MHz.
2) A Raspberry Pi Python validation script using pyserial to read and assert the exact message.

1) RP2040 “uart-hello-world-eco” firmware (C)

Create a project directory on the Pi (host build machine):

mkdir -p ~/pico-ice-uart-eco/firmware
cd ~/pico-ice-uart-eco

Fetch the Pico SDK (release tracking via Git); we’ll place it under ~/pico-sdk and set PICO_SDK_PATH accordingly.

cd ~
git clone --depth 1 https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk
git submodule update --init

Now in your firmware directory:

cd ~/pico-ice-uart-eco/firmware

Create these files:

• pico_sdk_import.cmake (copy from the SDK’s external template):

cp ~/pico-sdk/external/pico_sdk_import.cmake .

• CMakeLists.txt:

cmake_minimum_required(VERSION 3.13)

include(pico_sdk_import.cmake)

project(uart_eco C CXX ASM)

pico_sdk_init()

add_executable(uart_eco
    main.c
)

target_link_libraries(uart_eco
    pico_stdlib
    hardware_uart
    hardware_clocks
)

pico_enable_stdio_usb(uart_eco 0)
pico_enable_stdio_uart(uart_eco 0)

# Create UF2, bin, etc.
pico_add_extra_outputs(uart_eco)

• main.c:

#include "pico/stdlib.h"
#include "hardware/uart.h"
#include "hardware/clocks.h"

// Eco UART "Hello World" on RP2040 (Pico-ICE board)
// UART0 on pins GP0 (TX) and GP1 (RX), at 9600 baud
// System clock reduced to 12 MHz to save power.

#define UART_ID     uart0
#define BAUD_RATE   9600
#define UART_TX_PIN 0
#define UART_RX_PIN 1

static void eco_init(void) {
    // Lower the system clock; 12 MHz is plenty for 9600 baud UART
    // Returns true if set successfully.
    (void)set_sys_clock_khz(12000, true);

    // Initialize chosen UART
    uart_init(UART_ID, BAUD_RATE);

    // Set the GPIO function for the UART pins
    gpio_set_function(UART_TX_PIN, GPIO_FUNC_UART);
    gpio_set_function(UART_RX_PIN, GPIO_FUNC_UART);

    // Optionally, disable unnecessary pulls on RX to reduce microamps
    gpio_disable_pulls(UART_TX_PIN);
    gpio_disable_pulls(UART_RX_PIN);

    // Initialize stdlib timing (sleep_ms)
    stdio_init_all();
}

int main() {
    eco_init();

    // Minimal loop: send message at a gentle duty cycle
    const char *msg = "uart-hello-world-eco\r\n";

    while (true) {
        uart_puts(UART_ID, msg);
        // Keep the device mostly idle; sleep for 2 seconds
        sleep_ms(2000);
    }
}

This firmware:
– Sets the RP2040 system clock to 12 MHz to reduce current consumption.
– Uses UART0 at 9600 baud on GP0/GP1 (default mapping).
– Avoids setting up stdio over USB/UART (no printf), keeping the output strictly on UART0 via uart_puts.

2) Raspberry Pi validation script (Python 3.11, pyserial)

In your venv:

source ~/venv-uart-eco/bin/activate
mkdir -p ~/pico-ice-uart-eco/host
cd ~/pico-ice-uart-eco/host

Create read_uart_validate.py:

#!/usr/bin/env python3
import time
import sys
import serial

PORT = "/dev/serial0"
BAUD = 9600
EXPECTED = "uart-hello-world-eco"

def main():
    try:
        with serial.Serial(PORT, BAUD, timeout=2) as ser:
            print(f"Opened {PORT} at {BAUD} baud")
            # Flush any stale input
            ser.reset_input_buffer()
            t0 = time.time()
            seen = False

            while time.time() - t0 < 10:
                line = ser.readline().decode("utf-8", errors="ignore").strip()
                if line:
                    print(f"RX: {line}")
                    if line == EXPECTED:
                        seen = True
                        break

            if not seen:
                print("Did not see the expected message within 10 seconds.", file=sys.stderr)
                sys.exit(2)

            print("Validation OK: received exact 'uart-hello-world-eco'")
            sys.exit(0)
    except serial.SerialException as e:
        print(f"Serial error: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Make it executable:

chmod +x ~/pico-ice-uart-eco/host/read_uart_validate.py

---

Build/Flash/Run commands

All commands are to be run on the Raspberry Pi.

1) Build the RP2040 firmware

export PICO_SDK_PATH=~/pico-sdk
cd ~/pico-ice-uart-eco/firmware
mkdir -p build
cd build
cmake -DPICO_SDK_PATH=$PICO_SDK_PATH -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

On success, you will have uart_eco.uf2 under ~/pico-ice-uart-eco/firmware/build/.

2) Put Pico-ICE into BOOTSEL and flash UF2

• Unplug the Pico‑ICE USB‑C if connected.
• Press and hold the BOOT/BOOTSEL button on the Pico‑ICE.
• Plug in the USB‑C cable to the Raspberry Pi while holding the button.
• Release the button after the board enumerates as a USB mass storage device (often named RPI-RP2).

Copy the UF2:

UF2=~/pico-ice-uart-eco/firmware/build/uart_eco.uf2

# Identify the mount path (commonly /media/pi/RPI-RP2)
lsblk -o NAME,MOUNTPOINT | grep RP2 || true

# If auto-mounted at /media/pi/RPI-RP2:
cp "$UF2" /media/$USER/RPI-RP2/
sync

The device will automatically reboot after the UF2 is copied.

If your desktop environment doesn’t auto‑mount, you can mount manually:

# Find the device (e.g., /dev/sda1)
lsblk -p -o NAME,LABEL | grep RPI-RP2
# Suppose it is /dev/sda1
sudo mkdir -p /mnt/rp2
sudo mount /dev/sda1 /mnt/rp2
sudo cp "$UF2" /mnt/rp2/
sync
sudo umount /mnt/rp2

3) Run and read on the Raspberry Pi

Ensure wiring is as per the table (TX↔RX, GND↔GND). Then run the validation script:

source ~/venv-uart-eco/bin/activate
python ~/pico-ice-uart-eco/host/read_uart_validate.py

Expected terminal output:
– It opens /dev/serial0 at 9600.
– It prints lines received.
– It confirms: “Validation OK: received exact ‘uart-hello-world-eco’”.

If you prefer a quick manual check:

minicom -b 9600 -o -D /dev/serial0
# Press Ctrl-A then Q to quit (without reset) when done.

---

Step‑by‑step Validation

1) Confirm UART is free (login shell disabled):
sudo systemctl status serial-getty@ttyAMA0.service 2>/dev/null || true
sudo systemctl status serial-getty@ttyS0.service 2>/dev/null || true
The getty service should be inactive/disabled on whichever UART /dev/serial0 targets.

2) Confirm /dev/serial0 exists:
ls -l /dev/serial0

3) Check wiring:
– Pico‑ICE GP0 → Raspberry Pi GPIO15 (pin 10).
– Pico‑ICE GP1 → Raspberry Pi GPIO14 (pin 8).
– GND → GND (pin 6).
– USB‑C provides power to Pico‑ICE.

4) Confirm Pico‑ICE firmware is running:
– After UF2 copy, the board reboots automatically.
– The RP2040 is running at 12 MHz and broadcasting “uart-hello-world-eco” every ~2 seconds.

5) Validate with Python:
source ~/venv-uart-eco/bin/activate
python ~/pico-ice-uart-eco/host/read_uart_validate.py
– You should see a line like: “RX: uart-hello-world-eco”.
– The script exits with code 0 on success. To verify programmatically:
echo $?
Expect 0.

6) Optional sanity check with stty:
stty -F /dev/serial0 9600
cat /dev/serial0
Press Ctrl‑C to exit. You should see periodic lines.

7) Optional: Confirm low‑baud and smooth timing:
– Observed interval between lines should be ~2 seconds.
– Lower baud reduces switching activity and IO power.

8) Optional: Alternative test with screen:
screen /dev/serial0 9600
Exit with Ctrl‑A then K.

If any of these steps fails, see Troubleshooting below.

---

Troubleshooting

• No output on /dev/serial0:
• Re‑check that the serial login shell was disabled in raspi-config.
• Confirm enable_uart=1 is present in /boot/firmware/config.txt.

• Ensure you rebooted after configuration changes.

• Wrong pins:

• TX and RX must be crossed (Pico‑ICE TX → Pi RX, Pico‑ICE RX → Pi TX).
• Confirm you used GPIO14 (TXD) and GPIO15 (RXD) on the Pi’s 40‑pin header.

• Verify ground is connected.

• Baud mismatch:

• Firmware sets BAUD_RATE to 9600; open the host port at 9600.

• If you modified the code, keep host and device in sync.

• UF2 not copying:

• Ensure the board is in BOOTSEL (hold BOOT while plugging in).
• Try a different USB‑C cable (must support data).

• Make sure the RPI-RP2 drive is mounted before copying.

• Build errors:

• PICO_SDK_PATH must point to the pico-sdk:
  export PICO_SDK_PATH=~/pico-sdk
• Ensure submodules are initialized:
  cd ~/pico-sdk
git submodule update --init

• If CMake can’t find the SDK, verify pico_sdk_import.cmake is present in your firmware directory.

• Conflicting serial usage:

• Some HATs or services may grab the serial port. Stop them or remove overlays that reassign UART pins.

• USB power issues:

• If the board resets or disappears, try a different USB port or use a powered USB hub.

• Avoid also powering the Pico‑ICE from another source simultaneously.

• Python environment:

• If import serial fails, ensure you activated the venv and installed pyserial:
  source ~/venv-uart-eco/bin/activate
pip install pyserial

---

Improvements

• Dynamic eco modes:
• Add a “command listener” on UART RX to switch between fast (e.g., 48–125 MHz) and eco (12 MHz) modes at runtime.

• Gate the UART transmitter if no message needs to be sent.

• Deeper low‑power tricks:

• Use the RP2040 dormant or sleep states between transmissions, waking via a timer alarm.
• Reduce peripheral clocks to the minimum necessary.

• Disable unused GPIO pulls systematically.

• Higher‑integrity UART:

• Add CRLF normalization and a simple checksum (e.g., CRC8) to the message for robust host validation.

• Enable hardware flow control (CTS/RTS) for higher baud rates (requires extra pins).

• FPGA offload (leveraging the iCE40UP5K):

• Implement a UART TX core in the FPGA to offload the RP2040.
• RP2040 provides the message via SPI to the FPGA, which transmits autonomously at very low duty cycle.

• Toolchain: yosys/nextpnr-ice40/icestorm (can be installed on Raspberry Pi), then integrate with the Pico‑ICE bitstream loader used by the board vendor.

• Advanced host logging:

• Extend the Python script to timestamp lines, write to CSV/JSON, and auto‑retry if the serial port is busy.

• Integrate with gpiozero to signal activity on a Pi GPIO LED only when new lines are received.

• Device tree overlays:

• Pin the UART to core clocks most suitable for stability on Pi models with a secondary mini‑UART when needed.

---

Final Checklist

• Raspberry Pi OS Bookworm 64‑bit installed and updated.
• Python 3.11 venv created; pyserial installed:
• venv path: ~/venv-uart-eco
• pyserial installed and working.
• Interfaces:
• Serial login disabled.
• UART hardware enabled (enable_uart=1).
• Pico‑ICE (Lattice iCE40UP5K) wired to Raspberry Pi:
• GP0 (TX) → GPIO15 (RX, pin 10).
• GP1 (RX) → GPIO14 (TX, pin 8).
• GND → GND (pin 6).
• Firmware built using Pico SDK:
• PICO_SDK_PATH exported to ~/pico-sdk.
• Firmware UF2: ~/pico-ice-uart-eco/firmware/build/uart_eco.uf2.
• UF2 flashed via BOOTSEL mass storage:
• RPI-RP2 mounted.
• UF2 copied.
• Validation:
• Python script reads /dev/serial0 at 9600 baud.
• Output shows exact “uart-hello-world-eco”.
• Eco characteristics applied:
• RP2040 clock set to 12 MHz (set_sys_clock_khz(12000, true)).
• Low baud (9600) used to minimize switching and IO power.
• Next steps considered:
• Dormant sleeps, FPGA offload, or dynamic eco mode switching.

This completes the basic “uart-hello-world-eco” project on Raspberry Pi with the Pico-ICE (Lattice iCE40UP5K). You now have a reproducible, power‑conscious UART pipeline from the RP2040 to the Raspberry Pi suitable for lab demos, automated tests, and as a foundation for deeper MCU+FPGA co‑design work.