目次
ロボットをジョイスティック（PS4, PS5）、Meta Quest、またはキーボードで遠隔操作するためのパッケージ．
Meta Questのセットアップについてはこちらを参照．
本パッケージはロボット非依存です．ロボット固有の設定はすべて1つのconfigディレクトリ
（config/{robot_name}/）にまとまっており，起動時にrobot_name:=<名前>で選択します．
SOBITSロボット（sobit_home、sobit_pro、sobit_edu、sobit_mini、sobit_light）用の
configは同梱済みで，新しいロボットへの移植はこのディレクトリを作成するだけです —
コードやlaunchの変更は不要です（新しいロボットへの移植参照）．
対応入力デバイス：ps4、ps5、quest、keyboard
(上に戻る)
ここで，本レポジトリのセットアップ方法について説明します．
(上に戻る)
まず，以下の環境を整えてから，次のインストール段階に進んでください．
| System | Version |
|---|---|
| Ubuntu | 24.04 (Noble Numbat) |
| ROS | Jazzy Jalisco |
| Python | 3.12+ |
(上に戻る)
-
ROSの
srcフォルダに移動します．cd ~/colcon_ws/src/
-
本レポジトリをcloneします．
git clone -b jazzy-devel https://github.com/TeamSOBITS/sobits_teleop
-
レポジトリの中へ移動します．
cd sobits_teleop/ -
依存パッケージをインストールします．
bash install.sh
-
パッケージをビルドします．
cd ~/colcon_ws/ colcon build --symlink-install source ~/colcon_ws/install/setup.bash
(上に戻る)
基本的な流れ：
- ロボットと入力デバイスに対応するconfigファイルを確認・作成する．
- 入力デバイスをPCに接続する．
- 適切な引数を指定してテレオペノードを起動する．
(上に戻る)
各ロボットのconfigはconfig/{robot_name}/以下に配置します．
このディレクトリが本パッケージ内で唯一のロボット固有部分です：
| ファイル | 役割 |
|---|---|
robot.yaml |
ジョイントコントローラとcmd_velのトピック名 |
{device}.yaml |
使用するデバイスのボタン・軸マッピング |
arm_backend_plan.yaml |
Plan-and-replaceアーム追跡バックエンドのチューニング（Quest使用時のみ） |
arm_backend_servo.yaml |
MoveIt Servoアーム追跡バックエンドのチューニング（Quest使用時のみ） |
arm_scale_calibrator.yaml |
アームリーチキャリブレーションパラメータ（Quest使用時のみ） |
アームの構成情報（アームの一覧・planning group・目標/エンドエフェクタのフレーム・
コントローラトピック）は{device}.yaml（アームごとのarm:ブロック）とrobot.yaml
（trajectoryトピックのマップ）に一度だけ定義します．launcherが起動するバックエンドへ
注入するため，2つのarm_backend_*.yamlはチューニングのみを持ち，ほぼロボット非依存です．
robot.yaml（例）
/**:
ros__parameters:
robot_topic_name:
joint_states_topic: joint_states
joint_trajectory_topic:
head: head_position_controller/joint_trajectory
body: body_position_controller/joint_trajectory
arm_left: arm_left_position_controller/joint_trajectory
arm_right: arm_right_position_controller/joint_trajectory
cmd_vel_topic: cmd_vel{device}.yaml（例）
/**:
ros__parameters:
control_joints: # 操作するjoint_trajectory_controllerを定義
groups:
- head
- arm_left
head:
names:
- head_tilt_joint
- head_pan_joint
head_tilt_joint:
button: 2 # 有効化ボタン
fast_button: 6 # 押している間、高速モード
axis: 1 # ジョイスティック軸
axis_sign: 1 # 正負を反転する場合は-1
speed: 0.1 # 通常速度
fast_speed: 0.5 # 高速モード時の速度
control_poses: # 定義済みポーズへの移動
trigger: 8
pose_list:
- initial_pose
- pre_manipulation_pose
initial_pose:
button: 2
control_velocity: # 台車制御
button: 5
fast_button: 7
linear_x_axis: 1
linear_y_axis: 0
angular_axis: 3
axis_sign: 1
linear_scale: 0.1
angular_scale: 0.3
fast_linear_scale: 0.2
fast_angular_scale: 0.6(上に戻る)
すべての設定はCLI引数で指定します．launchファイルを直接編集する必要はありません．
| 引数 | デフォルト | 説明 |
|---|---|---|
robot_name |
sobit_home |
ロボット名（configディレクトリの選択に使用） |
device |
ps4 |
入力デバイス：ps4、ps5、quest、keyboard |
joystick_device |
/dev/input/js0 |
ジョイスティックデバイスパス（PS4/PS5のみ） |
ros_ip |
0.0.0.0 |
Quest TCP接続用のPC IPアドレス |
use_ds4drv |
True |
ds4drvを同時起動する（PS4のみ） |
use_moveit |
false |
アーム追跡バックエンドを起動する（Questのみ） |
use_servo |
false |
Plan-and-replaceの代わりにMoveIt Servoバックエンドを使用する（use_moveit:=trueが必要） |
use_sim_time |
false |
シミュレーション時刻を使用する（Gazebo） |
(上に戻る)
- コントローラをBluetoothでPCとペアリングする．
jstest-gtkコマンドで接続を確認する．- 起動する：
ros2 launch sobits_teleop sobits_teleop.launch.py \ robot_name:=sobit_home \ device:=ps4
Note
Dockerコンテナ内でds4drvを使用する場合は、/dev/input/と/run/udevをマウントすること．
- QuestとPCが同一Wi-Fiネットワークに接続されていることを確認する．
- PCのIPアドレスを確認する：
hostname -I
- テレオペノードを起動する：
ros2 launch sobits_teleop sobits_teleop.launch.py \ robot_name:=sobit_home \ device:=quest \ ros_ip:=<PC_IPアドレス>
- Quest側でUnityプロジェクトを起動し、左コントローラのメニューボタンでROS_IPを入力・設定する．
Meta Questのセットアップはmeta_quest_teleoperationを参照．
ros2 launch sobits_teleop sobits_teleop.launch.py \
robot_name:=sobit_home \
device:=keyboard(上に戻る)
ハンドコントローラのTFポーズをリアルタイムで追従するバックエンドが2種類あります．
どちらも同じインタフェース — {side}_target_link TFと
/{robot_name}/{arm_name}/moveit_track_enabled（std_msgs/Bool，グリップボタンが
自動でパブリッシュ）— を使うため，launch引数1つで切り替えられます．
| バックエンド | 選択方法 | 追従方式 |
|---|---|---|
Plan-and-replace（moveit_arm_controller） |
use_moveit:=true |
MoveIt2で短いCartesian計画をストリーミング；特異点付近はOMPLへフォールバック |
MoveIt Servo（servo_node + servo_target_bridge） |
use_moveit:=true use_servo:=true |
アームごとのmoveit_servoインスタンスが50Hzで微分IK |
ros2 launch sobits_teleop sobits_teleop.launch.py \
robot_name:=<robot_name> \
device:=quest \
ros_ip:=<PC_IPアドレス> \
use_moveit:=true \
use_servo:=true # 省略するとPlan-and-replaceバックエンド両launcherはlaunch/include/にあり，アーム構成をquest.yaml/robot.yamlから
注入するため，バックエンドのconfigはチューニングのみです．
arm_teleop:
update_rate_hz: 50.0 # 追従ループ周波数
max_cartesian_step_m: 0.10 # 1サイクルの最大ステップ
eef_step_m: 0.02 # Cartesian補間解像度
min_cartesian_fraction: 0.2 # この値を下回るとOMPLにフォールバック
replan_threshold_m: 0.03 # 目標がこの距離動いたら再計画
preempt_threshold_m: 0.30 # 実行中の軌道をキャンセルする距離
arrival_threshold_m: 0.03 # EEがこの距離以内なら計画をスキップ
velocity_scaling: 0.90
acceleration_scaling: 0.80
publish_mode: topic # 軌道ストリーミング（テレオペに最適）Servoスタック全ノードで1ファイル；共有の/**:セクションがチューニングを持ちます．
移植時に確認すべきロボット依存の項目：
moveit_servo:
scale: {linear: 1.5, rotational: 3.0} # EE速度上限 [m/s, rad/s]
publish_joint_velocities: false # アームのJTCが終端速度非ゼロの軌道を
# 拒否する場合はfalseのまま
lower_singularity_threshold: 50.0
hard_stop_singularity_threshold: 200.0 # 無効化しないこと（関節ワインドアップ）
joint_limit_margins: [0.02]
servo_bridge:
pose_rate_hz: 100.0
max_reach: 1.10 # 各アームの肩を中心としたリーチクランプ球の半径 [m]
# — 対象ロボットの肩→EEチェーン長の約90〜95%に設定bridgeは目標をmax_reach球にクランプするため，届かない位置の手をアームが追いかけて
完全伸展の特異点に陥ることを防ぎます．アームごとのフレームやトピックはアーム名から
規約で導出されます（arm_right → right_target_link、
hand_right_end_effector_link、arm_right_shoulder_tilt_linkなど）．
ロボットの命名が異なる場合はservo_bridge.{arm_name}.*のキーで上書きしてください．
Servoバックエンドにはros-$ROS_DISTRO-moveit-servo（install.shでインストール）と，
/{robot_name}名前空間で動作中のmove_groupが必要です — launcherが起動時に
ロボットモデルをそこから取得します．
| 入力 | 動作 |
|---|---|
グリップボタン（arm_enable_axis） |
押している間アームを追従 |
ポーズボタン（hand_pose_button） |
hand_pose_open/hand_pose_closeをトグル |
| トリガ + スティック左右 | アダプティブ開閉 |
| トリガ + スティック上下 | 把持タイプ関節（single_joint_name）を回転 |
(上に戻る)
config/{robot_name}/を作成し，robot.yaml（コントローラトピック）と使用する デバイスごとの{device}.yamlを用意する．- Questでアームテレオペを行う場合，
quest.yamlにアームごとのブロック（arm:、target_frame_name:、end_effector_frame_name:、グリッパのマッピング）を追加する — これが両バックエンド共通のアーム構成の単一定義源になります． - 既存ロボットの
arm_backend_plan.yaml/arm_backend_servo.yamlをコピーし， チューニングを調整する（max_reachをアーム長に合わせる；速度上限；しきい値）． robot_name:={robot_name}で起動する — それ以外の変更は不要です．
前提条件：アームがjoint_trajectory_controllerのトピックインタフェースで駆動される
こと（robot.yaml参照），アームごとに1つのplanning groupを持ち，SRDFの最後のリンクが
エンドエフェクタであるMoveIt configがあること，/{robot_name}名前空間でmove_group
が動作していること．
(上に戻る)
quest.yamlのscaleパラメータは人間のアームリーチとロボットのアームリーチを対応付けます．arm_scale_calibratorツールを使うと、適切なscale値を自動的に計算できます．
オペレータごとに一度実行する（ロボットURDFのアームリーチが変わった場合も再実行）．結果をconfig/{robot_name}/quest.yamlのright.scaleとleft.scaleに設定する．
config/{robot_name}/arm_scale_calibrator.yaml：
robot_arm_reach_m: 1.2926 # 肩からEEまでのフルキネマティックチェーン（URDFより）
right_frame: "right_controller_odom"
left_frame: "left_controller_odom"
parent_frame: "base_footprint"
grip_axis: 7 # Joyメッセージにおける右グリップの軸インデックス片腕ロボットの場合、使用しない側のフレームを""に設定する：
right_frame: "right_controller_odom"
left_frame: "" # 無効化 — 右アームのみ計測ros2 run sobits_teleop arm_scale_calibrator --ros-args \
--params-file install/sobits_teleop/share/sobits_teleop/config/{robot_name}/arm_scale_calibrator.yaml \
-p joy_topic:=/{robot_name}/joyNote
{robot_name}は使用するロボット名に置き換える（例：sobit_home）．
ステップ1 — 開始位置の設定
- 両コントローラーを持ち、自然な立ち姿勢をとる．
- 両腕をまっすぐ前方に伸ばす（ロボットの方向を向くように）．
- 右グリップボタンを押して離し、開始位置を記録する．
ステップ2 — T字ポーズへのスウィープ
- 両腕をゆっくりと左右真横に開いていく（肘を伸ばしたまま）．
- T字ポーズで完全に腕が伸びたら、右グリップボタンを押して離す．
Note
スウィープは2秒以上かける必要がある．短すぎる場合は警告が表示され、再度試みることができる．
=== RESULTS ===
Human arm reach used : 0.9150 m
Robot arm reach : 1.2926 m
Recommended scale = 1.2926 / 0.9150 = 1.4126
Update config/sobit_home/quest.yaml:
scale: 1.4126 # (both right and left)
表示されたscale値をquest.yamlに設定する：
right:
scale: 1.4126
left:
scale: 1.4126(上に戻る)
Gazeboシミュレーションと組み合わせて使用する場合はuse_sim_time:=trueを指定する：
ros2 launch sobits_teleop sobits_teleop.launch.py \
robot_name:=sobit_home \
device:=keyboard \
use_sim_time:=true(上に戻る)
- 疑似逆運動学の追加
現時点のバグや新規機能の依頼はIssueページをご覧ください．
(上に戻る)