Closed Loop Control Getting Started

January 4, 2025 Update -

Documentation for REVLib 2025 can now be found at: https://docs.revrobotics.com/revlib

Please bookmark our new page as we transition over and add more information there!

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:

Java

// 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();

API Docs: CANSparkFlex, SparkPIDController

C++

// 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();

API Docs: CANSparkMax, SparkPIDController

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: , , or ) and a control mode as shown below:

This will run your motor in the provided mode, but it won't move until you've configured the PID constants.

Java

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

API Docs: setReference, ControlType

C++

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

API Docs: SetReference, ControlType

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.

Use caution when running motors in Closed-Loop modes, as they may move very quickly and unexpectedly if improperly tuned.

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:

Java

// 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);

API Docs: SparkPIDController

C++

// 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);

API Docs: SparkPIDController

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.

The Kv values for the NEO family of Brushless Motors are documented within each motor's specifications table: NEO Vortex, NEO V1.1, NEO 550

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:

Java

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

API Docs: SparkPIDController

C++

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

API Docs: SparkPIDController

The F parameter should only be set when using a velocity-based PID controller, and should be set to zero otherwise to avoid unwanted behavior.

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:

Java

// 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);

API Docs: SparkPIDController

C++

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

API Docs: SparkPIDController

Maximum Velocity is in units of Revolutions per Minute (RPM)

Maximum Acceleration is in units of RPM per Second (RPM/s)

These parameters have no effect on modes other than Smart Motion and Smart Velocity