Controller#

Introduction #

The V5 Brain can connect to a V5 Controller. A V5 Controller has two analog joysticks and multiple buttons that the Brain can use to detect movements and presses.

For the examples below, the configured controller will be named controller_1 and will be used in all subsequent examples throughout this API documentation when referring to Controller class methods.

Below is a list of all available methods:

Actions – Turn Controller-programmed actions on or off.

rumble – Sends a rumble string to the V5 Controller.
print – Prints text on the Controller’s screen.
set_cursor – Sets the cursor position used for printing text on the Controller’s screen.
column – Returns the current column where text will be printed as an integer.
row – Returns the current row where text will be printed as an integer.
clear_screen – Clears the whole screen.
clear_row – Clears a screen row.
next_row – Moves the cursor to the beginning of the next row.
remote_control_code_enabled – Enable or disable Controller configured actions.

Getters – Read button states and joystick positions.

.pressing – Returns whether the specified button is being pressed.
.position – Returns the position of the joystick’s specified axis.

Callback – Run code when buttons or joysticks change state.

.pressed – Calls a function when the specified button is pressed.
.released – Calls a function when the specified button is released.
.changed – Calls a function when the joystick’s axis changes.

Constructors – Manually initialize and configure the controller.

Controller – Create a controller.

Actions #

rumble #

rumble sends a rumble string to the V5 Controller.

Usage:

controller.rumble(pattern)

Parameter	Description
`pattern`	A pattern using `.` and `-` for short and long rumbles.

# Rumble the V5 Controller to the pattern short-short-long-long.
controller.rumble('..--')

print #

controller.screen.print prints text on the Controller’s screen using the current cursor position.

Usage:

controller.screen.print(text, sep, precision)

Parameter	Description
`text`	The text to be printed on the controller screen.
`sep`	Optional. A string to inset between values. This must be written as a keyword argument (sep=). The default is `” “`.
`precision`	Optional. The number of decimal places to display when printing simple numbers. This must be written as a keyword argument (`precision=`). The default is 2.

# Print the number 1 on the screen.
controller.screen.print(1)

# Print the numbers 1, 2, 3 and 4 on the screen.
controller.screen.print(1, 2, 3, 4, sep='-')

# Print motor1's velocity on the screen using a format string.
controller.screen.print("motor1 : % 7.2f" %(motor1.velocity()))

set_cursor #

set_cursor sets the cursor to a specific row and column on the controller’s screen. The controller screen has 3 rows and 19 columns.

A screenshot of the V5 Controller screen, showing the rows and columns in the printable area. Row 1 Column 1 starts at the upper left corner and row 3, column 19 are in the lower right corner.

Usage:

controller.screen.set_cursor(row, col)

Parameter	Description
`row`	The row of the cursor from 1 to 3.
`col`	The column of the cursor from 1 to 19.

column #

column returns the current column where text will be printed as an integer.

Usage:

controller.screen.column()

Parameters	Description
	This method has no parameters.

# Print the column number on row 2, column 3.
controller.screen.set_cursor(2, 3)
controller.screen.print(controller.screen.column())

row #

row returns the current row where text will be printed as an integer.

Usage:

controller.screen.row()

Parameters	Description
	This method has no parameters.

# Print the column number on row 2, column 3.
controller.screen.set_cursor(2, 3)
controller.screen.print(controller.screen.row())

clear_screen #

clear_screen clears the whole screen.

Usage:

controller.screen.clear_screen()

Parameters	Description
	This method has no parameters.

# Print text and then clear the screen.
controller.screen.print("VEX V5")
wait(2, SECONDS)
controller.screen.clear_screen()

clear_row #

clear_row clears a screen row.

Usage:

controller.screen.clear_row(row)

Parameters	Description
`row`	Optional. The row to clear from 1 to 3. The default is the current cursor row.

# Clear row 2.
controller.screen.clear_row(2)

next_row #

next_row moves the cursor to the beginning of the next row.

Usage:

controller.screen.next_row()

Parameters	Description
	This method has no parameters.

# Print text and then clear row 2.
controller.screen.print("VEX V5")
controller.screen.next_row()
controller.screen.print("Controller")

remote_control_code_enabled #

remote_control_code_enabled is a variable that can be set to a boolean that enables or disables Controller configured actions from the Devices menu. The Controller is enabled by default. It can be set to either of the following:

