reBot Arm B601-RS Digital Twin & Control Stack

reBot Arm B601-RS

Three.js 可視化 · ROS 2 · SocketCAN · MuJoCo シミュレーション · LLM/MCP 制御

reBot Arm B601-RS Digital Twin & Control Stack は、Three.js Web コンソール、ROS 2 実機ドライバ、RS 専用 MuJoCo ダイナミクスシーン、ビジョン検出、軌道生成と逆運動学、そしてオプションの LLM/MCP グラスピングエージェントを統合しています。本ガイドでは、フルシステムのインストール、起動、および開発方法を説明します。

Star on GitHub4.2K

プロジェクトの特長

RS 専用アームモデル

Web コンソールと ROS 2 は ReBot_Arm_RS.urdf と、それに対応する STL メッシュを使用します。Web サーバーはまず rebotarm_ros2_RS ワークスペースからモデルを読み込み、オフライン用のバックアップコピーも保持します。
RobStride + SocketCAN 実機リンク

実機はデフォルトで Linux SocketCAN インターフェース can0 を 1 Mbps で使用します。コントローラは reBotArm_control_py を通じて RobStride モータと通信します。
MIT 125 Hz オンライン制御

Web コンソールは最大 60 Hz でターゲットを更新し、実機コントローラは速度・加速度・ジャークで制限されたオンライン参照軌道を 125 Hz で生成し、MIT の q/dq/kp/kd/tau コマンドを送信します。Web のターゲット更新はモータ制御ループをブロックしません。
実機とシミュレーションの名前空間分離

実機はデフォルトで /rebotarm、シミュレーションは /rebotarm_rs を使用します。同じ Web コンソールから制御対象を切り替えることができ、実機と Fake Driver を同時に起動してインターフェースを比較できます。
RS 専用 MuJoCo シーン

MuJoCo は physics モードと kinematic モードをサポートします。デフォルトの physics モードには、重力、接触、テーブルトップ上の物体、オーバーヘッドカメラ、色検出、および物理的な把持検証が含まれます。
フィードバック駆動の Web アニメーション

実機モードでは、ソリッドモデルが実際のフィードバックを、半透明モデルが制御ターゲットを表します。Web コンソールはローカルアニメーションを実機姿勢と誤認しないよう、rosbridge の計測値に対して適応ローパスフィルタ、フィードバックのデッドゾーン、表示補間を適用します。
安全ステートマシン

システムは軌道、重力補償、安全な原点復帰、および連続 Web コマンドを仲裁します。ゼロ以外の姿勢から無効化する場合は、まず安全な原点復帰を実行して検証します。検証に失敗した場合、アームが突然落下しないよう、アームは有効状態を維持します。
ビジュアルグラスピングと LLM/MCP エージェント

シミュレーションシーンには、オーバーヘッド検出、IK、把持、リフト検証、配置に対応した赤・青・黄のオブジェクトが用意されています。MCP ツールは単独でも、大規模言語モデルと接続して自然言語から構造化されたロボット操作を呼び出すこともできます。

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

RS 実機 CAN 配線

アームをしっかり固定し、可動範囲を確保します。
RobStride モータの CAN バス、電源、および USB-CAN アダプタを接続します。
CAN_H、CAN_L、GND が正しく配線されていることを確認し、ハードウェア要件に従って終端抵抗を設定します。
通電後、目的の CAN アダプタが Ubuntu 上に認識されていることを確認します。

can0 を設定します：

sudo ip link set can0 down 2>/dev/null || true
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up
ip -details link show can0

読み取り専用モードでバスフレームを観察します：

candump can0

連続した CAN フレームが表示されれば、そのインターフェースがデータを受信していることを意味します。candump を終了するには Ctrl+C を押します。

インターフェースが BUS-OFF 状態になった場合は、まず電源、グラウンド、ボーレート、終端抵抗、モータ ID、CAN 配線を確認してください。コントローラを何度も再起動してハードウェアの不具合を隠さないでください。

Web と ROS 2 のネットワーク

Web コンソールは、デフォルトでポート 9090 を使用する rosbridge WebSocket を介して ROS 2 と通信します：

Web console: http://<Ubuntu-IP>:3002
rosbridge:   ws://<Ubuntu-IP>:9090
MCP Server:  http://<Ubuntu-IP>:8081/mcp
Text Agent:  http://<Ubuntu-IP>:8082

Web コンソールと ROS 2 が同じマシンで動作している場合は、localhost を使用できます。LAN 上の別のコンピュータからアクセスする場合、ブラウザ側コンピュータ自身の localhost を入力せず、ROS 2 サービスを実行している Ubuntu ホストの IP を使用してください。

プロジェクトの起動スクリプトは、ROS 2 のディスカバリ範囲をデフォルトで LOCALHOST に設定しているため、Wi-Fi ローミングや IP 変更が発生しても、同一マシン上のノードが別々の DDS ネットワークに分断されることはありません。これは、他のデバイスからの HTTP/WebSocket ポートへのアクセスには影響しません。別のコンピュータを ROS グラフに直接参加させるには、関連するターミナルでも同じ値を設定します：

export REBOTARM_ROS_DISCOVERY_RANGE=SUBNET

動作環境要件

