orca-core 0.3.0__tar.gz

orca_core-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PROJECT_VERSION=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          if [ "$TAG_VERSION" != "$PROJECT_VERSION" ]; then
+            echo "Tag v$TAG_VERSION does not match pyproject.toml version $PROJECT_VERSION"
+            exit 1
+          fi
+          echo "Version check passed: $PROJECT_VERSION"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/orca_core
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

orca_core-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Run Tests on Pull Request
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: |
+          uv sync --group dev
+
+      - name: Run Tests
+        run: |
+          uv run pytest

orca_core-0.3.0/.gitignore

@@ -0,0 +1,131 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyderworkspace
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+.vscode/
+
+urdf/
+
+dev_scripts/
+
+orca_core/models/*
+
+# macOS
+.DS_Store
+
+.pytest_cache/

orca_core-0.3.0/CLAUDE.md

@@ -0,0 +1,145 @@
+# Claude Code Instructions
+
+## Project: ORCA Core
+
+Control package for the ORCA Hand - a dexterous open-source robotic hand. Provides hardware abstraction, calibration tools, and high-level joint-space control.
+
+## Project Structure
+
+```
+orca_core/
+├── api/              # High-level control API
+├── hardware/         # Hardware interfaces (motors)
+│   ├── dynamixel_client.py      # Dynamixel motor control
+├── utils/            # Shared utilities
+├── models/          # Hand configurations (YAML)
+└── core.py           # Main OrcaHand API
+
+scripts/              # CLI tools for calibration, demos
+tests/                # Unit tests
+docs/                 # Documentation
+```
+
+### Key Files
+
+- [orca_core/core.py](orca_core/core.py) - Main `OrcaHand` class API
+- [orca_core/hardware/dynamixel_client.py](orca_core/hardware/dynamixel_client.py) - Motor control interface
+- [orca_core/models/*/config.yaml](orca_core/models/) - Hand configuration files
+- [scripts/](scripts/) - Calibration and utility scripts
+
+### Hardware Components
+
+| Component | Interface | Description |
+|-----------|-----------|-------------|
+| Dynamixel Motors | `dynamixel_client.py` | Servo motor control (17 motors) |
+| Hand Configuration | `config.yaml` | Joint mapping, ROMs, calibration |
+
+---
+
+## Workflow
+
+### Git & PRs
+
+- Work on feature branches: `feature/description` or `fix/description`
+- Never push directly to `main`
+- Create PRs for all changes
+
+### Commit Guidelines
+
+- Use conventional commits: `Add feature`, `Fix bug`, `Update docs`
+- Keep messages concise and descriptive
+
+---
+
+## Code Style
+
+**Keep code clean and readable:**
+
+- Write concise, self-documenting code
+- Avoid excessive comments - prefer clear variable/function names
+- Only add comments for complex logic or non-obvious design decisions
+- Remove commented-out code before committing
+- Follow existing patterns in the codebase
+
+---
+
+## Development
+
+### Virtual Environment
+
+**IMPORTANT:** Use `uv` for Python commands and dependency management in this repo.
+
+```bash
+uv sync --group dev
+```
+
+This creates a local `.venv`. If you prefer an activated shell, use:
+
+```bash
+source .venv/bin/activate
+```
+
+Never install packages to the base/system Python environment.
+
+### Setup
+
+```bash
+uv sync --group dev
+```
+
+### Testing
+
+```bash
+uv run pytest tests/
+```
+
+### Common Scripts
+
+```bash
+# Calibration workflow
+uv run python scripts/tension.py orca_core/models/orcahand_v1_right
+uv run python scripts/calibrate.py orca_core/models/orcahand_v1_right
+uv run python scripts/neutral.py orca_core/models/orcahand_v1_right
+
+# Manual control
+uv run python scripts/slider_joint.py orca_core/models/orcahand_v1_right
+uv run python scripts/slider_motor.py orca_core/models/orcahand_v1_right
+```
+
+### Configuration
+
+All hand-specific settings are in `config.yaml`:
+- Motor-to-joint mapping
+- Joint ROMs (ranges of motion)
+- Neutral positions
+- Calibration sequences
+
+---
+
+## Technical Notes
+
+### Control Modes
+
+- `current_based_position` (recommended) - Position control with current feedback
+- `position` - Direct position control
+- `current` - Direct current control
+- `velocity` - Velocity control
+
+### Joint Naming Convention
+
+Format: `{finger}_{joint_type}`
+
+Fingers: `thumb`, `index`, `middle`, `ring`, `pinky`, `wrist`
+Joint types: `mcp`, `pip`, `dip`, `abd` (abduction)
+
+Example: `index_mcp`, `thumb_pip`
+
+---
+
+## Architecture
+
+See [docs/architecture-diagram.md](docs/architecture-diagram.md) for visual diagrams of:
+- System overview and component interactions
+- Data flow and sequence diagrams
+- Directory structure
+- Calibration workflow

