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