step.watchdog

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

DEFAULT_WATCHDOG_NAME

Classes

StartWatchdog	Arm a named watchdog with a timeout.
FeedWatchdog	Reset a named watchdog's deadline.
StopWatchdog	Disarm and remove a named watchdog.

Functions

start_watchdog(→ StartWatchdog)	Arm a named watchdog that will kill the robot if not fed in time.
feed_watchdog(→ FeedWatchdog)	Reset a named watchdog's deadline to prevent expiry.
stop_watchdog(→ StopWatchdog)	Disarm a named watchdog so it no longer expires.

Module Contents

step.watchdog.DEFAULT_WATCHDOG_NAME = 'default'

class step.watchdog.StartWatchdog(name: str, timeout: float | int)

Bases: step.Step

Arm a named watchdog with a timeout.

class step.watchdog.FeedWatchdog(name: str)

Bases: step.Step

Reset a named watchdog’s deadline.

class step.watchdog.StopWatchdog(name: str)

Bases: step.Step

Disarm and remove a named watchdog.

step.watchdog.start_watchdog(name: str = DEFAULT_WATCHDOG_NAME, timeout: 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.

Parameters:

• name – Unique identifier for this watchdog. Used by feed_watchdog and stop_watchdog to address it. Defaults to "default".

• 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"),
)

step.watchdog.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.

Parameters:

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")

step.watchdog.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.

Parameters:

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")