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