項目	推奨要件
バックエンド OS	Ubuntu 24.04
ROS 2	Jazzy
互換性のある参照環境	Ubuntu 22.04 + ROS 2 Humble（実機利用には独自のリグレッションテストが必要）
Python	3.12（Jazzy）または 3.10（Humble）
Node.js	18 以上
ブラウザ	最新の安定版 Chrome、Chromium、Edge、または Firefox
CAN ツール	`iproute2`、`can-utils`
実機 CAN	`can0`、1 Mbps
MuJoCo	プロジェクトの Python 環境によってインストール

インストール手順

ステップ 1: プロジェクトを取得する

Step 1

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

以下のコマンドでは、プロジェクトディレクトリとして ~/ReBot_Arm_DigitalTwin_RS を使用します。異なるディレクトリを使用する場合は、パスを適宜置き換えてください。

ステップ 2: 読み取り専用の環境チェック

Step 2

cd ~/ReBot_Arm_DigitalTwin_RS
./setup.sh --check

このコマンドはシステムをチェックするだけで、環境を変更しません。チェック内容は次のとおりです：

Ubuntu、Python、Node.js のバージョン
ROS 2、rosbridge、MoveIt、およびビルドツール
SocketCAN ツールと can0
Python 仮想環境と主要モジュール
ROS 2 ワークスペースのビルド結果
Web の package.json と .env

ステップ 3: ワンクリックでのインストールとビルド

Step 3

./setup.sh --yes
./rebotarm doctor

インストールスクリプトは、不足している ROS 2、Node.js、SocketCAN、およびビルド依存関係をインストールし、rebotarm_ros2_RS/.venv を作成して RS 実機、MuJoCo、Agent 用の Python 依存関係をインストールし、rosdep を実行し、次のコマンドで ROS 2 ワークスペースをビルドします：

colcon build --symlink-install

制御 SDK と MuJoCo モデルは、メインリポジトリによって通常のファイルとして追跡されています。これらは Git サブモジュールではなく、入れ子になった Git リポジトリも含みません。既存の .env ファイル、SDK、モデルは、インストールスクリプトによってリセットされません。

システム依存関係がすでに揃っている場合は、ROS ワークスペースを準備して再ビルドするだけで済みます：

./scripts/setup_rs_workspace.sh

Python パッケージを変更した後は、通常これだけで十分です：

source scripts/rs_env.sh
cd rebotarm_ros2_RS
colcon build --symlink-install

ステップ 4: Web 環境変数を設定する

Step 4

初回インストール時、reBotArm_simulator-RS/.env は .env.example から作成されます。主な項目は次のとおりです：

PORT=3002
HTTPS=0
REBOTARM_TEXT_AGENT_URL=http://localhost:8082
REBOTARM_MCP_URL=http://localhost:8081/mcp
MOTORBRIDGE_WS_URL=ws://127.0.0.1:9002
MOTORBRIDGE_WS_TOKEN=

Web コンソールと ROS 2/Agent が同じマシン上にない場合は、プロキシアドレスをバックエンドマシンの IP に変更してください。API キーやトークンは、環境変数またはコミットされないローカルの .env にのみ保存するようにしてください。

プロジェクトの起動

純粋な Web デモ
フル RS MuJoCo シミュレーション
RS 実機ロボット制御
実機/Fake デュアルデバッグ

rosbridge や ROS 2 を使わずに、Node.js Web サーバーだけを起動します：

cd ~/ReBot_Arm_DigitalTwin_RS/reBotArm_simulator-RS
npm start

ブラウザで次を開きます：

http://localhost:3002

このモードは、3D モデル、UI、姿勢プリセット、およびフロントエンド機能の開発に適しています。ROS 2 バックエンドがないため、Web コンソールは実機ロボットや完全な MuJoCo シーンを制御できません。

reBot Arm B601-RS web simulator interface

ターミナル 1 で Fake Driver、MuJoCo、カメラ、検出、MCP Agent、および rosbridge を起動します：

cd ~/ReBot_Arm_DigitalTwin_RS
./rebotarm start rs_sim

ターミナル 2 で Web コンソールを起動します：

cd ~/ReBot_Arm_DigitalTwin_RS
./rebotarm start web

http://localhost:3002 を開き、制御対象として「RS Simulation (/rebotarm_rs)」を選択し、ROS WebSocket として ws://localhost:9090 を入力します。

一般的なシミュレーションオプション：

# No native MuJoCo window; suitable for automated tests
REBOTARM_MUJOCO_VIEWER=false ./rebotarm start rs_sim

# Kinematic following only; does not validate contact, gravity, or physical grasping
REBOTARM_MUJOCO_MODE=kinematic ./rebotarm start rs_sim

# Do not start the MCP Agent
REBOTARM_START_AGENT=false ./rebotarm start rs_sim

# After confirming there are no active tasks, clean up leftover simulation processes, then start
./rebotarm start rs_sim --force

ビジュアルグラスピングでは、デフォルトの physics モードを必ず使用してください。kinematic モードは関節位置を直接同期するだけであり、制御ゲイン、接触安定性、把持力の評価には使用できません。

reBot Arm B601-RS MuJoCo physics simulation

まず SocketCAN を設定して確認します：

sudo ip link set can0 down 2>/dev/null || true
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up
ip -details -statistics link show can0

