reBot Arm B601-DM Digital Twin & Control Stack

Three.js 可視化 · URDF ロード · rosbridge ブリッジ · LLM/MCP 制御

このガイドは開発者向けです。reBot Arm B601-DM Digital Twin & Control Stack における reBotArm_simulator-DM Web コンソールの実行方法と拡張方法を説明します。このコンソールは軽量な Node.js + Three.js フロントエンドで、同一リポジトリ内の ROS2 ワークスペースから URDF と STL メッシュを読み込み、ブラウザ上で reBot Arm B601-DM の 6 自由度ボディとグリッパをレンダリングし、rosbridge WebSocket 経由で ROS2 と通信します。ジョイントミラーリング、制御ロック、重力補償、ビジュアルグラスピング、LLM テキスト制御まで、開発ワークフロー全体をサポートします。

Star on GitHub4.2K

注記

このガイドでは ROS2 バックエンドとして Ubuntu 24.04 + ROS2 Jazzy を使用します。Web フロントエンドは Windows、macOS、Linux 上の任意のモダンブラウザで動作します。ROS2 Humble / Ubuntu 22.04 でも同じワークフローに従うことができます。

プロジェクトの特長

ビルド不要のフロントエンド
Webpack や Vite などのバンドラに依存しません。すべてのフロントエンドアセットは、Node.js の静的サーバーによって直接配信されるプレーンな HTML/CSS/JS であり、デプロイとデバッグのコストを非常に低く抑えます。
URDF + STL の直接ロード
URDFLoader は、同一リポジトリ内の reBotArm_ros2_DM ワークスペースにある src/rebotarm_bringup/description/ から ReBot_Arm_DM.urdf と STL メッシュを読み込むため、ボディモデルを Web ディレクトリ側に二重管理する必要がありません。この URDF には完全なグリッパ定義が含まれています。Web レンダリング時には、end_link 配下の元のグリッパビジュアルを非表示にし、split_meshes/grouped_gripper/ から最適化済みの 4 つのグリッパ STL メッシュをロードします。
双方向 rosbridge ブリッジ
ReBotRosClient は rosbridge の JSON プロトコルをラップし、ジョイント状態、グリッパ状態、アームステータス、仮想カメラ画像、ビジョン検出結果を購読し、単一ジョイントコマンド、グリッパコマンド、ターゲットポーズをパブリッシュします。
LLM/MCP テキスト制御
Web ページは ROS を直接呼び出しません。代わりに、Node.js サーバーをプロキシとして VM 上で動作するテキストエージェント HTTP サービスへ転送し、MCP Server が自然言語のインテントを制約して構造化されたロボット操作に変換します。
ワンクリックインストールと統合起動
setup.sh はシステム依存パッケージのインストール、SDK のクローン、Python 仮想環境の作成、依存関係のインストール、colcon build の実行を自動で行います。統合エントリポイント rebotarm は、start web / dm / sim、doctor、status、stop などのコマンドを提供します。これは冪等であり、すでに存在して要件を満たしているコンポーネントは自動的にスキップされます。

配線とネットワークに関する注意

Web シミュレータ自体はハードウェアに直接接続しません。すべての制御コマンドは rosbridge を介して ROS2 に転送されます。次の 2 点を確認してください：

Ubuntu ホスト側: USB2CAN シリアルブリッジがアームの CAN バスに接続されており、グリッパモーターも同じ CAN バス上にあり、24V 電源が接続されていること。ホストがシリアルポートを認識しているか確認します：

ls /dev/ttyACM*

期待される出力

/dev/ttyACM0

/dev/ttyACM0（または ttyACM1 など）が表示されていれば、シリアルポートが認識されています。

Web ホスト側: Ubuntu ホストの rosbridge ポート（デフォルトは 9090）に到達できることを確認します。Web ホスト側のブラウザまたはターミナルから WebSocket 接続をテストします。例：

# Confirm the Ubuntu host IP is reachable
ping <Ubuntu IP>

# Confirm the rosbridge port is open (rosbridge must already be running on Ubuntu)
curl -i http://<Ubuntu IP>:9090

シリアルポートの権限を一時的に開放する必要がある場合（Ubuntu 側）：

sudo chmod 666 /dev/ttyACM0

より良い方法は、現在のユーザーを dialout グループに追加することで、再ログイン後に有効になります：

sudo usermod -a -G dialout $USER

動作環境要件

項目	推奨
オペレーティングシステム（バックエンド）	Ubuntu 24.04。Ubuntu 22.04 も動作可
ROS2	Jazzy。Humble も動作可
Python	システム Python、Jazzy では 3.12
Node.js	18 以上
ブラウザ	Chrome / Edge 90+、Firefox 90+、Safari 14+
MuJoCo（任意）	3.10+。完全な物理シミュレーションスタックにのみ必要

インストール手順

ステップ 0. アームの基本セットアップを完了する

Step 0

Web シミュレータ開発を始める前に、reBot Arm B601-DM クイックスタートの手順（アームの組み立て、モーター ID 設定、ゼロ点初期化、基本的な接続確認など）を完了してください。

このプロジェクトリポジトリには、Web シミュレータに必要な ROS2 ワークスペース、URDF、STL メッシュがすでに含まれています。reBot Arm B601-DM ROS2 Integration ガイドに従って別のワークスペースを構築する必要はありません。

ヒント

reBotArm_control_py は、実機ドライバ、逆運動学、動力学計算、重力補償を提供する中核の外部依存コンポーネントです。Web シミュレータ自体はこの SDK を直接インポートしませんが、ROS2 バックエンド上の実機ノード rebotarmcontroller、MuJoCo トルクロープ、重力補償機能はすべてこれに依存しています。Fake Driver + Web の純粋なシミュレーションモードのみを実行する場合は SDK は不要ですが、実機を制御したり重力補償を使用したりする場合は必須です。

setup.sh は reBotArm_control_py から SDK を自動取得し、~/ReBot_Arm_DigitalTwin_DM/reBotArm_ros2_DM/third_party/reBotArm_control_py/ にインストールします（検証済みコミットに固定）。すでに ~/reBotArm_control_py/ が存在する場合は自動的に検出され、再クローンは行われません。

