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