Raspberry Pi 5 con Yocto Scarthgap: Guía práctica

Raspberry Pi 5 cambió a núcleos Cortex-A76 y movió la E/S al chip southbridge RP1. Compilar con Yocto requiere más que solo cambiar el nombre de MACHINE de RPi4.

Esta guía te lleva paso a paso por la compilación de una imagen headless de Raspberry Pi 5 con Wi-Fi usando Yocto Scarthgap 5.0 LTS. Cubre el problema de compatibilidad con U-Boot, soluciones para el driver Wi-Fi y problemas conocidos.

Qué cambió en RPi5

RPi5 tiene una arquitectura fundamentalmente diferente de RPi4. Esto es lo que importa para las compilaciones de Yocto.

El mayor cambio es el southbridge RP1. En RPi4, Ethernet, USB y GPIO estaban integrados en el SoC. En RPi5, estos son gestionados por el chip RP1 conectado vía PCIe x4. Esto significa diferentes device trees y configuraciones de drivers. Para RPi3 o RPi4, consulta la guía de compilación para RPi.

Configuración del entorno de compilación

Preparación del host

Se recomienda Ubuntu 24.04 LTS. Instala los paquetes necesarios.

sudo apt update
sudo apt install -y gawk wget git diffstat unzip texinfo gcc build-essential \
  chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils \
  iputils-ping python3-git python3-jinja2 python3-subunit zstd liblz4-tool \
  file locales libacl1
sudo locale-gen en_US.UTF-8

Clonar Poky y las meta-capas

mkdir -p ~/yocto && cd ~/yocto
git clone -b scarthgap git://git.yoctoproject.org/poky
git clone -b scarthgap git://git.openembedded.org/meta-openembedded
git clone -b scarthgap git://git.yoctoproject.org/meta-raspberrypi
git clone -b scarthgap/u-boot https://git.yoctoproject.org/meta-lts-mixins

meta-raspberrypi usa la rama scarthgap. meta-lts-mixins usa la rama scarthgap/u-boot. La siguiente sección explica por qué se necesita esta última capa.

Configurar bblayers.conf

source poky/oe-init-build-env build-rpi5

Añade las capas a conf/bblayers.conf.

# conf/bblayers.conf
BBLAYERS ?= " \
  /home/user/yocto/poky/meta \
  /home/user/yocto/poky/meta-poky \
  /home/user/yocto/poky/meta-yocto-bsp \
  /home/user/yocto/meta-openembedded/meta-oe \
  /home/user/yocto/meta-openembedded/meta-python \
  /home/user/yocto/meta-openembedded/meta-networking \
  /home/user/yocto/meta-raspberrypi \
  /home/user/yocto/meta-lts-mixins \
"

El problema de U-Boot y su solución

Por qué se necesita meta-lts-mixins

Scarthgap incluye U-Boot v2024.01 por defecto. El soporte para RPi5 se añadió por primera vez en U-Boot v2024.04. El U-Boot predeterminado de Scarthgap simplemente no funciona en RPi5.

meta-lts-mixins (rama scarthgap/u-boot) retroporta U-Boot v2024.04 a Scarthgap. Añadir esta capa hace que U-Boot arranque correctamente en RPi5.

Alternativa: arranque directo del kernel

Puedes saltarte U-Boot completamente y arrancar el kernel directamente desde el firmware de RPi5. Sin embargo, U-Boot proporciona flexibilidad para arranque por red, cambio de particiones A/B y otras funcionalidades. A menos que tengas una razón específica para evitarlo, usa meta-lts-mixins con U-Boot.

Configuración de la compilación

Configuración básica

# conf/local.conf
MACHINE = "raspberrypi5"

# Colocar sstate-cache y descargas fuera del directorio de compilación
SSTATE_DIR = "/home/user/yocto/sstate-cache"
DL_DIR = "/home/user/yocto/downloads"

Para detalles sobre la optimización de sstate-cache, consulta la guía de optimización de velocidad de compilación.

Habilitar systemd

Para operación headless, usa systemd como gestor de init.

# conf/local.conf
DISTRO_FEATURES:append = " systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED:append = " sysvinit"
VIRTUAL-RUNTIME_init_manager = "systemd"
VIRTUAL-RUNTIME_initscripts = "systemd-compat-units"

Para crear servicios systemd personalizados, consulta la guía de servicios systemd.

Configuración de Wi-Fi

Hacer funcionar el Wi-Fi en RPi5 requiere añadir explícitamente los módulos del kernel y el firmware.

# conf/local.conf — habilitar Wi-Fi
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-brcmfmac"
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-brcmfmac-wcc"
IMAGE_INSTALL:append = " wireless-regdb-static"
IMAGE_INSTALL:append = " wpa-supplicant"

