AmazingHand PWM 器用なハンド — 全フローチュートリアル
付属配布パッケージ： delivery_package.zip
上位機のジェスチャーコマンドからジェスチャートラッキングまで、一気通貫の使用チュートリアル。 対応ハードウェア：ESP32-S3 + 8 チャンネル PWM サーボ(差動駆動)。
バージョン：2026-08-20 · 対応ファームウェア：ESP-IDF コンポーネント化版(
AmazingHand_Serial)
第 0 章 チュートリアルガイド
本チュートリアルは順番に沿って構成されています。まず自分がどのルートに進むかを確認してから、対応する章へ進んでください。
| ルート | 用途 | 前提条件 | 章 |
|---|---|---|---|
| A. 上位機ジェスチャーコマンド | ボタンをクリック/コマンド入力でロボットハンドがジェスチャー(グー/チョキ/パー/サムズアップ…) | Python + ファームウェア書き込み | 第 1-4 章 |
| B. GUI 内蔵ジェスチャートラッキング | カメラが手の動きに追従し、ロボットハンドがリアルタイムに再現(簡易版、IK なし) | A + 64 ビット Python + mediapipe | 第 1-4 章 + 5.1 |
| C. dora 公式 IK トラッキング | 公式の完全チェーン：カメラ→IK→8 関節角→サーボ(完全版) | A + Rust + uv + dora | 第 1-4 章 + 5.2 |
推奨ルート：
- 初めて使う → A へ。まずファームウェアと配線に問題がないことを確認。
- カメラ追従をすぐに見たい → B(軽量、数分でセットアップ完了)。
- 正式で完全なトラッキングをしたい → C(公式チェーン、精度最高)。
3 つのルートはハードウェアを共用し、追加で Rust/uv/dora をインストールする必要があるのはルート C のみです。
第 1 章 環境準備
順番にインストールします。ルート A/B は第 1.1 節のみ必要です。ルート C は第 1.2 節も必要です。
1.1 上位機環境(ルート A/B 必須)
① 64 ビット Python 3.12
必ず 64 ビットにしてください。mediapipe 0.10.14 は 64 ビット Windows 用の wheel のみ提供しており、32 ビットにはインストールできません。 これは GUI をダブルクリックしてもすぐに落ちるよくある原因でもあります。
D:\Python312-64bitへのインストールを推奨します(本機には既にこのパスがあります)。- インストール時に Add to PATH にチェックを入れてください。
- 確認(64 ビット)：
py -3.12-64 -c "import sys; print('64bit' if sys.maxsize > 2**32 else '32bit')"
# 输出: 64bit② 上位機の依存関係をインストール
プロジェクトのルートディレクトリ(hand_gui.py があるディレクトリ)：
pip install -r requirements.txt # 只需 pyserial③ トラッキング用追加依存関係(ルート B 用)
プロジェクトのルートディレクトリで実行：
setup_tracking.bat自動的に以下を行います：64 ビット Python の検索 → tracking_env 仮想環境の作成 → requirements-tracking.txt のインストール (mediapipe==0.10.14、numpy<2、scipy、opencv、Pillow、pyserial)→ mediapipe の検証。
または手動でインストール：
bashD:\Python312-64bit\python.exe -m pip install -r requirements-tracking.txt
1.2 dora 公式 IK 環境(ルート C 必須)
お客様によるインストール：..\02_hand_tracking\Demo\Windows_Scripts_CN\1-安装环境.bat(英語版は ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\1-Install_Env.bat)をダブルクリックすると、すべての依存関係が自動インストールされます： Rust ツールチェーン、uv(Python パッケージ管理)、dora-cli。
インストール後、ターミナルを閉じて開き直し、PATH を反映させてください。 詳細な依存関係(バージョン、手動インストール方法)は保守ドキュメントを参照してください。お客様側での対応は不要です。
第 2 章 ハードウェア配線
2.1 ハードウェアリスト
| ハードウェア | 説明 |
|---|---|
| ESP32-S3 開発ボード | YX-ESP32-S3 または同等品 |
| 8 チャンネル PWM サーボ | アナログサーボ、差動駆動 |
| サーボアダプタボード | サーボ → 8 チャンネル PWM 出力 |
| 独立 5V 電源 | 少なくとも 5V 3A、サーボの過渡電流が大きい |
| USB データケーブル | ESP32-S3 Type-C → PC |
| カメラ | 内蔵または USB カメラ(トラッキング用) |
2.2 GPIO マッピング
アダプタボード PWM1-8 → ESP32-S3 GPIO：
| アダプタボード | GPIO | 指 |
|---|---|---|
| PWM1 | 4 | 人差し指関節 1 |
| PWM2 | 5 | 人差し指関節 2 |
| PWM3 | 6 | 中指関節 1 |
| PWM4 | 7 | 中指関節 2 |
| PWM5 | 15 | 薬指関節 1 |
| PWM6 | 16 | 薬指関節 2 |
| PWM7 | 17 | 親指関節 1 |
| PWM8 | 18 | 親指関節 2 |
左右の手は同じ GPIO を共用します。左手/右手はソフトウェアで切り替えるため(第 4 章)、配線を変更する必要はありません。
2.3 電源要件
- サーボには独立した 5V 電源(少なくとも 3A)を使用し、USB 給電だけに頼らないでください。
- サーボの瞬間的な電流衝撃で ESP32 がリセットされることがあります(症状：ESP32 が繰り返し再起動する)。その場合は ESP32 を電源から切って再起動してください。
2.4 配線手順
- 8 チャンネルサーボ → アダプタボード PWM1-8
- アダプタボード → ESP32-S3 の対応 GPIO(上表)
- ESP32-S3 Type-C → PC
- カメラを PC に接続(トラッキング用)
詳細な配線/回路図は
ESP32开发板电路图/ディレクトリを参照してください。
第 3 章 前提条件：ファームウェアの書き込み
サーボが応答するには、まずファームウェアを書き込む必要があります。ファームウェアは
esp-idf\AmazingHand_Serial\にあります。
3.1 ESP-IDF 版のビルド(推奨)
Espressif IDE で AmazingHand_Serial プロジェクトを開きます：
- ターゲットチップを設定(初回)：
idf.py set-target esp32s3 - ビルド：
idf.py build - 書き込み(Windows では COM ポート、例：COM3)：
idf.py -p COM3 flash
3.2 書き込み後の確認
シリアルモニタ(ボーレート 115200)：
idf.py -p COM3 monitor次の起動ログが表示されるはずです：
AmazingHand Serial Control Ready (ESP-IDF)
Protocol: 115200-8N1 [0xAA CMD LEN DATA CKSUM]シリアルのボーレートはファームウェア/スクリプト側で統一設定済み(115200)のため、お客様が手動で設定する必要はありません。
注：通常、機器の納品時にはファームウェアは書き込み済みです。この手順は新しいファームウェア/再書き込み時のみ実行してください。
第 4 章 初回実行：上位機のジェスチャーコマンド
前提：ファームウェア書き込み済み(第 3 章)、ESP32 通電済み、シリアルケーブル接続済み。まずデバイスマネージャーで COM ポートを確認してください。
4.1 GUI 可視化(推奨)
方式 A：パッケージ化した exe を実行
dist/AmazingHand控制台.exe をダブルクリックします(トラッキングなし。トラッキングにはソースコード方式が必要)。
方式 B：ソースコードから実行
# 项目根目录,先激活追踪环境(装了 mediapipe)或任意带 pyserial 的 Python
tracking_env\Scripts\python hand_gui.pyGUI の使用手順
- シリアルポート選択：上部のドロップダウンで ESP32 の COM ポートを選択。
- 「接続」をクリック：ステータスランプが緑になり、ログに「接続済み」と表示され、自動的に NOP リンクテストを送信。
- ジェスチャーコマンド：「グー」「チョキ」「パー」「サムズアップ」「OK」「ピンチ」「指差し」などをクリックすると、ロボットハンドが実行。
- 左右の手：「右手」/「左手」にチェックを入れて親指のミラー方向を切り替え。
- サーボ直接駆動：8 個のスライダーをドラッグして、単一サーボの角度をリアルタイム制御(0-180°)。
- 指の差動制御(推奨)：各指に 2 つのプログレスバー——「屈曲◀▶伸展」は逆方向差動、「右スイング◀▶左スイング」は同方向スイング。2 つの自由度は独立し、同期駆動。
- 繰り返し/停止：前回のジェスチャーを繰り返し / 即座に中断。
- 通信ログ：下部に送受信フレームと応答をリアルタイム表示。
4.2 コマンドラインテスト(serial_test.py)
プロジェクトのルートディレクトリ：
# 链路测试(先确认能通)
python serial_test.py COM3 nop
# 手势
python serial_test.py COM3 rock # 石头
python serial_test.py COM3 thumbs_up # 真棒
python serial_test.py COM3 index # 指向
python serial_test.py COM3 open # 张开
python serial_test.py COM3 close # 握拳
# 单舵机直驱
python serial_test.py COM3 servo 1 90 # 舵机1 → 90°
# 全部归中
python serial_test.py COM3 mid
# 设左右手
python serial_test.py COM3 hand L
python serial_test.py COM3 hand R
# 扫频/自检
python serial_test.py COM3 sweep 1 # 舵机1 扫频
python serial_test.py COM3 test # 全部舵机逐个测试4.3 確認
- ジェスチャーをクリックすると、サーボが対応する動作を実行するはずです。シリアルログに
ACKとDONEが返ります。 - 応答コード：
0x00=OK、0x01=無効なコマンド、0x02=パラメータエラー、0x03=ビジー、0x10=完了。 - サーボがまったく動かない場合：第 6 章のよくある質問を参照(まず電源/シリアルを確認)。
ジェスチャーコマンドとシリアルプロトコルの完全な早見表は第 7 章を参照。
第 5 章 応用チュートリアル：ジェスチャートラッキング
前提：第 1-4 章完了(ファームウェア書き込み、シリアル制御可能、カメラ準備完了)。 本章は 2 つのルートがあります。どちらか一方を選んで進んでください。
5.1 GUI 内蔵トラッキング(軽量版)
対象：簡単なデモ向け。dora のインストール不要。カメラ → 差動サーボへ直接マッピング、IK なし。
前提
- 64 ビット Python +
setup_tracking.bat(第 1.1 節)。 - カメラが使用可能。
実行
# 项目根目录,用追踪环境启动 GUI
tracking_env\Scripts\python hand_gui.py- シリアルポートを選択 → 「接続」。
- 「ジェスチャートラッキング (MediaPipe カメラ)」パネルまでスクロール。
- カメラ番号を選択(既定 0)→「トラッキング開始」をクリック。
- 手を画面内に入れると、ロボットハンドが手の屈曲/伸展に追従。
原理
- mediapipe 0.10.14 が 4 指の指先の 3D ベクトルを抽出(手の座標系)。
hand_tracking.pyのtips_to_angles()が各指を差動角度にマッピング：- flex(屈曲/伸展)：3 指は z 成分、親指は y 成分を使用。
- base(左右スイング)：90 に固定(左右スイングは未実装)。
- GUI に EMA 平滑化(alpha=0.4)+ 60ms スロットリングを内蔵し、ぶれを防止。
制限
- IK なし：指先を直接角度にマッピングするため、精度は公式チェーンに劣ります。
- 左右スイングは保留：base は 90 に固定で、左右スイングは行いません。
- デモ/プロトタイプ向け。正式用途には 5.2 を推奨。
5.2 dora 公式 IK トラッキング(完全版)
対象：正式な使用向け。公式チェーン：カメラ → mediapipe → MuJoCo+mink IK → 8 関節角 → AHControl(Rust)→ ESP32 → PWM サーボ。
前提
- 完全な環境(Rust + uv + dora、第 1.2 節)。
- ファームウェア書き込み(第 3 章)。
- データフロー yml には PWM ボーレート(115200)が設定済みのため、手動で変更する必要はありません。
ステップ 1：デプロイ(ワンクリックスクリプト推奨)
..\02_hand_tracking\Demo\Windows_Scripts_CN\3-部署代码.bat(英語版は ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\3-Deploy_Demo.bat)をダブルクリックすると、自動的に以下が完了します： Python 環境の作成、AHControl(Rust)のビルド、AHSimulation/HandTracking(mediapipe)のインストール。
初回デプロイには数分かかります。スクリプトには環境変数の処理が組み込まれているため、手動で設定する必要はありません。
ステップ 2：実行
..\02_hand_tracking\Demo\Windows_Scripts_CN\4-运行代码.bat(英語版は ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\4-Run_Demo.bat)をダブルクリックし、メニューから選択します：
1 - 模拟仿真（摄像头手势追踪）
2 - 真实硬件（SCS0009 总线舵机）
3 - PWM 舵机（ESP32 直驱） ← 选 3さらにハンドの種類を選択：1 右手 / 2 左手。スクリプトが自動的に dora build + dora run を実行します。
- カメラウィンドウが開くので、手を画面に入れる → 3D シミュレーションの指が追従 → ロボットハンドが追従。
- 停止：Ctrl+C(またはウィンドウを閉じる)。
左右の手の切り替え
実行メニューでハンドの種類を選択するだけです(第 5.2 節ステップ 2)：1 右手 または 2 左手 を選択。
切り替え後、スクリプトが対応するデータフローを自動的に再ビルドします。ビルド完了を待ってからカメラ前で操作してください。
実行ログの見方
実行ウィンドウでは AHControl ノードが継続的にログを出力します。特に次の行に注目してください：
[ACK-STATS] sent N frames, ESP32 acked M framesM ≈ N(例：sent 300 frames, ESP32 acked 300 frames)→ 正常。ESP32 が毎フレーム受信しています。M = 0→ ESP32 がデータを受信していません。シリアル/電源を確認してください(第 6 章参照)。
この行が正常に増えていれば、サーボのチェーンは通っています。あとはカメラが追従できるかどうかの問題です。
第 6 章 よくある質問(実行中)
本節では、使用中に最も遭遇しやすく、自分で解決できる問題のみを挙げます。症状からすばやく原因を特定してください。
6.1 サーボがまったく動かない
順番に確認：
- 電源：サーボに独立電源(5V 3A 以上)が接続されていますか？USB 給電だけの場合、サーボが動かない、または ESP32 が繰り返し再起動することがあります。→ ESP32 を電源から切って再起動。
- シリアル：COM ポートは正しく選択されていますか？デバイスマネージャー → ポート(COM と LPT)で ESP32 に対応するポートを確認。他のプログラム(シリアルターミナルなど)が占有していませんか？→ 占有しているプログラムを終了。
- 配線：アダプタボード PWM1-8 は正しい GPIO に接続されていますか？サーボの信号線はしっかり挿さっていますか？
6.2 カメラの映像が出ない
- Windows で初回実行時にカメラのアクセス許可が表示されます → 「許可」をクリック。
- 以前に「いいえ」を選んだ場合：設定 → プライバシーとセキュリティ → カメラ → デスクトップアプリによるカメラへのアクセスを許可し、再実行してください。
6.3 カメラ映像はあるが、手が追従しない / 追従が鈍い
- カメラが手を正しく向いていること、光量が十分であること、手が画面内に全体が見えていることを確認。
- ゆっくり、大きく動かしてください。速すぎる、または動きが小さすぎると、トラッキングが追いつかないことがあります。
- 3D シミュレーションウィンドウで指は動きましたか？
- 動いた：トラッキングチェーンは正常。問題はサーボ/シリアルにあるため、6.1 を参照。
- 動かない：トラッキングノードが手を認識できていません。姿勢/光量を調整して再試行。
6.4 ハンドの種類が逆 / 親指の方向が逆
- 左手/右手を間違えていませんか？実行メニューで対応するハンドの種類を選択。
- 上位機 GUI で「右手」/「左手」にチェックを入れて切り替え。
6.5 左右の手の切り替えが反映されない
- ハンドの種類を切り替えると、
doraはデータフローを再ビルドする必要があります。実行メニューでハンドの種類を選択すると自動的にdora buildが実行されるので、完了を待ってください。
6.6 実行中に画面が固まる / ログが止まる
- カメラが他のアプリ(ビデオ会議、別のスクリプト)に占有されている可能性があります。終了してから再試行してください。
- または
Ctrl+Cで停止し、再実行してください。
6.7 USB ポートを変えた / PC 再起動後にシリアルポートが見つからない
- COM ポート番号が変わった可能性があります。デバイスマネージャーで新しい COM 番号を確認し、
2-配置串口.bat(または2-Setup_Serial.bat)を再実行してポートを一度選択してから、再度実行してください。
6.8 まだ解決しない場合
- 実行ターミナルのログのスクリーンショットを保守担当に送り、どのステップで、何をしたときに、どのような現象が起きたかを説明してください。
- 重要なログ：起動時の
[CONFIG]行、実行中の[ACK-STATS]行(ESP32 acked M framesの M が N に近いかどうか)。
第 7 章 コマンド早見表(付録)
完全なプロトコル説明は同ディレクトリの
用户手册.mdを参照してください。ここでは早見表を提供します。
7.1 ジェスチャーコマンド
| ジェスチャー | HEX | ACK | DONE |
|---|---|---|---|
| NOP | AA 00 00 00 | BB 00 00 00 | — |
| グー | 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(薬指) | AA 06 00 06 | BB 06 00 06 | BB 06 10 16 |
| 開く | 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 |
| ピンチ | AA 0A 00 0A | BB 0A 00 0A | BB 0A 10 1A |
| 指差し | AA 0C 00 0C | BB 0C 00 0C | BB 0C 10 1C |
7.2 制御コマンド
| コマンド | HEX | 説明 |
|---|---|---|
| 繰り返し | AA FE 00 FE | 前回のジェスチャーを繰り返す |
| 停止 | AA FF 00 FF | 即座に中断 |
| 右手設定 | AA F1 01 01 F1 | — |
| 左手設定 | AA F1 01 02 F2 | — |
| 直接駆動 | AA F0 08 [8×角度] CKSUM | 8 バイトの角度 |
7.3 フレームフォーマット
帧头(0xAA) + 命令(CMD) + 长度(LEN) + 数据(DATA) + 校验和(CKSUM)
CKSUM = CMD ^ LEN ^ DATA[0] ^ ... ^ DATA[N-1]
响应: 帧头(0xBB) + CMD + STATUS + (CMD^STATUS)7.4 上位機ツール
| ツール | コマンド | 用途 |
|---|---|---|
| GUI | tracking_env\Scripts\python hand_gui.py | ジェスチャーの可視化 + 直接駆動 + 差動 + トラッキング |
| パッケージ exe | dist/AmazingHand控制台.exe | Python 不要の可視化(トラッキングなし) |
| コマンドライン | python serial_test.py COMx <cmd> | 自動テスト |
7.5 トラッキングデータフローファイル(PWM 版)
| 用途 | ファイル |
|---|---|
| 左手 PWM トラッキング | dataflow_tracking_real_left_pwm.yml |
| 右手 PWM トラッキング | dataflow_tracking_real_right_pwm.yml |
| 左手 PWM 設定 | AHControl/config/l_hand_pwm.toml |
| 右手 PWM 設定 | AHControl/config/r_hand_pwm.toml |