Open Source Robotics

精選高品質的開源機器人專案、工具與軟體,推動機器人社群向前發展。

PULP-Dronet 組裝指南

奈米無人機的視覺導航,在 PULP 處理器上進行機上 CNN 推論。

授權條款

Apache 2.0

儲存庫的檔案採用 Apache-2.0。PULP-Dronet v3 資料集(zenodo.org/records/13348430)採用 CC BY-NC-SA 4.0,因此僅限非商業使用。外部模組各自保有其授權,說明見儲存庫的 LICENSE_README.md。查核日期:2026 年 11 月 2 日。

組裝指南

1. 原專案公開了什麼,以及所需的版本

PULP-Dronet 由外購硬體加上軟體構成。原專案沒有公開機構組裝:Crazyflie 2.1 與 AI-deck 都向 Bitcraze 購買,工作內容是安裝擴充板、建置並燒錄兩支程式,以及選做的重新產生網路程式碼。本指南的流程依據 Tiny-PULP-Dronet v3 README。

1.1 了解原專案要求的版本

飛行軟體只能搭配 Crazyflie 韌體標籤 2022.01 與 GAP SDK 3.9.1 使用。

  1. 原專案的飛行需求為:已安裝 gap-sdk(tag 3.9.1)、將 crazyflie-firmware tag 2022.01 下載到 drone-applications/external/crazyflie-firmware/、Crazyflie Client(tag 2022.01)與 crazyflie-lib-python(tag 0.1.17.1)。
  2. 原專案的警告:與新版本不相容,因為 crazyflie 韌體已大幅變更。
  3. Bitcraze 的 AI-deck 教學要你將 Crazyflie 更新到最新版本。由於上述警告,本專案請不要這樣做。
  4. 在 Crazyflie client 儲存庫中,原專案稱為 2022.01 的標籤名為 2022.1。
  5. SDK 在 Ubuntu 20.04.6 LTS 上以 gcc 9.4.0(9.4.0-1ubuntu1~20.04.2)及 Python 3.6.10 的 conda 環境測試。conda_deps.yml 中的訓練環境使用 Python 3.8.8。
  6. 本指南依照 Tiny-PULP-Dronet v3 README。v1 與 v2 資料夾有各自的 README 與不同的工具版本(v2 以 GAP SDK 3.8.1 測試),此處不採用。
  7. 原專案的 v3 儲存庫包含兩個網路:PULP-Dronet v3(19 fps、320 kB)與 Tiny-PULP-Dronet v3(139 fps、2.9 kB)。

2. 安裝 AI-deck 並連接除錯器

硬體步驟。AI-deck 與 Crazyflie 為外購品;燒錄 GAP8 需要除錯器。

2.1 將 AI-deck 裝到 Crazyflie 上

使用隨附的長排針,將 AI-deck 裝在 Crazyflie 2.1 上方。

  1. 原專案的飛行步驟寫道:「將 AI-deck 裝在 Crazyflie 的頂部。」
  2. Bitcraze 表示,AI-deck 可以用隨附的長排針裝在頂部或底部,而需要接 JTAG 線時,頂部位置最合適。

2.2 保護 ESP32 天線

如果擴充板裝在上方,請在脆弱的 ESP32 天線上點一小塊熱熔膠,或將擴充板裝在下方。

  1. ESP32 天線有點脆弱,墜機時可能損壞。
  2. 為了在墜機時更耐用,Bitcraze 建議將 AI-deck 裝在底部,或如其圖片所示點一塊熱熔膠。

2.3 將 JTAG 除錯器連接到 GAP8

將除錯器的轉接線接到 AI-deck 左側的 10-pin GAP8 接頭上。

  1. 原專案的燒錄步驟寫道:「為 AI-deck 上電並連接 JTAG 線。」v3 README 沒有指明除錯器。其指令使用 OpenOCD 線材設定檔 olimex-arm-usb-ocd-h.cfg,其 v1 README 則指名 Olimex ARM-USB-OCD-H。
  2. Bitcraze 測試並推薦 Olimex ARM-USB-TINY-H 搭配 ARM-JTAG-20-10 轉接器。其套組包含 ARM-USB-TINY-H 燒錄器、ARM-JTAG-20-10 轉接線(20-pin 燒錄器輸出轉 10-pin AI-deck 接頭)與一條 USB 線。除錯器需要 USB type B 線。STLink v2 無法使用,因為它只能為 Cortex 核心除錯。
  3. AI-deck 有兩個裝在板邊的 Cortex-M 10-pin(2x5,1.27 mm 間距)JTAG 接頭。從上方看電路板、攝影機朝前時,GAP8 接頭在左側,ESP32 接頭在右側。Pin 1 在左側,於電路板底面以 1 標示。
  4. 這兩款 Olimex 型號是不同的產品。SDK 為兩者各附一個線材設定檔:olimex-arm-usb-ocd-h.cfg 與 olimex-arm-usb-tiny-h.cfg,其 USB product id 不同。無論使用哪一款除錯器,都要將 OpenOCD 線材設定(GAPY_OPENOCD_CABLE,見燒錄步驟)指向該型號的檔案。Bitcraze 自己針對 ARM-USB-TINY-H 的指令使用 interface/ftdi/olimex-arm-usb-tiny-h.cfg。
  5. 在 Linux 上,依 SDK 步驟將你的使用者加入 dialout 群組(sudo usermod -a -G dialout <username>),然後登出再登入。

