CTRE Phoenix 6 C++ 24.50.0-alpha-2
MotionMagicVelocityDutyCycle.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/angular_velocity.h>
14#include <units/angular_acceleration.h>
15#include <units/dimensionless.h>
16#include <units/frequency.h>
17#include <units/time.h>
18
19
20namespace ctre {
21namespace phoenix6 {
22namespace controls {
23
24/**
25 * Requests Motion Magic® to target a final velocity using a motion profile.
26 * This allows smooth transitions between velocity set points. Users can
27 * optionally provide a duty cycle feedforward.
28 *
29 * Motion Magic® Velocity produces a motion profile in real-time while attempting to honor the specified
30 * Acceleration and Jerk value. This control mode does not use the CruiseVelocity, Expo_kV, or Expo_kA
31 * configs.
32 *
33 * If the specified acceleration is zero, the Acceleration under Motion Magic® configuration parameter is used
34 * instead. This allows for runtime adjustment of acceleration for advanced users. Jerk is also specified in
35 * the Motion Magic® persistent configuration values. If Jerk is set to zero, Motion Magic® will produce a
36 * trapezoidal acceleration profile.
37 *
38 * Target velocity can also be changed on-the-fly and Motion Magic® will do its best to adjust the profile.
39 * This control mode is duty cycle based, so relevant closed-loop gains will use fractional duty cycle for the
40 * numerator: +1.0 represents full forward output.
41 */
43{
44 ctre::phoenix::StatusCode SendRequest(const char *network, uint32_t deviceHash, std::shared_ptr<ControlRequest> &req) override
45 {
46 if (req.get() != this)
47 {
48 auto const reqCast = dynamic_cast<MotionMagicVelocityDutyCycle *>(req.get());
49 if (reqCast != nullptr)
50 {
51 *reqCast = *this;
52 }
53 else
54 {
55 req = std::make_shared<MotionMagicVelocityDutyCycle>(*this);
56 }
57 }
58
60 }
61
62public:
63 /**
64 * Target velocity to drive toward in rotations per second. This can be changed
65 * on-the fly.
66 */
67 units::angular_velocity::turns_per_second_t Velocity;
68 /**
69 * This is the absolute Acceleration to use generating the profile. If this
70 * parameter is zero, the Acceleration persistent configuration parameter is
71 * used instead. Acceleration is in rotations per second squared. If nonzero,
72 * the signage does not matter as the absolute value is used.
73 */
74 units::angular_acceleration::turns_per_second_squared_t Acceleration;
75 /**
76 * Set to true to use FOC commutation (requires Phoenix Pro), which increases
77 * peak power by ~15%. Set to false to use trapezoidal commutation.
78 *
79 * FOC improves motor performance by leveraging torque (current) control.
80 * However, this may be inconvenient for applications that require specifying
81 * duty cycle or voltage. CTR-Electronics has developed a hybrid method that
82 * combines the performances gains of FOC while still allowing applications to
83 * provide duty cycle or voltage demand. This not to be confused with simple
84 * sinusoidal control or phase voltage control which lacks the performance
85 * gains.
86 */
88 /**
89 * Feedforward to apply in fractional units between -1 and +1.
90 */
91 units::dimensionless::scalar_t FeedForward;
92 /**
93 * Select which gains are applied by selecting the slot. Use the configuration
94 * api to set the gain values for the selected slot before enabling this
95 * feature. Slot must be within [0,2].
96 */
97 int Slot;
98 /**
99 * Set to true to static-brake the rotor when output is zero (or within
100 * deadband). Set to false to use the NeutralMode configuration setting
101 * (default). This flag exists to provide the fundamental behavior of this
102 * control when output is zero, which is to provide 0V to the motor.
103 */
105 /**
106 * Set to true to force forward limiting. This allows users to use other limit
107 * switch sensors connected to robot controller. This also allows use of active
108 * sensors that require external power.
109 */
111 /**
112 * Set to true to force reverse limiting. This allows users to use other limit
113 * switch sensors connected to robot controller. This also allows use of active
114 * sensors that require external power.
115 */
117 /**
118 * Set to true to delay applying this control request until a timesync boundary
119 * (requires Phoenix Pro and CANivore). This eliminates the impact of
120 * nondeterministic network delays in exchange for a larger but deterministic
121 * control latency.
122 */
124
125 /**
126 * \brief The period at which this control will update at.
127 * This is designated in Hertz, with a minimum of 20 Hz
128 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
129 *
130 * If this field is set to 0 Hz, the control request will
131 * be sent immediately as a one-shot frame. This may be useful
132 * for advanced applications that require outputs to be
133 * synchronized with data acquisition. In this case, we
134 * recommend not exceeding 50 ms between control calls.
135 */
136 units::frequency::hertz_t UpdateFreqHz{100_Hz}; // Default to 100_Hz
137
138 /**
139 * \brief Requests Motion Magic® to target a final velocity using a motion
140 * profile. This allows smooth transitions between velocity set points.
141 * Users can optionally provide a duty cycle feedforward.
142 *
143 * \details Motion Magic® Velocity produces a motion profile in real-time while
144 * attempting to honor the specified Acceleration and Jerk value. This
145 * control mode does not use the CruiseVelocity, Expo_kV, or Expo_kA
146 * configs.
147 *
148 * If the specified acceleration is zero, the Acceleration under Motion
149 * Magic® configuration parameter is used instead. This allows for
150 * runtime adjustment of acceleration for advanced users. Jerk is also
151 * specified in the Motion Magic® persistent configuration values. If
152 * Jerk is set to zero, Motion Magic® will produce a trapezoidal
153 * acceleration profile.
154 *
155 * Target velocity can also be changed on-the-fly and Motion Magic®
156 * will do its best to adjust the profile. This control mode is duty
157 * cycle based, so relevant closed-loop gains will use fractional duty
158 * cycle for the numerator: +1.0 represents full forward output.
159 *
160 * \param Velocity Target velocity to drive toward in rotations per second.
161 * This can be changed on-the fly.
162 * \param Acceleration This is the absolute Acceleration to use generating
163 * the profile. If this parameter is zero, the
164 * Acceleration persistent configuration parameter is
165 * used instead. Acceleration is in rotations per second
166 * squared. If nonzero, the signage does not matter as
167 * the absolute value is used.
168 * \param EnableFOC Set to true to use FOC commutation (requires Phoenix
169 * Pro), which increases peak power by ~15%. Set to false to
170 * use trapezoidal commutation.
171 *
172 * FOC improves motor performance by leveraging torque
173 * (current) control. However, this may be inconvenient for
174 * applications that require specifying duty cycle or
175 * voltage. CTR-Electronics has developed a hybrid method
176 * that combines the performances gains of FOC while still
177 * allowing applications to provide duty cycle or voltage
178 * demand. This not to be confused with simple sinusoidal
179 * control or phase voltage control which lacks the
180 * performance gains.
181 * \param FeedForward Feedforward to apply in fractional units between -1 and
182 * +1.
183 * \param Slot Select which gains are applied by selecting the slot. Use the
184 * configuration api to set the gain values for the selected slot
185 * before enabling this feature. Slot must be within [0,2].
186 * \param OverrideBrakeDurNeutral Set to true to static-brake the rotor when
187 * output is zero (or within deadband). Set
188 * to false to use the NeutralMode
189 * configuration setting (default). This flag
190 * exists to provide the fundamental behavior
191 * of this control when output is zero, which
192 * is to provide 0V to the motor.
193 * \param LimitForwardMotion Set to true to force forward limiting. This
194 * allows users to use other limit switch sensors
195 * connected to robot controller. This also allows
196 * use of active sensors that require external
197 * power.
198 * \param LimitReverseMotion Set to true to force reverse limiting. This
199 * allows users to use other limit switch sensors
200 * connected to robot controller. This also allows
201 * use of active sensors that require external
202 * power.
203 * \param UseTimesync Set to true to delay applying this control request
204 * until a timesync boundary (requires Phoenix Pro and
205 * CANivore). This eliminates the impact of
206 * nondeterministic network delays in exchange for a
207 * larger but deterministic control latency.
208 */
209 MotionMagicVelocityDutyCycle(units::angular_velocity::turns_per_second_t Velocity, units::angular_acceleration::turns_per_second_squared_t Acceleration = 0.0_tr_per_s_sq, bool EnableFOC = true, units::dimensionless::scalar_t FeedForward = 0.0, int Slot = 0, bool OverrideBrakeDurNeutral = false, bool LimitForwardMotion = false, bool LimitReverseMotion = false, bool UseTimesync = false) : ControlRequest{"MotionMagicVelocityDutyCycle"},
210 Velocity{std::move(Velocity)},
212 EnableFOC{std::move(EnableFOC)},
214 Slot{std::move(Slot)},
219 {}
220
221 /**
222 * \brief Modifies this Control Request's Velocity parameter and returns itself for
223 * method-chaining and easier to use request API.
224 *
225 * Target velocity to drive toward in rotations per second. This can be changed
226 * on-the fly.
227 *
228 * \param newVelocity Parameter to modify
229 * \returns Itself
230 */
231 MotionMagicVelocityDutyCycle& WithVelocity(units::angular_velocity::turns_per_second_t newVelocity)
232 {
233 Velocity = std::move(newVelocity);
234 return *this;
235 }
236
237 /**
238 * \brief Modifies this Control Request's Acceleration parameter and returns itself for
239 * method-chaining and easier to use request API.
240 *
241 * This is the absolute Acceleration to use generating the profile. If this
242 * parameter is zero, the Acceleration persistent configuration parameter is
243 * used instead. Acceleration is in rotations per second squared. If nonzero,
244 * the signage does not matter as the absolute value is used.
245 *
246 * \param newAcceleration Parameter to modify
247 * \returns Itself
248 */
249 MotionMagicVelocityDutyCycle& WithAcceleration(units::angular_acceleration::turns_per_second_squared_t newAcceleration)
250 {
251 Acceleration = std::move(newAcceleration);
252 return *this;
253 }
254
255 /**
256 * \brief Modifies this Control Request's EnableFOC parameter and returns itself for
257 * method-chaining and easier to use request API.
258 *
259 * Set to true to use FOC commutation (requires Phoenix Pro), which increases
260 * peak power by ~15%. Set to false to use trapezoidal commutation.
261 *
262 * FOC improves motor performance by leveraging torque (current) control.
263 * However, this may be inconvenient for applications that require specifying
264 * duty cycle or voltage. CTR-Electronics has developed a hybrid method that
265 * combines the performances gains of FOC while still allowing applications to
266 * provide duty cycle or voltage demand. This not to be confused with simple
267 * sinusoidal control or phase voltage control which lacks the performance
268 * gains.
269 *
270 * \param newEnableFOC Parameter to modify
271 * \returns Itself
272 */
274 {
275 EnableFOC = std::move(newEnableFOC);
276 return *this;
277 }
278
279 /**
280 * \brief Modifies this Control Request's FeedForward parameter and returns itself for
281 * method-chaining and easier to use request API.
282 *
283 * Feedforward to apply in fractional units between -1 and +1.
284 *
285 * \param newFeedForward Parameter to modify
286 * \returns Itself
287 */
288 MotionMagicVelocityDutyCycle& WithFeedForward(units::dimensionless::scalar_t newFeedForward)
289 {
290 FeedForward = std::move(newFeedForward);
291 return *this;
292 }
293
294 /**
295 * \brief Modifies this Control Request's Slot parameter and returns itself for
296 * method-chaining and easier to use request API.
297 *
298 * Select which gains are applied by selecting the slot. Use the configuration
299 * api to set the gain values for the selected slot before enabling this
300 * feature. Slot must be within [0,2].
301 *
302 * \param newSlot Parameter to modify
303 * \returns Itself
304 */
306 {
307 Slot = std::move(newSlot);
308 return *this;
309 }
310
311 /**
312 * \brief Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for
313 * method-chaining and easier to use request API.
314 *
315 * Set to true to static-brake the rotor when output is zero (or within
316 * deadband). Set to false to use the NeutralMode configuration setting
317 * (default). This flag exists to provide the fundamental behavior of this
318 * control when output is zero, which is to provide 0V to the motor.
319 *
320 * \param newOverrideBrakeDurNeutral Parameter to modify
321 * \returns Itself
322 */
324 {
325 OverrideBrakeDurNeutral = std::move(newOverrideBrakeDurNeutral);
326 return *this;
327 }
328
329 /**
330 * \brief Modifies this Control Request's LimitForwardMotion parameter and returns itself for
331 * method-chaining and easier to use request API.
332 *
333 * Set to true to force forward limiting. This allows users to use other limit
334 * switch sensors connected to robot controller. This also allows use of active
335 * sensors that require external power.
336 *
337 * \param newLimitForwardMotion Parameter to modify
338 * \returns Itself
339 */
341 {
342 LimitForwardMotion = std::move(newLimitForwardMotion);
343 return *this;
344 }
345
346 /**
347 * \brief Modifies this Control Request's LimitReverseMotion parameter and returns itself for
348 * method-chaining and easier to use request API.
349 *
350 * Set to true to force reverse limiting. This allows users to use other limit
351 * switch sensors connected to robot controller. This also allows use of active
352 * sensors that require external power.
353 *
354 * \param newLimitReverseMotion Parameter to modify
355 * \returns Itself
356 */
358 {
359 LimitReverseMotion = std::move(newLimitReverseMotion);
360 return *this;
361 }
362
363 /**
364 * \brief Modifies this Control Request's UseTimesync parameter and returns itself for
365 * method-chaining and easier to use request API.
366 *
367 * Set to true to delay applying this control request until a timesync boundary
368 * (requires Phoenix Pro and CANivore). This eliminates the impact of
369 * nondeterministic network delays in exchange for a larger but deterministic
370 * control latency.
371 *
372 * \param newUseTimesync Parameter to modify
373 * \returns Itself
374 */
376 {
377 UseTimesync = std::move(newUseTimesync);
378 return *this;
379 }
380 /**
381 * \brief Sets the period at which this control will update at.
382 * This is designated in Hertz, with a minimum of 20 Hz
383 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
384 *
385 * If this field is set to 0 Hz, the control request will
386 * be sent immediately as a one-shot frame. This may be useful
387 * for advanced applications that require outputs to be
388 * synchronized with data acquisition. In this case, we
389 * recommend not exceeding 50 ms between control calls.
390 *
391 * \param newUpdateFreqHz Parameter to modify
392 * \returns Itself
393 */
394 MotionMagicVelocityDutyCycle &WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
395 {
396 UpdateFreqHz = newUpdateFreqHz;
397 return *this;
398 }
399 /**
400 * Returns a string representation of the object.
401 *
402 * \returns a string representation of the object.
403 */
404 std::string ToString() const override
405 {
406 std::stringstream ss;
407 ss << "Control: MotionMagicVelocityDutyCycle" << std::endl;
408 ss << " Velocity: " << Velocity.to<double>() << " rotations per second" << std::endl;
409 ss << " Acceleration: " << Acceleration.to<double>() << " rotations per second²" << std::endl;
410 ss << " EnableFOC: " << EnableFOC << std::endl;
411 ss << " FeedForward: " << FeedForward.to<double>() << " fractional" << std::endl;
412 ss << " Slot: " << Slot << std::endl;
413 ss << " OverrideBrakeDurNeutral: " << OverrideBrakeDurNeutral << std::endl;
414 ss << " LimitForwardMotion: " << LimitForwardMotion << std::endl;
415 ss << " LimitReverseMotion: " << LimitReverseMotion << std::endl;
416 ss << " UseTimesync: " << UseTimesync << std::endl;
417 return ss.str();
418 }
419
420 /**
421 * \brief Gets information about this control request.
422 *
423 * \returns Map of control parameter names and corresponding applied values
424 */
425 std::map<std::string, std::string> GetControlInfo() const override
426 {
427 std::map<std::string, std::string> controlInfo;
428 std::stringstream ss;
429 controlInfo["Name"] = GetName();
430 ss << Velocity.to<double>(); controlInfo["Velocity"] = ss.str(); ss.str(std::string{});
431 ss << Acceleration.to<double>(); controlInfo["Acceleration"] = ss.str(); ss.str(std::string{});
432 ss << EnableFOC; controlInfo["EnableFOC"] = ss.str(); ss.str(std::string{});
433 ss << FeedForward.to<double>(); controlInfo["FeedForward"] = ss.str(); ss.str(std::string{});
434 ss << Slot; controlInfo["Slot"] = ss.str(); ss.str(std::string{});
435 ss << OverrideBrakeDurNeutral; controlInfo["OverrideBrakeDurNeutral"] = ss.str(); ss.str(std::string{});
436 ss << LimitForwardMotion; controlInfo["LimitForwardMotion"] = ss.str(); ss.str(std::string{});
437 ss << LimitReverseMotion; controlInfo["LimitReverseMotion"] = ss.str(); ss.str(std::string{});
438 ss << UseTimesync; controlInfo["UseTimesync"] = ss.str(); ss.str(std::string{});
439 return controlInfo;
440 }
441};
442
443}
444}
445}
446
CTREXPORT int c_ctre_phoenix6_RequestControlMotionMagicVelocityDutyCycle(const char *canbus, uint32_t ecuEncoding, double updateTime, double Velocity, double Acceleration, bool EnableFOC, double FeedForward, int Slot, bool OverrideBrakeDurNeutral, bool LimitForwardMotion, bool LimitReverseMotion, bool UseTimesync)
Abstract Control Request class that other control requests extend for use.
Definition: ControlRequest.hpp:29
std::string const & GetName() const
Definition: ControlRequest.hpp:52
Requests Motion Magic® to target a final velocity using a motion profile.
Definition: MotionMagicVelocityDutyCycle.hpp:43
units::dimensionless::scalar_t FeedForward
Feedforward to apply in fractional units between -1 and +1.
Definition: MotionMagicVelocityDutyCycle.hpp:91
MotionMagicVelocityDutyCycle & WithLimitForwardMotion(bool newLimitForwardMotion)
Modifies this Control Request's LimitForwardMotion parameter and returns itself for method-chaining a...
Definition: MotionMagicVelocityDutyCycle.hpp:340
MotionMagicVelocityDutyCycle & WithOverrideBrakeDurNeutral(bool newOverrideBrakeDurNeutral)
Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for method-chain...
Definition: MotionMagicVelocityDutyCycle.hpp:323
MotionMagicVelocityDutyCycle & WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
Sets the period at which this control will update at.
Definition: MotionMagicVelocityDutyCycle.hpp:394
MotionMagicVelocityDutyCycle & WithEnableFOC(bool newEnableFOC)
Modifies this Control Request's EnableFOC parameter and returns itself for method-chaining and easier...
Definition: MotionMagicVelocityDutyCycle.hpp:273
bool UseTimesync
Set to true to delay applying this control request until a timesync boundary (requires Phoenix Pro an...
Definition: MotionMagicVelocityDutyCycle.hpp:123
MotionMagicVelocityDutyCycle & WithAcceleration(units::angular_acceleration::turns_per_second_squared_t newAcceleration)
Modifies this Control Request's Acceleration parameter and returns itself for method-chaining and eas...
Definition: MotionMagicVelocityDutyCycle.hpp:249
MotionMagicVelocityDutyCycle & WithFeedForward(units::dimensionless::scalar_t newFeedForward)
Modifies this Control Request's FeedForward parameter and returns itself for method-chaining and easi...
Definition: MotionMagicVelocityDutyCycle.hpp:288
units::angular_velocity::turns_per_second_t Velocity
Target velocity to drive toward in rotations per second.
Definition: MotionMagicVelocityDutyCycle.hpp:67
bool LimitReverseMotion
Set to true to force reverse limiting.
Definition: MotionMagicVelocityDutyCycle.hpp:116
MotionMagicVelocityDutyCycle & WithUseTimesync(bool newUseTimesync)
Modifies this Control Request's UseTimesync parameter and returns itself for method-chaining and easi...
Definition: MotionMagicVelocityDutyCycle.hpp:375
std::string ToString() const override
Returns a string representation of the object.
Definition: MotionMagicVelocityDutyCycle.hpp:404
MotionMagicVelocityDutyCycle & WithSlot(int newSlot)
Modifies this Control Request's Slot parameter and returns itself for method-chaining and easier to u...
Definition: MotionMagicVelocityDutyCycle.hpp:305
int Slot
Select which gains are applied by selecting the slot.
Definition: MotionMagicVelocityDutyCycle.hpp:97
units::frequency::hertz_t UpdateFreqHz
The period at which this control will update at.
Definition: MotionMagicVelocityDutyCycle.hpp:136
bool EnableFOC
Set to true to use FOC commutation (requires Phoenix Pro), which increases peak power by ~15%.
Definition: MotionMagicVelocityDutyCycle.hpp:87
units::angular_acceleration::turns_per_second_squared_t Acceleration
This is the absolute Acceleration to use generating the profile.
Definition: MotionMagicVelocityDutyCycle.hpp:74
bool OverrideBrakeDurNeutral
Set to true to static-brake the rotor when output is zero (or within deadband).
Definition: MotionMagicVelocityDutyCycle.hpp:104
std::map< std::string, std::string > GetControlInfo() const override
Gets information about this control request.
Definition: MotionMagicVelocityDutyCycle.hpp:425
MotionMagicVelocityDutyCycle & WithLimitReverseMotion(bool newLimitReverseMotion)
Modifies this Control Request's LimitReverseMotion parameter and returns itself for method-chaining a...
Definition: MotionMagicVelocityDutyCycle.hpp:357
MotionMagicVelocityDutyCycle(units::angular_velocity::turns_per_second_t Velocity, units::angular_acceleration::turns_per_second_squared_t Acceleration=0.0_tr_per_s_sq, bool EnableFOC=true, units::dimensionless::scalar_t FeedForward=0.0, int Slot=0, bool OverrideBrakeDurNeutral=false, bool LimitForwardMotion=false, bool LimitReverseMotion=false, bool UseTimesync=false)
Requests Motion Magic® to target a final velocity using a motion profile.
Definition: MotionMagicVelocityDutyCycle.hpp:209
bool LimitForwardMotion
Set to true to force forward limiting.
Definition: MotionMagicVelocityDutyCycle.hpp:110
MotionMagicVelocityDutyCycle & WithVelocity(units::angular_velocity::turns_per_second_t newVelocity)
Modifies this Control Request's Velocity parameter and returns itself for method-chaining and easier ...
Definition: MotionMagicVelocityDutyCycle.hpp:231
Status codes reported by APIs, including OK, warnings, and errors.
Definition: StatusCodes.h:27
Represents the state of one swerve module.
Definition: StatusCodes.h:18
Definition: span.hpp:401