Objetivo y caso de uso

Qué construirás: Un sistema de seguimiento de objetos en tiempo real utilizando OpenCV en una Raspberry Pi 4 con cámara HQ.

Para qué sirve

• Seguimiento de personas en entornos de seguridad mediante detección de movimiento.
• Control de calidad en líneas de producción al identificar objetos defectuosos.
• Interacción en proyectos de robótica, permitiendo que un robot siga a un objeto específico.
• Monitorización de tráfico en tiempo real para análisis de flujos vehiculares.

Resultado esperado

• Latencia de procesamiento de imágenes menor a 100 ms.
• Precisión de seguimiento superior al 90% en condiciones de luz adecuadas.
• Capacidad de procesar 30 FPS (fotogramas por segundo) en resolución 1080p.
• Detección de objetos en un rango de 5 metros con un 95% de fiabilidad.

Público objetivo: Desarrolladores y entusiastas de la visión por computadora; Nivel: Avanzado

Arquitectura/flujo: Captura de video desde la cámara HQ, procesamiento de imágenes en tiempo real con OpenCV, y salida de datos a través de MQTT para visualización remota.

Nivel: Avanzado

Prerrequisitos (SO, toolchain y versiones exactas)

Este caso práctico está probado y documentado para el siguiente entorno. Usa exactamente estas versiones o superiores compatibles cuando se indique; donde fijamos versiones con pip, debes respetarlas para reproducibilidad.

• Sistema operativo:
• Raspberry Pi OS Bookworm 64‑bit (Debian 12), imagen oficial para Raspberry Pi 4. Kernel Linux 6.6.x.
• Dispositivo:
• Raspberry Pi 4 Model B (2/4/8 GB) + HQ Camera (sensor Sony IMX477, conexión CSI-2).
• Toolchain y librerías (usuarios/espacio de usuario):
• Python 3.11 (Bookworm lo instala por defecto; versión probada 3.11.2).
• pip 24.2 (gestor de paquetes Python).
• virtualenv 20.26.3 (o venv estándar de Python).
• OpenCV (contrib) para Python: opencv-contrib-python==4.10.0.84
• NumPy==1.26.4
• Picamera2 (vía apt, bindings sobre libcamera): versión probada 0.3.16
• libcamera y utilidades de cámara (vía apt): libcamera-apps 0.1.0 (serie 0.1.x)
• gpiozero==1.6.2 (opcional; instalable con apt, útil para GPIOs si añades un botón físico).
• spidev y smbus2 (opcionales; no utilizados en el núcleo del proyecto).
• Compiladores (no estrictamente necesarios en este flujo, pero útiles para extensiones nativas):
• GCC 12.x (de Debian 12)
• CMake 3.25+ (si compilas OpenCV desde fuente; aquí usamos wheels de pip)

Notas:
– Elegimos Picamera2 para la captura porque integra libcamera (stack moderno de cámaras en Raspberry Pi OS Bookworm) y entrega imágenes como arrays de NumPy listos para OpenCV, evitando capas legacy (MMAL/raspicam).
– Fijamos opencv-contrib-python a 4.10.0.84 para disponer de los trackers CSRT y KCF del módulo contrib, necesarios para opencv-object-tracking con buen rendimiento/precisión.

Materiales

• 1× Raspberry Pi 4 Model B (cualquier RAM).
• 1× Raspberry Pi High Quality Camera (HQ Camera, sensor IMX477).
• 1× Cable plano CSI-2 oficial para cámara (largo según montaje).
• 1× Objetivo compatible (C o CS mount; ej., 6mm o 12mm) con su anillo adaptador.
• 1× Tarjeta microSD (≥32 GB, clase A1/A2) con Raspberry Pi OS Bookworm 64‑bit.
• 1× Fuente de alimentación oficial 5V/3A USB‑C.
• 1× Monitor HDMI, teclado y ratón (o acceso por SSH).
• 1× Trípode o soporte estable para la HQ Camera.
• Opcional:
• 1× Carcasa con soporte para cámara.
• Botón/LED conectados a GPIO (para triggers/feedback en variantes).

Asegúrate de referirte siempre al conjunto “Raspberry Pi 4 Model B + HQ Camera” en montaje, comandos y pruebas.

Preparación y conexión

Conexión física de la HQ Camera

• Apaga la Raspberry Pi y desconecta la alimentación.
• Monta el objetivo en la HQ Camera (rosca C/CS) y fija el anillo según el tipo de objetivo.
• Conecta el cable CSI-2:
• En Raspberry Pi 4 Model B, usa el conector marcado “CAMERA” (cerca del puerto micro‑HDMI más cercano al conector USB‑C).
• Levanta la pestaña del conector, inserta el cable con los contactos metálicos hacia el conector HDMI (orientación correcta: contactos mirando a los puertos HDMI), y baja la pestaña.
• En la HQ Camera, inserta el cable de forma que los contactos queden hacia el sensor (respeta la orientación del conector).
• Fija la cámara en trípode/soporte; evita vibraciones.
• Alimenta la Raspberry Pi y arranca.

Tabla de referencia de puertos y elementos relevantes

Habilitar interfaces y configuración del sistema

• Verifica/ajusta configuración de cámara y memoria GPU.
• Opción A: raspi-config
• Abre terminal:
  sudo raspi-config
• System Options → Performance Options → GPU Memory → establece 128 (o 256 si vas a usar 1080p/alta tasa).
• Interface Options:
  • Camera: en Bookworm ya no es necesario legado; no habilites “Legacy Camera”. Dejaremos libcamera por defecto.
  • SSH: habilita si vas a trabajar remoto.

• Finaliza y reinicia.

• Opción B: editar /boot/firmware/config.txt (equivalente y explícito)

• Abre el fichero:
  sudo nano /boot/firmware/config.txt
• Asegura estas líneas (añádelas si no existen):
  camera_auto_detect=1
gpu_mem=128
  No añadas start_x ni dtoverlay=vc4-kms-v3d-pi4 deshabilitado; deja el compositor KMS por defecto.
• Guarda y reinicia:
  sudo reboot

Comprobación básica de la cámara

Tras reiniciar, valida la HQ Camera con libcamera:

libcamera-hello -t 3000

• Debes ver vista previa 3 segundos. Si falla, revisa Troubleshooting.

Código completo con OpenCV y Picamera2

Implementaremos un seguidor de objetos con OpenCV (trackers CSRT/KCF) y captura con Picamera2. Permitiremos seleccionar una ROI con el ratón en tiempo de ejecución, cambiar de tracker por parámetro y mostrar FPS.

Características:
– Captura en RGB888 1280×720 @ 30 FPS vía Picamera2.
– Conversión a BGR para OpenCV.
– Trackers disponibles: CSRT (preciso), KCF (rápido). Elegibles por CLI.
– Teclas:
– s: seleccionar ROI y (re)inicializar tracker
– r: reiniciar tracker (sin ROI)
– p: pausar/continuar
– q/ESC: salir
– Overlay: bounding box, nombre del tracker, FPS.

Estructura del proyecto

• venv para aislamiento de Python 3.11.
• Script principal: track.py
• Script de diagnóstico rápido: cam_check.py

Código: cam_check.py (diagnóstico de cámara y latencia)

#!/usr/bin/env python3
# cam_check.py
from picamera2 import Picamera2
import time

def main():
    picam2 = Picamera2()
    # Configuración de previsualización a 1280x720 RGB888
    config = picam2.create_preview_configuration(
        main={"format": "RGB888", "size": (1280, 720)},
        buffer_count=4
    )
    picam2.configure(config)
    picam2.start()
    t0 = time.time()
    frames = 60
    for i in range(frames):
        frame = picam2.capture_array()  # numpy array (H, W, 3), RGB
    t1 = time.time()
    fps = frames / (t1 - t0)
    print(f"Picamera2 OK. Resolución 1280x720. FPS estimado: {fps:.2f}")
    picam2.stop()

if __name__ == "__main__":
    main()

Código: track.py (seguimiento de objetos con OpenCV)

#!/usr/bin/env python3
# track.py
# Uso:
#   python track.py --tracker csrt
#   python track.py --tracker kcf

import argparse
import time
import sys

import numpy as np
import cv2

from picamera2 import Picamera2

TRACKERS = {
    "csrt": cv2.legacy.TrackerCSRT_create,
    "kcf": cv2.legacy.TrackerKCF_create,
}

def build_tracker(name: str):
    key = name.lower()
    if key not in TRACKERS:
        raise ValueError(f"Tracker '{name}' no soportado. Usa uno de: {list(TRACKERS.keys())}")
    return TRACKERS[key]()

def draw_hud(frame, bbox, tracker_name, fps, state_text=None):
    h, w = frame.shape[:2]
    # Caja
    if bbox is not None:
        x, y, bw, bh = bbox
        p1 = (int(x), int(y))
        p2 = (int(x + bw), int(y + bh))
        cv2.rectangle(frame, p1, p2, (0, 255, 0), 2)
    # HUD
    overlay = [
        f"Tracker: {tracker_name.upper()}",
        f"FPS: {fps:.2f}",
        f"Resolucion: {w}x{h}"
    ]
    if state_text:
        overlay.append(state_text)
    y0 = 24
    for i, line in enumerate(overlay):
        cv2.putText(frame, line, (10, y0 + i * 22), cv2.FONT_HERSHEY_SIMPLEX, 0.65, (255, 255, 255), 2, cv2.LINE_AA)

def select_roi(frame):
    # OpenCV espera BGR; cv2.selectROI devuelve (x, y, w, h)
    bbox = cv2.selectROI("RoiSelector", frame, fromCenter=False, showCrosshair=True)
    cv2.destroyWindow("RoiSelector")
    if bbox == (0, 0, 0, 0):
        return None
    return bbox

