Current Control uses a PID controller to run the motor at a consistent current providing a consistent torque. The PID controller is run using the setpoint, in Amps, and the internally measured current draw.

It is called as shown below:

m_controller.setReference(setPoint, ControlType.kCurrent);

using namespace rev::spark;

m_controller.SetReference(setPoint, SparkBase::ControlType::kCurrent);

MAXMotion Velocity Control utilizes the MAXMotion parameters to improve upon velocity control. Honoring the maximum acceleration, MAXMotion Velocity Control will speed up your flywheel or rotary mechanism in a controlled way, reducing power draw and increasing consistency.

MAXMotion Velocity Control utilizes an internal velocity closed-loop controller, so transitioning from Velocity Control mode to MAXMotion Velocity Control is as simple as setting a maximum acceleration and changing the setReference call.

It is called as seen below:

m_controller.setReference(setPoint, ControlType.kMAXMotionVelocityControl);

using namespace rev::spark;

m_controller.SetReference(setPoint, SparkBase::ControlType::kMAXMotionVelocityControl);

Tips for Smooth Motions

• If your motion seems jittery, try reducing your PID constants, especially P. If the underlying velocity PID outruns the acceleration target, the motion may seem jittery and the velocity will not increase smoothly.

• Make sure your units are correct: maximum velocity is set in RPM by default and maximum acceleration is set in RPM per second by default.

• At low speeds, the acceleration may seem wobbly or inconsistent if the loop has been tuned for higher speeds or vice versa. If both are needed, try tuning separate PIDs and switching between slots when needed. This may be easier than finding those perfect constants that work beautifully across the board.

Migrating from Smart Velocity

All Smart Velocity constants and PIDs can be transferred to MAXMotion Velocity Mode. Be sure to transcribe any Smart Motion parameters to the MAXMotion parameters.

MAXMotion Position Control is a second-degree closed loop controller, allowing for smooth and consistent motions from one position to another by limiting both the velocity and acceleration of the motor. These can be configured via the MAXMotion Parameters, setting a target acceleration and a "cruise" velocity. The motor will spin up, honoring the acceleration target, hold speed at the cruise velocity, and then slow down honoring the acceleration target to arrive at the setpoint.

MAXMotion Position Control runs on top of an internal position PID controller, so the tuning process begins similarly to a typical position closed loop controller, with the P and D constants (See Getting Started with PID Tuning for more on this). Note that these values may need tweaked once you set your velocity and acceleration targets in order to smooth out the motion.

When setting your maximum velocity and maximum acceleration parameters, keep a few things in mind:

• Maximum velocity is in units of revolutions per minute by default

• Maximum acceleration is in units of RPM per second by default

• Your current limits may interfere with motions that move too quickly or hold against gravity for too long

• Try to achieve a good balance of smoothness and consistency with speed

Tips for Smooth Motions

• If your motion seems jittery, try adjusting your PID constants. If the target acceleration is faster or slower than your PIDs allow, the mechanism may appear to shake or jitter and speed and accuracy will be lost.

• Keep an eye on the current draw, as hitting limits may interfere with the functionality of MAXMotion. Increasing current limits or changing the gear ratio on your mechanism can help reduce the chances of this happening.

• Feed forwards may help smoothness but also may hurt it, depending on your mechanism. MAXMotion may be able to handle the motion on its own without any help at all.

• As MAXMotion runs on an underlying position closed loop controller, a kF gain is not recommended and may lead to unexpected results. Instead, lean on the PID constants to handle this.

Using MAXMotion

After tuning your constants, calling MAXMotion is as simple as passing in the setpoint to the controller.

m_controller.setReference(setPoint, SparkBase.ControlType.kMAXMotionPositionControl);

using namespace rev::spark;

m_controller.SetReference(setPoint, SparkBase::ControlType::kMAXMotionPositionControl);

Migrating from Smart Motion

Smart Motion used a different method for smooth second-degree motion control, but MAXMotion can be applied anywhere Smart Motion was previously. Maximum velocity and acceleration constants may be transferable, but should be tested with caution. All other constants will need re-tuned from scratch, including all PIDs.

MAXMotion has several improvements over Smart Motion, and should offer better consistency, a better tuning experience, better position retention, and an all-around better user experience. It is highly recommended to migrate all systems using Smart Motion to MAXMotion.

For a detailed technical and mathematical description of each term and its effect, the WPILib docs page on PID is a good resource.

FRC Usage

