Skip to content

Commit 5c06fb9

Browse files
lewisfmlewisfm
committed
docs: finish documenting devices 
1 parent 9c4ff1b commit 5c06fb9

File tree

12 files changed

+240
-123
lines changed

12 files changed

+240
-123
lines changed

‎.idea/kotlinc.xml‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎.idea/misc.xml‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/main/java/dev/vexide/hydrozoa/devices/Controller.java‎

Lines changed: 151 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -12,177 +12,226 @@
1212

1313
import java.util.Optional;
1414

15+
/**
16+
* A video-game-style VEX V5 controller, with two joysticks and a variety of buttons.
17+
* <p>
18+
* This class allows you to read from the buttons and joysticks on the controller and write to the controller’s display.
19+
* Controller instances are accessible through the {@link Peripherals} class.
20+
*/
1521
public class Controller {
1622
private final @NotNull Id id;
1723
private @NotNull State previousState = State.empty();
1824

25+
/**
26+
* Creates a new controller instance.
27+
*
28+
* @param ignoredKey the peripherals key, which may only be accessed from within the {@link Peripherals} class
29+
* @param type the type of controller to create
30+
* @see Peripherals#takeController(Controller.Id)
31+
*/
1932
@ApiStatus.Internal
2033
public Controller(@NotNull Peripherals.Key ignoredKey, @NotNull Id type) {
2134
this.id = type;
2235
}
2336

37+
/**
38+
* Gets the ID of this controller - whether it is the primary or partner controller.
39+
*
40+
* @return the controller ID
41+
*/
2442
public @NotNull Controller.Id getId() {
2543
return id;
2644
}
2745

46+
/**
47+
* Checks if this controller is connected to the robot brain.
48+
*
49+
* @return {@code true} if the controller is connected, {@code false} otherwise
50+
*/
2851
public boolean connected() {
2952
var status = VexSdk.Controller.vexControllerConnectionStatusGet(id.raw());
3053
return !status.equals(V5_ControllerStatus.kV5ControllerOffline);
3154
}
3255

56+
/**
57+
* Gets the latest data from the controller.
58+
*
59+
* @return the controller state, if the controller is connected and the robot is in driver control mode
60+
*/
3361
public @NotNull Optional<State> getState() {
3462
if (!CompetitionRuntime.mode().equals(CompetitionRuntime.Mode.Driver) || !connected()) {
3563
return Optional.empty();
3664
}
37-
var state = new State(
38-
new JoystickState(
39-
(byte) VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.AnaLeftX),
40-
(byte) VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.AnaLeftY)
41-
),
42-
new JoystickState(
43-
(byte) VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.AnaRightX),
44-
(byte) VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.AnaRightY)
45-
),
46-
new ButtonState(
47-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonA) == 1,
48-
previousState.a().pressed()
49-
),
50-
new ButtonState(
51-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonB) == 1,
52-
previousState.b().pressed()
53-
),
54-
new ButtonState(
55-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonX) == 1,
56-
previousState.x().pressed()
57-
),
58-
new ButtonState(
59-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonY) == 1,
60-
previousState.y().pressed()
61-
),
62-
new ButtonState(
63-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonUp) == 1,
64-
previousState.up().pressed()
65-
),
66-
new ButtonState(
67-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonDown) == 1,
68-
previousState.down().pressed()
69-
),
70-
new ButtonState(
71-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonLeft) == 1,
72-
previousState.left().pressed()
73-
),
74-
new ButtonState(
75-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonRight) == 1,
76-
previousState.right().pressed()
77-
),
78-
new ButtonState(
79-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonL1) == 1,
80-
previousState.l1().pressed()
81-
),
82-
new ButtonState(
83-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonL2) == 1,
84-
previousState.l2().pressed()
85-
),
86-
new ButtonState(
87-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonR1) == 1,
88-
previousState.r1().pressed()
89-
),
90-
new ButtonState(
91-
VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonR2) == 1,
92-
previousState.r2().pressed()
93-
)
94-
);
65+
var state = new State(new JoystickState((byte) VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.AnaLeftX), (byte) VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.AnaLeftY)), new JoystickState((byte) VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.AnaRightX), (byte) VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.AnaRightY)), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonA) == 1, previousState.a().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonB) == 1, previousState.b().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonX) == 1, previousState.x().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonY) == 1, previousState.y().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonUp) == 1, previousState.up().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonDown) == 1, previousState.down().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonLeft) == 1, previousState.left().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonRight) == 1, previousState.right().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonL1) == 1, previousState.l1().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonL2) == 1, previousState.l2().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonR1) == 1, previousState.r1().pressed()), new ButtonState(VexSdk.Controller.vexControllerGet(id.raw(), V5_ControllerIndex.ButtonR2) == 1, previousState.r2().pressed()));
9566
previousState = state;
9667
return Optional.of(state);
9768
}
9869

