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