インストール後のディレクトリ構成：

reBotArm_control_py/
├─ reBotArm_control_py/
│  ├─ actuator/          RebotArm class, JointGroup, motor control
│  ├─ controllers/       RebotArmEndPose (trajectory, IK, gravity compensation)
│  ├─ kinematics/        forward/inverse kinematics, load_robot_model, pad_q_for_model
│  └─ dynamics/          dynamics functions such as compute_generalized_gravity
├─ config/
│  └─ rebotarm_dm.yaml   DM motor config (ID, baud rate, limits, PID)
├─ urdf/                 Pinocchio dynamics model URDF
└─ pyproject.toml

SDK の pyproject.toml では requires-python >=3.10,<3.12 が宣言されていますが、このプロジェクトでは pip インストールではなく sys.path 経由で参照するため、Python 3.12 でも問題なく動作します。pip install -e . でバージョン競合が報告された場合は、そのステップをスキップし、ディレクトリが reBotArm_ros2_DM/third_party/reBotArm_control_py/ または ~/reBotArm_control_py/ に存在することだけ確認してください（コードはこれらのパスを自動的に探索します）。

ステップ 1. ワンクリックインストール

Step 1

git clone https://github.com/Yang-Ci/ReBot_Arm_DigitalTwin_DM.git ~/ReBot_Arm_DigitalTwin_DM
cd ~/ReBot_Arm_DigitalTwin_DM

リポジトリルートにある setup.sh は冪等であり、環境全体を自動的にセットアップします：

不足している apt システムパッケージ（ROS 2、Node.js、ros-dev-tools など）をインストール
reBotArm_control_py SDK を third_party/ にクローン（すでに存在する場合はスキップ）
Python 仮想環境（reBotArm_ros2_DM/.venv、--system-site-packages 付き）を作成
requirements.txt から Python 依存パッケージをインストール
Web 用 .env を .env.example から作成
rosdep による依存関係解決と colcon build --symlink-install の実行

./setup.sh

インストーラは冪等であり、すでに存在して要件を満たしているコンポーネントはスキップされ、既存の SDK、仮想環境、Web の .env を削除することはありません。不足している項目のみがインストールされます。最後に、インストール済み、スキップ、バージョン不一致、失敗した項目のサマリを表示します。

システムを変更せずにチェックのみを行う場合：

./setup.sh --check

インストール後、環境が準備完了していることを確認するために診断を実行します：

./rebotarm doctor

期待される出力（概要）

[rebotarm-setup] Checking supported platform
[rebotarm-setup] Checking runtime versions
[rebotarm-setup] Checking reBotArm_control_py SDK
[rebotarm-setup] Checking project virtual environment
[rebotarm-setup] Checking web configuration
[rebotarm-setup] Resolving ROS dependencies and building the workspace

Installed/updated (6)
  - apt nodejs
  - SDK ...
  - virtual environment ...
  - Python requirements checked/updated in project venv
  - created .env from example
  - ROS workspace built with colcon

Already usable; skipped (5)
  - Ubuntu 24.04 supported
  - Python 3.12.3 compatible
  - Node.js v18.19.0 compatible
  - existing SDK preserved
  - critical Python and SDK imports pass

Setup complete. Next:
  ./rebotarm doctor
  ./rebotarm start web
  ./rebotarm start dm

Setup complete メッセージが表示され、Failed or still missing セクションが空であれば成功です。

注記

もし setup.sh が自動的に ROS 2 をインストールしない場合（たとえば ROS の apt ソースがまだシステムに追加されていない場合）、インストーラは自動的に GitHub から公式の ros2-apt-source パッケージをダウンロードしてソースを追加し、再試行します。apt ソースを手動で設定する必要はありません。

ステップ 2. 環境変数を設定する

ステップ 2

setup.sh はすでに .env.example から .env を作成しています。ポートやプロキシの接続先を変更するには、.env を編集します：

# reBotArm_simulator-DM/.env key fields
PORT=3001
REBOTARM_TEXT_AGENT_URL=http://localhost:8082
REBOTARM_MCP_URL=http://localhost:8081/mcp

Web ページが Windows 上で動作し、ROS2 が Ubuntu VM 内で動作している場合は、REBOTARM_TEXT_AGENT_URL と REBOTARM_MCP_URL を Ubuntu VM の実際の IP に変更します（例：http://<Ubuntu IP>:8082）。

ステップ 3. Web サーバーを起動する

ステップ 3

cd ~/ReBot_Arm_DigitalTwin_DM
./rebotarm start web

このコマンドは ROS2 環境を自動で source し、rosbridge（ポートがすでに使用中の場合は既存のリスナーを再利用）と Node.js Web サーバーを起動します。起動後、ターミナルにアクセス用 URL が表示されます：

ROS WebSocket: ws://localhost:9090 (started by this command)
Web: http://localhost:3001
Ctrl+C stops processes started by this command.

ブラウザで http://localhost:3001 を開き、URDF と STL の読み込みが完了するまで待ちます。3D モデルが表示されればフロントエンドは正常に動作しています。このページはデフォルトでローカルの rosbridge に接続されているため、「ROS2 Bridge」パネルから直接操作できます。

注記

もし rosbridge を起動せずに純粋な Web デモだけを実行したい場合は、Web ディレクトリから手動で起動することもできます：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_simulator-DM
node server.js

この場合、ページ上ではジョイントスライダーのドラッグ、ポーズプリセット、TCP ドラッグが利用できますが、いかなる ROS ノードにも接続されません。

プロジェクトの起動

注記

./rebotarm コマンドは内部で環境を source するため、source scripts/source_rebotarm_env.sh を手動で実行する必要はありません。ただし、素の ros2 コマンドを直接実行する場合は、新しいターミナルごとに事前に source する必要があります。

純粋な Web デモ
Fake Driver シミュレーション
完全な物理シミュレーション
実機ロボット制御

