Skip to content

Effectors

Effector objects are created by Robot.configure(). Commands are buffered and sent repeatedly through the extension.

Effector

Effector(port: str, state_mirror=None)

Base class for effectors. It is public for extension and advanced use, but students normally configure Thruster or Servo.

Attributes

effector.port: str
effector.type: str

Thruster

set_duty

thruster.set_duty(duty: float) -> None

Sets open-loop duty. The intended range is −100 to 100. The value is rounded to an integer. The current Python implementation does not clamp to the intended range; values that cannot fit the command field raise ValueError.

set_current

thruster.set_current(amps: float) -> None

Sets the closed-loop current target in amps. The value is encoded in 0.01 A steps.

The built-in thruster specification currently has a 4.0 A current limit. Requests above that magnitude issue a warning and are still sent so the robot brain can apply its authoritative clamp. Unencodable values raise ValueError.

set_power

thruster.set_power(watts: float) -> None

Divides watts by the latest cached battery voltage and sends the resulting current command. Raises RuntimeError when no valid voltage above 0.1 V is available. The result is approximate because voltage telemetry may be slightly stale.

current: float

Latest measured current in amps. Returns 0.0 when telemetry is absent.

power: float

Latest measured power in watts. Uses reported power when available; otherwise returns cached battery voltage multiplied by current.

Servo

angle

servo.angle(deg: float) -> None

Sets servo position in degrees, encoded in 0.1-degree steps. Intended range: 0 to 180 degrees.

micros

servo.micros(us: int) -> None

Sets raw pulse width in microseconds. Intended range: 500 to 2500 µs.

The current Python implementation does not clamp either servo method to its intended range. It rejects only values that cannot fit the command field. The robot remains responsible for hardware-safe enforcement.

Errors shared by effectors

  • Commands on an unattached, directly constructed effector raise RuntimeError.
  • A command mode not allowed for the effector type raises TypeError.
  • A command value outside the signed 13-bit representation raises ValueError.
  • Typed robot accessors raise TypeError when the port has the wrong effector.