Control Requests#

Control Requests represent the output of a device. A list of control requests can be found in the API docs (Java, C++).

Note

Phoenix 6 utilizes the C++ units library when applicable.

Applying a Control Request#

Control requests can be applied by calling setControl() on the device object. setControl() returns a StatusCode (Java, C++, Python) enum that represents success state. A successful request will return StatusCode.OK.

// Command m_motor to 100% of duty cycle
m_motor.setControl(new DutyCycleOut(1.0));
// Command m_motor to 100% of duty cycle
m_motor.SetControl(controls::DutyCycleOut{1.0});
# Command m_motor to 100% of duty cycle
self.motor.set_control(controls.DutyCycleOut(1.0))

Modifying a Control Request#

Control requests are mutable, so they can be saved in a member variable and reused. For example, DutyCycleOut (Java, C++, Python) has an Output member variable that can be manipulated, thus changing the output DutyCycle (proportion of supply voltage).

Note

Java users should reuse control requests to prevent excessive invocation of the Garbage Collector.

final DutyCycleOut m_motorRequest = new DutyCycleOut(0.0);

m_motorRequest.Output = 1.0;
m_motor.setControl(m_motorRequest);
controls::DutyCycleOut m_motorRequest{0.0};

m_motorRequest.Output = 1.0;
m_motor.SetControl(m_motorRequest);
self.motor_request = controls.DutyCycleOut(0.0)

self.motor_request.output = 1.0
self.motor.set_control(self.motor_request)

Method Chaining API#

Control requests also supports modification using method chaining. This can be useful for mutating multiple values of a control request.

// initialize torque current FOC request with 0 amps
final TorqueCurrentFOC m_motorRequest = new TorqueCurrentFOC(0);

// mutate request with output of 10 amps and max duty cycle 0.5
m_motor.SetControl(m_motorRequest.withOutputAmps(10).withMaxAbsDutyCycle(0.5));
// initialize torque current FOC request with 0 amps
controls::TorqueCurrentFOC m_motorRequest{0_A};

// mutate request with output of 10 amps and max duty cycle 0.5
m_motor.SetControl(m_motorRequest.WithOutputAmps(10_A).WithMaxAbsDutyCycle(0.5));
# initialize torque current FOC request with 0 amps
self.motor_request = controls.TorqueCurrentFOC(0)

# mutate request with output of 10 amps and max duty cycle 0.5
self.motor.set_control(self.motor_request.with_output_amps(10).with_max_abs_duty_cycle(0.5))

Changing Update Frequency#

Control requests are automatically transmitted at a fixed update frequency. This update frequency can be modified by changing the UpdateFreqHz (Java, C++) field of the control request before sending it to the device.

// create a duty cycle request
final DutyCycleOut m_motorRequest = new DutyCycleOut(0);
// reduce the update frequency to 50 Hz
m_motorRequest.UpdateFreqHz = 50;
// create a duty cycle request
controls::DutyCycleOut m_motorRequest{0};
// reduce the update frequency to 50 Hz
m_motorRequest.UpdateFreqHz = 50;
# create a duty cycle request
self.motor_request = controls.DutyCycleOut(0)
# reduce the update frequency to 50 Hz
self.motor_request.update_freq_hz = 50

Tip

UpdateFreqHz can be set to 0 Hz to synchronously one-shot the control request. In this case, users must ensure the control request is sent periodically in their robot code. Therefore, we recommend users call setControl no slower than 20 Hz (50 ms) when the control is one-shot.