# 韌體開發中的 Deploy 流程類型

本文檔分類說明韌體**開發階段**常見的部署（Deploy）流程類型，以及各自的特點、適用平台和工具鏈。

## ⚠️ 重要說明

**FWAuto 定位**：

- ✅ **開發階段工具**：用於開發、測試、除錯階段的快速部署
- ❌ **不支援 Production 環境**：不處理生產環境的 firmware 更新、OTA、版本管理等

**支援的 Deploy 類型**：

1. **Direct Flashing**（直接燒錄） - MCU 開發主要方式
2. **Network Deployment**（網路部署） - Linux 開發板快速部署

**不支援的類型**（Production 環境用）：

- Bootloader Update（IAP/DFU）
- OTA Update（IoT 遠端更新）
- Mass Programming（生產線燒錄）

---

## 概覽：開發階段的 Deploy 方式

| 類型                   | 適用場景         | 連線方式             | FWAuto 支援 |
| ---------------------- | ---------------- | -------------------- | ----------- |
| **Direct Flashing**    | MCU 開發/除錯    | 實體連線（JTAG/SWD） | 🚧 規劃中   |
| **Network Deployment** | Linux 開發板測試 | 網路（SSH/SCP）      | ✅ 已支援   |

---

## 1. Direct Flashing（直接燒錄型）⭐

> **FWAuto 支援目標**：規劃支援 STM32 等 MCU 平台

### 適用場景

- **MCU 開發**：STM32、AVR、ESP32、Nordic nRF52、PIC、MSP430 等
- **開發/除錯階段**：寫程式 → 編譯 → 燒錄 → 測試的快速迭代循環

### 常用工具

| 燒錄器類型 | 適用平台        | 工具軟體                                      |
| ---------- | --------------- | --------------------------------------------- |
| ST-LINK    | STM32           | ST-LINK Utility, STM32CubeProgrammer, OpenOCD |
| J-Link     | ARM Cortex 系列 | J-Link Commander, Ozone                       |
| CMSIS-DAP  | ARM Cortex 系列 | OpenOCD, pyOCD                                |
| USB Serial | ESP32, Arduino  | esptool.py, avrdude                           |
| nRF-LINK   | Nordic nRF 系列 | nrfjprog, nRF Connect                         |

### 部署流程

```mermaid
flowchart LR
    A["檢查燒錄器連線"] --> B["讀取 binary/hex"]
    B --> C["擦除 Flash"]
    C --> D["寫入 Flash"]
    D --> E["驗證（可選）"]
    E --> F["重置 MCU"]
```

### 特點

**優點**：

- ✅ 實體連線穩定可靠
- ✅ 本機執行，不需要網路
- ✅ 同步操作，立即知道結果
- ✅ 檢測簡單（燒錄器是否連接）
- ✅ 支援除錯功能（斷點、單步執行）

**缺點**：

- ❌ 需要實體存取裝置
- ❌ 無法遠端更新
- ❌ 需要專用硬體（燒錄器）

### 環境檢測需求

- 燒錄器連接狀態（USB 裝置列舉）
- 目標 MCU 識別（晶片 ID、系列）
- Binary 檔案存在性和格式驗證

---

## 2. Network Deployment（網路部署型）⭐

> **FWAuto 支援目標**：已支援 AM62X，未來可擴展至其他 Linux 開發板

### 適用場景

- **Linux 嵌入式系統開發**：
  - TI AM62X (Sitara) ✅ 已支援
  - Raspberry Pi (各系列)
  - RISC-V SBC (BeagleV, VisionFive)
  - NVIDIA Jetson (Nano, Xavier, Orin)
  - NXP i.MX (i.MX6, i.MX8)
  - Rockchip (RK3399, RK3588)
- **開發/測試階段**：快速部署到開發板，收集日誌，驗證功能

### 📌 SD Card 開機的開發板

**重要說明**：許多 Linux 開發板使用 SD Card 開機（如 Raspberry Pi、BeagleBone 等）

**流程說明**：

1. **初始 OS 燒錄**（手動，FWAuto 不支援）：
   - 使用工具（Balena Etcher、Raspberry Pi Imager、`dd` 命令）
   - 燒錄 Linux 映像到 SD Card
   - 插入開發板並開機

2. **後續應用程式部署**（FWAuto 支援）：
   - ✅ 開發板開機後，使用 **Network Deployment (SSH)** 方式
   - ✅ 部署應用程式 binary
   - ✅ 收集遠端日誌
   - ✅ 快速迭代開發

**為何 SD Card 燒錄無法自動化**：

- ❌ 需要實體操作（拔插 SD Card）
- ❌ 不同平台工具差異大（Linux `dd`、Windows Win32DiskImager、macOS diskutil）
- ❌ 風險高（可能覆蓋錯誤的磁碟）
- ✅ 但 OS 燒錄通常只需做一次，後續都用 SSH 部署即可

### 常用工具

