WPILibC++ 2024.3.2
Joystick.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#pragma once
6
7#include <array>
8
9#include <units/angle.h>
10
11#include "frc/GenericHID.h"
12
13namespace frc {
14
15/**
16 * Handle input from standard Joysticks connected to the Driver Station.
17 *
18 * This class handles standard input that comes from the Driver Station. Each
19 * time a value is requested the most recent value is returned. There is a
20 * single class instance for each joystick and the mapping of ports to hardware
21 * buttons depends on the code in the Driver Station.
22 */
23class Joystick : public GenericHID {
24 public:
25 /// Default X axis channel.
26 static constexpr int kDefaultXChannel = 0;
27 /// Default Y axis channel.
28 static constexpr int kDefaultYChannel = 1;
29 /// Default Z axis channel.
30 static constexpr int kDefaultZChannel = 2;
31 /// Default twist axis channel.
32 static constexpr int kDefaultTwistChannel = 2;
33 /// Default throttle axis channel.
34 static constexpr int kDefaultThrottleChannel = 3;
35
36 /**
37 * Represents an analog axis on a joystick.
38 */
39 enum AxisType {
40 /// X axis.
42 /// Y axis.
44 /// Z axis.
46 /// Twist axis.
48 /// Throttle axis.
50 };
51
52 /**
53 * Represents a digital button on a joystick.
54 */
56 /// kTrigger.
58 /// kTop.
60 };
61
62 /**
63 * Construct an instance of a joystick.
64 *
65 * The joystick index is the USB port on the Driver Station.
66 *
67 * @param port The port on the Driver Station that the joystick is plugged
68 * into (0-5).
69 */
70 explicit Joystick(int port);
71
72 ~Joystick() override = default;
73
74 Joystick(Joystick&&) = default;
76
77 /**
78 * Set the channel associated with the X axis.
79 *
80 * @param channel The channel to set the axis to.
81 */
82 void SetXChannel(int channel);
83
84 /**
85 * Set the channel associated with the Y axis.
86 *
87 * @param channel The channel to set the axis to.
88 */
89 void SetYChannel(int channel);
90
91 /**
92 * Set the channel associated with the Z axis.
93 *
94 * @param channel The channel to set the axis to.
95 */
96 void SetZChannel(int channel);
97
98 /**
99 * Set the channel associated with the twist axis.
100 *
101 * @param channel The channel to set the axis to.
102 */
103 void SetTwistChannel(int channel);
104
105 /**
106 * Set the channel associated with the throttle axis.
107 *
108 * @param channel The channel to set the axis to.
109 */
110 void SetThrottleChannel(int channel);
111
112 /**
113 * Get the channel currently associated with the X axis.
114 *
115 * @return The channel for the axis.
116 */
117 int GetXChannel() const;
118
119 /**
120 * Get the channel currently associated with the Y axis.
121 *
122 * @return The channel for the axis.
123 */
124 int GetYChannel() const;
125
126 /**
127 * Get the channel currently associated with the Z axis.
128 *
129 * @return The channel for the axis.
130 */
131 int GetZChannel() const;
132
133 /**
134 * Get the channel currently associated with the twist axis.
135 *
136 * @return The channel for the axis.
137 */
138 int GetTwistChannel() const;
139
140 /**
141 * Get the channel currently associated with the throttle axis.
142 *
143 * @return The channel for the axis.
144 */
146
147 /**
148 * Get the X value of the current joystick.
149 *
150 * This depends on the mapping of the joystick connected to the current port.
151 */
152 double GetX() const;
153
154 /**
155 * Get the Y value of the current joystick.
156 *
157 * This depends on the mapping of the joystick connected to the current port.
158 */
159 double GetY() const;
160
161 /**
162 * Get the Z value of the current joystick.
163 *
164 * This depends on the mapping of the joystick connected to the current port.
165 */
166 double GetZ() const;
167
168 /**
169 * Get the twist value of the current joystick.
170 *
171 * This depends on the mapping of the joystick connected to the current port.
172 */
173 double GetTwist() const;
174
175 /**
176 * Get the throttle value of the current joystick.
177 *
178 * This depends on the mapping of the joystick connected to the current port.
179 */
180 double GetThrottle() const;
181
182 /**
183 * Read the state of the trigger on the joystick.
184 *
185 * Look up which button has been assigned to the trigger and read its state.
186 *
187 * @return The state of the trigger.
188 */
189 bool GetTrigger() const;
190
191 /**
192 * Whether the trigger was pressed since the last check.
193 *
194 * @return Whether the button was pressed since the last check.
195 */
197
198 /**
199 * Whether the trigger was released since the last check.
200 *
201 * @return Whether the button was released since the last check.
202 */
204
205 /**
206 * Constructs an event instance around the trigger button's digital signal.
207 *
208 * @param loop the event loop instance to attach the event to.
209 * @return an event instance representing the trigger button's digital signal
210 * attached to the given loop.
211 */
213
214 /**
215 * Read the state of the top button on the joystick.
216 *
217 * Look up which button has been assigned to the top and read its state.
218 *
219 * @return The state of the top button.
220 */
221 bool GetTop() const;
222
223 /**
224 * Whether the top button was pressed since the last check.
225 *
226 * @return Whether the button was pressed since the last check.
227 */
229
230 /**
231 * Whether the top button was released since the last check.
232 *
233 * @return Whether the button was released since the last check.
234 */
236
237 /**
238 * Constructs an event instance around the top button's digital signal.
239 *
240 * @param loop the event loop instance to attach the event to.
241 * @return an event instance representing the top button's digital signal
242 * attached to the given loop.
243 */
245
246 /**
247 * Get the magnitude of the direction vector formed by the joystick's
248 * current position relative to its origin.
249 *
250 * @return The magnitude of the direction vector
251 */
252 double GetMagnitude() const;
253
254 /**
255 * Get the direction of the vector formed by the joystick and its origin
256 * in radians.
257 *
258 * @return The direction of the vector in radians
259 * @deprecated Use GetDirection() instead.
260 */
261 [[deprecated("Use GetDirection() instead.")]]
262 double GetDirectionRadians() const;
263
264 /**
265 * Get the direction of the vector formed by the joystick and its origin
266 * in degrees.
267 *
268 * @return The direction of the vector in degrees
269 * @deprecated Use GetDirection() instead.
270 */
271 [[deprecated("Use GetDirection() instead.")]]
272 double GetDirectionDegrees() const;
273
274 /**
275 * Get the direction of the vector formed by the joystick and its origin.
276 *
277 * @return The direction of the vector.
278 */
279 units::radian_t GetDirection() const;
280
281 private:
282 enum Axis { kX, kY, kZ, kTwist, kThrottle, kNumAxes };
283 enum Button { kTrigger = 1, kTop = 2 };
284
285 std::array<int, Axis::kNumAxes> m_axes;
286};
287
288} // namespace frc
This class provides an easy way to link actions to inputs.
Definition: BooleanEvent.h:31
A declarative way to bind a set of actions to a loop and execute them when the loop is polled.
Definition: EventLoop.h:15
Handle input from standard HID devices connected to the Driver Station.
Definition: GenericHID.h:24
Handle input from standard Joysticks connected to the Driver Station.
Definition: Joystick.h:23
int GetYChannel() const
Get the channel currently associated with the Y axis.
double GetDirectionDegrees() const
Get the direction of the vector formed by the joystick and its origin in degrees.
void SetTwistChannel(int channel)
Set the channel associated with the twist axis.
bool GetTrigger() const
Read the state of the trigger on the joystick.
double GetTwist() const
Get the twist value of the current joystick.
int GetTwistChannel() const
Get the channel currently associated with the twist axis.
ButtonType
Represents a digital button on a joystick.
Definition: Joystick.h:55
@ kTopButton
kTop.
Definition: Joystick.h:59
@ kTriggerButton
kTrigger.
Definition: Joystick.h:57
bool GetTriggerReleased()
Whether the trigger was released since the last check.
static constexpr int kDefaultThrottleChannel
Default throttle axis channel.
Definition: Joystick.h:34
bool GetTopPressed()
Whether the top button was pressed since the last check.
void SetThrottleChannel(int channel)
Set the channel associated with the throttle axis.
bool GetTriggerPressed()
Whether the trigger was pressed since the last check.
BooleanEvent Top(EventLoop *loop) const
Constructs an event instance around the top button's digital signal.
~Joystick() override=default
int GetZChannel() const
Get the channel currently associated with the Z axis.
static constexpr int kDefaultXChannel
Default X axis channel.
Definition: Joystick.h:26
double GetX() const
Get the X value of the current joystick.
Joystick(int port)
Construct an instance of a joystick.
int GetXChannel() const
Get the channel currently associated with the X axis.
double GetThrottle() const
Get the throttle value of the current joystick.
double GetZ() const
Get the Z value of the current joystick.
bool GetTop() const
Read the state of the top button on the joystick.
bool GetTopReleased()
Whether the top button was released since the last check.
static constexpr int kDefaultTwistChannel
Default twist axis channel.
Definition: Joystick.h:32
static constexpr int kDefaultYChannel
Default Y axis channel.
Definition: Joystick.h:28
Joystick & operator=(Joystick &&)=default
void SetYChannel(int channel)
Set the channel associated with the Y axis.
double GetDirectionRadians() const
Get the direction of the vector formed by the joystick and its origin in radians.
double GetY() const
Get the Y value of the current joystick.
Joystick(Joystick &&)=default
int GetThrottleChannel() const
Get the channel currently associated with the throttle axis.
BooleanEvent Trigger(EventLoop *loop) const
Constructs an event instance around the trigger button's digital signal.
void SetZChannel(int channel)
Set the channel associated with the Z axis.
AxisType
Represents an analog axis on a joystick.
Definition: Joystick.h:39
@ kThrottleAxis
Throttle axis.
Definition: Joystick.h:49
@ kTwistAxis
Twist axis.
Definition: Joystick.h:47
@ kXAxis
X axis.
Definition: Joystick.h:41
@ kYAxis
Y axis.
Definition: Joystick.h:43
@ kZAxis
Z axis.
Definition: Joystick.h:45
static constexpr int kDefaultZChannel
Default Z axis channel.
Definition: Joystick.h:30
double GetMagnitude() const
Get the magnitude of the direction vector formed by the joystick's current position relative to its o...
units::radian_t GetDirection() const
Get the direction of the vector formed by the joystick and its origin.
void SetXChannel(int channel)
Set the channel associated with the X axis.
Definition: AprilTagPoseEstimator.h:15