orcahand/orca_core: Core Python Controller of the ORCA Hand

Orca Core is the core control package of the ORCA Hand. It's used to abstract hardware, provide scripts for calibration, tensioning and to control the hand with simple high-level control methods in joint space.

Get Started

To get started with Orca Core, follow these steps:

1. Sync a local development environment with uv:

uv sync --group dev

This creates a local .venv and installs the package plus development dependencies.

1. Run commands through uv:

uv run pytest

If you prefer an activated shell, you can still use:

source .venv/bin/activate      # macOS / Linux
    .venv\Scripts\activate         # Windows

End users who do not use uv can still install the package with:

pip install .

1. Check the configuration file:

1. Run the tension and calibration scripts:

uv run python scripts/tension.py orca_core/models/v2/orcahand-right/config.yaml
    uv run python scripts/calibrate.py orca_core/models/v2/orcahand-right/config.yaml

Replace the path with your specific hand model folder if needed.

1. Move the hand to the neutral position:

uv run python scripts/neutral.py orca_core/models/v2/orcahand-right/config.yaml

Troubleshooting

Serial Port Permissions (Linux)

On Linux, the serial port (e.g., /dev/ttyACM0) is owned by the dialout group. If your user is not in this group, you will get a permission denied error and motors won't be detected.

Permanent fix (requires re-login):

sudo usermod -aG dialout $USER

Temporary fix (resets on reboot/replug):

sudo chmod 666 /dev/ttyACM0

Windows

Supported on Windows 10 and 11; no permission setup is needed. Ports are named COM3, COM4, ... and are listed with:

uv run python -m serial.tools.list_ports -v

Driver notes, latency settings and the first-connection checklist: Running on Windows.

Serial port, baudrate, and motor type

By default these are all auto-detected at connect time.

However, you can declare them explicitly in config.yaml. Useful when:

• multiple hands are connected at once → port disambiguates which one
• motors run at a non-default baudrate → baudrate skips the probe sweep
• the auto-detection picks the wrong family → motor_type forces a specific one

# Optional overrides:   auto-detected if omitted
port: /dev/ttyACM0      # /dev/cu.usbmodemXXXX on macOS, COM3 on Windows
baudrate: 1000000       # 1M for v2; 3M for v1
motor_type: dynamixel   # or 'feetech'