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

Para compilar una imagen Yocto para Raspberry Pi 5, necesitas meta-lts-mixins para retroportar U-Boot a v2024.04 y configurar MACHINE=raspberrypi5. Reutilizar tu conf/local.conf de RPi4 tal cual dejará U-Boot sin poder arrancar.

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. Consulta la hoja de datos del BCM2712 para más detalles.

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. Leon Anavi publicó un artículo detallado si quieres más contexto sobre esto.

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

bmaptool es más rápido que dd porque solo escribe bloques no vacíos. Desde Scarthgap, bmaptool está oficialmente bajo el paraguas del Yocto Project.

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.

FAQ

¿Puedo reutilizar mi local.conf de RPi4 para RPi5?

Cambiar MACHINE a raspberrypi5 no es suficiente. También necesitas meta-lts-mixins (rama scarthgap/u-boot) en tu bblayers.conf, de lo contrario U-Boot no arrancará. Consulta la sección "El problema de U-Boot y su solución" en esta guía.

¿Qué pasa si no incluyo meta-lts-mixins?

U-Boot no arranca y nunca llegas al kernel. Puedes saltarte U-Boot completamente arrancando el kernel directamente desde el firmware de RPi5, pero pierdes arranque por red y cambio de particiones A/B. A menos que tengas una razón específica, añade meta-lts-mixins.

¿Cómo soluciono que el Wi-Fi no se detecte?

Lo más probable es que falte el módulo del kernel brcmfmac-wcc. Añade MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-brcmfmac-wcc" e IMAGE_INSTALL:append = " wireless-regdb-static" a local.conf. Si sigue sin funcionar, revisa dmesg | grep brcmfmac para buscar errores de carga de firmware.

¿Puedo usar una GUI (X11/Wayland) en RPi5 con Yocto?

Hay un problema conocido donde vc4graphics combinado con meta-networking causa fallos de arranque. Para compilaciones con GUI, elimina meta-networking o sigue el issue para una corrección. Para compilaciones headless, MACHINE_FEATURES:remove = "vc4graphics" lo soluciona.

¿Cuánto tarda la primera compilación?

Depende mucho de tu máquina host. Espera varias horas para una compilación limpia. Aplica las optimizaciones de la guía de velocidad de compilación — compartir sstate-cache y configurar parallel make — para reducirlo significativamente. Las compilaciones posteriores usan sstate-cache y son mucho más rápidas.

¿Puedo compilar para RPi5 con releases de Yocto diferentes a Scarthgap?

Walnascar (5.1) y posteriores incluyen U-Boot v2024.04+, así que RPi5 podría funcionar sin meta-lts-mixins. Kirkstone (4.0) tiene un U-Boot demasiado antiguo para RPi5. Si quieres LTS, Scarthgap + meta-lts-mixins es la opción más estable actualmente.

¿Cómo creo la capa personalizada que se usa en esta guía?

Los ejemplos de bbappend hacen referencia a meta-mylayer. Para los pasos de creación de capas, consulta la guía de creación de capas. Ejecuta bitbake-layers create-layer para generar una plantilla y luego añade tus archivos bbappend.

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.

Si planeas implementar actualizaciones OTA, la guía de comparación de OTA cubre RAUC, Mender y SWUpdate. Las configuraciones de partición A/B en RPi5 dependen de U-Boot, así que tener meta-lts-mixins es un prerrequisito.

Artículos relacionados:

• Compila Linux personalizado para Raspberry Pi con Yocto
• Migración de Kirkstone a Scarthgap: La lista de verificación completa
• Primeros pasos con Yocto: Compila tu primera imagen Linux
• La guía completa para compilaciones Yocto 10 veces más rápidas
• Inicio automático con systemd en Yocto: Guía con 7 errores comunes