orca_core-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [ORCA]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orca_core-0.3.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: orca_core
+Version: 0.3.0
+Summary: Core Python Controller of the ORCA Hand. Handles all hardware interaction, logic and abstracts control. Provides API for basic functionality and info of the hand.
+Author-email: clemens-chr <cchristoph@student.ethz.ch>, fabricenoelbourquin <fabrice.bourquin@protonmail.ch>, maximilianeberlein <meberlein@ethz.ch>, fracapuano <capuano@robots.ox.ac.uk>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: dynamixel-sdk<4.0.0,>=3.7.31
+Requires-Dist: fastapi<0.116.0,>=0.115.12
+Requires-Dist: numpy<3.0.0,>=2.2.6
+Requires-Dist: pyserial<4.0,>=3.5
+Requires-Dist: pyyaml<7.0.0,>=6.0.2
+Requires-Dist: uvicorn<0.35.0,>=0.34.2
+Description-Content-Type: text/markdown
+
+<div align="center" style="line-height: 1;">
+  <a href="https://arxiv.org/abs/2504.04259" target="_blank"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2504.04259-B31B1B?logo=arxiv"/></a>
+  <a href="https://discord.gg/xvGyxaccRa" target="_blank"><img alt="Discord" src="https://img.shields.io/badge/Discord-orcahand-7289da?logo=discord&logoColor=white&color=7289da"/></a>
+  <a href="https://x.com/orcahand" target="_blank"><img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/orcahand?style=social"/></a>
+  <a href="https://orcahand.com" target="_blank"><img alt="Website" src="https://img.shields.io/badge/Website-orcahand.com-blue?style=flat&logo=google-chrome"/></a>
+  <br>
+  <a href="https://github.com/orcahand/orca_core" target="_blank"><img alt="GitHub stars" src="https://img.shields.io/github/stars/orcahand/orca_core?style=social"/></a>
+  <a href="https://github.com/orcahand/orca_core/actions/workflows/test.yml" target="_blank"><img alt="Tests" src="https://github.com/orcahand/orca_core/actions/workflows/test.yml/badge.svg"/></a>
+</div>
+
+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`**:
+
+    ```sh
+    uv sync --group dev
+    ```
+
+    This creates a local `.venv` and installs the package plus development dependencies.
+
+2. **Run commands through `uv`**:
+
+    ```sh
+    uv run pytest
+    ```
+
+    If you prefer an activated shell, you can still use:
+
+    ```sh
+    source .venv/bin/activate
+    ```
+
+    End users who do not use `uv` can still install the package with:
+
+    ```sh
+    pip install .
+    ```
+
+3. **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.
+
+4. **Run the tension and calibration scripts**:
+
+    ```sh
+    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.
+
+5. **Move the hand to the neutral position**:
+
+    ```sh
+    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):
+
+```sh
+sudo usermod -aG dialout $USER
+```
+
+**Temporary fix** (resets on reboot/replug):
+
+```sh
+sudo chmod 666 /dev/ttyACM0
+```
+
+### 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
+
+```yaml
+# Optional overrides:   auto-detected if omitted
+port: /dev/ttyACM0      # or /'dev/cu.usbmodemXXXX' on macOS
+baudrate: 1000000       # 1M for v2; 3M for v1 
+motor_type: dynamixel   # or 'feetech'
+```
+

orca_core-0.3.0/README.md

@@ -0,0 +1,98 @@
+<div align="center" style="line-height: 1;">
+  <a href="https://arxiv.org/abs/2504.04259" target="_blank"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2504.04259-B31B1B?logo=arxiv"/></a>
+  <a href="https://discord.gg/xvGyxaccRa" target="_blank"><img alt="Discord" src="https://img.shields.io/badge/Discord-orcahand-7289da?logo=discord&logoColor=white&color=7289da"/></a>
+  <a href="https://x.com/orcahand" target="_blank"><img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/orcahand?style=social"/></a>
+  <a href="https://orcahand.com" target="_blank"><img alt="Website" src="https://img.shields.io/badge/Website-orcahand.com-blue?style=flat&logo=google-chrome"/></a>
+  <br>
+  <a href="https://github.com/orcahand/orca_core" target="_blank"><img alt="GitHub stars" src="https://img.shields.io/github/stars/orcahand/orca_core?style=social"/></a>
+  <a href="https://github.com/orcahand/orca_core/actions/workflows/test.yml" target="_blank"><img alt="Tests" src="https://github.com/orcahand/orca_core/actions/workflows/test.yml/badge.svg"/></a>
+</div>
+
+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`**:
+
+    ```sh
+    uv sync --group dev
+    ```
+
+    This creates a local `.venv` and installs the package plus development dependencies.
+
+2. **Run commands through `uv`**:
+
+    ```sh
+    uv run pytest
+    ```
+
+    If you prefer an activated shell, you can still use:
+
+    ```sh
+    source .venv/bin/activate
+    ```
+
+    End users who do not use `uv` can still install the package with:
+
+    ```sh
+    pip install .
+    ```
+
+3. **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.
+
+4. **Run the tension and calibration scripts**:
+
+    ```sh
+    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.
+
+5. **Move the hand to the neutral position**:
+
+    ```sh
+    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):
+
+```sh
+sudo usermod -aG dialout $USER
+```
+
+**Temporary fix** (resets on reboot/replug):
+
+```sh
+sudo chmod 666 /dev/ttyACM0
+```
+
+### 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
+
+```yaml
+# Optional overrides:   auto-detected if omitted
+port: /dev/ttyACM0      # or /'dev/cu.usbmodemXXXX' on macOS
+baudrate: 1000000       # 1M for v2; 3M for v1 
+motor_type: dynamixel   # or 'feetech'
+```
+

