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