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