Documento Tecnico: Installazione di Google Coral M.2/PCIe su Debian con Pyenv e Python 3.9

Ultimo Aggiornamento: 24 Maggio 2025 Contesto: Basato su un’installazione eseguita a Senago (Lombardia), Italia.

1. Introduzione

Questo documento fornisce una guida dettagliata per l’installazione degli acceleratori Google Coral (M.2 o Mini PCIe) su un sistema Debian (testato su Debian 11/12 con CPU x86_64). L’obiettivo è utilizzare una versione specifica di Python (3.9) gestita tramite pyenv, affrontando e risolvendo le problematiche che emergono quando non si utilizza il Python di sistema predefinito e quando si incontrano dipendenze software con versioni specifiche o link obsoleti.

La guida integra le istruzioni ufficiali di Google con soluzioni pratiche derivate da esperienze reali, in particolare evidenziando perché l’approccio apt-get per le librerie Python può fallire e come procedere con pip in modo mirato.

2. Prerequisiti

2.1. Hardware

• Computer con sistema Debian 64-bit (10 o superiore).
• Architettura x86-64 (o ARMv8).
• Uno slot M.2 o Mini PCIe disponibile.
• Supporto per MSI-X (PCI 3.0).
• Acceleratore Google Coral M.2 o Mini PCIe.

2.2. Software (Obiettivo)

• Python 3.9.x.

3. Fase 1: Preparazione dell’Ambiente Python (pyenv)

Per evitare conflitti con il Python di sistema, utilizzeremo pyenv per installare e gestire Python 3.9.

1. Installare le Dipendenze di Compilazione:

   sudo apt update
   sudo apt install -y make build-essential libssl-dev zlib1g-dev \
   libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
   libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev \
   liblzma-dev python3-openssl git

2. Installare pyenv:

   curl [https://pyenv.run](https://pyenv.run) | bash

3. Configurare la Shell: Aggiungere le seguenti righe al file di configurazione della propria shell (es. ~/.bashrc) e riavviare la shell (exec "$SHELL"):

   export PYENV_ROOT="$HOME/.pyenv"
   command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
   eval "$(pyenv init -)"

4. Installare e Attivare Python 3.9:

   pyenv install 3.9.13
   pyenv global 3.9.13
   # Verifica
   python3 --version 
   # Output atteso: Python 3.9.13

4. Fase 2: Installazione dei Driver di Sistema (apt)

Questa fase installa i componenti a basso livello necessari per la comunicazione con la TPU, seguendo la guida ufficiale.

1. Controllo Kernel:

   uname -r

   • Se è 4.19 o superiore, verificare lsmod | grep apex. Se l’output è vuoto, procedere. Altrimenti, consultare la guida ufficiale per il workaround.
2. Aggiungere Repository Google Coral:

   echo "deb [https://packages.cloud.google.com/apt](https://packages.cloud.google.com/apt) coral-edgetpu-stable main" | sudo tee /etc/apt/sources.list.d/coral-edgetpu.list
   curl [https://packages.cloud.google.com/apt/doc/apt-key.gpg](https://packages.cloud.google.com/apt/doc/apt-key.gpg) | sudo apt-key add -
   sudo apt-get update

3. Installare Driver e Runtime di Sistema:

   sudo apt-get install gasket-dkms libedgetpu1-std

4. Aggiungere Regole udev (Consigliato):

   sudo sh -c "echo 'SUBSYSTEM==\"apex\", MODE=\"0660\", GROUP=\"apex\"' >> /etc/udev/rules.d/65-apex.rules"
   sudo groupadd apex
   sudo adduser $USER apex

5. Riavviare il Sistema:

   sudo reboot

6. Verificare l’Installazione Hardware: Dopo il riavvio, eseguire:

   lspci -nn | grep 089a 
   # Dovrebbe mostrare l'ID 089a del dispositivo Coral
   ls /dev/apex_0
   # Dovrebbe mostrare /dev/apex_0

5. Fase 3: Installazione Librerie Python (pip) - Il Metodo Corretto

Questa è la fase più critica, dove deviamo dalla guida ufficiale per gestire il nostro ambiente pyenv.

5.1. La Trappola di apt

La guida ufficiale suggerisce sudo apt-get install python3-pycoral. Questo comando NON funzionerà nel nostro scenario perché apt tenterà di installare il pacchetto per il Python di sistema (es. 3.11), incontrando conflitti di versione. Dobbiamo usare pip.

5.2. Installazione con pip

Assicurarsi di essere nell’ambiente Python 3.9 (python3 --version deve restituire 3.9.13).

1. Installare tflite-runtime:
   • Poiché i link diretti sono spesso obsoleti, usiamo l’indice pip di Google:

     pip install tflite-runtime==2.5.0.post1 --extra-index-url [https://google-coral.github.io/py-repo/](https://google-coral.github.io/py-repo/)

2. Installare pycoral:
   • Scarichiamo il file .whl specifico per Python 3.9 da GitHub:

     wget [https://github.com/google-coral/pycoral/releases/download/v2.0.0/pycoral-2.0.0-cp39-cp39-linux_x86_64.whl](https://github.com/google-coral/pycoral/releases/download/v2.0.0/pycoral-2.0.0-cp39-cp39-linux_x86_64.whl)
     pip install pycoral-2.0.0-cp39-cp39-linux_x86_64.whl

3. Correggere NumPy:
   • È probabile che sia stato installato NumPy 2.x, incompatibile con questi pacchetti. Eseguiamo il downgrade:

     pip install "numpy<2"

6. Fase 4: Verifica Finale

Eseguiamo un esempio per confermare che tutto funzioni.

1. Ottenere gli Esempi:

   mkdir ~/coral && cd ~/coral
   git clone [https://github.com/google-coral/pycoral.git](https://github.com/google-coral/pycoral.git)
   cd pycoral

2. Scaricare i Requisiti dell’Esempio:

   bash examples/install_requirements.sh classify_image.py

3. Eseguire l’Inferenza:

   python3 examples/classify_image.py \
   --model test_data/mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite \
   --labels test_data/inat_bird_labels.txt \
   --input test_data/parrot.jpg

Se l’output mostra Ara macao (Scarlet Macaw): 0.75781 e i tempi di inferenza, l’installazione è stata completata con successo.

7. Conclusioni

L’installazione di Google Coral su Debian, specialmente con requisiti di versione Python personalizzati, richiede un approccio mirato. L’uso di pyenv è fondamentale per isolare l’ambiente. È essenziale riconoscere i limiti di apt per le librerie Python in questo contesto e affidarsi a pip, utilizzando strategie come --extra-index-url per reperire pacchetti specifici. Infine, la gestione delle versioni delle dipendenze, come NumPy, è cruciale per la compatibilità. Seguendo questi passaggi, è possibile ottenere un’installazione stabile e funzionale della Google Coral Edge TPU.

---