| 工具    | 用途               | 特點                 |
| ------- | ------------------ | -------------------- |
| SSH/SCP | 檔案傳輸和遠端執行 | 標準、安全、廣泛支援 |
| SFTP    | 檔案傳輸           | 類似 SCP，更多控制   |
| rsync   | 增量同步           | 適合大檔案或多檔案   |
| TFTP    | 簡單檔案傳輸       | Bootloader 常用      |

### 部署流程

```mermaid
flowchart LR
    A["檢查網路連線"] --> B["檢查 SSH 可用性"]
    B --> C["傳輸 binary"]
    C --> D["停止舊程式（可選）"]
    D --> E["設定權限（chmod +x）"]
    E --> F["執行新程式"]
    F --> G["收集遠端日誌（可選）"]
```

### 特點

**優點**：

- ✅ 遠端部署能力
- ✅ 可自動化整合進 CI/CD
- ✅ 支援多裝置同時部署
- ✅ 可收集遠端日誌

**缺點**：

- ⚠️ 需要穩定的網路連線
- ⚠️ 需要複雜的環境檢測（網路、SSH、防火牆）
- ⚠️ 可能有前置作業（killall、權限設定）
- ⚠️ 非同步操作（背景執行時無法立即確認）

### 環境檢測需求（複雜）

**網路層**：

- Ping 測試（ICMP）
- 網路可達性
- 延遲和封包遺失率

**SSH 層**：

- SSH port 開放性（port 22 或自訂）
- SSH 金鑰/密碼認證
- 防火牆規則
- SSH 服務狀態

**系統層**：

- 目標路徑寫入權限
- 磁碟空間檢查
- 舊程式是否在運行

**關鍵洞察**：

- SSH-based 的檢測邏輯可以**跨平台共用**（AM62X、Raspberry Pi、RISC-V）
- 這些檢測應該在 **FWAuto 層處理**，因為大部分 Linux-based 平台都需要

---

## Deploy 類型對比表（開發階段）

| 層面            | Direct Flashing           | Network Deployment             |
| --------------- | ------------------------- | ------------------------------ |
| **連線方式**    | 實體（JTAG/SWD/USB）      | 網路（SSH/SCP）                |
| **檢測複雜度**  | 低                        | 中高                           |
| **遠端能力**    | ❌ 需要實體連接           | ✅ 可遠端部署                  |
| **除錯能力**    | ✅ 完整（斷點、單步）     | ⚠️ 有限（日誌分析）            |
| **適用平台**    | MCU (STM32, nRF52, ESP32) | Linux SBC (AM62X, RPi, RISC-V) |
| **基礎設施**    | 燒錄器（ST-LINK, J-Link） | SSH 伺服器（開發板）           |
| **部署速度**    | 快（本機直連）            | 中（取決於網路和檔案大小）     |
| **日誌收集**    | ❌ 需要額外 UART 連線     | ✅ 內建遠端日誌支援            |
| **FWAuto 支援** | 🚧 規劃中                 | ✅ 已支援 (AM62X)              |

---

## FWAuto 支援規劃（開發階段）

### 目前支援（v0.5.0）

| 平台類型  | 具體平台 | Deploy 類型        | 狀態            | 版本   |
| --------- | -------- | ------------------ | --------------- | ------ |
| Linux SBC | TI AM62X | Network Deployment | ✅ 完整支援     | v0.5.0 |
| MCU       | STM32    | Direct Flashing    | 🚧 v1.0+ 規劃中 | -      |

### Deploy 類型分流表

此表說明不同平台如何對應到 FWAuto 的 deploy 流程。

| SDK Type  | Deploy Type        | 工具/燒錄器 | deploy_operations 函數      | 狀態      | 版本   |
| --------- | ------------------ | ----------- | --------------------------- | --------- | ------ |
| **am62x** | Network Deployment | SSH/SCP     | `_deploy_network()`         | ✅ 已支援 | v0.5.0 |
| **stm32** | Direct Flashing    | ST-LINK     | `_deploy_direct_flashing()` | 🚧 規劃中 | v1.0+  |

**關鍵設計原則**：

- ✅ **相同 Deploy Type 共用同一個函數**：
  - 所有 Network Deployment → `_deploy_network()`
  - 所有 Direct Flashing → `_deploy_direct_flashing()`
- ✅ **工具差異由 deploy.py 處理**：
  - deploy_operations **不知道**使用 ST-LINK、J-Link 還是 esptool
  - 各平台的 deploy.py 負責調用對應的工具
- ✅ **易於擴展**：
  - 新增 Raspberry Pi 5 → 無需修改 deploy_operations
  - 新增 AVR MCU → 重用 `_deploy_direct_flashing()`

### 短期擴展目標（開發階段）

**Network Deployment 擴展**：

- Raspberry Pi (3/4/5)
- RISC-V SBC (BeagleV, VisionFive)
- 其他 SSH-compatible Linux 開發板

