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