step.servo.steps_dsl
====================

.. py:module:: step.servo.steps_dsl

.. autoapi-nested-parse::

   Auto-generated step builders and DSL functions — DO NOT EDIT.

   Source: steps.py



Classes
-------

.. autoapisummary::

   step.servo.steps_dsl.ShakeServoBuilder
   step.servo.steps_dsl.SlowServoBuilder
   step.servo.steps_dsl.FullyDisableServosBuilder


Functions
---------

.. autoapisummary::

   step.servo.steps_dsl.shake_servo
   step.servo.steps_dsl.slow_servo
   step.servo.steps_dsl.fully_disable_servos


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

.. py:class:: ShakeServoBuilder

   Bases: :py:obj:`raccoon.step.step_builder.StepBuilder`


   Builder for ShakeServo. Auto-generated — do not edit.


   .. py:method:: servo(value: raccoon.hal.Servo | step.servo.preset.ServoPreset)


   .. py:method:: duration(value: float)


   .. py:method:: angle_a(value: float)


   .. py:method:: angle_b(value: float)


.. py:function:: shake_servo(servo: raccoon.hal.Servo | step.servo.preset.ServoPreset = _UNSET, duration: float = _UNSET, angle_a: float = _UNSET, angle_b: float = _UNSET)

   Oscillate a servo back and forth between two angles for a set time.

   Rapidly alternates the servo between ``angle_a`` and ``angle_b`` for
   the given duration. The dwell time at each angle is automatically
   estimated from the angular distance so the servo has time to
   physically reach each endpoint before reversing. Useful for shaking
   objects loose or signalling the operator.

   :param servo: The servo to control, obtained from the robot hardware map (e.g. ``robot.servo(1)``).
   :param duration: Total oscillation time in seconds. Must be >= 0.
   :param angle_a: First oscillation endpoint in degrees.
   :param angle_b: Second oscillation endpoint in degrees.

   :returns: A ShakeServoBuilder (chainable via ``.servo()``, ``.duration()``, ``.angle_a()``, ``.angle_b()``, ``.on_anomaly()``, ``.skip_timing()``).

   Example::

       from raccoon.step.servo import shake_servo

       # Shake a sorting tray for 3 seconds between 60 and 120 degrees
       shake_servo(robot.servo(1), duration=3.0, angle_a=60.0, angle_b=120.0)


.. py:class:: SlowServoBuilder

   Bases: :py:obj:`raccoon.step.step_builder.StepBuilder`


   Builder for SlowServo. Auto-generated — do not edit.


   .. py:method:: servo(value: raccoon.hal.Servo | step.servo.preset.ServoPreset)


   .. py:method:: angle(value: float)


   .. py:method:: speed(value: float)


   .. py:method:: easing(value: step.servo.steps.Easing | step.servo.steps.EasingFunc)


.. py:function:: slow_servo(servo: raccoon.hal.Servo | step.servo.preset.ServoPreset = _UNSET, angle: float = _UNSET, speed: float = 60.0, easing: step.servo.steps.Easing | step.servo.steps.EasingFunc = Easing.EASE_IN_OUT)

   Move a servo to an angle with smooth interpolated motion.

   Instead of commanding the servo to jump straight to the target (as
   ``servo()`` does), this step interpolates through intermediate
   positions using an easing curve. The default is smoothstep
   ease-in-ease-out (3t² − 2t³), which gives gentle acceleration and
   deceleration. Other curves can be selected via the ``easing``
   parameter.

   The total move duration is derived from the angular distance divided
   by ``speed``. Intermediate positions are updated at ~10 Hz.

   :param servo: The servo to control, obtained from the robot hardware map (e.g. ``robot.servo(0)``).
   :param angle: Target angle in degrees.
   :param speed: Movement speed in degrees per second. Must be positive. Defaults to 60.0 deg/s.
   :param easing: Interpolation curve. Pass an :class:`Easing` member or any callable ``(t: float) -> float`` mapping [0, 1] → [0, 1]. Defaults to ``Easing.EASE_IN_OUT``.

   :returns: A SlowServoBuilder (chainable via ``.servo()``, ``.angle()``, ``.speed()``, ``.easing()``, ``.on_anomaly()``, ``.skip_timing()``).

   Example::

       from raccoon.step.servo import slow_servo, Easing

       # Gently lower the arm servo to 20 degrees at 45 deg/s
       slow_servo(robot.servo(0), angle=20.0, speed=45.0)

       # Linear (constant-speed) motion
       slow_servo(robot.servo(0), angle=150.0, easing=Easing.LINEAR)

       # Ease-out only (fast start, slow stop)
       slow_servo(robot.servo(0), angle=0.0, easing=Easing.EASE_OUT)


.. py:class:: FullyDisableServosBuilder

   Bases: :py:obj:`raccoon.step.step_builder.StepBuilder`


   Builder for FullyDisableServos. Auto-generated — do not edit.


.. py:function:: fully_disable_servos()

   Fully disable all servo outputs, removing all power from the servo pins.

   Commands the firmware to enter the fully-disabled servo mode for every
   servo port. In this mode, no PWM signal is sent and the servos can be
   moved freely by hand. This is useful for saving power or when the
   servos should not hold position (e.g. at the end of a run).

   Servos will automatically re-enable when a new position command is
   sent (e.g. via ``servo()`` or ``slow_servo()``).

   :returns: A FullyDisableServosBuilder (chainable via , ``.on_anomaly()``, ``.skip_timing()``).

   Example::

       from raccoon.step.servo import fully_disable_servos

       # Release all servos at the end of a mission
       fully_disable_servos()