3. 設置主機電腦

以下全部在 Linux 電腦上進行。原專案測試過的系統是 Ubuntu 20.04.6 LTS。

3.1 連同子模組複製儲存庫

以遞迴方式複製 pulp-dronet,讓 NEMO、DORY 與檢視器一併下載。

  1. 執行:git clone --recursive [email protected]:pulp-platform/pulp-dronet.git(README 將該旗標印成 --recurive;儲存庫中的子模組位址是 ssh 位址,因此你的 GitHub ssh 金鑰必須能正常使用)。
  2. NEMO 是位於 tiny-pulp-dronet-v3/nemo-dory/nemo/ 的子模組,DORY 是位於 tiny-pulp-dronet-v3/nemo-dory/ 的子模組。若遞迴複製失敗,原專案建議從 pulp-platform 的 nemo 儲存庫下載 NEMO,並從 LorenzoLamberti94 的 dory_dronet 儲存庫下載 DORY。

3.2 建立 Python 環境

安裝用於訓練、測試與量化的 conda 環境。

  1. 在 tiny-pulp-dronet-v3 中執行:conda env create -f conda_deps.yml。環境名稱為 pulp-dronet-v3。
  2. 該檔案固定了 python 3.8.8、torch 1.5.0 與 torchvision 0.6.0。NEMO 不是從它安裝的,而是來自子模組。

3.3 安裝 GAP SDK 套件與 conda 環境

建立名為 gap_sdk 的 conda 環境,並安裝 SDK 所需的套件。

  1. 執行:conda create --name gap_sdk python==3.6.10 numpy cython,然後執行 conda activate gap_sdk。
  2. 安裝套件: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
  3. 需要 OpenCV 3.2。原專案表示它已不再受官方支援,並提供一個第三方安裝腳本:wget -O - https://gist.githubusercontent.com/syneart/3e6bb68de8b6390d2eb18bff67767dcb/raw/OpenCV3.2withContrib.sh | bash。這會執行他人 gist 中的腳本,因此請先閱讀它。用以下指令檢查:dpkg -l | grep libopencv

3.4 建置工具鏈與 OpenOCD

將 GAP RISC-V 工具鏈與 GAP8 OpenOCD 安裝到家目錄下的 gap 資料夾中。

  1. 原專案希望的目錄配置為:/home/YOUR_USER/gap/ 中包含 gap_gnu_toolchain、gap8_openocd 與 gap-sdk。
  2. 工具鏈:git clone https://github.com/GreenWaves-Technologies/gap_gnu_toolchain、cd gap_gnu_toolchain、git checkout 6fc27059038575e3bfef2b36ad7963a3ea77863e、./install.sh。若你選擇了自訂安裝路徑,請在 .bashrc 中加入 export GAP_RISCV_GCC_TOOLCHAIN="custom/path/that/you/chose"。commit 6fc27059038575e3bfef2b36ad7963a3ea77863e 存在於 gap8_openocd 儲存庫中,但在 2026 年 11 月 2 日於 gap_gnu_toolchain 儲存庫中找不到,而原專案沒有指明其他工具鏈版本。
  3. 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。
  4. 複製 udev 規則並重新載入:sudo cp /usr/share/gap8-openocd/openocd/contrib/60-openocd.rules /etc/udev/rules.d 與 sudo udevadm control --reload-rules && sudo udevadm trigger。
  5. 用 sudo usermod -a -G dialout <username> 將你的使用者加入 dialout 群組,然後登出再重新登入。

3.5 建置 GAP SDK 3.9.1