非常停止が動作することと作業空間が安全であることを確認したら、ターミナル 1 で実機ロボットコントローラを起動します：

cd ~/ReBot_Arm_DigitalTwin_RS
REBOTARM_RS_HARDWARE_CONFIRM=I_UNDERSTAND_RS_WILL_MOVE \
  ./rebotarm start rs

ターミナル 2 で Web コンソールと rosbridge を起動します：

./rebotarm start web

http://localhost:3002 を開き、「RS Real Robot (/rebotarm)」を選択します。最初のテストでは、次の順序に従ってください：

Web コンソールが接続済みと表示し、アームの状態が正常で、モーターエラーがないことを確認します。
enable をクリックします。
速度を 0.2-0.4 rad/s に設定します。
一度に 1 つの関節を少しずつ動かし、方向、リミット、およびフィードバックを確認します。
その後、TCP ドラッギング、軌道、または重力補償をテストします。
終了時は、安全な原点復帰と disable を行い、その後コントローラのターミナルで Ctrl+C を押します。

実機ロボットコントローラの一時停止に Ctrl+Z を使用しないでください。また、Web ボタンを物理的な非常停止として扱わないでください。古いコントローラインスタンスが残っている場合、実機ロボット起動スクリプトは古いインスタンスに安全な終了を要求し、そのコントローラに属すると確認された残留リソースをクリーンアップします。

reBot Arm B601-RS real robot web control

export REBOTARM_RS_HARDWARE_CONFIRM=I_UNDERSTAND_RS_WILL_MOVE
./scripts/start_rs_dual.sh

このスクリプトは次を起動します：

実機ロボット /rebotarm;
Fake Driver /rebotarm_rs;
rosbridge 9090。

これはインターフェース、関節方向、ステータスを比較するために使用します。完全な MuJoCo スタック、ビジョン、Agent、Web サーバーは起動しません。コマンドを送信する前に、Web コンソールで選択されている namespace を再度確認してください。

統一コマンドライン

Command	説明
`./rebotarm doctor`	読み取り専用の環境チェック。`./setup.sh --check` と同等
`./rebotarm start web`	rosbridge を起動または再利用し、Web サーバーを起動
`./rebotarm start rs_sim`	フル RS MuJoCo シミュレーションスタックを起動
`./rebotarm start rs`	RS 実機ロボットコントローラを起動。ハードウェア確認用の変数が必要
`./rebotarm status`	登録済みプロセス、ポート、および `can0` を表示
`./rebotarm stop`	`start web` によって登録された web/rosbridge 子プロセスを停止

フォアグラウンドで動作しているシミュレーションおよび実機ロボットプロセスは、それぞれのターミナルで Ctrl+C を使って正常終了させてください。

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

ReBot_Arm_DigitalTwin_RS/
|-- setup.sh                              One-click check, install, and build
|-- rebotarm                              Unified start, status, and stop entry
|-- requirements-rs-hardware.txt          RS real-robot Python dependencies
|-- requirements-rs-mujoco.txt            MuJoCo/Agent Python dependencies
|-- scripts/
|   |-- rs_env.sh                         Load ROS, venv, and workspace
|   |-- setup_rs_workspace.sh             Prepare and build the ROS 2 workspace
|   |-- start_rs_sim.sh                   Full RS simulation stack
|   |-- start_rs_hardware.sh              RS real-robot controller
|   |-- start_rs_dual.sh                  Real-robot/Fake dual-namespace startup
|   `-- start_rs_text_agent.sh            Text Agent HTTP service
|-- rebotarm_ros2_RS/
|   |-- src/rebotarmcontroller/           Real-robot controller and Fake Driver
|   |-- src/rebotarm_msgs/                Custom msg/srv/action
|   |-- src/rebotarm_bringup/             Config, URDF, meshes, and launch
|   |-- src/rebotarm_mujoco_rs/           RS MuJoCo, camera, detection, and tasks
|   |-- src/rebotarm_agent/               MCP Server and Text Agent
|   |-- src/rebotarm_moveit_config/       MoveIt configuration
|   |-- src/rebotarm_moveit_demos/        Trajectory and picking/placing examples
|   `-- third_party/reBotArm_control_py/  Plain-source control SDK
`-- reBotArm_simulator-RS/
    |-- server.js                           Static server and Agent proxy
    |-- public/index.html                   Web entry point
    |-- public/js/rebot-sim.js              Three.js, IK, scene, and animation
    |-- public/js/ros/rebot-ros-client.js   rosbridge client
    |-- public/js/ros/rebot-ros-ui.js       ROS UI, control, and feedback logic
    |-- public/js/rebot-llm.js              LLM chat UI
    |-- description/                         Standalone fallback model for the web
    `-- split_meshes/grouped_gripper/        Optional web gripper meshes

システムデータフロー

Web から RS 実機ロボットへのコマンド

User drags a joint slider or TCP handle
  -> Three.js / browser DLS IK
  -> 30 ms slider damping, 1 deg input dead zone, max 60 Hz throttle
  -> rosbridge WebSocket
  -> JointMitCmd ROS topic
  -> command state arbitration
  -> 125 Hz velocity/acceleration/jerk-limited online reference
  -> MIT q/dq/kp/kd/tau
  -> reBotArm_control_py
  -> MotorBridge + SocketCAN can0
  -> RobStride motors