最も軽量な実行方法です：Web サーバーのみを起動し、ROS2 との接続は行いません。ポーズのデモ、ティーチング、UI 開発に適しています：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_simulator-DM
node server.js

ブラウザで http://localhost:3001 を開きます。ジョイントスライダーのドラッグ、ポーズプリセット、TCP ドラッグ、ティーチ＆レコードが利用できますが、すべての操作は 3D モデルのみに影響し、ハードウェアや ROS ノードは一切駆動されません。

Web シミュレータのインターフェース

Fake Driver、rosbridge、Web サーバーを起動します。Web ページは rosbridge を通じてジョイント状態をミラーし、制御コマンドを送信します。インターフェース、ジョイント方向、リミットの検証に適しています。

ターミナル 1 — Fake Driver を起動：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_ros2_DM
source scripts/source_rebotarm_env.sh
ros2 launch rebotarm_bringup fake_bringup.launch.py

ターミナル 2 — rosbridge + Web を起動（1 コマンド）：

cd ~/ReBot_Arm_DigitalTwin_DM
./rebotarm start web

ページが ws://localhost:9090 に接続したら、「Mirror real joint state to the web」にチェックを入れると Fake Driver のジョイント状態が 3D モデルに同期されます。「Allow the web to send control to the real arm」にチェックを入れると、ジョイントスライダーと Pose モーションが rosbridge を通じてコマンドを送信します。

RViz モデルの可視化

1 つのコマンドで、Fake Driver、MuJoCo 物理グラスプ、タスクサーバー、仮想カメラ、色検出器、rosbridge を含むフルスタックを起動します：

cd ~/ReBot_Arm_DigitalTwin_DM
./rebotarm start sim

期待される出力

[rebot-mujoco-all] starting fake_bringup...
[rebot-mujoco-all] starting mujoco_physics_grasp...
[rebot-mujoco-all] starting sim_task_server...
[rebot-mujoco-all] starting sim_rgb_camera...
[rebot-mujoco-all] starting sim_color_detector...
[rebot-mujoco-all] starting rosbridge_websocket on :9090...

すべてのノードが順番に起動し、ERROR が出なければ成功です。

このスクリプトは内部的には reBotArm_ros2_DM/scripts/start_rebot_mujoco_all.sh と同等です。デフォルトでは Fake Driver、robot_state_publisher、MuJoCo 物理グラスプ、タスクサーバー、オーバーヘッド RGB カメラ、色検出器、rosbridge を起動します。その後、別のターミナルで ./rebotarm start web を実行して Web ページを起動します。ブラウザが ROS に接続したら、ビジュアルグラスピングのデモを利用できます。

MuJoCo 物理シミュレーション

実機モードでは、実機の bringup/ドライバと rosbridge を起動し、Web ページは同じ ROS インターフェースを通じて制御します。実機に切り替える前に、まず Fake Driver でインターフェース、ジョイント方向、リミットを低速で検証することを推奨します：

# Before starting, confirm the device node and grant permissions
ls /dev/ttyACM0
sudo chmod 666 /dev/ttyACM0

# Start the real-robot driver (auto-sources the environment)
cd ~/ReBot_Arm_DigitalTwin_DM
./rebotarm start dm

別のターミナルで、rosbridge + Web を起動します：

cd ~/ReBot_Arm_DigitalTwin_DM
./rebotarm start web

警告

実機コントローラに接続されている場合、Web からのコマンドは実際のハードウェアを駆動します。必ず先に Fake Driver でジョイント方向とリミットを検証してください。実機を初めて使用する際は、末端ジョイントを小さな動きでテストしてください。異常があれば直ちに「Disable」をクリックするか、制御ロックを解除してください。Web 上のチェックボックスだけに頼らず、現場には必ず非常停止、リミット、および作業空間の隔離を用意してください。

プロジェクトアーキテクチャ

ReBot_Arm_DigitalTwin_DM/
├─ setup.sh                         Idempotent one-click install and version check
├─ rebotarm                         Unified entry for start, stop, status, and diagnostics
├─ requirements.txt                 Python dependency version ranges
├─ PROJECT_ARCHITECTURE_ZH.md       Overall architecture, simulation principles, and debouncing notes
├─ reBotArm_ros2_DM/                ROS 2 workspace
│  ├─ scripts/                      One-click launch scripts and environment loading
│  ├─ third_party/                  reBotArm_control_py SDK for fresh installs
│  ├─ .venv/                        Project Python virtual environment (created by setup.sh)
│  └─ src/
│     ├─ rebotarm_msgs/             Custom msg/srv/action
│     ├─ rebotarmcontroller/        Real-robot driver, Fake Driver, hardware management
│     ├─ rebotarm_bringup/          URDF, STL, launch, motor config
│     ├─ rebotarm_mujoco/           MuJoCo simulation, IK, camera, vision
│     ├─ rebotarm_agent/            MCP Server and text agent
│     ├─ rebotarm_moveit_config/    MoveIt 2 configuration
│     └─ rebotarm_moveit_demos/     MoveIt 2 application demos
└─ reBotArm_simulator-DM/           Node.js + Three.js web console
   ├─ public/                       Pages, styles, front-end logic
   └─ split_meshes/grouped_gripper/ Web gripper meshes

データフロー：ブラウザは HTTP /api を介して Node.js の静的サーバーにアクセスし、rosbridge WebSocket を通じて ROS2 と双方向通信を行います。自然言語は Node.js によって Text Agent / MCP Server へプロキシされ、構造化されたツール呼び出しに変換されて ROS2 に入ります。ROS2 は Fake/実機ドライバとアームを下流側に駆動し、MuJoCo 物理シミュレーション、タスクサーバー、仮想カメラと横方向に接続します。Web ページ、LLM Agent、実機ロボットは互いへの呼び出しをハードコードしておらず、ROS2 のトピック、サービス、アクションによって疎結合化されています。

rebotarm の統一エントリポイントが、このプロジェクトを操作する主な方法です：

