Arduino IDE 2 上傳檔案到 ESP32/ESP8266 的外掛

Arduino IDE 2.x 版有完整的語法標色、程式碼補全等眾多功能, 比原本陽春的 Arduino 1.x 版要好用許多, 不過許多人可能因為缺少了可以上傳檔案到 ESP32/ESP8266 等控制板的功能, 在使用 Arduino IDE 2.x 時卡關。好消息來了, 已經有善心人士撰寫了外掛, 幫我們解決這個問題。

檔案上傳外掛下載網址

首先是有善心人士 Earle F. Philhower, III 撰寫了arduino-littlefs-upload 外掛, 你可以直接在這裡下載外掛檔案。但是這個外掛是針對 LittleFS 檔案系統, 如果你要採用的是 SPIFFS 檔案系統, 就派不上用場。於是就有另一個善心人士 espx 從剛剛介紹的外掛衍生出 arduino-spiffs-upload 外掛, 你可以在這裡下載外掛檔案。

安裝外掛

Arduino IDE 2 是從 The Eclipse Theia IDE 衍生而來, 其實也就是 Visual Studio Code 的源頭, 它們都共用同一套外掛機制, 只要在你的使用者目錄下找到 .arduinoIDE 資料夾, 在其中建立 plugins 資料夾, 將剛剛下載的 .vsix 外掛檔案複製到 plugins 資料夾中：

C:\USERS\{使用者名稱}\.ARDUINOIDE
└──plugins
   ├─arduino-littlefs-upload-1.1.5.vsix
   └─arduino-spiffs-upload-1.1.5.vsix

再重新開啟 Arduino IDE 即可。

上傳檔案

要上傳檔案, 只要在你的草稿碼資料夾下建立一個 data 資料夾, 像是這樣：

C:\USERS\MEEBO\CODE\ARDUINO\TEST_LITTLEFS
├─test_littleFS.ino
└─data
  └─test.txt

C:\USERS\MEEBO\CODE\ARDUINO\TEST_SPIFFS
├─test_SPIFFS.ino
└─data
  └─test.txt

接著, 就可以按 Ctrl+Shift+p 開啟命令面板, 輸入 "upload", 就會看到對應的命令：

選擇你想用的檔案系統對應的命令, 就可以將 data 資料夾內的所有內容上傳到 ESP32/ESP8266 上了。

要注意的是, 如果有開啟中的序列埠, 必須先關閉, 才能上傳。

你會看到這樣的訊息：

SPIFFS Filesystem Uploader

Using partition: default
Building SPIFFS filesystem
C:\Users\meebo\AppData\Local\Arduino15\packages\esp32\tools\mkspiffs\0.2.3/mkspiffs.exe -c C:\Users\meebo\code\Arduino\test_SPIFFS/data -p 256 -b 4096 -s 1441792 C:\Users\meebo\AppData\Local\Temp\tmp-15392-y5BDfcxef6G7-.spiffs.bin
/test.txt


