CLOCKWORK

Setup

Install

You need a PROS project on kernel ^4.2.1 with LemLib already installed (pros c install LemLib).

From the depot (recommended)

pros c add-depot clockwork https://raw.githubusercontent.com/AkshobyaRaoSWE/clockwork-lib/main/depot.json
pros c apply clockwork

From a release zip

pros c fetch clockwork@1.6.0.zip
pros c apply clockwork

To upgrade later, just run pros c apply clockwork again once the depot refreshes.

Setup

Quick start

Point the helpers at your own chassis and intake motor group, then call them from your routines.

#include "clockwork/clockwork.hpp"

// chassis and intake_motors are your own configured globals.
clockwork::Motion motion(&chassis);
clockwork::Roller intake(&intake_motors);

void autonomous() {
    chassis.setPose(0, 0, 0);

    intake.in();                          // start intaking
    motion.driveDistance(30, 110, 2000);  // 30 in, heading held
    motion.turnBy(90);                    // turn 90 deg clockwise
    motion.driveFullThenSlow(18, 6, 40, 1500); // fast, then gentle
    intake.pulse(-127, 300);              // eject for 300 ms

    if (motion.driveUntilStalled(70, 1200)) // ram the wall
        chassis.setPose(0, 0, 0);           // reset odom if we hit it
}

void opcontrol() {
    while (true) {
        intake.in();       // drive the intake
        intake.antiJam();  // clears jams by itself, never blocks
        pros::delay(20);
    }
}

More complete routines are on the EXAMPLES page.

Learn

Understanding gains (kP, kI, kD)

Every "Kp" in this library is really one question: how hard should the robot push to fix a mistake? You do not need any control-theory background for this. Read it once and the rest of the library makes sense.

The one idea behind all of it

A controller is a loop that runs many times a second and asks one thing:

That gap is the error. For a drive it might be "12 inches short." For an arm it might be "30 degrees too low." The controller turns that error into a motor power, waits a few milliseconds, checks again, and repeats until the error is basically zero. The gains decide how it turns error into power.

The tuning recipe

1. Set kI = 0 and kD = 0.
2. Raise kP until it reaches the target quickly and overshoots just a little. If it shakes hard, you went too far, back off.
3. Raise kD until that overshoot and shake smooth out. If it starts buzzing, back off.
4. Only if it still stops slightly short, add a tiny kI (start around 1/50th of kP) until it closes the gap. Otherwise leave kI = 0.

Symptom, then which gain

One thing that matters: loop timing

A controller assumes it runs at a steady rhythm. Always put a fixed delay in your loop (pros::delay(10) is typical) and keep it the same. If you change the loop delay, your tuned gains change meaning and you have to re-tune. That is why every example here ends its loop with a pros::delay.

Reference

clockwork::Motion

clockwork::Motion motion(&chassis);

Every drive helper holds the heading it started at with a P controller (headingKp) and bypasses the driver curve. The distance-based ones measure from the pose at the moment you call them, so give the chassis a valid pose first with setPose. Pass negative speeds or distances to run in reverse.

• driveFullThenSlow: full speed for fullDist inches, then slowSpeed for the next slowDist. Fast approach, soft arrival.
• driveDistance: drive dist inches, easing off near the target, settling within settleRange or timing out. driveKp sets how hard it pushes per inch remaining (raise for snappier, lower if it overshoots).
• driveTimed: apply speed for ms milliseconds, then stop.
• turnBy: turn degrees relative to your current heading (positive is clockwise) using the chassis's own turn PID. Blocks until it settles.
• driveUntilStalled: drive at power until the robot stops moving (a wall, an obstacle) or times out. Returns true if it actually stalled. Great for squaring on a wall before an odom reset.

Reference

clockwork::Roller

clockwork::Roller intake(&intake_motors, 127); // second arg = default power

How anti-jam works

