🛠 Le firmware caché : mettre à jour le bridge STM32H7 M7 qui expose les périphériques à Linux

Objectives

Beneath the surface of the X8, a third system operates that the IDE never sees: the Cortex-M7 of the STM32H747XI runs a proprietary Arduino bridge firmware (repository arduino/portentax8-stm32h7-fw, latest release 0.0.3, October 2023) which is "normally invisible to the user" and maps all MCU peripherals to Linux peripherals via the x8h7_\* kernel modules (repository portentax8-x8h7). When this firmware is out of sync, Linux-side peripherals fail without the M4 sketch being at fault. This tutorial covers: diagnosis, clean update, and knowledge of open bugs (CAN TX stall).

Hardware

• 1 × Arduino Portenta X8 + USB-C data cable
• Firmware binary: STM32H747AII6_CM7.bin from the releases at github.com/arduino/portentax8-stm32h7-fw
• adb + sudo access on the board
• Release notes: docs.arduino.cc/tutorials/portenta-x8/x8-firmware-release-notes
• For low-level H7 debugging: OpenOCD stlink configuration stm32h7x_dual_bank (defined in the Mbed core's boards.txt)

Complete Code

# 1. Telecharger le binaire de firmware M7 (releases du depot officiel)
#    puis le pousser sur la carte :
adb push STM32H747AII6_CM7.bin /home/fio

# 2. Installer la mise a jour dans le STM32H747
adb shell
fio@portenta-x8:~$ cd /home/fio
fio@portenta-x8:~$ sudo ./399-install-update

# 3. Reboot : maintenir le bouton poussoir embarque ~10 s

# 4. apres reboot, verifier l'etat general
sudo journalctl -fu m4-proxy        # le pont RPC doit repasser au vert
lsmod | grep x8h7                   # modules bridge charges
dmesg | grep -i x8h7                # traces du probe des peripheriques

# Optionnel : dashboard Linux Wizard depuis le PC
#   adb forward tcp:8080 tcp:80  ->  http://localhost:8080

Expected Verification

After running 399-install-update and rebooting via the button (10 s), the x8h7_* modules are loaded (lsmod), the m4-proxy service restarts cleanly, and RPC calls work again. The procedure is exactly the one from the official image-flashing tutorial; the Linux Wizard dashboard provides an overview of the board's status. This is the first thing to do before blaming your sketch when "RPC doesn't work at all."

Common Errors

• Believing that the M7 firmware is flashed like an Arduino sketch: it is updated from Linux (adb push + sudo ./399-install-update), not from the IDE — the IDE only talks to the M4.
• Forgetting the 10-second button reboot after installation: without a reboot, the old firmware remains active and nothing changes — the official procedure explicitly requires this.
• Desynchronized firmware = ghost Linux peripherals: the M7 bridge exposes GPIO, CAN, etc. to Linux; an outdated firmware breaks these peripherals without clear application-side messages — check the firmware-release-notes page first.
• Known CAN bug: "HAL_FDCAN_TxBufferCompleteCallback silently drops the TX-complete status when the shared SPI queue is full — causes permanent Linux-side TX stall" (issue #74, open); buffer-overrun fixes have been pushed via #60/#61 — if your CAN bus freezes on the Linux side, it is a documented suspect, not your wiring.
• Inactive platform: latest firmware release October 2023 — do not expect quick fixes; test any fix hypothesis on a demo board.
• >
• >