step.servo.preset
=================

.. py:module:: step.servo.preset

.. autoapi-nested-parse::

   ServoPreset — named positions for a servo, generated from project YAML.

   A ``ServoPreset`` wraps a raw ``Servo`` and provides callable attributes
   for each named position. It is the recommended way to interact with servos
   that have well-defined positions (e.g., "open", "closed", "up", "down").

   Calling a position without ``speed`` uses an instant ``servo()`` command.
   Calling with ``speed`` uses ``SlowServo`` for eased motion.

   The optional ``offset`` shifts all positions by a fixed amount — useful
   when a servo is remounted slightly off from its original alignment.

   Instances are normally **code-generated** from ``raccoon.project.yml``
   into ``defs.py``, so users just import and call::

       from src.hardware.defs import Defs

       # In a mission sequence:
       Defs.pom_arm.down()            # instant
       Defs.pom_arm.up(speed=250)     # eased at 250 deg/s

   YAML definition::

       definitions:
         pom_arm:
           type: Servo
           port: 1
           offset: 0           # optional, default 0
           positions:
             down: 0
             above_pom: 50
             up: 90



Classes
-------

.. autoapisummary::

   step.servo.preset.ServoPreset


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

.. py:class:: ServoPreset(servo: raccoon.hal.Servo, positions: dict[str, float], offset: float = 0)

   Named servo positions with optional mounting offset.

   Each position becomes a callable attribute that returns a Step.

   :param servo: The underlying ``Servo`` hardware device.
   :param positions: Mapping of position name to angle in degrees.
   :param offset: Fixed angle offset added to every position (default 0).


   .. py:property:: device
      :type: raccoon.hal.Servo


      The underlying Servo hardware device, for raw access.


   .. py:property:: offset
      :type: float


      Current mounting offset in degrees.


   .. py:property:: positions
      :type: dict[str, float]


      Copy of the position name → angle mapping (before offset).