CTRE Phoenix 6 C++ 24.3.0
DifferentialPositionDutyCycle.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/angle.h>
14#include <units/frequency.h>
15#include <units/time.h>
16
17
18namespace ctre {
19namespace phoenix6 {
20namespace controls {
21
22/**
23 * Request PID to target position with a differential position setpoint.
24 *
25 * This control mode will set the motor's position setpoint to the position specified by the user. It will
26 * also set the motor's differential position setpoint to the specified position.
27 */
29{
30 ctre::phoenix::StatusCode SendRequest(const char *network, uint32_t deviceHash, bool cancelOtherRequests, std::shared_ptr<ControlRequest> &req) override
31 {
32 if (req.get() != this)
33 {
34 auto const reqCast = dynamic_cast<DifferentialPositionDutyCycle *>(req.get());
35 if (reqCast != nullptr)
36 {
37 *reqCast = *this;
38 }
39 else
40 {
41 req = std::make_shared<DifferentialPositionDutyCycle>(*this);
42 }
43 }
44
46 }
47
48public:
49 /**
50 * Average position to drive toward in rotations.
51 */
52 units::angle::turn_t TargetPosition;
53 /**
54 * Differential position to drive toward in rotations.
55 */
56 units::angle::turn_t DifferentialPosition;
57 /**
58 * Set to true to use FOC commutation (requires Phoenix Pro), which increases
59 * peak power by ~15%. Set to false to use trapezoidal commutation.
60 *
61 * FOC improves motor performance by leveraging torque (current) control.
62 * However, this may be inconvenient for applications that require specifying
63 * duty cycle or voltage. CTR-Electronics has developed a hybrid method that
64 * combines the performances gains of FOC while still allowing applications to
65 * provide duty cycle or voltage demand. This not to be confused with simple
66 * sinusoidal control or phase voltage control which lacks the performance
67 * gains.
68 */
70 /**
71 * Select which gains are applied to the primary controller by selecting the
72 * slot. Use the configuration api to set the gain values for the selected slot
73 * before enabling this feature. Slot must be within [0,2].
74 */
76 /**
77 * Select which gains are applied to the differential controller by selecting
78 * the slot. Use the configuration api to set the gain values for the selected
79 * slot before enabling this feature. Slot must be within [0,2].
80 */
82 /**
83 * Set to true to static-brake the rotor when output is zero (or within
84 * deadband). Set to false to use the NeutralMode configuration setting
85 * (default). This flag exists to provide the fundamental behavior of this
86 * control when output is zero, which is to provide 0V to the motor.
87 */
89 /**
90 * Set to true to force forward 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 * Set to true to force reverse limiting. This allows users to use other limit
97 * switch sensors connected to robot controller. This also allows use of active
98 * sensors that require external power.
99 */
101
102 /**
103 * \brief The period at which this control will update at.
104 * This is designated in Hertz, with a minimum of 20 Hz
105 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
106 *
107 * If this field is set to 0 Hz, the control request will
108 * be sent immediately as a one-shot frame. This may be useful
109 * for advanced applications that require outputs to be
110 * synchronized with data acquisition. In this case, we
111 * recommend not exceeding 50 ms between control calls.
112 */
113 units::frequency::hertz_t UpdateFreqHz{100_Hz}; // Default to 100_Hz
114
115 /**
116 * \brief Request PID to target position with a differential position setpoint.
117 *
118 * \details This control mode will set the motor's position setpoint to the
119 * position specified by the user. It will also set the motor's
120 * differential position setpoint to the specified position.
121 *
122 * \param TargetPosition Average position to drive toward in rotations.
123 * \param DifferentialPosition Differential position to drive toward in
124 * rotations.
125 * \param EnableFOC Set to true to use FOC commutation (requires Phoenix
126 * Pro), which increases peak power by ~15%. Set to false to
127 * use trapezoidal commutation.
128 *
129 * FOC improves motor performance by leveraging torque
130 * (current) control. However, this may be inconvenient for
131 * applications that require specifying duty cycle or
132 * voltage. CTR-Electronics has developed a hybrid method
133 * that combines the performances gains of FOC while still
134 * allowing applications to provide duty cycle or voltage
135 * demand. This not to be confused with simple sinusoidal
136 * control or phase voltage control which lacks the
137 * performance gains.
138 * \param TargetSlot Select which gains are applied to the primary controller
139 * by selecting the slot. Use the configuration api to set
140 * the gain values for the selected slot before enabling
141 * this feature. Slot must be within [0,2].
142 * \param DifferentialSlot Select which gains are applied to the differential
143 * controller by selecting the slot. Use the
144 * configuration api to set the gain values for the
145 * selected slot before enabling this feature. Slot
146 * must be within [0,2].
147 * \param OverrideBrakeDurNeutral Set to true to static-brake the rotor when
148 * output is zero (or within deadband). Set
149 * to false to use the NeutralMode
150 * configuration setting (default). This flag
151 * exists to provide the fundamental behavior
152 * of this control when output is zero, which
153 * is to provide 0V to the motor.
154 * \param LimitForwardMotion Set to true to force forward limiting. This
155 * allows users to use other limit switch sensors
156 * connected to robot controller. This also allows
157 * use of active sensors that require external
158 * power.
159 * \param LimitReverseMotion Set to true to force reverse limiting. This
160 * allows users to use other limit switch sensors
161 * connected to robot controller. This also allows
162 * use of active sensors that require external
163 * power.
164 */
165 DifferentialPositionDutyCycle(units::angle::turn_t TargetPosition, units::angle::turn_t DifferentialPosition, bool EnableFOC = true, int TargetSlot = 0, int DifferentialSlot = 1, bool OverrideBrakeDurNeutral = false, bool LimitForwardMotion = false, bool LimitReverseMotion = false) : ControlRequest{"DifferentialPositionDutyCycle"},
166 TargetPosition{std::move(TargetPosition)},
168 EnableFOC{std::move(EnableFOC)},
169 TargetSlot{std::move(TargetSlot)},
174 {}
175
176 /**
177 * \brief Modifies this Control Request's TargetPosition parameter and returns itself for
178 * method-chaining and easier to use request API.
179 *
180 * Average position to drive toward in rotations.
181 *
182 * \param newTargetPosition Parameter to modify
183 * \returns Itself
184 */
185 DifferentialPositionDutyCycle& WithTargetPosition(units::angle::turn_t newTargetPosition)
186 {
187 TargetPosition = std::move(newTargetPosition);
188 return *this;
189 }
190
191 /**
192 * \brief Modifies this Control Request's DifferentialPosition parameter and returns itself for
193 * method-chaining and easier to use request API.
194 *
195 * Differential position to drive toward in rotations.
196 *
197 * \param newDifferentialPosition Parameter to modify
198 * \returns Itself
199 */
200 DifferentialPositionDutyCycle& WithDifferentialPosition(units::angle::turn_t newDifferentialPosition)
201 {
202 DifferentialPosition = std::move(newDifferentialPosition);
203 return *this;
204 }
205
206 /**
207 * \brief Modifies this Control Request's EnableFOC parameter and returns itself for
208 * method-chaining and easier to use request API.
209 *
210 * Set to true to use FOC commutation (requires Phoenix Pro), which increases
211 * peak power by ~15%. Set to false to use trapezoidal commutation.
212 *
213 * FOC improves motor performance by leveraging torque (current) control.
214 * However, this may be inconvenient for applications that require specifying
215 * duty cycle or voltage. CTR-Electronics has developed a hybrid method that
216 * combines the performances gains of FOC while still allowing applications to
217 * provide duty cycle or voltage demand. This not to be confused with simple
218 * sinusoidal control or phase voltage control which lacks the performance
219 * gains.
220 *
221 * \param newEnableFOC Parameter to modify
222 * \returns Itself
223 */
225 {
226 EnableFOC = std::move(newEnableFOC);
227 return *this;
228 }
229
230 /**
231 * \brief Modifies this Control Request's TargetSlot parameter and returns itself for
232 * method-chaining and easier to use request API.
233 *
234 * Select which gains are applied to the primary controller by selecting the
235 * slot. Use the configuration api to set the gain values for the selected slot
236 * before enabling this feature. Slot must be within [0,2].
237 *
238 * \param newTargetSlot Parameter to modify
239 * \returns Itself
240 */
242 {
243 TargetSlot = std::move(newTargetSlot);
244 return *this;
245 }
246
247 /**
248 * \brief Modifies this Control Request's DifferentialSlot parameter and returns itself for
249 * method-chaining and easier to use request API.
250 *
251 * Select which gains are applied to the differential controller by selecting
252 * the slot. Use the configuration api to set the gain values for the selected
253 * slot before enabling this feature. Slot must be within [0,2].
254 *
255 * \param newDifferentialSlot Parameter to modify
256 * \returns Itself
257 */
259 {
260 DifferentialSlot = std::move(newDifferentialSlot);
261 return *this;
262 }
263
264 /**
265 * \brief Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for
266 * method-chaining and easier to use request API.
267 *
268 * Set to true to static-brake the rotor when output is zero (or within
269 * deadband). Set to false to use the NeutralMode configuration setting
270 * (default). This flag exists to provide the fundamental behavior of this
271 * control when output is zero, which is to provide 0V to the motor.
272 *
273 * \param newOverrideBrakeDurNeutral Parameter to modify
274 * \returns Itself
275 */
277 {
278 OverrideBrakeDurNeutral = std::move(newOverrideBrakeDurNeutral);
279 return *this;
280 }
281
282 /**
283 * \brief Modifies this Control Request's LimitForwardMotion parameter and returns itself for
284 * method-chaining and easier to use request API.
285 *
286 * Set to true to force forward limiting. This allows users to use other limit
287 * switch sensors connected to robot controller. This also allows use of active
288 * sensors that require external power.
289 *
290 * \param newLimitForwardMotion Parameter to modify
291 * \returns Itself
292 */
294 {
295 LimitForwardMotion = std::move(newLimitForwardMotion);
296 return *this;
297 }
298
299 /**
300 * \brief Modifies this Control Request's LimitReverseMotion parameter and returns itself for
301 * method-chaining and easier to use request API.
302 *
303 * Set to true to force reverse limiting. This allows users to use other limit
304 * switch sensors connected to robot controller. This also allows use of active
305 * sensors that require external power.
306 *
307 * \param newLimitReverseMotion Parameter to modify
308 * \returns Itself
309 */
311 {
312 LimitReverseMotion = std::move(newLimitReverseMotion);
313 return *this;
314 }
315 /**
316 * \brief Sets the period at which this control will update at.
317 * This is designated in Hertz, with a minimum of 20 Hz
318 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
319 *
320 * If this field is set to 0 Hz, the control request will
321 * be sent immediately as a one-shot frame. This may be useful
322 * for advanced applications that require outputs to be
323 * synchronized with data acquisition. In this case, we
324 * recommend not exceeding 50 ms between control calls.
325 *
326 * \param newUpdateFreqHz Parameter to modify
327 * \returns Itself
328 */
329 DifferentialPositionDutyCycle &WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
330 {
331 UpdateFreqHz = newUpdateFreqHz;
332 return *this;
333 }
334 /**
335 * Returns a string representation of the object.
336 *
337 * \returns a string representation of the object.
338 */
339 std::string ToString() const override
340 {
341 std::stringstream ss;
342 ss << "class: DifferentialPositionDutyCycle" << std::endl;
343 ss << "TargetPosition: " << TargetPosition.to<double>() << std::endl;
344 ss << "DifferentialPosition: " << DifferentialPosition.to<double>() << std::endl;
345 ss << "EnableFOC: " << EnableFOC << std::endl;
346 ss << "TargetSlot: " << TargetSlot << std::endl;
347 ss << "DifferentialSlot: " << DifferentialSlot << std::endl;
348 ss << "OverrideBrakeDurNeutral: " << OverrideBrakeDurNeutral << std::endl;
349 ss << "LimitForwardMotion: " << LimitForwardMotion << std::endl;
350 ss << "LimitReverseMotion: " << LimitReverseMotion << std::endl;
351 return ss.str();
352 }
353
354 /**
355 * \brief Gets information about this control request.
356 *
357 * \returns Map of control parameter names and corresponding applied values
358 */
359 std::map<std::string, std::string> GetControlInfo() const override
360 {
361 std::map<std::string, std::string> controlInfo;
362 std::stringstream ss;
363 controlInfo["Name"] = GetName();
364 ss << TargetPosition.to<double>(); controlInfo["TargetPosition"] = ss.str(); ss.str(std::string{});
365 ss << DifferentialPosition.to<double>(); controlInfo["DifferentialPosition"] = ss.str(); ss.str(std::string{});
366 ss << EnableFOC; controlInfo["EnableFOC"] = ss.str(); ss.str(std::string{});
367 ss << TargetSlot; controlInfo["TargetSlot"] = ss.str(); ss.str(std::string{});
368 ss << DifferentialSlot; controlInfo["DifferentialSlot"] = ss.str(); ss.str(std::string{});
369 ss << OverrideBrakeDurNeutral; controlInfo["OverrideBrakeDurNeutral"] = ss.str(); ss.str(std::string{});
370 ss << LimitForwardMotion; controlInfo["LimitForwardMotion"] = ss.str(); ss.str(std::string{});
371 ss << LimitReverseMotion; controlInfo["LimitReverseMotion"] = ss.str(); ss.str(std::string{});
372 return controlInfo;
373 }
374};
375
376}
377}
378}
379
CTREXPORT int c_ctre_phoenix6_RequestControlDifferentialPositionDutyCycle(const char *canbus, uint32_t ecuEncoding, double updateTime, bool cancelOtherRequests, double TargetPosition, double DifferentialPosition, bool EnableFOC, int TargetSlot, 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 PID to target position with a differential position setpoint.
Definition: DifferentialPositionDutyCycle.hpp:29
int TargetSlot
Select which gains are applied to the primary controller by selecting the slot.
Definition: DifferentialPositionDutyCycle.hpp:75
int DifferentialSlot
Select which gains are applied to the differential controller by selecting the slot.
Definition: DifferentialPositionDutyCycle.hpp:81
units::angle::turn_t DifferentialPosition
Differential position to drive toward in rotations.
Definition: DifferentialPositionDutyCycle.hpp:56
bool LimitReverseMotion
Set to true to force reverse limiting.
Definition: DifferentialPositionDutyCycle.hpp:100
DifferentialPositionDutyCycle & WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
Sets the period at which this control will update at.
Definition: DifferentialPositionDutyCycle.hpp:329
std::map< std::string, std::string > GetControlInfo() const override
Gets information about this control request.
Definition: DifferentialPositionDutyCycle.hpp:359
DifferentialPositionDutyCycle(units::angle::turn_t TargetPosition, units::angle::turn_t DifferentialPosition, bool EnableFOC=true, int TargetSlot=0, int DifferentialSlot=1, bool OverrideBrakeDurNeutral=false, bool LimitForwardMotion=false, bool LimitReverseMotion=false)
Request PID to target position with a differential position setpoint.
Definition: DifferentialPositionDutyCycle.hpp:165
DifferentialPositionDutyCycle & WithDifferentialSlot(int newDifferentialSlot)
Modifies this Control Request's DifferentialSlot parameter and returns itself for method-chaining and...
Definition: DifferentialPositionDutyCycle.hpp:258
units::frequency::hertz_t UpdateFreqHz
The period at which this control will update at.
Definition: DifferentialPositionDutyCycle.hpp:113
DifferentialPositionDutyCycle & WithDifferentialPosition(units::angle::turn_t newDifferentialPosition)
Modifies this Control Request's DifferentialPosition parameter and returns itself for method-chaining...
Definition: DifferentialPositionDutyCycle.hpp:200
bool EnableFOC
Set to true to use FOC commutation (requires Phoenix Pro), which increases peak power by ~15%.
Definition: DifferentialPositionDutyCycle.hpp:69
DifferentialPositionDutyCycle & WithEnableFOC(bool newEnableFOC)
Modifies this Control Request's EnableFOC parameter and returns itself for method-chaining and easier...
Definition: DifferentialPositionDutyCycle.hpp:224
DifferentialPositionDutyCycle & WithTargetSlot(int newTargetSlot)
Modifies this Control Request's TargetSlot parameter and returns itself for method-chaining and easie...
Definition: DifferentialPositionDutyCycle.hpp:241
bool LimitForwardMotion
Set to true to force forward limiting.
Definition: DifferentialPositionDutyCycle.hpp:94
DifferentialPositionDutyCycle & WithOverrideBrakeDurNeutral(bool newOverrideBrakeDurNeutral)
Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for method-chain...
Definition: DifferentialPositionDutyCycle.hpp:276
DifferentialPositionDutyCycle & WithLimitReverseMotion(bool newLimitReverseMotion)
Modifies this Control Request's LimitReverseMotion parameter and returns itself for method-chaining a...
Definition: DifferentialPositionDutyCycle.hpp:310
DifferentialPositionDutyCycle & WithTargetPosition(units::angle::turn_t newTargetPosition)
Modifies this Control Request's TargetPosition parameter and returns itself for method-chaining and e...
Definition: DifferentialPositionDutyCycle.hpp:185
units::angle::turn_t TargetPosition
Average position to drive toward in rotations.
Definition: DifferentialPositionDutyCycle.hpp:52
std::string ToString() const override
Returns a string representation of the object.
Definition: DifferentialPositionDutyCycle.hpp:339
DifferentialPositionDutyCycle & WithLimitForwardMotion(bool newLimitForwardMotion)
Modifies this Control Request's LimitForwardMotion parameter and returns itself for method-chaining a...
Definition: DifferentialPositionDutyCycle.hpp:293
bool OverrideBrakeDurNeutral
Set to true to static-brake the rotor when output is zero (or within deadband).
Definition: DifferentialPositionDutyCycle.hpp:88
Definition: string_util.hpp:15