CTRE Phoenix 6 C++ 24.2.0
DifferentialDutyCycle.hpp
Go to the documentation of this file.
1/*
2 * Copyright (C) Cross The Road Electronics.  All rights reserved.
3 * License information can be found in CTRE_LICENSE.txt
4 * For support and suggestions contact support@ctr-electronics.com or file
5 * an issue tracker at https://github.com/CrossTheRoadElec/Phoenix-Releases
6 */
7#pragma once
8
12#include <sstream>
13#include <units/dimensionless.h>
14#include <units/angle.h>
15#include <units/frequency.h>
16#include <units/time.h>
17
18
19namespace ctre {
20namespace phoenix6 {
21namespace controls {
22
23/**
24 * Request a specified motor duty cycle with a differential position
25 * closed-loop.
26 *
27 * This control mode will output a proportion of the supplied voltage which is supplied by the user. It will
28 * also set the motor's differential position setpoint to the specified position.
29 */
31{
32 ctre::phoenix::StatusCode SendRequest(const char *network, uint32_t deviceHash, bool cancelOtherRequests, std::shared_ptr<ControlRequest> &req) override
33 {
34 if (req.get() != this)
35 {
36 auto const reqCast = dynamic_cast<DifferentialDutyCycle *>(req.get());
37 if (reqCast != nullptr)
38 {
39 *reqCast = *this;
40 }
41 else
42 {
43 req = std::make_shared<DifferentialDutyCycle>(*this);
44 }
45 }
46
48 }
49
50public:
51 /**
52 * Proportion of supply voltage to apply in fractional units between -1 and +1
53 */
54 units::dimensionless::scalar_t TargetOutput;
55 /**
56 * Differential position to drive towards in rotations
57 */
58 units::angle::turn_t DifferentialPosition;
59 /**
60 * Set to true to use FOC commutation (requires Phoenix Pro), which increases
61 * peak power by ~15%. Set to false to use trapezoidal commutation. FOC
62 * improves motor performance by leveraging torque (current) control. However,
63 * this may be inconvenient for applications that require specifying duty cycle
64 * or voltage. CTR-Electronics has developed a hybrid method that combines the
65 * performances gains of FOC while still allowing applications to provide duty
66 * cycle or voltage demand. This not to be confused with simple sinusoidal
67 * control or phase voltage control which lacks the performance gains.
68 */
70 /**
71 * Select which gains are applied to the differential controller by selecting
72 * the slot. Use the configuration api to set the gain values for the selected
73 * slot before enabling this feature. Slot must be within [0,2].
74 */
76 /**
77 * Set to true to static-brake the rotor when output is zero (or within
78 * deadband). Set to false to use the NeutralMode configuration setting
79 * (default). This flag exists to provide the fundamental behavior of this
80 * control when output is zero, which is to provide 0V to the motor.
81 */
83 /**
84 * Set to true to force forward limiting. This allows users to use other limit
85 * switch sensors connected to robot controller. This also allows use of active
86 * sensors that require external power.
87 */
89 /**
90 * Set to true to force reverse limiting. This allows users to use other limit
91 * switch sensors connected to robot controller. This also allows use of active
92 * sensors that require external power.
93 */
95
96 /**
97 * \brief The period at which this control will update at.
98 * This is designated in Hertz, with a minimum of 20 Hz
99 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
100 *
101 * If this field is set to 0 Hz, the control request will
102 * be sent immediately as a one-shot frame. This may be useful
103 * for advanced applications that require outputs to be
104 * synchronized with data acquisition. In this case, we
105 * recommend not exceeding 50 ms between control calls.
106 */
107 units::frequency::hertz_t UpdateFreqHz{100_Hz}; // Default to 100_Hz
108
109 /**
110 * \brief Request a specified motor duty cycle with a differential position
111 * closed-loop.
112 *
113 * \details This control mode will output a proportion of the supplied voltage
114 * which is supplied by the user. It will also set the motor's
115 * differential position setpoint to the specified position.
116 *
117 * \param TargetOutput Proportion of supply voltage to apply in fractional
118 * units between -1 and +1
119 * \param DifferentialPosition Differential position to drive towards in
120 * rotations
121 * \param EnableFOC Set to true to use FOC commutation (requires Phoenix
122 * Pro), which increases peak power by ~15%. Set to false to
123 * use trapezoidal commutation. FOC improves motor
124 * performance by leveraging torque (current) control.
125 * However, this may be inconvenient for applications that
126 * require specifying duty cycle or voltage.
127 * CTR-Electronics has developed a hybrid method that
128 * combines the performances gains of FOC while still
129 * allowing applications to provide duty cycle or voltage
130 * demand. This not to be confused with simple sinusoidal
131 * control or phase voltage control which lacks the
132 * performance gains.
133 * \param DifferentialSlot Select which gains are applied to the differential
134 * controller by selecting the slot. Use the
135 * configuration api to set the gain values for the
136 * selected slot before enabling this feature. Slot
137 * must be within [0,2].
138 * \param OverrideBrakeDurNeutral Set to true to static-brake the rotor when
139 * output is zero (or within deadband). Set
140 * to false to use the NeutralMode
141 * configuration setting (default). This flag
142 * exists to provide the fundamental behavior
143 * of this control when output is zero, which
144 * is to provide 0V to the motor.
145 * \param LimitForwardMotion Set to true to force forward limiting. This
146 * allows users to use other limit switch sensors
147 * connected to robot controller. This also allows
148 * use of active sensors that require external
149 * power.
150 * \param LimitReverseMotion Set to true to force reverse limiting. This
151 * allows users to use other limit switch sensors
152 * connected to robot controller. This also allows
153 * use of active sensors that require external
154 * power.
155 */
156 DifferentialDutyCycle(units::dimensionless::scalar_t TargetOutput, units::angle::turn_t DifferentialPosition, bool EnableFOC = true, int DifferentialSlot = 1, bool OverrideBrakeDurNeutral = false, bool LimitForwardMotion = false, bool LimitReverseMotion = false) : ControlRequest{"DifferentialDutyCycle"},
157 TargetOutput{std::move(TargetOutput)},
159 EnableFOC{std::move(EnableFOC)},
164 {}
165
166 /**
167 * \brief Modifies this Control Request's TargetOutput parameter and returns itself for
168 * method-chaining and easier to use request API.
169 * \param newTargetOutput Parameter to modify
170 * \returns Itself
171 */
172 DifferentialDutyCycle& WithTargetOutput(units::dimensionless::scalar_t newTargetOutput)
173 {
174 TargetOutput = std::move(newTargetOutput);
175 return *this;
176 }
177
178 /**
179 * \brief Modifies this Control Request's DifferentialPosition parameter and returns itself for
180 * method-chaining and easier to use request API.
181 * \param newDifferentialPosition Parameter to modify
182 * \returns Itself
183 */
184 DifferentialDutyCycle& WithDifferentialPosition(units::angle::turn_t newDifferentialPosition)
185 {
186 DifferentialPosition = std::move(newDifferentialPosition);
187 return *this;
188 }
189
190 /**
191 * \brief Modifies this Control Request's EnableFOC parameter and returns itself for
192 * method-chaining and easier to use request API.
193 * \param newEnableFOC Parameter to modify
194 * \returns Itself
195 */
197 {
198 EnableFOC = std::move(newEnableFOC);
199 return *this;
200 }
201
202 /**
203 * \brief Modifies this Control Request's DifferentialSlot parameter and returns itself for
204 * method-chaining and easier to use request API.
205 * \param newDifferentialSlot Parameter to modify
206 * \returns Itself
207 */
209 {
210 DifferentialSlot = std::move(newDifferentialSlot);
211 return *this;
212 }
213
214 /**
215 * \brief Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for
216 * method-chaining and easier to use request API.
217 * \param newOverrideBrakeDurNeutral Parameter to modify
218 * \returns Itself
219 */
220 DifferentialDutyCycle& WithOverrideBrakeDurNeutral(bool newOverrideBrakeDurNeutral)
221 {
222 OverrideBrakeDurNeutral = std::move(newOverrideBrakeDurNeutral);
223 return *this;
224 }
225
226 /**
227 * \brief Modifies this Control Request's LimitForwardMotion parameter and returns itself for
228 * method-chaining and easier to use request API.
229 * \param newLimitForwardMotion Parameter to modify
230 * \returns Itself
231 */
233 {
234 LimitForwardMotion = std::move(newLimitForwardMotion);
235 return *this;
236 }
237
238 /**
239 * \brief Modifies this Control Request's LimitReverseMotion parameter and returns itself for
240 * method-chaining and easier to use request API.
241 * \param newLimitReverseMotion Parameter to modify
242 * \returns Itself
243 */
245 {
246 LimitReverseMotion = std::move(newLimitReverseMotion);
247 return *this;
248 }
249 /**
250 * \brief Sets the period at which this control will update at.
251 * This is designated in Hertz, with a minimum of 20 Hz
252 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
253 *
254 * If this field is set to 0 Hz, the control request will
255 * be sent immediately as a one-shot frame. This may be useful
256 * for advanced applications that require outputs to be
257 * synchronized with data acquisition. In this case, we
258 * recommend not exceeding 50 ms between control calls.
259 *
260 * \param newUpdateFreqHz Parameter to modify
261 * \returns Itself
262 */
263 DifferentialDutyCycle &WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
264 {
265 UpdateFreqHz = newUpdateFreqHz;
266 return *this;
267 }
268 /**
269 * Returns a string representation of the object.
270 *
271 * \returns a string representation of the object.
272 */
273 std::string ToString() const override
274 {
275 std::stringstream ss;
276 ss << "class: DifferentialDutyCycle" << std::endl;
277 ss << "TargetOutput: " << TargetOutput.to<double>() << std::endl;
278 ss << "DifferentialPosition: " << DifferentialPosition.to<double>() << std::endl;
279 ss << "EnableFOC: " << EnableFOC << std::endl;
280 ss << "DifferentialSlot: " << DifferentialSlot << std::endl;
281 ss << "OverrideBrakeDurNeutral: " << OverrideBrakeDurNeutral << std::endl;
282 ss << "LimitForwardMotion: " << LimitForwardMotion << std::endl;
283 ss << "LimitReverseMotion: " << LimitReverseMotion << std::endl;
284 return ss.str();
285 }
286
287 /**
288 * \brief Gets information about this control request.
289 *
290 * \returns Map of control parameter names and corresponding applied values
291 */
292 std::map<std::string, std::string> GetControlInfo() const override
293 {
294 std::map<std::string, std::string> controlInfo;
295 std::stringstream ss;
296 controlInfo["Name"] = GetName();
297 ss << TargetOutput.to<double>(); controlInfo["TargetOutput"] = ss.str(); ss.str(std::string{});
298 ss << DifferentialPosition.to<double>(); controlInfo["DifferentialPosition"] = ss.str(); ss.str(std::string{});
299 ss << EnableFOC; controlInfo["EnableFOC"] = ss.str(); ss.str(std::string{});
300 ss << DifferentialSlot; controlInfo["DifferentialSlot"] = ss.str(); ss.str(std::string{});
301 ss << OverrideBrakeDurNeutral; controlInfo["OverrideBrakeDurNeutral"] = ss.str(); ss.str(std::string{});
302 ss << LimitForwardMotion; controlInfo["LimitForwardMotion"] = ss.str(); ss.str(std::string{});
303 ss << LimitReverseMotion; controlInfo["LimitReverseMotion"] = ss.str(); ss.str(std::string{});
304 return controlInfo;
305 }
306};
307
308}
309}
310}
311
CTREXPORT int c_ctre_phoenix6_RequestControlDifferentialDutyCycle(const char *canbus, uint32_t ecuEncoding, double updateTime, bool cancelOtherRequests, double TargetOutput, double DifferentialPosition, bool EnableFOC, int DifferentialSlot, bool OverrideBrakeDurNeutral, bool LimitForwardMotion, bool LimitReverseMotion)
Abstract Control Request class that other control requests extend for use.
Definition: ControlRequest.hpp:28
std::string const & GetName() const
Definition: ControlRequest.hpp:51
Request a specified motor duty cycle with a differential position closed-loop.
Definition: DifferentialDutyCycle.hpp:31
std::string ToString() const override
Returns a string representation of the object.
Definition: DifferentialDutyCycle.hpp:273
std::map< std::string, std::string > GetControlInfo() const override
Gets information about this control request.
Definition: DifferentialDutyCycle.hpp:292
DifferentialDutyCycle & WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
Sets the period at which this control will update at.
Definition: DifferentialDutyCycle.hpp:263
units::angle::turn_t DifferentialPosition
Differential position to drive towards in rotations.
Definition: DifferentialDutyCycle.hpp:58
int DifferentialSlot
Select which gains are applied to the differential controller by selecting the slot.
Definition: DifferentialDutyCycle.hpp:75
DifferentialDutyCycle & WithOverrideBrakeDurNeutral(bool newOverrideBrakeDurNeutral)
Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for method-chain...
Definition: DifferentialDutyCycle.hpp:220
DifferentialDutyCycle & WithEnableFOC(bool newEnableFOC)
Modifies this Control Request's EnableFOC parameter and returns itself for method-chaining and easier...
Definition: DifferentialDutyCycle.hpp:196
DifferentialDutyCycle & WithDifferentialPosition(units::angle::turn_t newDifferentialPosition)
Modifies this Control Request's DifferentialPosition parameter and returns itself for method-chaining...
Definition: DifferentialDutyCycle.hpp:184
DifferentialDutyCycle & WithDifferentialSlot(int newDifferentialSlot)
Modifies this Control Request's DifferentialSlot parameter and returns itself for method-chaining and...
Definition: DifferentialDutyCycle.hpp:208
bool LimitReverseMotion
Set to true to force reverse limiting.
Definition: DifferentialDutyCycle.hpp:94
DifferentialDutyCycle & WithLimitForwardMotion(bool newLimitForwardMotion)
Modifies this Control Request's LimitForwardMotion parameter and returns itself for method-chaining a...
Definition: DifferentialDutyCycle.hpp:232
DifferentialDutyCycle & WithTargetOutput(units::dimensionless::scalar_t newTargetOutput)
Modifies this Control Request's TargetOutput parameter and returns itself for method-chaining and eas...
Definition: DifferentialDutyCycle.hpp:172
bool EnableFOC
Set to true to use FOC commutation (requires Phoenix Pro), which increases peak power by ~15%.
Definition: DifferentialDutyCycle.hpp:69
units::frequency::hertz_t UpdateFreqHz
The period at which this control will update at.
Definition: DifferentialDutyCycle.hpp:107
DifferentialDutyCycle(units::dimensionless::scalar_t TargetOutput, units::angle::turn_t DifferentialPosition, bool EnableFOC=true, int DifferentialSlot=1, bool OverrideBrakeDurNeutral=false, bool LimitForwardMotion=false, bool LimitReverseMotion=false)
Request a specified motor duty cycle with a differential position closed-loop.
Definition: DifferentialDutyCycle.hpp:156
bool LimitForwardMotion
Set to true to force forward limiting.
Definition: DifferentialDutyCycle.hpp:88
DifferentialDutyCycle & WithLimitReverseMotion(bool newLimitReverseMotion)
Modifies this Control Request's LimitReverseMotion parameter and returns itself for method-chaining a...
Definition: DifferentialDutyCycle.hpp:244
bool OverrideBrakeDurNeutral
Set to true to static-brake the rotor when output is zero (or within deadband).
Definition: DifferentialDutyCycle.hpp:82
units::dimensionless::scalar_t TargetOutput
Proportion of supply voltage to apply in fractional units between -1 and +1.
Definition: DifferentialDutyCycle.hpp:54
Definition: RcManualEvent.hpp:12