よくある問題（FAQ）
共通
SCS0009 と PWM のどちらを選ぶべき？ 位置フィードバック、精度、LeRobot/SO-ARM101 のデータ収集が必要なら SCS0009、単体デモ、ジェスチャー操作、ウェブ／デスクトップでのクイックスタートなら PWM を選んでください。詳しくは バージョン比較 を参照。
2 つのサーボ構成を同時に接続できる？ できません。給電、プロトコル、ファームウェアがすべて異なるため、同時に片方だけ接続してください。
ハンドにそのまま通電できる？ 初回通電の前にハンドを中間位置に合わせ、中間位置に合わせてサーボホーンを取り付けてください。外部電源とドライバ基板／ESP32 は共通グラウンドにする必要があります。
サーボの型番は変更できる？ SCS0009 版はバスサーボを使用します。PWM 版のファームウェアは PTK 7452 MG-D（333 Hz デジタルサーボ）に合わせてキャリブレーションされています。SG90 などの 50 Hz アナログサーボは PWM 版に直接置き換えられず、LEDC_FREQ とパルス幅のキャリブレーションを変更する必要があります。
SCS0009 シリアルバス版
動作の向きが逆になった → 「奇数 ID が先」に従って配線しているか確認してください。左手は angle_offset_deg = -35.16 も確認します。
左手の握り拳の幅が足りない／サーボが唸る → config.json のリミットが ±120° になっているか確認してください（デフォルトの ±90 では左手の握り拳がクリップされます）。
指が動かない／「N 個のモーターが必要、M 個を検出」と表示される → tools/scan_servos.py を実行してください。左手の ID が最も配線を間違えやすいです（9–16 ではなく 11–18）。
中間位置がずれている → 中間位置の値 -17.578125 は公式の raw 451/571 に対応します。機械的組み立てに合わせてキャリブレーションするには config.json の middle.positions を変更してください。
サーボ ID はどう設定する？ → SCS0009 調整ツールでスキャンして ID を変更します。右手 1–8、左手 11–18。
Linux でシリアルポートを開けない → 現在のユーザーを dialout グループに追加して再ログインしてください。
位置／温度／電圧は読み出せる？ → 読み出せます。SCS0009 は位置、速度、電圧、温度の読み戻しに対応しています。プロトコルメモリテーブルは scs_servo_protocol.md を参照してください。
PWM サーボ版
接続に失敗する／ESP32 が応答しない → 115200 ボーレート、ESP32 の COM ポート、5V/3A の給電と共通グラウンドを確認してください。シリアルポートを開くとリセットされることがあり、ページは自動的に NOP を再試行します。
サーボが動かない、または震える → 333 Hz のデジタルサーボ（PTK 7452 MG-D または同等品）であること、電源容量が十分であることを確認してください。SG90 はファームウェアの変更が必要です。
向きが逆 → ウェブの config.json の pwm.calibration で、該当する指の scale を -1 に変更してください。
中間位置がずれている → 該当するチャンネルの offset_deg を調整してください。詳しくは PWM プロトコル、コマンド、キャリブレーション を参照。
「忙（ジェスチャー実行中）」と表示される → ファームウェアが内蔵ジェスチャーを実行中です。完了を待つか、停止（0xFF）を送信してください。
PWM 版にフィードバックはある？ → 位置／温度／電圧の読み戻しはなく、ストールや脱調も検出できません。
PWM サーボにボーレートはある？ → サーボ自体にはありません。PC ↔ ESP32 のシリアルは固定で 115200 8N1 です。
一部のサーボだけ接続してテストできる？ → できます。未接続のチャンネルは空けておいても他のチャンネルに影響しません。空きコネクタは絶縁に注意してください。
カメラの映像は出るが手に追従しない／反応が鈍い → 照明を均一にし、手のひらをカメラから約 40–80 cm 離して正対させてください。カメラを占有している他のプログラムを閉じ、シリアルポートが接続されていることを確認してください。GUI のトラッキングパラメータは PWM ハンドトラッキング を参照。
左右手の切り替えが反映されない → ファームウェアは 0xF1 で左手／右手を切り替えます（ウェブ接続時に自動送信されます）。この設定は主にファームウェア内蔵ジェスチャーの親指方向に影響し、ウェブのポーズは現在の制御対象に応じて各手のマッピングを使用します。
追跡画面が固まる／ログが止まる → トラッキングを停止してから再開してください。それでも応答しない場合は GUI を閉じて開き直し、カメラが他のプログラムに占有されていないことを確認してください。
USB ポートを変えたらシリアルポートが見つからない → デバイスマネージャーで新しい COM 番号を確認し、GUI またはウェブで「Refresh」をクリックしてから選び直してください。
ウェブコントロール
モデルの読み込み失敗／カメラトラッキングの読み込み失敗 → ページがローカルサーバーから提供されていること（file:// で直接開いていないこと）、MediaPipe のリソースパスへアクセスできることを確認してください。ローカルチュートリアルはサーバー側の MediaPipe ルーティングを修正済みです。それでも失敗する場合は、ブラウザの Console/Network で 404 や権限エラーを確認してください。
カメラの認識が不正確 → 照明を均一にし、手のひらをカメラへ正対させます。tracking.js の SMOOTH（デフォルト 0.35）は大きいほど滑らかですが反応が鈍くなります。
ある指が追従しない → 3 つのポーズを取り直してください。向きが逆なら該当するポーズを取り直します。親指は屈伸のみで、開きには参加しません。
握り拳の途中であるサーボが逆転する → 開きが曲げに応じて 0 まで減衰しているか（side *= (1 - curl)）を確認し、開きの制御量の符号と大きさが異常でないか確認してください。
ウェブのドライバーはどう切り替える？ → 上部の「Driver」ドロップダウンで SCS0009 または PWM を選択します。PWM は 115200 のシリアルポートを選ぶ必要があります。詳しくは ウェブコントロール概要 を参照。
デスクトップツール
SCS0009 GUI にシリアルポートが一覧表示されない → USB アダプターを挿し直す、ドライバーをインストールする、または GUI を再起動してください。Linux では dialout を確認します。
Connect ボタンが灰色になる → すでに接続済みです。先に Disconnect をクリックしてください。
シーケンスで一部の指が動かない → 各ステップの速度を確認し、各ポーズに 8 個すべてのサーボ値が含まれるようにしてください。
ストール表示が消えない → 機械的な引っかかりを確認してください。目標と実際の位置の差が大きく、動作がない場合にストールと判定されます。
PWM GUI の起動時に mediapipe が無いと表示される → tools/tracking_env の Python で起動するか、tools/setup_tracking.bat を再実行してください。
ハンドトラッキング
mediapipe に solutions サブモジュールが無い → mediapipe==0.10.14 をインストールし、Python 3.12 が 64 ビットであることを確認してください。
dora のバージョンが合わない → pyproject.toml とログに合わせて dora のバージョンを揃えてください。クリーンアップ後に再インストールします。
モデルの読み込みに失敗する（中国語パス） → プロジェクト／モデルをすべて英語のパスへ置いてください。
カメラの映像が出ない／権限 → システムのカメラ権限を許可してください。仮想マシンではカメラの USB パススルーが必要です。
SCS0009 公式 Demo と PWM GUI トラッキングの違いは？ → SCS0009 は dora + MuJoCo IK の完全な経路を使用します。PWM 版は GUI 内蔵の MediaPipe による軽量トラッキングを提供し、dora Demo はモジュールに含まれません。詳しくは SCS0009 ハンドトラッキング / PWM ハンドトラッキング を参照。