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