orca_core-0.3.0/demo/kapangi_replay_sequence_20250504_002233.yaml

@@ -0,0 +1,86 @@
+waypoints:
+- - -1.3838059871070456
+  - 39.50322115940708
+  - 29.727971294064197
+  - 3.9583243017137164
+  - 23.259423624484
+  - -1.4294918424607772
+  - -6.4964021105343335
+  - 0.36155512208764407
+  - -2.317030842836431
+  - 0.19268796429848578
+  - -16.086516407281145
+  - -8.04819335676791
+  - -1.0183711992257258
+  - -30.540644808170356
+  - -7.890279922866355
+  - 1.3903098387457788
+  - -6.765344072379541
+- - 11.843708014395531
+  - 33.810570990938395
+  - 39.6509771563681
+  - 14.716653238081136
+  - 20.16004390320306
+  - 41.61191935986699
+  - 48.158546502335575
+  - -0.891868436564458
+  - 21.581234833483606
+  - 12.94145956318161
+  - -11.771373854495955
+  - 4.8521717094038195
+  - 19.387890720620135
+  - -23.677574769678245
+  - 3.2740759381415074
+  - 1.292636913806362
+  - -10.32605867302501
+- - 20.288968200727723
+  - 10.141096095502142
+  - 38.111201874647584
+  - 14.34244948098383
+  - 18.093793188612146
+  - 26.65187571443417
+  - 8.794589227884572
+  - -1.3739544206614198
+  - 60.711363532662624
+  - 41.77592761266973
+  - -11.972079610186114
+  - 26.858668149988716
+  - 27.66589091710985
+  - -24.98963527595022
+  - 7.4156882107908615
+  - 1.3903098387457788
+  - -10.32605867302501
+- - 25.88522370626887
+  - -2.542548796834623
+  - 39.47989692307919
+  - 13.687600176108575
+  - 13.86736364185117
+  - 25.98326925075341
+  - 8.794589227884572
+  - -1.6632060111195983
+  - 35.67508447620737
+  - -8.705782739788873
+  - -5.248436794565741
+  - 70.39736707678503
+  - 29.398501871953258
+  - -16.309873918239095
+  - 29.294223164727043
+  - 35.18504698811759
+  - -12.084952549931714
+- - 30.362228679034846
+  - -15.226178166718157
+  - 39.565433715841124
+  - 13.219845479736946
+  - 15.182255104911214
+  - 26.40117426997817
+  - 8.794589227884572
+  - 0.45797231890703927
+  - 16.766566503702535
+  - 22.43886680240547
+  - -6.653377084396858
+  - 32.92941257099505
+  - 28.532196394531553
+  - -12.37370024273459
+  - 63.05738281491582
+  - 39.28729465482644
+  - -12.084952549931714

orca_core-0.3.0/docs/auto_docs_instructions.md

@@ -0,0 +1,23 @@
+Install dependencies first with `uv`:
+
+```sh
+uv sync --group dev --group docs
+```
+
+To test localy:
+
+```sh
+uv run mkdocs serve --clean
+```
+
+To build: 
+
+```sh
+uv run mkdocs build
+``` 
+
+To test build:
+
+```sh
+uv run python -m http.server 8000 --directory site
+```