def main():
    parser = argparse.ArgumentParser(description="Seguimiento de objetos con OpenCV en Raspberry Pi 4 + HQ Camera")
    parser.add_argument("--tracker", type=str, default="csrt", choices=list(TRACKERS.keys()),
                        help="Algoritmo de tracking: csrt (precisión) o kcf (rapidez)")
    parser.add_argument("--width", type=int, default=1280, help="Ancho de captura")
    parser.add_argument("--height", type=int, default=720, help="Alto de captura")
    parser.add_argument("--display", action="store_true", help="Mostrar ventana de OpenCV (necesario para seleccionar ROI)")
    parser.add_argument("--warmup", type=int, default=5, help="Frames de calentamiento antes del tracking")
    args = parser.parse_args()

    # Inicializar cámara
    picam2 = Picamera2()
    config = picam2.create_preview_configuration(
        main={"format": "RGB888", "size": (args.width, args.height)},
        buffer_count=4
    )
    picam2.configure(config)
    picam2.start()

    # Calentamiento
    for _ in range(args.warmup):
        _ = picam2.capture_array()

    # Estado del tracker
    tracker = build_tracker(args.tracker)
    has_target = False
    bbox = None
    paused = False

    last_t = time.time()
    fps = 0.0

    window_name = "OpenCV Object Tracking"
    if args.display:
        cv2.namedWindow(window_name, cv2.WINDOW_NORMAL)
        cv2.resizeWindow(window_name, args.width, args.height)

    print("Controles:")
    print("  s: seleccionar ROI y (re)iniciar tracker")
    print("  r: reiniciar tracker sin ROI")
    print("  p: pausar/continuar")
    print("  q/ESC: salir")

    while True:
        if not paused:
            # Captura en RGB, convertimos a BGR para OpenCV
            frame_rgb = picam2.capture_array()
            frame = cv2.cvtColor(frame_rgb, cv2.COLOR_RGB2BGR)
        else:
            # En pausa, no actualizamos frame
            pass

        # Tracking
        state_text = None
        if has_target and bbox is not None and not paused:
            ok, newbox = tracker.update(frame)
            if ok:
                bbox = newbox
            else:
                state_text = "Perdido: presiona 's' para seleccionar ROI"
                has_target = False

        # FPS
        t = time.time()
        dt = t - last_t
        last_t = t
        if dt > 0:
            fps = 1.0 / dt

        # Dibujo
        if args.display:
            draw_hud(frame, bbox if has_target else None, args.tracker, fps, state_text=state_text)
            cv2.imshow(window_name, frame)

        # Interacción
        key = cv2.waitKey(1) & 0xFF if args.display else 0xFF
        if key in (ord('q'), 27):  # 'q' o ESC
            break
        elif key == ord('p'):
            paused = not paused
        elif key == ord('r'):
            tracker = build_tracker(args.tracker)
            has_target = False
            bbox = None
        elif key == ord('s'):
            if not args.display:
                print("La selección de ROI requiere --display")
            else:
                # Seleccionar ROI sobre el frame actual
                # Aseguramos frame reciente si estaba en pausa
                if paused:
                    frame_rgb = picam2.capture_array()
                    frame = cv2.cvtColor(frame_rgb, cv2.COLOR_RGB2BGR)
                    paused = False
                sel = select_roi(frame)
                if sel is not None and sel[2] > 0 and sel[3] > 0:
                    tracker = build_tracker(args.tracker)
                    ok = tracker.init(frame, sel)
                    if ok:
                        bbox = sel
                        has_target = True
                    else:
                        print("No se pudo inicializar el tracker con la ROI seleccionada")

    if args.display:
        cv2.destroyAllWindows()
    picam2.stop()

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        sys.exit(0)

Breve explicación de partes clave:
– Picamera2:
– create_preview_configuration con formato RGB888 y tamaño 1280×720 para un equilibrio entre latencia y calidad.
– capture_array entrega un ndarray RGB; convertimos a BGR para OpenCV.
– Trackers CSRT/KCF:
– Se crean vía cv2.legacy._create (en OpenCV 4.10.0.84 los trackers están en el módulo legacy).
– CSRT: más preciso, costoso en CPU.
– KCF: más rápido, algo menos robusto ante oclusiones/escala.
– selectROI: permite al usuario definir el objeto a seguir.
– HUD: renderiza caja, FPS, nombre del tracker y estado.

Compilación/instalación/ejecución (pasos reproducibles)

Trabajaremos en una venv con Python 3.11, instalando dependencias con apt y pip.

1) Actualiza el sistema

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

2) Instala paquetes del sistema (libcamera y Picamera2, entre otros)

sudo apt install -y \
  python3-venv python3-dev \
  libatlas-base-dev \
  libcamera-apps \
  python3-picamera2 \
  git pkg-config \
  libgtk-3-0 libgtk-3-dev \
  libjpeg-dev libpng-dev libtiff-dev \
  libavcodec-dev libavformat-dev libswscale-dev \
  libqt5gui5 libqt5widgets5 libqt5core5a \
  libopenblas-dev

Notas:
– python3-picamera2 instala Picamera2 (versión probada 0.3.16 en Bookworm).
– libcamera-apps proporciona libcamera-hello, -still, -vid para validación y utilidades.

3) Crea y activa un entorno virtual (Python 3.11)

python3 -V
# Debe mostrar Python 3.11.x
python3 -m venv ~/venvs/pi-opencv-track
source ~/venvs/pi-opencv-track/bin/activate
python -m pip install --upgrade pip==24.2 setuptools==68.2.2 wheel==0.44.0

4) Instala dependencias Python exactas (vía pip, con versiones fijadas)

pip install numpy==1.26.4
# Usamos contrib para disponer de trackers (csrt/kcf):
pip install opencv-contrib-python==4.10.0.84
# Para ejecutarse sin display, puedes añadir opencv-python-headless==4.10.0.84,
# pero para selección de ROI con ventana es preferible opencv-contrib-python.

5) Crea el directorio del proyecto y añade los scripts

mkdir -p ~/projects/opencv-object-tracking
cd ~/projects/opencv-object-tracking
nano cam_check.py
# pega el contenido del cam_check.py mostrado
nano track.py
# pega el contenido del track.py mostrado
chmod +x cam_check.py track.py

6) Validación rápida de Picamera2

source ~/venvs/pi-opencv-track/bin/activate
python cam_check.py

• Debe imprimir “Picamera2 OK…” con FPS aproximados (p.ej., 45–60 FPS en 1280×720 sin procesamiento, dependiente de carga).

7) Ejecución del seguimiento (con ventana)

source ~/venvs/pi-opencv-track/bin/activate
python track.py --tracker csrt --display

• Se abrirá la ventana. Pulsa ‘s’ para seleccionar el objeto y ver la caja verde.

8) Opciones útiles
– Para usar KCF (más ligero):
python track.py --tracker kcf --display
– Para cambiar resolución (más FPS, menos calidad):
python track.py --width 960 --height 540 --tracker kcf --display
– Para headless (sin display) y ROI fija (editar el código para setear bbox inicial) o usar un frontend remoto (VNC/SSH X11).

Validación paso a paso

1) Validar hardware y cámara
– Comando:
libcamera-hello -t 3000
– Esperado: ventana de vista previa 3 segundos sin errores en consola.

2) Verificar versión de Picamera2 y libcamera
– Comando:
python -c "from picamera2 import __version__ as v; print('Picamera2', v)"
libcamera-hello --version
– Esperado:
– Picamera2 0.3.16 (o cercano 0.3.x).
– libcamera-hello v0.1.0 (serie 0.1.x).

3) Verificar paquete OpenCV dentro de la venv
– Comando:
source ~/venvs/pi-opencv-track/bin/activate
python -c "import cv2; import numpy as np; print('OpenCV', cv2.__version__); print('Has contrib?', hasattr(cv2, 'legacy'))"
– Esperado:
– OpenCV 4.10.0 (coincide con 4.10.0.84).
– Has contrib? True (módulo cv2.legacy disponible).

4) Test de capturas rápidas
– Comando:
python cam_check.py
– Esperado:
– Mensaje “Picamera2 OK. Resolución 1280×720. FPS estimado: XX.XX”.

5) Ejecución del seguidor con CSRT y selección de ROI
– Comando:
python track.py --tracker csrt --display
– Pasos:
1. Aparece ventana «OpenCV Object Tracking».
2. Pulsa ‘s’, se abre una ventana de selección (RoiSelector).
3. Dibuja un rectángulo alrededor del objeto a seguir y confirma (ENTER o doble clic).
4. Debe verse una caja verde en el objeto; el overlay mostrará “Tracker: CSRT” y “FPS: …”.
– Validaciones:
– La caja sigue el objeto mientras lo mueves moderadamente.
– FPS entre 10–25 en CSRT @1280×720 en RPi 4, dependiendo de iluminación y carga.
– Si pierdes el objeto, mensaje “Perdido: presiona ‘s’ para seleccionar ROI”.

6) Conmutar a KCF para mejorar FPS
– Comando:
python track.py --tracker kcf --display
– Esperado:
– FPS superior (p.ej., 20–35 FPS @720p), tracking robusto a movimientos medios.

7) Ajustar resolución para validar latencia/precisión
– Comando:
python track.py --tracker kcf --width 960 --height 540 --display
– Esperado:
– FPS más altos; tracking con algo menos de detalle.

8) Medición de CPU y estabilidad
– Comandos:
top -d 1
# o
vcgencmd measure_temp
– Esperado:
– CPU de 120–250% (en total, multi-core) según tracker/resolución.
– Temperatura < 80°C (aconsejable disipador/ventilador si supera 70°C en cargas largas).

