🔌 node-red-contrib-autoupload-arduino

一個 Node-RED 節點，用於透過 arduino-cli 自動將 Arduino 程式碼（Sketch）編譯並上傳到指定的開發板。

ℹ️ 兼容性聲明 (Compatibility Note): 本節點主要是在 Linux 環境下開發和測試。雖然 arduino-cli 和 Node.js 支援跨平台，但檔案路徑處理（例如 ~/ 和 /dev/ttyACM0 格式）和執行權限在 Windows 和 macOS 上可能需要額外調整。

🛠️ Linux 環境配置 (Prerequisites Setup for Linux)

本節點要求系統已安裝並配置 arduino-cli，且已安裝目標板型核心。請在您的 Linux 終端機中，依序執行以下命令來完成環境設置：

1. 安裝並配置 Arduino CLI

# 下載並安裝最新版本 Arduino CLI
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

# 設定永久環境變數，將 arduino-cli 加入 PATH
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 確認安裝成功 (應顯示版本號)
arduino-cli version

2. 初始化配置與安裝 AVR 核心

# 初始化 Arduino CLI 配置檔案
arduino-cli config init

# 更新板型索引
arduino-cli core update-index

# 安裝 Arduino AVR 板型核心 (適用於 Uno, Mega, Nano 等)
arduino-cli core install arduino:avr

# 建立預設 Sketch 目錄 (與節點的預設 file_path 相符)
mkdir -p ~/Arduino/BlinkSerial
cd ~/Arduino/BlinkSerial

3. Arduino 開發板

您的 Arduino 板必須通過 USB 連接到運行 Node-RED 的電腦。

⚙️ 節點配置 (Node Configuration)

雙擊 Auto Upload 節點以配置以下屬性：

| 欄位 | 說明 | 範例值 | | :--- | :--- | :--- | | Arduino 端口 | 連接到 Arduino 開發板的序列埠地址。 (Linux 範例: /dev/ttyACM0) | /dev/ttyACM0 或 COM3 | | Arduino 板型 | 開發板的 FQBN (Fully Qualified Board Name)。必須與 arduino-cli 格式一致。 | arduino:avr:uno 或 arduino:avr:mega | | 檔案內容 | 包含您的 Arduino 程式碼 (.ino 檔案內容) 的程式碼編輯器。 | 標準 Arduino Sketch 程式碼 | | (隱藏) 儲存路徑 | 節點將程式碼暫時寫入進行編譯的完整檔案路徑。 | ~/Arduino/BlinkSerial/BlinkSerial.ino |

🚀 工作流程 (How It Works)

本節點是一個輸入型節點，它會監聽輸入訊息（msg）。當收到任何輸入訊息時，它將執行以下連續步驟：

1. 儲存程式碼 (Save Code): 將配置中提供的檔案內容寫入到儲存路徑所指定的暫存 .ino 檔案中。
2. 檢查 CLI (Check CLI): 執行 arduino-cli version 驗證 CLI 是否存在。
3. 編譯 (Compile): 執行 arduino-cli compile --fqbn <BOARD> <FILE_PATH>。
4. 上傳 (Upload): 如果編譯成功，執行 arduino-cli upload -p <PORT> --fqbn <BOARD> <FILE_PATH>。

📥 輸入與輸出 (Input and Output)

輸入 (Input)

本節點只需要一個觸發訊息即可啟動流程。通常建議連接一個 Inject 節點，然後手動或定時觸發：

• 觸發訊息: 任何 msg (例如：來自 Inject 節點的空訊息)。

輸出 (Output)

本節點會輸出一條訊息，其中包含上傳流程的結果狀態：

| 屬性 | 狀態 | 說明 | | :--- | :--- | :--- | | msg.payload.status | "success" | 程式碼已成功編譯並上傳。 | | msg.payload.message | 成功訊息。 | Code compiled and uploaded successfully. | | msg.payload.log | 包含 arduino-cli upload 的標準輸出日誌。 | | msg.payload.status | "failure" | 流程失敗 (儲存、編譯或上傳階段出錯)。 | | msg.payload.message | 失敗訊息。 | 描述在哪個階段失敗。 | | msg.payload.error | 包含 Node.js 錯誤訊息。 | | msg.payload.stderr | 包含 arduino-cli 的標準錯誤輸出 (Stderr)。 |

🟢 節點狀態 (Node Status)

節點在運行時會在編輯器中顯示即時狀態：

| 顏色/形狀 | 狀態文字 | 說明 | | :--- | :--- | :--- | | 藍點 | Saving code to file... / Starting upload process... | 正在準備或儲存檔案。 | | 黃點 | Checking CLI... / Compiling sketch... | 正在執行外部命令。 | | 綠點 | Upload Success | 流程完成且成功。 | | 紅圈 | Upload Failed | 流程中途發生錯誤。 |

💡 範例使用 (Example Usage)

您可以使用 Inject 節點觸發 Auto Upload 節點，然後將其輸出連接到 Debug 節點，以便在 Node-RED 偵錯面板中查看編譯和上傳的結果。

📡 接收序列埠資料 (Receiving Serial Data)

本節點僅負責上傳程式碼。如果您希望在程式碼上傳成功後，在 Node-RED 流程中接收 Arduino 開發板傳來的序列埠訊號，您需要安裝並使用官方的序列埠節點：

1. 安裝 node-red-node-serialport： 您可以在 Node-RED 編輯器的 管理面板 (Palette Manager) 中搜尋並安裝，或者在 Node-RED 根目錄下使用以下命令安裝：

   npm install node-red-node-serialport

2. 配置 Serial In 節點：

   • 在您的 Node-RED 流程中拖曳 Serial In 節點。
   • 將其配置為使用您在 Auto Upload 節點中指定的相同 Arduino 端口 (例如 /dev/ttyACM0) 和序列埠速率 (Baud Rate)。
   • 接著，您就可以將 Serial In 節點連接到其他流程或 Debug 節點來觀察 Arduino 發送的數據了。