PWM 伺服馬達協定、命令與標定
本頁涵蓋 PWM 韌體的序列埠協定、命令、校準和參數精調。接線見 PWM 接線，燒錄見 PWM 快速上手，桌面/網頁控制見 PWM 桌面上位機 / PWM 網頁控制。
以下命令在儲存庫的
AmazingHand-PWM/目錄下執行。韌體原始碼：firmware/AmazingHand_Serial/。
1. 命令與手勢一覽
前 11 列為手勢命令，其餘為直驅、選邊、重複、停止和鏈路測試命令。
| 手勢/命令 | 命令 | 說明 |
|---|---|---|
| 石頭 | 0x01 | 猜拳：全指握拳 |
| 剪刀 | 0x02 | 猜拳：食指+中指伸出呈 V 字 |
| 布 | 0x03 | 猜拳：全指張開 |
| 比讚 | 0x04 | 拇指豎起，其餘握拳 |
| 嘲諷1 | 0x05 | 搖食指（「不不不」） |
| 嘲諷2 | 0x06 | 無名指伸展晃動（替代小指） |
| 張開 | 0x07 | 全指張開 |
| 握拳 | 0x08 | 全指閉合 |
| OK | 0x09 | OK 手勢 |
| 捏合 | 0x0A | 捏合手勢 |
| 指向 | 0x0C | 食指伸出做「指」動作 |
| 直驅 | 0xF0 | 直接控制 8 路伺服馬達角度 |
| 設左右手 | 0xF1 | 切換左手/右手模式 |
| 重複 | 0xFE | 重複執行上一次手勢 |
| 停止 | 0xFF | 立即終止目前手勢 |
| NOP | 0x00 | 鏈路測試 |
註：命令 0x0B 已停用（原「拇指朝下」與「比讚」動作重複，已移除）。
2. 韌體校準（可選，首次使用建議）
伺服馬達中心位和脈寬需按實際機構校準，可直接在韌體原始碼中修改：
- 編輯
components/hand_servo/hand_servo.c頂部的middle_pos[8]和min_pw/mid_pw/max_pw[8]。
校準後需重新編譯燒錄。
3. 序列埠通訊協定
3.1 實體層
| 參數 | 值 |
|---|---|
| 介面 | USB Serial (UART0) |
| 鮑率 | 115200 |
| 資料位元 | 8 |
| 同位檢查位元 | 無 (None) |
| 停止位元 | 1 |
| 流量控制 | 無 |
3.2 幀格式
主機 → ESP32（命令幀）
┌────────┬────────┬──────────┬────────────────┬──────────┐
│ 0xAA │ CMD_ID │ DATA_LEN │ DATA[0 .. N-1] │ CHECKSUM │
│ 1 Byte │ 1 Byte │ 1 Byte │ N Bytes │ 1 Byte │
└────────┴────────┴──────────┴────────────────┴──────────┘
幀頭 命令ID 資料長度 資料負載 校驗和- 幀頭: 固定
0xAA，標識一幀的開始 - CMD_ID: 命令編號（見 命令參考）
- DATA_LEN: 資料負載的位元組數（0-8，超過 8 的幀無效）
- DATA: 資料負載，長度由 DATA_LEN 決定
- CHECKSUM:
CMD_ID ^ DATA_LEN ^ DATA[0] ^ ... ^ DATA[N-1]（XOR 校驗）
如果 DATA_LEN = 0，則 CHECKSUM = CMD_ID。
ESP32 → 主機（回應幀）
┌────────┬────────┬────────┬──────────┐
│ 0xBB │ CMD_ID │ STATUS │ CHECKSUM │
│ 1 Byte │ 1 Byte │ 1 Byte │ 1 Byte │
└────────┴────────┴────────┴──────────┘
幀頭 命令ID 狀態碼 校驗和- 幀頭: 固定
0xBB - CMD_ID: 原始命令編號
- STATUS: 狀態碼（見下表）
- CHECKSUM:
CMD_ID ^ STATUS
狀態碼
| STATUS | 含義 | 說明 |
|---|---|---|
| 0x00 | OK | 命令已接受，開始執行 |
| 0x01 | 無效命令 | CMD_ID 不在命令表中 |
| 0x02 | 參數錯誤 | 資料長度或內容不正確 |
| 0x03 | 忙碌 | 手勢執行中，暫不接受新命令 |
| 0x10 | 完成 | 手勢執行完畢 |
3.3 通訊時序
主機 ESP32
│ │
│──── [AA 01 00 01] ────────→│ 發送「石頭」命令
│ │
│←─── [BB 01 00 01] ─────────│ ACK: 命令已接受
│ │
│ (執行手勢中)
│ │
│←─── [BB 01 10 11] ─────────│ 完成: 手勢執行完畢
│ │
│──── [AA 02 00 02] ────────→│ 發送「剪刀」命令
│ │
│←─── [BB 02 00 02] ─────────│ ACK
│ │3.4 停止手勢 & 幀逾時
- 發送
[AA FF 00 FF]可隨時中斷正在執行的手勢 - ESP32 在 200ms 內未收完一幀會自動丟棄（防止丟位元組導致永久失步）
- 校驗和不匹配的幀會被靜默丟棄，上位機應實作逾時重發
3.5 左右手模式
預設右手模式。發送 [AA F1 01 02 F2] 切換左手，[AA F1 01 01 F1] 切回右手。左右手影響拇指的運動方向（石頭/剪刀/比讚/OK/捏合等含拇指手勢）。
4. 命令參考
4.1 手勢命令（0x01–0x0A、0x0C）
這些命令無需資料負載 (DATA_LEN=0)，ESP32 收到後立即執行對應手勢。
| 命令 | HEX 幀 | 回應 | 說明 |
|---|---|---|---|
| 石頭 | AA 01 00 01 | BB 01 00 01 → BB 01 10 11 | 全指握拳 |
| 剪刀 | AA 02 00 02 | BB 02 00 02 → BB 02 10 12 | 食指+中指伸出 |
| 布 | AA 03 00 03 | BB 03 00 03 → BB 03 10 13 | 全指張開 |
| 比讚 | AA 04 00 04 | BB 04 00 04 → BB 04 10 14 | 拇指豎起 |
| 嘲諷1 | AA 05 00 05 | BB 05 00 05 → BB 05 10 15 | 搖食指（約 2.5s） |
| 嘲諷2 | AA 06 00 06 | BB 06 00 06 → BB 06 10 16 | 無名指晃動（約 2.5s） |
| 張開 | AA 07 00 07 | BB 07 00 07 → BB 07 10 17 | 全指張開 |
| 握拳 | AA 08 00 08 | BB 08 00 08 → BB 08 10 18 | 全指閉合 |
| OK | AA 09 00 09 | BB 09 00 09 → BB 09 10 19 | OK 手勢 |
| 捏合 | AA 0A 00 0A | BB 0A 00 0A → BB 0A 10 1A | 捏合手勢 |
| 指向 | AA 0C 00 0C | BB 0C 00 0C → BB 0C 10 1C | 食指伸出做「指」動作 |
4.2 直驅命令 (0xF0)
直接控制 8 路伺服馬達角度，8 位元組資料分別對應伺服馬達 1-8，每位元組取值範圍 0-180。
範例：全部伺服馬達歸中位（90°）
發送: AA F0 08 5A 5A 5A 5A 5A 5A 5A 5A F8
│ │ │ └── 8 個 0x5A (90°) ──┘ │
│ │ │ └── CHECKSUM
│ │ └── DATA_LEN = 8
│ └── CMD_DIRECT_DRIVE
└── 幀頭校驗和 = F0 ^ 08 ^ 5A ^ 5A ^ 5A ^ 5A ^ 5A ^ 5A ^ 5A ^ 5A = F8
8 個相同的 0x5A 兩兩 XOR 得 0x00，最終
0xF0 ^ 0x08 ^ 0x00 = 0xF8
範例：食指張開(伺服馬達1=170°, 伺服馬達2=10°)，其餘歸中(90°)
發送: AA F0 08 AA 0A 5A 5A 5A 5A 5A 5A 58
└─170° └─10°4.3 設左右手 (0xF1)
1 位元組資料：0x01 = 右手，0x02 = 左手。
設右手: AA F1 01 01 F1
設左手: AA F1 01 02 F24.4 控制命令
| 命令 | HEX 幀 | 說明 |
|---|---|---|
| NOP | AA 00 00 00 | 鏈路測試，立即返回 BB 00 00 00 |
| 重複 | AA FE 00 FE | 重複執行上一次手勢 |
| 停止 | AA FF 00 FF | 立即終止目前手勢 |
4.5 回應速查
收到無效命令時（以 0xFC 這個不存在的命令為例）：
發送: AA FC 00 FC
回應: BB FC 01 FD （STATUS=0x01 無效命令）校驗和驗證:
FC ^ 00 = FC，回應FC ^ 01 = FD
5. 手勢參數精調
5.1 參數位置
每個手勢的角度偏移量用 #define 巨集定義，無需改邏輯程式碼，只調數值。
- ESP-IDF 版：
components/hand_gestures/hand_gestures.c頂部「手勢參數（使用者可調）」區
5.2 參數含義
// 例：石頭手勢
#define ROCK_IDX_OFF1 70 // 食指關節1 偏移量
#define ROCK_IDX_OFF2 -70 // 食指關節2 偏移量- 正值 = 彎曲握緊，負值 = 伸展打開
- 每根手指 2 個偏移量，相對
middle_pos（預設 90°） - 差動結構：兩伺服馬達並排、軸心共線；同向旋轉產生左右側擺，反向旋轉產生屈伸；兩個偏移角之和對應側擺，之差對應屈伸。
5.3 調參步驟
- 找到對應手勢的
#define巨集 - 修改數值（增大 → 幅度更大；減小 → 幅度更小）
- 重新編譯燒錄，用上位機測試效果
- 反覆微調直到動作自然
6. 常見問題
Q1: 上位機連不上序列埠？
- 確認 ESP32 已透過 Type-C 連接電腦
- 檢查裝置管理員中的 COM 埠號是否與 GUI 選擇一致
- 確認鮑率 115200
- 斷開其他佔用序列埠的軟體
Q2: 發送命令沒反應？
- 先發
AA 00 00 00（NOP），應收到BB 00 00 00 - 確認韌體已燒錄且目標晶片是 ESP32-S3
- 檢查接線（GND 是否共地）
Q3: 手勢動作幅度不對或方向反了？
進入手勢參數精調（見 第 5 節）調整對應巨集。
Q4: 左右手模式影響哪些手勢？
石頭/剪刀/比讚/OK/捏合等含拇指的手勢，切換左右手後拇指鏡像方向。
Q5: 手指卡住、伸不出來？
所有收縮類手勢執行前會自動「先全手展開再收攏」，避免手指被上一手勢擋住。若仍卡住，檢查機械裝配或減小收縮幅度。