The software framework for all CTR-Electronics robot components.
See what control components make sense for your robotic needs at CTR-Electronics.
2018 Phoenix Documentation | Migration Guide
2018 Software Reference Manual (pdf) | API Docs Java C++
Examples: Java/C++/LabVIEW| Create an issue | Store
- Purpose of this guide
- Looking for the migration guide?
- Initial Hardware Testing
- Before you write any software!
- Everything is installed, can I write software now?
- Where is the API?
- Hardware Object Model
- Motor Controllers
- Multi-purpose/Sensor Devices
- Common Device API
- Software Object Model
- Driver Station
- CRF Firmware Versions
- Errata
To provide a top-to-bottom walk through of how to integrate CTRE's many hardware products into your robot's software. This includes supporting FRC teams for this season's game POWERUP. The software libraries for CTRE devices are bundled into the Phoenix Framework, which supports FRC-C++/Java/LabVIEW and HERO-C#. For advanced software questions, please see the 2018 Software Reference Manual (pdf).
The Phoenix framework provides the following new feature...
- Advanced Current limiting (Peak Current vs Continuous Current with Peak timeout).
- Support for the new Victor SPX.
- Talon SRX and Victor SPX deadband can be change from 4% to (0.1% - 25%) for all control modes.
- New follower features (Victor SPX follows Talon SRX, vice versa)
- Support for CANifier (PWM input/ PWM output/ Common-Anode LED Strip/ Digital IO / Quadrature)
- Remote Limit Switches. Victor SPX and Talon SRX can use other CANifiers/Victor SPXs/Talon SRXs for forward/reverse limit switch.
- API changes to accommodate upcoming Cascaded-PID-Loop and Pigeon-integration in Talon SRX.
- API changes to accommodate targeting heading during Motion Magic and Motion Profiling.
- WPI_TalonSRX and WPI_VictorSPX classes that drop into WPILIB's various objects. This allows clean implementation of the various WPILIB wrappers.
- Increase in Talon SRX/ Victor SPX number of closed-loop slots (from two to four).
- Robot Builder support for all devices above.
- Support for all three FRC languages.
- Motor controller configuration parameters can be defaulted with B/C press-and-hold on boot.
- SetInvert applies "all the way" down to the firmware for all control modes. You can also SetInvert() without breaking Sensor phase.
- Documentation is now on GitHub to allow for greater collaboration, along with example repositories.
Shortly after Kickoff will be an additional update to support...
- Remote sensor selection for closed looping off of sensors on other CAN devices.
- Pigeon IMU integration into Talon closed-loops (MotionMagicArc and MotionProfileArc).
- Various upper level objects (Gearbox/Drivetrain/Servo objects with unit scaling).
The migration guide is can be found here.
For your competition team to have the best chance of success, hardware components should be tested as soon as they are received. This is generally done by...
- Powering up the device and confirming LED states.
- Ensuring hardware shows up in the web-based config if wired to CAN Bus.
- Drive outputs / drive motor in both directions (if motor controller).
- Factory default using the B/C calibration button to default persistent settings. This is explained in the sections below, but it is worth pointing out how important this step is. It is in your team's best interest to test ALL purchased robot components immediately and in isolation.
- Robot replacement components should be in a state of readiness. Otherwise a replacement during competition can yield erroneous behavior.
- Many robot components (in general) have fixed warranty periods, and replacements must be done within them.
- Confirming devices are functional before handing them to students ensures best chance of success.
Follow the sections below in order. Otherwise you will see compiler errors for missing calls/VIs. This is also necessary for the roboRIO Web-based configuration.
The Phoenix Framework installer is the Windows Executable Installer that provides all software and API Libraries required to support CTRE products.
FRC Teams: Phoenix Framework should be installed after all other FRC software, including LabVIEW and/or Eclipse and the Driver Station update. See the FRC Screensteps for instructions on FRC Software.
If your computer is not running a Windows operating system, see the non-windows section.
The installer can be found here. Download and unzip the latest version of the CTRE Phoenix Framework Installer.
This page also contains some installer archives, so if you need an older version you can find it here as well.
FRC Teams: For the 2018 competition season, the minimum installer version that will work with the current control system is version 5.1.1.1.
Note: You will need administrative privileges to run the installer.
Run the executable that was downloaded in the previous step. If Windows prompts with an "unpublished" dialog box, press "More Info" and "Allow App to Run".
At a minimum, you must select the components for the programming language you are using.
After the installation is finished, you must restart any programming environment you are using (Eclipse or LabVIEW).
A zip file containing the Phoenix Framework libraries is available here.
Download the latest non-windows zip file and follow the README it contains to install the Phoenix API.
It is necessary to install Phoenix onto your roboRIO in order to use the Web-Based Configuration Page.
Additionally, LabVIEW teams must install Phoenix on the roboRIO for their robot programs using Phoenix to run properly.
Open the Phoenix LifeBoat utility and select the "roboRIO Upgrade" tab.
Follow the instructions on the tab to install Phoenix on your roboRIO.
When the upgrade is complete, a prompt will appear instructing LabVIEW teams restart their application. Java teams are also asked to redeploy their application to ensure the correct Phoenix library is installed (development PC vs robot controller).
Internet Explorer 11 is necessary to use the roboRIO web-based configuration.
In the future, CTRE will be replacing this interface, but for the time being this is the primary means of checking the presence of your CAN devices. This also allows for field-upgrade, device ID setting, etc.
Windows 7 and Windows 10 already have Internet Explorer 11 installed.
It can be manually installed here... https://support.microsoft.com/en-us/help/17621/internet-explorer-downloads
To test if Internet Explorer 11 is already installed, try running "iexplore" in the Windows start menu. Press Windows Key + 'R' to open Run window. Type "iexplore" and press enter.
The Eclipse files are typically installed in
- C:\Users\your-user-name\wpilib\user\cpp\lib (libCTRE_Phoenix)
- C:\Users\your-user-name\wpilib\user\java\lib (CTRE_Phoenix)
After the Phoenix Installer places these files, generally Eclipse must be restarted. Otherwise the IDE may report that the classes/functions cannot be found.
C++ Teams can confirm that the library was installed and discovered correctly by monitoring the Console tab.
Java Teams can confirm that both jar files are discovered in the project tree.
Testing the install can be done by opening LabVIEW and confirming the VIs are installed. This can be done by opening an existing project or creating a new project, or opening a single VI in LabVIEW. Whatever the simplest method to getting to the LabVIEW palette.
Instructions for checking the palette can be found here The file locations are also explained for manually review of the VIs.
Nope, there is still more to do. Follow each subsection to ensure device communication is healthy. Otherwise troubleshooting your software will become unnecessarily difficult.
A useful diagnostic feature in the FRC Control system is the roboRIO's Web-based Configuration and Monitoring page. This provides diagnostic information on all discovered CTRE CAN devices. CTRE devices can also be field-upgraded using this interface. This feature is accessible by entering the mDNS name of your robot in a web browser, typically roborio-XXXX-frc.local where XXXX is the team number (no leading zeros for three digit team numbers).
When connected via USB, you can generally type 172.22.11.2 to quickly reach web-based config.
Because the interface uses Silverlight, the user must use Internet Explorer 11. Instructions on installing Internet Explorer can be found here.
If "CAN Interface" is missing, then the web-based config plugin is likely not installed.
Instructions for upgrading the roboRIO are here
A CTRE CAN Device can have a device ID from 0 to 62. 63 and above are not allowed. If you select an invalid ID, you will get an immediate prompt.
Two dissimilar CAN models can use the same device ID. For example, Talon SRX 1 and Victor SPX 1 can coexist on the same CAN bus. However two models must not use the same device ID. Set the device ID of each device in isolation or use the web-based config to change the default ID from '0' to a unique number, then duplicate/close-reopen the internet explorer page to re-populate the device tree.
You will need to be logged into the roboRIO Web-based configuration to update your CAN devices. Username is "admin" with a blank password.
Select a CAN device in the device tree and press the "Update firmware button".
Phoenix installs the Cross The Road Firmware Files (CRF) into two locations...
- C:\users\Public\Documents\FRC (or similar).
- C:\users\Public\Documents\Cross The Road Electronics\LifeBoat\HERO Firmware Files
Make sure when checking these folders that you are looking on the same computer you installed Phoenix.
Firmware files are named Product-Application-Version-Suffix.crf.
Minimum Talon SRX firmware is 3.1.
Specific CRF Version information can be found here.
NOTE: Firmware versions are read as MAJOR-DOT-MINOR. E.g. 1.23 => One-dot-twenty-three E.g. 1.4 => One-dot-four Therefore 1.23 is newer than 1.4.
Each device can be named uniquely to identify it's purpose or unique characteristics. Feel free to change the contents of the name of a selected CAN device, and press Save. If you clear the Name text entry and press save, the name will default to "Device (Device Number)"
Press the self-test button to acquire a snapshot of the device's signals. This can be used to determine various configuration information, sensor health, and reliability of the device.
The API is available in several forms....
- The LabVIEW/C++/Java API source is available on GitHub.
- HTML documentation for C++/Java is generally available on ctr-electronics.com and on the developer's PC after Phoenix install.
- Eclipse supports intellisense/auto-coding features.
The following sections should be followed to ensure the best software-developing experience.
Eclipse Java users will have to add the Javadoc manually whenever creating or working with a new project to fully utilize the intellisense when programming. Steps can be found below.
-
Using the Package Explorer in the Java view, navigate through your new project to the "Referenced Libraries" tab. From there, you will both find CTRE_Phoenix.jar and CTRE_Phoenix-sources.jar.
-
Right click on CTRE_Phoenix.jar and select preferences. From there, you will navigate to the "Java Source Attachment" window.
-
Click on the "Variable" button and Create a new variable by clicking on "New..."
-
From there you should see a "Edit Variable" window as seen below. Start off by using the exact name of "CTRE_Phoenix.sources". Then clicking on "File..", navigate to the CTRE_Phoenix-sources.jar file, which is generally found within C:\Users'AccountName'\wpilib\user\java\lib
-
Now exit all windows by clicking on "OK". Verify that the Javadoc has been installed by hovering over any of the Phoenix Framework API which should bring up a small window with information about the API's functionality, parameters, return. It also grants the ability to go to the API's source location.
The java libraries for the phoenix framework can be imported by starting the import with import com.ctre.phoenix. The line can be finished off by manually typing in the package wanted or by using intellisense. Intellisense can be brought up by pressing CTRL + Spacebar at the . (dot). This will show all the sub-packages, classes, and interfaces available within the current package as seen below.
If the Javadoc was installed properly, which was explained in the "Add Javadoc if using Java" section, you should have the ability to hover over the Phoenix Framework API and find it's functionality details, parameters and return.
C++ modules simply need to include one header
#include "ctre/Phoenix.h"
This single header will include several of the Phoenix header files and brings several Phoenix namespaces into scope. Advanced C++ programmers may wish to avoid including many namespaces, in which case they can probe the contents of the header and pick out what they need.
The default Palette View can be confusing for most teams, as the names of the VI's are hidden. This can be changed by the following procedure:
- Options screen under LabVIEW Tools
The CTRE Palette is located in:
- WPI Robotics Library -> Third Party.
This palette can also be found in:
- WPI Robotics Library -> RobotDrive -> MotorControl -> CanMotor
- WPI Robotics Library -> Sensors -> Third Party
- WPI Robotics Library -> Actuators -> Third Party
The Phoenix VIs are installed inside a folder in the main installation directory. This would be: "C:\Users\Public\Documents\Cross The Road Electronics".
If your Public Documents folder is on different drive, your drive letter may be different.
There are two types of VI when it comes to CTRE/VEX motor controllers - Motor Controller (or "MC") 
and Enhanced Motor Controller (or "E-MC") 
.
Motor Controller VIs work for all CTRE/VEX motor controllers.
Enhanced Motor Controller VIs work only for motor controllers with a data port (currently Talon SRX).
CTRE/VEX provide two CAN/PWM motor controller options...
The first step of controlling a motor controller is to instantiate the controller in your robot controller software.
If using LabVIEW, use the Open VI corresponding to your motor controller. Here we are creating an object for the Talon with device ID 15. Notice that with LabVIEW you can also pick your motor direction on open.
If using a programming language, create a Talon SRX object using the appropriate class name.
private TalonSRX m_Wheel = new TalonSRX(15);
Regardless of the what the motor controller is used for, the next step is usually open-loop (no sensor) control. This is to ensure the mechanism is functional and that the motor and motor controller is wired correctly.
Start with the open-loop features below and configure each setting that is applicable.
Both the Talon SRX and Victor SPX have some persistent settings such as neutral mode, limit switches, soft limits, PID gains and a few others. These settings can be reverted to factory defaults by holding the B/C button on the Talon SRX and Victor SPX.
- Hold down the B/C CAL button until both status LEDS begin to rapidly blink red and green.
- Release the B/C CAL button.
- If the Talon SRX was calibrated properly, the status LEDs will blink green several times. If the calibration failed, the status LEDs will blink red and the previous calibration will be kept.
These features and configurations influence the behavior of the motor controller when it is directly controlled by the robot controller.
Motor controller output direction can be set by calling the setInverted() function as seen below.
Note: Regardless of invert value, the LEDs will blink green when positive output is requested (by robot code or firmware closed loop). Only the motor leads are inverted. This feature ensures that sensor phase and limit switches will properly match the LED pattern (when LEDs are green => forward limit switch and soft limits are being checked).
Pass in false if the signage of the motor controller is correct, else pass in true to reverse direction.
When using motor controllers in a master/follower configuration, all motor controllers need to have their direction set independently. A follower controller will not automatically change direction if you only invert the master.
Java -
/* Talon Direction has been inverted */
Hardware.Talon.setInverted(true);LabVIEW - You can pick your direction in the open VI. Use the Set Invert VI if you need to change it again.
Mode of operation during Neutral output may be set by using the setNeutralMode() function.
As of right now, there are two options when setting the neutral mode of a motor controller, brake and coast.
Java -
/* Displaying the two neutral mode options that both the Talon and Victor have */
Hardware.Talon.setNeutralMode(com.ctre.phoenix.motorcontrol.NeutralMode.Coast);
Hardware.Talon.setNeutralMode(com.ctre.phoenix.motorcontrol.NeutralMode.Brake);LabVIEW -
Talon SRX can limit the output current to a specified maximum threshold. This functionality (when enabled) functions in all control modes.
Current limiting configuration and enable can be controlled by the following API.
- Configure the continuous current limit to the amperage that you desire the current-draw be limited to.
- Configure the peak current limit to the threshold necessary to exceed to activate current limiting. If the peak current limit is less than the continuous current limit (zero for example) current limiting will be enforced when the current-draw exceeds to continuous current limit.
- Configure the peak current duration to the duration allowable over the peak current limit. If peak current duration is configured to 0, current limiting is enforced immediately after current-draw surpasses the peak current threshold.
- Enable current limiting.
Note: There is a noise floor (around 1-2 amps) to the Talon SRX current measurements. Setting a current limit close to those values may yield unexpected results. As a general rule of thumb it is not recommended to use a current limit below 5 amps.
/* The following java example limits the current to 10 amps whenever the current has exceeded 15 amps for 100 Ms */
talon.configContinuousCurrentLimit(10, 0);
talon.configPeakCurrentLimit(15, 0);
talon.configPeakCurrentDuration(100, 0);
talon.enableCurrentLimit(true);LabVIEW and C++ have similar function/VIs.
The Talon SRX and Victor SPX can be set to honor a ramp rate to prevent instantaneous changes in output.
There are two ramp rates - one for open-loop control modes and one for closed-loop control modes.
The open-loop ramp rate of a motor controller can be configured by using the configOpenloopRamp(); function. The function takes two parameters and returns a Error code generated by the function if the configuration fails to complete within the timeout.
Note: The open-loop ramp rate should only be configured for motor controller masters, as followers will mimic the Masters output already.
Note: The web-based configuration page entry for Ramp Rate should not be used. See the errata for more information.
Java -
/* Talon is configured to ramp from neutral to full within 2 seconds, and followers are configured to 0*/
leftMaster.configOpenloopRamp(2, 0);
leftFollower.configOpenloopRamp(0, 0); /* no need since master ramps */
rightMaster.configOpenloopRamp(2, 0);
rightFollower.configOpenloopRamp(0, 0); /* no need since master ramps */LabVIEW -
Both the Talon SRX and Victor SPX have a follower feature that allows the motor controllers to mimic another motor controller's output. Users will still need to set the motor controller's direction and neutral mode.
There are two methods for creating a follower motor controller. The first method set(ControlMode.follower, IDofMotorController) allows users to create a motor controller follower of the same model, talon to talon, or victor to victor.
The second method follow() allows users to create a motor controller follower of not only the same model, but also other models, talon to talon, victor to victor, talon to victor, and victor to talon.
Java -
/* The first line, we have a Victor following a Talon. The follow() function may also be used to create Talon follower for a Victor */
victorFollower.follow(Hardware.TalonMaster);
/* In the second line, we have a Talon following Talon. The set(ControlMode.Follower, MotorcontrollerID) creates followers of the same model. */
talonFollower.set(com.ctre.phoenix.motorcontrol.ControlMode.Follower, 6);LabVIEW -
Below is an example using the new FOLLOW VI.
Avoid using the SET VI when using LabVIEW as this is unsupported.
An “out of the box” Talon SRX or Victor SPX will default to the limit switch setting of “Normally Open” for both forward and reverse. This means that motor drive is allowed when a limit switch input is not closed (i.e. not connected to ground). When a limit switch input is closed (is connected to ground) the Talon SRX/Victor SPX will disable motor drive and individually blink both LEDs red in the direction of the fault (red blink pattern will move towards the M+/white wire for positive limit fault, and towards M-/green wire for negative limit fault)
Limit switch features can be disabled or changed to “Normally Closed” in the roboRIO web-based configuration. Changing the settings will take effect once the “Save” button is pressed. The settings are saved in persistent memory.
If the neutral mode or limit switch mode is changed in the roboRIO web-based configuration, the motor controller will momentarily disable then resume motor drive. All other settings can be changed without impacting the motor drive or enabled-state of the Talon SRX
The source of the forward and reverse limit switches are configurable in software. For Talon SRX you can choose the default feedback connector (data port), and for both controllers you can choose a remote source or to deactivate the limit switch. You must also indicate whether this limit switch is normally open, normally closed, or disabled, which overrides the setting from the web-based configuration page. This override is not permanent and will be reset when the device is power cycled. If you are choosing a remote source, you must also specify the device ID of the remote CAN device.
Java -
/* Configured forward and reverse limit switch of Talon to be from a feedback connector and be normally open */
Hardware.leftTalonMaster.configForwardLimitSwitchSource(LimitSwitchSource.FeedbackConnector, LimitSwitchNormal.NormallyOpen, 0);
Hardware.leftTalonMaster.configReverseLimitSwitchSource(LimitSwitchSource.FeedbackConnector, LimitSwitchNormal.NormallyOpen, 0);
/* Configured forward and reverse limit switch of a Victor to be from a Remote Talon SRX with the ID of 3 and normally closed */
Hardware.rightVictorMaster.configForwardLimitSwitchSource(RemoteLimitSwitchSource.RemoteTalonSRX, LimitSwitchNormal.NormallyClosed, 3, 0);
Hardware.rightVictorMaster.configReverseLimitSwitchSource(RemoteLimitSwitchSource.RemoteTalonSRX, LimitSwitchNormal.NormallyClosed, 3, 0);LabVIEW -
The enable state of the limit switches can be overridden in software. This can be called at any time to enable or disable both limit switches.
Java -
/* Limit switches are forced disabled on Talon and forced enabled on Victor */
Hardware.leftTalonMaster.overrideLimitSwitchesEnable(false);
Hardware.rightVictorMaster.overrideLimitSwitchesEnable(true);LabVIEW -
These features and configurations influence the behavior of the motor controller when encoders/sensors are being used to provide feedback to a maneuver.
Sensors for motor controllers provide feedback about the position, velocity, and acceleration of the system using that motor controller. The Talon SRX supports a wide variety of sensors while the Victor SPX is able to grab sensor data from another motor controller, which we call remote source.
Sensors allows both the motor controller and user to receive data and feedback. That information allows us to act upon different situations by giving us information about the motors position, speed, and acceleration. This information is especially important when implementing a closed-loop control, such as a PID control loop.
Java/C++ - Use the configSelectedFeedbackSensor routine. Example below.. LabVIEW - Use the "Config Sensor" Vi under Victor SPX or Talon SRX (depending on motor controller).
There are multiple methods of ensuring the connected sensor is active and returning meaningful data. The best method is to plot the signal and watch the plot, looking for continuous data that is responsive. Another, but less reliable method is to print your values to a console and check for values, which makes it harder to see if there is noise in the values.
If the reported value is not what is expected (eg. quadrature position is reporting as 0 or 1), check your sensor and wiring to make sure the physical sensor setup is good.
Java/C++ - For the FRC languages, the easiest way to produce a plot is to use the SmartDashboard, a feature part of the FRC Driver Station. Below is an example of how to set up the sensor on the Talon SRX and get a plot.
Java -
/* Setup sensors to check status, can also be used for phasing */
Hardware.rightMaster.configSelectedFeedbackSensor(com.ctre.phoenix.motorcontrol.FeedbackDevice.QuadEncoder, 0, 0);
Hardware.rightMaster.setSensorPhase(false);
Hardware.leftMaster.configSelectedFeedbackSensor(com.ctre.phoenix.motorcontrol.FeedbackDevice.QuadEncoder, 0, 0);
Hardware.leftMaster.setSensorPhase(false);
/* Output value to SmartDashboard */
SmartDashboard.putNumber("Right Sensor position", Hardware.rightMaster.getSelectedSensorPosition(0));
SmartDashboard.putNumber("Left Sensor Velocity", Hardware.leftMaster.getSelectedSensorVelocity(0));Once you have deployed the code and opened SmartDashboard from the FRC Driver Station, you may reveal the values by going under the view tab and revealing the values which will be listed by their key name. You may then change the numerical indicator the a line-plot and generate the plot by driving the motor controller.
Sensor phase is the term used to explain sensor direction. In order for limit switches and closed-loop features to function properly the sensor and motor has to be “in-phase.” This means that the sensor position must move in a positive direction as the motor controller drives positive output (and LEDs are green). To test this, first drive the motor manually (using
gamepad axis for example). Watch the sensor position in the roboRIO web-based configuration self-test, plot using the method explained in the section How do I know the sensor works?, or by calling GetSensorPosition() and printing it to console.
Sensor phase can be set by using setSensorPhase(). If the sensor is out of phase, set true.
Java -
/* Sensor was out of phase, invert the sensor */
Hardware.Talon.setSensorPhase(true);C++ -
LabVIEW -
Position units are in the natural units of the sensor. This ensures the best resolution possible when performing closed-loops in firmware.
| Sensor Type | Units per rotation |
|---|---|
| Quadrature Encoder : US Digital 1024 CPR | 4096 (because Talon/CANifer counts every edge) |
| CTRE Magnetic Encoder (relative/quadrature) | 4096 |
| CTRE Magnetic Encoder (absolute/pulse width encoded) | 4096 |
| Any pulse width encoded position | 4096 represents 100% duty cycle |
| AndyMark CIMcoder | 80 (because 20 pulses => 80 edges) |
Velocity is measured in sensor units per 100ms. This ensures sufficient resolution regardless of the sensing strategy. For example, when using the CTRE Magnetic Encoder, 1u velocity represents 1/4096 of a rotation every 100ms. Generally you can multiply the velocity units by 600/UnitsPerRotation to obtain RPM.
Tachometer velocity measurement is unique in that it measures time directly. As a result, the reported velocity is calculated where 1024 represents a full "rotation". This means that a velocity measurement of 1 represents 1/1024 of a rotation every 100ms.
Soft limits can be used to disable motor drive when the “Sensor Position” is outside of a specified range. Forward output will be disabled if the “Sensor Position” is greater than the Forward Soft Limit. Reverse output will be disabled if the “Sensor Position” is less than the Reverse Soft Limit. The respective Soft Limit Enable must be enabled for this feature to take effect.
Java -
/* Talon configured to have soft limits 10000 native units in either direction and enabled */
rightMaster.configForwardSoftLimitThreshold(10000, 0);
rightMaster.configReverseSoftLimitThreshold(-10000, 0);
rightMaster.configForwardSoftLimitEnable(true, 0);
rightMaster.configReverseSoftLimitEnable(true, 0);LabVIEW -
After the soft limits have been configured, at any point you can override the enable to turn the soft limit functionality off.
LabVIEW -
Closed-loop Ramping works the same way as open-loop ramping using configClosedloopRamp. See Ramping for more information on ramping.
When it comes to the Talon SRX and Victor SPX, there are multiple closed-loop control mode options to choose from. Below is a list with an explanation of each supported closed-loop type.
Position closed-loop The Talon's closed-loop logic can be used to maintain a target position. Target and sampled position is passed into the equation in native units.
Velocity closed-loop The Talon's closed-loop logic can be used to maintain a target velocity. Target and sampled velocity is passed into the equation in native units per 100ms.
Current closed-loop The Talon's closed-loop logic can be used to approach a target current-draw. Target and sampled current is passed into the equation in milliamperes.
Note: Current Control Mode is separate from Current Limit. Current limit can be found here.
Motion Magic Talon will closed-loop to target position while honoring an maximum "cruise" velocity and specified acceleration.
Motion Magic (Arc) This is an advanced control mode that will allow for simultaneous servoing of a distance and heading. This will be released in a future update.
Motion profiling / Motion profiling (Arc) With this, a savvy developer can actually stream motion profile trajectory points into the Talon’s internal buffer (even while executing the profile). This allows fine control of position and speed throughout the entire movement.
This feature is being reimplemented to allow for simulataneous servoing of a distance and heading (using Pigeon IMU) and will be released shortly.
Below is a full example for position closed-looping using the HERO development board. These functions are also available in FRC C++/Java, and comparable VIs are available in LabVIEW. The position closed-loop examples can also be found below. Java -
Coming soon. This exists in last year's documentation and will be merge in accordingly.
When tuning gains, it is recommended to zero out all closed-loop control parameters and start with P (or F if recommended for the control mode).
Motor output is represented as a 11-bit number in firmware. All units for motor output are a scalar from -1023 to +1023.
Closed-loop error is the difference between the target setpoint and the current sensor value.
For position: closed-loop error = target - sensor position.
For velocity: closed-loop error = target - sensor velocity.
Feed-Forward is typically used in velocity and motion profile/magic closed-loop modes.
F gain is multiplied directly by the set point passed into the programming API. The result of this multiplication is in motor output units [-1023, 1023]. This allows the robot to feed-forward using the target set-point.
In order to calculate feed-forward, you will need to measure your motor's velocity at a specified percent output (preferably an output close to the intended operating range).
You can see the measured velocity in a few different ways. The fastest is to usually do a self-test in the web-based interface - This will give you both your velocity and your percent output.
F-gain is then calculated using the following formula:
F-gain = ([Percent Output] x 1023) / [Velocity]
Using the example from the self-test picture above, that would be:
F-gain = (0.48 x 1023) / 6331 = 0.077561
We can then check our math - if the target velocity is set to 6331 native units per 100ms, the closed-loop output will be (0.077561 x 6331) = 491 (which is 48% of 1023).
P is the proportional gain. It modifies the closed-loop output by a proportion (the gain value) of the closed-loop error.
P gain is specified in output unit per error unit. For example, a value of 102 is ~9.97% (which is 102/1023) output per 1 unit of Closed-Loop Error.
Example: Position Closed-loop
When tuning P, it's useful to estimate your starting value. If you want your mechanism to drive 50% output when the error is 4096 (one rotation when using CTRE Mag Encoder), then the calculated Proportional Gain would be (0.50 X 1023) / 4096 = ~0.125.
To check our math, take an error (native units) of 4096 X 0.125 => 512 (50% output).
Tune this until the sensed value is close to the target under typical load. Many prefer to simply double the P-gain until oscillations occur, then reduce accordingly.
I is the integral gain. It modifies the closed-loop output according to the integral error (summation of the closed-loop error each iteration).
I gain is specified in output units per integrated error. For example, a value of 10 equates to ~0.97% for each accumulated error (Integral Accumulator). Integral accumulation is done every 1ms.
Example: Position Closed-loop
If your mechanism never quite reaches your target and using integral gain is viable, start with 1/100th of the Proportional Gain.
D is the derivative gain. It modifies the closed-loop output according to the derivative error (change in closed-loop error each iteration).
D gain is specified in output units per derivative error. For example a value of 102 equates to ~9.97% (which is 102/1023) per change of Sensor Position/Velocity unit per 1ms.
Example: Position Closed-loop
If your mechanism accelerates too abruptly, Derivative Gain can be used to smooth the motion. Typically start with 10x to 100x of your current Proportional Gain.
All sensor data is reported periodically on the CAN Bus. The frames periods can be modified by using the setStatusFramePeriod functions of the Java/C++ objects, and the "Set Status Frame" Vis in LabVIEW.
Documentation will be updated soon.
In the meantime the pre-Phoenix API is relatively close. See the software portion of the User's Guide.
Pigeon Tech Resources
Additionally the example repositories can be used for reference.
Phoenix-Examples-Languages
Phoenix-Examples-LabVIEW
Documentation will be updated soon.
In the meantime the pre-Phoenix API is relatively close. See the software portion of the User's Guide.
CANifier Tech Resources
Additionally the example repositories can be used for reference.
Phoenix-Examples-Languages
Phoenix-Examples-LabVIEW
The Talon SRX, Victor SPX, CANifier, and Pigeon IMU have a common set of device functions. These are explained below.
In C++/Java, many routines return an ErrorCode. Depending on the function, this can be used to determine if the function was successful.
Additionally each object has a getLastError() routine that will return the code for the last function called.
In LabVIEW, the error output is filled with a CTRE error code when an error condition occurs.
In all circumstances, error events are also sent to the Driver Station console output. However Driver Station messages are debounced to reduce flooding the console.
All device classes and VIs support a hasResetOccurred routine that allows the caller to poll if the device has reset since last call. Additionally, Talon SRX and Victor SPX have a sticky fault (accessible via web-based config or API) to indicate if the motor controller has been reset/power-booted during robot-enable.
In addition to the feature specific config* routines/VIs in C++/Java/LabVIEW, there are general Config Parameter routines that will take an arbitrary enumeration value type ParamEnum.
When using the general configuration get/set routines, ordinal can be used to specify...
- which PID slot to select (when accessing gains).
- which PID loop to select (when accessing PID signals such as integral accumulator)
- which limit switch direction, 0 for forward, 1 for reverse (when accessing limit parameters)
Every language supports a ConfigGetParameter and ConfigSetParameter.
All config* routines in the C++/Java require a timeoutMs parameter. When set to a non-zero value, the config routine will wait for an acknowledgement from the device before returning. If the timeout is exceeded, an error code is generated and a Driver Station message is produced. When set to zero, no checking is performed (identical behavior to the CTRE v4 Toolsute).
The Phoenix framework supports an adapter class for Victor SPX and Talon SRX hardware objects. Depending on language, the developer needs to be made aware of the following sections below to utilize certain WPILIB classes/VIs.
The WPI_TalonSRX and WPI_VictorSPX classes implement several WPILIB interfaces.
WPILIB motor controllers generally support...
- Live Window/Sendable features
- Test Mode
- Motor Safety
- SpeedController interface (which assumes motor controller is "simple")
- a single parameter set(), (which assume motor controller is "simple")
WPI_TalonSRX and WPI_VictorSPX can also be subclassed/forked/modified for advanced teams that want to use the WPILIB drivetrain classes (which are primarily designed for simple motor controllers), while using the advanced features of the Talon/Victor.
Additionally future release of Phoenix will include CTRE developed drivetrain objects that natively support our motor controllers.
LabVIEW's NI/WPILIB objects will natively work the Talon SRX/Victor SPX motor references. Using the WPI Motor Set VI in Teleop.vi:
Opening Multiple Motors for a Drivetrain in Begin.vi:
DS Errors should be addressed as soon as they appear. This is because...
- Phoenix API will report if a device is missing, not functioning, has too-old firmware, etc.
- If errors are numerous and typical, then users cannot determine if there is a new problem to address.
- A large stream of errors can bog down the Driverstation/roboRIO. Phoenix Framework has a debouncing strategy to ensure this does not happen, but not all libraries do this.
Phoenix DS errors occur on call. Meaning VIs/API functions must be called in robot code for any errors to occur. When an error does occur, a stack trace will report where in the robot code to look.
Use the web-based configuration page to update the firmware of the device.
Note that the robot application must be restarted for the firmware version check to clear. This can be done by redeploying the robot application or simply restarting the robot.
This usually indicates that your device ID is wrong or your firmware pre-dates Phoenix.
Use the web-based configuration page to check your device IDs and make sure your firmware is up-to-date.
This is usually caused by a diagram disable structure around a MotorController or EnhancedMotorController VI
In order to fix this, you must wire the device reference through the enabled state of the diagram disabled block
Phoenix 5.2.1.1:
- Pigeon-Application-0.41-FixedParamResp.crf
- CANifier-Application-0.40-FirmVers.crf
- TalonSrx-Application-3.3.crf (Motion Profile added).
- VictorSpx-Application-3.1.crf
Phoenix 5.1.3.1:
- Pigeon-Application-0.41-FixedParamResp.crf
- CANifier-Application-0.40-FirmVers.crf
- TalonSrx-Application-3.1.crf
- VictorSpx-Application-3.1.crf
Phoenix 5.2.1.1:
- getClosedLoopTarget reports in units of milliamperes when in current closed-loop mode.
Phoenix 5.1.3.1:
- Talon SRX/ Victor SPX motion-profile mode is not available in the kickoff release. This is due to the modifications done to support Pigeon IMU integration. This will be remedied in a future release. [Resolved in 5.2.1.1]
LabVIEW: Do not use SET VI when using follwer features in LabVIEW.
Instead use the FOLLOW VI documented in this section.
Web-based Configuration:
- The individual ramp rate inside the closed-loop slot has been replaced with
configOpenloopRamp and configClosedloopRamp. Instead use these routine as the web-based
config entry will always read zero.