Troubleshooting (errores típicos y soluciones)

1) libcamera-hello falla con “No cameras available” o “ERROR: *** no cameras found ***”
– Causas:
– Cable CSI invertido o mal asentado.
– HQ Camera no detectada por DT.
– Soluciones:
– Revisa orientación y firmeza del cable en Pi y HQ Camera.
– Asegura camera_auto_detect=1 en /boot/firmware/config.txt.
– Prueba añadir explícitamente el overlay del sensor:
echo "dtoverlay=imx477" | sudo tee -a /boot/firmware/config.txt
sudo reboot

2) Picamera2 ImportError: cannot import name ‘Picamera2’
– Causas: paquete no instalado, venv activada sin acceso a apt libs.
– Soluciones:
– Instala vía apt (fuera de la venv, es un paquete del sistema):
sudo apt install -y python3-picamera2
– Lanza Python desde venv; la librería del sistema es visible.

3) cv2.legacy no existe o error “module ‘cv2’ has no attribute ‘legacy’”
– Causas: instalaste opencv-python y no opencv-contrib-python.
– Solución:
pip uninstall -y opencv-python opencv-contrib-python
pip install opencv-contrib-python==4.10.0.84

4) Ventana de OpenCV no abre (display vacío) o selectROI no aparece
– Causas: sin servidor X, sesión SSH sin reenvío X11, dependencia GTK faltante.
– Soluciones:
– Ejecuta en consola local con monitor conectado.
– Instala dependencias de GUI:
sudo apt install -y libgtk-3-0 libgtk-3-dev
– Para SSH, usa VNC o X11 forwarding (ssh -X), aunque puede afectar rendimiento.

5) Bajos FPS/lag alto
– Causas: resolución elevada, tracker CSRT muy costoso, GPU mem insuficiente.
– Soluciones:
– Reduce resolución: –width 960 –height 540
– Usa –tracker kcf
– Aumenta gpu_mem a 256 si usas múltiples ventanas o alta resolución.
– Cierra procesos en segundo plano (Chromium, etc.).

6) Tracking pierde el objeto tras oclusión o cambio de escala
– Causas: trackers KCF/CSRT tienen límites ante oclusiones prolongadas.
– Soluciones:
– Re-selecciona ROI con ‘s’.
– Cambia a CSRT si usabas KCF.
– Iluminación constante y enfoque nítido del objetivo.

7) Errores de memoria o “Illegal instruction” al instalar OpenCV
– Causas: wheel incompatible, conflictos entre pip y apt.
– Soluciones:
– Borra e instala limpio en venv:
pip uninstall -y opencv-python opencv-contrib-python numpy
pip cache purge
pip install numpy==1.26.4 opencv-contrib-python==4.10.0.84
– Evita mezclar apt get python3-opencv con pip opencv-contrib-python en la misma venv.

8) Imagen invertida o colores extraños
– Causas: conversión de color omitida (RGB→BGR).
– Solución: asegura cv2.cvtColor(frame_rgb, cv2.COLOR_RGB2BGR) antes del tracker.

Mejoras y variantes

• Multi-objeto con MultiTracker:
• Usa cv2.legacy.MultiTracker_create y permite seleccionar varias ROIs (repite selectROI hasta cancelar) e inicializar múltiples trackers (p.ej., KCF para cada objeto).
• Re-identificación y robustez:
• Integra un detector (YOLOv5/YOLOv8 nano) para re‑detectar y re‑inicializar el tracker si se pierde.
• Usa un filtro de Kalman para suavizar trayectorias, mejorando estabilidad en jitter.
• Registro de trayectorias:
• Guarda en CSV (timestamp, bbox, tracker, FPS).
• Visualiza heatmap de trayectorias en tiempo real.
• Rendimiento:
• Baja resolución (960×540) y KCF para mayor FPS en CPU.
• Compila OpenCV con NEON/VFPv4 y TBB/OpenBLAS si buscas exprimir rendimiento (avanzado).
• Streaming remoto:
• Servidor RTSP o WebRTC: procesa con OpenCV y transmite la vista anotada (gstreamer + uv4l o aiortc).
• Control por GPIO:
• Usa gpiozero para iniciar/pausar tracking con un botón físico, y LED para estado (útil en montajes sin pantalla).
• Servicio systemd:
• Ejecuta track.py automáticamente al arranque (en entornos headless), escribiendo salida a archivo o stream.
• Auto ROI:
• Inicializa ROI automáticamente con el objeto más grande en movimiento (diferenciación de frames o detección simple con MOG2).

Ejemplo de fragmento para MultiTracker (orientativo):

# Dentro del main, tras elegir tracker base, permitir múltiples ROIs
multi = cv2.legacy.MultiTracker_create()
rois = []
while True:
    sel = select_roi(frame)
    if sel is None or sel[2] == 0 or sel[3] == 0:
        break
    rois.append(sel)
    multi.add(build_tracker(args.tracker), frame, sel)
# En el loop:
ok, boxes = multi.update(frame)
for b in boxes:
    x, y, bw, bh = [int(v) for v in b]
    cv2.rectangle(frame, (x, y), (x+bw, y+bh), (0, 255, 255), 2)

Checklist de verificación

• [ ] Raspberry Pi 4 Model B con HQ Camera conectada correctamente (CSI “CAMERA”; orientación del cable verificada).
• [ ] Raspberry Pi OS Bookworm 64‑bit instalado y actualizado (sudo apt full-upgrade).
• [ ] GPU memory configurada a 128 MB o más en /boot/firmware/config.txt (gpu_mem=128/256).
• [ ] libcamera-hello muestra vista previa (cámara detectada, sin errores).
• [ ] Entorno virtual creado y activado: ~/venvs/pi-opencv-track.
• [ ] pip y setuptools actualizados dentro de la venv (pip 24.2, setuptools 68.2.2).
• [ ] Paquetes Python instalados con versiones exactas:
• [ ] numpy==1.26.4
• [ ] opencv-contrib-python==4.10.0.84
• [ ] Picamera2 instalado vía apt (python3-picamera2, versión 0.3.x).
• [ ] cam_check.py ejecuta y reporta FPS estimado sin errores.
• [ ] track.py abre ventana, permite seleccionar ROI con ‘s’, muestra bbox y FPS.
• [ ] CSRT y KCF probados; KCF ofrece mayor FPS, CSRT mayor precisión.
• [ ] Troubleshooting consultado si hay errores (sin “No cameras available”, sin ImportError de cv2.legacy).
• [ ] Validación final: seguimiento estable del objeto en al menos 30 segundos con FPS aceptable para la aplicación objetivo.

Con esto, dispones de un pipeline robusto de “opencv-object-tracking” puro CPU sobre Raspberry Pi 4 Model B + HQ Camera, basado en libcamera/Picamera2, con control interactivo, reproducible y ampliable a variantes más avanzadas.

Objetivo y caso de uso

Qué construirás: Un sistema para leer la temperatura utilizando un sensor I2C conectado a la placa Pico-ICE RP2040 y validando los datos en una Raspberry Pi.

Para qué sirve

• Monitoreo de temperatura en entornos industriales utilizando sensores I2C.
• Control de climatización en invernaderos mediante lectura de temperatura en tiempo real.
• Desarrollo de proyectos de IoT que requieren datos de temperatura precisos.
• Integración de datos de temperatura en sistemas de automatización del hogar.

Resultado esperado

• Lectura de temperatura con una precisión de ±0.5 °C.
• Actualización de datos cada 2 segundos a través de I2C.
• Latencia de respuesta inferior a 100 ms al consultar el sensor desde Raspberry Pi.
• Capacidad de enviar datos a un servidor MQTT con un intervalo de 5 segundos.

Público objetivo: Desarrolladores y entusiastas de la electrónica; Nivel: Medio

Arquitectura/flujo: Sensor I2C conectado a Pico-ICE RP2040, datos leídos y procesados en Raspberry Pi.

Nivel: Medio

Prerrequisitos

En este caso práctico trabajaremos con el microcontrolador RP2040 incluido en la placa “Pico-ICE (RP2040 + iCE40UP5K)”, conectando un sensor de temperatura por I2C y validando la lectura desde un equipo “host” Raspberry Pi con Raspberry Pi OS Bookworm 64‑bit.

Sistema operativo y versiones probadas

• Raspberry Pi OS Bookworm 64‑bit (kernel 6.x), actualizado a fecha reciente.
• Python 3.11 (versión incluida por defecto en Bookworm: 3.11.x).

Toolchain exacta utilizada (probada y recomendada)

Herramientas para compilar y depurar el firmware del RP2040 con el SDK de Raspberry Pi:

• Raspberry Pi Pico SDK: v1.5.1
• CMake: 3.25.1
• Arm GNU Toolchain (arm-none-eabi-gcc): 12.2.Rel1
• picotool: 1.1.0
• i2c-tools (host): 4.3
• Python paquetes (host, en venv):
• pyserial==3.5
• rich==13.7.1

Nota: En este caso práctico no sintetizaremos lógica para el FPGA iCE40UP5K, pero si deseas tener el toolchain listo para futuras ampliaciones con el FPGA de la Pico-ICE, estas versiones funcionan correctamente en Raspberry Pi OS Bookworm:
– Yosys: 0.29
– nextpnr-ice40: 0.4
– Project IceStorm: 0.0+20230110

Habilitar interfaces en la Raspberry Pi (host)

• I2C del host (útil para herramientas de diagnóstico como i2cdetect, aunque el I2C principal lo usará el RP2040 en la Pico-ICE):
• Interactivo: sudo raspi-config
  • Interface Options → I2C → Enable.
