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