robot.heading_reference

Classes

HeadingReferenceService

Stores an absolute IMU heading reference and computes turns relative to it.

Module Contents

class robot.heading_reference.HeadingReferenceService(robot: robot.api.GenericRobot)

Bases: robot.service.RobotService

Stores an absolute IMU heading reference and computes turns relative to it.

Use robot.get_service(HeadingReferenceService) to access.

mark(origin_offset_deg: float = 0.0, positive_direction: str = 'left') → None

Capture the current absolute IMU heading as the reference.

Parameters:

• origin_offset_deg – Offset in degrees added to the captured heading. Use this to define a consistent origin regardless of the robot’s physical starting rotation. For example, if the robot is placed at 30° to the board edge but you want 0° to mean “along the board edge”, pass origin_offset_deg=-30.

• positive_direction – Which physical direction corresponds to positive angles. "left" (default) means CCW is positive, matching the standard mathematical convention. "right" flips the sign so CW is positive.

property reference_deg: float | None

The stored reference in degrees, or None if not set.

compute_turn(target_deg: float, force_direction: str | None = None) → float

Compute the signed relative turn angle to reach target_deg from reference.

Parameters:

• target_deg – Desired heading in degrees relative to the reference.

• force_direction – "left" to force CCW, "right" to force CW, or None (default) for shortest path.

Returns:

Signed angle in degrees (positive = CCW / left, negative = CW / right). Normalized to [-180, 180] for shortest path, or adjusted to the forced direction.

Raises:

RuntimeError – If no reference has been marked yet.