• O bien editando en el host:
  • Añadir/asegurar dtoverlay=i2c‑arm en /boot/firmware/config.txt
• Serie:
• Para usar /dev/ttyACM0 (USB CDC del RP2040) no necesitas activar UART del GPIO de la Pi. Basta con pertenecer al grupo dialout.

Preparación de entorno Python (host)

1) Crear un entorno virtual y activarlo.
2) Instalar pyserial y rich.

Comandos exactos (host Raspberry Pi):

sudo apt update
sudo apt install -y python3-venv python3-pip i2c-tools cmake git gcc-arm-none-eabi gdb-multiarch build-essential picotool minicom

# (Opcional) Verificar versiones principales
cmake --version       # Debe indicar 3.25.1 en Bookworm
arm-none-eabi-gcc --version  # "12.2.Rel1"
picotool --version    # "picotool v1.1.0" (o cercano)

# Crear venv para las utilidades en Python
python3 -m venv ~/venvs/pico-ice-env
source ~/venvs/pico-ice-env/bin/activate
pip install --upgrade pip
pip install pyserial==3.5 rich==13.7.1

Para trabajar con el SDK del RP2040:

# Obtener pico-sdk v1.5.1 y pico-examples (solo para referencias si lo deseas)
mkdir -p ~/pico
cd ~/pico
git clone -b 1.5.1 https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk
git submodule update --init

# (Opcional) ejemplos
cd ..
git clone -b 1.5.1 https://github.com/raspberrypi/pico-examples.git

Configura la variable de entorno PICO_SDK_PATH en tu shell (puedes añadirla a ~/.bashrc):

echo 'export PICO_SDK_PATH=$HOME/pico/pico-sdk' >> ~/.bashrc
source ~/.bashrc

Tabla de herramientas y versiones

Materiales

• 1× Pico-ICE (RP2040 + iCE40UP5K).
• 1× Sensor de temperatura I2C: TMP102 (módulo de 3.3 V, típico en breakout de Adafruit o SparkFun).
• 1× Cable USB-C a USB-A (la Pico-ICE suele emplear conector USB-C) para conectar a la Raspberry Pi host.
• 1× Protoboard y 4× cables dupont M-F.
• (Opcional) 2× resistencias de 4.7 kΩ como pull-up de SDA/SCL si tu breakout no las integra (muchos módulos de TMP102 ya las incluyen).
• (Opcional) Lupa o multímetro para verificar continuidad.

Recomendación: verifica que el módulo TMP102 tenga resistencias pull-up en SDA/SCL. Si no estás seguro, consulta su hoja de datos o el serigrafiado del breakout.

Preparación y conexión

Preparación del entorno de trabajo (host Raspberry Pi)

1) Actualiza el sistema:
– sudo apt update && sudo apt full-upgrade -y
– Reinicia si hay actualización del kernel: sudo reboot

2) Asegura pertenencia al grupo dialout para acceder a /dev/ttyACM0 sin sudo:
– sudo usermod -aG dialout $USER
– cierra sesión y vuelve a entrar, o ejecuta newgrp dialout.

3) Habilita I2C del host (útil para i2cdetect y diagnóstico):
– sudo raspi-config → Interface Options → I2C → Enable
– o edita /boot/firmware/config.txt (dtoverlay=i2c-arm) y reinicia.

4) Prepara el venv de Python con pyserial y rich (ya mostrado en prerrequisitos).

Conexiones entre Pico-ICE y el TMP102

Vamos a usar I2C0 del RP2040 en los pines GP4 (SDA) y GP5 (SCL), que son el mapeo “clásico” del Pico y compatibles con muchas bibliotecas y ejemplos.

Conexión recomendada:

• Alimentación:
• 3V3 (de la Pico-ICE) → VCC del TMP102
• GND (de la Pico-ICE) → GND del TMP102
• I2C:
• GP4 (I2C0 SDA) → SDA del TMP102
• GP5 (I2C0 SCL) → SCL del TMP102
• Dirección:
• ADD0/ADDR del TMP102 → GND para dirección 0x48 (dirección por defecto más común)
• ALERT/INT → sin conectar (no lo usaremos en este ejercicio)

Tabla de conexión de pines:

Notas:
– El bus I2C requiere resistencias pull‑up en SDA y SCL (típicamente 4.7 kΩ). Muchos breakouts las integran. Si tu módulo no las tiene, añade las pull-up a 3V3.
– El RP2040 permite activar pull-ups internos, pero son débiles; no sustituyen correctamente a unas pull-up externas en buses I2C de cierta longitud/ruido.

Código completo

A continuación presentamos el firmware completo en C basado en el Raspberry Pi Pico SDK v1.5.1 para:
– Inicializar I2C0 a 100 kHz en GP4/GP5.
– Detectar el dispositivo en 0x48.
– Leer la temperatura del registro 0x00 del TMP102.
– Enviar por USB CDC (stdout) un JSON por línea con la lectura, cada 500 ms.

Incluimos además el CMakeLists.txt mínimo del proyecto. Después proporcionamos un pequeño script Python (host) para escuchar las líneas por /dev/ttyACM0 y mostrarlas con formato.

main.c (firmware RP2040: lectura I2C del TMP102 y envío por USB)

// main.c
// Proyecto: i2c-temperature-sensor-readout en Pico-ICE (RP2040 + iCE40UP5K)
// Toolchain: Pico SDK v1.5.1, arm-none-eabi-gcc 12.2.Rel1, CMake 3.25.1

#include <stdio.h>
#include "pico/stdlib.h"
#include "hardware/i2c.h"

#define I2C_PORT        i2c0
#define I2C_SDA_PIN     4   // GP4 para SDA de I2C0
#define I2C_SCL_PIN     5   // GP5 para SCL de I2C0
#define I2C_BAUDRATE    100000

// Dirección por defecto del TMP102 con ADD0 a GND
#define TMP102_ADDR     0x48
#define TMP102_TEMP_REG 0x00

static bool i2c_device_present(uint8_t addr) {
    // Intento de escribir 0 bytes con STOP, típico para detectar NACK/ACK
    uint8_t dummy = 0x00;
    int ret = i2c_write_blocking(I2C_PORT, addr, &dummy, 1, false);
    return (ret >= 0);
}

static bool tmp102_read_temp_c(float *temp_c) {
    uint8_t reg = TMP102_TEMP_REG;
    uint8_t buf[2] = {0};

    // Escribimos el puntero de registro con 'no stop' para generar un repeated start
    int w = i2c_write_blocking(I2C_PORT, TMP102_ADDR, &reg, 1, true);
    if (w < 0) return false;

    int r = i2c_read_blocking(I2C_PORT, TMP102_ADDR, buf, 2, false);
    if (r < 0) return false;

    // TMP102: 12-bit, MSB first: [T11..T4] en buf[0], [T3..T0 xxxx] en buf[1]
    int16_t raw = ((buf[0] << 8) | buf[1]) >> 4;
    // Signo si bit 11 está a 1
    if (raw & 0x800) {
        raw |= 0xF000; // extender signo 12-bit a 16-bit
    }

    *temp_c = raw * 0.0625f; // cada LSB = 0.0625°C
    return true;
}

int main() {
    stdio_init_all();

    // Espera hasta que el host abra el CDC (opcional, timeout)
    const uint32_t start = to_ms_since_boot(get_absolute_time());
    while (!stdio_usb_connected()) {
        if (to_ms_since_boot(get_absolute_time()) - start > 3000) break;
        tight_loop_contents();
    }

    // Inicialización de I2C
    i2c_init(I2C_PORT, I2C_BAUDRATE);
    gpio_set_function(I2C_SDA_PIN, GPIO_FUNC_I2C);
    gpio_set_function(I2C_SCL_PIN, GPIO_FUNC_I2C);
    // Pull-ups internos débiles (recomendado disponer de pull-ups externos en el breakout)
    gpio_pull_up(I2C_SDA_PIN);
    gpio_pull_up(I2C_SCL_PIN);

    // LED (si la Pico-ICE mantiene el LED en GP25)
    const uint LED_PIN = 25;
    gpio_init(LED_PIN);
    gpio_set_dir(LED_PIN, GPIO_OUT);
    bool led = false;

    // Comprobación del dispositivo I2C
    bool found = i2c_device_present(TMP102_ADDR);

    // Mensaje de cabecera JSON para fácil parsing en el host
    printf("{\"event\":\"boot\",\"sdk\":\"1.5.1\",\"i2c_baud\":%u,\"tmp102_addr\":\"0x%02X\",\"present\":%s}\n",
           I2C_BAUDRATE, TMP102_ADDR, found ? "true" : "false");

    // Bucle principal
    while (true) {
        float t_c = 0.0f;
        bool ok = tmp102_read_temp_c(&t_c);

        // Timestamps de milisegundos desde arranque para depuración
        uint32_t ms = to_ms_since_boot(get_absolute_time());

        if (ok) {
            printf("{\"ts_ms\":%u,\"addr\":\"0x%02X\",\"temp_c\":%.4f}\n", ms, TMP102_ADDR, t_c);
        } else {
            printf("{\"ts_ms\":%u,\"addr\":\"0x%02X\",\"error\":\"i2c_read_failed\"}\n", ms, TMP102_ADDR);
        }

        // Parpadeo del LED a 1 Hz aprox.
        led = !led;
        gpio_put(LED_PIN, led);

        sleep_ms(500);
    }

    return 0;
}

Puntos clave del código:
– i2c_write_blocking(…, nostop=true) + i2c_read_blocking(…) implementa la lectura con “repeated start” que exigen muchos sensores.
– La conversión a temperatura toma el dato de 12 bits en complemento a dos y lo multiplica por 0.0625 °C/LSB.
– La salida en JSON por línea hace muy sencilla la validación con Python en el host.

