CTR Electronics Phoenix Pro User manual

Phoenix Pro
CTR Electronics
May 19, 2023

Intro
1 Why Phoenix Pro? 3
2 Installing Phoenix Pro 5
3 Conguring your Device 9
4 Device Licensing 11
5 Phoenix Tuner X 17
6 TalonFX 45
7 Pigeon 2.0 47
8 CANcoder 51
9 API Usage 55
10 Simulation 101
11 WPILib Integration 105
12 Examples 109
13 CANivore Intro 115
14 CANivore Setup 117
15 CANivore API 123
16 Hardware-Attached Simulation 125
17 Advanced Conguration 127
18 Troubleshooting 131
19 Support 135
i

ii

Phoenix Pro
Welcome to the Phoenix Pro documentation. Individuals looking for Phoenix 5 documentation
may locate it here.
The Phoenix Pro software framework allows you to control and congure your CTR Electronics
Phoenix Pro Devices. Phoenix Pro represents a complete rewrite of the software framework
over the existing Phoenix 5 framework. With Phoenix Pro, users have access to many new
features that expand the control the user has over their devices.
Important: User’s looking for documentation on the Phoenix 6 API can nd that on the
latest version of this site.
CTR Electronics Blog For news and updates about your CTR Electronics device, please check
out our blog.
Changelog A changelog containing API, Tuner and Firmware changes is
available here.
Migration Guide A Phoenix 5 migration guide is available here.
Installation Installation instructions for Phoenix API & Tuner.
Phoenix Tuner Documentation that introduces the companion application to
manage your CTR Electronics devices.
Hardware Reference Documentation for device specic conguration, trou-
bleshooting and setup instructions.
API Reference Documentation and details on using the CTR Electronics device API. This
includes usage of signals, congs, control requests, etc.
Examples Software API examples for controlling your devices.
Troubleshooting Common troubleshooting for hardware or software problems.
1

Phoenix Pro
2

1
Why Phoenix Pro?
Phoenix Pro currently oers the following features and will further expand.
1.1 Comprehensive API
• Device signal getters return a StatusSignalValue object, expanding the functionality of
status signals.
• Control devices with an extensive list of exible, strongly-typed control request objects.
1.2 Canonical Units
• Uses the popular Units library for C++ and standardizes on SI units.
• Signals are documented with the unit type and the minimum and maximum values.
1.3 Time Base Synchronization
• Using CANivore Timesync, signals from all devices are sampled and published to the
CAN bus at the same time.
• API can synchronously wait for data from multiple devices on a CANivore to arrive.
3

Phoenix Pro
1.4 Field Oriented Control (FOC)
• ~15% increase in peak power.
• Increased torque output; faster acceleration and higher speeds under load.
• Greater eiciency; the motor draws less current for the same output power, increasing
battery life.
• Support for direct torque control.
1.5 Improved Device Control
• New and improved control output types and closed-loop conguration.
• Improved Motion Magic® with jerk control and support for modifying the prole on the
y.
• Kalman-based algorithms to reduce latency while maintaining smooth data.
•Fuse a CANcoder with the motor’s internal rotor, getting absolute data all the time while
using the fast internal sensor for closed looping.
1.6 Enhanced Support for CAN FD
• Improved CAN FD framing further reduces any CAN bus utilization issues.
• Larger CAN frames allow for the addition of more advanced features.
1.7 New Tuner X Self Tests
• Detailed and resolute self tests to improve debugging.
1.8 Free High-Fidelity Simulation
• Simulation closely follows the behavior of real hardware.
• Write unit-tests for your robot code, and make sure the robot works before deploying.
•Try Phoenix Pro before you buy!
4 Chapter 1. Why Phoenix Pro?

2
Installing Phoenix Pro
Installation of Phoenix Pro is comprised of a few steps
•Installing API
•Installing Tuner
•Updating Device Firmware
•Device Licensing
2.1 API Installation
Phoenix Pro currently supports Java and C++ for development.
2.1.1 System Requirements
The following targets are supported:
• NI roboRIO
• Windows 10/11 x86-64
• Linux x86-64 (desktop)
–Ubuntu 22.04 or newer
–Debian Bullseye or newer
• Linux ARM32 and ARM64 (Raspberry Pi, NVIDIA Jetson)
–Ubuntu 20.04 or newer
–Debian Bullseye or newer
• macOS (regular simulation only)
5

Phoenix Pro
2.1.2 O󰍒ine
Important: Users on non-Windows devices should skip to the Online installation instruc-
tions.
1. Download the Phoenix Framework Installer
2. Navigate through the installer, ensuring applicable options are selected
3. Apply the vendordep via WPILib VSCode Adding Oine Libraries
2.1.3 Online
FRC (Pro Only)
Important: This vendordep is for robot projects that are only using Phoenix Pro licensed
devices.
Paste the following URL in WPILib VS Code Install New Libraries (Online)
•https://maven.ctr-electronics.com/release/com/ctre/phoenixpro/
PhoenixPro-frc2023-latest.json
6 Chapter 2. Installing Phoenix Pro