新しい Web ターゲットは、オンライン軌道の終端点だけを更新します。ブラウザが一時的に次のフレームの送信を止めた場合でも、125 Hz の制御ループは連続した参照値の生成を継続します。コマンドの QoS 深度は 1 なので、新しいターゲットは未処理の古いターゲットを上書きし、ドラッギング停止後に位置のバックログが再生されることを防ぎます。

RS 実機ロボットから Web へのフィードバック

RobStride encoder/status
  -> SocketCAN can0
  -> SDK status cache
  -> 20 Hz real-robot sync query
  -> 60 Hz ROS JointState publication
  -> rosbridge subscription throttle
  -> adaptive low-pass + feedback dead zone
  -> 32-120 ms display interpolation
  -> Three.js solid feedback model

半透明モデルは制御ターゲットを表します。関節およびグリッパの誤差が十分に小さくなると、ターゲットの影は自動的に消えます。表示フィルタリングは Web 上の見た目だけに影響し、モーターに送信されるターゲットは変更しません。

MuJoCo シミュレーションチェーン

Web console or Agent
  -> ROS 2 commands, services, or actions
  -> Fake RS Driver (100 Hz)
  -> MuJoCo Sync (250 Hz)
  -> RS MJCF dynamics and collision
  -> joint/object states, overhead camera, and color detection
  -> Web console and MCP Agent

Web 制御に関する注意事項

制御ターゲットと namespace

モード	Namespace	Web モデルソース
RS 実機ロボット	`/rebotarm`	実機ロボットの `/joint_states` フィードバック
RS シミュレーション	`/rebotarm_rs`	実際の MuJoCo 状態を優先して使用

モードを切り替えると、Web コンソールはターゲット namespace に応じて rosbridge クライアントとインターフェースパスを再作成します。

関節とグリッパ

J1〜J6 はラジアン単位で制御され、RS URDF と同じリミットを持ちます。
Web 上の速度範囲は 0.05-1.50 rad/s で、デフォルトは 1.2 rad/s です。
J1〜J6 はデフォルトで 30 ms のスライダ減衰と 1 deg の入力デッドゾーンを使用し、スライダを離したときに最終位置が強制的に確定されます。
J7/グリッパは Web 上では開口幅として表示され、範囲は 0-71.5 mm です。
グリッパは publish 時に RS モーター範囲 0-5 rad に変換され、ROS フィードバックはミリメートルに戻されます。
J7 は J1〜J6 のラジアン減衰や入力デッドゾーンを通らず、ブラウザのレンダリングフレームごとに最新のターゲットだけが送信されます。

TCP ドラッギングと IK

Web コンソールは、TCP ターゲットの解法に DLS（damped least squares）を使用します。RS バージョンでは特異点の度合いに応じて減衰を調整し、その後、同じ MIT オンライン制御チェーンを通じて関節解を送信します。

Web の Three.js シーンは Y-up、ROS は Z-up を使用します。座標変換ロジックは rebot-sim.js にあります。姿勢機能を拡張する際は、フォーム値を直接入れ替えるのではなく、既存の変換処理を再利用してください。

姿勢入力はメートル単位を使用します：X は前方、Y は左方向、Z は上方向です。ターゲットに到達できない場合は、まず Z を増やすか水平方向の距離を短くし、その後で姿勢制約と関節リミットを確認してください。

ティーチングと軌道再生

Web コンソールは関節軌道を記録し、呼び出すことができます：

/<namespace>/follow_joint_trajectory

RS 実機アクションサーバーは、連続な単調三次エルミート位置／速度リファレンスを使用し、短すぎる軌道セグメントを自動的に延長して、通常の実機軌道速度をおよそ 0.60 rad/s 未満に保ちます。呼び出し側はアクション結果または実機フィードバックを待つ必要があり、元のリクエストの所要時間に基づいて再生アニメーションを早期終了させてはいけません。

有効化、安全ホーミング、無効化

実機コントローラは、起動のたびに有効化する必要があります。
safe_home は滑らかにゼロへ戻り、角度と速度を検証します。
ゼロ以外の姿勢から無効化をクリックすると、まず SAFE_HOMING に入ります。
ホーミング検証が失敗した場合、モーターは有効のままで、失敗結果が返されます。
set_zero はモーターのゼロ点を書き換えるもので、通常のホーミングボタンではありません。機構が実際にキャリブレーション済み姿勢にあるときにのみ呼び出してください。

重力補償

RS の重力補償は現在計測されている姿勢から開始し、MIT 制御を関節ごとに切り替えるため、ゼロ姿勢がターゲットと誤認されることはありません。繰り返し開始しても結果は同じであり、停止すると最後に計測した位置が保持されます。

重力補償中は、Web の関節、TCP、軌道、およびグリッパーコマンドは拒否されます。関連サービス：

/<namespace>/gravity_compensation/start
/<namespace>/gravity_compensation/stop
/<namespace>/gravity_compensation/status

ROS 2 インターフェース

以下の例では実機の /rebotarm を使用します。シミュレーションでは、プレフィックスを /rebotarm_rs に置き換えてください。

ステータストピック

