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_pidController.setReference(setPoint, CANSparkBase.ControlType.kCurrent);

m_pidController.SetReference(SetPoint, rev::CANSparkBase::ControlType::kCurrent);

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 PID controller in raw position mode, with a feedforward
m_pidController.setReference(
    setPoint, 
    CANSparkBase.ControlType.kPosition, 
    feedForward
);

// Set the setpoint of the PID controller in raw position mode, with a feedforward
m_pidController.SetReference(
    SetPoint, 
    rev::CANSparkBase::ControlType::kPosition,
    feedForward
);

Setting up Closed-Loop Control

Closed-loop control in REVLib is accessed through the SPARK's PID Controller object. This object is specific to each motor and tracks the PID gains and closed-loop constants. It also contains all the methods needed to configure and control your motor. It can be accessed as shown below:

// initialize the motor (Flex/MAX are setup the same way)
CANSparkFlex m_motor = new CANSparkFlex(deviceID, MotorType.kBrushless);

// initialize the PID controller
SparkPIDController m_pidController = m_motor.getPIDController();

// initialize the motor (Flex/MAX are setup the same way)
rev::CANSparkMax m_motor{deviceID, rev::CANSparkMax::MotorType::kBrushless};

// initialize the PID Controller
rev::SparkPIDController m_pidController = m_motor.GetPIDController();

To drive your motor in a Closed-Loop control mode, address the PID Controller object and give it a set point (a target in whatever units are required by your control mode: position, velocity, or current) and a control mode as shown below:

// Set the setpoint of the PID controller in raw position mode
m_pidController.setReference(setPoint, CANSparkBase.ControlType.kPosition);

// Set the setpoint of the PID controller in raw position mode
m_pidController.SetReference(SetPoint, rev::CANSparkBase::ControlType::kPosition);

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 set and tuned.

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 slot number as an argument to each of the parameter setting methods. When applying the setpoint, pass the slot number and the motor controller will switch to the appropriate config.

PID Parameters

A PID controller has 3 core parameters or gains. For more information on these gains and how to tune them, see Getting Started with PID Tuning.

These gains can be configured on the SparkPIDController object as shown below:

// Set the P value of the PID controller on slot 0 to 0.25
m_pidController.SetP(kP);
m_pidController.SetI(kI);
m_pidController.SetD(kD);
m_pidController.SetIZone(kIz);

// Set the minimum and maximum outputs of the motor [-1, 1]
m_pidController.SetOutputRange(kMinOutput, kMaxOutput);

// Set the P value of the PID controller on slot 0 to 0.25
m_pidController.SetP(kP);
m_pidController.SetI(kI);
m_pidController.SetD(kD);
m_pidController.SetIZone(kIz);

// Set the minimum and maximum outputs of the motor [-1, 1]
m_pidController.SetOutputRange(kMinOutput, kMaxOutput);

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:

// Set kFF
m_pidController.SetFF(1/Kv);

// Set kFF
m_pidController.SetFF(1/Kv);

Smart Motion Parameters

There are another set of parameters available for the SparkPIDController, which only apply to Smart Motion and Smart Velocity. These allow you to configure and tune the motion profiles generated by Smart Motion. They can be set as seen below:

// Set Smart Motion / Smart Velocity parameters
int smartMotionSlot = 0;
m_pidController.setSmartMotionMaxVelocity(maxVel, smartMotionSlot);
m_pidController.setSmartMotionMinOutputVelocity(minVel, smartMotionSlot);
m_pidController.setSmartMotionMaxAccel(maxAcc, smartMotionSlot);
m_pidController.setSmartMotionAllowedClosedLoopError(allowedErr, smartMotionSlot);

// Set Smart Motion / Smart Velocity parameters
m_pidController.SetSmartMotionMaxVelocity(maxVel);
m_pidController.SetSmartMotionMinOutputVelocity(minVel);
m_pidController.SetSmartMotionMaxAccel(maxAcc);
m_pidController.SetSmartMotionAllowedClosedLoopError(allowedErr);

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 Smart Motion Parameters, 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 Smart Motion Example Program 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:

m_pidController.setReference(setPoint, CANSparkBase.ControlType.kSmartMotion);

m_pidController.SetReference(SetPoint, rev::CANSparkBase::ControlType::kSmartMotion);

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_pidController.setReference(setPoint, CANSparkBase.ControlType.kPosition);

m_pidController.SetReference(SetPoint, rev::CANSparkBase::ControlType::kPosition);

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.

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_pidController.setReference(setPoint, CANSparkBase.ControlType.kVelocity);

m_pidController.SetReference(SetPoint, rev::CANSparkBase::ControlType::kVelocity);

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_pidController.setReference(setPoint, CANSparkBase.ControlType.kSmartVelocity);

m_pidController.SetReference(SetPoint, rev::CANSparkBase::ControlType::kSmartVelocity);