コマンド	説明
`./rebotarm start web`	rosbridge + Web サーバーを起動（環境を自動で source）
`./rebotarm start dm`	DM 実機ロボットドライバを起動（別ターミナル、環境を自動で source）
`./rebotarm start sim`	フル MuJoCo シミュレーションスタックを起動（実機ロボットと同時起動しないこと）
`./rebotarm doctor`	診断チェック（`./setup.sh --check` と同等）
`./rebotarm status`	プロセス、ポート、シリアルポート、ROS ノードの状態を表示
`./rebotarm stop`	`start web` によって管理されているバックグラウンドプロセスを停止

注記

すべての ./rebotarm コマンドは内部で source scripts/source_rebotarm_env.sh を実行するため、環境を手動で読み込む必要はありません。ただし、（起動ファイルを手動で立ち上げるなどして）素の ros2 コマンドを直接実行する場合は、事前に source する必要があります：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_ros2_DM
source scripts/source_rebotarm_env.sh

このスクリプトは、順に ROS2（/opt/ros/jazzy/setup.bash）、Python venv（.venv/bin/activate）、cmeel のパス（Pinocchio の C 拡張）、およびワークスペース（install/setup.bash）を読み込みます。

コアモジュールに関する注意（クリックして展開）

server.js — Node.js スタティックサーバー

server.js は依存関係ゼロの Node.js HTTP サーバーです。主な役割は次のとおりです：

public/ 配下の静的フロントエンドアセットを配信する；
同一リポジトリ内の ROS2 ワークスペースから URDF と STL メッシュを読み込み、/api/urdf および /api/description/meshes/<file> エンドポイントとして公開する；
Web 専用のグリッパーメッシュ /api/gripper_meshes/<file>（split_meshes/grouped_gripper/ から）を配信する；
LLM チャットリクエスト /api/llm/chat とヘルスチェック /api/llm/health を VM 内の text-agent HTTP サービスへプロキシする；
MCP 設定エンドポイント /api/mcp/config を提供し、textAgentUrl と mcpUrl を返す。

主要なパス解決（server.js）：

const BRINGUP_DIR = path.resolve(
  path.join(ROOT, '..', 'reBotArm_ros2_DM', 'src', 'rebotarm_bringup')
);
const URDF_FILE = path.join(BRINGUP_DIR, 'description', 'urdf', 'ReBot_Arm_DM.urdf');
const MESHES_DIR = path.join(BRINGUP_DIR, 'description', 'meshes');
const GRIPPER_MESHES_DIR = path.join(ROOT, 'split_meshes', 'grouped_gripper');

注記

server.js は相対パス ../reBotArm_ros2_DM/... を通じて ROS2 ワークスペースを見つけます。web ディレクトリを別の場所に移動した場合は、これらのパスをそれに合わせて更新するか、ROS2 ワークスペースと同じバージョンのモデルコピーを web ディレクトリ内に保持する必要があります。

rebot-sim.js — 3D シーンコア

rebot-sim.js はフロントエンドのコア（約 1700 行）で、次の責務を持ちます：

Three.js のシーン、カメラ、レンダラー、およびカスタムオービットコントローラーの初期化；
URDFLoader を通じて URDF を読み込み；loader.packages は package://rebotarm_bringup を ${origin}/api にマッピングし、メッシュ要求が Node.js エンドポイントを経由するようにする；
Web 専用のグリッパービジュアルグループ（4 つの STL）を end_link にアタッチし、駆動範囲を 0〜90mm とする；
DLS（damped least squares）逆運動学ソルバー IKSolver を実装し、TCP ドラッグと目標姿勢の解をサポートする；
姿勢プリセット、関節スライダー、TCP ドラッグ、ティーチングの記録／再生／エクスポート、到達可能領域推定、およびターゲットゴーストを提供する；
window.reBotSim オブジェクトを通じて API を公開し、rebot-ros-ui.js から呼び出せるようにする。

関節定義（rebot-sim.js）：

const jointDefs = [
  { name: 'joint1', label: 'J1 base yaw',    min: -2.8,  max: 2.8,  home: 0 },
  { name: 'joint2', label: 'J2 shoulder',     min: -3.14, max: 0,    home: 0 },
  { name: 'joint3', label: 'J3 elbow',       min: -3.14, max: 0,    home: 0 },
  { name: 'joint4', label: 'J4 wrist pitch', min: -1.87, max: 1.57, home: 0 },
  { name: 'joint5', label: 'J5 wrist yaw',   min: -1.57, max: 1.57, home: 0 },
  { name: 'joint6', label: 'J6 tool roll',   min: -3.14, max: 3.14, home: 0 },
  { name: 'gripper', label: 'J7 gripper', min: 0, max: 0.09, home: 0, unit: 'm' }
];

注記

Web の Three.js 座標系は ROS の座標系と異なります。Three.js はデフォルトで Y-up、ROS はデフォルトで Z-up です。rebot-sim.js は threeToRos(v) によって { x: v.x, y: -v.z, z: v.y } という変換を行います。カスタム姿勢機能を開発する際は必ずこの変換を使用してください。そうしないと座標が誤ってしまいます。

rebot-ros-client.js — rosbridge クライアント

ReBotRosClient は EventTarget を継承し、rosbridge v2 JSON プロトコルをラップして次の機能を提供します：

connect(url) / disconnect(): WebSocket 接続管理（自動再接続（autoReconnect, reconnectDelay）付き）；
subscribe(topic, type, callback, options): トピック購読（throttleRate によるスロットリングをサポート）；
callService(service, type, args): サービスを呼び出し、Promise を返す；
sendActionGoal(actionName, actionType, goal): /_action/send_goal を通じてアクションを呼び出す；
高レベルラッパー：enable(), disable(), safeHome(), startGravityCompensation(), setGripper(), moveToPose(), solveMoveToPoseIK(), followJointTrajectory()；
パブリッシュ用ラッパー：publishJointCommand(), publishGripperCommand(), publishTargetPose()。

デフォルトのネームスペースは rebotarm で、すべてのトピック／サービスパスは /rebotarm/ で始まります。