In FRC, PID loops are used in many types of mechanisms, from flywheel shooters to vertical arms. These need to be tuned to different constants, depending on the units they use and the physical design of the mechanism, however the process to find these constants is roughly the same.

Most teams find success using controllers tuned primarily with P and D, using a Feed Forward to account for steady-state error.

The Constants

P - Proportional Gain

P, the proportional gain, is the primary factor of the control loop. This is multiplied by the error and that gain is added to the output. This does the heavy lifting of the motion, pushing the motor in the direction it needs to go.

I - Integral Gain

I, the integral gain, is not often recommended in FRC. It is useful for eliminating steady-state error, or error that the other gains leave behind and cannot address. It accumulates the error over time and multiplies it by the I gain, gradually increasing the power it supplies until that has evened out. If it is needed, it's recommended to use a limited to prevent I windup.

D - Derivative Gain

The derivative gain, D, is used to tune out oscillation and dampen the motion. It resists motion, decreasing power when the mechanism is moving. A good balance of P and D is needed to make a smooth motion with no oscillation.

Tuning

Several guides for PID tuning are available, such as this one on the WPILib docs. It may be useful to consult multiple, especially those available that reference your specific mechanism.

Any method for PID tuning will start with the same concept, however, regardless of mechanism. Before you can tune your mechanism, you should setup a graph of the setpoint and that measured value, either through the REV Hardware Client or a similar utility. This will allow you to analyze each test and properly evaluate the changes to make.

To then tune a basic PID loop, follow the steps below:

1. Set all constants (P, I, D, F, arb Feed Forward, etc) to 0

2. If you are operating in Velocity Control Mode (or a velocity-based control mode), set F to the motor's value as discussed in F Parameter

3. Ensure the mechanism is safe to actuate. This process will spin the motor, potentially at unexpected speeds and in unexpected directions

4. Check the direction of the motor, and invert it if needed so that positive output is in the desired direction

5. Set P to a very small number, relative to the units you are working in

6. Set a target for the motor to move to. Ensure this is within the range of your mechanism.

7. Gradually increase P until you see movement, by small increments

8. Once you see motion, increase P by small increments until it reaches the target at the desired speed

9. If you see oscillation, decrease P or begin to increment D by a small amount

10. Continue to adjust these parameters until the motion is quick, precise, and repeatable

Arbitrary Feed Forward

The SPARK Flex and SPARK MAX do not have any support for more complex physics-based Feed Forward models, but do include a means of applying an arbitrary voltage which can be calculated in your team code and passed to the API.

It can be applied with the setpoint as seen below:

// Set the setpoint of the controller in raw position mode, with a feedforward
m_controller.setReference(
    setPoint, 
    ControlType.kPosition,
    0,
    feedForward
);

using namespace rev::spark;

// Set the setpoint of the controller in raw position mode, with a feedforward
m_controller.SetReference(
    setPoint, 
    SparkBase::ControlType::kPosition,
    0,
    feedForward
);

Velocity Control uses the PID controller to run the motor at a set speed in RPM. An FF gain, as detailed in F Parameter, is your friend in finding consistency when tuning this mode.

It is called in the same way as Position Control:

m_controller.setReference(setPoint, ControlType.kVelocity);

using namespace rev::spark;

m_controller.SetReference(setPoint, SparkBase::ControlType::kVelocity);

Position Control is used to point the motor in a specific direction. It takes a setpoint in rotations and uses the PID loop to move to that position. The Position control mode pipes directly into a PID controller with the configured encoder.

A properly tuned Position control loop should respond quickly and accurately to a setpoint change and should not oscillate around the target.

To run the motor in Position control mode, set the PID Controller setpoint as shown below.

m_controller.setReference(setPoint, ControlType.kPosition);

using namespace rev::spark;

m_controller.SetReference(setPoint, SparkBase::ControlType::kPosition);

The Smart Velocity control mode utilizes the Smart Motion parameters to improve upon velocity control. Honoring the maximum acceleration, Smart Velocity will speed up and slow down your flywheel or rotary mechanism in a controlled way, reducing power draw and increasing consistency.

It is called as seen below:

m_controller.setReference(setPoint, ControlType.kSmartVelocity);

using namespace rev::spark;

m_controller.SetReference(setPoint, SparkBase::ControlType::kSmartVelocity);

Closed-Loop Control Basics

