Mano Orca

Configuración del software

instalación del SDK orca_core, configuración del controlador USB, API de control de dedos individuales, interfaz de mano ROS2, lectura de sensores táctiles y simulación MuJoCo. Desde una instalación de Python fresca hasta que se muevan las 17 articulaciones.

Ir a una sección:

› Instalación del SDK › API de Control de Dedos › Primitivas de Agarre › Integración de ROS2 › Sensores Táctiles › Simulación › Solución de problemas

Paso 1 — Instalación del SDK

Instalación del SDK orca_core

orca_core es el SDK oficial de Python para la Mano Orca. Se puede instalar a través de pip y es compatible con Python 3.9+. No se requiere ROS para el control básico de articulaciones.

Crear un entorno virtual

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

Instalar a través de pip

pip install orca-core

Instalar a través de Poetry (recomendado para desarrollo)

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

Verificar la instalación y encontrar tu mano

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)
"

Paso 2 — Control de Dedos API

Control Individual de Dedos

La OrcaHand la clase expone todas las 17 articulaciones a través de accesores de dedo y articulación nombrados. El modo de control predeterminado es current_based_position.

Conectar y leer todas las posiciones de las articulaciones

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()

Mover articulaciones individuales

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()

Establecer múltiples articulaciones simultáneamente

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()

Paso 3 — Primitivas de Agarre

Primitivas de Agarre Integradas

orca_core se envía con primitivas de agarre calibradas para tareas de manipulación comunes. Estas son la forma más rápida de probar el agarre básico antes de implementar políticas personalizadas.

Usando primitivas de agarre

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()

Interpolar entre agarres

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()

Paso 4 — Integración ROS2

Interfaz de Mano ROS2

La orca_ros2 el paquete proporciona una interfaz completa de ROS2 para el control coordinado de brazo + mano. Publica estados de articulaciones y acepta comandos de trayectoria de articulaciones.

Instalar 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

Lanzar el nodo del controlador de mano

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

Suscribirse al tema del estado de las articulaciones

ros2 topic echo /orca_hand/joint_states

Enviar comando de posición conjunta

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

Lanzamiento coordinado de brazo + mano (con OpenArm)

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

Esto lanza tanto el openarm_ros2 controlador del brazo como el orca_ros2 controlador de la mano bajo un solo espacio de nombres, permitiendo la ejecución de trayectorias coordinadas a través de MoveIt2.

Paso 5 — Sensores Táctiles

Lectura del Sensor Táctil

La Mano Orca monta opcionalmente sensores táctiles en las yemas de los dedos (Paxini o compatibles). Los datos táctiles fluyen de manera independiente a través de una conexión USB separada.

Lectura de la fuerza de contacto en la yema del dedo

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()

Umbral de detección de contacto

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)

Opcional — Simulación

Simulación MuJoCo

La Mano Orca se envía con modelos MJCF de MuJoCo calibrados — mano izquierda, mano derecha y una escena bimanual. La simulación comparte nombres de juntas y espacios de acción idénticos con el hardware real.

Instalar y ejecutar la simulación

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()
"

Transferir de sí a real

Los nombres de las juntas en el modelo MJCF coinciden exactamente con el orca_core SDK. Una política entrenada en simulación sobre primitivas de agarre puede ser desplegada directamente en hardware real — la única diferencia es la latencia del USB serial (~3ms) frente al tiempo de paso de física.

Solución de problemas

Problemas Comunes

Error 1 Algunos dedos no responden — escaneo parcial del servo

Generalmente, un cable en cadena no está completamente asentado en una unión entre módulos de dedos. El bus STS es una cadena — una mala conexión hace que todos los servos aguas abajo fallen.

Solución:

# 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()
"

Error 2 Dedo alcanzando límites duros — sobre tensión del tendón

Un dedo no puede extenderse o flexionarse completamente. El enrutamiento del tendón es demasiado ajustado en un lado. Ocurre más comúnmente después del reensamblaje.

Solución:

# 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

Error 3 El tema joint_states de ROS2 no está publicando

El nodo del controlador orca_ros2 se lanzó pero no está publicando los estados de las articulaciones. Generalmente es un problema de permisos de puerto o una sesión de orca_core en conflicto.

Solución:

# 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

Anterior ← Guía de configuración

Siguiente Especificaciones →

¿Software funcionando? Comienza a recopilar datos.

Una vez que las 17 articulaciones están en movimiento, el siguiente paso es grabar episodios de manipulación diestro.

Guía de recopilación de datos → Documentación oficial de Orca Obtén ayuda en el foro