rotation.hpp

IRotation — a rotation / tracking-wheel sensor (pros::Rotation) behind the HAL.

This header declares 1 type (8 members).

Extracted from include/shulib/hal/rotation.hpp — this page is that header's documentation, reformatted, so it cannot disagree with the code. Prose about how to think about the API lives in the user guide; worked recipes live in the cookbook; this page is the complete, mechanical list of what exists.

Contents

• class IRotation
• ~IRotation
• IRotation
• IRotation (overload 2)
• IRotation (overload 3)
• operator=
• operator= (overload 2)
• position
• velocity

class IRotation

class IRotation

A rotation / tracking-wheel sensor behind the HAL, in canonical units (radians, rad/s). The PROS adapter converts centidegrees to radians exactly once and NEVER negates: reversal is applied once by PROS itself, decided by the SIGN of the port number the sensor is constructed on, so a consumer re-applies neither: there is no reversed boolean anywhere in this API, and the port number is the only place direction is chosen. This seam reports SHAFT rotation, not distance: turning it into travel needs a wheel diameter, localization::TrackingWheel's job. There is NO validity channel here: an implementation must always return a finite, plausible value, so the PROS adapter screens the in-band PROS_ERR sentinel by holding the last good reading rather than propagating it or zeroing. TWO CORRECTIONS TO THE NEXT SENTENCE, both measured at DEFECTS1 and both left standing here because the sentence is published. (1) The stuck-odometry cross-check reads IMotor, never this seam, and it works in DELTAS — so a pod frozen at 0 and one frozen at 12345 are indistinguishable to it, and the zero is not what hides a dead pod. (2) The screen's "never zero" holds only AFTER a first good read: the PROS adapter's last-good caches start at 0, so a pod that faults from the very first tick publishes 0 rad and 0 rad/s for the whole run, with faultedReads() > 0 beside a zero output as the only tell. The sibling seam (hal/motor.hpp) already carries its cold-start caveat; this one did not. A frozen reading, not a zeroed one, is what the loop's stuck-odometry cross-check is built to notice.

class, declared at include/shulib/hal/rotation.hpp:36.

IRotation::~IRotation

virtual ~IRotation() = default

All defaulted, and what is worth knowing here is the lifetime rather than the language rule: an implementation is REFERENCED and never owned — a TrackingWheel holds an hal::IRotation& and latches its travel baseline off it at construction — so the sensor object must outlive every wheel built on it, and every odometry built on those. The destructor is virtual only so that owning one through an IRotation* would still be well-defined; declaring it is what forces the copy and move members to be re-defaulted.

function, declared at include/shulib/hal/rotation.hpp:44.

IRotation::IRotation

IRotation() = default

Covered by the comment on ~IRotation — one comment documents this run of special members.

function, declared at include/shulib/hal/rotation.hpp:45.

IRotation::IRotation (overload 2)

IRotation(const IRotation&) = default

Covered by the comment on ~IRotation — one comment documents this run of special members.

function, declared at include/shulib/hal/rotation.hpp:46.

IRotation::IRotation (overload 3)

IRotation(IRotation&&) = default

Covered by the comment on ~IRotation — one comment documents this run of special members.

function, declared at include/shulib/hal/rotation.hpp:47.

IRotation::operator=

IRotation& operator=(const IRotation&) = default

Covered by the comment on ~IRotation — one comment documents this run of special members.

function, declared at include/shulib/hal/rotation.hpp:48.

IRotation::operator= (overload 2)

IRotation& operator=(IRotation&&) = default

Covered by the comment on ~IRotation — one comment documents this run of special members.

function, declared at include/shulib/hal/rotation.hpp:49.

IRotation::position

[[nodiscard]] virtual units::AngleDim position() const = 0

Cumulative shaft rotation (NOT wrapped) — total travel for odometry.

function, declared at include/shulib/hal/rotation.hpp:52.

IRotation::velocity

[[nodiscard]] virtual units::AngularVelocity velocity() const = 0

Measured shaft angular velocity.

function, declared at include/shulib/hal/rotation.hpp:55.

Design commentary, from the header

The header opens with the reasoning behind these shapes. It is reproduced here in full because a reference that only lists signatures teaches nobody why.

The header’s own reasoning — 8 lines

 IRotation — a rotation / tracking-wheel sensor (pros::Rotation) behind the HAL.
 Reports CUMULATIVE shaft rotation and angular velocity in canonical units
 (radians, rad/s). The hal/pros adapter converts centidegrees→radians exactly
 once and never negates: reversal is PROS's own, from a negative port number.

 position() is CUMULATIVE and must NOT wrap (it uses AngleDim, not the wrapping
 math::Angle): odometry integrates total tracking-wheel travel, not a heading.

---

Last updated 2026-08-15 — published from the main release branch, commit fa545ff. This site tracks releases, so between them it can lag the repository — that lag is deliberate, and it is what keeps the development log off the public site. For the current state of the code, see the repository.