A Closed-Loop Control System in its most basic form is a process that uses feedback to improve the accuracy of its outputs. Closed-Loop Control Systems, sometimes referred to as Feedback Controllers, are frequently used when maintaining or reaching a steady output is important or if the system may have outside influences that could affect the system's output.

A simple example using this type of Control is an automatic coffee maker. In its Closed-Loop Control System, the output is hot coffee and the process we are getting feedback on is the heating of the water. If the coffee maker receives feedback that the water is cold, it will start to heat the pot. When the water is almost hot enough to brew the coffee, the control algorithm will continue to heat the water until the correct goal temperature has been reached. Once the water reaches it's goal temperature, or if it gets too hot, the system will stop heating the water and wait until it receives feedback that the heater needs to begin again.

Closed-Loop Control with SPARK Motor Controllers

Closed-Loop Control is a staple of complex FRC mechanism programming. WPILib offers several sets of libraries to allow teams to run PID loops on the roboRIO, but they require setup in your team's code and can only update every 20ms.

With a PID loop onboard a SPARK Motor Controller, the setup is simple, doesn't clutter your code, and the loop is updated every 10ms, doubling the responsiveness and precision of the controller. Even when using a more complex controller on the roboRIO, it's still recommended to put as much processing on the motor controller as possible.

Both the SPARK MAX and SPARK Flex can operate in several closed-loop control modes, using sensor input to tightly control the motor velocity, position or current. The internal control loop follows a standard PID algorithm with a feed-forward (F) term to compensate for known system offsets. This allows the motor to follow precise and repeatable motions, useful for complex mechanisms.

Below is a diagram of the firmware implementation of the internal PIDF.

Additionally, an arbitrary feedforward signal is added to the output of the control loop after all calculations are done. The units for this signal can be selected as either voltage or duty cycle. This feature allows more advanced feedforward calculations to be performed by the controller. More details about the types of feedforward calculations can be found on the WPILib documentation. Using the voltage units for arbitrary feedforward allows the user to send the calculated feedforward voltage from the WPILib API directly to the control loop.

Smart Motion Control is a complex control mode that allows for smoother and more controlled movements from one position to another. By configuring the maximum velocity and acceleration, as shown in , this control mode will create a motion that accelerates, holds a constant "cruise" velocity, and then decelerates to a stop at the setpoint.

This control mode takes a setpoint in units of rotations, but the underlying implementation executes a Velocity PID controller, so the PID tuning process will be more like a Velocity controller.

The is a good tool for tuning this control loop, as it allows you to toggle between Smart Motion and Velocity control to fine-tune the constants and parameters.

Running Smart Motion Control is as easy as any other control mode: configure the constants, pick your setpoints, and set it as the mode when you apply the position target, as seen below:

Smart Motion Control is a complex control mode that allows for smoother and more controlled movements from one position to another. By configuring the maximum velocity and acceleration, as shown in

Setting up Closed-Loop Control

Closed-loop control in REVLib is accessed through the SPARK's closed loop controller object. This object is specific to each motor and contains all the methods needed to control your motor with closed-loop control. It can be accessed as shown below:

To drive your motor in a closed-loop control mode, address the closed loop controller object and give it a set point (a target in whatever units are required by your control mode: , , or ) and a control mode as shown below:

The provided example above runs the motor in position control mode, which is just a conventional PID loop reading the motor's current position from the configured encoder and taking a setpoint in rotations.

PID Constants and Configuration

To run a PID loop, several constants are required. For a more advanced controller, even more parameters need to be set and tuned.

PID Parameters

These gains can be configured on the with the closedLoop member of a SparkFlexConfigor SparkMaxConfig object as seen below:

F Parameter

The SPARK family of motor controllers also offer an F term, which is a velocity feed-forward. This is unique to each type of motor, and can be calculated by taking the reciprocal of the motor's velocity constant (Kv), in other words 1/Kv.

For a NEO Vortex, this value is 1/565. This is only needed when running a velocity-based control loop (velocity mode, Smart Motion, and Smart Velocity). The F parameter can be set as seen below:

MAXMotion Parameters

MAXMotion has parameters that allow you to configure and tune the motion profiles generated by MAXMotion. The parameters can be set through the maxMotion member of the closedLoop config.

Smart Motion Parameters

Slots

The SPARK MAX and SPARK Flex each have 4 closed-loop slots, each with their own set of constants. These slots are numbered 0-3. You can pass the desired as an argument to each of the applicable configurations.

When applying the setpoint, pass the slot number and the motor controller will switch to the appropriate config.