rebot-ros-ui.js — ROS コントロールパネル

rebot-ros-ui.js（約 1500 行）は、ReBotRosClient と reBotSim をつなぐビジネスレイヤーで、次の責務を持ちます：

関節状態、グリッパー状態、アームステータス、仮想カメラ画像、ビジョン検出結果、およびシミュレーションアニメーションイベントの購読；
「実機の関節状態を Web にミラーする」と「Web から実機アームへの制御送信を許可する」という 2 つのスイッチの実装；
関節コマンドのスロットリング（COMMAND_INTERVAL_MS = 45ms）とミラーホールド（MIRROR_HOLD_MS = 1800ms）；
重力補償の開始／停止およびステータス問い合わせ；
グリッパー制御と到達待ち（commandGripperAndWait）；
IK チェック、姿勢モーション、軌道送信、およびローレベル再生フォールバック；
完全なビジュアル把持フロー（退避、整列、事前下降、下降、把持、持ち上げ、移動）；
シミュレーションアニメーションイベント（attach_object / release_object）により、Web グリッパーがオブジェクトに追従するよう駆動する。

コントロールロックは誤操作を防ぐための重要なセーフガードです。controlAllowed() は一元的にチェックを行い、ROS が接続されていない場合やコントロールロックがチェックされていない場合には、すべての制御コマンドを遮断し、ページは 3D モデルのみを更新します。

rebot-llm.js — LLM テキスト制御 UI

rebot-llm.js は自然言語チャットインターフェースを実装します。チェーンは次のとおりです：

web rebot-llm.js
  -> Node.js /api/llm/chat
  -> Text Agent HTTP service (default :8082)
  -> MCP Server (default :8081/mcp)
  -> ROS 2 service/action/topic

起動時にはまず /api/llm/health を呼び出して text-agent のヘルスチェックを行い、成功後に入力ボックスを有効化します。メッセージは /api/llm/chat を通じて text-agent にプロキシされ、返ってきた text と events（ツール呼び出しプロセス）がチャットエリアにレンダリングされます。停止時には { text: '__reset__', reset: true } を送信してコンテキストをクリアします。

ROS2 インターフェース概要（クリックして展開）

Web シミュレータが購読およびパブリッシュする主要な ROS2 インターフェースを以下に示します。デフォルトのネームスペースは rebotarm です。

購読トピック

Topic	Type	Description
`/rebotarm/joint_states`	`sensor_msgs/msg/JointState`	6 関節＋グリッパーのリアルタイム位置
`/rebotarm/gripper/state`	`rebotarm_msgs/msg/JointMotorState`	グリッパーの位置／速度／トルク
`/rebotarm/arm_status`	`rebotarm_msgs/msg/ArmStatus`	イネーブル状態、モード、ステートマシン
`/rebotarm/mujoco/overhead_rgb/image_raw`	`sensor_msgs/msg/Image`	デスクトップ俯瞰 RGB カメラ画像
`/rebotarm/vision/color_blocks/detections`	`std_msgs/msg/String`	カラーブロック検出結果（JSON）
`/rebotarm/sim/animation_event`	`std_msgs/msg/String`	シミュレーションアニメーションイベント（把持／解放）

パブリッシュトピック

Topic	Type	Description
`/rebotarm/joints/<jointN>/cmd`	`rebotarm_msgs/msg/JointMotorCmd`	単一関節のスパースコマンド（mode=1 POS_VEL）
`/rebotarm/gripper/cmd`	`rebotarm_msgs/msg/JointMotorCmd`	グリッパーコマンド（m, 0〜0.09）
`/rebotarm/mujoco/target_pose`	`geometry_msgs/msg/PoseStamped`	TCP ドラッグの目標姿勢

呼び出されるサービス

Service	Type	Description
`/rebotarm/enable`	`std_srvs/srv/Trigger`	すべてのモーターを有効化
`/rebotarm/disable`	`std_srvs/srv/Trigger`	すべてのモーターを無効化
`/rebotarm/safe_home`	`std_srvs/srv/Trigger`	安全な原点復帰
`/rebotarm/gravity_compensation/start`	`std_srvs/srv/Trigger`	重力補償の開始
`/rebotarm/gravity_compensation/stop`	`std_srvs/srv/Trigger`	重力補償の停止
`/rebotarm/gravity_compensation/status`	`std_srvs/srv/Trigger`	重力補償ステータスの問い合わせ
`/rebotarm/gripper/set`	`rebotarm_msgs/srv/SetGripper`	グリッパー到達サービス
`/rebotarm/move_to_pose_ik`	`rebotarm_msgs/srv/MoveToPoseIK`	IK 解サービス
`/rosapi/topics`	`rosapi_msgs/srv/Topics`	診断：すべてのトピックを列挙
`/rosapi/services`	`rosapi_msgs/srv/Services`	診断：すべてのサービスを列挙

呼び出されるアクション

Action	Type	Description
`/rebotarm/move_to_pose`	`rebotarm_msgs/action/MoveToPose`	デカルト姿勢モーション
`/rebotarm/follow_joint_trajectory`	`control_msgs/action/FollowJointTrajectory`	関節軌道の実行

注記

ROS2 環境内で FollowJointTrajectory または MoveToPose の _action/send_goal サービスが見つからない場合、Web ページは自動的に「ローレベル再生」モードにフォールバックします：軌道ポイントのタイムスタンプに従って単一関節コマンドをポイントごとにパブリッシュし、3D モデル側でも補間を同期します。これにより、Fake Driver だけの最小環境でも、Web ページは軌道をデモンストレーションできます。

グリッパーの単位と座標系の取り決め

Web と ROS のインターフェースでは、グリッパーの単位として メートル を使用します：

close: 0.00 m
open:  0.09 m

モーターファームウェアは ラジアン（0.0 = 閉、−5.0 = 開）を使用します。変換は ROS2 コントローラーの HardwareManager 内で行われ、Web ページはラジアンを直接扱いません。

