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