Uploading SPIFFS filesystem
C:\Users\meebo\AppData\Local\Arduino15\packages\esp32\tools\esptool_py\4.5.1/esptool.exe --chip esp32 --port COM9 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 2686976 C:\Users\meebo\AppData\Local\Temp\tmp-15392-y5BDfcxef6G7-.spiffs.bin
esptool.py v4.5.1
Serial port COM9
Connecting....
Chip is ESP32-D0WDQ6 (revision v1.0)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: ac:67:b2:38:7f:34
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changed.
Configuring flash size...
Auto-detected Flash size: 4MB
Flash will be erased from 0x00290000 to 0x003effff...
Compressed 1441792 bytes to 2734...
Writing at 0x00290000... (100 %)
Wrote 1441792 bytes (2734 compressed) at 0x00290000 in 6.5 seconds (effective 1776.6 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting via RTS pin...

Completed upload.

也會看到 Arduino IDE 的通知：

就表示上傳成功了。

ESP8266 使用時的注意事項

目前在 ESP8266 上使用 1.1.5 版的外掛上傳 SPIFFS 時, 我遇到外掛找錯工具程式的問題, 這個外掛分成兩個步驟：

1. 將專案中的 data 資料夾包裝成 SPIFFS 格式的 bin 檔。
2. 將包裝好的 bin 檔上傳到開發板上。

其中第一個步驟依靠的是 mkspiffs 工具程式, 不過在我同時安裝有 ESP32/ESP8266 套件的 Arduino IDE 2.x 上, 會遇到要上傳到 ESP8266 時, 外掛使用了 ESP32 套件中的 mkspiffs 工具, 而不是 ESP8266 套件中的同名工具, 目前 ESP8266 套件 3.1.2 內的 mkspiffs 工具版本為：

# C:\Users\meebo\AppData\Local\Arduino15\packages\esp8266\tools\mkspiffs\3.1.0-gcc10.3-e5f9fec\mkspiffs.exe --version

C:\Users\meebo\AppData\Local\Arduino15\packages\esp8266\tools\mkspiffs\3.1.0-gcc10.3-e5f9fec\mkspiffs.exe  version: 0.2.0

而 ESP32 套件 3.0.7 上的版本為：

# C:\Users\meebo\AppData\Local\Arduino15\packages\esp32\tools\mkspiffs\0.2.3/mkspiffs.exe --version
mkspiffs ver. 0.2.3
Build configuration name: arduino-esp32
SPIFFS ver. 0.3.7-5-gf5e26c4
Extra build flags: -DSPIFFS_OBJ_META_LEN=4
SPIFFS configuration:
  SPIFFS_OBJ_NAME_LEN: 32
  SPIFFS_OBJ_META_LEN: 4
  SPIFFS_USE_MAGIC: 1
  SPIFFS_USE_MAGIC_LENGTH: 1
  SPIFFS_ALIGNED_OBJECT_INDEX_TABLES: 0

你可以看到兩者版本不同, 而 ESP32 的版本有明確標示是以 esp32 為目標建置的版本, 它包裝的 SPIFFS 檔在我的測試中上傳到 ESP8266 是無法使用的。

解決方案

最簡單的解決的方法就是移除 ESP32 套件, 重新開啟 Arduino IDE 2.x, 讓外掛重新找到 ESP8266 套件下的 mkspiffs 工具。不過如果你就是得用 ESP32 套件, 這當然就不切實際。

另外一種解決方法就是自己手動包裝並上傳 SPIFFS 檔, 你可以先依照前面介紹的方法完成上傳 SPIFFS 檔的程序, 然後從 Arduino IDE 中下方窗格找到 SPIFFS Upload 分頁, 會看到完整的執行步驟, 例如：

SPIFFS Filesystem Uploader

Building SPIFFS filesystem
C:\Users\meebo\AppData\Local\Arduino15\packages\esp32\tools\mkspiffs\0.2.3/mkspiffs.exe -c C:\Users\meebo\Desktop\test_fs/data -p 256 -b 8192 -s 2072576 C:\Users\meebo\AppData\Local\Temp\tmp-25864-sf0vorjf7fJV-.spiffs.bin
/www/favicon.ico
/www/img/logo.png
/www/index.html


Uploading SPIFFS filesystem
C:\Users\meebo\AppData\Local\Arduino15\packages\esp8266\tools\python3\3.7.2-post1/python3.exe C:\Users\meebo\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\3.1.2/tools/upload.py --chip esp8266 --port COM4 --baud 921600 write_flash 2097152 C:\Users\meebo\AppData\Local\Temp\tmp-25864-sf0vorjf7fJV-.spiffs.bin
esptool.py v3.0
Serial port COM4
Connecting....

其中 Building SPIFFS filesystem 底下就是包裝 SPIFFS 檔的指令：

C:\Users\meebo\AppData\Local\Arduino15\packages\esp32\tools\mkspiffs\0.2.3/mkspiffs.exe -c C:\Users\meebo\Desktop\test_fs/data -p 256 -b 8192 -s 2072576 C:\Users\meebo\AppData\Local\Temp\tmp-25864-sf0vorjf7fJV-.spiffs.bin

你只要把開頭的指令換成 esp8266 套件下的同名工具就可以了, 你可以參考前面顯示個別工具版本時的指令找到自己環境中的工具位置。包裝好檔案中, 就可以用執行步驟中 Uploading SPIFFS filesystem 下的指令上傳檔案。

錯誤原因

根據 mkspiffs 工具自己的建置腳本來看, 根據不同的平台, 編譯時會需要不同的選項, 也就是雖然工具名稱都一樣, 但用錯不同方式建置的工具, 就無法使用。

在 arduino-spiffs-upload 的這一行：

tool = findTool(arduinoContext, "runtime.tools.mkspiffs");

會找到的是 ESP32 套件安裝的 mkspiffs.exe 檔, 如果把這一行改成：

tool = findTool(arduinoContext, "runtime.tools.mkspiffs-3");

就可以正確找到 ESP8266 套件安裝的 mkspiffs.exe 檔 (Linux/Mac 平台尚未測試過是不是會有同樣的問題)。