70+
/**
71+
* A unique identifier for one of the two V5 controllers that may be connected to the robot brain.
72+
*/
9973
public enum Id {
74+
/**
75+
* The primary controller, also known as the "master" controller. This controller is directly connected to the
76+
* robot brain via a radio or wired connection.
77+
*/
10078
Primary,
79+
/**
80+
* The partner controller. This controller is connected to the primary controller via a wired connection.
81+
*/
10182
Partner;
10283

103-
@NotNull
104-
V5_ControllerId raw() {
84+
/**
85+
* Gets the internal representation of this controller ID.
86+
*
87+
* @return the raw controller ID value
88+
*/
89+
@NotNull V5_ControllerId raw() {
10590
return switch (this) {
10691
case Primary -> V5_ControllerId.kControllerMaster;
10792
case Partner -> V5_ControllerId.kControllerPartner;
10893
};
10994
}
11095
}
11196

112-
public record State(
113-
@NotNull JoystickState leftStick,
114-
@NotNull JoystickState rightStick,
115-
@NotNull ButtonState a,
116-
@NotNull ButtonState b,
117-
@NotNull ButtonState x,
118-
@NotNull ButtonState y,
119-
@NotNull ButtonState up,
120-
@NotNull ButtonState down,
121-
@NotNull ButtonState left,
122-
@NotNull ButtonState right,
123-
@NotNull ButtonState l1,
124-
@NotNull ButtonState l2,
125-
@NotNull ButtonState r1,
126-
@NotNull ButtonState r2
127-
) {
97+
/**
98+
* The current state of the controller, including the positions of the joysticks and the states of the buttons.
99+
*
100+
* @param leftStick the state of the left joystick
101+
* @param rightStick the state of the right joystick
102+
* @param a the state of the A button
103+
* @param b the state of the B button
104+
* @param x the state of the X button
105+
* @param y the state of the Y button
106+
* @param up the state of the up button
107+
* @param down the state of the down button
108+
* @param left the state of the left button
109+
* @param right the state of the right button
110+
* @param l1 the state of the L1 button
111+
* @param l2 the state of the L2 button
112+
* @param r1 the state of the R1 button
113+
* @param r2 the state of the R2 button
114+
*/
115+
public record State(@NotNull JoystickState leftStick, @NotNull JoystickState rightStick, @NotNull ButtonState a,
116+
@NotNull ButtonState b, @NotNull ButtonState x, @NotNull ButtonState y, @NotNull ButtonState up,
117+
@NotNull ButtonState down, @NotNull ButtonState left, @NotNull ButtonState right,
118+
@NotNull ButtonState l1, @NotNull ButtonState l2, @NotNull ButtonState r1,
119+
@NotNull ButtonState r2) {
120+
/**
121+
* Gets an empty controller state, with all buttons and joysticks in their default positions.
122+
* <p>
123+
* This state is useful as a fallback when the controller is not connected or the robot is not in driver control
124+
* mode:
125+
* <pre>{@code
126+
* Controller controller = peripherals.takeController(Controller.Id.Primary);
127+
* var state = controller.getState().orElseGet(Controller.State::empty);
128+
* }</pre>
129+
*
130+
* @return an empty controller state
131+
*/
128132
@Contract(value = "-> new", pure = true)
129133
public static @NotNull State empty() {
130-
return new State(
131-
JoystickState.empty(),
132-
JoystickState.empty(),
133-
ButtonState.empty(),
134-
ButtonState.empty(),
135-
ButtonState.empty(),
136-
ButtonState.empty(),
137-
ButtonState.empty(),
138-
ButtonState.empty(),
139-
ButtonState.empty(),
140-
ButtonState.empty(),
141-
ButtonState.empty(),
142-
ButtonState.empty(),
143-
ButtonState.empty(),
144-
ButtonState.empty()
145-
);
134+
return new State(JoystickState.empty(), JoystickState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty(), ButtonState.empty());
146135
}
147136
}
148137

149-
public record JoystickState(
150-
byte rawX,
151-
byte rawY
152-
) {
138+
/**
139+
* The current state of a joystick, including the raw X and Y values and their normalized values.
140+
*
141+
* @param rawX the raw X value of the joystick, ranging from -127 to 127
142+
* @param rawY the raw Y value of the joystick, ranging from -127 to 127
143+
*/
144+
public record JoystickState(byte rawX, byte rawY) {
145+
/**
146+
* Gets an empty joystick state, with both the X and Y values set to 0.
147+
*
148+
* @return an empty joystick state
149+
* @see State#empty()
150+
*/
153151
@Contract(value = "-> new", pure = true)
154152
public static @NotNull JoystickState empty() {
155153
return new JoystickState((byte) 0, (byte) 0);
156154
}
157155

156+
/**
157+
* Gets the normalized X value of the joystick, ranging from -1.0 to 1.0.
158+
*
159+
* @return the normalized X value
160+
*/
158161
public double getX() {
159162
return rawX / 127.0;
160163
}
161164

165+
/**
166+
* Gets the normalized Y value of the joystick, ranging from -1.0 to 1.0.
167+
*
168+
* @return the normalized Y value
169+
*/
162170
public double getY() {
163171
return rawY / 127.0;
164172
}
165173
}
166174

167-
public record ButtonState(
168-
boolean pressed,
169-
boolean previousPressed
170-
) {
175+
/**
176+
* The current state of a button, including whether it is currently pressed and whether it was pressed when the
177+
* previous controller state was read.
178+
*
179+
* @param pressed whether the button is currently pressed
180+
* @param previouslyPressed whether the button was pressed when the controller was last read from
181+
*/
182+
public record ButtonState(boolean pressed, boolean previouslyPressed) {
183+
/**
184+
* Gets an empty button state, with the button both currently not pressed and previously not pressed.
185+
*
186+
* @return an empty button state
187+
* @see State#empty()
188+
*/
171189
@Contract(value = "-> new", pure = true)
172190
public static @NotNull ButtonState empty() {
173191
return new ButtonState(false, false);
174192
}
175193

194+
/**
195+
* Checks if the button is currently released (not pressed).
196+
*
197+
* @return {@code true} if the button is released, {@code false} if it is pressed
198+
*/
176199
public boolean released() {
177200
return !pressed;
178201
}
179202

203+
/**
204+
* Checks if the button used to be released, but is now pressed. This is useful for triggering actions when a
205+
* button is pressed, but not continuously running those actions while the button is held down.
206+
* <p>
207+
* For example, you might use this method to toggle a boolean value each time a button is pressed:
208+
* <pre>{@code
209+
* var state = controller.getState().orElseGet(Controller.State::empty);
210+
* boolean toggle = false;
211+
* if (state.a().isNowPressed()) {
212+
* toggle = !toggle;
213+
* System.out.println("Toggled: " + toggle);
214+
* }
215+
* }</pre>
216+
*
217+
* @return {@code true} if the button was released and is now pressed, {@code false} otherwise
218+
* @see #pressed()
219+
* @see #isNowReleased()
220+
*/
180221
public boolean isNowPressed() {
181-
return pressed && !previousPressed;
222+
return pressed && !previouslyPressed;
182223
}
183224

225+
/**
226+
* Checks if the button used to be pressed, but is now released. This is useful for triggering actions when a
227+
* button is released, but not continuously running those actions until the button is pressed again.
228+
*
229+
* @return {@code true} if the button was pressed and is now released, {@code false} otherwise
230+
* @see #released()
231+
* @see #isNowPressed()
232+
*/
184233
public boolean isNowReleased() {
185-
return !pressed && previousPressed;
234+
return !pressed && previouslyPressed;
186235
}
187236
}
188237
}

‎src/main/java/dev/vexide/hydrozoa/devices/DeviceDisconnectedException.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
*/
99
public class DeviceDisconnectedException extends DeviceException {
1010
/**
11-
* Create a new {@code DeviceDisconnectedException}.
11+
* Creates a new {@code DeviceDisconnectedException}.
1212
*
1313
* @param port the port number
1414
* @param type the expected device type

‎src/main/java/dev/vexide/hydrozoa/devices/IncorrectDeviceException.java‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,20 @@
33
import dev.vexide.hydrozoa.DeviceException;
44
import dev.vexide.hydrozoa.devices.smart.SmartDevice;
55

6+
/**
7+
* An exception thrown when an unexpected type of device is connected to a port.
8+
* <p>
9+
* This is in contrast to {@link DeviceDisconnectedException}, which is thrown when no device at all is connected to a
10+
* port.
11+
*/
612
public class IncorrectDeviceException extends DeviceException {
13+
/**
14+
* Creates a new {@code IncorrectDeviceException}.
15+
*
16+
* @param port the port number of the device
17+
* @param expected the device type that was expected
18+
* @param actual the device type that was found instead
19+
*/
720
public IncorrectDeviceException(int port, SmartDevice.Type expected, SmartDevice.Type actual) {
821
super(String.format("Expected a %s to be connected to port %d, but a %s was found", expected, port, actual));
922
}

‎src/main/java/dev/vexide/hydrozoa/devices/package-info.java‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
/// Functionality for accessing hardware connected to the V5 brain.
2-
///
3-
/// ## Overview
4-
///
5-
/// The V5 brain features 21 RJ9 4p4c connector ports (known as “Smart ports”) for communicating with newer V5
6-
/// peripherals, as well as six 3-wire ports with log-to-digital conversion capability for compatibility with legacy
7-
/// Cortex devices. This package provides access to both smart devices and ADI devices.
8-
///
9-
/// @since 0.1.0
1+
/**
2+
* Functionality for accessing hardware connected to the V5 brain.
3+
*
4+
* <h2>Overview</h2>
5+
* <p>
6+
* The V5 brain features 21 RJ9 4p4c connector ports (known as “Smart ports”) for communicating with newer V5
7+
* peripherals, as well as six 3-wire ports with log-to-digital conversion capability for compatibility with legacy
8+
* Cortex devices. This package provides access to both smart devices and ADI devices.
9+
*
10+
* @since 0.1.0
11+
*/
1012
package dev.vexide.hydrozoa.devices;

0 commit comments

Comments
 (0)