**Direct Flashing 支援**：

- STM32 系列（ST-LINK）
- ESP32 系列（esptool）
- Nordic nRF52 系列（J-Link/nrfjprog）

### 架構設計原則

FWAuto 的 `deploy_operations` 設計：

1. **在內部區隔不同 deploy 類型**
   - `_deploy_network()` - Linux-based 平台
   - `_deploy_direct_flashing()` - MCU-based 平台

2. **環境檢測邏輯共用**
   - SSH 檢測可跨 Linux 平台共用（AM62X、Raspberry Pi、RISC-V）
   - Direct Flashing 檢測相對簡單（可由 deploy.py 處理）

3. **保持 deploy_node 統一介面**
   - deploy_node 不需要知道部署類型細節
   - 所有類型透過統一的 `deploy_firmware()` 介面調用

### 不支援的類型

#### Production 環境相關

以下類型**不在 FWAuto 支援範圍**，因為這些是 production 環境的更新機制：

- ❌ Bootloader Update (IAP/DFU)
- ❌ OTA Update (IoT 遠端更新)
- ❌ Mass Programming (生產線燒錄)
- ❌ Secure Boot / Signed Firmware
- ❌ A/B Partition / Rollback 機制

#### 開發環境相關

- ❌ **SD Card OS 燒錄**：
  - 理由：需要實體操作（拔插 SD Card），無法自動化
  - 風險：可能覆蓋錯誤的磁碟
  - 替代方案：手動燒錄 OS 後，使用 Network Deployment 部署應用程式
  - 適用平台：Raspberry Pi、BeagleBone、部分 RISC-V SBC

---

## 附錄：其他 Deploy 方式（參考）

以下為其他常見的 firmware/OS 部署方式，**FWAuto 不支援**，僅供知識參考。

### A. SD Card / USB Storage Update

**適用場景**：Linux 開發板的 OS 初始化、消費性電子產品現場更新
**FWAuto 立場**：**不支援 OS 燒錄，但支援燒錄後的應用程式部署**

#### 手動 SD Card 燒錄流程（開發階段）

```mermaid
flowchart LR
    A["下載 OS 映像"] --> B["使用燒錄工具"]
    B --> C["選擇 SD Card"]
    C --> D["燒錄映像"]
    D --> E["插入開發板"]
    E --> F["開機"]
    F --> G["✅ 後續使用 SSH 部署"]
```

**常用工具**：

| 工具                | 平台                | 特點                                   |
| ------------------- | ------------------- | -------------------------------------- |
| Balena Etcher       | Windows/macOS/Linux | 圖形化介面，安全（自動選擇可移除裝置） |
| Raspberry Pi Imager | Windows/macOS/Linux | Raspberry Pi 官方工具                  |
| `dd` 命令           | Linux/macOS         | 命令列工具，強大但危險                 |
| Win32DiskImager     | Windows             | 簡單易用                               |
| Rufus               | Windows             | 支援多種映像格式                       |

**為何無法自動化**：

- ❌ 需要實體拔插 SD Card
- ❌ 需要識別正確的儲存裝置（風險高）
- ❌ 不同平台工具和 API 差異大
- ❌ 開發機通常沒有多餘的 SD Card 讀卡機

**但可以這樣做**：

1. **一次性手動燒錄** OS 映像到 SD Card
2. **開發板開機後**，使用 FWAuto 的 Network Deployment
3. **快速迭代**：編譯 → SSH 部署 → 測試 → 修改 → 重複

**適用開發板**：

- Raspberry Pi 系列
- BeagleBone Black/AI
- 部分 RISC-V SBC（VisionFive、BeagleV）
- Rock Pi
- Orange Pi

---

### B. Bootloader Uqpdate (IAP/DFU)

**適用場景**：產品部署後的現場更新
**特點**：

- 透過 Bootloader 實現自主更新
- 有驗證機制（CRC/簽章）
- 支援 A/B 分區和 rollback

**常見實作**：

- STM32 DFU (Device Firmware Update)
- ESP32 OTA
- Nordic nRF DFU

### B. OTA Update (Over-The-Air)

**適用場景**：IoT 裝置大規模遠端更新
**特點**：

- 透過雲端平台管理
- 支援版本管理和灰度發布
- 裝置自主決定更新時機

**常見架構**：

- HTTP/HTTPS (RESTful API)
- MQTT (AWS IoT, Azure IoT Hub)
- CoAP (輕量級協定)

### C. Mass Programming

**適用場景**：工廠生產線批量燒錄
**特點**：

- Gang Programmer（一次燒錄多片）
- 整合進自動化生產線
- 高效率大量生產

---

## 參考資料

### FWAuto 相關

- **Research**: `.ai/prpi/research/2025-11-12-deploy-operations-abstraction-analysis.md`
- **CLAUDE.md**: `CLAUDE.md` - Maketool Abstraction Layer 設計原則
