本リポジトリは、TeachArm 展示デモのための FastAPI ベース実行環境と、管理 UI(Control Panel)をまとめたものです。docs/ 以下の仕様書に沿って、Vision/Mapping/Dialogue/Arm を統合するサーバと、監視・手動操作用の React UI を提供します。
teacharm/– FastAPI サーバ側の Python パッケージ。設定読み込み、教材・スクリプト処理、各サービス stub を含む。services/router.py– ルールベースルーティングサービスservices/deepseek.py– DeepSeek による文章生成専用サービス(必要時のみ呼び出し)services/dialogue.py– Router → 台本 → DeepSeek の順で処理する対話オーケストレーションservices/vision.py– カメラ入力、ArUco検出、MediaPipe Handsによる手検出services/arm.py– SO-101 ロボットアーム制御services/tts.py– VOICEVOX 音声合成services/asr.py– faster-whisper による音声認識
config/– Arm 安全領域や VOICEVOX パラメータ、9 点キャリブレーション、カメラ設定などの JSON/YAML。materials/– 教材 A/B の領域定義ファイル。scripts/common.yaml– 先生ロール・台本コマンド・ネガティブルール・エラー復帰メッセージ。.env.example– 環境変数テンプレート(Tailscale IP、LLM/VOICEVOX URL 等)。control-panel/– React + Vite 製のコントロールパネル UI。docs/– 各機能の詳細ドキュメント。tools/– ArUcoマーカー生成、座標変換、PDF抽出などのユーティリティ。
TeachArm の対話システムは、ルールベースルーティング と DeepSeek(文章生成専用) を組み合わせた設計です:
-
ルールベースルーティング(ローカル処理)
- 入力:状態、ASRテキスト、候補領域など
- 処理:キーワードマッチングでアクション決定
- 出力:次に実行すべきアクション
- メリット:高速・確実、ネットワーク不要
-
台本優先
- Router が決定したアクションに従い、まず
scripts/common.yamlの台本を確認 - 台本がある場合はそれを使用
- Router が決定したアクションに従い、まず
-
DeepSeek(自宅サーバー、Tailscale 経由)
- 台本が無い場合や、言い換えが必要な場合のみ呼び出し
- 1〜2文の短文生成
- 教材外の質問は拒否して学習に戻す
この設計により、展示会での安定運用を実現しています。
TeachArm サーバは Python 3.11 + venv/pip を推奨。Python バージョンは pyproject.toml の requires-python に固定している。
# 実行場所: 開発PC / Raspberry Pi
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# SO-101 実機用は別環境で: pip install -r requirements/arm.txt
cp .env.example .env # Tailscale IP などを実値で記入
python -m teacharm.mainMediaPipe の solutions が必要な場合は .venv を Python 3.10 で作成し、
.venv に requirements/vision-py310.txt をインストールする。
デフォルトで http://0.0.0.0:8000 で待ち受けます。主なエンドポイント:
GET /health– サーバヘルスチェックGET /api/stats– Router と DeepSeek の統計情報(リクエスト数、フォールバック数、平均時間など)GET /api/materials– 教材一覧POST /api/materials/select– 教材選択POST /api/events/pointer– ポインタイベント(指差し認識)POST /api/dialogue– テキスト入力による対話POST /api/asr/transcribe– 音声ファイルの文字起こし(faster-whisper)POST /api/dialogue/audio– 音声入力→対話→音声生成POST /api/arm/move– アーム移動POST /api/arm/safe_pose– アームをセーフポーズに戻すGET /api/state– 現在の状態取得POST /api/vision/start– カメラ起動POST /api/vision/stop– カメラ停止POST /api/vision/calibrate– ArUcoキャリブレーション実行WebSocket /ws/vision– リアルタイムビジョンフレーム配信(10fps)
TeachArmはカメラを使用してArUcoマーカー検出と手・指先追跡を行います。
# 1. ArUcoマーカーを生成
python tools/generate_aruco_markers.py
# 2. 生成されたマーカーを印刷し、教材の四隅に配置
# 3. カメラアクセス許可 (macOS)
# システム環境設定 > セキュリティとプライバシー > カメラ
# 4. インタラクティブデモ(プレビュー付き)
python demo_vision.py
# または基本テスト
python test_vision.pyデモ画面では:
- リアルタイムでカメラ映像を確認
- 手・指先の検出結果を可視化(緑の円と十字)
- ArUcoマーカーの検出状況を表示
cキーでキャリブレーション、qキーで終了
詳細は Visionクイックスタート または Vision機能ガイド を参照。
.env:Tailscale IP、LLM モデル名、Control Panel URL を実値にする。OLLAMA_BASE_URL:自宅サーバーの LLM URL(Tailscale 経由)OLLAMA_MODEL:文章生成用モデル(例: deepseek-r1:7b)ASR_MODELほか:音声入力(faster-whisper)の設定
config/arm_limits.json:SO-101 の関節制限・Safe Pose を設定。- SO-101 は 6 つの Feetech STS3215 サーボモーターを使用
- 各関節のギア比と可動範囲を記録(詳細: SO-101 Documentation)
safe_pose.anglesに6軸の安全姿勢を関節角度(度)で指定
config/arm_calibration.json:9 点 (u,v)→(x,y,z) を入力。materials/material_*.json:教材領域(question/line)を実データで記入。config/voicevox_params.yaml:VOICEVOX の話速/抑揚などを調整(必要に応じて)。config/camera.yaml:カメラ解像度、MediaPipe設定などを調整(デフォルトで動作)。
SO-101 の接続・キャリブレーション手順は SO-101セットアップガイド を参照してください。
関節角操作は scripts/move_arm.py から実行できます。macOS で lerobot[feetech] と faster-whisper が衝突する場合は、
SO-101 専用の仮想環境に分けて運用します。
python3.11 -m venv .venv-so101
source .venv-so101/bin/activate
pip install -r requirements/arm.txt
python scripts/move_arm.py --statusガイド内の「ターミナルの指示」は lerobot-setup-motors などの CLI 出力を指します。
URDF は SO-ARM100 の Simulation/SO101/so101_new_calib.urdf を参照しています(https://github.com/TheRobotStudio/SO-ARM100/blob/main/Simulation/SO101/so101_new_calib.urdf)。
- ✅ Dialogue/Router/DeepSeek: 完全実装済み
- ✅ Vision (Camera + MediaPipe Hands): 完全実装済み
- ✅ TTS (VOICEVOX): スタブ実装(外部サーバー接続対応)
⚠️ Arm (SO-101): 関節角制御は実装済み(LeRobot/Feetech SDK が必要、IK は未実装)
実機(カメラ、SO-101アーム)が揃い次第、該当サービスを有効化できます。
control-panel/ ディレクトリにあるコントロールパネルは Node.js が必要です。
cd control-panel
npm install
npm run devデフォルトでは http://localhost:8000 のサーバに接続します。別ホストへ向ける場合は VITE_TEACHARM_API_URL を指定してください。
VITE_TEACHARM_API_URL=http://100.xxx.xxx.xxx:8000 npm run devUI 上で以下の操作が可能です:
- サーバヘルスの確認
- Router / DeepSeek の統計情報表示(リクエスト数、フォールバック数、平均応答時間)
- 教材選択の切り替え
- 手動のポインタイベント送信(
on_point/on_help) - ダイアログテキスト送信(Router → 台本 → DeepSeek)
- アーム座標指定・Safe Pose 戻し
- ログの時系列確認(Router アクション、DeepSeek 呼び出し時間を含む)
scripts/common.yamlの内容編集(YAML エディタで直接保存可能)
Control Panel は Tailscale 内でのみ公開し、.env の CONTROL_PANEL_URL にブラウザでアクセスする URL を記入してください。外部からアクセスする場合は CONTROL_PANEL_HOST=0.0.0.0 を設定します。
本プロジェクトは GitHub Actions を使用して、Tailscale 経由で自宅サーバーへ自動デプロイできます。
mainブランチへの push で自動デプロイ- 機密情報は GitHub Secrets で安全に管理(6項目のみ)
- 非機密設定は
.env.exampleファイルでリポジトリ管理 - Tailscale ネットワーク経由で安全に転送
- バックエンドとフロントエンドの自動ビルド・再起動
詳細な手順については GitHub Actions デプロイガイド を参照してください。
概要:
- Tailscale OAuth Client を作成
- Tailscale SSH を有効化
- GitHub Secrets を設定(デプロイ設定 + 環境変数)
mainブランチに push
デプロイ後、サーバー上で自動的に以下が実行されます:
- 既存プロセスの停止
- Python 依存関係のインストール
- Control Panel のビルド
- バックエンドとフロントエンドの起動