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