Phoenix Pro
FRC (Pro & Phoenix 5)
Important: This vendordep is for robot projects that are using both Phoenix Pro licensed
devices & Phoenix 5 devices.
Paste the following URL in WPILib VS Code Install New Libraries (Online)
•https://maven.ctr-electronics.com/release/com/ctre/phoenixpro/
PhoenixProAnd5-frc2023-latest.json
Important: Devices on Phoenix Pro rmware must use the Phoenix Pro API. Device on
Phoenix 5 rmware must use the Phoenix 5 API.
non-FRC (Linux)
Phoenix Pro is distributed through our APT repository. Begin with adding the repository to
your APT sources.
sudo curl -s --compressed -o /usr/share/keyrings/ctr-pubkey.gpg "https://deb.ctr-
,→electronics.com/ctr-pubkey.gpg"
sudo curl -s --compressed -o /etc/apt/sources.list.d/ctr<year>.list "https://deb.ctr-
,→electronics.com/ctr<year>.list"
Note: <year> should be replaced with the year of Phoenix Pro software for which you have
purchased licenses.
After adding the sources, Phoenix Pro can be installed and updated using the following:
sudo apt update
sudo apt install phoenix-pro
Tip: To get a robot application up and running quickly, check out our non-FRC Linux example.
2.2 Tuner X Installation
Phoenix Tuner X is a modern version of the legacy Phoenix Tuner v1 application that is used
to congure CTRE Phoenix CAN devices.
Phoenix Tuner X is supported on Android, Windows 10 (build 1903+), and Windows 11. In-
stallation is available from the respective OS stores.
• Windows: https://apps.microsoft.com/store/detail/phoenix-tuner/9NVV4PWDW27Z
• Android: https://play.google.com/store/apps/details?id=com.ctre.phoenix_tuner
2.2. Tuner X Installation 7

Phoenix Pro
8 Chapter 2. Installing Phoenix Pro

3
Con󰍏guring your Device
All CTR Electronics devices have an ID that distinguishes multiple devices of the same type on
the same CAN bus. This should be congured to the user’s preference. Firmware upgrading
is also generally required for each new release of Phoenix Pro API. Please visit the relevant
Tuner pages on how to complete these steps.
Updating Firmware Click here to visit the section on updating your device rmware
Conguring IDs Click here to visit the section on conguring your device ID
9

Phoenix Pro
10 Chapter 3. Con󰍏guring your Device

4
Device Licensing
The following devices are eligible for single-device licensing:
• TalonFX (Falcon 500)
• Pigeon 2
• CANcoder
Additionally, CANivore is supported for licensing. When a CANivore is licensed, all devices
on that bus are Pro enabled without additional activation.
Important: All license activation and verication features are only available in Phoenix
Tuner X. Phoenix Tuner v1 does not support licensing actions.
4.1 Purchasing a License
Licenses can be purchased in the licensing section on the CTR Electronics store. Click here
to purchase a license.
Once a license has been purchased, you will receive an email conrmation conrming your
purchase. Once this email is received, the license should be visible in the list of licenses in
Tuner X.
4.2 Activating a License
Licenses are activated by rst clicking on the LIC icon in the bottom right corner of the device
card.
11

Phoenix Pro
This will open up a screen which displays a list of currently attached licenses for that device.
Click on the Activate a new license button on the bottom of the popup.
12 Chapter 4. Device Licensing

Phoenix Pro
A list of purchased (but unattached) license seats are shown here. Click on the license you
would like to redeem and press the Activate Selected License button to conrm redemption
of that seat.
Warning: Users should be aware that license activation is permanent and irreversible
Once the activation is complete, the license will be downloaded to the device. In the event
that Tuner X disconnects from the internet or from the robot before this completes, the li-
cense is still activated and available for download the next time Tuner X is connected to the
internet/robot.
4.2. Activating a License 13

Phoenix Pro
4.2.1 Activating a License without a Robot
Devices that have been seen by Tuner X at least once will be available in Device History. This
can be useful for licensing a device when disconnected from the robot.
4.3 Verifying Activation State
An icon displaying the license state of your device is located in the bottom right of the device
card.
The below table can be used to determine your device license state for troubleshooting.
14 Chapter 4. Device Licensing

Phoenix Pro
State Image Description
Licensed Device is licensed for the current version of Phoenix Pro API.
CANivore con-
tains Licenses
CANivore contains at least one bus license, which it will use
to remote-license all compliant CAN devices.
Pro Licensing
Error
Device is licensed and there was an error communicating
license state.
Licensing Error Device is not licensed and there was an error communicating
license state.
Not Licensed Device is not licensed for this version of Phoenix Pro API.
Licensing Not
Supported
Icon not
present
Device does not support licensing or is using an incompatible
rmware for device licensing.
4.4 Troubleshooting
• Did you activate a license for this device?
–Clicking on the icon will show licenses that are attached to this device
• Is the latest diagnostic server running?
–Check the version at the bottom of Tuner X’s devices page.
∗ Latest version details can be found in the changelog under the latest Phoenix-Pro
version.
–Conrm the vendordep in your robot project is the latest version.
–Alternatively, you can deploy the temporary diagnostic server.
• Is the latest Pro rmware ashed onto the device?
4.4. Troubleshooting 15

Phoenix Pro
16 Chapter 4. Device Licensing