# orcahand/orca_core architecture

> Architecture diagram of the GitHub repository orcahand/orca_core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orcahand/orca_core
- Repository: https://github.com/orcahand/orca_core

## Overview

Orca Core is the ORCA Hand control package: users configure a hand, connect through hardware abstraction, then command joint-space motion or run maintenance workflows such as tensioning and calibration. The graph also preserves encoder feedback, tactile sensing, and kinematics as distinct capabilities. Several connections rely on README statements or SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`orca_core/hardware_hand.py`](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware_hand.py) (Hand interface), [`orca_core/hardware_hand_sensing.py`](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware_hand_sensing.py) (Sensing hand interface), [`orca_core/hardware/motor_factory.py`](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/motor_factory.py) (Motor client factory), [`orca_core/hand_factory.py`](https://github.com/orcahand/orca_core/blob/main/orca_core/hand_factory.py) (Hand factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Configuration and entry"]
  node_config["Hand configuration<br/>[hand_config.py]"]
  node_factory["Hand factory<br/>[hand_factory.py]"]
  node_user_api["Python API<br/>[api.py]"]
end

subgraph group_control["Hand control"]
  node_hand["Hand interface<br/>[hardware_hand.py]"]
  node_joint_position["Joint commands<br/>[joint_position.py]"]
  node_joint_control["Joint feedback loop<br/>[joint_loop.py]"]
  node_joint_controller["Joint controller"]
end

subgraph group_hardware["Hardware access"]
  node_motor_factory["Motor client factory<br/>[motor_factory.py]"]
  node_motor_client["Motor abstraction<br/>[motor_client.py]"]
  node_dynamixel["Dynamixel driver"]
  node_feetech["Feetech driver<br/>[feetech_client.py]"]
end

subgraph group_sensing["Sensing and kinematics"]
  node_serial_link["Hand serial link"]
  node_encoder_client["Joint encoder client"]
  node_encoder_protocol["Encoder protocol"]
  node_tactile_client["Tactile client<br/>[tactile_client.py]"]
  node_sensing_hand["Sensing hand interface"]
  node_kinematics["Hand kinematics<br/>[hand_kinematics.py]"]
end

subgraph group_maintenance["Maintenance"]
  node_calibration["Calibration routine"]
  node_tensioning["Tensioning<br/>[tensioning.py]"]
  node_calibration_data["Calibration data<br/>[calibration.py]"]
  node_maintenance_scripts["Maintenance commands<br/>[calibrate.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_user_api
node_user_api -->|"exposes"| node_factory
node_factory -->|"loads"| node_config
node_factory -->|"creates"| node_hand
node_hand -->|"creates client"| node_motor_factory
node_motor_factory -->|"implements"| node_motor_client
node_motor_factory -->|"selects"| node_dynamixel
node_motor_factory -->|"selects"| node_feetech
node_hand -->|"commands"| node_joint_position
node_hand -->|"runs"| node_calibration
node_hand -->|"runs"| node_tensioning
node_calibration -->|"updates"| node_calibration_data
node_maintenance_scripts -->|"configures"| node_hand
node_operator -->|"runs"| node_maintenance_scripts
node_sensing_hand -->|"extends"| node_hand
node_sensing_hand -->|"uses"| node_tactile_client
node_sensing_hand -->|"uses"| node_joint_control
node_sensing_hand -->|"uses"| node_encoder_client
node_encoder_client -->|"reads"| node_serial_link
node_encoder_client -->|"decodes with"| node_encoder_protocol
node_tactile_client -->|"reads"| node_serial_link
node_joint_control -->|"uses"| node_joint_controller
node_sensing_hand -->|"uses"| node_kinematics

click node_config "https://github.com/orcahand/orca_core/blob/main/orca_core/hand_config.py"
click node_factory "https://github.com/orcahand/orca_core/blob/main/orca_core/hand_factory.py"
click node_user_api "https://github.com/orcahand/orca_core/blob/main/orca_core/api/api.py"
click node_hand "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware_hand.py"
click node_joint_position "https://github.com/orcahand/orca_core/blob/main/orca_core/joint_position.py"
click node_joint_control "https://github.com/orcahand/orca_core/blob/main/orca_core/control/joint_loop.py"
click node_joint_controller "https://github.com/orcahand/orca_core/blob/main/orca_core/control/joint_controller.py"
click node_motor_factory "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/motor_factory.py"
click node_motor_client "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/motor_client.py"
click node_dynamixel "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/dynamixel_client.py"
click node_feetech "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/feetech_client.py"
click node_serial_link "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/hand_serial_link.py"
click node_encoder_client "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/joint_encoder_client.py"
click node_encoder_protocol "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/sensing/encoder_protocol.py"
click node_tactile_client "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/tactile_client.py"
click node_sensing_hand "https://github.com/orcahand/orca_core/blob/main/orca_core/hardware_hand_sensing.py"
click node_kinematics "https://github.com/orcahand/orca_core/blob/main/orca_core/kinematics/hand_kinematics.py"
click node_calibration "https://github.com/orcahand/orca_core/blob/main/orca_core/maintenance/calibration_routine.py"
click node_tensioning "https://github.com/orcahand/orca_core/blob/main/orca_core/maintenance/tensioning.py"
click node_calibration_data "https://github.com/orcahand/orca_core/blob/main/orca_core/calibration.py"
click node_maintenance_scripts "https://github.com/orcahand/orca_core/blob/main/scripts/calibrate.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_factory,node_user_api toneBlue
class node_hand,node_joint_position,node_joint_control,node_joint_controller toneAmber
class node_motor_factory,node_motor_client,node_dynamixel,node_feetech toneMint
class node_serial_link,node_encoder_client,node_encoder_protocol,node_tactile_client,node_sensing_hand,node_kinematics toneRose
class node_calibration,node_tensioning,node_calibration_data,node_maintenance_scripts,node_operator toneIndigo
```

## Components

### Configuration and entry

- [Hand configuration](https://github.com/orcahand/orca_core/blob/main/orca_core/hand_config.py): `orca_core/hand_config.py`
- [Hand factory](https://github.com/orcahand/orca_core/blob/main/orca_core/hand_factory.py): `orca_core/hand_factory.py`
- [Python API](https://github.com/orcahand/orca_core/blob/main/orca_core/api/api.py): `orca_core/api/api.py`

### Hand control

- [Hand interface](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware_hand.py): `orca_core/hardware_hand.py`
- [Joint commands](https://github.com/orcahand/orca_core/blob/main/orca_core/joint_position.py): `orca_core/joint_position.py`
- [Joint feedback loop](https://github.com/orcahand/orca_core/blob/main/orca_core/control/joint_loop.py): `orca_core/control/joint_loop.py`
- [Joint controller](https://github.com/orcahand/orca_core/blob/main/orca_core/control/joint_controller.py): `orca_core/control/joint_controller.py`

### Hardware access

- [Motor client factory](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/motor_factory.py): `orca_core/hardware/motor_factory.py`
- [Motor abstraction](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/motor_client.py): `orca_core/hardware/motor_client.py`
- [Dynamixel driver](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/dynamixel_client.py): `orca_core/hardware/dynamixel_client.py`
- [Feetech driver](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/feetech_client.py): `orca_core/hardware/feetech_client.py`

### Sensing and kinematics

- [Hand serial link](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/hand_serial_link.py): `orca_core/hardware/hand_serial_link.py`
- [Joint encoder client](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/joint_encoder_client.py): `orca_core/hardware/joint_encoder_client.py`
- [Encoder protocol](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/sensing/encoder_protocol.py): `orca_core/hardware/sensing/encoder_protocol.py`
- [Tactile client](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware/tactile_client.py): `orca_core/hardware/tactile_client.py`
- [Sensing hand interface](https://github.com/orcahand/orca_core/blob/main/orca_core/hardware_hand_sensing.py): `orca_core/hardware_hand_sensing.py`
- [Hand kinematics](https://github.com/orcahand/orca_core/blob/main/orca_core/kinematics/hand_kinematics.py): `orca_core/kinematics/hand_kinematics.py`

### Maintenance

- [Calibration routine](https://github.com/orcahand/orca_core/blob/main/orca_core/maintenance/calibration_routine.py): `orca_core/maintenance/calibration_routine.py`
- [Tensioning](https://github.com/orcahand/orca_core/blob/main/orca_core/maintenance/tensioning.py): `orca_core/maintenance/tensioning.py`
- [Calibration data](https://github.com/orcahand/orca_core/blob/main/orca_core/calibration.py): `orca_core/calibration.py`
- [Maintenance commands](https://github.com/orcahand/orca_core/blob/main/scripts/calibrate.py): `scripts/calibrate.py`

### Other components

- **Operator**

## Connections

- Operator → Python API: uses
- Python API → Hand factory: exposes (evidence: `orca_core/api/api.py`)
- Hand factory → Hand configuration: loads (evidence: `orca_core/hand_factory.py`)
- Hand factory → Hand interface: creates (evidence: `orca_core/hand_factory.py`)
- Hand interface → Motor client factory: creates client (evidence: `orca_core/hardware_hand.py`)
- Motor client factory → Motor abstraction: implements (evidence: `orca_core/hardware/motor_factory.py`)
- Motor client factory → Dynamixel driver: selects (evidence: `orca_core/hardware/motor_factory.py`)
- Motor client factory → Feetech driver: selects (evidence: `orca_core/hardware/motor_factory.py`)
- Hand interface → Joint commands: commands (evidence: `orca_core/hardware_hand.py`)
- Hand interface → Calibration routine: runs (evidence: `orca_core/hardware_hand.py`)
- Hand interface → Tensioning: runs (evidence: `orca_core/hardware_hand.py`)
- Calibration routine → Calibration data: updates (evidence: `orca_core/maintenance/calibration_routine.py`)
- Maintenance commands → Hand interface: configures
- Operator → Maintenance commands: runs
- Sensing hand interface → Hand interface: extends (evidence: `orca_core/hardware_hand_sensing.py`)
- Sensing hand interface → Tactile client: uses (evidence: `orca_core/hardware_hand_sensing.py`)
- Sensing hand interface → Joint feedback loop: uses (evidence: `orca_core/hardware_hand_sensing.py`)
- Sensing hand interface → Joint encoder client: uses (evidence: `orca_core/hardware_hand_sensing.py`)
- Joint encoder client → Hand serial link: reads (evidence: `orca_core/hardware/joint_encoder_client.py`)
- Joint encoder client → Encoder protocol: decodes with (evidence: `orca_core/hardware/joint_encoder_client.py`)
- Tactile client → Hand serial link: reads (evidence: `orca_core/hardware/tactile_client.py`)
- Joint feedback loop → Joint controller: uses (evidence: `orca_core/control/joint_loop.py`)
- Sensing hand interface → Hand kinematics: uses (evidence: `orca_core/hardware_hand_sensing.py`)