CMakeLists.txt

# CMakeLists.txt
cmake_minimum_required(VERSION 3.13)
set(PICO_SDK_PATH $ENV{PICO_SDK_PATH})

include(${PICO_SDK_PATH}/external/pico_sdk_import.cmake)

project(i2c_temp_pico_ice C CXX ASM)
set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)

pico_sdk_init()

add_executable(i2c_temp_pico_ice
    main.c
)

target_link_libraries(i2c_temp_pico_ice
    pico_stdlib
    hardware_i2c
)

# Habilitar STDIO por USB y deshabilitar UART
pico_enable_stdio_usb(i2c_temp_pico_ice 1)
pico_enable_stdio_uart(i2c_temp_pico_ice 0)

pico_add_extra_outputs(i2c_temp_pico_ice)

Script Python (host) para leer /dev/ttyACM0 y mostrar lecturas

Este script abre el puerto serie USB de la Pico-ICE (CDC ACM) y parsea las líneas JSON, mostrando la temperatura y una barra visual simple.

# host_read_serial.py
# Requiere: pyserial==3.5, rich==13.7.1 (en el venv)
import json
import sys
import time
import serial
from rich.console import Console
from rich.table import Table

PORT = "/dev/ttyACM0"
BAUD = 115200

def main():
    console = Console()
    console.print(f"[bold green]Abriendo puerto {PORT} a {BAUD} baudios...[/bold green]")

    try:
        ser = serial.Serial(PORT, BAUD, timeout=2)
    except Exception as e:
        console.print(f"[bold red]Error al abrir {PORT}: {e}[/bold red]")
        sys.exit(1)

    # Tabla dinámica
    table = Table(title="Lectura TMP102 desde Pico-ICE (USB CDC)")
    table.add_column("ts_ms", justify="right")
    table.add_column("addr")
    table.add_column("temp_c", justify="right")
    table.add_column("bar")

    # Leer líneas indefinidamente
    try:
        while True:
            line = ser.readline().decode("utf-8", errors="ignore").strip()
            if not line:
                continue

            # Intenta parsear JSON; si falla, lo muestra crudo
            try:
                obj = json.loads(line)
                if "temp_c" in obj:
                    t = float(obj["temp_c"])
                    ts = obj.get("ts_ms", "")
                    addr = obj.get("addr", "")
                    # Barra proporcional simple
                    bars = int(max(0, min(50, (t + 10) * 1.5)))
                    bar = "█" * bars
                    table.rows = []  # limpiar y mostrar solo la última
                    table.add_row(str(ts), str(addr), f"{t:0.2f}", bar)
                    console.clear()
                    console.print(table)
                else:
                    console.print(f"[yellow]{line}[/yellow]")
            except json.JSONDecodeError:
                console.print(f"[cyan]{line}[/cyan]")

    except KeyboardInterrupt:
        console.print("[bold]Saliendo[/bold]")
    finally:
        ser.close()

if __name__ == "__main__":
    main()

Compilación, flasheo y ejecución

1) Estructura de proyecto y configuración

Crea la estructura del proyecto en tu home:

cd ~
mkdir -p pico-projects/i2c_temp_pico_ice
cd pico-projects/i2c_temp_pico_ice

Copia dentro main.c y CMakeLists.txt tal como se han mostrado.

Verifica que la variable de entorno PICO_SDK_PATH está definida y apunta a ~/pico/pico-sdk (v1.5.1):

echo $PICO_SDK_PATH
ls $PICO_SDK_PATH

2) Generación con CMake y compilación

mkdir -p build
cd build
cmake -DPICO_SDK_PATH=${PICO_SDK_PATH} ..
make -j$(nproc)

Al finalizar, deberías ver artefactos:
– i2c_temp_pico_ice.uf2
– i2c_temp_pico_ice.elf
– i2c_temp_pico_ice.bin

3) Flasheo por BOOTSEL (UF2)

1) Conecta la Pico-ICE a la Raspberry Pi host por USB-C.
2) Mantén pulsado el botón BOOTSEL de la Pico-ICE y entonces enchufa o pulsa RESET (si existe). La unidad RPI-RP2 aparecerá montada en /media/pi/RPI-RP2 (la ruta puede variar).
3) Copia el UF2:

# Ajusta la ruta de montaje si es diferente
cp i2c_temp_pico_ice.uf2 /media/$USER/RPI-RP2/
sync

La Pico-ICE se reiniciará automáticamente ejecutando el firmware.

4) Verificación con picotool (opcional)

picotool info -a

Debería mostrar información del binario cargado.

5) Ejecución (lectura por USB CDC desde el host)

• Lista dispositivos: ls /dev/ttyACM*
• Ejecuta el script Python en el venv:

source ~/venvs/pico-ice-env/bin/activate
python ~/pico-projects/i2c_temp_pico_ice/host_read_serial.py

Deberás ver la tabla actualizándose con la temperatura. Toca el sensor con un dedo y observa cómo sube la lectura.

Validación paso a paso

1) Alimentación y enumeración USB:
– dmesg | tail debe mostrar un dispositivo CDC ACM al conectar la Pico-ICE.
– Comprueba /dev/ttyACM0 (o /dev/ttyACM1 si tienes otros).

2) Mensaje de arranque (JSON):
– Al abrir el puerto, deberías ver una línea similar a:
– {«event»:»boot»,»sdk»:»1.5.1″,»i2c_baud»:100000,»tmp102_addr»:»0x48″,»present»:true}
– “present”: true indica que el RP2040 recibió ACK del dispositivo en 0x48 al inicio.

3) Lecturas periódicas:
– Cada ~500 ms: {«ts_ms»:…, «addr»:»0x48″,»temp_c»:…}
– Temperatura ambiente típica: 20–30 °C en interiores.

4) Prueba térmica:
– Toca el sensor con tu dedo 5–10 s. La lectura debería subir 2–6 °C.
– Soplar aire frío o acercarlo a una ventana abierta debería bajar la lectura.

5) Robustez del parsing:
– El script Python refresca una tabla con la última lectura. Si desconectas y reconectas el cable, vuelve a ejecutar el script tras que aparezca /dev/ttyACM0.

6) Verificación básica de I2C del host (opcional):
– Aunque el sensor está cableado al RP2040, puedes usar i2cdetect -l para listar buses del host y confirmar que I2C del host está activo. No debes ver el TMP102 en el bus del host (salvo que lo re‑cables, lo cual no es necesario en este caso práctico). Este paso sirve únicamente para confirmar que i2c-tools funcionan.

Troubleshooting (errores típicos y soluciones)

1) No aparece /dev/ttyACM0:
– Verifica el cable USB-C (datos, no solo carga).
– Prueba otro puerto USB de la Raspberry Pi.
– Revisa dmesg | tail para mensajes de enumeración.
– Comprueba pertenecer al grupo dialout: groups $USER
– Reinicia la Raspberry Pi si todo falla.

2) “present:false” en el mensaje de arranque:
– Direccionamiento del TMP102: ADD0 a GND → 0x48. Si tu breakout cambia la dirección, ajusta TMP102_ADDR en el código (0x49, 0x4A, 0x4B según cableado ADD0).
– Comprueba wiring: GP4→SDA, GP5→SCL, 3V3→VCC, GND→GND.
– Asegura pull-ups efectivas en SDA/SCL (4.7 kΩ a 3.3 V). Las internas del RP2040 son débiles.

3) Lecturas erráticas o NaN:
– Verifica continuidad de cables y calidad del contacto en la protoboard.
– Reduce la frecuencia I2C a 100 kHz (ya está en 100 kHz); si la subiste, vuelve a 100 kHz.
– Aleja cables I2C de fuentes de ruido (motores, convertidores DC-DC sin blindaje).

4) “i2c_read_failed” esporádicos:
– Revisa la alimentación del sensor (VCC estable 3.3 V).
– Asegúrate de que no hay dos dispositivos con la misma dirección en el mismo bus (si añadiste otros sensores).
– Acorta los cables I2C o mejora el ruteo.

5) El LED no parpadea:
– Algunas variantes/ensamblajes pueden no tener LED en GP25 o estar cableado al FPGA. El programa no depende del LED; usa la salida por serie como validación principal. Si lo deseas, comenta el bloque del LED.

6) El script Python no muestra nada:
– Verifica que el puerto sea correcto (/dev/ttyACM0 vs ACM1).
– Asegura que el venv está activado y pyserial instalado.
– Prueba minicom -D /dev/ttyACM0 -b 115200 para ver las líneas crudas.

7) Error de compilación con pico-sdk:
– Asegura PICO_SDK_PATH apuntando a la ruta del pico-sdk v1.5.1 correctamente.
– Ejecuta git submodule update –init desde pico-sdk si faltan submódulos.
– Verifica cmake –version y arm-none-eabi-gcc –version coinciden con las versiones listadas.

8) Fallo al copiar el UF2:
– Debes entrar en modo BOOTSEL: mantener pulsado BOOTSEL al conectar o reiniciar.
– Asegura que la unidad RPI-RP2 se monta (usa lsblk o dmesg).
– Si el sistema monta en solo lectura o falla, prueba otro cable USB o puerto.

Mejoras/variantes

1) Cambiar de I2C0 a I2C1:
– Usa GP6 (SDA1) y GP7 (SCL1) o cualquier par alternativo del RP2040 compatible.
– Cambia I2C_PORT a i2c1 y actualiza los pines en el código.

2) Añadir filtrado/estadística:
– Calcula media móvil o mediana sobre N lecturas.
– Publica min/max y desviación estándar en el JSON.

