Skip to content

qua121/stackchan-simulator

BranchesTags

Repository files navigation

スタックチャン 動力学シミュレータ

M5Stack 卓上ロボット スタックチャン（Stack-chan / ｽﾀｯｸﾁｬﾝ）の MuJoCo 動力学シミュレータです。2 自由度（パン／チルト）の頭部モデル、質量分布、 関節可動域（ROM）、サーボのトルク／速度制限は、物理パラメータ同定レポート （リポジトリには同梱しない内部資料）に基づいています。

本プロジェクトは非公式です。 Stack-chan 本体プロジェクトおよび各権利者とは 別個に、独立して開発されています。

デフォルト構成：M5Stack CoreS3 + Feetech SCS0009（標準モデル、合計 187.2 g）。

セットアップ

uv が必要です。依存パッケージは .venv に インストールされます。

uv sync

実行方法

# Web ダッシュボード（日本語 UI）-> http://127.0.0.1:8000 が開きます
uv run python scripts/run_web_dashboard.py

# 実機互換モード: ダッシュボード(:8000) + AI_StackChan2 互換 API(:80) を同時起動
uv run python scripts/run_device_emulator.py

# パン／チルトのスライダー付きインタラクティブビューア（操作パネル）
uv run python scripts/run_gui_manual.py

# PD ステップ応答デモ -> artifacts/pd_step_response.png を保存
uv run python scripts/run_pd_demo.py --no-show

# 注視 IK：頭部が移動するターゲットを追従
uv run python scripts/run_gaze_demo.py             # ビューア表示
uv run python scripts/run_gaze_demo.py --headless  # 数値サマリのみ

# テスト
uv run pytest

上記の CLI スクリプトの出力はすべて日本語です。run_pd_demo.py はグラフの ラベルも日本語で描画します（Windows のシステム日本語フォントを使用）。各スクリプトは --profile {report,rt,cad} と --servo {SCS0009,SG90,RS304MD,XL330-M288-T} の オプションを受け付けます。

Web ダッシュボード

uv run python scripts/run_web_dashboard.py を実行すると、日本語の Web UI が 起動し、ブラウザで http://127.0.0.1:8000 が開きます。以下の機能があります。

  • three.js によるロボットのリアルタイム 3D 表示
  • スライダーによる手動パン／チルト操作
  • 注視 IK ターゲティング（ターゲットをクリック／ドラッグして頭部に追従させる）
  • サーボのストール（停動）限界を基準としたトルクゲージ付きのライブテレメトリ
  • PD ゲイン（kp／kv）の調整
  • セッションの録画・再生と CSV エクスポート

物理演算・逆運動学・制御はすべて既存の Python コード （params.py / robot.py / controller.py / ik.py / sim.py）で実行され、 ブラウザは描画のみを担当します。ダッシュボードは FastAPI + WebSocket の バックエンドでこれらのモジュールを再利用します。運動学情報は /api/model（params.py から導出）から配信され、three.js はローカルに同梱 （実行時の CDN 参照なし、MIT ライセンス）、UI には BIZ UDPGothic フォントを （システムで利用可能な場合に）指定しています。フォントファイルは同梱しません。

実機互換モード（AI_StackChan2 HTTP API）

run_device_emulator.py は、外部アプリが実機の「AIスタックチャン」と誤認して 通信できるよう、robo8080/AI_StackChan2 の受信側 HTTP API（実機はポート 80）を再現します。/face や /speech を送ると、 ブラウザ上の顔（表情・口パク）と 3D 機構にそのまま反映されます。

curl "http://127.0.0.1/speech?say=こんにちは"
curl "http://127.0.0.1/face?expression=1"   # 1=happy
エンドポイント メソッド 役割
/ , /inline GET 簡易応答
/speech?say=&voice= GET 発話（吹き出し＋口パク）
/face?expression=0-5 GET 表情（0=neutral,1=happy,2=sleepy,3=doubt,4=sad,5=angry）
/chat?text=&voice= GET 会話（任意の LLM 連携、未設定時はエコー）
/setting?volume=&speaker=&led= GET 音量・スピーカ・LED 設定
/role /role_set /role_get GET/POST/GET キャラクター設定
/apikey /apikey_set GET/POST APIキー設定

各ルートと /face のインデックス→表情の対応は、AI_StackChan2 の公開実装を 参考に、互換性確認のため本プロジェクトで独自実装したものです（実機の ソースコードやアセットは含みません）。/chat を実際の AI 応答にするには、 OpenAI 互換の LLM バックエンドを環境変数で設定します（AnythingLLM の Generic OpenAI / OpenAI / M5 LLM Module 等）。

# 任意: /chat を実応答に（OpenAI 互換エンドポイント）
$env:STACKCHAN_LLM_BASE_URL = "http://localhost:3001"   # 例: AnythingLLM
$env:STACKCHAN_LLM_API_KEY  = "..."
$env:STACKCHAN_LLM_MODEL    = "gpt-4o-mini"