antiJam(int reversePower = 127, int reverseMs = 200, int jamHoldMs = 150, double velThreshold = 5.0)

Call it once per loop, right after you command the intake. It is a little state machine that reads the last power you sent, so it always knows which way you meant to run and it never blocks.

• Idle (you commanded 0): it does nothing and returns false.
• Watching: you commanded movement, so it checks the real velocity. Moving fine resets the stall timer. Below velThreshold starts the timer.
• Jam confirmed: once it has been stalled longer than jamHoldMs, it drives the group the opposite way at reversePower for a reverseMs window.
• Clearing: later calls just let the burst run, then it resumes your original command on its own and returns to watching.

while (true) {
    intake.in();
    intake.antiJam();      // reverses a 200 ms burst on a jam, then resumes
    pros::delay(20);
}

Reference

clockwork::PIDController

clockwork::PIDController pid(kP, kI, kD, integralCap = 0, outputCap = 0);

A standalone PID for anything LemLib doesn't drive: an arm, a lift, a flywheel, a wall-align. If the three numbers are new to you, read Understanding gains first.

Two constructor extras: integralCap limits how much the integral can build up (anti-windup; 0 disables it), and outputCap limits the returned power. Pass 127 for outputCap so update() never hands a motor an out-of-range command.

// arm: kP=0.9, kI=0, kD=4, integral cap 50, output clamped to motor range
clockwork::PIDController armPid(0.9f, 0.0f, 4.0f, 50.0f, 127.0f);

void moveArmTo(float targetDeg) {
    armPid.reset();
    while (!armPid.settled(2.0f)) {
        float measured = armSensor.get_position() / 100.0f;
        arm.move(armPid.update(targetDeg - measured));
        pros::delay(10); // steady loop timing, see the gains guide
    }
    arm.brake();
}

To hold a position forever, like keeping an arm up under gravity, skip the settled() exit and just keep calling update() every loop.

Reference

clockwork::AutonSelector

clockwork::AutonSelector selector(&master); // pass your pros::Controller

A controller-driven autonomous selector. You register routines by name, the driver scrolls them with the D-pad before the match, the current pick shows on the controller and brain screens, and run() runs the choice in autonomous(). It uses only core PROS, so it works on any project, no liblvgl or LLEMU.

void initialize() {
    selector.add("Left rush",  left_rush);
    selector.add("Right safe", right_safe);
    selector.add("Do nothing", [] {});
    selector.draw();
}

void competition_initialize() {
    while (true) { selector.poll(); pros::delay(20); } // driver picks here
}

void autonomous() { selector.run(); }

Reference

clockwork::SlewRateLimiter

clockwork::SlewRateLimiter slew(2.5f); // most it can move per call

Ramps a value toward a target by at most a fixed step each call, so the command eases in instead of jumping. Use it to smooth driver throttle, so a hard shove can't wheelie the robot or brown out the battery, or to bring a flywheel up to speed gently.

The step is per call, so it depends on your loop rate. At a 10 ms loop, a step of about 2.5 ramps from 0 to full power (127) over roughly half a second. Keep the loop delay steady and the ramp stays consistent.

void opcontrol() {
    while (true) {
        int y = master.get_analog(pros::E_CONTROLLER_ANALOG_LEFT_Y);
        left_mg.move(slew.calculate(y)); // eased instead of instant
        pros::delay(10);
    }
}

Reference

clockwork::Pneumatics

clockwork::Pneumatics clamp('A'); // ADI port A (or a number 1-8)

Wraps a single pneumatic piston (an ADI digital-out solenoid) for a clamp, wings, or a tilt. It remembers whether it's extended, so you can toggle it and read its state instead of tracking a loose bool.

Pass startExtended to the constructor if the piston should begin pushed out.

Reference

clockwork::Toggle

clockwork::Toggle clampToggle;

A latch that flips a boolean on the released-to-pressed edge of a button. Feed it the button state every loop and it handles the edge detection, so a single press toggles once instead of flickering while you hold it. This is what makes a one-button clamp or speed mode work.

