Wolflib

Wolflib is a private differential-drive motion and localization library for PROS 4.2.2. It provides tracking-wheel/IMU odometry, PID-based autonomous motions, driver-control curves, learned occupancy maps, Monte Carlo localization (MCL), odometry-first pose fusion, and a compact LVGL field view.

Path assets, pure pursuit, and path following are intentionally not included.

Documentation

The API website is generated with Doxygen and the pinned Doxygen Awesome theme from README.md, docs/, and the public headers in include/wolflib. GitHub Actions builds it on every relevant push to main and publishes generated HTML to 750W/wolflib-docs. The live site is 750w.github.io/wolflib-docs.

Build the same site locally with:

git submodule update --init
doxygen Doxyfile

Then open build/docs/html/index.html.

Quick start

1. Copy the hardware layout in src/main.cpp and replace every placeholder port and dimension.
2. Configure at least one forward tracking source and an IMU. Dedicated horizontal tracking is strongly recommended for drivetrains that slide.
3. Measure each distance sensor from the tracking center. X is positive right, Y is positive forward, and sensor angles are clockwise from the front.
4. Tune the lateral and angular controllers with MCL fusion disabled.
5. Insert a FAT32 microSD card, set kMappingMode = true, drive a deliberate scan of the static field, and press X to save the map.
6. Set kMappingMode = false, rebuild, and verify loadMap() succeeds before relying on MCL corrections.

The project builds both example firmware and a reusable PROS template archive:

make all
make library
make template

Run the platform-independent regression suite on a host computer with:

cmake -S tests -B /tmp/wolflib-build -DCMAKE_BUILD_TYPE=Debug
cmake --build /tmp/wolflib-build --parallel
ctest --test-dir /tmp/wolflib-build --output-on-failure

Pose model

All chassis distances are inches and headings are degrees. The field origin is its center; positive X points right, positive Y points forward, and positive heading rotates clockwise.

Three pose products are intentionally separate:

• getOdometryPose() is raw tracking-wheel/IMU integration.
• getMclEstimate() is the raw particle estimate and uncertainty.
• getPose() is what motion controllers use.

MCL never replaces short-term odometry. When an estimate passes the configured sensor-count and covariance gates, it adjusts a bounded map-to-odometry correction. setMclFusionEnabled(false) removes that correction from getPose() without stopping the filter. resetMclToOdometry() reseeds the particles and clears the correction.

Mapping limitations

Mapping is an odometry-referenced occupancy scan, not loop-closing SLAM. A bad tracking pose produces a bad map. Scan slowly from a known pose and prioritize walls or fixed structures. Use ignoredMapRegions for areas dominated by movable game pieces. Runtime MCL uses an explicit outlier component, but no filter can make a map of constantly changing objects fully reliable.

See docs/GUIDE.md for the API, tuning, failure handling, and hardware checklist. For autonomous programming examples, motion options, queueing, and cancellation, see docs/MOTIONS.md.