逆戟鲸之手

软件设置

orca_core SDK 安装、USB 驱动程序设置、单独手指控制 API、ROS2 手部界面、触觉传感器读取和 MuJoCo 模拟。从全新的 Python 安装到所有 17 个关节都移动了。

跳转到一个部分：

› SDK安装 › 手指控制 API › 掌握原语 › ROS2 集成 › 触觉传感器 > 模拟 › 故障排除

第 1 步 — SDK 安装

orca_core SDK安装

orca_core 是 Orca Hand 的官方 Python SDK。它可以通过 pip 安装并支持 Python 3.9+。基本联合控制不需要 ROS。

创建虚拟环境

python -m venv ~/.venvs/orca
source ~/.venvs/orca/bin/activate   # Windows: .venvs\orca\Scripts\activate

通过 pip 安装

pip install orca-core

通过 Poetry 安装（推荐用于开发）

git clone https://github.com/orcahand/orca_core.git
cd orca_core
poetry install

验证安装并找到你的手

python -c "from orca_core import OrcaHand; print('orca_core installed OK')"

# Find the USB serial port
python -c "
from orca_core import OrcaHand
# Lists available ports
import serial.tools.list_ports
ports = list(serial.tools.list_ports.comports())
for p in ports:
    print(p)
"

第 2 步 — 手指控制 API

单独的手指控制

这 OrcaHand 类通过命名的手指和关节访问器公开所有 17 个关节。控制模式默认为 current_based_position.

连接并读取所有关节位置

from orca_core import OrcaHand

hand = OrcaHand(port="/dev/ttyUSB0", handedness="right")
hand.connect()

# Read all joint positions (returns dict of joint_name: position_deg)
positions = hand.get_positions()
print(positions)
# e.g. {'thumb_abduct': 0.0, 'thumb_mcp': 15.2, ...}

hand.disconnect()

移动各个关节

from orca_core import OrcaHand
import time

hand = OrcaHand(port="/dev/ttyUSB0", handedness="right")
hand.connect()
hand.enable_all()

# Move thumb MCP joint to 45 degrees
hand.set_position("thumb_mcp", 45.0)
time.sleep(0.5)

# Move index finger MCP to 60 degrees
hand.set_position("index_mcp", 60.0)
time.sleep(0.5)

# Open all fingers
hand.open_all()
time.sleep(1.0)

hand.disable_all()
hand.disconnect()

同时设置多个关节

from orca_core import OrcaHand

hand = OrcaHand(port="/dev/ttyUSB0", handedness="right")
hand.connect()
hand.enable_all()

# Command all 17 joints at once (dict of joint_name: target_deg)
pose = {
    "thumb_abduct": 30.0,
    "thumb_mcp":    45.0,
    "thumb_pip":    30.0,
    "thumb_dip":    20.0,
    "index_mcp":    70.0,
    "index_pip":    60.0,
    "index_dip":    40.0,
    # ... remaining joints
}
hand.set_positions(pose)

hand.disable_all()
hand.disconnect()

第 3 步 — 掌握基元

内置抓取基元

orca_core 附带用于常见操作任务的校准抓取基元。这些是在实施自定义策略之前测试基本掌握能力的最快方法。

使用抓取原语

from orca_core import OrcaHand
from orca_core.grasps import GraspLibrary
import time

hand = OrcaHand(port="/dev/ttyUSB0", handedness="right")
hand.connect()
hand.enable_all()
grasps = GraspLibrary()

# Open hand
hand.execute_grasp(grasps.open)
time.sleep(1.0)

# Power grasp (whole-hand wrap)
hand.execute_grasp(grasps.power_grasp)
time.sleep(1.0)

# Precision pinch (thumb + index tip)
hand.execute_grasp(grasps.precision_pinch)
time.sleep(1.0)

# Tripod grasp (thumb + index + middle)
hand.execute_grasp(grasps.tripod)
time.sleep(1.0)

# Lateral pinch (thumb side against index lateral)
hand.execute_grasp(grasps.lateral_pinch)
time.sleep(1.0)

hand.open_all()
hand.disable_all()
hand.disconnect()

在抓取之间进行插值

from orca_core import OrcaHand
from orca_core.grasps import GraspLibrary
import time, numpy as np

hand = OrcaHand(port="/dev/ttyUSB0", handedness="right")
hand.connect()
hand.enable_all()
grasps = GraspLibrary()

# Smoothly interpolate from open to power grasp over 30 steps
for alpha in np.linspace(0, 1, 30):
    pose = grasps.interpolate(grasps.open, grasps.power_grasp, alpha)
    hand.set_positions(pose)
    time.sleep(0.05)

hand.disable_all()
hand.disconnect()

第 4 步 — ROS2 集成

ROS2手部接口

这 orca_ros2 软件包提供了完整的 ROS2 接口，用于协调臂 + 手控制。它发布联合状态并接受联合轨迹命令。

安装orca_ros2

mkdir -p ~/orca_ws/src && cd ~/orca_ws/src
git clone https://github.com/orcahand/orca_ros2.git
cd ~/orca_ws
source /opt/ros/humble/setup.bash
colcon build --symlink-install

启动手驱动器节点

source ~/orca_ws/install/setup.bash
ros2 launch orca_ros2 orca_hand.launch.py \
  port:=/dev/ttyUSB0 \
  handedness:=right

订阅联合国家主题

ros2 topic echo /orca_hand/joint_states

发送关节位置指令

ros2 topic pub /orca_hand/joint_command \
  sensor_msgs/msg/JointState \
  '{name: ["index_mcp", "index_pip"], position: [1.22, 1.05]}'

