step.watchdog
=============

.. py:module:: step.watchdog

.. autoapi-nested-parse::

   Watchdog DSL steps — arm, feed, and disarm named keepalive watchdogs.

   Watchdogs are registered with the robot's ``WatchdogManager`` and, on
   expiry, cancel the main-mission task. This triggers the normal shutdown
   path: background tasks drain, the shutdown mission runs, then the process
   exits.

   Feeding is between-step only. Long-running steps should not attempt to
   feed from inside their own update loop — use ``timeout(...)`` for
   per-step stall detection instead.

   Example::

       from raccoon.step import seq, start_watchdog, feed_watchdog, stop_watchdog
       from raccoon.step.motion import drive_forward

       seq(
           start_watchdog("scoring", timeout=5.0),
           drive_forward(30),
           feed_watchdog("scoring"),
           drive_forward(30),
           stop_watchdog("scoring"),
       )



Attributes
----------

.. autoapisummary::

   step.watchdog.DEFAULT_WATCHDOG_NAME


Classes
-------

.. autoapisummary::

   step.watchdog.StartWatchdog
   step.watchdog.FeedWatchdog
   step.watchdog.StopWatchdog


Functions
---------

.. autoapisummary::

   step.watchdog.start_watchdog
   step.watchdog.feed_watchdog
   step.watchdog.stop_watchdog


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

.. py:data:: DEFAULT_WATCHDOG_NAME
   :value: 'default'


.. py:class:: StartWatchdog(name: str, timeout: Union[float, int])

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


   Arm a named watchdog with a timeout.


.. py:class:: FeedWatchdog(name: str)

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


   Reset a named watchdog's deadline.


.. py:class:: StopWatchdog(name: str)

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


   Disarm and remove a named watchdog.


.. py:function:: start_watchdog(name: str = DEFAULT_WATCHDOG_NAME, timeout: Union[float, int] = 5.0) -> StartWatchdog

   Arm a named watchdog that will kill the robot if not fed in time.

   Registers a keepalive watchdog with the robot's ``WatchdogManager``. If
   the watchdog is not fed via ``feed_watchdog`` before ``timeout`` seconds
   elapse, it expires and cancels the main-mission task — the same code
   path used by the global ``shutdown_in`` timer. The shutdown mission
   still runs, so motors are hard-stopped and the robot parks safely.

   Multiple watchdogs can run simultaneously by using distinct names. The
   default name covers the common single-watchdog case.

   :param name: Unique identifier for this watchdog. Used by ``feed_watchdog``
                and ``stop_watchdog`` to address it. Defaults to ``"default"``.
   :param timeout: Seconds between feeds before expiry. Must be positive.

   :returns: A StartWatchdog step instance.

   Example::

       from raccoon.step import seq, start_watchdog, feed_watchdog, stop_watchdog
       from raccoon.step.motion import drive_forward

       seq(
           start_watchdog("scoring", timeout=5.0),
           drive_forward(30),
           feed_watchdog("scoring"),
           drive_forward(30),
           stop_watchdog("scoring"),
       )


.. py:function:: feed_watchdog(name: str = DEFAULT_WATCHDOG_NAME) -> FeedWatchdog

   Reset a named watchdog's deadline to prevent expiry.

   Pushes the watchdog's deadline forward by its full timeout. Feeding an
   unarmed watchdog logs a warning but does not raise.

   :param name: Identifier of the watchdog to feed. Defaults to ``"default"``.

   :returns: A FeedWatchdog step instance.

   Example::

       from raccoon.step import feed_watchdog

       feed_watchdog("scoring")


.. py:function:: stop_watchdog(name: str = DEFAULT_WATCHDOG_NAME) -> StopWatchdog

   Disarm a named watchdog so it no longer expires.

   Removes the watchdog from the manager. Stopping an unarmed watchdog
   logs a warning but does not raise — intended for cleanup paths where
   the watchdog may or may not still be active.

   :param name: Identifier of the watchdog to disarm. Defaults to ``"default"``.

   :returns: A StopWatchdog step instance.

   Example::

       from raccoon.step import stop_watchdog

       stop_watchdog("scoring")