Wolflib configuration and operation guide

Hardware configuration

wolflib::ChassisConfig owns all behavior but not PROS devices. Create motor, encoder, IMU, and distance-sensor objects with static lifetime, then pass their pointers into the configuration.

TrackingWheel supports:

• pros::adi::Encoder (360 ticks per revolution),
• pros::Rotation (centidegrees), and
• pros::MotorGroup (degrees, averaged across the group).

Its gear ratio is wheel revolutions per sensor/motor revolution. A vertical wheel offset is positive to the right. A horizontal wheel offset is positive forward.

Distance mounts use the same tracking center. The default valid interval is 0.8–78.7 inches, matching the practical 20–2000 mm V5 sensor range. Readings of 9999, PROS_ERR, out-of-range values, and low-confidence readings over 200 mm are rejected. DistanceConfidencePolicy::Ignore skips the confidence channel, RequireMinimum applies the configured threshold, and ScaleWeight also scales the observation weight from the 0–63 confidence reading.

PID and motion tuning

Tune with setMclFusionEnabled(false) so localization corrections cannot hide mechanical or odometry errors.

1. Tune angular kP, then increase kD until turns stop oscillating.
2. Tune lateral kP and kD on straight moves.
3. Add integral only for a repeatable steady-state error. windupRange limits where integral accumulates.
4. Add slew if acceleration causes wheel slip or tipping.
5. Configure small and large exit ranges and dwell times. A motion also obeys its hard timeout.

All motion methods accept an options structure. A per-motion slew value overrides the controller default; zero disables slew and a negative value inherits it. async=true enqueues and returns; async=false waits for completion. The queue is FIFO. cancelMotion stops only the active command, while cancelAllMotions also clears queued work. waitUntil reports inches for lateral motions and accumulated degrees for turn/swing motions.

moveToPose uses a boomerang/carrot controller, not pure pursuit. lead controls curvature and horizontalDrift changes how aggressively it turns into the target pose.

See Using motions for complete examples, per-motion options, queueing, waits, and cancellation.

Mapping workflow

Mapping requires a FAT32 microSD card.

1. Set the known pose with setPose.
2. Call beginMapping(true).
3. Drive slowly so every fixed surface is observed repeatedly and from several angles.
4. Call finishMappingAndSave().
5. On normal boots, call loadMap().

The .wmap format contains a versioned header, field geometry, ignored regions, log-odds grid, and CRC. Saving uses a temporary file and keeps the last valid map as .bak; loading automatically tries that backup.

Mapping pauses MCL scoring and forces controller pose to raw odometry. Finishing rebuilds the distance field, reloads the particle filter, seeds it at odometry, and restores the previous fusion setting.

MCL tuning

Start with the defaults: 200 particles, 50 ms measurements, 3-inch measurement sigma, 12% outlier probability, and at least two valid sensor readings.

• Raise translation/rotation noise when odometry regularly slips.
• Raise measurement sigma for noisy geometry or imperfect maps.
• Raise outlier probability when movable objects frequently block sensors.
• Increase particles only after measuring task timing on the brain.
• Tighten covariance gates only after observing real match data.

At least two differently oriented sensors are recommended; three or four make field symmetries less ambiguous. resetMclGlobal() is diagnostic. Competition autonomous should seed from its known starting pose.

Failure behavior

An absent SD card, invalid header/version, checksum failure, or unreadable map returns a MapStatus and disables fusion. Odometry and all PID motions remain available. Sensor failures remove only that observation. Corrections are confidence-gated, limited to 0.5 inch and 2 degrees per MCL update by default, and ramp into controller pose over 500 ms after fusion is enabled.

Hardware acceptance

• Confirm wheel and motor signs by pushing the robot forward by hand.
• Verify IMU positive rotation matches clockwise-positive headings.
• Compare physical and reported 24-inch movements and 90-degree turns.
• Confirm every distance mount reports the expected wall.
• Map, reboot, reload, and check CRC/backup recovery.
• Compare raw odometry, raw MCL, and fused pose over repeated autonomous runs.
• Move game objects into sensor beams and confirm corrections remain bounded.
• Verify the LVGL robot footprint has the correct scale and orientation.