协调臂+手发射（使用OpenArm）

ros2 launch orca_ros2 openarm_orca.launch.py \
  arm_can_interface:=can0 \
  hand_port:=/dev/ttyUSB0 \
  handedness:=right

这将同时启动 openarm_ros2 手臂驱动器和 orca_ros2 手动驱动程序位于单个命名空间下，通过 MoveIt2 实现协调轨迹执行。

第 5 步 — 触觉传感器

触觉传感器读数

Orca Hand 可选择安装指尖触觉传感器（Paxini 或兼容）。触觉数据通过单独的 USB 连接独立传输。

读取指尖接触力

from orca_core import OrcaHand
from orca_core.sensors import TactileSensorArray

hand = OrcaHand(port="/dev/ttyUSB0", handedness="right")
tactile = TactileSensorArray(port="/dev/ttyUSB1")  # separate USB port

hand.connect()
tactile.connect()
hand.enable_all()

import time
for _ in range(100):
    # Returns dict of finger_name: contact_force_N
    forces = tactile.read_forces()
    positions = hand.get_positions()
    print(f"Index force: {forces.get('index', 0):.3f} N | "
          f"Index MCP: {positions['index_mcp']:.1f} deg")
    time.sleep(0.01)

hand.disable_all()
hand.disconnect()
tactile.disconnect()

接触检测阈值

from orca_core.sensors import TactileSensorArray

tactile = TactileSensorArray(port="/dev/ttyUSB1")
tactile.connect()

# Set contact detection threshold per finger (in N)
tactile.set_threshold(finger="index", threshold_n=0.1)
tactile.set_threshold(finger="thumb", threshold_n=0.15)

# Returns True when contact exceeds threshold
in_contact = tactile.is_in_contact("index")
print("Index in contact:", in_contact)

可选 — 模拟

MuJoCo 模拟

Orca Hand 附带经过校准的 MuJoCo MJCF 模型 - 左手、右手和双手场景。该模拟与真实硬件共享相同的联合名称和动作空间。

安装并运行模拟

pip install mujoco
pip install orca-core[sim]  # or: pip install orca-mujoco

# Clone the MuJoCo model package
git clone https://github.com/orcahand/orcahand_description.git

# Launch the right-hand sim
python -c "
import mujoco, mujoco.viewer
import numpy as np

model = mujoco.MjModel.from_xml_path('orcahand_description/mjcf/orca_right.xml')
data = mujoco.MjData(model)

with mujoco.viewer.launch_passive(model, data) as viewer:
    while viewer.is_running():
        mujoco.mj_step(model, data)
        viewer.sync()
"

模拟到真实的传输

MJCF 模型中的联名与 orca_core SDK 完全一样。在抓取基元上进行模拟训练的策略可以直接部署到真实硬件中 - 唯一的区别是 USB 串行延迟（约 3 毫秒）与物理步骤时序。

故障排除

常见问题

错误1 一些手指没有响应——部分伺服扫描

通常，菊花链电缆没有完全固定在指状模块之间的连接处。 STS 总线是一条链——一个错误的连接会导致所有下游伺服系统丢失。

使固定：

# Scan to see which servo IDs are found
python -c "
from orca_core import OrcaHand
hand = OrcaHand(port='/dev/ttyUSB0', handedness='right')
hand.connect()
ids = hand.scan_motors()
print('Found IDs:', ids)  # should be 1..17
hand.disconnect()
"

错误2 手指达到硬极限——肌腱过度紧张

手指无法完全伸展或弯曲。一侧肌腱走线太紧。最常发生在重新组装后。

使固定：

# Check joint limits — move each joint to its range manually
python -c "
from orca_core import OrcaHand
hand = OrcaHand(port='/dev/ttyUSB0')
hand.connect()
# Enable compliance mode — move finger by hand to feel the limits
hand.set_compliance_mode(finger='index', enabled=True)
"
# If finger hits hard limit below expected range,
# loosen the extensor tendon by 0.5 turns at the tendon anchor

错误3 ROS2 joint_states 主题未发布

orca_ros2 驱动程序节点已启动，但未发布联合状态。通常是端口权限问题或 orca_core 会话冲突。

使固定：

# 1. Ensure no other orca_core session has the port open
# Close any Python scripts using the hand first

# 2. Add USB serial permissions (Linux)
sudo usermod -aG dialout $USER  # log out and back in

# 3. Re-launch with explicit port
ros2 launch orca_ros2 orca_hand.launch.py port:=/dev/ttyUSB0

# 4. Check topic
ros2 topic hz /orca_hand/joint_states   # should be ~100 Hz

以前的 ← 设置指南

下一个规格 →

软件工作正常吗？开始收集数据。

一旦所有 17 个关节都开始活动，下一步就是记录灵巧的操作过程。

数据收集指南 → Orca 官方文档在论坛上获取帮助

软件设置

orca_core SDK安装

创建虚拟环境

通过 pip 安装

通过 Poetry 安装（推荐用于开发）

验证安装并找到你的手

单独的手指控制

连接并读取所有关节位置

移动各个关节

同时设置多个关节

内置抓取基元

使用抓取原语

在抓取之间进行插值

ROS2手部接口

安装orca_ros2

启动手驱动器节点

订阅联合国家主题

发送关节位置指令

协调臂+手发射（使用OpenArm）

触觉传感器读数

读取指尖接触力

接触检测阈值

MuJoCo 模拟

安装并运行模拟

模拟到真实的传输

常见问题

软件工作正常吗？ 开始收集数据。

软件工作正常吗？开始收集数据。