トピック	型	説明
`/rebotarm/joint_states`	`sensor_msgs/msg/JointState`	6 軸とグリッパーの統合ステータス
`/rebotarm/joints/<name>/state`	`rebotarm_msgs/msg/JointMotorState`	単一モーターの位置、速度、トルク、およびステータスコード
`/rebotarm/gripper/state`	`rebotarm_msgs/msg/JointMotorState`	グリッパーモーターの生ステータス
`/rebotarm/control_target`	`sensor_msgs/msg/JointState`	Web コンソールまたはアクション層からの最終ターゲット
`/rebotarm/control_reference`	`sensor_msgs/msg/JointState`	125 Hz オンライン軌道リファレンスの ROS サンプル；`effort` にリファレンス加速度を格納
`/rebotarm/arm_status`	`rebotarm_msgs/msg/ArmStatus`	有効状態、モード、ステートマシン、およびエラーコード

低レベルコマンドトピック

トピック	型	説明
`/rebotarm/joints/<joint1..joint6>/cmd/mit`	`rebotarm_msgs/msg/JointMitCmd`	実機用 Web コンソールからのデフォルト関節コマンド
`/rebotarm/joints/<joint1..joint6>/cmd/pos_vel`	`rebotarm_msgs/msg/JointPosVelCmd`	位置・速度コマンド
`/rebotarm/gripper/cmd/mit`	`rebotarm_msgs/msg/JointMitCmd`	RS グリッパー MIT コマンド
`/rebotarm/gripper/cmd/pos_vel`	`rebotarm_msgs/msg/JointPosVelCmd`	グリッパー位置・速度コマンド
`/rebotarm/mujoco/target_pose`	`geometry_msgs/msg/PoseStamped`	TCP ターゲット姿勢

自分で低レベルコマンドを publish する前に、arm_status.state_machine を確認してください。GRAVITY_COMP、SAFE_HOMING、または軌道実行中に制御を奪ってはいけません。

サービス

サービス	型	説明
`/rebotarm/enable`	`std_srvs/srv/Trigger`	アームを有効化
`/rebotarm/disable`	`std_srvs/srv/Trigger`	安全に無効化；必要に応じて先にホーミング
`/rebotarm/safe_home`	`std_srvs/srv/Trigger`	検証付き安全ホーミング
`/rebotarm/set_zero`	`rebotarm_msgs/srv/SetZero`	モーターのゼロ点を書き込み；慎重に使用
`/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/move_to_pose_ik`	`rebotarm_msgs/srv/MoveToPoseIK`	姿勢 IK ソルバ
`/rebotarm/gripper/set`	`rebotarm_msgs/srv/SetGripper`	グリッパー位置制御
`/rebotarm/gripper/open`	`rebotarm_msgs/srv/GripperCommand`	グリッパーを開く
`/rebotarm/gripper/close`	`rebotarm_msgs/srv/GripperCommand`	グリッパーを閉じる

例：

source scripts/rs_env.sh
ros2 service call /rebotarm/gravity_compensation/status std_srvs/srv/Trigger '{}'
ros2 service call /rebotarm/safe_home std_srvs/srv/Trigger '{}'

アクション

アクション	型	説明
`/rebotarm/follow_joint_trajectory`	`control_msgs/action/FollowJointTrajectory`	関節軌道
`/rebotarm/gripper/command`	`control_msgs/action/GripperCommand`	グリッパーアクション
`/rebotarm/move_to_pose`	`rebotarm_msgs/action/MoveToPose`	デカルト姿勢モーション

MuJoCo およびビジョンインターフェース

インターフェース	型／用途
`/rebotarm_rs/mujoco/joint_states`	実際の MuJoCo 関節状態
`/rebotarm_rs/mujoco/object_states`	シーンオブジェクト状態（JSON）
`/rebotarm_rs/mujoco/overhead_rgb/image_raw`	オーバーヘッド RGB カメラ
`/rebotarm_rs/vision/color_blocks/detections`	カラーオブジェクト検出 JSON
`/rebotarm_rs/mujoco/reset`	シミュレーションをリセット
`/rebotarm_rs/mujoco/record/start`	記録を開始
`/rebotarm_rs/mujoco/record/stop`	記録を停止
`/rebotarm_rs/mujoco/record/replay`	記録を再生
`/rebotarm_rs/mujoco/record/clear`	記録をクリア

ビジュアルグラスピング

フルシミュレーションには、デフォルトで赤い立方体、青い直方体、黄色い円柱が含まれます。Web コンソールではターゲットカラーを選択するか自動選択し、その後アライメント、プレグラスプ、下降、閉じる、持ち上げ、配置を実行できます。

グラスプ成功は軌道完了だけでは決まりません。システムは MuJoCo オブジェクトが実際に持ち上げられたかどうかも確認し、グリッパーが空のまま閉じた場合や、オブジェクトをつかまずに軌道だけ完了した場合の誤った成功報告を防ぎます。

ビジュアルグラスピングのトラブルシューティング：

source scripts/rs_env.sh
ros2 topic echo /rebotarm_rs/vision/color_blocks/detections --once
ros2 topic echo /rebotarm_rs/mujoco/object_states --once
ros2 service list | grep rebotarm_rs

