Loading [MathJax]/extensions/tex2jax.js
CTRE Phoenix 6 C++ 25.4.0
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
DifferentialVoltage.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
13#include <units/frequency.h>
14#include <units/time.h>
15#include <units/voltage.h>
16#include <units/angle.h>
17
18namespace ctre {
19namespace phoenix6 {
20namespace controls {
21
22/**
23 * Request a specified voltage with a differential position closed-loop.
24 *
25 * This control mode will attempt to apply the specified voltage to the motor. If the supply voltage is below
26 * the requested voltage, the motor controller will output the supply voltage. It will also set the motor's
27 * differential position setpoint to the specified position.
28 */
30{
31 ctre::phoenix::StatusCode SendRequest(const char *network, uint32_t deviceHash, std::shared_ptr<ControlRequest> &req) const override
32 {
33 if (req.get() != this)
34 {
35 auto const reqCast = dynamic_cast<DifferentialVoltage *>(req.get());
36 if (reqCast != nullptr)
37 {
38 *reqCast = *this;
39 }
40 else
41 {
42 req = std::make_shared<DifferentialVoltage>(*this);
43 }
44 }
45
47 }
48
49public:
50 /**
51 * \brief Voltage to attempt to drive at
52 *
53 * - Units: Volts
54 *
55 */
56 units::voltage::volt_t TargetOutput;
57 /**
58 * \brief Differential position to drive towards in rotations
59 *
60 * - Units: rotations
61 *
62 */
63 units::angle::turn_t DifferentialPosition;
64 /**
65 * \brief Set to true to use FOC commutation (requires Phoenix Pro), which
66 * increases peak power by ~15% on supported devices (see
67 * hardware#traits#SupportsFOC). Set to false to use trapezoidal commutation.
68 *
69 * FOC improves motor performance by leveraging torque (current) control.
70 * However, this may be inconvenient for applications that require specifying
71 * duty cycle or voltage. CTR-Electronics has developed a hybrid method that
72 * combines the performances gains of FOC while still allowing applications to
73 * provide duty cycle or voltage demand. This not to be confused with simple
74 * sinusoidal control or phase voltage control which lacks the performance
75 * gains.
76 */
77 bool EnableFOC = true;
78 /**
79 * \brief Select which gains are applied to the differential controller by
80 * selecting the slot. Use the configuration api to set the gain values for the
81 * selected slot before enabling this feature. Slot must be within [0,2].
82 */
84 /**
85 * \brief Set to true to static-brake the rotor when output is zero (or within
86 * deadband). Set to false to use the NeutralMode configuration setting
87 * (default). This flag exists to provide the fundamental behavior of this
88 * control when output is zero, which is to provide 0V to the motor.
89 */
91 /**
92 * \brief Set to true to force forward limiting. This allows users to use other
93 * limit switch sensors connected to robot controller. This also allows use of
94 * active sensors that require external power.
95 */
96 bool LimitForwardMotion = false;
97 /**
98 * \brief Set to true to force reverse limiting. This allows users to use other
99 * limit switch sensors connected to robot controller. This also allows use of
100 * active sensors that require external power.
101 */
102 bool LimitReverseMotion = false;
103 /**
104 * \brief Set to true to ignore hardware limit switches and the
105 * LimitForwardMotion and LimitReverseMotion parameters, instead allowing
106 * motion.
107 *
108 * This can be useful on mechanisms such as an intake/feeder, where a limit
109 * switch stops motion while intaking but should be ignored when feeding to a
110 * shooter.
111 *
112 * The hardware limit faults and Forward/ReverseLimit signals will still report
113 * the values of the limit switches regardless of this parameter.
114 */
116 /**
117 * \brief Set to true to delay applying this control request until a timesync
118 * boundary (requires Phoenix Pro and CANivore). This eliminates the impact of
119 * nondeterministic network delays in exchange for a larger but deterministic
120 * control latency.
121 *
122 * This requires setting the ControlTimesyncFreqHz config in MotorOutputConfigs.
123 * Additionally, when this is enabled, the UpdateFreqHz of this request should
124 * be set to 0 Hz.
125 */
126 bool UseTimesync = false;
127
128 /**
129 * \brief The period at which this control will update at.
130 * This is designated in Hertz, with a minimum of 20 Hz
131 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
132 *
133 * If this field is set to 0 Hz, the control request will
134 * be sent immediately as a one-shot frame. This may be useful
135 * for advanced applications that require outputs to be
136 * synchronized with data acquisition. In this case, we
137 * recommend not exceeding 50 ms between control calls.
138 */
139 units::frequency::hertz_t UpdateFreqHz{100_Hz};
140
141 /**
142 * \brief Request a specified voltage with a differential position closed-loop.
143 *
144 * \details This control mode will attempt to apply the specified voltage to the
145 * motor. If the supply voltage is below the requested voltage, the
146 * motor controller will output the supply voltage. It will also set
147 * the motor's differential position setpoint to the specified
148 * position.
149 *
150 * \param TargetOutput Voltage to attempt to drive at
151 * \param DifferentialPosition Differential position to drive towards in
152 * rotations
153 */
154 DifferentialVoltage(units::voltage::volt_t TargetOutput, units::angle::turn_t DifferentialPosition) : ControlRequest{"DifferentialVoltage"},
157 {}
158
159 /**
160 * \brief Modifies this Control Request's TargetOutput parameter and returns itself for
161 * method-chaining and easier to use request API.
162 *
163 * Voltage to attempt to drive at
164 *
165 * - Units: Volts
166 *
167 *
168 * \param newTargetOutput Parameter to modify
169 * \returns Itself
170 */
171 DifferentialVoltage &WithTargetOutput(units::voltage::volt_t newTargetOutput)
172 {
173 TargetOutput = std::move(newTargetOutput);
174 return *this;
175 }
176
177 /**
178 * \brief Modifies this Control Request's DifferentialPosition parameter and returns itself for
179 * method-chaining and easier to use request API.
180 *
181 * Differential position to drive towards in rotations
182 *
183 * - Units: rotations
184 *
185 *
186 * \param newDifferentialPosition Parameter to modify
187 * \returns Itself
188 */
189 DifferentialVoltage &WithDifferentialPosition(units::angle::turn_t newDifferentialPosition)
190 {
191 DifferentialPosition = std::move(newDifferentialPosition);
192 return *this;
193 }
194
195 /**
196 * \brief Modifies this Control Request's EnableFOC parameter and returns itself for
197 * method-chaining and easier to use request API.
198 *
199 * Set to true to use FOC commutation (requires Phoenix Pro), which increases
200 * peak power by ~15% on supported devices (see hardware#traits#SupportsFOC).
201 * Set to false to use trapezoidal commutation.
202 *
203 * FOC improves motor performance by leveraging torque (current) control.
204 * However, this may be inconvenient for applications that require specifying
205 * duty cycle or voltage. CTR-Electronics has developed a hybrid method that
206 * combines the performances gains of FOC while still allowing applications to
207 * provide duty cycle or voltage demand. This not to be confused with simple
208 * sinusoidal control or phase voltage control which lacks the performance
209 * gains.
210 *
211 * \param newEnableFOC Parameter to modify
212 * \returns Itself
213 */
215 {
216 EnableFOC = std::move(newEnableFOC);
217 return *this;
218 }
219
220 /**
221 * \brief Modifies this Control Request's DifferentialSlot parameter and returns itself for
222 * method-chaining and easier to use request API.
223 *
224 * Select which gains are applied to the differential controller by selecting
225 * the slot. Use the configuration api to set the gain values for the selected
226 * slot before enabling this feature. Slot must be within [0,2].
227 *
228 * \param newDifferentialSlot Parameter to modify
229 * \returns Itself
230 */
232 {
233 DifferentialSlot = std::move(newDifferentialSlot);
234 return *this;
235 }
236
237 /**
238 * \brief Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for
239 * method-chaining and easier to use request API.
240 *
241 * Set to true to static-brake the rotor when output is zero (or within
242 * deadband). Set to false to use the NeutralMode configuration setting
243 * (default). This flag exists to provide the fundamental behavior of this
244 * control when output is zero, which is to provide 0V to the motor.
245 *
246 * \param newOverrideBrakeDurNeutral Parameter to modify
247 * \returns Itself
248 */
249 DifferentialVoltage &WithOverrideBrakeDurNeutral(bool newOverrideBrakeDurNeutral)
250 {
251 OverrideBrakeDurNeutral = std::move(newOverrideBrakeDurNeutral);
252 return *this;
253 }
254
255 /**
256 * \brief Modifies this Control Request's LimitForwardMotion parameter and returns itself for
257 * method-chaining and easier to use request API.
258 *
259 * Set to true to force forward limiting. This allows users to use other limit
260 * switch sensors connected to robot controller. This also allows use of active
261 * sensors that require external power.
262 *
263 * \param newLimitForwardMotion Parameter to modify
264 * \returns Itself
265 */
266 DifferentialVoltage &WithLimitForwardMotion(bool newLimitForwardMotion)
267 {
268 LimitForwardMotion = std::move(newLimitForwardMotion);
269 return *this;
270 }
271
272 /**
273 * \brief Modifies this Control Request's LimitReverseMotion parameter and returns itself for
274 * method-chaining and easier to use request API.
275 *
276 * Set to true to force reverse limiting. This allows users to use other limit
277 * switch sensors connected to robot controller. This also allows use of active
278 * sensors that require external power.
279 *
280 * \param newLimitReverseMotion Parameter to modify
281 * \returns Itself
282 */
283 DifferentialVoltage &WithLimitReverseMotion(bool newLimitReverseMotion)
284 {
285 LimitReverseMotion = std::move(newLimitReverseMotion);
286 return *this;
287 }
288
289 /**
290 * \brief Modifies this Control Request's IgnoreHardwareLimits parameter and returns itself for
291 * method-chaining and easier to use request API.
292 *
293 * Set to true to ignore hardware limit switches and the LimitForwardMotion and
294 * LimitReverseMotion parameters, instead allowing motion.
295 *
296 * This can be useful on mechanisms such as an intake/feeder, where a limit
297 * switch stops motion while intaking but should be ignored when feeding to a
298 * shooter.
299 *
300 * The hardware limit faults and Forward/ReverseLimit signals will still report
301 * the values of the limit switches regardless of this parameter.
302 *
303 * \param newIgnoreHardwareLimits Parameter to modify
304 * \returns Itself
305 */
306 DifferentialVoltage &WithIgnoreHardwareLimits(bool newIgnoreHardwareLimits)
307 {
308 IgnoreHardwareLimits = std::move(newIgnoreHardwareLimits);
309 return *this;
310 }
311
312 /**
313 * \brief Modifies this Control Request's UseTimesync parameter and returns itself for
314 * method-chaining and easier to use request API.
315 *
316 * Set to true to delay applying this control request until a timesync boundary
317 * (requires Phoenix Pro and CANivore). This eliminates the impact of
318 * nondeterministic network delays in exchange for a larger but deterministic
319 * control latency.
320 *
321 * This requires setting the ControlTimesyncFreqHz config in MotorOutputConfigs.
322 * Additionally, when this is enabled, the UpdateFreqHz of this request should
323 * be set to 0 Hz.
324 *
325 * \param newUseTimesync Parameter to modify
326 * \returns Itself
327 */
329 {
330 UseTimesync = std::move(newUseTimesync);
331 return *this;
332 }
333 /**
334 * \brief Sets the period at which this control will update at.
335 * This is designated in Hertz, with a minimum of 20 Hz
336 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
337 *
338 * If this field is set to 0 Hz, the control request will
339 * be sent immediately as a one-shot frame. This may be useful
340 * for advanced applications that require outputs to be
341 * synchronized with data acquisition. In this case, we
342 * recommend not exceeding 50 ms between control calls.
343 *
344 * \param newUpdateFreqHz Parameter to modify
345 * \returns Itself
346 */
347 DifferentialVoltage &WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
348 {
349 UpdateFreqHz = newUpdateFreqHz;
350 return *this;
351 }
352 /**
353 * \brief Returns a string representation of the object.
354 *
355 * \returns a string representation of the object.
356 */
357 std::string ToString() const override
358 {
359 std::stringstream ss;
360 ss << "Control: DifferentialVoltage" << std::endl;
361 ss << " TargetOutput: " << TargetOutput.to<double>() << " Volts" << std::endl;
362 ss << " DifferentialPosition: " << DifferentialPosition.to<double>() << " rotations" << std::endl;
363 ss << " EnableFOC: " << EnableFOC << std::endl;
364 ss << " DifferentialSlot: " << DifferentialSlot << std::endl;
365 ss << " OverrideBrakeDurNeutral: " << OverrideBrakeDurNeutral << std::endl;
366 ss << " LimitForwardMotion: " << LimitForwardMotion << std::endl;
367 ss << " LimitReverseMotion: " << LimitReverseMotion << std::endl;
368 ss << " IgnoreHardwareLimits: " << IgnoreHardwareLimits << std::endl;
369 ss << " UseTimesync: " << UseTimesync << std::endl;
370 return ss.str();
371 }
372
373 /**
374 * \brief Gets information about this control request.
375 *
376 * \returns Map of control parameter names and corresponding applied values
377 */
378 std::map<std::string, std::string> GetControlInfo() const override
379 {
380 std::map<std::string, std::string> controlInfo;
381 std::stringstream ss;
382 controlInfo["Name"] = GetName();
383 ss << TargetOutput.to<double>(); controlInfo["TargetOutput"] = ss.str(); ss.str(std::string{});
384 ss << DifferentialPosition.to<double>(); controlInfo["DifferentialPosition"] = ss.str(); ss.str(std::string{});
385 ss << EnableFOC; controlInfo["EnableFOC"] = ss.str(); ss.str(std::string{});
386 ss << DifferentialSlot; controlInfo["DifferentialSlot"] = ss.str(); ss.str(std::string{});
387 ss << OverrideBrakeDurNeutral; controlInfo["OverrideBrakeDurNeutral"] = ss.str(); ss.str(std::string{});
388 ss << LimitForwardMotion; controlInfo["LimitForwardMotion"] = ss.str(); ss.str(std::string{});
389 ss << LimitReverseMotion; controlInfo["LimitReverseMotion"] = ss.str(); ss.str(std::string{});
390 ss << IgnoreHardwareLimits; controlInfo["IgnoreHardwareLimits"] = 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_RequestControlDifferentialVoltage(const char *canbus, uint32_t ecuEncoding, double updateFrequency, double TargetOutput, double DifferentialPosition, bool EnableFOC, 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
Request a specified voltage with a differential position closed-loop.
Definition DifferentialVoltage.hpp:30
bool IgnoreHardwareLimits
Set to true to ignore hardware limit switches and the LimitForwardMotion and LimitReverseMotion param...
Definition DifferentialVoltage.hpp:115
DifferentialVoltage & WithIgnoreHardwareLimits(bool newIgnoreHardwareLimits)
Modifies this Control Request's IgnoreHardwareLimits parameter and returns itself for method-chaining...
Definition DifferentialVoltage.hpp:306
DifferentialVoltage & WithEnableFOC(bool newEnableFOC)
Modifies this Control Request's EnableFOC parameter and returns itself for method-chaining and easier...
Definition DifferentialVoltage.hpp:214
bool UseTimesync
Set to true to delay applying this control request until a timesync boundary (requires Phoenix Pro an...
Definition DifferentialVoltage.hpp:126
bool EnableFOC
Set to true to use FOC commutation (requires Phoenix Pro), which increases peak power by ~15% on supp...
Definition DifferentialVoltage.hpp:77
bool LimitForwardMotion
Set to true to force forward limiting.
Definition DifferentialVoltage.hpp:96
DifferentialVoltage & WithLimitForwardMotion(bool newLimitForwardMotion)
Modifies this Control Request's LimitForwardMotion parameter and returns itself for method-chaining a...
Definition DifferentialVoltage.hpp:266
units::angle::turn_t DifferentialPosition
Differential position to drive towards in rotations.
Definition DifferentialVoltage.hpp:63
DifferentialVoltage(units::voltage::volt_t TargetOutput, units::angle::turn_t DifferentialPosition)
Request a specified voltage with a differential position closed-loop.
Definition DifferentialVoltage.hpp:154
DifferentialVoltage & WithDifferentialPosition(units::angle::turn_t newDifferentialPosition)
Modifies this Control Request's DifferentialPosition parameter and returns itself for method-chaining...
Definition DifferentialVoltage.hpp:189
int DifferentialSlot
Select which gains are applied to the differential controller by selecting the slot.
Definition DifferentialVoltage.hpp:83
DifferentialVoltage & WithUseTimesync(bool newUseTimesync)
Modifies this Control Request's UseTimesync parameter and returns itself for method-chaining and easi...
Definition DifferentialVoltage.hpp:328
DifferentialVoltage & WithLimitReverseMotion(bool newLimitReverseMotion)
Modifies this Control Request's LimitReverseMotion parameter and returns itself for method-chaining a...
Definition DifferentialVoltage.hpp:283
DifferentialVoltage & WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
Sets the period at which this control will update at.
Definition DifferentialVoltage.hpp:347
units::frequency::hertz_t UpdateFreqHz
The period at which this control will update at.
Definition DifferentialVoltage.hpp:139
DifferentialVoltage & WithOverrideBrakeDurNeutral(bool newOverrideBrakeDurNeutral)
Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for method-chain...
Definition DifferentialVoltage.hpp:249
DifferentialVoltage & WithDifferentialSlot(int newDifferentialSlot)
Modifies this Control Request's DifferentialSlot parameter and returns itself for method-chaining and...
Definition DifferentialVoltage.hpp:231
bool LimitReverseMotion
Set to true to force reverse limiting.
Definition DifferentialVoltage.hpp:102
std::string ToString() const override
Returns a string representation of the object.
Definition DifferentialVoltage.hpp:357
std::map< std::string, std::string > GetControlInfo() const override
Gets information about this control request.
Definition DifferentialVoltage.hpp:378
units::voltage::volt_t TargetOutput
Voltage to attempt to drive at.
Definition DifferentialVoltage.hpp:56
DifferentialVoltage & WithTargetOutput(units::voltage::volt_t newTargetOutput)
Modifies this Control Request's TargetOutput parameter and returns itself for method-chaining and eas...
Definition DifferentialVoltage.hpp:171
bool OverrideBrakeDurNeutral
Set to true to static-brake the rotor when output is zero (or within deadband).
Definition DifferentialVoltage.hpp:90
Status codes reported by APIs, including OK, warnings, and errors.
Definition StatusCodes.h:27
Definition Diff_PositionDutyCycle_Position.hpp:15
Definition span.hpp:401