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