グリッパーが閉じてもオブジェクトを持ち上げない場合：

physics モードが使用されていることを確認する；
カメラとカラー検出が連続的に publish されているか確認する；
ターゲットの幅、向き、および把持高さを確認する；
ログ内の接触安定性と物理的な持ち上げ検証結果を確認する；
複数のグラスプまたは IK リクエストを同時に開始しない。

LLM/MCP テキスト制御

アーキテクチャ

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

LLM は自然言語を理解し、MCP レイヤーが意図を制約して構造化されたツール呼び出しに変換します。LLM 設定がなくても、MCP の検出、IK、関節、グリッパー、およびグラスプツールは直接呼び出すことができます。

テキストエージェントの起動

フルシミュレーションでは、デフォルトで MCP Agent が起動します。自然言語エントリポイントを有効にするには、別のターミナルを開いてください：

cd ~/ReBot_Arm_DigitalTwin_RS
export DASHSCOPE_API_KEY='your-key'
export REBOTARM_LLM_MODEL='qwen-plus'
./scripts/start_rs_text_agent.sh

デフォルトアドレス：

MCP Server: http://127.0.0.1:8081/mcp
Dashboard:  http://localhost:8082

Web コンソールでは次のことができます：

アームと ROS のステータスを問い合わせる；
グリッパーを開閉する；
ターゲット姿勢が到達可能か確認する；
指定した姿勢へ移動する；
指定した色のオブジェクトを把持する。

実機環境でモーションツールを有効にする前に、Agent のモーション権限とネームスペースを明示的に確認してください。自然言語エントリポイントは、アームバックエンドの安全ステートマシンをバイパスしたり、物理的な非常停止を代替したりすることはできません。

主要制御パラメータ

実機のデフォルト設定は次の場所にあります：

rebotarm_ros2_RS/src/rebotarm_bringup/config/rebotarm_hardware.yaml

現在の RS の主要パラメータ：

rate: 125
control:
  arm_control_mode: mit
  mit_kp: [80, 150, 150, 50, 50, 50]
  mit_kd: [5, 10, 10, 5, 4, 4]
  stream_acceleration_limit: 4.0
  stream_jerk_limit: 30.0
  stream_natural_frequency: 8.0
gravity_compensation:
  kp: 2.0
  kd: 1.0

その他のデフォルト周波数：

レイヤー	デフォルト周波数	説明
Web 関節ターゲット	最大 60 Hz	スライダーと TCP IK がターゲットを連続更新
実機同期フィードバッククエリ	20 Hz	RobStride 計測キャッシュを更新
ROS 実機状態	60 Hz	キャッシュからフィードバック、ターゲット、リファレンスを publish
RS MIT 制御	125 Hz	オンラインスムージングとモーターコマンド
Fake Driver	100 Hz	シミュレーション制御と状態
MuJoCo 同期	250 Hz	デフォルトのダイナミクス同期
MuJoCo オブジェクト状態	30 Hz	シーンと Agent
オーバーヘッドカメラ	8 Hz	RGB 画像
カラー検出	10 Hz	検出結果

ゲインを調整する前に、以下をすべて同時に記録してください：

/rebotarm/control_target
/rebotarm/control_reference
/rebotarm/joint_states

ターゲットが不連続な場合は Web 入力レイヤーを確認し、リファレンスが不連続な場合はオンライン軌道を確認し、リファレンスが連続だがフィードバックがオーバーシュートする場合は MIT ゲイン、負荷、摩擦、電流、温度上昇を確認してください。Web アニメーションだけがジッタする場合に限り、フィードバックフィルタリングと rosbridge の到着間隔を確認してください。

二次開発ガイド

Web 関節リミットまたは姿勢プリセットの変更

ファイル：

reBotArm_simulator-RS/public/js/rebot-sim.js

関節定義は jointDefs に、プリセットは presets にあります。関節リミットを変更する際は、RS URDF、SDK 設定、および実際の機械的リミットを合わせて検証し、Web 上の表示範囲だけを変更しないでください。

Web コマンドの周波数、フィルタリング、ダンピングを変更する

ファイル：

reBotArm_simulator-RS/public/js/ros/rebot-ros-ui.js

このファイルは、Web コマンドのスロットリング、実機フィードバックのフィルタリング、フィードバックのデッドゾーン、補間、ターゲットシャドウ、制御ロック、およびビジョンロジックを扱います。Web アニメーションのレイテンシを補償するために、実機の MIT ゲインを上げないでください。

カスタム ROS インターフェースを追加する

クライアントラッパーは次の場所にあります：

reBotArm_simulator-RS/public/js/ros/rebot-ros-client.js

UI レイヤーに Topic、Service、または Action のパスを追加し、クライアントの subscribe()、callService()、または sendActionGoal() を呼び出します。インターフェースは常に現在の namespace から生成し、シミュレーションコマンドを実機に送信してしまうことを避けてください。

RS URDF またはメッシュを変更する

ROS 2 の主要モデル：

rebotarm_ros2_RS/src/rebotarm_bringup/description/urdf/ReBot_Arm_RS.urdf
rebotarm_ros2_RS/src/rebotarm_bringup/description/meshes_rs/

Web サーバーはまず上記のモデルを読み込みます。Web ディレクトリをコピーして単体で実行した場合は、次を使用します：

