Configuration

Devices support persistent settings through the use of “configs”.

Tip

Configs can also be configured using Phoenix Tuner X. See Tuner Configs for more information.

Configuration Objects

There are device-specific Configuration classes that group configuration data of devices in a meaningful way. These classes are Passive Data Structures. One example is TalonFXConfiguration, which has subgroups of configs such as MotorOutputConfigs. The configs can be modified through public member variables of the Configuration object. The complete list of configuration objects can be found in the API documentation (Java, C++, Python).

Note

Phoenix 6 utilizes the C++ units library and, optionally, the Java units library when applicable. Using the Java units library may increase GC overhead.

Java

var talonFXConfigs = new TalonFXConfiguration();

C++

configs::TalonFXConfiguration talonFXConfigs{};

Python

talonfx_configs = configs.TalonFXConfiguration()

Future Proofing Configs

There is a corner case with configs where the device may have firmware with newer configs that didn’t exist when the version of the API was built. To account for this problem, device Configuration objects have a FutureProofConfigs (Java, C++, Python) field.

Configurator API

Device objects have a getConfigurator() method that returns a device-specific Configurator object. The Configurator is used to retrieve, apply, and factory default the configs of a device.

Note

The getConfigurator() routine can be called frequently without any performance implications.

The device-specific configurators have type-specific overloads that allow for the widest variety of device-compatible configs. As a result, the caller can pass the entire device Configuration object or just the relevant subgroup of configs to the Configurator API.

Java

var talonFXConfigurator = m_talonFX.getConfigurator();

C++

auto& talonFXConfigurator = m_talonFX.GetConfigurator();

Python

talonfx_configurator = self.talonfx.configurator

Reading Configs

To read configs stored in a device, use the refresh() method to update a Configuration object. The example below demonstrates retrieving a full TalonFXConfiguration (Java, C++, Python) object from a TalonFX device.

Warning

refresh() is a blocking API call that waits on the device to respond. Calling refresh() periodically may slow down the execution time of the periodic function, as it will always wait up to DefaultTimeoutSeconds (Java, C++, Python) for the response when no timeout parameter is specified.

Java

var talonFXConfigurator = m_talonFX.getConfigurator();
var talonFXConfigs = new TalonFXConfiguration();

// optional timeout (in seconds) as a second optional parameter
talonFXConfigurator.refresh(talonFXConfigs);

C++

auto& talonFXConfigurator = m_talonFX.GetConfigurator();
configs::TalonFXConfiguration talonFXConfigs{};

// optional timeout (in seconds) as a second optional parameter
talonFXConfigurator.Refresh(talonFXConfigs);

Python

talonfx_configurator = self.talonfx.configurator
talonfx_configs = configs.TalonFXConfiguration()

# optional timeout (in seconds) as a second optional parameter
talonfx_configurator.refresh(talonfx_configs)

Applying Configs

Configs can be applied to a device by calling apply() on the Configurator with a Configuration object.

Warning

apply() is a blocking API call that waits on the device to respond. Calling apply() periodically may slow down the execution time of the periodic function, as it will always wait up to DefaultTimeoutSeconds (Java, C++, Python) for the response when no timeout parameter is specified.

Java

var talonFXConfigurator = m_talonFX.getConfigurator();
var motorConfigs = new MotorOutputConfigs();

// set invert to CW+ and apply config change
motorConfigs.Inverted = InvertedValue.Clockwise_Positive;
talonFXConfigurator.apply(motorConfigs);

C++

auto& talonFXConfigurator = m_talonFX.GetConfigurator();
configs::MotorOutputConfigs motorConfigs{};

// set invert to CW+ and apply config change
motorConfigs.Inverted = signals::InvertedValue::Clockwise_Positive;
talonFXConfigurator.Apply(motorConfigs);

Python

talonfx_configurator = self.talonfx.configurator
motor_configs = configs.MotorOutputConfigs()

# set invert to CW+ and apply config change
motor_configs.inverted = signals.InvertValue.CLOCKWISE_POSITIVE
talonfx_configurator.apply(motor_configs)

Tip

To modify a single configuration value without affecting the other configs, users can call refresh() after constructing the config object, or users can cache the config object and reuse it for future calls to apply().

Factory Default

A newly-created Configuration object contains the default configuration values of a device. As a result, it is unnecessary to factory default a device before applying a modified device Configuration object.

A device’s configs can be explicitly restored to the factory defaults by passing a newly-created Configuration object to the device Configurator.

Java

m_talonFX.getConfigurator().apply(new TalonFXConfiguration());

C++

m_talonFX.GetConfigurator().Apply(configs::TalonFXConfiguration{});

Python

self.talonfx.configurator.apply(configs.TalonFXConfiguration())