URDF では、finger_left / finger_right はリミット 0~0.0285（m）を持つプリズマティックジョイントです。Web ページは fingerOpeningToGripperCommand() を通じて、finger_left の開き量を 0〜0.09 m のグリッパーコマンド範囲にマッピングします。

座標フレームについて、Web の Three.js はデフォルトで Y-up、ROS はデフォルトで Z-up です。すべての TCP 姿勢は ROS に publish される前に threeToRos() で変換されます：

function threeToRos(v) {
  return { x: v.x, y: -v.z, z: v.y };
}

LLM/MCP テキスト制御

自然言語による制御は、ブラウザから ROS へ直接呼び出されるのではなく、Node.js を経由してプロキシされます。レイヤー化された設計により、LLM が意図を理解しつつ、MCP レイヤーがその意図を構造化されたロボット操作へと制約します。

MCP サーバーとテキストエージェントの起動

Ubuntu VM で MCP サーバーを起動します（デフォルトはロックモードで読み取り専用）：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_ros2_DM
source scripts/source_rebotarm_env.sh
ros2 launch rebotarm_agent rebotarm_mcp.launch.py

シミュレーションモーションモード（動作許可）：

ros2 launch rebotarm_agent rebotarm_mcp.launch.py motion_mode:=allow

テキストエージェントの HTTP サービスを起動します（Web ページから呼び出すため）：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_ros2_DM
./scripts/start_rebotarm_text_agent_http.sh

期待される出力

[rebotarm-text-agent-http] MCP=http://127.0.0.1:8081/mcp
[rebotarm-text-agent-http] model=qwen-plus
INFO:     Uvicorn running on http://0.0.0.0:8082

Uvicorn running on http://0.0.0.0:8082 が表示されたら準備完了です。

デフォルトでは 0.0.0.0:8082 で待ち受け、MCP は http://127.0.0.1:8081/mcp を指し、LLM はデフォルトで qwen-plus を使用します。

Web での利用方法

Web ページの「LLM text control」パネルで「Start AI assistant」をクリックします。ページはまずテキストエージェントのヘルスチェックを行い、成功すると入力ボックスが有効になります。自然言語コマンドを直接入力できます。例えば：

アームの状態を問い合わせる
X=0.3 Y=0 Z=0.3 に移動
グリッパーを開く
赤いブロックをつかむ

テキストエージェントの応答とツール呼び出しの処理は、チャットエリアに表示されます。

プロキシ先の設定

Web ページは .env 内の REBOTARM_TEXT_AGENT_URL と REBOTARM_MCP_URL を通じてバックエンドを特定します。Web ページが Windows 上で動作し、ROS2 が Ubuntu VM で動作している場合は、これらを VM の実際の IP に変更します：

REBOTARM_TEXT_AGENT_URL=http://<Ubuntu IP>:8082
REBOTARM_MCP_URL=http://<Ubuntu IP>:8081/mcp

変更後、./rebotarm start web（または node server.js）を再起動します。起動時にページは /api/mcp/config から現在のプロキシバックエンドを読み込み、表示します。

MCP Dashboard 可視化パネル

MCP Dashboard は独立したデバッグ用エントリであり、Web シミュレータを必要としません。起動手順は 2 ステップです：

ターミナル 1 — MCP サーバーを起動：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_ros2_DM
source scripts/source_rebotarm_env.sh
ros2 launch rebotarm_agent rebotarm_mcp.launch.py motion_mode:=allow

ターミナル 2 — テキストエージェントを起動（MCP Dashboard を含む）：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_ros2_DM
./scripts/start_rebotarm_text_agent_http.sh

ブラウザでアクセス：

http://localhost:8082/

ブラウザで http://<Ubuntu IP>:8082/ を開くとアクセスできます。追加のインストールは不要です。

機能：

ツール概要：MCP サーバーから登録済みツールをすべて自動取得し、カテゴリ（ステータス & 診断、有効化制御、モーション制御、グリッパー制御、重力補償、ビジュアルグラスピング、記録 & 再生）ごとにグループ化します；
検索フィルター：上部の検索ボックスでツール名と説明をリアルタイムにフィルタリングします；
パラメータフォーム：各ツールの inputSchema に基づいて入力ボックスを自動生成します。パラメータを入力し、「Call」をクリックすると対応する MCP ツールを直接呼び出します；
モーションタグ：motion_mode=allow を必要とするツールには「Motion」ラベルが付与されます；
カスタムツール登録：「Register new tool」ボタンをクリックし、ツール名、説明、カテゴリ、Webhook URL、パラメータ Schema（JSON）を入力して、カスタムツールをパネルに追加します。呼び出し時には、パラメータが JSON として Webhook URL に POST されます；
CN/EN 切り替え：右上の言語ボタンで CN/EN インターフェースをワンクリックで切り替えできます。選択はブラウザの localStorage に保存されます；
自然言語入力：右側のチャットボックスに自然言語コマンドを入力すると、LLM → MCP チェーンを通じて /chat エンドポイントに送られ、応答とツール呼び出しの処理がログエリアにリアルタイム表示されます。

ヒント

MCP Dashboard は独立したデバッグ用エントリであり、Web シミュレータに依存しません。MCP サーバー（:8081）とテキストエージェント（:8082）が動作していれば、http://<Ubuntu IP>:8082/ を開くだけで、18 個すべての MCP ツールを閲覧・呼び出しできます。

エンドポイント概要：

エンドポイント	メソッド	説明
`/` または `/dashboard`	GET	Dashboard の HTML ページを返します（ダークなガラスパネルテーマ、CN/EN 切り替え対応）
`/tools`	GET	MCP ツール一覧の JSON（名前、説明、パラメータスキーマ、カテゴリ、カスタムフラグ）を返します
`/call_tool`	POST	指定した MCP ツールを直接呼び出します。ボディ：`{"name":"...", "arguments":{...}}`
`/register_tool`	POST	カスタムツールを登録します。ボディ：`{"name":"...", "description":"...", "category":"...", "webhook_url":"...", "parameters":{...}}`
`/unregister_tool`	POST	登録済みカスタムツールを削除します。ボディ：`{"name":"..."}`
`/chat`	POST	自然言語での対話。ボディ：`{"text":"..."}`
`/health`	GET	ヘルスチェック