clamp.set(clampToggle.update(master.get_digital(pros::E_CONTROLLER_DIGITAL_L1)));

Reference

clockwork::joystickCurve

float shaped = clockwork::joystickCurve(input, 2.0f, 5);

Shapes a raw joystick reading so the middle of the stick is gentler than the ends. You get fine control for small nudges and still hit full power at the extremes, which is the trick that makes a drive feel precise instead of twitchy.

left_mg.move(clockwork::joystickCurve(y + x, 2.0f, 5));

Reference

clockwork::TrapezoidalProfile

clockwork::TrapezoidalProfile profile(24.0f, 40.0f, 80.0f); // distance, maxVel, maxAccel

A speed-up / cruise / slow-down motion profile, the smooth shape you want for a move instead of slamming to full speed and back. You give it how far to go, the top speed to allow, and how hard it may accelerate; it works out the timing and tells you the target velocity and position at any moment. If the distance is too short to reach top speed it hands you a triangle instead of a trapezoid, and a negative distance profiles a reverse move.

Units are yours to pick as long as they agree: inches and inches/sec means acceleration is inches/sec² and time is seconds.

float t = (pros::millis() - start) / 1000.0f;
int power = (int)(profile.velocityAt(t) * (127.0f / 40.0f)); // velocity -> power

Reference

clockwork::FlywheelController

clockwork::FlywheelController fw(0.21f, 0.05f); // kFF, kP  (outputMax defaults to 127)

A velocity controller for a flywheel. A position PID is the wrong tool for a spinning mass, so this uses the combo that works: output = kFF * targetRpm + kP * (targetRpm - measuredRpm). The feedforward term (kFF) guesses the power to hold the target speed and does the heavy lifting; the proportional term (kP) trims the error and helps it snap back after a shot drags the wheel down. Output is clamped to [0, outputMax] because a flywheel only spins one way.

flywheel.move(fw.update(500, flywheel.get_actual_velocity()));

More

Examples

Straight rush and score

void rushAndScore() {
    clockwork::Motion motion(&chassis);
    chassis.setPose(0, 0, 0);
    intake.in();
    motion.driveFullThenSlow(36, 8, 45, 2500); // 36 in full, 8 in easing to 45
    intake.pulse(-127, 400);                   // eject
}

Wall-align and reset odometry

void alignToWall() {
    clockwork::Motion motion(&chassis);
    if (motion.driveUntilStalled(70, 1500)) {
        lemlib::Pose p = chassis.getPose();
        chassis.setPose(p.x, 0, 0); // squared up, re-zero the known axis
    }
}

Box pattern with relative turns

void box() {
    clockwork::Motion motion(&chassis);
    chassis.setPose(0, 0, 0);
    for (int i = 0; i < 4; i++) {
        motion.driveDistance(24, 110, 2000);
        motion.turnBy(90);
    }
}

The full set lives in EXAMPLES.md.

More

Testing

The pure-logic classes (PIDController and SlewRateLimiter) have no PROS or hardware dependency, so they come with tests you can run on your own computer, no V5 brain needed.

make test        # or: bash test/run.sh

That builds the tests with your system compiler and runs them. They check the proportional math, the output clamp, that a PID actually converges on a target, and that the slew limiter ramps and never overshoots.

CLOCKWORK host tests
747 checks, 0 failed
OK

The motion helpers and the selector talk to real hardware, so they are verified by building the template into a project and running it on a robot.

More

Building & releasing

You need the PROS toolchain (pros and arm-none-eabi) on your PATH.

pros make            # build the project + bin/clockwork.a
pros make template   # package clockwork@<version>.zip

To cut a release: bump VERSION in the Makefile, run pros make template, attach the zip to a GitHub release, and add an entry to depot.json. The template ships only the public headers and the compiled archive.

Versioning follows semver. See the changelog.