step.arm.preset
===============

.. py:module:: step.arm.preset

.. autoapi-nested-parse::

   ArmPreset — named arm positions with pre-solved servo angles.

   Named positions are resolved at codegen time (on the dev machine) via the
   raccoon-cli ArmChain generator. At runtime the Wombat only performs a dict
   lookup and issues existing servo steps — no IK library required.

   Instances are generated from ``raccoon.project.yml`` into ``defs.py``::

       definitions:
         arm:
           type: ArmChain
           joints:
             - servo: shoulder_servo
               length_cm: 12.5
               joint_range_deg: [0, 90]
               servo_range_deg: [10, 130]
           positions:
             grab_cone: {x: 18, y: 0, z: 5}

   Generated usage::

       from src.hardware.defs import Defs

       Defs.arm.grab_cone()  # instant — all joints move in parallel
       Defs.arm.grab_cone(speed=60)  # eased at 60 deg/s per joint



Classes
-------

.. autoapisummary::

   step.arm.preset.ArmPreset


Module Contents
---------------

.. py:class:: ArmPreset(joints: list[raccoon.hal.Servo], positions: dict[str, list[float]])

   Named arm positions backed by pre-solved servo angles.

   Each position becomes a callable attribute that returns a Step.
   All joints move simultaneously via ``parallel()``.

   Calling without ``speed`` issues instant ``servo()`` commands.
   Calling with ``speed`` uses ``SlowServo`` on every joint.

   :param joints: Servo hardware devices in kinematic order (base → tip).
   :param positions: Mapping of position name to pre-solved servo angles
                     in degrees (one angle per joint, same order as ``joints``).


   .. py:property:: joints
      :type: list[raccoon.hal.Servo]


      The underlying servo hardware devices in kinematic order.


   .. py:method:: to(x: float, y: float, z: float = 0.0, speed: float | None = None) -> raccoon.step.Step

      Move the arm to a Cartesian position via runtime IK.

      Requires ``ikpy`` to be installed (``pip install ikpy``).
      For competition use, prefer named positions — they are pre-solved
      at codegen time and carry zero runtime overhead.

      :param x: Target x in cm (forward from the first joint origin).
      :param y: Target y in cm (lateral).
      :param z: Target z in cm (vertical). Defaults to 0.
      :param speed: Optional speed in deg/s for eased motion.