セカンダリ開発ガイド

関節リミットやプリセットの変更

関節リミットとプリセット姿勢は、rebot-sim.js の先頭にある jointDefs と presets オブジェクトで定義されています。変更後、ページをリロードすれば反映され、ビルドは不要です。関節リミットは URDF 内の <limit> と一致させる必要がある点に注意してください。一致していないと、Web モデルと ROS の挙動が一致しません。

カスタム ROS インターフェースの追加

新しいトピックを購読したり、新しいサービスを呼び出す必要がある場合は、rebot-ros-ui.js の REQUIRED_TOPICS または REQUIRED_SERVICES に追加し、ボタンイベント内で client.subscribe() または client.callService() を呼び出します。ReBotRosClient はすでに rosbridge プロトコルをラップしているため、WebSocket 通信を手書きする必要はありません。

LLM ツールの拡張

LLM ツールは rebotarm_agent の MCP サーバーによって定義されています。新しいツールを追加するには、ROS2 ワークスペース内の rebotarm_agent パッケージに実装を追加します。ビルドし直すと、テキストエージェントが自動的にそれを公開します。Web 側の変更は不要で、ツール呼び出しの処理は /api/llm/chat の events フィールドを通じて返され、レンダリングされます。

Web グリッパーメッシュの変更

Web 専用のグリッパー STL は split_meshes/grouped_gripper/ にあり、gripper_base.stl、gripper_hardware.stl、left_finger.stl、right_finger.stl が含まれます。これらのファイルを置き換えてページをリロードしてください。Web ディレクトリ内に 2 つ目の urdf/ や meshes/ のコピーを追加しないでください。実行時に使用されるのはこれら 4 つのグリッパー STL のみです。

rosbridge 接続アドレスの変更

rosbridge の WebSocket アドレスは、Web ページの「ROS2 Bridge」パネルでユーザーが手動入力します。デフォルトではハードコードされていません。デフォルトまたはプリセットアドレスを変更するには：

reBotArm_simulator-DM/public/js/ros/rebot-ros-client.js（クライアントのデフォルトは空で、入力ボックスから与えられます）
reBotArm_simulator-DM/public/js/ros/rebot-ros-ui.js（localStorage から最後のアドレスを読み込みます）

ページは、入力ボックスが空の場合に最後に保存されたアドレスの読み込みを試みます。デフォルトを変更するか、Web の接続パネルで実際のアドレスを直接入力してください。

主要ファイルクイックリファレンス（クリックで展開）

ファイル	用途
`reBotArm_simulator-DM/server.js`	Node.js 静的サーバー + LLM プロキシ
`reBotArm_simulator-DM/package.json`	npm スクリプト（start / dev）
`reBotArm_simulator-DM/.env`	ポートとプロキシ先の設定
`reBotArm_simulator-DM/public/index.html`	シングルページアプリのエントリとコントロールパネルレイアウト
`reBotArm_simulator-DM/public/css/rebot-sim.css`	ダークテーマのスタイル
`reBotArm_simulator-DM/public/js/rebot-sim.js`	3D シーン、IK、ティーチング、ドラッグのコア処理
`reBotArm_simulator-DM/public/js/rebot-llm.js`	LLM チャット UI
`reBotArm_simulator-DM/public/js/ros/rebot-ros-client.js`	rosbridge WebSocket クライアント
`reBotArm_simulator-DM/public/js/ros/rebot-ros-ui.js`	ROS コントロールパネル UI とビジネスロジック
`reBotArm_simulator-DM/public/lib/three-r128.min.js`	Three.js レンダリングエンジン
`reBotArm_simulator-DM/public/lib/STLLoader-umd.js`	STL メッシュローダー
`reBotArm_simulator-DM/public/lib/URDFLoader.js`	URDF パーサー
`reBotArm_simulator-DM/split_meshes/grouped_gripper/`	Web 専用グリッパー STL（4 ファイル）

FAQ

1. ブラウザを開いた後、「Loading Rebot_ARM-B601-DM arm model...」のまま変わりません

