02-ジェスチャートラッキングチュートリアル

ジェスチャートラッキング — 使用チュートリアル(PWM サーボ版)

本ディレクトリはジェスチャートラッキングを提供します：カメラがあなたの手を認識し、器用なハンドがリアルタイムに追従します(完全な IK チェーン)。

チェーン：カメラ → mediapipe 手部骨格 → MuJoCo+IK → 8 関節角 → ESP32 → PWM サーボ

適用：ESP32-S3 + 8 チャンネル PWM サーボ。ファームウェアの書き込みは ..\03_firmware_docs を参照してください。

一、前提条件

1. ハードウェア：ESP32-S3 + 8 チャンネル PWM サーボに通電、USB 接続済み、カメラが使用可能。

2. ファームウェア：書き込み済み(..\03_firmware_docs の用户手册を参照)。

3. 初回デプロイ(1 回だけ、下記参照)。

二、初回デプロイ

2.1 環境のインストール

Demo\Windows_Scripts_CN\ に入り(英語システムでは Windows_Deploy_Scripts\)、番号順にダブルクリックします：

1-安装环境.bat   → 安装 Rust / uv / dora(几分钟)

インストール後、ターミナルを閉じて開き直してください。

2.2 Demo のデプロイ

3-部署代码.bat   → 创建 Python 环境 + 编译 AHControl + 安装依赖(几分钟)

三、ジェスチャートラッキングを実行(毎回)

3.1 実行スクリプトをダブルクリック

Demo\Windows_Scripts_CN\ に入り、4-运行代码.bat をダブルクリックします：

Select a run mode:
   1 - 模拟仿真（摄像头手势追踪）
   2 - 真实硬件（SCS0009 总线舵机）
   3 - PWM 舵机（ESP32 直驱）    ← 选 3

さらにハンドの種類を選択します：

PWM 舵机（ESP32 直驱）- 请选择灵巧手：
   1 - 右手          ← 选 1
   2 - 左手          ← 选 2

3.2 使用開始

1. スクリプトが自動的に dora build + dora run を実行します。

2. カメラウィンドウが開き、3D シミュレーションの指が表示されます。

3. 手を画面に入れて指を動かす → 3D シミュレーションが追従 → 器用なハンドが追従。

4. 停止：Ctrl+C(またはウィンドウを閉じる)。

Linux システム：Demo\Linux_Scripts_CN\(中国語)または Linux_Deploy_Scripts\(英語)を使用し、スクリプト名に .sh が付き、bash 脚本名 または実行権限を付けて実行する必要があります。

四、正常に動作しているかの確認方法

実行ウィンドウで AHControl ノードが出力します：

[ACK-STATS] sent N frames, ESP32 acked M frames

• M ≈ N(例：sent 300 frames, ESP32 acked 300 frames)→ 正常、サーボリンクが通っています。

• M = 0 → ESP32 がデータを受信していません、シリアルポート/電源供給を確認してください(下記参照)。

この行が増え続けていれば、サーボリンクが正常であることがわかります。残りはカメラが追従できるかどうかの問題です。

五、左右の手の切り替え

実行メニューでハンドの種類を選択するだけです。切り替え後はスクリプトが自動的に再ビルドするので、ビルド完了を待ってから操作してください。

六、よくある質問

現象	対処
サーボがまったく動かない	電源供給(5V 3A)、COM ポート、配線を確認；ログの acked M frames が 0 かどうか
カメラの映像が出ない	カメラの権限を許可する(設定→プライバシー→カメラ)
手が追従しない / 鈍い	光量を十分に、手を完全に画面に入れる、ゆっくり大きく動かす
ハンド形状が逆 / 親指の方向が逆	メニューで左右の手を正しく選びましたか？もう一方を試してください
USB ポートを変えてシリアルポートが見つからない	2-配置串口.bat を再実行し、新しい COM ポートを一度選択する

七、SCS0009 バスサーボのユーザー

本 Demo は公式の SCS0009 バスサーボにも対応しています。メニューで 2 - 真实硬件(SCS0009 总线舵机) を選択し、構成と説明は Demo\双版本舵机并存说明.md および公式チュートリアルを参照してください。

ディレクトリ説明

パス	内容
Demo\AHControl	Rust サーボ制御プログラム(ソースコード、デプロイ時に自動コンパイル)
Demo\AHSimulation	MuJoCo シミュレーション + IK 求解
Demo\HandTracking	MediaPipe 手部トラッキング
Demo\Windows_Scripts_CN / Windows_Deploy_Scripts	Windows ワンクリックスクリプト(中/英)
Demo\Linux_Scripts_CN / Linux_Deploy_Scripts	Linux ワンクリックスクリプト(中/英)
Demo\dataflow_*_pwm.yml	PWM 版データフロー(ボーレート 115200 を内蔵済み)