Skip to content

Troubleshooting

The extension is unreachable

Typical message:

Extension not reachable at tcp://127.0.0.1:5172

Check that:

  • the HELM extension is running;
  • the script was launched from the extension;
  • no other HELM Python client is already connected;
  • a custom HELM_LINK_ENDPOINT or Robot(endpoint=...) value is correct.

The Python API does not connect directly to USB.

Configuration does not match

Robot.configure() compares the declared hardware with the response returned through the extension. A mismatch raises RuntimeError before arming.

Check every sensor, effector, port, and PID entry against the physical robot configuration. Do not catch this error and continue into a match.

A port declaration is rejected

  • Sensor port keys must begin with S.
  • Effector port keys must begin with A.
  • Sensor values must be Sensor subclasses such as IMU.
  • Effector values must be Effector subclasses such as Thruster.
  • PID gains may be supplied only for declared thruster ports.

Pass classes, not constructed objects:

sensors={"S2": IMU}
effectors={"A1": Thruster}

An accessor raises KeyError

The requested port was not declared in configure():

robot.sensor("S2")
robot.effector("A1")

Use the same port spelling as the configuration mapping.

A typed accessor raises TypeError

robot.thruster(port) and robot.servo(port) verify the configured type. Use the accessor matching the declaration, or use robot.effector(port) when code intentionally accepts either type.

robot.imu or robot.radiobeacon is missing

Dynamic shortcuts are installed only when exactly one sensor has that type. With multiple IMUs or beacons, use the explicit port accessor:

reading = robot.sensor("S1").read()

Explicit accessors are also easier for static analysis and editor completion.

A sensor reading has ok == False

The sample is missing, marked invalid, or more than 250 ms old. Inspect reading.age, check robot.link_ok, and use a safe fallback. Do not command motion based on stale sensor values.

set_power() says battery voltage is invalid

Thruster.set_power() needs cached battery voltage above 0.1 V. Wait for valid status telemetry and verify the robot link and battery before using power mode. Use set_duty() or set_current() only when that behavior is appropriate for your robot.

A current-limit warning appears

The request exceeds the library's current thruster limit, currently 4.0 A. Python warns but sends the request; the robot brain performs the final clamp. Reduce the requested current unless the robot's documented configuration specifically calls for a different behavior.

A command value cannot be encoded

Effector commands use a signed 13-bit value. Extremely large current, angle, duty, or pulse-width values raise ValueError. Stay within the documented hardware ranges rather than relying on encoding limits.

A callback stops running

robot.running becomes false when its autonomous or driver phase ends. A callback that returns early is not invoked again during that same phase, and HELM idles all effector setpoints. Keep the phase's ongoing behavior inside:

while robot.running:
    ...

Controller input and robot telemetry travel through different parts of the system. The Controller can continue reporting sticks and buttons while the Controller-to-robot link is down. Treat link_ok == False as a robot-link failure even if gamepad values still change.