Guida al montaggio di PULP-Dronet
Navigazione visiva per nanodroni con inferenza CNN a bordo di un processore PULP.
Licenza
Apache 2.0
I file del repository sono Apache-2.0. Il dataset PULP-Dronet v3 (zenodo.org/records/13348430) è CC BY-NC-SA 4.0, quindi è per uso non commerciale. I moduli esterni mantengono le proprie licenze, descritte nel file LICENSE_README.md del repository. Verificato il 2 nov 2026.
Guida al montaggio
1. Cosa pubblica la fonte originale e le versioni necessarie
PULP-Dronet è hardware acquistato più software. La fonte originale non pubblica alcuna costruzione meccanica: il Crazyflie 2.1 e l'AI-deck si acquistano da Bitcraze, e il lavoro consiste nel montare il deck, compilare e caricare due programmi e, facoltativamente, rigenerare il codice della rete. Il percorso di questa guida è il README di Tiny-PULP-Dronet v3.
1.1 Conosci le versioni richieste dal progetto originale
Il software di volo funziona solo con il tag 2022.01 del firmware Crazyflie e con GAP SDK 3.9.1.
- I requisiti del progetto originale per il volo sono: il gap-sdk installato (tag 3.9.1), crazyflie-firmware tag 2022.01 scaricato in drone-applications/external/crazyflie-firmware/, il Crazyflie Client (tag 2022.01) e crazyflie-lib-python (tag 0.1.17.1).
- Avviso del progetto originale: «non c'è compatibilità con le nuove versioni, perché il firmware del crazyflie è cambiato drasticamente».
- Il tutorial di Bitcraze sull'AI-deck dice di aggiornare il Crazyflie all'ultima release. Non farlo per questo progetto, a causa dell'avviso qui sopra.
- Nel repository del client Crazyflie il tag che il progetto originale chiama 2022.01 si chiama 2022.1.
- L'SDK è stato testato su Ubuntu 20.04.6 LTS con gcc 9.4.0 (9.4.0-1ubuntu1~20.04.2) e un ambiente conda con Python 3.6.10. L'ambiente di addestramento in conda_deps.yml usa Python 3.8.8.
- Questa guida segue il README di Tiny-PULP-Dronet v3. Le cartelle v1 e v2 hanno i loro README e versioni diverse degli strumenti (la v2 è stata testata con GAP SDK 3.8.1) e qui non vengono seguite.
- Il repository v3 del progetto originale contiene due reti: PULP-Dronet v3 (19 fps, 320 kB) e Tiny-PULP-Dronet v3 (139 fps, 2.9 kB).
2. Monta l'AI-deck e collega il debugger
Passaggi hardware. L'AI-deck e il Crazyflie si acquistano; il debugger serve per programmare il GAP8.
2.1 Monta l'AI-deck sul Crazyflie
Monta l'AI-deck sopra il Crazyflie 2.1 usando i pin header lunghi forniti.
- Il passaggio del progetto originale sul volo dice: «Monta l'AI-deck sopra il Crazyflie.»
- Bitcraze dice che l'AI-deck si può montare sopra o sotto usando i pin header lunghi forniti, e che la posizione superiore funziona meglio quando bisogna collegare un cavo JTAG.
2.2 Proteggi l'antenna dell'ESP32
Se il deck è sopra, metti una goccia di colla a caldo sulla fragile antenna dell'ESP32, oppure monta il deck sotto.
- L'antenna dell'ESP32 è un po' fragile e può danneggiarsi negli urti.
- Per una maggiore resistenza agli urti, Bitcraze dice di montare l'AI-deck sotto, oppure di mettere una goccia di colla a caldo come mostrato nella sua immagine.
2.3 Collega il debugger JTAG al GAP8
Usa il cavo adattatore del debugger sul connettore GAP8 a 10 pin a sinistra dell'AI-deck.
- Il passaggio del progetto originale sul caricamento del firmware dice: «Accendi l'AI-deck e collega il cavo JTAG.» Il README v3 non indica alcun debugger. I suoi comandi usano il file del cavo OpenOCD olimex-arm-usb-ocd-h.cfg, e il suo README v1 indica l'Olimex ARM-USB-OCD-H.
- Bitcraze ha testato e consiglia l'Olimex ARM-USB-TINY-H con l'adattatore ARM-JTAG-20-10. Il suo bundle contiene il programmatore ARM-USB-TINY-H, il cavo adattatore ARM-JTAG-20-10 (dall'uscita a 20 pin del programmatore ai connettori a 10 pin dell'AI-deck) e un cavo USB. Il debugger richiede un cavo USB di tipo B. L'STLink v2 non funziona, perché può fare il debug solo dei core Cortex.
- L'AI-deck ha due connettori JTAG Cortex-M a 10 pin (2x5, passo 1,27 mm), montati sul bordo. Il connettore del GAP8 è a sinistra e quello dell'ESP32 a destra guardando la scheda dall'alto con la telecamera davanti. Il pin 1 è a sinistra, indicato con un 1 sul lato inferiore della scheda.
- I due modelli Olimex sono prodotti diversi. L'SDK fornisce un file del cavo separato per ciascuno, olimex-arm-usb-ocd-h.cfg e olimex-arm-usb-tiny-h.cfg, con product id USB diversi. Qualunque debugger usi, fai puntare l'impostazione del cavo OpenOCD (GAPY_OPENOCD_CABLE, vedi il passaggio sul caricamento del firmware) al file di quel modello. I comandi di Bitcraze per l'ARM-USB-TINY-H usano interface/ftdi/olimex-arm-usb-tiny-h.cfg.
- Su Linux, aggiungi il tuo utente al gruppo dialout (sudo usermod -a -G dialout <username>) ed esci e rientra nella sessione, come nei passaggi dell'SDK.
3. Configura il computer host
Tutto questo si fa su un computer Linux. Il sistema provato dalla fonte originale è Ubuntu 20.04.6 LTS.
3.1 Clona il repository con i suoi sottomoduli
Clona pulp-dronet in modo ricorsivo, così NEMO, DORY e il visualizzatore vengono scaricati insieme.
- Esegui: git clone --recursive [email protected]:pulp-platform/pulp-dronet.git (il README riporta il flag come --recurive; gli indirizzi dei submodule nel repository sono indirizzi ssh, quindi la tua chiave ssh di GitHub deve funzionare).
- NEMO è un submodule in tiny-pulp-dronet-v3/nemo-dory/nemo/ e DORY un submodule in tiny-pulp-dronet-v3/nemo-dory/. Se il clone ricorsivo non riesce, il progetto originale dice di scaricare NEMO dal repository nemo di pulp-platform e DORY dal repository dory_dronet di LorenzoLamberti94.
3.2 Crea l'ambiente Python
Installa l'ambiente conda per addestramento, test e quantizzazione.
- Da tiny-pulp-dronet-v3 esegui: conda env create -f conda_deps.yml. L'ambiente si chiama pulp-dronet-v3.
- Il file fissa python 3.8.8, torch 1.5.0 e torchvision 0.6.0. NEMO non viene installato da lì: proviene dal submodule.
3.3 Installa i pacchetti del GAP SDK e l'ambiente conda
Crea un ambiente conda chiamato gap_sdk e installa i pacchetti necessari all'SDK.
- Esegui: conda create --name gap_sdk python==3.6.10 numpy cython e poi conda activate gap_sdk.
- Installa i pacchetti: sudo apt-get install -y build-essential git libftdi-dev libftdi1 doxygen python3-pip libsdl2-dev curl cmake libusb-1.0-0-dev scons gtkwave libsndfile1-dev rsync autoconf automake texinfo libtool pkg-config libsdl2-ttf-dev
- Serve OpenCV 3.2. Il progetto originale dice che non è più supportato ufficialmente e fornisce uno script di installazione di terze parti: wget -O - https://gist.githubusercontent.com/syneart/3e6bb68de8b6390d2eb18bff67767dcb/raw/OpenCV3.2withContrib.sh | bash. Questo esegue uno script dal gist di qualcun altro, quindi leggilo prima. Verifica con: dpkg -l | grep libopencv
3.4 Compila la toolchain e OpenOCD
Installa la toolchain GAP RISC-V e l'OpenOCD per GAP8 in una cartella gap nella tua directory home.
- Il progetto originale vuole questa struttura: /home/YOUR_USER/gap/ contenente gap_gnu_toolchain, gap8_openocd e gap-sdk.
- Toolchain: git clone https://github.com/GreenWaves-Technologies/gap_gnu_toolchain, cd gap_gnu_toolchain, git checkout 6fc27059038575e3bfef2b36ad7963a3ea77863e, ./install.sh. Se hai scelto un percorso di installazione personalizzato, aggiungi export GAP_RISCV_GCC_TOOLCHAIN="custom/path/that/you/chose" al tuo .bashrc. Il commit 6fc27059038575e3bfef2b36ad7963a3ea77863e esiste nel repository gap8_openocd ma non è stato trovato nel repository gap_gnu_toolchain il 2 novembre 2026, e il progetto originale non indica nessun'altra versione della toolchain.
- OpenOCD (commit 6fc27059038575e3bfef2b36ad7963a3ea77863e): git clone https://github.com/GreenWaves-Technologies/gap8_openocd.git, cd gap8_openocd, git checkout 6fc27059038575e3bfef2b36ad7963a3ea77863e, ./bootstrap, ./configure --program-prefix=gap8- --prefix=/usr --datarootdir=/usr/share/gap8-openocd, make -j, sudo make -j install.
- Copia le regole udev e ricaricale: sudo cp /usr/share/gap8-openocd/openocd/contrib/60-openocd.rules /etc/udev/rules.d e sudo udevadm control --reload-rules && sudo udevadm trigger.
- Aggiungi il tuo utente al gruppo dialout con sudo usermod -a -G dialout <username>, poi esci e rientra nella sessione.
3.5 Compila GAP SDK 3.9.1
Esegui il checkout del tag release-v3.9.1 del gap_sdk di GreenWaves e compilalo.
- Eseguite: git clone https://github.com/GreenWaves-Technologies/gap_sdk.git, cd gap_sdk, git checkout release-v3.9.1, git submodule update --init --recursive.
- Caricate la configurazione dell'AI-deck con source configs/ai_deck.sh. Il README la riporta una volta come configs/ai-ai_deck.sh; il file nel tag è configs/ai_deck.sh, e i comandi successivi del README usano ai_deck.sh.
- Poi eseguite: conda activate gap_sdk, pip install -r requirements.txt, pip install -r tools/nntool/requirements.txt, make sdk.
- Importante, dal progetto originale: caricate sempre la configurazione in un terminale nuovo.
3.6 Controlla che l'SDK funzioni
Esegui l'esempio helloworld nel simulatore e poi sulla scheda.
- Simulatore: cd gap_sdk/examples/pmsis/helloworld, poi make clean all run platform=gvsoc.
- Sulla scheda: export GAPY_OPENOCD_CABLE=interface/ftdi/olimex-arm-usb-ocd-h.cfg (il valore del progetto originale per l'ARM-USB-OCD-H; per un ARM-USB-TINY-H usate interface/ftdi/olimex-arm-usb-tiny-h.cfg), export GAP_RISCV_GCC_TOOLCHAIN="/home/YOUR_USER_PATH/gap/gap_gnu_toolchain", cd gap_sdk/examples/pmsis/helloworld/, poi make clean all run platform=board.
- Il progetto originale precisa che per ogni scheda sono preimpostati cavi diversi, e che per un cavo diverso si definisce GAPY_OPENOCD_CABLE come percorso del relativo file in gap_sdk/tools/gap8-openocd/tcl/interface/ftdi/.
3.7 Scarica i sorgenti e gli strumenti Crazyflie
Scarica crazyflie-firmware al tag 2022.01, il client e la libreria Python ai tag indicati dal progetto originale.
- Scaricate crazyflie-firmware al tag 2022.01 in ./drone-applications/external/crazyflie-firmware/. La cartella contiene solo un file .gitkeep, quindi il firmware non è incluso nel clone.
- Installate il Crazyflie Client al tag 2022.01 (chiamato 2022.1 in quel repository) e crazyflie-lib-python al tag 0.1.17.1.
- Il progetto originale non elenca gli strumenti di compilazione per il firmware Crazyflie.
4. Quantizza la rete e genera il codice (facoltativo)
Il repository contiene già il codice GAP8 generato per entrambe le reti in tiny-pulp-dronet-v3/drone-applications/gap8-dronet-app/, quindi questa sezione ti serve solo se modifichi la rete. Il README originale chiama quella cartella gap8_app.
4.1 Usa i pesi preaddestrati
I due modelli preaddestrati sono file nella cartella model del repository.
- I pesi sono tiny-pulp-dronet-v3/model/pulp-dronet-v3-resblock-1.0.pth e tiny-pulp-dronet-v3/model/tiny-pulp-dronet-v3-dw-pw-0.125.pth.
- Il repository ha release chiamate pulp-dronet-v3 e pulp-dronet-v2, ma nessuna delle due contiene file.
4.2 Quantizza il modello con NEMO
Esegui quantize.py per produrre il modello ONNX e le attivazioni di riferimento (golden).
- Attivate l'ambiente con conda activate pulp-dronet-v3.
- PULP-Dronet v3: python quantize.py --gpu=0 --model_weights_path=../model/pulp-dronet-v3-resblock-1.0.pth --block_type=ResBlock --depth_mult=1.0 --bypass=True --data_path_testing=./dataset/ --export_path=./nemo_output/
- Tiny-PULP-Dronet v3: python quantize.py --gpu=0 --model_weights_path=../model/tiny-pulp-dronet-v3-dw-pw-0.125.pth --block_type=Depthwise --depth_mult=0.125 --bypass=False --data_path_testing=./dataset/ --export_path=./nemo_output/
- I comandi esportano i modelli ONNX e i pesi in ./nemo_output/. Lo script si trova in tiny-pulp-dronet-v3/nemo-dory/, e i percorsi relativi nei comandi del progetto originale iniziano con ../model/, quindi eseguitelo da quella cartella.
- Il progetto originale dice di fornire modelli già quantizzati in nemo-dory/nemo-output/; quella cartella non è nel repository.
4.3 Genera il codice C con DORY
Esegui network_generate.py sul modello quantizzato.
- Attivate l'ambiente con conda activate dory. Il progetto originale non spiega come crearlo. Il README di DORY indica Python 3.6.8 con Mako 1.0.12, numpy 1.18.4, onnx 1.5.0, pandas 1.0.3 e ortools 7.5.7466.
- Da nemo-dory/dory_dronet/dory_example/ (il percorso del README; il .gitmodules del repository mette il sottomodulo DORY in nemo-dory/dory) eseguite, per PULP-Dronet v3: python network_generate.py --network_dir=../../nemo_output/pulp-dronet-v3-resblock-1.0/ --sdk=gap_sdk --Bn_Relu_Bits=64 --l2_buffer_size 410000 --l1_buffer_size 35000 --verbose_level=Check_all+Perf_final
- Per Tiny-PULP-Dronet v3: python network_generate.py --network_dir=../../nemo_output/tiny-pulp-dronet-v3-dw-pw-0.125/ --sdk=gap_sdk --Bn_Relu_Bits=64 --l2_buffer_size 410000 --l1_buffer_size 35000 --verbose_level=Check_all+Perf_final
- Il codice viene generato in dory_dronet/dory_examples/application/.
5. Programma il drone e vola
I tre passaggi originali: carica l'applicazione Crazyflie, programma il GAP8, poi vola dal client Crazyflie. Un primo avvio facoltativo tramite il debugger verifica la rete sul GAP8.
5.1 Prova la rete sul GAP8 tramite il debugger
Esegui l'applicazione dall'host senza scriverla in flash.
- Aprite un nuovo terminale, caricate l'SDK ed esportate il file del cavo: source gap_sdk/configs/ai_deck.sh ed export GAPY_OPENOCD_CABLE=$HOME/gap/gap_sdk/tools/gap8-openocd/tcl/interface/ftdi/olimex-arm-usb-ocd-h.cfg (per un ARM-USB-TINY-H usate olimex-arm-usb-tiny-h.cfg nella stessa cartella).
- PULP-Dronet v3: cd pulp-dronet/tiny-pulp-dronet-v3/drone-applications/gap8_app/pulp-dronet-v3/ ed eseguite make clean all run CORE=8 platform=board.
- Tiny-PULP-Dronet v3: cd pulp-dronet/tiny-pulp-dronet-v3/drone-applications/gap8_app/tiny-pulp-dronet-v3/ ed eseguite make clean all run CORE=8 platform=board. Nel repository la cartella si chiama gap8-dronet-app, non gap8_app.
- Il progetto originale dice che il dato di 139 fps si riferisce alla rete tiny e quello di 19 fps a PULP-Dronet v3.
5.2 Compila e carica l'applicazione Crazyflie
Compila crazyflie-dronet-app con crazyflie-firmware 2022.01 e caricala in modalità bootloader.
- La crazyflie-dronet-app è il controllore di volo. Riceve le uscite della CNN dall'AI-deck tramite UART.
- Compilate il codice: cd ./drone-applications/crazyflie-dronet-app/ ed eseguite make clean platform=cf2. Il Makefile dell'applicazione prende il firmware da ../external/crazyflie-firmware.
- Con il drone spento, tenete premuto il pulsante di accensione per 3 secondi. Il drone dovrebbe entrare in modalità bootloader.
- Poi eseguite make cload e attendete il completamento della scrittura del firmware.
5.3 Carica l'applicazione GAP8
Compila l'applicazione GAP8 e scrivila nella flash dell'AI-deck tramite il debugger.
- Accendete l'AI-deck e collegate il cavo JTAG.
- Caricate l'SDK e impostate il file del cavo: source gap_sdk/configs/ai_deck.sh ed export GAPY_OPENOCD_CABLE=$HOME/gap/gap_sdk/tools/gap8-openocd/tcl/interface/ftdi/olimex-arm-usb-ocd-h.cfg (olimex-arm-usb-tiny-h.cfg per un ARM-USB-TINY-H).
- Entrate nella cartella dell'applicazione ed eseguite make clean all e poi make flash. Il progetto originale indica la cartella come ./drone-applications/gap-dronet-app/, che non esiste. I Makefile si trovano in drone-applications/gap8-dronet-app/pulp-dronet-v3/ e drone-applications/gap8-dronet-app/tiny-pulp-dronet-v3/.
- I Makefile in quelle cartelle compilano per un solo core se CORE non è impostato (il comando di prova sopra imposta CORE=8). I comandi di scrittura del firmware del progetto originale non lo impostano.
- Ora spegnete e riaccendete il drone. Secondo il progetto originale, a quel punto PULP-Dronet è in esecuzione sull'AI-deck.
5.4 Facoltativo: trasmetti le immagini della telecamera
Attiva lo streamer JPEG e usa il visualizzatore.
- Attivate #define JPEG_STREAMER 1 in drone-applications/gap8-dronet-app/pulp-dronet-v3/DORY_network/src/main.c (lì è commentato). Usate il visualizzatore in drone-applications/gap8-dronet-app/viewer-pulp-dronet/.
- Il progetto originale dice: abbiamo sviluppato la nostra applicazione usando un firmware NINA specifico. Se acquistate un nuovo AI deck, il firmware di serie probabilmente non è compatibile. Seguite le istruzioni del repository NINA-flashing-crazyflie per scrivere il firmware corretto. La frase si trova sotto le note sullo streamer e non viene spiegata oltre.
- Il README di quel repository: docker pull bitcraze/aideck-nina, git clone https://github.com/bitcraze/aideck-gap8-examples, cd aideck-gap8-examples, git checkout a89e29072b7069b819dc930a8ca4a050b026d28d, docker pull bitcraze/aideck-nina:3.3.1, cd NINA/firmware/, poi un docker run con il file del cavo Olimex ARM-USB-OCD-H (vedere il README per il comando completo, che include make menuconfig per scegliere la modalità access point o router).
5.5 Avvia il volo
Apri il client Crazyflie, imposta il parametro fly a 1 e il drone decolla.
- L'AI-deck deve essere montato sulla parte superiore del Crazyflie.
- Avviate il Crazyflie Client con cfclient.
- Andate nella scheda Parameters del cfclient e impostate a 1 il parametro fly del gruppo START_STOP. Il drone decollerà e avvierà la navigazione autonoma.
- Se attivate i printf di debug, potete vederli nella scheda Console del cfclient.
- Il progetto originale non fornisce istruzioni di sicurezza per il volo.