reBotArm_simulator-RS/description/urdf/ReBot_Arm_RS.urdf
reBotArm_simulator-RS/description/meshes_rs/

これらを変更する際は両方のコピーを同期させ、Linux のファイル名の大文字小文字を確認してください。

MuJoCo を変更する

ファイル/ディレクトリ	役割
`rebotarm_ros2_RS/src/rebotarm_mujoco_rs/models/`	RS MJCF および STL
`rebotarm_mujoco_rs/mujoco_sync.py`	同期周波数、ダイナミクス、および PD
`rebotarm_mujoco_rs/scene_camera.py`	俯瞰カメラ
`rebotarm_mujoco_rs/scene_detector.py`	色検出
`rebotarm_mujoco_rs/task_server.py`	タスク、記録、および再生
`rebotarm_mujoco_rs/launch/mujoco_rs.launch.py`	起動パラメータ

MCP ツールを拡張する

MCP Server は次の場所にあります：

rebotarm_ros2_RS/src/rebotarm_agent/rebotarm_agent/rebotarm_mcp_server.py

ツールを追加する際：

明確な入力スキーマと単位を定義する；
読み取り専用ツールとモーションツールを分離する；
モーションツールでは namespace、状態、およびモーション許可を検証する；
コントローラを直接バイパスするのではなく、ROS 2 Service/Action/Topic を通じてバックエンドを呼び出す；
ワークスペースを再ビルドし、シミュレーションでエラー、タイムアウト、およびキャンセル経路をテストする。

検証コマンド

source scripts/rs_env.sh
python3 -m pytest rebotarm_ros2_RS/src/rebotarmcontroller/test -q

