01-GUI 可視化制御
可視化ジェスチャー指令 — 使用チュートリアル
本ディレクトリは上位機制御ツールを提供します：ESP32 に接続した後、パソコンでボタンをクリック／コマンドを入力して器用なハンドにジェスチャーを実行させます。
適用：ESP32-S3 + 8 チャンネル PWM サーボ(差動駆動)。ファームウェアの書き込みは
..\03_firmware_docsの説明を参照してください。
一、2 つの使用方法
| 方式 | 必要なもの | 適する用途 |
|---|---|---|
| パッケージ版プログラム(推奨) | AmazingHand控制台.exe をダブルクリック | Python のインストール不要、クリックするだけ |
| ソースコード実行 | 64 ビット Python 3.12 | ジェスチャートラッキングが必要、またはカスタマイズしたい場合 |
二、方式一：exe をダブルクリック
AmazingHand控制台.exeをダブルクリックします。シリアルポート選択：上部のドロップダウンボックスで ESP32 の COM ポートを選択します(デバイスマネージャーで確認)。
**「接続」**をクリックします：ステータスランプが緑になり、ログに「接続済み」と表示されます。
ジェスチャーボタンをクリックします：グー / チョキ / パー / サムズアップ / OK / ピンチ / 指差し / 開く / 握拳、器用なハンドが実行します。
左右の手：「右手」/「左手」にチェックを入れて切り替えます(親指のミラー方向が異なります)。
サーボ直接駆動：8 個のスライダーをドラッグして、単一サーボの角度をリアルタイム制御します(0-180°)。
指の差動制御：各指に 2 つのプログレスバー——
屈曲◀▶伸展：指を曲げるか伸ばします(範囲 -70 ~ +70)。
右スイング◀▶左スイング：指を左右に振ります(範囲 60 ~ 120、90=中立)。
繰り返し / 停止：前回のジェスチャーを繰り返す / 即座に中断します。
三、方式二：ソースコード実行
依存関係のインストール
64 ビット Python 3.12 が必要です(mediapipe は 64 ビットのみ対応)。
# 1. 基本依存パッケージをインストール
pip install -r requirements.txt
# 2. トラッキング依存関係をインストール(ジェスチャートラッキングが必要な場合、仮想環境を自動構築)
setup_tracking.bat実行
# トラッキング環境で起動(mediapipe 含む)
tracking_env\Scripts\python hand_gui.pyまたは直接
python hand_gui.py(pyserial が入った任意の Python)。
GUI 内蔵のジェスチャートラッキング
GUI にはジェスチャートラッキングパネルが内蔵されています(カメラが手の動作に追従)：
シリアルポートに接続した後、「ジェスチャートラッキング (MediaPipe カメラ)」パネルまでスクロールします。
カメラ番号を選択し(既定値 0)、**「トラッキング開始」**をクリックします。
手をカメラの画面に入れると、器用なハンドが屈曲/伸展に追従します。
トラッキングには
setup_tracking.batで mediapipe をインストールしておく必要があります。インストール不要の exe にはトラッキング機能は含まれません。
四、コマンドラインテスト(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 # すべてのサーボを順番にテスト五、よくある質問
| 現象 | 対処 |
|---|---|
| サーボが動かない | 電源供給(5V 3A 独立電源)、COM ポート、配線を確認 |
| exe が強制終了する | ソースコード方式で実行する(パッケージ版は依存関係が欠けている可能性) |
| カメラの映像が出ない | カメラの権限を許可する(設定→プライバシー→カメラ) |
| ハンド形状が逆になる | 逆の左右の手にチェックを入れる |
完全なプロトコルとコマンドの説明は
..\03_firmware_docs\用户手册.mdを参照してください。