顔表示・音声・AI コンポーネント

  • 顔は 3D ヘッドの本体モニターに表示されます（組み立て後の実機のように一体表示。 独立した顔パネルは廃止）。m5stack-avatar の既定フェイス（白パーツ/黒背景・塗り円の目＋自動瞬き・矩形の口・矩形の眉・呼吸・ 表情）に忠実な 320×240 オフスクリーン描画を、頭部前面のスクリーン面にテクスチャと して貼っています。m5stack-avatar のソースコードや画像アセットは含まず、概念に基づく 独自実装の近似です。
  • 視線モードを GUI で切替できます（追従＝pan/tilt 連動／サッケード＝本家風ランダム ／両立）。
  • 音声対話: 「音声を再生」で発話テキストをブラウザ読み上げ（口パク連動）、 「マイクで話す」で音声認識→応答までを実行（対応ブラウザ・ユーザ操作が必要）。
  • AI はコンポーネント化され差し替え容易です（web/ai/）。LLM は OpenAI 互換 （環境変数で設定）、TTS/STT は既定でブラウザ実装、サーバ側アダプタも追加可能。

LLM 連携に関する注意: 本プロジェクトは任意の OpenAI 互換 LLM エンドポイントに 接続できます。各 LLM サービスの利用規約・料金・データ保持ポリシーは利用者ご自身で 確認してください。API キーは環境変数で渡し、リポジトリに含めないでください。 /apikey_set で保存した値や /chat の会話内容はメモリ上に保持されます（暗号化 されません）。会話内容の取り扱いにご注意ください。

ディレクトリ構成

パス 役割
src/stackchan_sim/params.py 物理パラメータ（唯一の真実の源。レポート由来）
src/stackchan_sim/model.py params から MJCF を生成
src/stackchan_sim/robot.py MuJoCo モデルのラッパー StackchanRobot
src/stackchan_sim/controller.py サーボモデル（速度レート制限＋トルククランプ）、PD ゲイン
src/stackchan_sim/ik.py 2 自由度 注視 逆運動学（解析解）
src/stackchan_sim/sim.py ヘッドレス実行＋インタラクティブビューア補助
src/stackchan_sim/web/server.py Web ダッシュボード用 FastAPI バックエンド＋WebSocket
src/stackchan_sim/web/simloop.py 非同期シミュレーションループ、録画・再生
src/stackchan_sim/web/contract.py API／WS の共通契約（唯一の真実の源）
src/stackchan_sim/web/compat.py AI_StackChan2 互換 HTTP API
src/stackchan_sim/web/ai/ 差し替え可能な AI コンポーネント（LLM/TTS/STT 抽象）
src/stackchan_sim/web/llm.py web/ai への薄いファサード（後方互換）
src/stackchan_sim/web/static/js/face_renderer.js 本家準拠の顔描画（320×240、本体モニターに貼付）
src/stackchan_sim/web/static/js/audio.js ブラウザ音声 I/O（TTS / 音声認識）
scripts/run_device_emulator.py 実機互換モード起動（ダッシュボード＋互換API）
src/stackchan_sim/web/static/ three.js フロントエンド（同梱、実行時 CDN なし）
scripts/run_web_dashboard.py Web ダッシュボードの起動スクリプト
models/stackchan/stackchan.xml デフォルト MJCF のスナップショット（model.write_model で再生成）
models/stackchan/meshes/ STL メッシュ
artifacts/ 生成物・実行時出力の集約先（git 管理対象外。デモ png / playwright 出力など）

ライセンス

本プロジェクトのソースコード・モデル・ドキュメントは Apache License 2.0 の 下で公開します（LICENSE）。

  • 一部のモデルスケルトンおよび STL メッシュは rostack-chan 由来で、 Apache-2.0 の条件に従って再配布しています（改変あり）。詳細は NOTICE、THIRD_PARTY_NOTICES.md、 models/stackchan/NOTICE を参照してください。
  • three.js（MIT, three.js authors）を web/static/vendor/ に同梱しています。
  • 本プロジェクトは 非公式 の Stack-chan シミュレータであり、Stack-chan 本体 プロジェクトおよび各権利者とは別個に開発されています。
  • AI_StackChan2 互換 API および顔描画は、公開実装・概念を参考にした独自実装で、 それらのソースコードやアセットは含みません。

クレジット

  • 運動学スケルトン（リンク変換、関節軸）と STL メッシュ （feet_SCS0009.stl、bracket_SCS0009_marged.stl、stackchan_shell.stl）: Ar-Ray-code 氏による rostack-chan （Apache-2.0）。
  • AI_StackChan2（robo8080） — 互換 API の挙動参考。
  • m5stack-avatar（meganetaaan） — 顔表現の概念参考。

About

Unofficial MuJoCo dynamics simulator for the Stack-chan desktop robot — web dashboard, AI_StackChan2-compatible device emulator, and an on-monitor avatar face.

Topics

python threejs avatar simulator robotics mujoco pan-tilt m5stack digital-twin fastapi stackchan stack-chan

Resources

Readme

License

Apache-2.0 license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0 Latest
May 28, 2026

Packages

 
 
 

Contributors

Languages