brcmfmac-wcc es un módulo de dependencia para el driver Wi-Fi de Broadcom. Sin él, la interfaz Wi-Fi no será detectada. wireless-regdb-static proporciona la base de datos regulatoria inalámbrica para tu país.

Incluir credenciales Wi-Fi en la imagen

Usa un bbappend para incluir la configuración de wpa_supplicant en el momento de la compilación.

# meta-mylayer/recipes-connectivity/wpa-supplicant/wpa-supplicant_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI:append = " file://wpa_supplicant-wlan0.conf"

do_install:append() {
    install -d ${D}${sysconfdir}/wpa_supplicant/
    install -m 0600 ${WORKDIR}/wpa_supplicant-wlan0.conf \
        ${D}${sysconfdir}/wpa_supplicant/wpa_supplicant-wlan0.conf
}

# meta-mylayer/recipes-connectivity/wpa-supplicant/files/wpa_supplicant-wlan0.conf
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=0
update_config=1
country=US

network={
    ssid="YOUR_SSID"
    psk="YOUR_PASSWORD"
    key_mgmt=WPA-PSK
}

Configurar systemd-networkd para Wi-Fi

# meta-mylayer/recipes-core/systemd/systemd_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI:append = " file://wlan0.network"

do_install:append() {
    install -d ${D}${sysconfdir}/systemd/network/
    install -m 0644 ${WORKDIR}/wlan0.network \
        ${D}${sysconfdir}/systemd/network/wlan0.network
}

# meta-mylayer/recipes-core/systemd/files/wlan0.network
[Match]
Name=wlan0

[Network]
DHCP=ipv4

Habilitar el servicio wpa_supplicant en el arranque

# meta-mylayer/recipes-connectivity/wpa-supplicant/wpa-supplicant_%.bbappend (añadir a lo anterior)
SYSTEMD_AUTO_ENABLE:${PN} = "enable"

Con systemd-networkd y wpa_supplicant trabajando juntos, el dispositivo se conecta al Wi-Fi automáticamente en el arranque.

Compilación y flasheo

Ejecutar la compilación

bitbake core-image-base

La primera compilación toma varias horas dependiendo del hardware. Aplica las optimizaciones de velocidad de compilación de antemano para reducir el tiempo de espera.

Flashear a tarjeta SD

cd tmp/deploy/images/raspberrypi5/
# Usando bmaptool (recomendado)
sudo bmaptool copy core-image-base-raspberrypi5.wic.bz2 /dev/sdX

# Usando dd
bzcat core-image-base-raspberrypi5.wic.bz2 | sudo dd of=/dev/sdX bs=4M status=progress
sync

Verificar

Inserta la tarjeta SD en RPi5 y enciende. Conéctate vía consola serial (UART) o HDMI.

# Verificar Wi-Fi
ip addr show wlan0
ping -c 3 8.8.8.8

Si wlan0 tiene una dirección IP asignada, la configuración está completa.

Problemas conocidos y soluciones

Interfaz Wi-Fi no detectada

Síntoma: wlan0 no aparece en la salida de ip link.

Causa: Módulo del kernel brcmfmac-wcc faltante.

Solución: Añadir a conf/local.conf:

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-brcmfmac-wcc"
IMAGE_INSTALL:append = " wireless-regdb-static"

Fallo de arranque con vc4graphics + meta-networking

Síntoma: RPi5 no arranca después de añadir la capa meta-networking.

Causa: Conflicto conocido entre la MACHINE_FEATURE vc4graphics y meta-networking (issue #1383 de meta-raspberrypi).

Solución: Para compilaciones headless donde la aceleración GPU no es necesaria, elimina vc4graphics.

# conf/local.conf
MACHINE_FEATURES:remove = "vc4graphics"

Problema de USB en U-Boot

Síntoma: La función USB Mass Storage (UMS) de U-Boot no funciona en RPi5.

Causa: Problema de device tree en U-Boot (issue #1464 de meta-raspberrypi).

Solución: Esto no afecta al arranque normal. Si necesitas la funcionalidad UMS, monitorea el issue para actualizaciones.

Conclusión

Compilar una imagen headless con Wi-Fi para RPi5 con Yocto Scarthgap, paso a paso.

El southbridge RP1 de RPi5 introdujo una estructura de device tree diferente de RPi4. Pero meta-raspberrypi y meta-lts-mixins se encargan del trabajo pesado — los cambios que necesitas hacer son limitados.

Los problemas conocidos (driver Wi-Fi, conflicto vc4graphics) tienen soluciones documentadas. Revisa los issues de meta-raspberrypi periódicamente y elimina las soluciones temporales cuando las correcciones lleguen upstream.