ページがローディングオーバーレイのまま止まっている場合、URDF または STL メッシュのリクエストが失敗しています。ブラウザの開発者ツールで Network パネルを開き、/api/urdf と /api/description/meshes/*.STL が 200 を返しているか確認してください。よくある原因：

server.js 内の BRINGUP_DIR パスの解決が誤っており（Web ディレクトリをモノレポ以外の場所に移動した）、src/rebotarm_bringup/description/ が見つからない；
URDF 内の package://rebotarm_bringup/... がマッピングできない；loader.packages が ${origin}/api を指していることを確認してください；
STL ファイルが欠落している、またはパスの大文字小文字が一致していない（Linux は大文字小文字を区別します）。

2. ROS に接続してもステータスが「offline」のまま

次の順番で確認してください：

Ubuntu 側で rosbridge が動作しており、0.0.0.0:9090（127.0.0.1 ではない）で待ち受けているか；
Web ホストから Ubuntu の 9090 ポートに到達できるか（ファイアウォール、VM のネットワークモード）；
WebSocket アドレスが ws:// で始まっているか（例：ws://localhost:9090）；

3. ジョイントスライダーで実機ロボットを制御できない

Web ページから実機ロボットを制御するには、3 つのアンロック手順が必要です：

「ROS2 Bridge」パネルで ROS に接続します（WebSocket を実機コントローラの rosbridge に接続）；
「Allow the web to send control to the real arm」にチェックを入れ、確認ダイアログで「OK」をクリックします；
「Enable」ボタンをクリックします。

これら3つの手順はすべて必須です。コントロールロックがチェックされていない場合、スライダーをドラッグしても3Dモデルが動くだけで、ROSコマンドは送信されません。

4. グリッパーがWebと同期しない

/rebotarm/gripper/state の position はラジアンではなくメートル（0～0.09）である必要があります。同期しない場合は、ROS2コントローラ内の ros_publishers.py が gripper_position_m() を使用しているか確認してください。Webページ側では、フォールバックのフィードバックソースとして /rebotarm/joint_states の finger_left からグリッパー開度も推定します。

5. LLMアシスタントが起動しない

Webページに「Connection failed」と表示される場合、Ubuntu VM 内で text-agent のHTTPサービスが動作しているか確認します：

cd ~/ReBot_Arm_DigitalTwin_DM/reBotArm_ros2_DM
./scripts/start_rebotarm_text_agent_http.sh

そして .env 内の REBOTARM_TEXT_AGENT_URL が、正しいVMのIPとポート（デフォルトは 8082）を指していることを確認します。ページはまず /api/llm/health を呼び出してヘルスチェックを行い、失敗した場合はメッセージエリアに具体的なエラー内容を表示します。

6. ビジュアル把持デモが動作しない

ビジュアル把持は完全な物理シミュレーションスタックに依存します。次を確認してください：

MuJoCo のオーバーヘッドRGBカメラが動作しており、/rebotarm/mujoco/overhead_rgb/image_raw に画像があるか；
カラー検出器が動作しており、/rebotarm/vision/color_blocks/detections に結果があるか；
Webカメラプレビューにフレームが表示され、色認識ステータスに「N / target X」と表示されているか；
ターゲットカラーの選択が正しいか（auto/red/yellow/blue）。

7. フロントエンドのコード変更が反映されない

フロントエンドのアセットはNode.jsによって静的に配信されます。変更後はブラウザをリロードしてください。現在のバージョンではService Workerを登録していないため、オフラインキャッシュが原因で古いバージョンが更新されないということはありません。それでもブラウザに古いコンテンツが表示される場合は、ハードリロード（Ctrl+Shift+R）を行うか、通常のキャッシュをクリアしてください。

8. "URDFLoader" または "THREE" が見つからない

これらは public/lib/ 配下のサードパーティライブラリで、index.html によって <script> タグ経由で読み込まれます。次を確認してください：

public/lib/three-r128.min.js、public/lib/URDFLoader.js、public/lib/STLLoader-umd.js が存在すること；
index.html 内の <script> タグのパスが正しく、読み込み順が Three.js → STLLoader → URDFLoader → ビジネスロジック用スクリプトになっていること；
ブラウザコンソールに404や読み込み順序のエラーが出ていないこと。

9. `setup.sh` がエラーを報告する、またはインストールに失敗する

setup.sh は冪等であり、失敗したコンポーネントは最後のサマリーの Failed or still missing に一覧表示されます。よくあるケース：

ROS aptソースが設定されていない：インストーラは自動的に ros2-apt-source パッケージをダウンロードしてソースを追加しますが、これにはsudoが必要です；
Pythonバージョンの不一致：Jazzy には 3.12、Humble には 3.10 が必要です。不一致は Version/platform mismatches に一覧表示されます；
SDK のクローンに失敗した：ネットワークとGitHubへの到達性を確認するか、reBotArm_ros2_DM/third_party/reBotArm_control_py/ に手動でクローンしてから再実行してください；
colcon build が失敗した：rosdep が初期化されているか（sudo rosdep init && rosdep update）を確認し、その後 ./setup.sh を再実行してください。

連絡先

技術サポート：Issue を送信
プロジェクトリポジトリ：Github
フォーラム：Seeed Studio Forum

プロジェクトの特長​

配線とネットワークに関する注意​

動作環境要件​

インストール手順​

ステップ 0. アームの基本セットアップを完了する​

ステップ 1. ワンクリックインストール​

ステップ 2. 環境変数を設定する​

ステップ 3. Web サーバーを起動する​

プロジェクトの起動​

プロジェクトアーキテクチャ​

グリッパーの単位と座標系の取り決め​

LLM/MCP テキスト制御​

MCP サーバーとテキストエージェントの起動​

Web での利用方法​

プロキシ先の設定​

MCP Dashboard 可視化パネル​

セカンダリ開発ガイド​

関節リミットやプリセットの変更​

カスタム ROS インターフェースの追加​

LLM ツールの拡張​

Web グリッパーメッシュの変更​

rosbridge 接続アドレスの変更​

FAQ​

1. ブラウザを開いた後、「Loading Rebot_ARM-B601-DM arm model...」のまま変わりません​

2. ROS に接続してもステータスが「offline」のまま​

3. ジョイントスライダーで実機ロボットを制御できない​

4. グリッパーがWebと同期しない​

5. LLMアシスタントが起動しない​

6. ビジュアル把持デモが動作しない​

7. フロントエンドのコード変更が反映されない​

8. "URDFLoader" または "THREE" が見つからない​

9. setup.sh がエラーを報告する、またはインストールに失敗する​

連絡先​

参考文献​

プロジェクトの特長

配線とネットワークに関する注意

動作環境要件

インストール手順

ステップ 0. アームの基本セットアップを完了する

ステップ 1. ワンクリックインストール

ステップ 2. 環境変数を設定する

ステップ 3. Web サーバーを起動する

プロジェクトの起動

プロジェクトアーキテクチャ

グリッパーの単位と座標系の取り決め

LLM/MCP テキスト制御

MCP サーバーとテキストエージェントの起動

Web での利用方法

プロキシ先の設定

MCP Dashboard 可視化パネル

セカンダリ開発ガイド

関節リミットやプリセットの変更

カスタム ROS インターフェースの追加

LLM ツールの拡張

Web グリッパーメッシュの変更

rosbridge 接続アドレスの変更

FAQ

1. ブラウザを開いた後、「Loading Rebot_ARM-B601-DM arm model...」のまま変わりません

2. ROS に接続してもステータスが「offline」のまま

3. ジョイントスライダーで実機ロボットを制御できない

4. グリッパーがWebと同期しない

5. LLMアシスタントが起動しない

6. ビジュアル把持デモが動作しない

7. フロントエンドのコード変更が反映されない

8. "URDFLoader" または "THREE" が見つからない

9. `setup.sh` がエラーを報告する、またはインストールに失敗する

連絡先

参考文献