libstp.step.servo.steps
=======================

.. py:module:: libstp.step.servo.steps


Classes
-------

.. autoapisummary::

   libstp.step.servo.steps.SetServoPosition
   libstp.step.servo.steps.ShakeServo
   libstp.step.servo.steps.EaseServo
   libstp.step.servo.steps.FullyDisableServos


Functions
---------

.. autoapisummary::

   libstp.step.servo.steps.servo
   libstp.step.servo.steps.shake_servo
   libstp.step.servo.steps.slow_servo
   libstp.step.servo.steps.fully_disable_servos


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

.. py:class:: SetServoPosition(servo: libstp.hal.Servo, target_angle: float, duration: Optional[float] = None)

   Bases: :py:obj:`libstp.step.Step`


   Set a servo to a target angle and optionally wait for the move to finish.


.. py:function:: servo(servo: libstp.hal.Servo, angle: float) -> SetServoPosition

   Set a servo to a specific angle and wait for the move to finish.

   Commands the servo to the requested angle, then sleeps for an
   estimated duration based on the angular distance the servo needs to
   travel and its approximate speed. This ensures subsequent steps do
   not begin until the servo has physically reached its target.

   The valid angle range is 0 to 170 degrees.

   :param servo: The servo to control, obtained from the robot hardware map
                 (e.g. ``robot.servo(0)``).
   :param angle: Target angle in degrees, from 0.0 to 170.0.

   :returns: A ``SetServoPosition`` step with automatically estimated wait
             duration.

   Example::

       from libstp.step.servo import servo

       # Open a claw by moving servo 0 to 90 degrees
       servo(robot.servo(0), 90.0)

       # Close the claw, then raise the arm
       sequence(
           servo(robot.servo(0), 10.0),
           motor_move_to(robot.motor(2), position=400),
       )


.. py:class:: ShakeServo(servo: libstp.hal.Servo, duration: float, angle_a: float, angle_b: float)

   Bases: :py:obj:`libstp.step.Step`


   Oscillate a servo between two angles for a fixed amount of time.


.. py:function:: shake_servo(servo: libstp.hal.Servo, duration: float, angle_a: float, angle_b: float) -> ShakeServo

   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.

   The valid angle range is 0 to 170 degrees.

   :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 (0.0 -- 170.0).
   :param angle_b: Second oscillation endpoint in degrees (0.0 -- 170.0).

   :returns: A ``ShakeServo`` step ready to be scheduled in a step sequence.

   Example::

       from libstp.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:: EaseServo(servo: libstp.hal.Servo, target_angle: float, speed: float)

   Bases: :py:obj:`libstp.step.Step`


   Move a servo to a target angle with ease-in/ease-out timing.


.. py:function:: slow_servo(servo: libstp.hal.Servo, angle: float, speed: float = 60.0) -> EaseServo

   Move a servo to an angle with smooth ease-in/ease-out motion.

   Instead of commanding the servo to jump straight to the target (as
   ``servo()`` does), this step interpolates through intermediate
   positions using a smoothstep curve (3t^2 - 2t^3). The result is a
   gentle acceleration and deceleration that avoids mechanical shock and
   reduces jerk on the mechanism.

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

   The valid angle range is 0 to 170 degrees.

   :param servo: The servo to control, obtained from the robot hardware map
                 (e.g. ``robot.servo(0)``).
   :param angle: Target angle in degrees (0.0 -- 170.0).
   :param speed: Movement speed in degrees per second. Must be positive.
                 Defaults to 60.0 deg/s, which moves the full range in about
                 2.8 seconds.

   :returns: An ``EaseServo`` step ready to be scheduled in a step sequence.

   Example::

       from libstp.step.servo import slow_servo

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

       # Use default speed for a smooth open
       slow_servo(robot.servo(0), angle=150.0)


.. py:class:: FullyDisableServos

   Bases: :py:obj:`libstp.step.Step`


   Fully disable all servo outputs, removing all power.


.. py:function:: fully_disable_servos() -> FullyDisableServos

   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 ``FullyDisableServos`` step.

   Example::

       from libstp.step.servo import fully_disable_servos

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