Raspberry Pi 5: GPIO non funzionano in Python, cosa controllare

Se i GPIO del Raspberry Pi 5 non funzionano in uno script Python, controlla prima la libreria usata e l’ambiente di esecuzione. Il vecchio RPi.GPIO originale non supporta il Pi 5; installare un pacchetto in un interprete diverso da quello usato dall’editor può invece produrre un semplice errore di modulo mancante. Nessuno dei due casi dimostra che i pin siano guasti.

Questa guida riguarda Raspberry Pi 5 con Raspberry Pi OS e Python 3. È una procedura documentale di diagnosi, non un collaudo elettrico della tua scheda. Prima di toccare fili o moduli, spegni il sistema e scollega l’alimentazione. I segnali GPIO lavorano a 3,3 V e non tollerano ingressi a 5 V: non confondere i pin di alimentazione del connettore con quelli di segnale.

Perché uno script del vecchio Raspberry Pi può fallire

Il connettore familiare non garantisce che il software acceda all’hardware nello stesso modo. Sul Pi 5 i GPIO passano attraverso il controller RP1. Il documento ufficiale Raspberry Pi sulle librerie GPIO distingue le vecchie soluzioni che accedono direttamente ai registri dalle interfacce compatibili con l’architettura attuale.

Per un nuovo progetto, GPIO Zero con un backend compatibile come lgpio è un punto di partenza più adatto del vecchio RPi.GPIO. Per un programma esistente, però, installare GPIO Zero non converte automaticamente il codice: le API sono diverse. Il documento descrive anche rpi-lgpio come alternativa compatibile con l’API RPi.GPIO; la scelta va verificata rispetto alle funzioni realmente usate dal progetto, non applicata come sostituzione universale.

Leggi l’errore prima di installare altri pacchetti

• ModuleNotFoundError: il modulo richiesto non è visibile all’interprete che esegue il programma. Controlla nome della libreria e ambiente Python.
• BadPinFactory o errore del backend: GPIO Zero può essere presente, ma non trovare un’interfaccia utilizzabile per accedere ai pin. L’importazione e l’accesso hardware sono due passaggi distinti.
• Il programma parte ma il dispositivo non reagisce: solo a questo punto diventano centrali numerazione, configurazione del progetto e collegamenti, senza escludere un errore nel codice.

Dal terminale che usi per avviare lo script, questi comandi mostrano l’interprete e la posizione del modulo. Non comandano uscite GPIO:

python3 -c "import sys; print(sys.executable)"
python3 -c "import gpiozero; print(gpiozero.__file__)"

Se l’editor usa un altro interprete, confronta il percorso nelle sue impostazioni. Un pacchetto installato correttamente nel Python di sistema può risultare assente in un ambiente virtuale isolato. Anche dopo un nuovo allestimento di Linux, sistema operativo e dipendenze del singolo progetto restano livelli distinti.

Installazione e ambiente virtuale: evita di mescolare i livelli

GPIO Zero è normalmente già presente in Raspberry Pi OS. Se manca, la documentazione di installazione GPIO Zero indica il pacchetto di sistema:

sudo apt update
sudo apt install python3-gpiozero

Per creare un nuovo ambiente virtuale che possa vedere anche i pacchetti di sistema, la documentazione propone questa impostazione:

python3 -m venv gpiozero-env --system-site-packages
source ./gpiozero-env/bin/activate

Se usi invece un ambiente completamente isolato, devi gestire al suo interno anche le dipendenze e il backend necessari. Non ricorrere a sudo pip o a permessi aperti indiscriminatamente sui dispositivi per aggirare un errore non ancora compreso.

Attenzione ai tutorial datati: la documentazione corrente segnala che il problema della pin factory lgpio con l’installazione pip su Pi 5 è stato corretto in GPIO Zero 2.0.1.post3, a luglio 2026. Dire oggi che “pip non funziona sul Pi 5” senza specificare versione e dipendenze è quindi fuorviante.

Solo dopo verifica numerazione e cablaggio

In GPIO Zero i numeri interi dei pin seguono normalmente la numerazione BCM, non la posizione fisica sul connettore. Controlla lo schema della libreria e quello del progetto: il diciassettesimo contatto fisico non diventa automaticamente GPIO17. Evita inoltre di copiare un numero di dispositivo gpiochip trovato in una vecchia guida senza verificare il sistema in uso.

Gli esempi per altre schede, come i progetti con ESP32 e Home Assistant, non forniscono una mappa dei pin trasferibile al Raspberry Pi. Prima di ricollegare qualsiasi modulo, verifica tensioni ammesse, massa comune quando richiesta e schema del produttore.

La diagnosi è completa quando sai quale interprete esegue il codice, quale libreria usa, quale backend accede ai GPIO e quale numerazione richiede il progetto. Conserva versione del sistema, errore completo e programma minimo riproducibile: sono informazioni più utili di un elenco di pacchetti installati per tentativi.