Skip to content

Robot

Robot is the top-level handle for configuration, match lifecycle, hardware, controller input, and robot status.

Constructor

Robot(endpoint: str | None = None)

When endpoint is omitted, HELM uses the HELM_LINK_ENDPOINT environment variable or falls back to tcp://127.0.0.1:5172. The extension normally sets the environment automatically when launching a script.

Constructing Robot does not open the connection. The connection is opened by configure().

configure

robot.configure(
    *,
    sensors: dict[str, type[Sensor]],
    effectors: dict[str, type[Effector]],
    pid: dict[str, tuple[float, float, float]] | None = None,
) -> None

Declares hardware, opens the extension connection, sends the configuration, and verifies the echoed result.

Raises:

  • RuntimeError if called after configuration or if verification fails;
  • ValueError for invalid port prefixes, PID targets, or PID tuple lengths;
  • TypeError when a declaration uses the wrong class category;
  • a runtime link error if the extension is unreachable or does not respond.

See Hardware configuration.

run

robot.run(
    *,
    initialize: Callable[[Robot], None] | None = None,
    autonomous: Callable[[Robot], None] | None = None,
    driver: Callable[[Robot], None] | None = None,
) -> None

Arms, invokes initialize once, dispatches phase callbacks, idles setpoints after each callback, and disarms on exit. The call blocks until POSTMATCH, ESTOP, or an exception ends the session.

Callbacks are optional. Each receives the same Robot instance.

Advanced arming methods

robot.arm() -> None
robot.disarm() -> None

arm() requires successful configuration and waits for an acknowledgement. disarm() requests disarm and suppresses communication failures during cleanup. Ordinary programs should use run() instead.

State properties

running: bool

True while an autonomous or driver callback is active in its matching phase. Use it as the condition for callback loops.

phase: Phase

Latest match phase reported through the extension.

Whether the Controller-to-robot link is healthy according to status telemetry. This does not describe the Python-to-extension connection.

estopped: bool

Reported E-Stop state. Read-only.

battery_voltage: float

Latest battery voltage in volts, or 0.0 before a usable status value arrives.

controller: Controller

Controller input object, available immediately after construction.

Hardware accessors

robot.sensor(port: str) -> Sensor
robot.effector(port: str) -> Effector
robot.thruster(port: str) -> Thruster
robot.servo(port: str) -> Servo

sensor() and effector() raise KeyError for undeclared ports. thruster() and servo() also raise TypeError when the declared effector has the wrong type.

Unique sensor types receive dynamic lowercase shortcuts, such as robot.imu and robot.radiobeacon. No shortcut is created when more than one sensor has the same type.