orca-core 0.3.0__py3-none-any.whl

orca_core/__init__.py

@@ -0,0 +1,28 @@
+# ==============================================================================
+# Copyright (c) 2025 ORCA
+#
+# This file is part of ORCA and is licensed under the MIT License.
+# You may use, copy, modify, and distribute this file under the terms of the MIT License.
+# See the LICENSE file at the root of this repository for full license information.
+# ==============================================================================
+from .calibration import CalibrationResult
+from .hand_config import BaseHandConfig
+from .hand_config import OrcaHandConfig
+from .hand_config import OrcaHandTouchConfig
+from .hand_config import canonical_joint_ids
+from .hardware_hand import OrcaHand
+from .hardware_hand import OrcaHandTouch
+from .joint_position import OrcaJointPositions
+from .version import LATEST_VERSION
+
+__all__ = [
+    "CalibrationResult",
+    "BaseHandConfig",
+    "OrcaHandConfig",
+    "OrcaHandTouchConfig",
+    "OrcaHand",
+    "OrcaHandTouch",
+    "OrcaJointPositions",
+    "canonical_joint_ids",
+    "LATEST_VERSION",
+]

orca_core/api/api.py

@@ -0,0 +1,365 @@
+# ==============================================================================
+# Copyright (c) 2025 ORCA
+#
+# This file is part of ORCA and is licensed under the MIT License.
+# You may use, copy, modify, and distribute this file under the terms of the MIT License.
+# See the LICENSE file at the root of this repository for full license information.
+# ==============================================================================
+
+import os
+import sys
+import time
+from fastapi import FastAPI, HTTPException, Body
+from pydantic import BaseModel, Field
+from typing import List, Dict, Optional, Union, Tuple
+import numpy as np
+import uvicorn
+from orca_core.utils.yaml_utils import read_yaml, update_yaml
+
+from orca_core import OrcaHand
+
+app = FastAPI(title="OrcaHand API", version="1.0.0")
+
+# --- Global OrcaHand Instance ---
+# Ensure necessary config files are present or adjust path as needed
+
+hand = OrcaHand()
+
+class MotorList(BaseModel):
+    motor_ids: Optional[List[int]] = None
+
+class MaxCurrent(BaseModel):
+    current: Union[float, List[float]]
+
+class JointPositions(BaseModel):
+    positions: Dict[str, float] = Field(..., example={"index_flex": 0.5, "thumb_flex": 0.2})
+
+
+def handle_hand_exception(e: Exception):
+    """Translates OrcaHand runtime errors to HTTP exceptions."""
+    if isinstance(e, RuntimeError):
+        if "not connected" in str(e).lower():
+            raise HTTPException(status_code=409, detail=f"Hand operation failed: {e}")
+        elif "not calibrated" in str(e).lower():
+             raise HTTPException(status_code=409, detail=f"Hand operation failed: {e}")
+        else:
+            raise HTTPException(status_code=400, detail=f"Hand operation failed: {e}")
+    elif isinstance(e, ValueError):
+         raise HTTPException(status_code=422, detail=f"Invalid input: {e}")
+    else:
+        raise HTTPException(status_code=500, detail=f"Internal server error: {e}")
+
+
+# --- API Endpoints ---
+@app.post("/config", summary="Set Hand Configuration", tags=["Configuration"])
+def set_hand_config(config_path: str = Body(..., example="/path/to/config")):
+    """
+    Sets or updates the hand configuration by recreating the OrcaHand object.
+
+    Args:
+        config_path (str): Path to the new configuration file.
+
+    Returns:
+        dict: Success message.
+    """
+    global hand, current_config_path
+    try:
+        if hand.is_connected():
+            hand.disconnect()
+
+        current_config_path = config_path
+        hand = OrcaHand(model_path=current_config_path)
+        return {"message": f"Hand configuration updated to: {config_path}"}
+    except Exception as e:
+        handle_hand_exception(e)
+        
+@app.post("/connect", summary="Connect to the OrcaHand", tags=["Connection"])
+def connect_hand():
+    """
+    Establishes a connection to the OrcaHand hardware.
+
+    Returns:
+        dict: Status message indicating success or failure.
+    """
+    if hand.is_connected():
+        return {"message": "Hand already connected."}
+    try:
+        success, msg = hand.connect()
+        if success:
+             return {"message": msg}
+        else:
+            raise HTTPException(status_code=500, detail=f"Connection failed: {msg}")
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.post("/disconnect", summary="Disconnect from the OrcaHand", tags=["Connection"])
+def disconnect_hand():
+    """
+    Disconnects from the OrcaHand hardware, disabling torque first.
+
+    Returns:
+        dict: Status message indicating success or failure.
+    """
+    if not hand.is_connected():
+        return {"message": "Hand already disconnected."}
+    try:
+        try:
+            hand.disable_torque()
+            time.sleep(0.1) 
+        except Exception as torque_err:
+            print(f"Warning: Error disabling torque before disconnect: {torque_err}")
+
+        success, msg = hand.disconnect()
+        if success:
+            return {"message": msg}
+        else:
+            raise HTTPException(status_code=500, detail=f"Disconnection failed: {msg}")
+    except Exception as e:
+         handle_hand_exception(e)
+
+
+@app.get("/status", summary="Get Hand Status", tags=["Status"])
+def get_status():
+    """
+    Retrieves the current connection and calibration status of the hand.
+
+    Returns:
+        dict: Contains 'connected' (bool) and 'calibrated' (bool) status.
+    """
+    try:
+        return {
+            "connected": hand.is_connected(),
+            "calibrated": hand.is_calibrated() if hand.is_connected() else False
+        }
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.post("/torque/enable", summary="Enable Motor Torque", tags=["Control"])
+def enable_torque(motor_list: MotorList = Body(None)):
+    """
+    Enables torque for specified motors or all motors if none are specified.
+
+    Args:
+        motor_list (MotorList, optional): A JSON body containing a list of motor IDs.
+                                           Example: {"motor_ids": [1, 3]}
+                                           If omitted or null, torque is enabled for all motors.
+
+    Returns:
+        dict: Success message.
+    """
+    try:
+        ids = motor_list.motor_ids if motor_list else None
+        hand.enable_torque(motor_ids=ids)
+        return {"message": f"Torque enabled for motors: {ids or 'all'}"}
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.post("/torque/disable", summary="Disable Motor Torque", tags=["Control"])
+def disable_torque(motor_list: MotorList = Body(None)):
+    """
+    Disables torque for specified motors or all motors if none are specified.
+
+    Args:
+        motor_list (MotorList, optional): A JSON body containing a list of motor IDs.
+                                           Example: {"motor_ids": [1, 3]}
+                                           If omitted or null, torque is disabled for all motors.
+
+    Returns:
+        dict: Success message.
+    """
+    try:
+        ids = motor_list.motor_ids if motor_list else None
+        hand.disable_torque(motor_ids=ids)
+        return {"message": f"Torque disabled for motors: {ids or 'all'}"}
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.post("/current/max", summary="Set Maximum Motor Current", tags=["Control"])
+def set_max_current(max_current: MaxCurrent):
+    """
+    Sets the maximum current limit for the motors.
+
+    Args:
+        max_current (MaxCurrent): A JSON body containing either a single float
+                                  (applied to all motors) or a list of floats
+                                  (one per motor, in order).
+                                  Example single: {"current": 300.0}
+                                  Example list: {"current": [300.0, 350.0, 300.0]}
+
+    Returns:
+        dict: Success message.
+    """
+    try:
+        hand.set_max_current(current=max_current.current)
+        return {"message": "Maximum current set successfully."}
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.get("/motors/position", summary="Get Motor Positions", tags=["State"])
+def get_motor_position():
+    """
+    Retrieves the current position of all motors in radians.
+
+    Returns:
+        dict: Contains a list of motor positions: {"positions": [pos1, pos2, ...]}.
+              Returns null if not connected.
+    """
+    try:
+        pos = hand.get_motor_pos()
+        return {"positions": pos.tolist() if pos is not None else None}
+    except Exception as e:
+        handle_hand_exception(e)
+
+
+@app.get("/motors/current", summary="Get Motor Currents", tags=["State"])
+def get_motor_current():
+    """
+    Retrieves the current current draw of all motors.
+
+    Returns:
+        dict: Contains a list of motor currents: {"currents": [cur1, cur2, ...]}.
+              Returns null if not connected.
+    """
+    try:
+        cur = hand.get_motor_current()
+        return {"currents": cur.tolist() if cur is not None else None}
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.get("/motors/temperature", summary="Get Motor Temperatures", tags=["State"])
+def get_motor_temperature():
+    """
+    Retrieves the current temperature of all motors.
+
+    Returns:
+        dict: Contains a list of motor temperatures: {"temperatures": [temp1, temp2, ...]}.
+              Returns null if not connected.
+    """
+    try:
+        temp = hand.get_motor_temp()
+        return {"temperatures": temp.tolist() if temp is not None else None}
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.get("/joints/position", summary="Get Joint Positions", tags=["State"])
+def get_joint_position():
+    """
+    Retrieves the current position of all calibrated joints.
+
+    Returns:
+        dict: A dictionary mapping joint names to their positions:
+              {"positions": {"joint1": pos1, "joint2": pos2, ...}}.
+              Returns null for positions if not connected or not calibrated.
+              Individual joint values might be null if that specific joint isn't calibrated yet.
+    """
+    try:
+        j_pos = hand.get_joint_pos()
+        return {"positions": j_pos}
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.post("/joints/position", summary="Set Joint Positions", tags=["Control"])
+def set_joint_position(joint_positions: JointPositions):
+    """
+    Sets the desired positions for specified joints. Requires calibration.
+
+    Args:
+        joint_positions (JointPositions): A JSON body containing a dictionary
+                                          mapping joint names to desired positions (in radians).
+                                          Example: {"positions": {"index_flex": 1.0, "thumb_oppose": 0.5}}
+
+    Returns:
+        dict: Success message.
+    """
+    try:
+        hand.set_joint_pos(joint_pos=joint_positions.positions)
+        return {"message": "Joint positions command sent successfully."}
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.get("/calibrate/status", summary="Get Calibration Status", tags=["Calibration"])
+def get_calibration_status():
+    """
+    Checks if the hand is fully calibrated.
+
+    Returns:
+        dict: Contains 'calibrated' (bool) status.
+    """
+    try:
+        return {"calibrated": hand.is_calibrated()}
+    except Exception as e:
+        handle_hand_exception(e)
+
+@app.post("/calibrate")
+def calibrate_auto():
+    """
+    Starts the automatic calibration routine defined in the configuration.
+    This might take some time.
+
+    Returns:
+        dict: Message indicating calibration start and eventual result.
+    """
+    if not hand.is_connected():
+         raise HTTPException(status_code=409, detail="Hand must be connected to calibrate.")
+    try:
+        hand.calibrate()
+        calib_status = hand.is_calibrated()
+        msg = "Automatic calibration finished." + (" Successfully." if calib_status else " Failed or incomplete.")
+        return {"message": msg, "calibrated": calib_status}
+    except Exception as e:
+        handle_hand_exception(e)
+        
+# @app.get("/config/settings", summary="Get Current Configuration Settings", tags=["Configuration"])
+# def get_config_settings():
+#     """
+#     Retrieves the current configuration settings from the file.
+
+#     Returns:
+#         dict: Current configuration settings.
+#     """
+#     global current_config_path
+#     try:
+#         if not current_config_path:
+#             raise HTTPException(status_code=400, detail="No configuration file is currently loaded.")
+#         config_data = read_yaml(current_config_path)
+#         return {"config": config_data}
+#     except Exception as e:
+#         handle_hand_exception(e)
+
+
+# @app.put("/config/settings", summary="Update Configuration Settings", tags=["Configuration"])
+# def update_config_settings(updated_settings: dict = Body(...)):
+#     """
+#     Updates specific settings in the configuration file and reloads the OrcaHand object.
+
+#     Args:
+#         updated_settings (dict): A dictionary containing the settings to update.
+
+#     Returns:
+#         dict: Success message.
+#     """
+#     global hand, current_config_path
+#     try:
+#         if not current_config_path:
+#             raise HTTPException(status_code=400, detail="No configuration file is currently loaded.")
+        
+#         # Read the current configuration
+#         config_data = read_yaml(current_config_path)
+        
+#         # Update the configuration with the new settings
+#         config_data.update(updated_settings)
+        
+#         # Write the updated configuration back to the file
+#         write_config_file(current_config_path, config_data)
+        
+#         # Reinitialize the OrcaHand object with the updated configuration
+#         if hand.is_connected():
+#             hand.disconnect()
+#         hand = OrcaHand(model_path=current_config_path)
+        
+#         return {"message": "Configuration updated successfully.", "updated_config": config_data}
+#     except Exception as e:
+#         handle_hand_exception(e)
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

