State and sensor data¶

HELM reads are non-blocking. The library continuously caches the latest robot, sensor, and controller data received through the extension. Properties and read() methods return that cached state immediately.

Sensor readings¶

Every sensor reading includes:

reading = robot.imu.read()
if reading.ok:
    use_heading(reading.heading)
else:
    stop_or_use_a_fallback()

Before a sensor has supplied data, read() returns a typed empty reading with timestamp == 0, age == math.inf, and ok == False.

The extension and robot synchronize time when possible. During local or simulated operation without a synchronized offset, age falls back to time since the sample was received.

Units¶

IMU heading is relative, not a compass heading or absolute north.

Controller state¶

Controller input is available through robot.controller:

forward = robot.controller.left_stick.y
turn = robot.controller.right_stick.x
a_is_down = robot.controller.button("A").is_down

Controller state comes from the Controller's own input packets. It can remain available even when robot.link_ok is false, as long as the extension and Controller connection are still operating.

Buttons expose only is_down. To detect a new press, compare consecutive loop iterations:

previous = False

while robot.running:
    current = robot.controller.button("A").is_down
    if current and not previous:
        print("A was just pressed")
    previous = current

The current API accepts any non-empty button name, converts it to uppercase, and returns a cached Button. Valid physical names depend on the connected controller hardware.

Robot status¶

The robot exposes cached status through read-only properties:

robot.phase
robot.link_ok
robot.estopped
robot.battery_voltage

A default value such as False or 0.0 may mean no status packet has arrived yet. Design startup behavior accordingly.