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