orca_core/base_hand.py

@@ -0,0 +1,244 @@
+# ==============================================================================
+# Copyright (c) 2025 ORCA
+#
+# This file is part of ORCA and is licensed under the MIT License.
+# You may use, copy, modify, and distribute this file under the terms of the MIT License.
+# See the LICENSE file at the root of this repository for full license information.
+# ==============================================================================
+
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+
+import numpy as np
+
+from .demo_presets import DEMO_POSE_FRACTIONS, DEMO_SEQUENCES
+from .hand_config import BaseHandConfig
+from .joint_position import OrcaJointPositions
+
+from .constants import NUM_STEPS, STEP_SIZE
+
+
+class BaseHand(ABC):
+    """Abstract base class defining the shared joint-space interface for all ORCA hand backends.
+
+    Concrete subclasses implement :meth:`_get_joint_positions` and
+    :meth:`_set_joint_positions`.
+    All higher-level motion helpers (interpolation, normalisation, neutral
+    position) live here so they are available regardless of backend.
+
+    On construction the hand loads its :class:`~orca_core.BaseHandConfig`,
+    validates it, and registers its default joint ordering with
+    :class:`~orca_core.OrcaJointPosition`.
+
+    The class exposes methods for:
+    - Setting joint positions, thus reaching arbitrary hand specifications
+    - Recording and replaying named positions
+    - Moving to the neutral position defined in the hand configuration file, ``config.yaml``.
+
+    Args:
+        config_path: Path to a ``config.yaml`` file. When ``None`` the default
+            model bundled with the package is used.
+    """
+
+    config_cls = BaseHandConfig
+
+    def __init__(
+        self,
+        config_path: str | None = None,
+        config: BaseHandConfig | None = None,
+        model_version: str | None = None,
+        model_name: str | None = None,
+        **config_kwargs,
+    ):
+        self.config = (
+            config
+            if config is not None
+            else self.config_cls.from_config_path(
+                config_path=config_path,
+                model_version=model_version,
+                model_name=model_name,
+                **config_kwargs,
+            )
+        )
+        self.config.validate()
+        OrcaJointPositions.register_joint_names(self.config.joint_ids)
+
+        self.recorded_positions: dict[str, OrcaJointPositions] = {}
+
+    @abstractmethod
+    def _get_joint_positions(self) -> OrcaJointPositions:
+        """Return the current joint configuration."""
+        pass
+
+    @abstractmethod
+    def _set_joint_positions(self, joint_pos: OrcaJointPositions) -> bool:
+        """Apply a joint-space command. Return ``True`` if the command was applied."""
+        pass
+
+    def _coerce_joint_positions(
+        self,
+        joint_pos: OrcaJointPositions | Mapping[str, float | None] | np.ndarray,
+    ) -> OrcaJointPositions:
+        if isinstance(joint_pos, OrcaJointPositions):
+            return joint_pos
+
+        if isinstance(joint_pos, Mapping):
+            return OrcaJointPositions.from_dict(dict(joint_pos))
+
+        if isinstance(joint_pos, np.ndarray):
+            return OrcaJointPositions.from_ndarray(joint_pos, joint_ids=self.config.joint_ids)
+
+        raise TypeError(
+            "joint_pos must be an OrcaJointPositions instance, a mapping, or a 1-D numpy array."
+        )
+
+    def pose_from_fractions(
+        self,
+        fractions: Mapping[str, float],
+    ) -> OrcaJointPositions:
+        """Build a pose by specifying joints as fractions of their ROM, read from config."""
+        pose_dict = {joint: 0.0 for joint in self.config.joint_ids}
+        pose_dict.update(self.config.neutral_position)
+
+        for joint, fraction in fractions.items():
+            if joint not in self.config.joint_roms_dict:
+                continue
+
+            joint_min, joint_max = self.config.joint_roms_dict[joint]
+            pose_dict[joint] = joint_min + float(fraction) * (joint_max - joint_min)
+
+        return self.config.clamp_joint_positions(OrcaJointPositions.from_dict(pose_dict))
+
+    def set_joint_positions(
+        self,
+        joint_pos: OrcaJointPositions | Mapping[str, float | None] | np.ndarray,
+        num_steps: int = 1,
+        step_size: float = 1e-2,
+    ):
+        """Command the hand to a target joint configuration.
+
+        Positions are clamped to configured ROM bounds before being sent to
+        the hardware for increased safety.
+        When *num_steps* > 1 the motion is linearly interpolated
+        from the current position, with a ``time.sleep(step_size)`` pause
+        between each intermediate waypoint.
+
+        Args:
+            joint_pos: Target joint positions as an
+                :class:`~orca_core.OrcaJointPosition`, a ``dict``, or a 1-D
+                ``np.ndarray`` aligned with :attr:`joint_ids`.
+            num_steps: Number of interpolation steps. Use ``1`` for an
+                immediate move (default). Simulation hands should always use ``1``.
+            step_size: Sleep duration in seconds between interpolated steps.
+                Ignored when *num_steps* is ``1``.
+        """
+        joint_pos = self._coerce_joint_positions(joint_pos)
+        joint_pos = self.config.clamp_joint_positions(joint_pos)
+        waypoints = self._linear_waypoints_to(joint_pos, num_steps)
+        for i, wp in enumerate(waypoints):
+            self._set_joint_positions(wp)
+            if i < len(waypoints) - 1:
+                time.sleep(step_size)
+
+    def get_joint_position(self) -> OrcaJointPositions:
+        return self._get_joint_positions()
+
+    def _linear_waypoints_to(
+        self, target: OrcaJointPositions, num_steps: int
+    ) -> list[OrcaJointPositions]:
+        """Return linear waypoints from current pose to *target*."""
+        # TODO(fracapuano): Move this to a stateless util function
+        if num_steps <= 1:
+            return [target]
+
+        current = self._get_joint_positions()
+        out: list[OrcaJointPositions] = []
+        for step in range(num_steps + 1):
+            t = step / num_steps
+            out.append(
+                OrcaJointPositions.from_dict({
+                    joint: current.data[joint] * (1 - t)
+                    + target.data.get(joint, current.data[joint]) * t
+                    for joint in current.data
+                })
+            )
+        return out
+
+    def register_position(self, name: str, joint_pos: OrcaJointPositions):
+        self.recorded_positions[name] = self.config.clamp_joint_positions(joint_pos)
+
+    def remove_position(self, name: str):
+        try:
+            del self.recorded_positions[name]
+        except KeyError:
+            pass  # position was not among recorded positions
+
+    def set_named_position(self, name: str, num_steps: int = 1, step_size: float = 1.0):
+        self.set_joint_positions(self.recorded_positions[name], num_steps=num_steps, step_size=step_size)
+
+    def play_named_positions(
+        self,
+        names: Sequence[str],
+        cycles: int = 1,
+        num_steps: int = 1,
+        step_size: float = 1.0,
+        return_to_neutral: bool = False,
+        neutral_num_steps: int | None = None,
+        neutral_step_size: float | None = None,
+    ) -> None:
+        if cycles < 0:
+            raise ValueError("cycles must be non-negative.")
+
+        for _ in range(cycles):
+            for name in names:
+                self.set_named_position(name, num_steps=num_steps, step_size=step_size)
+            if return_to_neutral:
+                self.set_neutral_position(
+                    num_steps=num_steps if neutral_num_steps is None else neutral_num_steps,
+                    step_size=step_size if neutral_step_size is None else neutral_step_size,
+                )
+
+    def run_demo(
+        self,
+        demo_name: str = "main",
+        cycles: int = 1,
+        num_steps: int = NUM_STEPS,
+        step_size: float = STEP_SIZE,
+        return_to_neutral: bool = True,
+    ) -> tuple[str, ...]:
+        if demo_name not in DEMO_POSE_FRACTIONS or demo_name not in DEMO_SEQUENCES:
+            available = ", ".join(sorted(DEMO_SEQUENCES))
+            raise ValueError(f"Unknown demo '{demo_name}'. Available demos: {available}.")
+
+        poses = {
+            name: self.pose_from_fractions(fractions)
+            for name, fractions in DEMO_POSE_FRACTIONS[demo_name].items()
+        }
+        sequence = DEMO_SEQUENCES[demo_name]
+
+        for _ in range(cycles):
+            for name in sequence:
+                self.set_joint_positions(poses[name], num_steps=num_steps, step_size=step_size)
+            
+            if return_to_neutral:
+                self.set_neutral_position(num_steps=num_steps, step_size=step_size)
+
+        return sequence
+
+    def set_neutral_position(self, num_steps: int = NUM_STEPS, step_size: float = STEP_SIZE):
+        """Move hand to neutral position."""
+        self.set_joint_positions(
+            OrcaJointPositions.from_dict(self.config.neutral_position),
+            num_steps=num_steps,
+            step_size=step_size,
+        )
+
+    def set_zero_position(self, num_steps: int = NUM_STEPS, step_size: float = STEP_SIZE):
+        self.set_joint_positions(
+            OrcaJointPositions.from_dict(
+                {joint: 0.0 for joint in self.config.joint_ids}
+            ),
+            num_steps=num_steps,
+            step_size=step_size,
+        )