3) Compatibilidad con otros sensores I2C:
– MCP9808 (0x18/0x19/0x1A/0x1C): cambio de registro y fórmula de conversión.
– LM75/TMP75: lectura de 9 a 12 bits; ajustar parsing.

4) Alerta de temperatura:
– Configurar el registro de T_HIGH/T_LOW del TMP102 y usar ALERT.
– Hacer que el RP2040 envíe un evento JSON en cada alerta.

5) Integración con el FPGA iCE40UP5K (Pico-ICE):
– Usa el valor de temperatura para modular un color en un LED RGB controlado por el FPGA.
– Toolchain recomendado (si decides dar el paso):
– Yosys 0.29, nextpnr-ice40 0.4, IceStorm 0.0+20230110.
– Crea un PWM RGB sencillo en Verilog conectado a pines del FPGA cableados al LED RGB de la Pico-ICE y recibe el dato del RP2040 por un bus simple (por ejemplo, SPI o un latch de GPIO si la placa expone dicho nexo). Esta parte excede el alcance del caso práctico actual, pero la preparación de toolchain ya está indicada.

6) Registro y visualización:
– En el host, guarda JSONL a fichero y grafica con matplotlib o con herramientas como Grafana/Telegraf.
– Añade marca de tiempo del sistema en lugar de ts_ms local de firmware.

7) Robustez:
– Implementa reintentos en I2C y watchdog.
– Detecta desconexión del sensor y re‑inicializa bus.

Checklist de verificación

• [ ] Raspberry Pi OS Bookworm 64‑bit actualizado.
• [ ] Python 3.11 disponible y venv creado/activado.
• [ ] Toolchain instalada con versiones:
• [ ] CMake 3.25.1
• [ ] arm-none-eabi-gcc 12.2.Rel1
• [ ] pico-sdk v1.5.1 descargado y PICO_SDK_PATH configurado
• [ ] picotool 1.1.0
• [ ] Paquetes Python en venv: pyserial==3.5, rich==13.7.1.
• [ ] Conexiones físicas:
• [ ] 3V3 → VCC TMP102
• [ ] GND → GND TMP102
• [ ] GP4 → SDA TMP102
• [ ] GP5 → SCL TMP102
• [ ] ADD0/ADDR TMP102 → GND (dirección 0x48)
• [ ] Pull-ups en SDA/SCL presentes (breakout o externas).
• [ ] Compilación exitosa (UF2 generado).
• [ ] Flasheo por BOOTSEL correcto (unidad RPI-RP2).
• [ ] /dev/ttyACM0 aparece en el host y pertenece al usuario (grupo dialout).
• [ ] Script host_read_serial.py ejecutándose y mostrando la temperatura.
• [ ] La temperatura sube al tocar el sensor y vuelve a bajar al soltar.
• [ ] Sin errores “i2c_read_failed” persistentes (si aparecen, revisar wiring/pull-ups/frecuencia).

Con este flujo, dispones de una solución reproducible y clara para “i2c-temperature-sensor-readout” usando exactamente la placa Pico-ICE (RP2040 + iCE40UP5K), con una toolchain concreta y versiones verificables, conexiones coherentes con el modelo, código completo y validación guiada paso a paso.

Objetivo y caso de uso

Qué construirás: Un controlador de servos PWM de bajo jitter utilizando Raspberry Pi Pico-ICE y MicroPython.

Para qué sirve

• Controlar la posición de servos en proyectos de robótica.
• Implementar sistemas de automatización del hogar con control preciso de actuadores.
• Desarrollar prototipos de dispositivos interactivos que requieren movimiento controlado.

Resultado esperado

• Latencia de respuesta del servo inferior a 10 ms.
• Precisión de control de posición de ±1 grado.
• Capacidad de controlar hasta 8 servos simultáneamente con un jitter menor a 5 ms.

Público objetivo: Desarrolladores de hardware y entusiastas de la robótica; Nivel: Medio

Arquitectura/flujo: Controlador de servos conectado a Raspberry Pi Pico-ICE mediante PWM, gestionado a través de MicroPython.

Nivel: Medio

Prerrequisitos

Sistema operativo y entorno base

• Equipo anfitrión: una Raspberry Pi (cualquier modelo de 64 bits) con:
• Raspberry Pi OS Bookworm 64‑bit (versión probada: 2024-10-22)
• Kernel y firmware por defecto de Bookworm
• Python 3.11 (versión probada: 3.11.2)

Toolchain exacta (probada en este caso práctico)

La siguiente toolchain y versiones son las utilizadas y verificadas para este tutorial, orientado a programar el RP2040 de la Pico‑ICE en MicroPython y a operar desde la Raspberry Pi:

• Firmware de dispositivo:
• MicroPython para RP2040 (UF2): v1.22.2 (build rp2-pico-20240222-v1.22.2.uf2)
• Herramientas en la Raspberry Pi (host):
• mpremote (CLI): 1.23.0
• pyserial (biblioteca Python): 3.5
• gpiozero (opcional): 1.6.2
• pip: 24.2 (o posterior)
• venv de Python 3.11 (módulo estándar)
• Utilidades del sistema:
• udev y grupos de acceso serie (dialout) por defecto en Raspberry Pi OS Bookworm

Notas:
– No es necesario compilar C/C++ ni usar el SDK del RP2040 para este caso. El objetivo “pwm-servo-control” se implementa con MicroPython y PIO del RP2040, aprovechando la placa Pico‑ICE como hardware.
– Si más adelante deseas explorar el FPGA iCE40UP5K, la toolchain típica sería: Yosys (≥0.28), nextpnr-ice40 (≥0.4) e icestorm; no es requerida para este tutorial.

Habilitar interfaces y preparar el host

• Este proyecto no requiere activar SPI/I2C en la Raspberry Pi. Sin embargo:
• Asegúrate de que tu usuario pertenece al grupo dialout para acceder a /dev/ttyACM0 sin sudo.
• Opcionalmente, verifica configuración de consola serie (no usada aquí).

Comandos exactos (ejecutar en la Raspberry Pi):

# 1) Actualiza índices de paquetes
sudo apt update

# 2) Instala herramientas base
sudo apt install -y python3.11 python3-venv python3-pip python3-gpiozero

# 3) Añade tu usuario al grupo "dialout" para acceso a puertos serie
sudo usermod -aG dialout "$USER"

# 4) Cierra sesión y vuelve a entrar (o reinicia) para aplicar el grupo
#    Alternativamente:
newgrp dialout

Crear un entorno virtual y paquetes Python requeridos

Recomendado para aislar dependencias:

# Crea y activa un entorno virtual
python3 -m venv ~/venvs/picoice
source ~/venvs/picoice/bin/activate

# Actualiza pip y instala paquetes con versiones exactas
pip install --upgrade pip==24.2
pip install mpremote==1.23.0 pyserial==3.5
# gpiozero viene por apt (1.6.2), no es necesario instalarla por pip

Materiales

• 1x Placa Pico‑ICE (RP2040 + iCE40UP5K). Modelo exacto: “Pico‑ICE (RP2040 + iCE40UP5K)”
• 1x Servomotor de radiocontrol (ejemplos compatibles):
• Micro‑servo SG90 (consumo bajo; puede funcionar con 5 V, señal a 3.3 V)
• O servo estándar de 5 V con señal compatible 3.3 V (recomendado revisar hoja de datos)
• 1x Fuente de alimentación 5 V externa para el servo (mínimo 1 A para servos pequeños; 2–3 A para servos más demandantes)
• 1x Cable USB (USB‑A a micro‑USB) para la Pico‑ICE
• Cables Dupont macho‑macho (x3 mínimo: señal, 5 V, GND)
• (Opcional) Protoboard
• (Opcional) Multímetro/analizador lógico/osciloscopio para validar el PWM
• (Opcional) Resistencia de 100 Ω en serie con la señal si el cable al servo es muy largo (reduce ringing)

Notas de seguridad:
– No alimentes el servo desde el 5 V del USB de la Pico‑ICE si no estás seguro de su corriente máxima; la fuente USB puede no soportarlo y provocar reinicios o daño.
– Conecta siempre masa común (GND) entre la Pico‑ICE y la fuente del servo.

Preparación y conexión

Mapa de conexiones (servomotor de 3 hilos)

Los servos típicamente usan:
– Marrón/Negro: GND
– Rojo: +5 V
– Naranja/Amarillo/Blanco: Señal PWM (3.3 V compatible en la mayoría de servos)

En la Pico‑ICE (que mantiene el pinout compatible con Raspberry Pi Pico), usaremos el pin GPIO15 como salida PWM de control.

Tabla de cableado:

Pasos detallados:
1) Desconecta la Pico‑ICE del USB (sin alimentación).
2) Conecta el cable de señal del servo al pin GPIO15 de la Pico‑ICE.
– La Pico‑ICE usa el mismo pinout que la Raspberry Pi Pico; el pin GPIO15 está rotulado en la serigrafía del módulo.
3) Conecta el GND del servo al GND de la Pico‑ICE.
4) Conecta el +5 V del servo a la salida de tu fuente 5 V externa.
5) Une GND de la fuente externa con GND de la Pico‑ICE (común).
6) Verifica polaridad y firmeza de las conexiones.
7) Conecta la Pico‑ICE al USB de la Raspberry Pi con el cable micro‑USB. Aún no enciendas la fuente 5 V del servo.
8) Una vez cargado el firmware, enciende la fuente 5 V del servo.

Recomendación: si es tu primera prueba y tu servo es pequeño (p. ej., SG90), usa una fuente 5 V externa de 1–2 A con protección. Evita alimentarlo desde el puerto USB del ordenador.

Código completo

