Main d'orque

Configuration du logiciel

Installation du SDK orca_core, configuration du pilote USB, API de contrôle individuel des doigts, interface manuelle ROS2, lecture du capteur tactile et simulation MuJoCo. D'une nouvelle installation de Python au déplacement des 17 articulations.

Accéder à une section :

›Installation de votre SDK › API de contrôle des doigts › Saisir les primitives › Intégration ROS2 › Capteurs tactiles › Simulations › Dépannage

Étape 1 — Installation du SDK

Installation de votre SDK orca_core

orca_core est le SDK Python officiel pour Orca Hand. Il est installable via pip et prend en charge Python 3.9+. Aucun ROS requis pour le contrôle conjoint de base.

Créer un environnement virtuel

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

Installateur via pip

pip install orca-core

Installer via Poetry (recommandé pour le développement)

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

Vérifiez l'installation et trouvez votre main

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

Étape 2 — API de contrôle des doigts

Contrôle individuel des doigts

Le OrcaHand La classe expose les 17 articulations via des accesseurs de doigts et d'articulations nommés. Le mode de contrôle est par défaut current_based_position.

Connectez-vous et lisez toutes les positions communes

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

Déplacer des articulations individuelles

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

Définir plusieurs joints simultanément

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

Étape 3 - Saisir les primitives

Primitives de saisie intégrées

orca_core est livré avec des primitives de préhension calibrées pour les tâches de manipulation courantes. Il s’agit du moyen le plus rapide de tester les connaissances de base avant de mettre en œuvre des politiques personnalisées.

Utiliser des primitives de saisie

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

Interpoler entre les saisies

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

Étape 4 — Intégration ROS2

Interface manuelle ROS2

Le orca_ros2 Le package fournit une interface ROS2 complète pour une commande coordonnée bras + main. Il publie les états conjoints et accepte les commandes de trajectoire conjointes.

Installateur 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

Lancez le nœud du pilote manuel

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

Abonnez-vous au sujet commun de l'État

ros2 topic echo /orca_hand/joint_states

Envoyer une commande de position commune

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

Lancement coordonné bras + main (avec OpenArm)

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

Cela lance à la fois le openarm_ros2 pilote de bras et le orca_ros2 pilote manuel sous un seul espace de noms, permettant une exécution coordonnée de trajectoire via MoveIt2.

Étape 5 — Capteurs tactiles

Lecture du capteur tactile

L'Orca Hand monte en option des capteurs tactiles du bout des doigts (Paxini ou compatible). Les données tactiles sont diffusées indépendamment via une connexion USB séparée.

Lecture de la force de contact du bout du doigt

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

Seuil de détection des contacts

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)

Facultatif — Simulation

Simulation MuJoCo

L'Orca Hand est livré avec des modèles MuJoCo MJCF calibrés – main gauche, main droite et une scène bimanuelle. La simulation partage des noms communs et des espaces d'action identiques avec le matériel réel.

Installer et exécuter la simulation

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

Transfert de simulation à réel

Les noms communs dans le modèle MJCF correspondent au orca_core SDK exactement. Une politique formée à la simulation sur des primitives de saisie peut être déployée directement sur du matériel réel — la seule différence est la latence série USB (~ 3 ms) par rapport à la synchronisation des étapes physiques.

Dépannage

Problèmes courants

Erreur 1 Certains doigts ne répondent pas - scan partiel du servo

Habituellement, un câble en guirlande n'est pas entièrement installé à la jonction entre les modules à doigts. Le bus STS est une chaîne : une mauvaise connexion fait tomber tous les servos en aval.

Réparer:

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

Erreur 2 Doigt atteignant des limites difficiles – surtension du tendon

Un doigt ne peut pas s’étendre ou fléchir complètement. L’acheminement des tendons est trop serré d’un côté. Se produit le plus souvent après le remontage.

Réparer:

# 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

Erreur 3 Le sujet joint_states ROS2 ne publie pas

Le nœud du pilote orca_ros2 a été lancé mais ne publie pas les états conjoints. Il s'agit généralement d'un problème d'autorisation de port ou d'une session orca_core conflictuelle.

Réparer:

# 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

Précédente ← Guide de configuration

Suivante Spécifications →

Le logiciel fonctionne ? Commencez à collecter des données.

Une fois que les 17 articulations bougent, l’étape suivante consiste à enregistrer les épisodes de manipulation adroite.

Guide de collecte de données → Documents officiels d'Orca Obtenir de l'aide sur le forum