簽出 GreenWaves gap_sdk 的 release-v3.9.1 標籤並建置。

  1. 執行:git clone https://github.com/GreenWaves-Technologies/gap_sdk.git、cd gap_sdk、git checkout release-v3.9.1、git submodule update --init --recursive。
  2. 以 source configs/ai_deck.sh 載入 AI-deck 的設定。README 有一處把它寫成 configs/ai-ai_deck.sh;該 tag 中的檔案是 configs/ai_deck.sh,而 README 後面的指令也使用 ai_deck.sh。
  3. 接著執行:conda activate gap_sdk、pip install -r requirements.txt、pip install -r tools/nntool/requirements.txt、make sdk。
  4. 原專案的重要提示:務必在全新開啟的終端機中載入設定。

3.6 確認 SDK 能正常運作

先在模擬器中、再在電路板上執行 helloworld 範例。

  1. 模擬器:cd gap_sdk/examples/pmsis/helloworld,然後執行 make clean all run platform=gvsoc。
  2. 在板子上:export GAPY_OPENOCD_CABLE=interface/ftdi/olimex-arm-usb-ocd-h.cfg(這是原專案為 ARM-USB-OCD-H 給的值;ARM-USB-TINY-H 請用 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/,然後執行 make clean all run platform=board。
  3. 原專案指出,每種板子預設設定的線材不同;若使用其他線材,請將 GAPY_OPENOCD_CABLE 定義為 gap_sdk/tools/gap8-openocd/tcl/interface/ftdi/ 底下對應檔案的路徑。

3.7 取得 Crazyflie 原始碼與工具

依原專案指定的標籤,取得 crazyflie-firmware 標籤 2022.01、用戶端程式與 Python 函式庫。

  1. 將 tag 2022.01 的 crazyflie-firmware 下載到 ./drone-applications/external/crazyflie-firmware/。該資料夾只有一個 .gitkeep 檔案,因此複製下來的儲存庫裡沒有韌體。
  2. 安裝 tag 2022.01 的 Crazyflie Client(在該儲存庫中稱為 2022.1),以及 tag 0.1.17.1 的 crazyflie-lib-python。
  3. 原專案沒有列出 Crazyflie 韌體的建置工具。

4. 量化網路並產生程式碼(選做)

儲存庫中已在 tiny-pulp-dronet-v3/drone-applications/gap8-dronet-app/ 放有兩個網路已產生的 GAP8 程式碼,因此只有在你修改網路時才需要本章節。原專案的 README 將該資料夾稱為 gap8_app。

4.1 使用預訓練權重

兩個預訓練模型是儲存庫 model 資料夾中的檔案。

  1. 權重檔為 tiny-pulp-dronet-v3/model/pulp-dronet-v3-resblock-1.0.pth 與 tiny-pulp-dronet-v3/model/tiny-pulp-dronet-v3-dw-pw-0.125.pth。
  2. 儲存庫有名為 pulp-dronet-v3 與 pulp-dronet-v2 的 release,但兩者都沒有附任何檔案。

4.2 以 NEMO 量化模型

執行 quantize.py,產生 ONNX 模型與 golden activations。

  1. 以 conda activate pulp-dronet-v3 啟用環境。
  2. 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/
  3. 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/
  4. 這些指令會將 ONNX 模型與權重匯出到 ./nemo_output/。腳本位於 tiny-pulp-dronet-v3/nemo-dory/,而原專案指令中的相對路徑以 ../model/ 開頭,因此請在該資料夾中執行。
  5. 原專案表示在 nemo-dory/nemo-output/ 提供了預先量化的模型;該資料夾不在儲存庫中。

4.3 以 DORY 產生 C 程式碼

對量化後的模型執行 network_generate.py。

  1. 以 conda activate dory 啟用環境。原專案沒有說明如何建立此環境。DORY 自己的 README 列出 Python 3.6.8,搭配 Mako 1.0.12、numpy 1.18.4、onnx 1.5.0、pandas 1.0.3 與 ortools 7.5.7466。
  2. 在 nemo-dory/dory_dronet/dory_example/(README 中的路徑;儲存庫的 .gitmodules 將 DORY 子模組放在 nemo-dory/dory)中,針對 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
  3. 針對 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
  4. 程式碼會產生在 dory_dronet/dory_examples/application/ 底下。

5. 燒錄無人機並飛行

原專案的三個步驟:燒錄 Crazyflie 應用程式、燒錄 GAP8,然後從 Crazyflie 用戶端飛行。可選擇先透過除錯器執行一次,檢查 GAP8 上的網路。

5.1 透過除錯器在 GAP8 上測試網路

從主機執行應用程式,不需燒錄。

  1. 開啟新的終端機,載入 SDK 並匯出線材檔案:source gap_sdk/configs/ai_deck.sh 以及 export GAPY_OPENOCD_CABLE=$HOME/gap/gap_sdk/tools/gap8-openocd/tcl/interface/ftdi/olimex-arm-usb-ocd-h.cfg(ARM-USB-TINY-H 請使用同一資料夾中的 olimex-arm-usb-tiny-h.cfg)。
  2. PULP-Dronet v3:cd pulp-dronet/tiny-pulp-dronet-v3/drone-applications/gap8_app/pulp-dronet-v3/,然後執行 make clean all run CORE=8 platform=board。
  3. Tiny-PULP-Dronet v3:cd pulp-dronet/tiny-pulp-dronet-v3/drone-applications/gap8_app/tiny-pulp-dronet-v3/,然後執行 make clean all run CORE=8 platform=board。在儲存庫中,該資料夾是 gap8-dronet-app,而不是 gap8_app。
  4. 原專案表示,139 fps 的數字屬於小型網路,19 fps 則屬於 PULP-Dronet v3。

5.2 建置並燒錄 Crazyflie 應用程式

以 crazyflie-firmware 2022.01 編譯 crazyflie-dronet-app,並在 bootloader 模式下載入。

  1. crazyflie-dronet-app 是飛行控制器。它透過 UART 從 AI-deck 接收 CNN 的輸出。
  2. 編譯程式碼:cd ./drone-applications/crazyflie-dronet-app/,然後執行 make clean platform=cf2。此應用程式的 Makefile 從 ../external/crazyflie-firmware 取得韌體。
  3. 在無人機電源關閉時,按住電源按鈕 3 秒。這應該會讓無人機進入 bootloader 模式。
  4. 接著執行 make cload,並等待燒錄完成。

5.3 燒錄 GAP8 應用程式

建置 GAP8 應用程式,並透過除錯器寫入 AI-deck 的快閃記憶體。

  1. 開啟 AI-deck 的電源並接上 JTAG 線。
  2. 載入 SDK 並設定線材檔案:source gap_sdk/configs/ai_deck.sh 以及 export GAPY_OPENOCD_CABLE=$HOME/gap/gap_sdk/tools/gap8-openocd/tcl/interface/ftdi/olimex-arm-usb-ocd-h.cfg(ARM-USB-TINY-H 請用 olimex-arm-usb-tiny-h.cfg)。
  3. 進入應用程式資料夾,先執行 make clean all,再執行 make flash。原專案將資料夾寫成 ./drone-applications/gap-dronet-app/,但它並不存在。Makefile 位於 drone-applications/gap8-dronet-app/pulp-dronet-v3/ 與 drone-applications/gap8-dronet-app/tiny-pulp-dronet-v3/。
  4. 除非設定了 CORE,這些資料夾中的 Makefile 都只為單一核心建置(上面的測試指令設定了 CORE=8)。原專案的燒錄指令沒有設定它。
  5. 現在將無人機重新上電(先關機再開機)。原專案表示,此時 PULP-Dronet 就會在 AI-deck 上執行。

5.4 選配:串流攝影機影像

開啟 JPEG 串流器並使用檢視器。

  1. 在 drone-applications/gap8-dronet-app/pulp-dronet-v3/DORY_network/src/main.c 中啟用 #define JPEG_STREAMER 1(該行在檔案中被註解掉)。使用 drone-applications/gap8-dronet-app/viewer-pulp-dronet/ 中的檢視器。
  2. 原專案寫道:「我們的應用程式是使用特定的 NINA 韌體開發的。如果你買的是新的 AI deck,出廠韌體很可能不相容。請依照 NINA-flashing-crazyflie 儲存庫中的說明燒錄正確的韌體。」這句話位於串流器的說明之下,沒有進一步解釋。
  3. 該儲存庫的 README: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/,然後搭配 Olimex ARM-USB-OCD-H 線材檔案執行 docker run(完整指令請見 README,其中包含用 make menuconfig 選擇存取點或路由器模式)。

5.5 開始飛行

開啟 Crazyflie 用戶端,將 fly 參數設為 1,無人機就會起飛。

  1. AI-deck 必須安裝在 Crazyflie 的上方。
  2. 以 cfclient 啟動 Crazyflie Client。
  3. 前往 cfclient 的 Parameters 分頁,將 START_STOP 群組中的 fly 參數設為 1。無人機會起飛並開始自主導航。
  4. 如果啟用了除錯用的 printf,可以在 cfclient 的 Console 分頁中看到輸出。
  5. 原專案沒有提供飛行的安全說明。

本網站需要 JavaScript 才能正常運作。請啟用 JavaScript 以瀏覽我們的開源機器人專案。