bash -n setup.sh rebotarm scripts/*.sh

node --check reBotArm_simulator-RS/server.js
node --check reBotArm_simulator-RS/public/js/rebot-sim.js
node --check reBotArm_simulator-RS/public/js/ros/rebot-ros-client.js
node --check reBotArm_simulator-RS/public/js/ros/rebot-ros-ui.js
node --check reBotArm_simulator-RS/public/js/rebot-llm.js

ランタイムチェック：

./rebotarm status
ros2 node list
ros2 topic list | grep rebotarm
ros2 service list | grep rebotarm
ros2 action list | grep rebotarm

FAQ

1. Web ページがモデル読み込み画面のまま進まない

ブラウザの開発者ツールの Network パネルを開き、次のリクエストが 200 を返しているか確認します：

/api/urdf
/api/description/meshes/*.STL

よくある原因：

RS URDF または STL が存在しない；
Web ディレクトリだけを移動しており、フォールバックモデルが不完全；
URDF 内の package:// マッピングが正しくない；
Linux のファイル名の大文字小文字が一致していない；
Three.js、STLLoader、または URDFLoader の読み込み順序が誤っている。

2. ROS が「disconnected」と表示される

ss -ltnp | grep 9090
ros2 node list
./rebotarm status

rosbridge が 0.0.0.0:9090 で待ち受けていること、および WebSocket アドレスが ws:// で始まっていることを確認します。リモートブラウザでは、ブラウザを開いているコンピュータの localhost ではなく、Ubuntu の IP を入力してください。

3. Web コンソールは接続しているが、スライダで実機を制御できない

次の順に確認します：

Web コンソールが RS 実機の /rebotarm 上にある。
ROS WebSocket が接続されている。
Web 制御ロックが有効になっている。
アームが有効化されている。
arm_status が GRAVITY_COMP、TRAJ_RUNNING、または SAFE_HOMING になっていない。
実機コントローラに CAN またはモータエラーがない。

4. Web モデルがジッタする、またはターゲットシャドウが残り続ける

同じ namespace に対して、コントローラと state publisher がそれぞれ 1 つだけ存在することを確認する。
/joint_states に複数の publisher がいないか確認する。
control_target、control_reference、および joint_states を同時に記録する。
CAN エラーカウンタとフィードバック到着間隔を確認する。
軌道再生と手動の連続ドラッグを同時に実行しない。

長時間残るターゲットシャドウは、実際のフィードバックがターゲットに到達していないことを意味する場合が多く、必ずしも Web レンダリングの問題とは限りません。

5. CAN フィードバックがない、または BUS-OFF

ip -details -statistics link show can0
candump can0

次を確認します：

ボーレートが 1 Mbps になっているか；
CAN_H/CAN_L が逆になっていないか；
両端の終端抵抗；
モータ電源と共通グラウンド；
モータ ID と SDK 設定；
USB-CAN ドライバとインターフェース名。

エラーカウンタが増え続ける場合は、直ちに実機テストを停止してください。

6. disable をクリックしてもアームの電源がすぐに切れない

アームがゼロ姿勢付近にない場合、コントローラはまず安全なホーミングを実行し、その結果を検証します。これは想定された動作です。ホーミングが失敗した場合、非ゼロ姿勢からの落下を防ぐため、システムはアームを有効なままに保ちます。緊急時には物理的な非常停止ボタンを使用してください。

7. 重力補償が開始できない、または制御できない

アームが有効化されていることを確認する。
/gravity_compensation/status を問い合わせる。
軌道または安全ホーミングが実行中でないことを確認する。
重力補償中は他のモーションコマンドは拒否される。
モード切り替え時に落下する可能性のある荷重を必ず支持する。

8. ビジュアルグラスピングが動作しない

完全な rs_sim が physics モードで動作していることを確認し、次を確認します：

ros2 topic echo /rebotarm_rs/mujoco/overhead_rgb/image_raw --once
ros2 topic echo /rebotarm_rs/vision/color_blocks/detections --once
ros2 topic echo /rebotarm_rs/mujoco/object_states --once

ボタンがタスクがキューに入っていることを示している場合は、現在の直列アクションが終了するまで待ち、複数のグラスピング要求を繰り返し開始しないでください。

9. LLM アシスタントが接続に失敗する

Text Agent が起動していることを確認します：

./scripts/start_rs_text_agent.sh

reBotArm_simulator-RS/.env 内の REBOTARM_TEXT_AGENT_URL と REBOTARM_MCP_URL を確認します。Web コンソールは /api/llm/health を通じてバックエンドをチェックします。API キーを Web ソースコードに書き込んだり、リポジトリにコミットしたりしないでください。

10. フロントエンドを変更してもページに古いバージョンが表示される

RS Web コンソールには Service Worker/PWA のサポートが含まれています。まず Ctrl+Shift+R でハードリフレッシュを行います。それでも更新されない場合は、サイトデータを消去するか、ブラウザの開発者ツールで Service Worker の登録を解除してから、ページを再読み込みしてください。

11. `setup.sh` または `colcon build` が失敗する

Ubuntu、ROS 2、および Python のバージョンが一致していることを確認する。
rosdep が初期化され、更新できることを確認する。
./setup.sh --check を実行して不足している項目を確認する。
numpy、scipy、mujoco、pinocchio、motorbridge、および fastmcp が rebotarm_ros2_RS/.venv でインポートできることを確認する。
ユーザーファイルを削除またはリセットする前にバックアップを取り、破壊的なコマンドでビルド問題を解決しないこと。

クイックコマンド表

# Check and install
./setup.sh --check
./setup.sh --yes
./rebotarm doctor

# Full simulation
./rebotarm start rs_sim
./rebotarm start web

# Natural-language Agent
export DASHSCOPE_API_KEY='your-key'
./scripts/start_rs_text_agent.sh

# RS real robot
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up
REBOTARM_RS_HARDWARE_CONFIRM=I_UNDERSTAND_RS_WILL_MOVE ./rebotarm start rs

# Status and stop
./rebotarm status
./rebotarm stop

参考文献

ROS 2 Jazzy ドキュメント: https://docs.ros.org/en/jazzy/
rosbridge_suite: https://github.com/RobotWebTools/rosbridge_suite
Three.js: https://threejs.org/docs/
URDFLoader: https://github.com/gkjohnson/urdf-loaders
MuJoCo: https://mujoco.readthedocs.io/
Model Context Protocol: https://modelcontextprotocol.io/
B601-RS プロジェクトドキュメント: README.md、USER_MANUAL_ZH.md、DEVELOPER_GUIDE_ZH.md、DATA_FLOW_RS_ZH.md

プロジェクトの特長​

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

RS 実機 CAN 配線​

Web と ROS 2 のネットワーク​

動作環境要件​

インストール手順​

ステップ 1: プロジェクトを取得する​

ステップ 2: 読み取り専用の環境チェック​

ステップ 3: ワンクリックでのインストールとビルド​

ステップ 4: Web 環境変数を設定する​

プロジェクトの起動​

統一コマンドライン​

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

システムデータフロー​

Web から RS 実機ロボットへのコマンド​

RS 実機ロボットから Web へのフィードバック​

MuJoCo シミュレーションチェーン​

Web 制御に関する注意事項​

制御ターゲットと namespace​

関節とグリッパ​

TCP ドラッギングと IK​

ティーチングと軌道再生​

有効化、安全ホーミング、無効化​

重力補償​

ROS 2 インターフェース​

ステータストピック​

低レベルコマンドトピック​

サービス​

アクション​

MuJoCo およびビジョンインターフェース​

ビジュアルグラスピング​

LLM/MCP テキスト制御​

アーキテクチャ​

テキストエージェントの起動​

主要制御パラメータ​

二次開発ガイド​

Web 関節リミットまたは姿勢プリセットの変更​

Web コマンドの周波数、フィルタリング、ダンピングを変更する​

カスタム ROS インターフェースを追加する​

RS URDF またはメッシュを変更する​

MuJoCo を変更する​

MCP ツールを拡張する​

検証コマンド​

FAQ​

1. Web ページがモデル読み込み画面のまま進まない​

2. ROS が「disconnected」と表示される​

3. Web コンソールは接続しているが、スライダで実機を制御できない​

4. Web モデルがジッタする、またはターゲットシャドウが残り続ける​

5. CAN フィードバックがない、または BUS-OFF​

6. disable をクリックしてもアームの電源がすぐに切れない​

7. 重力補償が開始できない、または制御できない​

8. ビジュアルグラスピングが動作しない​

9. LLM アシスタントが接続に失敗する​

10. フロントエンドを変更してもページに古いバージョンが表示される​

11. setup.sh または colcon build が失敗する​

クイックコマンド表​

参考文献​