True — Enable Controller configured actions.
False — Disable Controller configured actions.

Usage: remote_control_code_enabled = False

# Drive forward or backward using the left joystick
remote_control_code_enabled = False

while True:
    if controller_1.axis3.position() > 0:
        drivetrain.drive(FORWARD)
    elif controller_1.axis3.position() < 0:
        drivetrain.drive(REVERSE)
    # Press A to use the controller configured actions
    elif controller_1.buttonA.pressing():
        break
    else:
        drivetrain.stop()
    wait(20, MSEC)

remote_control_code_enabled = True

Getters #

.pressing #

.pressing returns an integer indicating whether a specific button on the controller is currently being pressed. This method must be called on a specific button object, such as buttonEDown (see full list of button objects below).

1 - The specified button is being pressed.
0 - The specified button is not being pressed.

Usage:
One of twelve available button objects can be used with this method, as shown below:

The front and back side of the V5 Controller with the buttons highlighted in yellow. On the surface of the controller are up, down, left, and right arrow buttons on the left, and X, A, B, Y buttons clockwise from 12 oclock on the right. On the back side of the controller are L1, L2, R1, and R2 on the left and right sides respectively.

Button	Command
`buttonA`	`controller_1.buttonA.pressing()` — The A button
`buttonB`	`controller_1.buttonB.pressing()` — The B button
`buttonX`	`controller_1.buttonX.pressing()` — The X button
`buttonY`	`controller_1.buttonY.pressing()` — The Y button
`buttonDown`	`controller_1.buttonDown.pressing()` — The Down button
`buttonUp`	`controller_1.buttonUp.pressing()` — The Up button
`buttonLeft`	`controller_1.buttonLeft.pressing()` — The Left button
`buttonRight`	`controller_1.buttonRight.pressing()` — The Right button
`buttonL1`	`controller_1.buttonL1.pressing()` — The L1 button
`buttonL2`	`controller_1.buttonL2.pressing()` — The L2 button
`buttonR1`	`controller_1.buttonR1.pressing()` — The R1 button
`buttonR2`	`controller_1.buttonR2.pressing()` — The R2 button

Parameters	Description
	This method has no parameters.

# Turn right while L1 is pressed
while True:
    if controller_1.buttonL1.pressing():
        drivetrain.turn(RIGHT)
    else:
        drivetrain.stop()

.position #

.position returns the position of the joystick’s specified axis as an integer from –100 to 100, representing a percentage. This method must be called on a specific axis object, such as axis1 (see full list of axis objects below).

Usage:

One of four available axes can be used with this method, as shown below:

A VEX V5 Controller with the axes around the joysticks labeled. Axis 1 and 2 are around the right joystick, and Axis 3 and 4 are around the left.

Axis	Command
`axis1`	`controller_1.axis1.position()` — The Right Joystick’s vertical axis
`axis2`	`controller_1.axis2.position()` — The Right Joystick’s horizontal axis
`axis3`	`controller_1.axis3.position()` — The Left Joystick’s horizontal axis
`axis4`	`controller_1.axis4.position()` — The Left Joystick’s vertical axis

Parameters	Description
	This method has no parameters.

# Turn with the left joystick
remote_control_code_enabled = False

while True:
    if controller_1.axis4.position() > 10:
        drivetrain.turn(RIGHT)
    elif controller_1.axis4.position() < -10:
        drivetrain.turn(LEFT)
    else:
        drivetrain.stop()
    wait(20, MSEC)

Callback #

.pressed #

.pressed registers a function to be called when a specific button on the controller is pressed. This method must be called on a specific button object, such as buttonEDown – (see full list of button objects below).

Usage:
One of the available button objects can be used with this method, as shown below:

Button	Command
`buttonA`	`controller_1.buttonA.pressed(callback, arg)` — The A button
`buttonB`	`controller_1.buttonB.pressed(callback, arg)` — The B button
`buttonX`	`controller_1.buttonX.pressed(callback, arg)` — The X button
`buttonY`	`controller_1.buttonY.pressed(callback, arg)` — The Y button
`buttonDown`	`controller_1.buttonDown.pressed(callback, arg)` — The Down button
`buttonUp`	`controller_1.buttonUp.pressed(callback, arg)` — The Up button
`buttonLeft`	`controller_1.buttonLeft.pressed(callback, arg)` — The Left button
`buttonRight`	`controller_1.buttonRight.pressed(callback, arg)` — The Right button
`buttonL1`	`controller_1.buttonL1.pressed(callback, arg)` — The L1 button
`buttonL2`	`controller_1.buttonL2.pressed(callback, arg)` — The L2 button
`buttonR1`	`controller_1.buttonR1.pressed(callback, arg)` — The R1 button
`buttonR2`	`controller_1.buttonR2.pressed(callback, arg)` — The R2 button

Parameters	Description
callback	A function that is previously defined to execute when the specified button is being pressed.
arg	Optional. A tuple containing arguments to pass to the callback function. Functions with Parameters for more information.

# Drive forward when A is pressed
def drive_forward():
    drivetrain.drive_for(FORWARD, 100, MM)

controller_1.buttonA.pressed(drive_forward)

.released #

.released registers a function to be called when a specific button on the controller is released. This method must be called on a specific button object, such as buttonL1 – (see full list of button objects below).

Usage:
One of the available button objects can be used with this method, as shown below:

Button	Command
`buttonA`	`controller_1.buttonA.released(callback, arg)` — The A button
`buttonB`	`controller_1.buttonB.released(callback, arg)` — The B button
`buttonX`	`controller_1.buttonX.released(callback, arg)` — The X button
`buttonY`	`controller_1.buttonY.released(callback, arg)` — The Y button
`buttonDown`	`controller_1.buttonDown.released(callback, arg)` — The Down button
`buttonUp`	`controller_1.buttonUp.released(callback, arg)` — The Up button
`buttonLeft`	`controller_1.buttonLeft.released(callback, arg)` — The Left button
`buttonRight`	`controller_1.buttonRight.released(callback, arg)` — The Right button
`buttonL1`	`controller_1.buttonL1.released(callback, arg)` — The L1 button
`buttonL2`	`controller_1.buttonL2.released(callback, arg)` — The L2 button
`buttonR1`	`controller_1.buttonR1.released(callback, arg)` — The R1 button
`buttonR2`	`controller_1.buttonR2.released(callback, arg)` — The R2 button

Parameters	Description
callback	A function that is previously defined to execute when the specified button is released.
arg	Optional. A tuple containing arguments to pass to the callback function. Functions with Parameters for more information.

# Drive backward when A is released
def back_up():
    drivetrain.drive_for(REVERSE, 100, MM)

controller_1.buttonA.released(back_up)

.changed #

.changed registers a function to be called when the joystick’s position changes. This method must be called on a specific axis object, such as axis1 (see full list of axis objects below).

Usage:
One of four available axes can be used with this method, as shown below:

A VEX V5 Controller with the axes around the joysticks labeled. Axis 1 and 2 are around the right joystick, and Axis 3 and 4 are around the left.

Axis	Command
`axis1`	`controller_1.axis1.changed(callback, arg)` — The Right Joystick’s vertical axis
`axis2`	`controller_1.axis2.changed(callback, arg)` — The Right Joystick’s horizontal axis
`axis3`	`controller_1.axis3.changed(callback, arg)` — The Left Joystick’s horizontal axis
`axis4`	`controller_1.axis4.changed(callback, arg)` — The Left Joystick’s vertical axis

Parameters	Description
callback	A function that is previously defined to execute when the axis’ value changes.
arg	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

# Play a sound when the left joystick moves
def tada_sound():
    brain.play_sound(SoundType.TADA)
    wait(1, SECONDS)

controller_1.axis4.changed(tada_sound)

Constructors #

Constructors are used to manually create Controller objects, which are necessary for configuring a controller outside of VEXcode. You can only create two controllers in a project.

Controller #

Controller creates a controller.

Usage:
Controller(controller_type)

Parameters	Description
`controller_type`	Optional.The type of controller to create. `PRIMARY` (Default) - The primary controller. `PARTNER` - The partner controller.

Parameters

Description

controller_type

Optional.The type of controller to create.

PRIMARY (Default) - The primary controller.
PARTNER - The partner controller.

# Create a Controller
controller_1 = Controller(PRIMARY)

# Create two Controllers
controller_1 = Controller(PRIMARY)
controller_2 = Controller(PARTNER)