Objetivo: generar una señal PWM específica para servos (50 Hz, periodo 20 ms) con ancho de pulso entre ~1.0 ms (≈0°) y ~2.0 ms (≈180°), usando PIO del RP2040 en MicroPython. Implementaremos:
– Un programa PIO que recibe por FIFO dos valores: tiempo alto (high_us) y tiempo bajo (low_us), en microsegundos.
– Un lazo en MicroPython que expone una pequeña interfaz por USB CDC (serial) para:
– Fijar ángulo en grados.
– Fijar ancho de pulso en microsegundos.
– Calibrar rangos min/max.

El archivo se grabará como main.py en la Pico‑ICE.

servo_pwm.py (para grabar como main.py en la Pico‑ICE)

# main.py — Control PWM de servo con PIO (RP2040) en la Pico-ICE
# Versión probada con MicroPython v1.22.2 (rp2)
#
# Protocolo simple por USB CDC (ttyACM):
# - "A <grados>"            -> Establece ángulo (0-180)
# - "U <microsegundos>"     -> Establece pulso en us (500-2500 típ.)
# - "C <min_us> <max_us>"   -> Calibra rango en us (p. ej., 1000 2000)
# - "Q"                     -> Reporta estado actual
# Devuelve lineas "OK ..." o "ERR ..."

from rp2 import PIO, StateMachine, asm_pio
from machine import Pin
import sys
import select

# Config: pin de señal del servo
SERVO_PIN = 15  # GPIO15 en Pico-ICE

# Rango por defecto (ajustable por "C")
MIN_US = 1000
MAX_US = 2000
PERIOD_US = 20000  # 20 ms -> 50 Hz

# Estado actual
_state = {
    "angle": 90,
    "pulse_us": 1500,
    "min_us": MIN_US,
    "max_us": MAX_US,
}

# Programa PIO:
# - Pull #1: high_us -> X
# - Mantiene pin alto X ciclos (frecuencia de SM = 1 MHz => 1 ciclo = 1 us)
# - Pull #2: low_us -> Y
# - Mantiene pin bajo Y ciclos
# - Repite
@asm_pio(set_init=PIO.OUT_LOW)
def servo_prog():
    pull(block)           # high_us
    mov(x, osr)
    set(pins, 1)
    label("high")
    jmp(x_dec, "high")
    pull(block)           # low_us
    mov(y, osr)
    set(pins, 0)
    label("low")
    jmp(y_dec, "low")
    jmp("servo_prog")     # bucle

# Inicializa PIO a 1 MHz para que 1 instrucción = ~1 us
sm = StateMachine(0, servo_prog, freq=1_000_000, set_base=Pin(SERVO_PIN))
sm.active(1)

def _clamp(v, vmin, vmax):
    return max(vmin, min(vmax, v))

def angle_to_us(angle, min_us=None, max_us=None):
    if min_us is None:
        min_us = _state["min_us"]
    if max_us is None:
        max_us = _state["max_us"]
    angle = _clamp(angle, 0, 180)
    us = int(min_us + (max_us - min_us) * (angle / 180.0))
    return us

def set_pulse_us(pulse_us):
    pulse_us = _clamp(int(pulse_us), 300, PERIOD_US - 300)
    low_us = PERIOD_US - pulse_us
    # Publica a la FIFO del PIO (dos palabras de 32 bits)
    sm.put(pulse_us)
    sm.put(low_us)
    _state["pulse_us"] = pulse_us
    # Actualiza "angle" si está dentro del rango calibrado
    if _state["min_us"] < _state["max_us"]:
        span = _state["max_us"] - _state["min_us"]
        # Si span > 0, mapea su inversa dentro de 0-180 (aproximado)
        if span > 0:
            rel = _clamp((pulse_us - _state["min_us"]) / span, 0.0, 1.0)
            _state["angle"] = int(round(180 * rel))

def set_angle(angle_deg):
    pulse_us = angle_to_us(angle_deg)
    set_pulse_us(pulse_us)

def calibrate(min_us, max_us):
    min_us = int(min_us)
    max_us = int(max_us)
    if min_us < 300 or max_us > 2700 or (max_us - min_us) < 400:
        return False
    _state["min_us"] = min_us
    _state["max_us"] = max_us
    return True

def report():
    return f'OK angle={_state["angle"]} pulse_us={_state["pulse_us"]} range=({ _state["min_us"] },{ _state["max_us"] }) pin={SERVO_PIN}'

# Inicialización: centra el servo a 90°
set_angle(90)

# Bucle de comandos por USB CDC
poller = select.poll()
poller.register(sys.stdin, select.POLLIN)

def _handle_line(line):
    line = line.strip()
    if not line:
        return
    parts = line.split()
    cmd = parts[0].upper()
    try:
        if cmd == "A" and len(parts) == 2:
            angle = int(parts[1])
            set_angle(angle)
            print(report())
        elif cmd == "U" and len(parts) == 2:
            us = int(parts[1])
            set_pulse_us(us)
            print(report())
        elif cmd == "C" and len(parts) == 3:
            min_us = int(parts[1])
            max_us = int(parts[2])
            if calibrate(min_us, max_us):
                print(report())
            else:
                print("ERR calibrate_out_of_range")
        elif cmd == "Q":
            print(report())
        else:
            print("ERR unknown_command")
    except Exception as e:
        print("ERR", str(e))

# Lazo principal
print("OK Pico-ICE servo controller ready")
print(report())

while True:
    # No bloqueante: comprueba si hay datos entrantes por USB CDC
    ev = poller.poll(50)  # 50 ms
    if ev:
        try:
            line = sys.stdin.readline()
            _handle_line(line)
        except Exception as e:
            print("ERR read:", e)

Puntos clave:
– El PIO corre a 1 MHz, por lo que cada iteración del bucle “high”/“low” equivale a 1 microsegundo.
– El RP2040 mantiene la estabilidad de 50 Hz dividiendo explícitamente el periodo: high_us + low_us = 20 000 us.
– Se expone una mínima interfaz de texto por USB CDC para poder conducir el servo desde un script host.

Script host en la Raspberry Pi (control por serie)

Este script envía comandos a la Pico‑ICE a través de /dev/ttyACM0, variando el ángulo y midiendo las respuestas.

Guárdalo como host_control.py en la Raspberry Pi (en tu home o en el proyecto):

#!/usr/bin/env python3
# host_control.py — Control del servo via USB CDC (ttyACM)
# Requiere: pyserial==3.5
import sys
import time
import serial
import argparse

def open_port(dev, baud=115200, timeout=1.0):
    return serial.Serial(dev, baudrate=baud, timeout=timeout)

def send(ser, cmd):
    ser.write((cmd.strip() + "\n").encode("ascii"))
    ser.flush()
    line = ser.readline().decode("utf-8", errors="replace").strip()
    return line

def main():
    ap = argparse.ArgumentParser(description="Control PWM servo (Pico-ICE RP2040)")
    ap.add_argument("--dev", default="/dev/ttyACM0", help="Dispositivo serie (por defecto: /dev/ttyACM0)")
    ap.add_argument("--angle", type=int, default=None, help="Fijar ángulo (0-180)")
    ap.add_argument("--us", type=int, default=None, help="Fijar pulso en microsegundos (500-2500)")
    ap.add_argument("--cal", nargs=2, type=int, metavar=("MIN_US","MAX_US"), help="Calibrar rango en us")
    ap.add_argument("--sweep", action="store_true", help="Barrido 0-180-0 continuo")
    args = ap.parse_args()

    with open_port(args.dev) as ser:
        # Lee líneas de bienvenida
        for _ in range(2):
            try:
                print(ser.readline().decode().strip())
            except:
                pass

        if args.cal:
            resp = send(ser, f"C {args.cal[0]} {args.cal[1]}")
            print(resp)

        if args.angle is not None:
            resp = send(ser, f"A {args.angle}")
            print(resp)

        if args.us is not None:
            resp = send(ser, f"U {args.us}")
            print(resp)

        if args.sweep:
            while True:
                for ang in range(0, 181, 10):
                    print(send(ser, f"A {ang}"))
                    time.sleep(0.3)
                for ang in range(180, -1, -10):
                    print(send(ser, f"A {ang}"))
                    time.sleep(0.3)
        else:
            # Consulta estado y termina
            print(send(ser, "Q"))

if __name__ == "__main__":
    sys.exit(main())

Puntos clave:
– No requiere permisos root si tu usuario pertenece a dialout.
– Por defecto busca /dev/ttyACM0, el cual aparece cuando la Pico‑ICE corre MicroPython y expone USB CDC.

Compilación/flash/ejecución

No hay compilación en este caso (microcontrolador con MicroPython). Pasos para cargar el firmware de MicroPython y tu script:

1) Descargar el firmware UF2 de MicroPython (RP2040)

Ejecuta en la Raspberry Pi:

# Ubicación de trabajo
mkdir -p ~/picoice-servo && cd ~/picoice-servo

# Descarga MicroPython v1.22.2 para RP2040 (RPi Pico compatible):
wget https://micropython.org/resources/firmware/rp2-pico-20240222-v1.22.2.uf2 -O micropython-rp2040-v1.22.2.uf2

2) Entrar en modo BOOTSEL y copiar el UF2

1) Desconecta la Pico‑ICE del USB.
2) Mantén pulsado el botón BOOTSEL de la Pico‑ICE.
3) Conecta el cable USB a la Raspberry Pi y suelta BOOTSEL.
4) Debería montarse una unidad USB de nombre RPI-RP2.
5) Copia el archivo UF2:

# Sustituye /media/$USER/RPI-RP2 por el punto de montaje real detectado en tu sistema
cp micropython-rp2040-v1.22.2.uf2 /media/$USER/RPI-RP2/
sync

6) La Pico‑ICE se reiniciará automáticamente en MicroPython.

Verifica el dispositivo serie:

