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