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. While working directly with core will let you interact with your ORCA Hand on a deep level, the Orca Ui repository (found at: https://github.com/orcahand/orca_ui) can let users get started right away, helping you setup/maintain your hand, tune its performance, and better understand its capabilities.
- Stop after a motor-bus error: a USB error in the middle of a motor transaction no longer leaves the port marked busy ("Port is in use"), so Stop and disconnect still switch torque off and close the port.
- Holding in place: goal positions are rounded to the nearest motor step instead of cut off, so a motor told to hold where it is no longer pushes against a goal one step away and heats up.
- Guided tensioning reports when its live readings stop (
sampler_failed) or torque can't be switched off at the end (torque_off_failed), and the terminal script prints these and motor faults. Asking to test a joint again is saved even when you go straight to the score. setup.yaml: writes from several programs on the same hand (the console and a script) no longer overwrite each other; they take turns throughsetup.yaml.lockbeside it.- Manual calibration asks for one joint at a time on configs without
manual_calibration_sequence:, and calibration's drive-current table only lists joints measured in that run.
- Guided tensioning (
scripts/guided_tension.py, v2.1 hands): motors pull atmax_current, settle where they stopped, then hold at each motor's ceiling while you ratchet. Avoid hard pushes on a finger while the motors hold, because they may loosen the tendon. Its currents can be overridden per motor family underguided_tension_currents:inconfig.yaml. - Slack test and tension sweep: new routines in
orca_core.maintenance(run_slack_test,run_tension_sweep), with currents per motor family. They refuse to run while a joint-feedback loop is running. Feetech values are provisional, and on Feetech a slack test pass can miss small slack. - Manual calibration:
run_calibration(manual=True)asks you to move each joint to its stops by hand, followingmanual_calibration_sequence:inconfig.yaml, and lets you step back to redo a stop. - Hardware versions: boards report three digits (
210= v2.1.0,211= v2.1.1). Older boards that report21or2are still understood, and a v2.1.1 hand also getsjoint_roms_v211:. - Records: tensioning records live in
setup.yamlbeside the config. Olderlast_tension.yamlandtension_progress.yamlare still read. - Touch sensors: the sensing link reads whatever bytes have arrived and ignores replies to earlier requests, so touch keeps working while the program is busy. Before 0.13.0, a busy program could lose touch until it reconnected.
To get started with Orca Core, follow these steps:
Pre-installation steps
-
Git clone the orca_core repository:
#use any preferred method, ssh clone shown here git clone git@github.com:orcahand/orca_core.git -
Install uv (found at: https://docs.astral.sh/uv/getting-started/)
Installing the repository
-
Sync a local development environment with
uv:uv sync --group dev
This creates a local
.venvand installs the package plus development dependencies. -
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
uvcan still install the package with:pip install .
Post-installation sample usage scripts
-
Check the configuration file:
- Review the config file (e.g.,
orca_core/models/v2/orcahand-right/config.yaml) and make sure it matches your hardware setup. Joint ranges and the guided-tensioning currents every v2 model shares are inorca_core/models/v2/shared.yaml, merged under each model'sconfig.yaml. To keep a model outside the package, write a complete copy withorca_core.write_standalone_config("my-hand/config.yaml", model_name="orcahand-right").
- Review the config file (e.g.,
-
Run the tension and calibration scripts:
uv run python scripts/detect.py uv run python scripts/guided_tension.py orca_core/models/v2/orcahand-right/config.yaml uv run python scripts/calibrate.py orca_core/models/v2/orcahand-right/config.yaml
detect.pyonly reads: it shows which model, motor type and hardware version is plugged in. Replace the path with that model's folder. Guided tensioning needs v2.1 hardware; on v2.0, usescripts/tension.pyinstead. Tension first and calibrate last.Calibration and tensioning records are saved in the hand's own folder,
~/.orca/hands/<hand id>/(see Where a hand's files live), so several hands of one model can share its config. -
Move the hand to the neutral position:
uv run python scripts/neutral.py orca_core/models/v2/orcahand-right/config.yaml
Each physical hand keeps its own files (calibration, setup records, identity) in ~/.orca/hands/<hand id>/ (set
ORCA_HOME to move ~/.orca); a model's config.yaml is only ever read. Files older versions kept beside config.yaml
are no longer read; calibrate each hand once. Details: docs/pages/orca-core-docs/hand-files.md.
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 $USERTemporary fix (resets on reboot/replug):
sudo chmod 666 /dev/ttyACM0Supported 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 -vDriver notes, latency settings and the first-connection checklist: Running on Windows.
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 →
portdisambiguates which one - motors run at a non-default baudrate →
baudrateskips the probe sweep - the auto-detection picks the wrong family →
motor_typeforces 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'