ls -l /dev/ttyACM*
# Deberías ver algo como /dev/ttyACM0

3) Copiar el código main.py a la Pico‑ICE

Con el venv activado y mpremote instalado:

# Asegúrate de estar en el venv:
source ~/venvs/picoice/bin/activate

# Crea el archivo con el código de MicroPython (desde antes) en local
nano servo_pwm.py
# (pega el contenido de main.py mostrado en la sección de código completo y guarda)

# Copia a la Pico-ICE como main.py usando mpremote
mpremote connect /dev/ttyACM0 fs cp servo_pwm.py :main.py

# Reinicia suave para ejecutar main.py
mpremote connect /dev/ttyACM0 soft-reset

Si todo es correcto, al reconectar por serie verás:
– “OK Pico‑ICE servo controller ready”
– El estado inicial con ángulo 90°.

4) Ejecutar el script host y mover el servo

Conecta la fuente 5 V del servo, asegurando masa común con la Pico‑ICE. Luego:

# Crea el script host
nano host_control.py
# (pega el contenido mostrado en la sección de código completo y guarda)

# Asegura permisos de ejecución
chmod +x host_control.py

# Prueba: consulta estado
./host_control.py --dev /dev/ttyACM0 --angle 90
# Salida esperada: "OK angle=90 pulse_us=1500 range=(1000,2000) pin=15" y línea de bienvenida

# Mueve a 0°, 90°, 180° (tres comandos separados):
./host_control.py --dev /dev/ttyACM0 --angle 0
./host_control.py --dev /dev/ttyACM0 --angle 90
./host_control.py --dev /dev/ttyACM0 --angle 180

# Barrido continuo:
./host_control.py --dev /dev/ttyACM0 --sweep
# Interrumpe con Ctrl+C

Validación paso a paso

1) Verificación inicial (consola):
– Conecta por serie y verifica banners:
– “OK Pico‑ICE servo controller ready”
– Estado actual: p. ej., “OK angle=90 pulse_us=1500 range=(1000,2000) pin=15”.
– Ejecuta:
– ./host_control.py –dev /dev/ttyACM0 –angle 90
– Debes recibir “OK angle=90 …”.

2) Verificación del servo (física):
– Con el servo alimentado por 5 V externo y masa común con la Pico‑ICE:
– –angle 0: el servo se mueve hacia un extremo mecánico.
– –angle 90: el servo se centra.
– –angle 180: el servo se mueve hacia el otro extremo.
– Si notas zumbidos o vibraciones excesivas en los extremos, calibra el rango a 1000–2000 us (o ajusta según tu modelo):
– ./host_control.py –cal 1000 2000
– Luego repite 0–90–180.

3) Validación eléctrica (osciloscopio/analizador lógico):
– Mide en GPIO15 respecto a GND.
– Periodo constante 20 ms (50 Hz).
– Pulso alto:
– ≈1.00 ms a 0°
– ≈1.50 ms a 90°
– ≈2.00 ms a 180°
– El nivel alto debe ser ~3.3 V (tolerado por la mayoría de servos como señal).

4) Validación de estabilidad:
– Inicia un barrido:
– ./host_control.py –sweep
– Observa que el movimiento es fluido y sin reinicios de la Pico‑ICE (si hay reinicios, tu fuente 5 V del servo puede ser insuficiente).

5) Validación del protocolo:
– Envía:
– ./host_control.py –us 1200
– Espera: “OK pulse_us=1200 …”
– Envía consulta:
– ./host_control.py
– Espera: “OK angle=… pulse_us=… range=(min,max) pin=15”.

6) Validación de rango/calibración:
– Si tu servo satura antes de 0° o 180°, prueba valores p. ej., 900–2100 us.
– ./host_control.py –cal 900 2100
– ./host_control.py –angle 0
– ./host_control.py –angle 180
– Ajusta hasta lograr recorrido útil sin forzar el servo.

Troubleshooting (5–8 casos típicos)

1) No aparece /dev/ttyACM0:
– Causa: la Pico‑ICE no está en MicroPython o no enumeró USB CDC.
– Solución:
– Repite el proceso BOOTSEL y copia el UF2 de MicroPython.
– Prueba otro cable USB (de datos, no solo carga).
– Comprueba dmesg: dmesg | tail -n 50.

2) Permisos denegados al abrir el puerto:
– Causa: tu usuario no está en el grupo dialout.
– Solución:
– sudo usermod -aG dialout «$USER»
– Cierra sesión y vuelve a entrar (o newgrp dialout).

3) Servo vibra, se mueve a saltos o la Pico‑ICE se reinicia:
– Causa: fuente 5 V insuficiente para el servo o sin masa común.
– Solución:
– Usa una fuente dedicada 5 V de 1–3 A según el servo.
– Asegura GND común entre la fuente y la Pico‑ICE.
– Evita alimentar el servo desde el 5 V del USB de la placa.

4) El servo no se mueve o se mueve muy poco:
– Causa: pulso fuera del rango útil del servo o pin de señal incorrecto.
– Solución:
– Verifica que el cable de señal está en GPIO15.
– Calibra rango (p. ej., 1000–2000 us): ./host_control.py –cal 1000 2000
– Prueba con –angle 0 / 90 / 180 y observa.

5) Señal PWM no mide 50 Hz o el ancho no corresponde:
– Causa: frecuencia del PIO mal configurada.
– Solución:
– Verifica que en main.py el StateMachine está a freq=1_000_000.
– Regraba el script: mpremote fs cp servo_pwm.py :main.py; mpremote soft-reset.

6) El host_control.py no recibe “OK …”:
– Causa: el puerto no lee la línea de bienvenida o hay buffering.
– Solución:
– Añade una pausa breve tras abrir el puerto (sleep 1 s) o simplemente ignora las primeras líneas.
– Comprueba el dispositivo: ./host_control.py –dev /dev/ttyACM1 si hay múltiples dispositivos.

7) Ruidos eléctricos o movimientos erráticos con cables largos:
– Causa: integridad de señal degradada.
– Solución:
– Añade una resistencia de ~100 Ω en serie con la línea de señal cerca del servo.
– Mantén cortos los cables y usa trenzado o cables de mejor calidad.

8) El servo golpea contra topes mecánicos:
– Causa: rango de pulso demasiado amplio para ese servo.
– Solución:
– Reduce el rango (p. ej., 1100–1900 us): ./host_control.py –cal 1100 1900.

Mejoras/variantes

• Control de múltiples servos:
• Replicar el programa PIO en distintas StateMachines o usar una PIO con múltiples pines y turnos, cuidando el periodo de 20 ms por canal.
• Suavizado y rampas:
• Implementar rampas de aceleración/desaceleración en el lado MicroPython (p. ej., incrementos de 5° cada 20 ms) para movimientos más suaves.
• Lectura de un potenciómetro:
• Añadir un potenciómetro conectado a un ADC del RP2040 y mapear su lectura a un ángulo del servo, manteniendo el mismo motor PIO de PWM.
• Persistencia de calibración:
• Guardar en flash (p. ej., en un archivo JSON) los valores min_us y max_us establecidos con “C”.
• Interfaz de usuario en el host:
• Aplicación Tkinter simple que mueva una barra deslizante y envíe comandos “A ” por pyserial.
• Uso del FPGA iCE40UP5K (variante avanzada):
• Implementar el generador de PWM en el FPGA (iCE40UP5K) y usar el RP2040 como maestro SPI para enviar nuevos anchos de pulso. Requiere toolchain Yosys/nextpnr/icestorm y mapeo de pines a los conectores disponibles en la Pico‑ICE.
• Telemetría:
• Enviar por USB CDC lecturas de tensión de la fuente (si añades un divisor y ADC) o registro de eventos para diagnóstico.

Checklist de verificación

• [ ] SO: Raspberry Pi OS Bookworm 64‑bit (2024‑10‑22 o similar) con Python 3.11 operativo.
• [ ] Entorno virtual creado y activo: ~/venvs/picoice.
• [ ] Paquetes instalados: mpremote==1.23.0, pyserial==3.5, gpiozero (1.6.2 por apt).
• [ ] Usuario en grupo dialout y acceso a /dev/ttyACM0 sin sudo.
• [ ] Firmware MicroPython v1.22.2 cargado en la Pico‑ICE (UF2 correcto).
• [ ] Conexiones:
• [ ] Señal del servo al GPIO15 de la Pico‑ICE.
• [ ] GND del servo unido a GND de la Pico‑ICE y a GND de la fuente 5 V.
• [ ] +5 V del servo desde la fuente externa (no desde el USB de la placa, salvo micro-servos muy ligeros bajo tu responsabilidad).
• [ ] Código main.py (servo_pwm.py) copiado a la Pico‑ICE y ejecutándose (mensajes “OK …” por USB).
• [ ] Script host_control.py ejecuta y reporta estado con “Q”.
• [ ] El servo responde a –angle 0/90/180 sin vibraciones excesivas.
• [ ] Validación de PWM (opcional con instrumento): 50 Hz y 1.0–2.0 ms según ángulo.
• [ ] Si fue necesario, calibración aplicada (p. ej., 1000–2000 us) y guardada en tu flujo de trabajo.

Apéndice: Tabla-resumen de herramientas y versiones (este proyecto)

Con este caso práctico has implementado un control de servomotor por PWM en la Pico‑ICE, apoyándote en PIO del RP2040 con MicroPython y manejándolo desde una Raspberry Pi con Bookworm 64‑bit y Python 3.11. La arquitectura resultante es robusta para ampliarla a múltiples canales, añadir rampas de movimiento e incluso llevar la generación a hardware en el FPGA iCE40UP5K en una variante más avanzada.

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.

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.

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)”.