同构遥操作¶

面向 高擎 Panthera HT 双臂的主从 同构遥操作：在关节空间移动主臂，从臂跟随。

已实现： 通过 drag_teleop_controller 的同构遥操作（包名是历史遗留）。未实现： 拖动示教（拖动遥操作）、轨迹录制/回放，或 enter_teach_mode。

在 open-deploy-ws 的 panthera-ht 分支上，优先使用 ./teleop_start.sh（见高擎 Panthera HT 及该分支 README）。下列 launch 与 drag_teleop_controller README 一致。

README： drag_teleop_controller README

前置条件¶

工作空间已包含 drag_teleop_controller（公开）
高擎 Panthera HT 描述（panthera_ht）
两个启动进程：一个 master、一个 slave（mock 或两台实体臂）

概述¶

同一个控制器插件，两种角色：

角色	作用
`master`	操作者侧。重力补偿，便于在关节空间移动主臂；发布映射后的关节状态。
`slave`	从臂。跟踪映射后的主臂关节（可选 ruckig 平滑）。

控制模式（mode）：position（仅从臂）、mit、effort。仅主臂的力反馈（feedback）：false、position、effort。关节映射在发布 teleop_states 之前完成。夹爪由同一 launch 拉起的 adaptive_gripper_controller 控制。

准备¶

cd ~/open-deploy-ws
colcon build --packages-select drag_teleop_controller --symlink-install
source install/setup.bash

Mock（无需硬件）¶

两个终端：

# Terminal 1 — master
ros2 launch drag_teleop_controller drag_teleop_controller.launch.py \
  role:=master hardware:=mock_components

# Terminal 2 — slave
ros2 launch drag_teleop_controller drag_teleop_controller.launch.py \
  role:=slave hardware:=mock_components

检查控制器与话题：

ros2 control list_controllers --controller-manager /drag_teleop_master/controller_manager
# drag_teleop_controller / left_gripper_controller / right_gripper_controller should be active

ros2 topic echo /drag_teleop_master/teleop_states
ros2 topic echo /drag_teleop_slave/teleop_states

真机（高擎 Panthera HT）¶

在 panthera-ht 分支上优先使用 ./teleop_start.sh。下列 launch 文件与参数名与软件包 README 一致。默认 robot 为 panthera_ht。真机用 hardware:=real（或 real_usb）。

# Master (low-stiffness, gravity-compensated)
ros2 launch drag_teleop_controller drag_teleop_controller.launch.py \
  role:=master hardware:=real mode:=effort \
  hardware_control_mode:=effort \
  hardware_gripper_kp:="1e-5" hardware_gripper_kd:="1e-5"

# Slave (MIT follow)
ros2 launch drag_teleop_controller drag_teleop_controller.launch.py \
  role:=slave hardware:=real mode:=mit

可选：主臂加外部力矩反馈，增加 feedback:=effort（见 README）。

模式切换¶

自定义服务，不是 std_srvs/Trigger：

ros2 service call /drag_teleop_master/teleop_mode \
  drag_teleop_controller/srv/TeleopMode "{mode: effort}"
ros2 service call /drag_teleop_master/teleop_feedback \
  drag_teleop_controller/srv/TeleopFeedback "{mode: position}"

启动参数（摘要）¶

参数	默认值	含义
`role`	（必选）	`master` 或 `slave`
`robot`	`panthera_ht`	查找 `{robot}_description`
`type`	`dual`	`single` / `left` / `right` / `dual`
`hardware`	`mock_components`	`real` / `real_usb` / `mock_components` / `gz` / `isaac`
`mode`	（yaml）	`position`（仅从臂） / `mit` / `effort`
`feedback`	（yaml）	`false` / `position` / `effort`（仅主臂）
`moveJ_pub`	`false`	主臂可发布 OCS2 moveJ 与夹爪命令

各 role × mode 的控制律、驱动层要求和 YAML 键见 README。

安全¶

物理接触

真机时：

确保急停随时可及
先在 mock 验证，再以低刚度主臂（effort）启动，然后启用从臂
缓慢移动；注意关节限位与夹伤点
接触机械臂前，确认两个 role 进程已启动且 teleop_states 正在发布

验证¶

Mock：两个 controller manager 中 drag_teleop_controller 均为 active
/drag_teleop_master/teleop_states 与 /drag_teleop_slave/teleop_states 正在发布
主臂关节状态变化会反映到从臂（映射后的关节名）

故障排查¶

控制器无法激活¶

role 必须是 master 或 slave
硬件必须导出 mode 所需的命令接口（position / velocity / effort）。控制器在 on_activate 时校验。

从臂不跟随¶

两个进程正在运行，且 robot / type 一致
分别 echo 两个 teleop_states 话题
input_topic 默认是 /drag_teleop_{对侧}/teleop_states

DexCap / 关节重映射¶

DexCap 手套到机器人的映射是 另一个 软件包：teleop-joint-mapper。不是这条主从同构路径。