CTRE Phoenix 6 C++ 24.3.0
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, bool cancelOtherRequests, 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 /**
99 * \brief The period at which this control will update at.
100 * This is designated in Hertz, with a minimum of 20 Hz
101 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
102 *
103 * If this field is set to 0 Hz, the control request will
104 * be sent immediately as a one-shot frame. This may be useful
105 * for advanced applications that require outputs to be
106 * synchronized with data acquisition. In this case, we
107 * recommend not exceeding 50 ms between control calls.
108 */
109 units::frequency::hertz_t UpdateFreqHz{100_Hz}; // Default to 100_Hz
110
111 /**
112 * \brief Request a specified voltage with a differential position closed-loop.
113 *
114 * \details This control mode will attempt to apply the specified voltage to the
115 * motor. If the supply voltage is below the requested voltage, the
116 * motor controller will output the supply voltage. It will also set
117 * the motor's differential position setpoint to the specified
118 * position.
119 *
120 * \param TargetOutput Voltage to attempt to drive at
121 * \param DifferentialPosition Differential position to drive towards in
122 * rotations
123 * \param EnableFOC Set to true to use FOC commutation (requires Phoenix
124 * Pro), which increases peak power by ~15%. Set to false to
125 * use trapezoidal commutation.
126 *
127 * FOC improves motor performance by leveraging torque
128 * (current) control. However, this may be inconvenient for
129 * applications that require specifying duty cycle or
130 * voltage. CTR-Electronics has developed a hybrid method
131 * that combines the performances gains of FOC while still
132 * allowing applications to provide duty cycle or voltage
133 * demand. This not to be confused with simple sinusoidal
134 * control or phase voltage control which lacks the
135 * performance gains.
136 * \param DifferentialSlot Select which gains are applied to the differential
137 * controller by selecting the slot. Use the
138 * configuration api to set the gain values for the
139 * selected slot before enabling this feature. Slot
140 * must be within [0,2].
141 * \param OverrideBrakeDurNeutral Set to true to static-brake the rotor when
142 * output is zero (or within deadband). Set
143 * to false to use the NeutralMode
144 * configuration setting (default). This flag
145 * exists to provide the fundamental behavior
146 * of this control when output is zero, which
147 * is to provide 0V to the motor.
148 * \param LimitForwardMotion Set to true to force forward limiting. This
149 * allows users to use other limit switch sensors
150 * connected to robot controller. This also allows
151 * use of active sensors that require external
152 * power.
153 * \param LimitReverseMotion Set to true to force reverse limiting. This
154 * allows users to use other limit switch sensors
155 * connected to robot controller. This also allows
156 * use of active sensors that require external
157 * power.
158 */
159 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) : ControlRequest{"DifferentialVoltage"},
160 TargetOutput{std::move(TargetOutput)},
162 EnableFOC{std::move(EnableFOC)},
167 {}
168
169 /**
170 * \brief Modifies this Control Request's TargetOutput parameter and returns itself for
171 * method-chaining and easier to use request API.
172 *
173 * Voltage to attempt to drive at
174 *
175 * \param newTargetOutput Parameter to modify
176 * \returns Itself
177 */
178 DifferentialVoltage& WithTargetOutput(units::voltage::volt_t newTargetOutput)
179 {
180 TargetOutput = std::move(newTargetOutput);
181 return *this;
182 }
183
184 /**
185 * \brief Modifies this Control Request's DifferentialPosition parameter and returns itself for
186 * method-chaining and easier to use request API.
187 *
188 * Differential position to drive towards in rotations
189 *
190 * \param newDifferentialPosition Parameter to modify
191 * \returns Itself
192 */
193 DifferentialVoltage& WithDifferentialPosition(units::angle::turn_t newDifferentialPosition)
194 {
195 DifferentialPosition = std::move(newDifferentialPosition);
196 return *this;
197 }
198
199 /**
200 * \brief Modifies this Control Request's EnableFOC parameter and returns itself for
201 * method-chaining and easier to use request API.
202 *
203 * Set to true to use FOC commutation (requires Phoenix Pro), which increases
204 * peak power by ~15%. Set to false to use trapezoidal commutation.
205 *
206 * FOC improves motor performance by leveraging torque (current) control.
207 * However, this may be inconvenient for applications that require specifying
208 * duty cycle or voltage. CTR-Electronics has developed a hybrid method that
209 * combines the performances gains of FOC while still allowing applications to
210 * provide duty cycle or voltage demand. This not to be confused with simple
211 * sinusoidal control or phase voltage control which lacks the performance
212 * gains.
213 *
214 * \param newEnableFOC Parameter to modify
215 * \returns Itself
216 */
218 {
219 EnableFOC = std::move(newEnableFOC);
220 return *this;
221 }
222
223 /**
224 * \brief Modifies this Control Request's DifferentialSlot parameter and returns itself for
225 * method-chaining and easier to use request API.
226 *
227 * Select which gains are applied to the differential controller by selecting
228 * the slot. Use the configuration api to set the gain values for the selected
229 * slot before enabling this feature. Slot must be within [0,2].
230 *
231 * \param newDifferentialSlot Parameter to modify
232 * \returns Itself
233 */
235 {
236 DifferentialSlot = std::move(newDifferentialSlot);
237 return *this;
238 }
239
240 /**
241 * \brief Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for
242 * method-chaining and easier to use request API.
243 *
244 * Set to true to static-brake the rotor when output is zero (or within
245 * deadband). Set to false to use the NeutralMode configuration setting
246 * (default). This flag exists to provide the fundamental behavior of this
247 * control when output is zero, which is to provide 0V to the motor.
248 *
249 * \param newOverrideBrakeDurNeutral Parameter to modify
250 * \returns Itself
251 */
252 DifferentialVoltage& WithOverrideBrakeDurNeutral(bool newOverrideBrakeDurNeutral)
253 {
254 OverrideBrakeDurNeutral = std::move(newOverrideBrakeDurNeutral);
255 return *this;
256 }
257
258 /**
259 * \brief Modifies this Control Request's LimitForwardMotion parameter and returns itself for
260 * method-chaining and easier to use request API.
261 *
262 * Set to true to force forward limiting. This allows users to use other limit
263 * switch sensors connected to robot controller. This also allows use of active
264 * sensors that require external power.
265 *
266 * \param newLimitForwardMotion Parameter to modify
267 * \returns Itself
268 */
269 DifferentialVoltage& WithLimitForwardMotion(bool newLimitForwardMotion)
270 {
271 LimitForwardMotion = std::move(newLimitForwardMotion);
272 return *this;
273 }
274
275 /**
276 * \brief Modifies this Control Request's LimitReverseMotion parameter and returns itself for
277 * method-chaining and easier to use request API.
278 *
279 * Set to true to force reverse limiting. This allows users to use other limit
280 * switch sensors connected to robot controller. This also allows use of active
281 * sensors that require external power.
282 *
283 * \param newLimitReverseMotion Parameter to modify
284 * \returns Itself
285 */
286 DifferentialVoltage& WithLimitReverseMotion(bool newLimitReverseMotion)
287 {
288 LimitReverseMotion = std::move(newLimitReverseMotion);
289 return *this;
290 }
291 /**
292 * \brief Sets the period at which this control will update at.
293 * This is designated in Hertz, with a minimum of 20 Hz
294 * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
295 *
296 * If this field is set to 0 Hz, the control request will
297 * be sent immediately as a one-shot frame. This may be useful
298 * for advanced applications that require outputs to be
299 * synchronized with data acquisition. In this case, we
300 * recommend not exceeding 50 ms between control calls.
301 *
302 * \param newUpdateFreqHz Parameter to modify
303 * \returns Itself
304 */
305 DifferentialVoltage &WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
306 {
307 UpdateFreqHz = newUpdateFreqHz;
308 return *this;
309 }
310 /**
311 * Returns a string representation of the object.
312 *
313 * \returns a string representation of the object.
314 */
315 std::string ToString() const override
316 {
317 std::stringstream ss;
318 ss << "class: DifferentialVoltage" << std::endl;
319 ss << "TargetOutput: " << TargetOutput.to<double>() << std::endl;
320 ss << "DifferentialPosition: " << DifferentialPosition.to<double>() << std::endl;
321 ss << "EnableFOC: " << EnableFOC << std::endl;
322 ss << "DifferentialSlot: " << DifferentialSlot << std::endl;
323 ss << "OverrideBrakeDurNeutral: " << OverrideBrakeDurNeutral << std::endl;
324 ss << "LimitForwardMotion: " << LimitForwardMotion << std::endl;
325 ss << "LimitReverseMotion: " << LimitReverseMotion << std::endl;
326 return ss.str();
327 }
328
329 /**
330 * \brief Gets information about this control request.
331 *
332 * \returns Map of control parameter names and corresponding applied values
333 */
334 std::map<std::string, std::string> GetControlInfo() const override
335 {
336 std::map<std::string, std::string> controlInfo;
337 std::stringstream ss;
338 controlInfo["Name"] = GetName();
339 ss << TargetOutput.to<double>(); controlInfo["TargetOutput"] = ss.str(); ss.str(std::string{});
340 ss << DifferentialPosition.to<double>(); controlInfo["DifferentialPosition"] = ss.str(); ss.str(std::string{});
341 ss << EnableFOC; controlInfo["EnableFOC"] = ss.str(); ss.str(std::string{});
342 ss << DifferentialSlot; controlInfo["DifferentialSlot"] = ss.str(); ss.str(std::string{});
343 ss << OverrideBrakeDurNeutral; controlInfo["OverrideBrakeDurNeutral"] = ss.str(); ss.str(std::string{});
344 ss << LimitForwardMotion; controlInfo["LimitForwardMotion"] = ss.str(); ss.str(std::string{});
345 ss << LimitReverseMotion; controlInfo["LimitReverseMotion"] = ss.str(); ss.str(std::string{});
346 return controlInfo;
347 }
348};
349
350}
351}
352}
353
CTREXPORT int c_ctre_phoenix6_RequestControlDifferentialVoltage(const char *canbus, uint32_t ecuEncoding, double updateTime, bool cancelOtherRequests, double TargetOutput, double DifferentialPosition, bool EnableFOC, int DifferentialSlot, bool OverrideBrakeDurNeutral, bool LimitForwardMotion, bool LimitReverseMotion)
Abstract Control Request class that other control requests extend for use.
Definition: ControlRequest.hpp:28
std::string const & GetName() const
Definition: ControlRequest.hpp:51
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:217
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:269
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:193
int DifferentialSlot
Select which gains are applied to the differential controller by selecting the slot.
Definition: DifferentialVoltage.hpp:77
DifferentialVoltage & WithLimitReverseMotion(bool newLimitReverseMotion)
Modifies this Control Request's LimitReverseMotion parameter and returns itself for method-chaining a...
Definition: DifferentialVoltage.hpp:286
DifferentialVoltage & WithUpdateFreqHz(units::frequency::hertz_t newUpdateFreqHz)
Sets the period at which this control will update at.
Definition: DifferentialVoltage.hpp:305
units::frequency::hertz_t UpdateFreqHz
The period at which this control will update at.
Definition: DifferentialVoltage.hpp:109
DifferentialVoltage & WithOverrideBrakeDurNeutral(bool newOverrideBrakeDurNeutral)
Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for method-chain...
Definition: DifferentialVoltage.hpp:252
DifferentialVoltage & WithDifferentialSlot(int newDifferentialSlot)
Modifies this Control Request's DifferentialSlot parameter and returns itself for method-chaining and...
Definition: DifferentialVoltage.hpp:234
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:315
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)
Request a specified voltage with a differential position closed-loop.
Definition: DifferentialVoltage.hpp:159
std::map< std::string, std::string > GetControlInfo() const override
Gets information about this control request.
Definition: DifferentialVoltage.hpp:334
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:178
bool OverrideBrakeDurNeutral
Set to true to static-brake the rotor when output is zero (or within deadband).
Definition: DifferentialVoltage.hpp:84
Definition: string_util.hpp:15