API

class vex.Accelerometer(port, sensitivity=0)

Bases: object

Accelerometer class - create a new accelerometer. For full functionality, three Accelerometer instances would need to be created, one for each axis.

accx = Accelerometer(brain.three_wire_port.a)
accy = Accelerometer(brain.three_wire_port.b)
accz = Accelerometer(brain.three_wire_port.c)

__init__(port, sensitivity=0)

Ctor.

Parameters

port – The 3wire port to use for the accelerometer.
sensitivity – set high sensitivity mode (+/- 2G), use True or 1. (optional)

acceleration()

The current value of the accelerometer scaled to units of gravity.

Returns: A value in the range +/- 6 or +/-2G if high sensitivity mode is set.

# get accelerometer in range+/- 6G
value = accz.acceleration()

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the accelerometer changes.

Parameters

callback – A function that will be called when the value of the accelerometer changes.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("accelerometer changed")

accz.changed(foo)

type()

value(units: ~typing.Union[~vex.AnalogUnits.AnalogUnits, ~vex.PercentUnits.PercentUnits] = 12BIT)

The current value of the accelerometer.

Parameters: units – A valid AnalogUnits type or PERCENT, the default is 12 bit analog. (optional)
Returns: A value in the range that is specified by the units.

# get accelerometer in range 0 - 4095
value = accz.value()

# get accelerometer in range 0 - 1023
value = accz.value(AnalogUnits.TENBIT)

class vex.AnalogIn(port)

Bases: object

AnalogIn class - create a new analog input.

ana1 = AnalogIn(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the analog input.

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the analog input changes.

Parameters

callback – A function that will be called when the value of the analog input changes.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("analog input changed")

ana1.changed(foo)

type()

value(units: ~typing.Union[~vex.AnalogUnits.AnalogUnits, ~vex.PercentUnits.PercentUnits] = 12BIT)

The current value of the analog input.

Parameters: units – A valid AnalogUnits type or PERCENT, the default is 12 bit analog. (optional)
Returns: A value in the range that is specified by the units.

# get analog input in range 0 - 4095
value = ana1.value()

# get analog input in range 0 - 1023
value = ana1.value(AnalogUnits.TENBIT)

class vex.AnalogUnits

Bases: object

The measurement units for analog values.

class AnalogUnits(value, name)

Bases: vexEnum

Analog units.

EIGHTBIT = 8BIT: An analog unit that is measured in an 8-bit analog value (a value with 256 possible states).

MV = MV: An analog unit that is measured in millivolts.

PCT = PCT: An analog unit that is measured in percentage.

TENBIT = 10BIT: An analog unit that is measured in an 10-bit analog value (a value with 1024 possible states).

TWELVEBIT = 12BIT: An analog unit that is measured in an 12-bit analog value (a value with 4096 possible states).

class vex.AxisType

Bases: object

The defined units for inertial sensor axis.

class AxisType(value, name)

Bases: vexEnum

Axis type.

XAXIS = XAXIS: The X axis of the Inertial sensor.

YAXIS = YAXIS: The Y axis of the Inertial sensor.

ZAXIS = ZAXIS: The Z axis of the Inertial sensor.

vex.BRAKE = BRAKE: A brake unit that is defined as motor brake.

class vex.Brain(*args)

Bases: object

Brain class. The Brain class creates a number of instances of internal classes that allow access to the screen, battery, 3wire ports and sd card on the EXP brain.

Returns: An instance of the Brain class.

brain = Brain()

class Battery

Bases: object

Battery class - access the brain battery.

Returns: Instance of Battery class.

__init__()

capacity()

Read remaining capacity of the battery.

Returns: Capacity as percentage.

current(units=AMP)

Read the current of the battery.

Params units: AMP, default is mA but jot available as an enum. (optional)
Returns: Current in supplied units.

temperature(units: Union[TemperatureUnits, PercentUnits] = PERCENT)

Read the temperature of the battery (system temperature for EXP).

Parameters: units – PERCENT, CELCIUS or FAHRENHEIT, default is CELCIUS. (optional)
Returns: Temperature in supplied units.

voltage(units=mV)

Read the voltage of the battery:

Parameters: units – VOLTS or MV, default is MV. (optional)
Returns: Voltage in supplied units.

class Button(*args)

Bases: object

Button class - access the brain buttons.

Returns: Instance of Button class.

__init__(*args)

pressed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when a button is pressed.

Parameters

callback – A function that will be called when the button is pressed.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("button pressed")

brain.buttonLeft.pressed(foo)

pressing()

Returns whether a button is currently being pressed.

Returns: True or False.

released(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when a button is released

Parameters

callback – A function that will be called when the button is pressed.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("button released")

brain.buttonLeft.pressed(foo)

class Lcd

Bases: object

Brain.Lcd class. A class used to access to screen on the EXP for drawing and receiving touch events.

Returns: An instance of the Brain.Lcd class.

__init__()

clear_line(number=None, color=0): Deprecated.

clear_row(number=None, color=0)

Clear screen row to a single color. The color can be passed in similar ways to the Color class.

Parameters

row – The row to clear, default is current cursor row. (optional)
color – The color the screen will be set to, default is BLACK. (optional)

# clear row to black
brain.screen.clear_row()

# clear row 2 to red
brain.screen.clear_row(2, Color.RED)

clear_screen(color=0)

Clear the whole screen to a single color. The color can be passed in similar ways to the Color class.

Parameters: color – The color the screen will be set to, default is BLACK. (optional)

# clear screen to black
brain.screen.clear_screen()

# clear screen to blue using predefined color
brain.screen.clear_screen(Color.BLUE)

column()

Return the current column where text will be printed.

Returns: Column.

draw_circle(x: Union[int, float], y: Union[int, float], radius: Union[int, float], color: Optional[Any] = None)

Draw a circle on the screen using the current pen and fill colors.

Parameters

x – The x position of the circle center referenced to the screen origin.
y – The y position of the circle center referenced to the screen origin.
radius – The height of the circle.
color – An optional fill color, the current fill color will be used if not suppplied. (optional)

# draw a green circle on the screen that is filled using blue
brain.screen.set_pen_color(Color.GREEN)
brain.screen.set_fill_color(Color.BLUE)
brain.screen.draw_circle(50, 50, 10)

# draw a green circle on the screen that is filled using red
brain.screen.set_pen_color(Color.GREEN)
brain.screen.draw_circle(100, 50, 10, Color.RED)

draw_image_from_file(filename: str, x: Union[int, float], y: Union[int, float])

Display the named image from the SD Card.

Parameters

filename – The file name of the image.
x – The X coordinate for the top left corner of the image on the screen.
y – The Y coordinate for the top left corner of the image on the screen.

Returns

True if successfully drawm, False on error.

# draw the vex.bmp image on the screen at coodinate 0, 0
# an image named vex.bmp must be on the SD Card in the root folder
brain.screen.draw_image_from_file('vex.bmp', 0, 0)

draw_line(x1: Union[int, float], y1: Union[int, float], x2: Union[int, float], y2: Union[int, float])

Draw a line on the screen using the current pen color.

Parameters

x1 – The x position of the beginning of the line referenced to the screen origin.
y1 – The y position of the beginning of the line referenced to the screen origin.
x2 – The x position of the end of the line referenced to the screen origin.
y2 – The y position of the end of the line referenced to the screen origin.

# draw a red line on the screen
brain.screen.set_pen_color(Color.RED)
brain.screen.draw_line(10, 10, 20, 20)

draw_pixel(x: Union[int, float], y: Union[int, float])

Draw a pixel on the screen using the current pen color.

Parameters

x – The x position to draw the pixel referenced to the screen origin.
y – The y position to draw the pixel referenced to the screen origin.

# draw a red pixel on the screen
brain.screen.set_pen_color(Color.RED)
brain.screen.draw_pixel(10, 10)

draw_rectangle(x: Union[int, float], y: Union[int, float], width: Union[int, float], height: Union[int, float], color: Optional[Any] = None)

Draw a rectangle on the screen using the current pen and fill colors.

Parameters

x – The x position of the rectangle top/left corner referenced to the screen origin.
y – The y position of the rectangle top/left corner referenced to the screen origin.
width – The width of the rectangle.
height – The height of the rectangle.
color – An optional fill color, the current fill color will be used if not suppplied. (optional)

# draw a green rectangle on the screen that is filled using blue
brain.screen.set_pen_color(Color.GREEN)
brain.screen.set_fill_color(Color.BLUE)
brain.screen.draw_rectangle(10, 10, 20, 20)

# draw a green rectangle on the screen that is filled using red
brain.screen.set_pen_color(Color.GREEN)
brain.screen.draw_rectangle(50, 50, 20, 20, Color.RED)

get_string_height(*args)

get height of a string

#### Arguments:: arguments are in the same format as can be passed to the print function.
#### Returns:: height of string as integer.

get_string_width(*args)

get width of a string

#### Arguments:: arguments are in the same format as can be passed to the print function.
#### Returns:: width of string as integer.

new_line(): Deprecated.

next_row(): Move the cursoe to the beginning of the next row.

pressed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the screen is pressed.

Parameters

callback – A function that will be called when the screen is pressed.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("screen pressed")

brain.screen.pressed(foo)

pressing()

Returns whether the screen is currently being pressed (touched)

Returns: True or False.

print(*args, **kwargs)

Print text on the screen using current curser position.

Optional keyword arguments:

sep: string inserted between values, default a space.
precision: the number of decimal places to display when printing simple numbers, default is 2

# print the number 1 on the screen at current cursor position
brain.screen.print(1)

# print the numbers 1, 2, 3 and 4 on the screen at current cursor position separated by a '-'
brain.screen.print(1, 2, 3, 4, sep='-')

# print motor1 velocity on the screen using a format string
brain.screen.print("motor  1 : % 7.2f" %(motor1.velocity()))

print_at(*args, **kwargs)

Print text on the screen at x and y coordinates.

Required keyword arguments:

x: The x position of the text referenced to the screen origin.
y: The y position of the text referenced to the screen origin.

Optional keyword arguments:

sep: string inserted between values, default a space.
precision: the number of decimal places to display when printing simple numbers, default is 2
opaque: text does not clear background pixels if set to False. default is True.

# print the number 1 on the screen at position x=100, y=40
brain.screen.print_at(1, x=100, y=40)

# print the numbers 1, 2, 3 and 4 on the screen at position x=100, y=40
brain.screen.print_at(1, 2, 3, 4, x=100, y=40)

# print motor1 velocity on the screen using a format string at position x=100, y=40
brain.screen.print_at("motor  1 : % 7.2f" %(motor1.velocity()), x=100, y=40)

released(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the screen is released (touch removed).

Parameters: callback – A function that will be called when the screen is released.
Arg: A tuple that is used to pass arguments to the callback function. (optional)
Returns: An instance of the Event class.

def foo():
    print("screen released")

brain.screen.released(foo)

render()

Switch drawing to double buffered and render too screen. Once called, further drawing will not appear on the screen until the next time render is called. This function will block until the screen can be updated.

Returns: True if buffer was successfully rendered to screen.

row()

Return the current row where text will be printed.

Returns: Row.

set_clip_region(x: Union[int, float], y: Union[int, float], width: Union[int, float], height: Union[int, float])

Sets the clip region for drawing to the supplied rectangle. All drawing is clipped to the given rectangle. This is set on a per thread basis.

Parameters

x – The x position of the rectangle top/left corner referenced to the screen origin.
y – The y position of the rectangle top/left corner referenced to the screen origin.
width – The width of the rectangle.
height – The height of the rectangle.

set_cursor(row: Union[int, float], col: Union[int, float])

Set the cursor position used for printing text on the screen row and column spacing will take into account the selected font. The base cell size if 10x20 pixels for the MONO20 font. Text may not accurately print if using a proportional font. The top, left corner of the screen is position 1,1.

Parameters

row – The cursor row.
col – The cursor column.

set_fill_color(color)

Set the fill color used for drawing rectangles and circles. The color can be passed in similar ways to the Color class. The color is specific to the running thread.

Parameters: color – The fill color.

# set pen color red using a hex value
brain.screen.set_fill_color(0xFF0000)

# set pen color blue using predefined color
brain.screen.set_fill_color(Color.BLUE)

# set pen color green using web string
brain.screen.set_fill_color("#00FF00")

set_font(fontname: FontType)

Set the font type used for printing text on the screen

Parameters: fontname – The font name.

brain.screen.font_type(FontType.MONO40)

set_origin(x: Union[int, float], y: Union[int, float])

Set the origin used for drawing graphics on the screen. Drawing functions consider the top left corner of the screen as the origin. This function can move the origin to an alternate position such as the center of the screen.

Parameters

x – The origins x position relative to top left corner.
y – The origins y position relative to top left corner.

set_pen_color(color)

Set the pen color used for drawing lines, rectangles and circles

The color can be passed in similar ways to the Color class. The color is specific to the running thread.

Parameters: color – The pen color.

# set pen color red using a hex value
brain.screen.set_pen_color(0xFF0000)

# set pen color blue using predefined color
brain.screen.set_pen_color(Color.BLUE)

# set pen color green using web string
brain.screen.set_pen_color("#00FF00")

set_pen_width(width: Union[int, float])

Set the pen width used for drawing lines, rectangles and circles

Parameters: width – The pen width.

x_position()

The X coordinate of the last screen event, press or release.

Returns: The X coordinate as an int.

def foo():
    print("screen pressed at ", brain.screen.x_position())

brain.screen.pressed(foo)

y_position()

The Y coordinate of the last screen event, press or release.

Returns: The Y coordinate as an int.

def foo():
    print("screen pressed at ", brain.screen.y_position())

brain.screen.pressed(foo)

class Sdcard

Bases: object

Sdcard class - access the brain sdcard.

Returns: Instance of Sdcard class.

__init__()

appendfile(filename: str, *args)

Append a bytearray into a named file. Append is used to add more data to an existing file.

Parameters

filename – The name of the file to write.
buffer – A bytearray to write into the file.

Returns

The number of bytes written.

# append bytearray into file
brain.sdcard.appendfile('MyTextFile.txt', bytearray("World "))

exists(*args)

Check to see if named file exists on the sd card.

Parameters: filename – The name of the file to check.
Returns: True if file exists.

filesize(filename: str)

Returns the size in bytes of the named file.

Parameters: filename – The name of the file to check.
Returns: Size of file in bytes.

is_inserted()

Returns status of SD Card.

Returns: True if an sdcard is inserted into the brain.

loadfile(filename: str, *args)

Load the named file.

Parameters

filename – The name of the file to read.
buffer – A bytearray to read the file into. (optional)

Returns

A bytearray with file data.

# read file into new bytearray
b = brain.sdcard.loadfile('MyTextFile.txt')

savefile(filename: str, *args)

Save a bytearray into a named file. If the optional bytearray is None, then an empty file is created.

Parameters

filename – The name of the file to write.
buffer – A bytearray to write into the file. (optional)

Returns

The number of bytes written

# write bytearray into file
brain.sdcard.savefile('MyTextFile.txt', bytearray("Hello "))

size(filename: str)

Returns the size in bytes of the named file.

Parameters: filename – The name of the file to check.
Returns: Size of file in bytes.

__init__(*args)

battery: An instance of the Battery class

buttonCheck: An instance of the Button class for the check button

buttonDown: An instance of the Button class for the right button

buttonLeft: An instance of the Button class for the left button

buttonRight: An instance of the Button class for the right button

buttonUp: An instance of the Button class for the left button

play_file(filename: str, volume=100, source=0)

Play a sound file in wav format on the brain

Parameters

filename – The sound file to play
volume – The sound volume, maximum is 100. (optional)
source – Reserved, should be set to 0. (optional)

brain.play_file('myfile.wav')
brain.play_file('myfile.wav', 50)

play_note(octave: Union[int, float], note: Union[int, float], duration=1000, volume=1000)

Play a note on the brain. There are two forms of this function on EXP. The first for uses two arguments and is compatible with IQ2. Notes are in the range 1 to 7. The second for takes 3 or 4 arguments and allows a 12 note scale which included sharps/flats.

Parameters

octave – The octave to use
note – The note to play
duration – The duration in mS to play the note for. (optional)
volume – The sound volume, maximum is 100. (optional)

brain.play_note(1, 4)
brain.play_note(1, 4, 200, 50)

play_sound(sound: SoundType, volume=100)

Play a sound on the brain.

Parameters

sound – The sound to play.
volume – The sound volume, maximum is 100. (optional)

brain.play_sound(SoundType.TADA)

screen: An instance of the Lcd class

sdcard: An instance of the Sdcard class

sound_duration()

Get the total duration of the currently playing sound.

Returns: The duration in mS.

sound_is_active()

Check whether a sound is playing

Returns: True is a sound is playing.

sound_off()

Stop any sound that is playing.

brain.sound_off()

sound_remaining()

Get the remaining duration of the currently playing sound.

Returns: The duration in mS.

three_wire_port: An instance of the Triport (3wire) class

timer: An instance of the Timer class

class vex.BrakeType

Bases: object

The defined units for motor brake values.

BRAKE = BRAKE: A brake unit that is defined as motor brake.

class BrakeType(value, name)

Bases: vexEnum

Brake type.

COAST = COAST: A brake unit that is defined as motor coast.

HOLD = HOLD: A brake unit that is defined as motor hold.

class vex.Bumper(port)

Bases: object

Bumper class - create a new bumper switch.

bumper1 = Bumper(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port the bumper switch is connected to.

pressed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the bumper switch is pressed.

Parameters

callback – A function that will be called when the bumper switch is pressed
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class

def foo():
     print("switch pressed")

bumper1.pressed(foo)

pressing()

Returns whether the bumper switch is currently being pressed.

Returns: True or False.

released(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the bumper switch is released.

Parameters

callback – A function that will be called when the bumper switch is released
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class

def foo():
     print("switch released")

bumper1.released(foo)

type()

value()

The current value of the bumper switch.

Returns: 1 or 0.

vex.COAST = COAST: A brake unit that is defined as motor coast.

class vex.Code(c1: Signature, *args)

Bases: object

Code class - a class for holding vision sensor codes. A vision code is a collection of up to five vision signatures.

SIG_1 = Signature(1, 6035, 7111, 6572, -1345, -475, -910, 3.000, 0)
SIG_2 = Signature(2, 6035, 7111, 6572, -1345, -475, -910, 3.000, 0)
C1 = Code(SIG_1, SIG_2)

__init__(c1: Signature, *args)

Ctor.

Parameters

sig1 – A vision signature.
sig2 – A vision signature.
(optional) (sig5) – A vision signature.
(optional) – A vision signature.
(optional) – A vision signature.

id(): Not used, always returns 0

class vex.Color(*args)

Bases: object

Color class - create a new color. This class is used to create instances of color objects.

BLACK = 0: Predefined Color black.

BLUE = 255: Predefined color: blue.

CYAN = 65535: Predefined color: cyan.

GREEN = 65280: Predefined color: green.

ORANGE = 16753920: Predefined color: orange.

PURPLE = 16711935: Predefined color: purple.

RED = 16711680: Predefined color: red.

TRANSPARENT = 0: Predefined color: transparent.

WHITE = 16777215: Predefined color: white.

YELLOW = 16776960: Predefined color: yellow.

__init__(*args)

Ctor.

The color value, can be specified in various ways, see examples.

# create blue using hex value
c = Color(0x0000ff)

# create blue using r, g, b values
c = Color(0, 0, 255)

# create blue using web string
c = Color("#00F")

# create blue using web string (alternate)
c = Color("#0000FF")

# create red using an existing object
c = Color(Color.RED)

hsv(hue: Union[int, float], saturation: Union[int, float], value: Union[int, float])

Change existing Color instance using hsv.

Parameters

hue – The hue of the color.
saturation – The saturation of the color.
value – The brightness of the color.

Returns

Integer value representing the color.

# create a color that is red
c.hsv( 0, 1.0, 1.0)

is_transparent()

Return whether color is transparent or not.

Returns: True or False

rgb(*args): Change existing Color instance to new rgb value.

web(value: str)

Change existing Color instance using web string.

Parameters: value – The new color as a web string.
Returns: Integer value representing the color.

# create a color that is red
c.web('#F00')

class vex.Competition(driver: Callable[[], None], autonomous: Callable[[], None])

Bases: object

Competition class - create a class used for competition control.

def driver():
     print("driver called")

def auton():
     print("auton called")

comp = Competition(driver, auton)

__init__(driver: Callable[[], None], autonomous: Callable[[], None])

Ctor.

Parameters

driver – A function called as a thread when the driver control period starts.
autonomous – A function called as a thread when the driver control period starts.

is_autonomous()

Return autonomous state of the robot.

Returns: True if autonomous is enabled.

is_competition_switch()

Return connection state of the competition switch.

Returns: True if competition switch is connected.

static is_driver_control()

Return driver control state of the robot.

Returns: True if driver control is enabled.

static is_enabled()

Return enable/disable state of the robot.

Returns: True if the robot is enabled.

is_field_control()

Return connection state of field controller.

Returns: True if field controller is connected.

class vex.Controller(*args)

Bases: object

Controller class - create a class to access the controller.

Returns: An instance of the Controller class.

class Axis(*args)

Bases: object

Axis class

Returns: An instance of an Axis class.

__init__(*args)

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the axis value changes.

Parameters

callback – A function that will be called when the axis value changes
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("axis changed")

controller.axis1.changed(foo)

position()

Return the current position of the axis in percentage.

Returns: A value in the range +/- 100.

a = controller.axis1.position()

value()

Return the current position of the axis.

Returns: A value in the range +/- 127

a = controller.axis1.position()

class Button(*args)

Bases: object

__init__(*args)

pressed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when a button is pressed

Parameters

callback – A function that will be called when the button is pressed.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("button pressed")

controller.buttonL1.pressed(foo)

pressing()

Returns whether a button is currently being pressed.

Returns: True or False.

released(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when a button is released.

Parameters

callback – A function that will be called when the button is pressed.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("button released")

controller.buttonL1.pressed(foo)

class Lcd(*args)

Bases: object

Controller.Lcd class. A class used to access the screen on the V5 controller.

Returns: An instance of the Brain.Lcd class.

__init__(*args)

clear_line(number: Union[int, float])

clear_row(number: Union[int, float])

Clear screen row

Parameters: row – The row to clear, 1, 2, or 3, default is current cursor row. (optional)

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

clear_screen()

Clear the whole screen.

controller.screen.clear_screen()

column(): Return the current column where text will be printed.

new_line(): Deprecated.

next_row(): Move the cursor to the beginning of the next row.

print(*args)

Print text on the screen using current curser position.

Optional keyword arguments.

sep: string inserted between values, default a space.
precision: the number of decimal places to display when printing simple numbers, default is 2

# print the number 1 on the screen at current cursor position
controller.screen.print(1)

# print the numbers 1, 2, 3 and 4 on the screen at current cursor position separated by a '-'
controller.screen.print(1, 2, 3, 4, sep='-')

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

row(): Return the current row where text will be printed.

set_cursor(row: Union[int, float], col: Union[int, float])

Set the cursor position used for printing text on the screen. V5 controller has at most 3 lines of text.

Parameters

row – The cursor row. 1, 2 or 3
col – The cursor column. The first column is 1.

__init__(*args)

axis1: The joystick axis 1 on the controller

axis2: The joystick axis 2 on the controller

axis3: The joystick axis 3 on the controller

axis4: The joystick axis 4 on the controller

buttonA: The A button on the controller

buttonB: The B button on the controller

buttonDown: The Down button on the controller

buttonL1: The L1 button on the controller

buttonL2: The L2 button on the controller

buttonL3: The L3 button on the controller (EXP controller only)

buttonLeft: The Left button on the controller (V5 controller only)

buttonR1: The R1 button on the controller

buttonR2: The R2 button on the controller

buttonR3: The R3 button on the controller (EXP controller only)

buttonRight: The Right button on the controller (V5 controller only)

buttonUp: The Up button on the controller

buttonX: The X button on the controller (V5 controller only)

buttonY: The Y button on the controller (V5 controller only)

rumble(pattern: str)

Send a rumble string to the V5 controller

Parameters: pattern – A pattern using ‘.’ and ‘-’ for short and long rumbles.

controller.rumble('..--')

screen: An instance of the Lcd class (V5 controller only)

class vex.ControllerType

Bases: object

The defined types for controller devices.

class ControllerType(value, name)

Bases: vexEnum

Controller type.

PARTNER = PARTNER: A controller defined as a partner controller.

PRIMARY = PRIMARY: A controller defined as a primary controller.

class vex.CurrentUnits

Bases: object

The measurement units for current values.

AMP = AMP: A current unit that is measured in amps.

class CurrentUnits(value, name)

Bases: vexEnum

Current units.

vex.DEGREES = DEG: A rotation unit that is measured in degrees.

vex.DPS = DPS: A velocity unit that is measured in degrees per second.

class vex.DigitalIn(port)

Bases: object

DigitalIn class - create a new digital input.

dig1 = DigitalIn(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the digital input.

high(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the digital input goes to the logic high state.

Parameters

callback – A function that will be called when the digital input goes to the logic high state
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class

def foo():
     print("input high")

dig1.high(foo)

low(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the digital input goes to the logic low state.

Parameters

callback – A function that will be called when the digital input goes to the logic low state
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("input low")

dig1.low(foo)

type()

value()

The current value of the digital input.

Returns: 1 or 0.

class vex.DigitalOut(port)

Bases: object

DigitalOut class - create a new digital output.

dig1 = DigitalOut(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the digital output.

set(value)

Set the output level for the digital output.

param value

0, 1, True or False.

dig1.set(True)

type()

value()

The current value of the digital output.

Returns: 1 or 0.

class vex.DirectionType

Bases: object

The defined units for direction values.

class DirectionType(value, name)

Bases: vexEnum

Direction type.

FORWARD = FORWARD: A direction unit that is defined as forward.

REVERSE = REVERSE: A direction unit that is defined as backward.

UNDEFINED = UNDEFINED: A direction unit used when direction is not known.

class vex.Distance(port)

Bases: object

Distance class - a class for working with the distance sensor.

dist1 = Distance(Ports.PORT1)

__init__(port)

Ctor.

Parameters: port – The smartport this device is attached to.

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the distance value changes.

Parameters

callback – A function that will be called when the distance value changes
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("distance changed")

dist1.changed(foo)

installed()

Check for device connection.

Returns: True or False.

is_object_detected()

Returns if an object is detected.

Returns: True or False.

object_distance(units=MM)

The current distance the sensor is reading. The distance will return a large positive number if no object is detected.

Parameters: units – The distance units to return the distance value in; default is MM. (optional)
Returns: A value for distance in the specified units.

# get distance in mm
value = dist1.object_distance()

# get distance in inches
value = dist1.object_distance(INCHES)

object_rawsize()

Get the raw value of object size the sensor is detecting. Raw size will be a number ranging from 0 to about 400. Larger and more reflective objects will return larger values.

Returns: A value for object size that is a number.

# get object raw size
size = dist1.object_rawsize()

object_size()

Get an estimation of the object size the sensor is detecting.

Returns: A value for object size. The value will be of type ObjectSizeType.

# get object size
size = dist1.object_size()

object_velocity()

Returns the object velocity. Velocity is calculated from change of distance over time.

Returns: The velocity in m/s.

timestamp()

Request the timestanp of last received message from the sensor.

Returns: Timestamp of the last status packet in mS.

class vex.DistanceUnits

Bases: object

The measurement units for distance values.

CM = CM: A distance unit that is measured in centimeters.

class DistanceUnits(value, name)

Bases: vexEnum

Distance units.

IN = IN: A distance unit that is measured in inches.

MM = MM: A distance unit that is measured in millimeters.

class vex.DriveTrain(lm, rm, wheelTravel: Union[int, float] = 300, trackWidth: Union[int, float] = 320, wheelBase: Union[int, float] = 320, units=MM, externalGearRatio=1.0)

Bases: object

DriveTrain class - use this to create a simple drivetrain

A simple two motor drivetrain using default values.

motor1 = Motor(Ports.PORT1)
motor2 = Motor(Ports.PORT2, True)
drive1 = DriveTrain(motor1, motor2)

A four motor drivetrain using custom values.

motor1 = Motor(Ports.PORT1)
motor2 = Motor(Ports.PORT2)
motor3 = Motor(Ports.PORT3, True)
motor4 = Motor(Ports.PORT4, True)
mgl = MotorGroup(motor1, motor3)
mgr = MotorGroup(motor2, motor4)
drive1 = DriveTrain(mgl, mgr, 8.6, 10, 12, INCHES)

__init__(lm, rm, wheelTravel: Union[int, float] = 300, trackWidth: Union[int, float] = 320, wheelBase: Union[int, float] = 320, units=MM, externalGearRatio=1.0)

Ctor.

Parameters

lm – Left motor or motorgroup.
rm – Right motor or motorgroup.
wheelTravel – The circumference of the driven wheels, default is 300 mm. (optional)
trackWidth – The trackwidth of the drivetrain, default is 320 mm. (optional)
wheelBase – The wheelBase of the drivetrain, default is 320 mm. (optional)
units – The units that wheelTravel, trackWidth and wheelBase are specified in, default is MM. (optional)
externalGearRatio – An optional gear ratio used to compensate drive distances if gearing is used. (optional)

current(units=AMP)

Returns the total current all drivetrain motors are using.

Parameters: units – The units for the returned current, the default is AMP. (optional)
Returns: The drivetrain current in provided units.

drive(direction, velocity=None, units=RPM)

Drive the drivetrain using the provided arguments. The drive command is similar to the motor spin command. All drive motors are commanded using the provided parameters.

Parameters

direction – The direction to drive, FORWARD or REVERSE.
velocity – spin the motors using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units – The units of the provided velocity, default is RPM. (optional)

# drive forward at velocity set with set_velocity
drive1.drive(FORWARD)
# drive forward at 50 rpm
drive1.drive(FORWARD, 50)
# drive with negative velocity, ie. backwards
drive1.drive(FORWARD, -20)
# drive forwards with 100% velocity
drive1.drive(FORWARD, 100, PERCENT)
# drive forwards at 50 rpm
drive1.drive(FORWARD, 50, RPM)
# drive forwards at 360 dps
drive1.drive(FORWARD, 360.0, VelocityUnits.DPS)

drive_for(direction, distance, units=IN, velocity=None, units_v=RPM, wait=True)

Move the drivetrain using the provided arguments. The drive_for command is similar to the motor spin_for command, however, the drivetrain is commanded to move a distance.

Parameters

direction – The direction to drive.
distance – The distance to drive.
units – The units for the provided distance, the default is INCHES. (optional)
velocity – drive using this velocity, the default velocity set by set_drive_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

Returns

None or if wait is True then completion success or failure.

# drive forward 10 inches from the current position
drive1.drive_for(FORWARD, 10, INCHES)

# drive reverse 1000mm from the current position with motors at 50 rpm
drive1.drive_for(REVERSE, 10000, MM, 50, RPM)

efficiency(units=PERCENT)

Returns the average efficiency of the left and right motors. This command only considers the first motor for left and right sides of the drive.

Parameters: units – The units for the efficiency, the only valid value is PERCENT. (optional)
Returns: The motor efficiency in percent.

get_timeout()

Get the current timeout value used by the drivetrain

Returns: Timeout value in mS.

is_done()

Returns the current status of the drive_for or turn_for command. This function is used when False has been passed as the wait parameter to drive_for or turn_for. It will return False if the drivetrain is still moving or True if it has completed the move or a timeout occured.

Returns: The current drive_for or turn_for status.

is_moving()

Returns the current status of the drive_for or turn_for command. This function is used when False has been passed as the wait parameter to drive_for or turn_for. It will return True if the drivetrain is still moving or False if it has completed the move or a timeout occured.

Returns: The current drive_for or turn_for status.

power(units=WATT)

Returns the total power all drivetrain motors are using. This command only considers the first motor for left and right sides of the drive.

Parameters: units – The units for the returned power, the default is WATT. (optional)
Returns: The drivetrain power in provided units

set_drive_velocity(velocity, units=RPM)

Set default velocity for drive commands. This will be the velocity used for subsequent calls to drive if a velocity is not provided to that function.

Parameters

velocity – The new velocity.
units – The units for the supplied velocity, the default is RPM.

set_stopping(mode=COAST)

Set the stopping mode for all motors on the drivetrain. Setting the action for the motors when stopped.

Parameters: mode – The stopping mode, COAST, BRAKE or HOLD.

set_timeout(timeout, units=MSEC)

Set the timeout value used all motors on the drivetrain. The timeout value is used when performing drive_for and turn_for commands. If timeout is reached and the motor has not completed moving, then the function will return False.

Parameters

timeout – The new timeout.
units – The units for the provided timeout, the default is MSEC.

set_turn_velocity(velocity, units=RPM)

Set default velocity for turn commands. This will be the velocity used for subsequent calls to turn if a velocity is not provided to that function.

Parameters

velocity – The new velocity.
units – The units for the supplied velocity, the default is RPM.

stop(mode=None): Stop the drivetrain, set to 0 velocity and set current stopping_mode. The motors will be stopped and set to COAST, BRAKE or HOLD.

temperature(units=CELSIUS)

Returns the average temperature of the left and right motors. This command only considers the first motor for left and right sides of the drive.

Parameters: units – The units for the returned temperature, the default is CELCIUS. (optional)
Returns: The motor temperature in provided units.

torque(units=NM)

Returns the total torque all drivetrain motors are using. This command only considers the first motor for left and right sides of the drive.

Parameters: units – The units for the returned torque, the default is NM. (optional)
Returns: The motor torque in provided units.

turn(direction, velocity=None, units=RPM)

Turn the drivetrain using the provided arguments. The drive command is similar to the motor spin command. All drive motors are commanded using the provided parameters.

Parameters

direction – The turn direction, LEFT or RIGHT.
velocity – spin the motors using this velocity, the default velocity set by set_turn_velocity will be used if not provided. (optional)
units – The units of the provided velocity, default is RPM. (optional)

# turn left at velocity set with set_turn_velocity
drive1.turn(LEFT)
# drive right at 50 rpm
drive1.turn(RIGHT, 50)
# turn right with 100% velocity
drive1.turn(RIGHT, 100, PERCENT)
# turn right at 50 rpm
drive1.turn(RIGHT, 50, RPM)
# turn right at 360 dps
drive1.turn(RIGHT, 360.0, VelocityUnits.DPS)

turn_for(direction, angle, units=DEG, velocity=None, units_v=RPM, wait=True)

Turn the drivetrain using the provided arguments. The turn_for command is similar to the motor spin_for command, however, the drivetrain is commanded to turn a specified angle.

Parameters

direction – The direction to turn, LEFT or RIGHT
angle – The angle to turn
units – The units for the provided angle, the default is DEGREES. (optional)
velocity – drive using this velocity, the default velocity set by set_drive_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

Returns

None or if wait is True then completion success or failure.

# turn right 90 degrees
drive1.turn_for(RIGHT, 90, DEGREES)
# turn left 180 degrees with motors at 50 rpm
drive1.turn_for(LEFT, 180, DEGREES, 50, RPM)

velocity(units=RPM)

Returns average velocity of the left and right motors.

Parameters: units – The units for the returned velocity, the default is RPM. (optional)
Returns: The drivetrain velocity in provided units.

class vex.Electromagnet(port)

Bases: object

Electromagnet class - a class for working with the electromagnet.

em1 = Electromagnet(Ports.PORT1)

__init__(port)

Ctor.

Parameters: port – The smartport this device is attached to.

drop(duration=1000, units=MSEC, power=50)

Energize the electromagnet to drop objects.

Parameters

duration – the duration to energize the magner for, default is 1 second. (optional)
units – the units for duration, default is MSEC. (optional)
power – the power used when energizing. (optional)

# drop with default values
em1.drop()

# drop with custom values
em1.drop(250, MSEC, 90)

installed()

Check for device connection.

Returns: True or False.

pickup(duration=1000, units=MSEC, power=50)

Energize the electromagnet to pickup objects.

Parameters

duration – the duration to energize the magner for, default is 1 second. (optional)
units – the units for duration, default is MSEC. (optional)
power – the power used when energizing. (optional)

# pickup with default values
em1.pickup()

# pickup with custom values
em1.pickup(250, MSEC, 90)

set_power(value)

Set the default power to use for drop and pickup methods.

Parameters: value – Power in range 0 to 100.

# set default power to 80
em1.set_power(80)

temperature(*args)

Returns the temperature of the electromagnet.

Parameters: units – The units for the returned temperature, the default is CELCIUS. (optional)
Returns: The electromagnet temperature in provided units.

timestamp()

Request the timestanp of last received message from the sensor.

Returns: Timestamp of the last status packet in mS.

class vex.Encoder(port)

Bases: object

Encoder class - create a new encoder sensor. An encoder uses two adjacent 3wire ports. Valid port pairs are a/b, c/d, e/f and g/h.

enc1 = Encoder(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the encoder sensor.

position(units=DEG)

The current position of the encoder.

Parameters: units – The rotation units to return the position value in, default is DEGREES. (optional)
Returns: A value for encoder position in the specified units.

# get encoder position
value = enc1.position()

reset_position(): Reset the encoder position to 0.

set_position(value, units=DEG)

Set the encoder position to a new value.

Parameters

value – The new value to use for position.
units – The rotation units type for value, the default is DEGREES. (optional)

# set the value of position to 180 degrees
enc1.set_position(180)

type()

value()

The current value of the encoder in raw counts. One full turn of the encoder is 360 counts.

Returns: A value for encoder counts.

# get encoder raw counts
value = enc1.value()

velocity(units=RPM)

The current velocity of the encoder

Parameters: units – The velociyt units to return the position value in, default is RPM. (optional)
Returns: A value for encoder velocity in the specified units.

# get encoder velocity in rpm
value = enc1.velocity()

class vex.Event(callback=None, arg: tuple = ())

Bases: object

Event class - create a new event. A function is registered that will be called when the event broadcast() function is called. More than one function can be assinged to a single event.

def foo():
     print("foo")

def bar():
     print("bar")

e = Event(foo)
e.set(bar)

# There needs to be some small delay after events are created before they can be broadcast to
sleep(20)

# cause both foo and bar to be called
e.broadcast()

__init__(callback=None, arg: tuple = ())

Ctor.

Parameters

callback – A function that will be called when the event is broadcast. (optional)
arg – A tuple that is used to pass arguments to the event callback function. (optional)

broadcast()

Broadcast to the event and cause all registered callback function to run.

# broadcast to an existing event e
e.broadcast()

broadcast_and_wait(timeout=60000)

Broadcast to the event and cause all registered callback function to run. This is similar to broadcast except that it will wait for all registered callbacks to complete before returning.

# broadcast to an existing event e, wait for completion
e.broadcast_and_wait()

set(callback: Callable[[...], None], arg: tuple = ())

Add callback function to an existing event.

Parameters

callback – A function that will be called when the event is broadcast.
arg – A tuple that is used to pass arguments to the event callback function. (optional)

def bar():
     print("bar")

# add callback function to existing event e
e.set(bar)

class vex.EventMask(*args)

Bases: object

__init__(*args)

vex.FORWARD = FORWARD: A direction unit that is defined as forward.

class vex.FontType

Bases: object

A unit representing font type and size

CJK16 = CJK16: Chinese/Japanese/Korean font of size 16.

class FontType(value, name)

Bases: vexEnum

Font type.

MONO12 = MONO12: Proportional font of size 12.

MONO15 = MONO15: Proportional font of size 15.

MONO20 = MONO20: Monotype font of size 20.

MONO30 = MONO30: Monotype font of size 30.

MONO40 = MONO40: Monotype font of size 40.

MONO60 = MONO60: Monotype font of size 60.

PROP20 = PROP20: Proportional font of size 20.

PROP30 = PROP30: Proportional font of size 30.

PROP40 = PROP40: Proportional font of size 40.

PROP60 = PROP60: Proportional font of size 60.

class vex.GearSetting

Bases: object

The defined units for gear values.

class GearSetting(value, name)

Bases: vexEnum

Gear setting.

RATIO_18_1 = RATIO18_1: A gear unit that is defined as the green 18:1 gear cartridge used in V5 Smart Motors.

RATIO_36_1 = RATIO36_1: A gear unit that is defined as the red 36:1 gear cartridge used in V5 Smart Motors.

RATIO_6_1 = RATIO6_1: A gear unit that is defined as the blue 6:1 gear cartridge used in V5 Smart Motors.

class vex.GestureType

Bases: object

The defined units for optical sensor gesture types.

DOWN = DOWN: Down.

class GestureType(value, name)

Bases: vexEnum

Gesture type.

LEFT = LEFT: Left.

NONE = NONE: None.

RIGHT = RIGHT: Right.

UP = UP: Up.

class vex.Gps(port, *args)

Bases: object

Gps class - a class for working with the gps sensor.

gps1 = Gps(Ports.PORT1)

__init__(port, *args)

Ctor.

Parameters

port – The smartport this device is attached to.
origin_x – The X location of the GPS with respect to origin of the robot. Note: both X and Y must be supplied. (optional)
origin_y – The Y location of the GPS with respect to origin of the robot. Note: both X and Y must be supplied. (optional)
units – The units that X and Y location are specified in, default is MM. (optional)

acceleration(axis: AxisType)

Read the acceleration for one axis of the gps.

Parameters: axis – The axis to read.
Returns: A value for the acceleration of the axis in units of gravity.

# get the acceleration for the Z axis of the gps
zaccel = gps1.acceleration(ZAXIS)

calibrate(): Not used on the GPS sensor.

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the gps heading changes. This is not particularly useful as gps heading is not stable and will cause many events.

Parameters

callback – A function that will be called when the value of the gps heading changes
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("heading changed")

gps1.changed(foo)

get_turn_type()

Get the direction that returns positive values for heading. An advanced function that is not generally used.

Returns: The current TurnType, LEFT or RIGHT.

gyro_rate(axis: AxisType, units=DPS)

Read the gyro rate for one axis of the gps.

Parameters

axis – The axis to read.
units – The units to return the orientation in, default is DPS. (optional)

Returns

A value for the axis orientation in the units specified.

# get the gyro rate for the Z axis of the gps
zrate = gps1.gyro_rate(ZAXIS)

heading(units=DEG)

Read the current heading of the gps. Heading will be returned in the range 0 - 359.99 degrees

Parameters: units – The units to return the heading in, default is DEGREES. (optional)
Returns: A value for heading in the range that is specified by the units.

# get the current heading for the gps
value = gps1.heading()

installed(*args)

Check for device connection.

Returns: True or False.

is_calibrating(): Not used on the GPS sensor.

orientation(axis: OrientationType, units=DEG)

Read the orientation for one axis of the gps.

Parameters

axis – The axis to read.
units – The units to return the orientation in, default is DEGREES. (optional)

Returns

A value for the axis orientation in the units specified.

# get the pitch value for the gps
pitch = gps1.orientation(OrientationType.PITCH)

quality()

Read the current quality of the gps data. A quality of 100 indicates the gps can see the gps field strip and is returning good readings. The value for quality will reduce as the confidence in x and y location lowers.

Returns: A value of quality in the range 0 to 100.

# get the current location and heading quality for the gps
q = gps1.quality()

reset_heading(): Reset the gps heading to 0.

reset_rotation(): Reset the gps rotation to 0.

rotation(units=DEG)

Read the current rotation of the gps. Rotation is not limited, it can be both positive and negative and shows the absolute angle of the gps.

Parameters: units – The units to return the rotation in, default is DEGREES. (optional)
Returns: A value for heading in the range that is specified by the units.

# get the current rotation for the gps
value = gps1.rotation()

set_heading(value, units=DEG)

Set the gps heading to a new value. The new value for heading should be in the range 0 - 359.99 degrees.

Parameters

value – The new value to use for heading.
units – The rotation units type for value, the default is DEGREES. (optional)

# set the value of heading to 180 degrees
gps1.set_heading(180)

set_location(x, y, units=MM, angle=0, units_r=DEG)

Set the initial location of the robot. This gives a hint as to the location of the robot/gps sensor when it is first initialized. This can be used if in the initial position the gps cannot see the gps field strip.

Note

Both X and Y must be supplied.

Parameters

x – The X location of the GPS with respect to origin of the robot.
y – The Y location of the GPS with respect to origin of the robot.
units – The units that X and Y coordinates are specified in, default is MM. (optional)
angle – The initial heading of the robot. (optional)
units_r – The units that angle is specified in, default is DEGREES. (optional)

# set the initial location of the gps
gps1.set_location(1000, -1000, MM, 90, DEGREES)

set_origin(x=0, y=0, units=MM)

Set the origin of the gps sensor. An alternate way of setting sensor origin if not provided in the Gps class constructor.

Note

Both X and Y must be supplied.

Parameters

x – The X location of the GPS with respect to origin of the robot.
y – The Y location of the GPS with respect to origin of the robot.
units – The units that X and Y location are specified in, default is MM. (optional)

# set the origin of the gps
gps1.set_origin(6, -6, INCHES)

set_rotation(value, units=DEG)

Set the gps rotation to a new value.

Parameters

value – The new value to use for rotation.
units – The rotation units type for value, the default is DEGREES. (optional)

# set the value of rotation to 180 degrees
gps1.set_rotation(180)

set_sensor_rotation(value, units=DEG)

Set the sensor rotation of the gps sensor with respect tothe robot. This allows heading and rotation methods to return angles relative to the robot rather than the gps.

Parameters

value – The angle of the GPS with respect to the robot.
units – The units that value is specified in, default is DEGREES. (optional)

# set the sensor rotation of the gps
gps1.set_sensor_rotation(180, DEGREES)

set_turn_type(turntype)

Set the direction that returns positive values for heading. An advanced function that is not generally used.

Parameters: turntype – TurnType.LEFT or TurnType.RIGHT.

timestamp()

Request the timestanp of last received message from the sensor

Returns: Timestamp of the last status packet in mS.

x_position(units=MM)

Read the current x coordinate of the gps.

Parameters: units – The units to return the position in, default is MM. (optional)
Result: A value for the x coordinate in the units specified.

# get the current x coordinate for the gps
posx = gps1.x_position()

y_position(units=MM)

Read the current y coordinate of the gps.

Parameters: units – The units to return the position in, default is MM. (optional)
Returns: A value for the y coordinate in the units specified.

# get the current y coordinate for the gps
posy = gps1.y_position()

class vex.Gyro(port)

Bases: object

Gyro class - create a new gyro sensor.

gyro1 = Gyro(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the gyro sensor.

calibrate()

Start calibration of the gyro. Calibration should done when the gyro is not moving.

# start calibration
gyro1.calibrate()
# wait for completion
while gyro1.is_calibrating():
    sleep(50, MSEC)

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the gyro heading changes.

Parameters

callback – A function that will be called when the value of the gyro heading changes.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("gyro changed")

gyro1.changed(foo)

get_turn_type()

Get the direction that returns positive values for heading. An advanced function that is not generally used.

Returns: The current TurnType, LEFT or RIGHT.

heading(units=DEG)

Read the current heading of the gyro. Heading will be returned in the range 0 - 359.99 degrees.

Parameters: units – The units to return the heading in, default is DEGREES. (optional)
Returns: A value for heading in the range that is specified by the units.

# get the current heading for the gyro
value = gyro1.heading()

is_calibrating()

Check the calibration status of the gyro. Calibration should done when the gyro is not moving.

Returns: True when the gyro is calibrating

# start calibration
gyro1.calibrate()
# wait for completion
while gyro1.is_calibrating():
    sleep(50, MSEC)

reset_heading(): Reset the gyro heading to 0.

reset_rotation(): Reset the gyro rotation to 0.

rotation(units=DEG)

Read the current rotation of the gyro. Rotation is not limited, it can be both positive and negative and shows the absolute angle of the gyro.

Parameters: units – The units to return the rotation in, default is DEGREES. (optional)
Returns: A value for heading in the range that is specified by the units.

# get the current rotation for the gyro
value = gyro1.rotation()

set_heading(value: Union[int, float], units=DEG)

Set the gyro heading to a new value. The new value for heading should be in the range 0 - 359.99 degrees.

Parameters

value – The new value to use for heading.
units – The rotation units type for value, the default is DEGREES. (optional)

# set the value of heading to 180 degrees
gyro1.set_heading(180)

set_rotation(value, units=DEG)

Set the gyro rotation to a new value.

Parameters

value – The new value to use for rotation.
units – The rotation units type for value, the default is DEGREES. (optional)

# set the value of rotation to 180 degrees
gyro1.set_rotation(180)

set_turn_type(turntype: TurnType)

Set the direction that returns positive values for heading. An advanced function that is not generally used.

Parameters: turntype – TurnType.LEFT or TurnType.RIGHT.

type()

value(units: Union[RotationUnits, PercentUnits] = DEG)

The current value of the gyro. This method is generally not used, see heading() and rotation()

Parameters: units – A valid RotationUnits type or PERCENT, the default is DEGREES. (optional)
Returns: A value in the range that is specified by the units.

# get gyroin range 0 - 360 degrees
value = gyro1.value()

vex.HOLD = HOLD: A brake unit that is defined as motor hold.

vex.INCHES = IN: A distance unit that is measured in inches.

class vex.Inertial(port=28)

Bases: object

Inertial class - a class for working with the inertial sensor

#### Arguments:: port (optional): The smartport this device is attached to
#### Returns:: An instance of the Inertial class

# initialize internal IMU
imu1 = Inertial()

# initialize an external IMU on a smartport
imu1 = Inertial(Ports.PORT1)

__init__(port=28)

acceleration(axis: AxisType)

read the acceleration for one axis of the inertial sensor

Parameters: axis – The axis to read.
Returns: A value for the acceleration of the axis in units of gravity.

# get the acceleration for the Z axis of the inertial sensor
zaccel = imu1.acceleration(ZAXIS)

calibrate()

Start calibration of the inertial sensor. Calibration should done when the inertial sensor is not moving.

# start calibration
imu1.calibrate()
# wait for completion
while imu1.is_calibrating():
    sleep(50, MSEC)

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the inertial sensor heading changes.

Parameters

callback – A function that will be called when the value of the inertial sensor heading changes.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("heading changed")

imu1.changed(foo)

collision(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the inertial sensor detects a collision.

Parameters

callback – A function that will be called when the inertial sensor detects a collision.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("collision")

imu1.collision(foo)

get_turn_type()

Get the direction that returns positive values for heading. An advanced function that is not generally used.

Returns: The current TurnType, LEFT or RIGHT.

gyro_rate(axis: AxisType, units=DPS)

Read the gyro rate for one axis of the inertial sensor.

Parameters

axis – The axis to read
units – The units to return the gyro rate in, default is DPS. (optional)

Returns

A value for the gyro rate of the axis in the units specified.

# get the gyro rate for the Z axis of the inertial sensor
zrate = imu1.gyro_rate(ZAXIS)

heading(units=DEG)

Read the current heading of the inertial sensor. Heading will be returned in the range 0 - 359.99 degrees.

Parameters: units – The units to return the heading in, default is DEGREES. (optional)
Returns: A value for heading in the range that is specified by the units.

# get the current heading for the inertial sensor
value = imu1.heading()

installed(*args)

Check for device connection

Returns: True or False.

is_calibrating()

Check the calibration status of the inertial sensor. Calibration should done when the inertial sensor is not moving.

Returns: True when the inertial sensor is calibrating

# start calibration
imu1.calibrate()
# wait for completion
while imu1.is_calibrating():
    sleep(50, MSEC)

orientation(axis: OrientationType, units=DEG)

Read the orientation for one axis of the inertial sensor.

Parameters

axis – The axis to read.
units – The units to return the orientation in, default is DEGREES. (optional)

Returns

A value for the axis orientation in the units specified.

# get the pitch value for the inertial sensor
pitch = imu1.orientation(OrientationType.PITCH)

reset_heading(): Reset the inertial sensor heading to 0.

reset_rotation(): Reset the inertial sensor rotation to 0.

rotation(units=DEG)

Read the current rotation of the inertial sensor. Rotation is not limited, it can be both positive and negative and shows the absolute angle of the gps.

Parameters: units – The units to return the rotation in, default is DEGREES. (optional)
Returns: A value for heading in the range that is specified by the units.

# get the current rotation for the inertial sensor
value = imu1.rotation()

set_heading(value, units=DEG)

Set the inertial sensor heading to a new value. The new value for heading should be in the range 0 - 359.99 degrees.

Params value: The new value to use for heading.
Params units: The rotation units type for value, the default is DEGREES

# set the value of heading to 180 degrees
imu1.set_heading(180)

set_rotation(value, units=DEG)

Set the inertial sensor rotation to a new value.

Parameters

value – The new value to use for rotation.
units – The rotation units type for value, the default is DEGREES. (optional)

# set the value of rotation to 180 degrees
imu1.set_rotation(180)

set_turn_type(turntype)

Set the direction that returns positive values for heading. An advanced function that is not generally used.

Parameters: turntype – TurnType.LEFT or TurnType.RIGHT.

timestamp()

Request the timestanp of last received message from the sensor.

Returns: Timestamp of the last status packet in mS.

vex.LEFT = LEFT: A turn unit that is defined as left turning.

class vex.Led(port)

Bases: object

Led class - create a new led

led1 = Led(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the led.

off()

Turn the led off.

led1.off()

on()

Turn the led on.

led1.on()

type()

value()

The current value of the led.

Returns: 1 or 0.

class vex.LedStateType

Bases: object

The defined units for optical sensor led state.

class LedStateType(value, name)

Bases: vexEnum

LED state type.

OFF = OFF: Off.

ON = ON: On.

class vex.Light(port)

Bases: object

Light class - create a new light sensor.

light1 = Light(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the light sensor.

brightness(units=PERCENT)

The current brightness of light falling on the light sensor. The brightness of the light sensor is an estimation based on the raw value of the sensor. A brightness of 0% is a raw value of approximated 900 or greater. A brightness of 100% is a raw value of 0.

Parameters: units – The only valid value is PERCENT. (optional)
Returns: A value in the range 0 to 100%.

# get light sensor brightness in range of 0 -100%
value = light1.brightness()

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the light sensor changes.

Parameters

callback – A function that will be called when the value of the light sensor changes
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class

def foo():
     print("light sensor changed")

light1.changed(foo)

type()

value(units: ~typing.Union[~vex.AnalogUnits.AnalogUnits, ~vex.PercentUnits.PercentUnits] = 12BIT)

The current value of the light sensor.

Parameters: units – A valid AnalogUnits type or PERCENT, the default is 12 bit analog. (optional)
Returns: A value in the range that is specified by the units.

# get light sensor in range 0 - 4095
value = light1.value()

# get light sensor in range 0 - 1023
value = light1.value(AnalogUnits.TENBIT)

class vex.Limit(port: TriportPort)

Bases: object

Limit class - create a new limit switch.

limit1 = Limit(brain.three_wire_port.a)

__init__(port: TriportPort)

Ctor.

Parameters: port – The 3wire port the limit switch is connected to.

pressed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the limit switch is pressed.

Parameters

callback – A function that will be called when the limit switch is pressed.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("switch pressed")

limit1.pressed(foo)

pressing()

Returns whether the limit switch is currently being pressed.

Returns: True or False.

released(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the limit switch is released.

Parameters

callback – A function that will be called when the limit switch is released.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("switch released")

limit1.released(foo)

type()

value()

The current value of the limit switch

Returns: 1 or 0.

class vex.Line(port)

Bases: object

Line class - create a new line sensor.

line1 = Line(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the line sensor.

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the line sensor changes.

callback: A function that will be called when the value of the line sensor changes. arg: A tuple that is used to pass arguments to the callback function. (optional) :return: An instance of the Event class.

def foo():
     print("line sensor changed")

line1.changed(foo)

reflectivity(units=PERCENT)

The current reflectivity of the line sensor. The reflectivity of the line sensor is an estimation based on the raw value of the sensor. A reflectivity of 0% is a raw value of approximated 3000 or greater. A reflectivity of 100% is a raw value of 0.

Parameters: units – The only valid value is PERCENT. (optional)
Returns: A value in the range 0 to 100%.

# get line sensor reflectivity in range of 0 -100%
value = line1.reflectivity()

type()

value(units: ~typing.Union[~vex.AnalogUnits.AnalogUnits, ~vex.PercentUnits.PercentUnits] = 12BIT)

The current value of the line sensor.

Parameters: units – A valid AnalogUnits type or PERCENT, the default is 12 bit analog. (optional)
Returns: A value in the range that is specified by the units.

# get line sensor in range 0 - 4095
value = line1.value()

# get line sensor in range 0 - 1023
value = line1.value(AnalogUnits.TENBIT)

vex.MM = MM: A distance unit that is measured in millimeters.

vex.MSEC = MSEC: A time unit that is measured in milliseconds.

vex.MV = mV: A voltage unit that is measured in millivolts.

class vex.MessageLink(port, name: str, linktype: VexlinkType, wired=False)

Bases: object

MessageLink class - a class for communicating using VEXlink.

link = MessageLink(Ports.PORT1, 'james', VexlinkType.MANAGER)

__init__(port, name: str, linktype: VexlinkType, wired=False)

Ctor.

Parameters

port – The smartport the VEXlink radio is attached to.
name – The name of this link.
linktype – The type of this link, either VexlinkType.MANAGER or VexlinkType.WORKER.
wired – Set to True if this is a wired link. (optional)

installed()

Check for device connection.

Returns: True or False.

is_linked()

Return link status

Returns: True if the link is active and connected to the paired brain.

receive(timeout=300000)

Receive the next message.

Parameters: timeout – An optional timeout value in mS before the function returns. (optional)

message = link.receive()

received(*args)

Register a function to be called when a message is received. If the message is ommitted then the callback will be called for all messages.

Parameters

message – A message name for which the callback will be called. (optional)
callback – A function that will be called when a message is received.

def cb(message, link, index, value):
     print(link, message, index, value)

link.received('test', cb)

send(message: str, *args)

Send a message with optional parameters.

Parameters

message – A string, the message to send.
(optional) (value) – A int such as port number.
(optional) – A float.

Returns

length of transmitted data or None on error.

# send the message 'test' with no parameters
link.send('test')

# send the message 'test' with parameters
link.send('test', 1, 3.14)

class vex.Motor(port: int, *args)

Bases: object

Motor class - use this to create an instance of a V5 smart motor.

motor1 = Motor(Ports.PORT1)
motor2 = Motor(Ports.PORT2, GearSetting.RATIO_36_1)
motor3 = Motor(Ports.PORT3, True)
motor4 = Motor(Ports.PORT4, GearSetting.RATIO_6_1, True)

__init__(port: int, *args)

Ctor.

Parameters

port – The smartport this device is attached to
gears – The gear cartridge installed in the motor, default is the green 18_1. (optional)
reverse – Should the motor’s spin direction be reversed, default is False. (optional)

command(*args)

Returns the last velocity sent to the motor.

Parameters: units – The units for the returned velocity, the default is RPM. (optional)
Returns: The motor command velocity in provided units

current(*args)

Returns the current the motor is using.

Parameters: units – The units for the returned current, the default is AMP. (optional)
Returns: The motor current in provided units

direction()

Returns the current direction the motor is spinning in.

Returns: The spin direction, FORWARD, REVERSE or UNDEFINED.

efficiency(*args)

Returns the efficiency of the motor.

Parameters: units – The units for the efficiency, the only valid value is PERCENT. (optional)
Returns: The motor efficiency in percent.

get_timeout()

Returns the current value of motor timeout

Returns: The current timeout value.

installed()

Check for device connection.

Returns: True or False.

is_done()

Returns the current status of the spin_to_position or spin_for command. This function is used when False has been passed as the wait parameter to spin_to_position or spin_for. It will return False if the motor is still spinning or True if it has completed the move or a timeout occured.

Returns: The current spin_to_position or spin_for status.

is_spinning()

Returns the current status of the spin_to_position or spin_for command. This function is used when False has been passed as the wait parameter to spin_to_position or spin_for. It will return True if the motor is still spinning or False if it has completed the move or a timeout occured.

Returns: The current spin_to_position or spin_for status.

is_spinning_mode()

position(*args)

Returns the position of the motor.

Parameters: units – The units for the returned position, the default is DEGREES. (optional)
Returns: The motor position in provided units

power(*args)

Returns the power the motor is providing.

Parameters: units – The units for the returned power, the default is WATT. (optional)
Returns: The motor power in provided units.

reset_position(): Reset the motor position to 0.

set_max_torque(value, units: Union[TorqueUnits, PercentUnits, CurrentUnits])

Set the maximum torque the motor will use. The torque can be set as torque, current or percent of maximum.

Parameters

value – The new maximum torque to use.
units – The units that value is passed in.

# set maximum torque to 2 Nm
motor1.set_max_torque(2, TorqueUnits.NM)

# set maximum torque to 1 Amp
motor1.set_max_torque(1, CurrentUnits.AMP)

# set maximum torque to 20 percent
motor1.set_max_torque(20, PERCENT)

set_position(value: Union[int, float], units=DEG)

Set the current position of the motor. The position returned by the position() function is set to this value.

Parameters

value – The new position.
units – The units for the provided position, the default is DEGREES.

set_reversed(value: bool)

Set the reverse flag for the motor. Setting the reverse flag will cause spin commands to run the motor in reverse.

Parameters: value – Reverse flag, True or False.

set_stopping(value: BrakeType)

Set the stopping mode of the motor. Setting the action for the motor when stopped.

Parameters: value – The stopping mode, COAST, BRAKE or HOLD.

set_timeout(value: Union[int, float], units=MSEC)

Set the timeout value used by the motor. The timeout value is used when performing spin_to_position and spin_for commands. If timeout is reached and the motor has not completed moving, then the spin… function will return False.

Parameters

value – The new timeout.
units – The units for the provided timeout, the default is MSEC.

set_velocity(value: Union[int, float], units: Union[VelocityUnits, PercentUnits] = RPM)

Set default velocity for the motor. This will be the velocity used for subsequent calls to spin if a velocity is not provided to that function.

Parameters

value – The new velocity.
units – The units for the supplied velocity, the default is RPM.

spin(direction: DirectionType, *args, **kwargs)

Spin the motor using the provided arguments

Parameters

direction – The direction to spin the motor, FORWARD or REVERSE.
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units – The units of the provided velocity, default is RPM. (optional)

# spin motor forward at velocity set with set_velocity
motor1.spin(FORWARD)
# spin motor forward at 50 rpm
motor1.spin(FORWARD, 50)
# spin with negative velocity, ie. backwards
motor1.spin(FORWARD, -20)
# spin motor forwards with 100% velocity
motor1.spin(FORWARD, 100, PERCENT)
# spin motor forwards at 50 rpm
motor1.spin(FORWARD, 50, RPM)
# spin motor forwards at 360 dps
motor1.spin(FORWARD, 360.0, VelocityUnits.DPS)

spin_for(direction: DirectionType, rot_or_time: Union[int, float], *args, **kwargs)

Spin the motor to a relative position using the provided arguments. Move the motor to the requested position or for the specified amout of time. The position is relative (ie. an offset) to the current position. This function supports keyword arguments.

Parameters

dir – The direction to spin the motor, FORWARD or REVERSE
rot_or_time – The relative position to spin the motor to or tha amount of time to spin for
units – The units for the provided position or time, the default is DEGREES or MSEC. (optional)
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

# spin 180 degrees from the current position
motor1.spin_for(FORWARD, 180)
# spin reverse 2 TURNS (revolutions) from the current position
motor1.spin_for(REVERSE, 2, TURNS)
# spin 180 degrees from the current position at 25 rpm
motor1.spin_for(FORWARD, 180, DEGREES, 25, RPM)
# spin 180 degrees  from the current position and do not wait for completion
motor1.spin_for(FORWARD, 180, DEGREES, False)
# spin 180 degrees  from the current position and do not wait for completion
motor1.spin_for(FORWARD, 180, DEGREES, wait=False)

spin_to_position(rotation: Union[int, float], *args, **kwargs)

Spin the motor to an absolute position using the provided arguments. Move the motor to the requested position. This function supports keyword arguments.

Parameters

rotation – The position to spin the motor to.
units – The units for the provided position, the default is DEGREES. (optional)
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

# spin to 180 degrees
motor1.spin_to_position(180)

# spin to 2 TURNS (revolutions)
motor1.spin_to_position(2, TURNS) 

# spin to 180 degrees at 25 rpm
motor1.spin_to_position(180, DEGREES, 25, RPM)

# spin to 180 degrees and do not wait for completion
motor1.spin_to_position(180, DEGREES, False)

# spin to 180 degrees and do not wait for completion
motor1.spin_to_position(180, DEGREES, wait=False)

stop(mode=None): Stop the motor, set to 0 velocity and set current stopping_mode. The motor will be stopped and set to COAST, BRAKE or HOLD.

temperature(*args)

Returns the temperature of the motor.

Parameters: units – The units for the returned temperature, the default is CELCIUS. (optional)
Returns: The motor temperature in provided units.

timestamp()

Request the timestanp of last received message from the motor.

Returns: Timestamp of the last status packet in mS.

torque(*args)

Returns the torque the motor is providing.

Parameters: units – The units for the returned torque, the default is NM. (optional)
Returns: The motor torque in provided units.

velocity(*args)

Returns the velocity of the motor.

Parameters: units – The units for the returned velocity, the default is RPM. (optional)
Returns: The motor velocity in provided units.

class vex.Motor29(port, reverse_flag=False)

Bases: object

Motor29 class - create a new pwm motor output. The Motor29 class will create raw RC style pwm waveform. This is primarily for use with the VEX MC29 motor controller. To minimize current draw, new values sent to the motor will have slew rate control applied.

motor1 = Motor29(brain.three_wire_port.a)

__init__(port, reverse_flag=False)

Ctor.

Parameters

port – The 3wire port to use for the motor controller.
reverse_flag – set reverse flag for this motor, spin commands will cause opposite rotation if set True; default is False. (optional)

set_reversed(value)

Set the reversed flag for the motor.

Parameters: value – 1, 0, True or False.

# set motor reversed flag True
motor1.set_reversed(True)

set_velocity(value, units=RPM)

Set default velocity for the motor. This will be the velocity used for subsequent calls to spin of a velocity is not provided to that function.

Parameters

value – The new velocity.
units – The units for the supplied velocity, the default is RPM.

spin(direction: DirectionType, velocity=None, units=None)

Spin the motor using the provided arguments. The motor is assumed to have a maximum velocity of 100 rpm.

Parameters

direction – The direction to spin the motor, FORWARD or REVERSE.
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units – The units of the provided velocity, default is RPM. (optional)

# spin motor forward at velocity set with set_velocity
motor1.spin(FORWARD)
# spin motor forward at 50 rpm
motor1.spin(FORWARD, 50)
# spin with negative velocity, ie. backwards
motor1.spin(FORWARD, -20)
# spin motor forwards with 100% velocity
motor1.spin(FORWARD, 100, PERCENT)
# spin motor forwards at 50 rpm
motor1.spin(FORWARD, 50, RPM)
# spin motor forwards at 360 dps
motor1.spin(FORWARD, 360.0, VelocityUnits.DPS)

stop(): Stop the motor, set to 0 velocity.

type()

value()

Read the current raw motor controller pwm value. This is the raw internal pwm value. A motor velocity of 0 will return 127. A maximum positive motor velocity will return 255.

Returns: A value in the range 0 to 255.

# get motor current pwm value
value = motor1.value()

class vex.MotorGroup(*argv)

Bases: object

MotorGroup class - use this to create a group of motors

motor1 = Motor(Ports.PORT1)
motor2 = Motor(Ports.PORT2)
mg1 = MotorGroup(motor1, motor2)

__init__(*argv)

Ctor.

Parameters: argv – One or more Motor class instances.

count()

Return the number of motors in the group.

Returns: The number of motors in the group.

current(units=AMP)

Returns the total current all motors are using

Parameters: units – The units for the returned current, the default is AMP. (optional)
Returns: The motor current in provided units.

direction()

Returns the current direction the first motor is spinning in.

Returns: The spin direction, FORWARD, REVERSE or UNDEFINED

efficiency(units=PERCENT)

Returns the efficiency of the first motor.

Parameters: units – The units for the efficiency, the only valid value is PERCENT. (optional)
Returns: The motor efficiency in percent.

is_done()

Returns the current status of the spin_to_position or spin_for command. This function is used when False has been passed as the wait parameter to spin_to_position or spin_for. It will return False if any motor is still spinning or True if they have completed the move or a timeout occured.

Returns: The current spin_to_position or spin_for status.

is_spinning()

Returns the current status of the spin_to_position or spin_for command. This function is used when False has been passed as the wait parameter to spin_to_position or spin_for. It will return True if any motor is still spinning or False if they have completed the move or a timeout occured.

Returns: The current spin_to_position or spin_for status.

is_spinning_mode()

position(units=DEG)

Returns the position of the first motor.

Parameters: units – The units for the returned position, the default is DEGREES. (optional)
Returns: The motor position in provided units.

power(units=WATT)

Returns the power the first motor is providing.

Parameters: units – The units for the returned power, the default is WATT. (optional)
Returns: The motor power in provided units.

reset_position(): Reset the motor position to 0 for all motors in the group.

set_max_torque(value, units=NM)

Set the maximum torque all motors in the group will use. The torque can be set as torque, current or percent of maximum.

#### Arguments:

param value: The new maximum torque to use.
param units: The units that value is passed in.

# set maximum torque to 2 Nm
motor1.set_max_torque(2, TorqueUnits.NM)

# set maximum torque to 1 Amp
motor1.set_max_torque(1, CurrentUnits.AMP)

# set maximum torque to 20 percent
motor1.set_max_torque(20, PERCENT)

set_position(value, units=None)

Set the current position for all kotors in the group. The position returned by the position() function is set to this value.

Parameters

value – The new posiiton.
units – The units for the provided position, the default is DEGREES.

set_stopping(mode=COAST)

Set the stopping mode for all motors in the group. Setting the action for the motor when stopped.

Parameters: mode – The stopping mode, COAST, BRAKE or HOLD.

set_timeout(timeout, units=MSEC)

Set the timeout value used for all motors in the group. The timeout value is used when performing spin_to_position and spin_for commands. If timeout is reached and the motor has not completed moving, then the spin.

Parameters

timeout – The new timeout.
units – The units for the provided timeout, the default is MSEC.

set_velocity(velocity, units=None)

Set default velocity for all motors in the group. This will be the velocity used for subsequent calls to spin if a velocity is not provided to that function.

Parameters

velocity – The new velocity.
units – The units for the supplied velocity, the default is RPM.

spin(direction, velocity=None, units=RPM)

Spin all motors in the group using the provided arguments.

Parameters

direction – The direction to spin the motor, FORWARD or REVERSE
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units – The units of the provided velocity, default is RPM. (optional)

# spin motors forward at velocity set with set_velocity
mg1.spin(FORWARD)
# spin motors forward at 50 rpm
mg1.spin(FORWARD, 50)
# spin with negative velocity, ie. backwards
mg1.spin(FORWARD, -20)
# spin motors forwards with 100% velocity
mg1.spin(FORWARD, 100, PERCENT)
# spin motors forwards at 50 rpm
mg1.spin(FORWARD, 50, RPM)
# spin motors forwards at 360 dps
mg1.spin(FORWARD, 360.0, VelocityUnits.DPS)

spin_for(direction, rotation, units=DEG, velocity=None, units_v=RPM, wait=True)

Spin all motors in the group to a relative position using the provided arguments. Move the motor to the requested position or for the specified amout of time. The position is relative (ie. an offset) to the current position. This function supports keyword arguments.

Parameters

direction – The direction to spin the motor, FORWARD or REVERSE.
rotation – The relative position to spin the motor to or tha amount of time to spin for.
units – The units for the provided position or time, the default is DEGREES or MSEC. (optional)
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

# spin 180 degrees from the current position
mg1.spin_for(FORWARD, 180)

# spin reverse 2 TURNS (revolutions) from the current position
mg1.spin_for(REVERSE, 2, TURNS)

# spin 180 degrees from the current position at 25 rpm
mg1.spin_for(FORWARD, 180, DEGREES, 25, RPM)

# spin 180 degrees  from the current position and do not wait for completion
mg1.spin_for(FORWARD, 180, DEGREES, False)

# spin 180 degrees  from the current position and do not wait for completion
mg1.spin_for(FORWARD, 180, DEGREES, wait=False)

spin_to_position(rotation, units=DEG, velocity=None, units_v=RPM, wait=True)

Spin all motors in the group to an absolute position using the provided arguments. Move the motor to the requested position. This function supports keyword arguments.

Parameters

rotation – The position to spin the motor to
units – The units for the provided position, the default is DEGREES. (optional)
velocity – Spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

# spin to 180 degrees
mg1.spin_to_position(180)
# spin to 2 TURNS (revolutions)
mg1.spin_to_position(2, TURNS) 
# spin to 180 degrees at 25 rpm
mg1.spin_to_position(180, DEGREES, 25, RPM)
# spin to 180 degrees and do not wait for completion
mg1.spin_to_position(180, DEGREES, False)
# spin to 180 degrees and do not wait for completion
mg1.spin_to_position(180, DEGREES, wait=False)

stop(mode=None): Stop all motors in the group, set to 0 velocity and set current stopping_mode. The motor will be stopped and set to COAST, BRAKE or HOLD.

temperature(units=CELSIUS)

Returns the temperature of the first motor.

Parameters: units – The units for the returned temperature, the default is CELCIUS. (optional)
Returns: The motor torque in provided units.

torque(units=NM)

Returns the torque the first motor is providing.

Parameters: units – The units for the returned torque, the default is NM. (optional)
Returns: The motor torque in provided units.

velocity(units=RPM)

Returns the velocity of the first motor.

Parameters: units – The units for the returned velocity, the default is RPM. (optional)
Returns: The motor velocity in provided units.

class vex.MotorVictor(port, reverse_flag=False)

Bases: object

MotorVictor class - create a new pwm motor output. The MotorVictor class will create raw RC style pwm waveform. This is primarily for use with the VEX Victor motor controller

Parameters

port – The 3wire port to use for the motor controller
reverse_flag – set reverse flag for this motor, spin commands will cause opposite rotation if set True; default is False. (optional)

Returns

An instance of the MotorVictor class

motor1 = MotorVictor(brain.three_wire_port.a)

__init__(port, reverse_flag=False)

set_reversed(value)

Set the reveraed flag for the motor.

Parameters: value – 1, 0, True or False.

# set motor reversed flag True
motor1.set_reversed(True)

set_velocity(value, units=RPM)

Set default velocity for the motor. This will be the velocity used for subsequent calls to spin of a velocity is not provided to that function.

Parameters

value – The new velocity.
units – The units for the supplied velocity, the default is RPM.

spin(direction, velocity=None, units=None)

Spin the motor using the provided arguments. The motor is assumed to have a maximum velocity of 100 rpm.

Parameters

direction – The direction to spin the motor, FORWARD or REVERSE.
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units – The units of the provided velocity, default is RPM. (optional)

# spin motor forward at velocity set with set_velocity
motor1.spin(FORWARD)
# spin motor forward at 50 rpm
motor1.spin(FORWARD, 50)
# spin with negative velocity, ie. backwards
motor1.spin(FORWARD, -20)
# spin motor forwards with 100% velocity
motor1.spin(FORWARD, 100, PERCENT)
# spin motor forwards at 50 rpm
motor1.spin(FORWARD, 50, RPM)
# spin motor forwards at 360 dps
motor1.spin(FORWARD, 360.0, VelocityUnits.DPS)

stop(): Stop the motor, set to 0 velocity.

type()

value()

Read the current raw motor controller pwm value. This is the raw internal pwm value. A motor velocity of 0 will return 127. A maximum positive motor velocity will return 255.

Returns: A value in the range 0 to 255.

# get motor current pwm value
value = motor1.value()

class vex.ObjectSizeType

Bases: object

The defined units for distance sensor object size.

LARGE = LARGE: Large.

MEDIUM = MEDIUM: Medium.

NONE = NONE: None.

class ObjectSizeType(value, name)

Bases: vexEnum

Object size type.

SMALL = SMALL: Small.

class vex.Optical(port)

Bases: object

Optical class - a class for working with the optical sensor.

opt1 = Optical(Ports.PORT1)

class Gesture

Bases: object

__init__()

__init__(port)

Ctor.

Parameters: port – The smartport this device is attached to.

brightness(readraw=False)

Read the brightness value from the optical sensor.

Parameters: readraw – return raw brightness value if True rather than percentage. (optional)
Returns: brightness as a float in the range 0 - 100%.

brightness = opt1.brightness()

color()

Read the color from the optical sensor.

Returns: Color as an instance of the Color class.

c = opt1.color()

gesture_disable()

Disable gesture mode.

opt1.gesture_disable()

gesture_down(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when a gesture down event is detected. Gesture must be enabled for events to fire.

Parameters

callback – A function that will be called when a gesture down event is detected.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("down detected")

opt1.gesture_down(foo)

gesture_enable()

Enable gesture mode.

opt1.gesture_enable()

gesture_left(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when a gesture left event is detected. Gesture must be enabled for events to fire.

Parameters

callback – A function that will be called when a gesture left event is detected.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("left detected")

opt1.gesture_left(foo)

gesture_right(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when a gesture right event is detected. Gesture must be enabled for events to fire.

Parameters

callback – A function that will be called when a gesture right event is detected.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("right detected")

opt1.gesture_right(foo)

gesture_up(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when a gesture up event is detected. Gesture must be enabled for events to fire.

Parameters

callback – A function that will be called when a gesture up event is detected.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("up detected")

opt1.gesture_up(foo)

get_gesture(newobject=False)

Get gesture data.

Parameters: newobject – create a new Gesture object to return data in. (optional)
Returns: An object with the last gesture data.

opt1.gesture_disable()

hue()

Read the hue value from the optical sensor.

Returns: Jue as a float in the range 0 - 359.99 degrees

hue = opt1.hue()

installed()

Check for device connection.

Returns: True or False.

is_near_object()

Check to see if the optical proximity sensor detects an object.

Returns: True if near an object.

if opt1.is_near_object():
    print('near object')

object_detect_threshold(value: Union[int, float])

Set the threshold for object detection.

Parameters: value – Number in the range 0 to 255. A value of 0 will just return current value.
Returns: current value

opt1.object_detect_threshold(100)

object_detected(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when an object detected event occurs.

Parameters

callback – A function that will be called when an object detected event occurs
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("object detected")

opt1.object_detected(foo)

object_lost(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when an object lost event occurs

Parameters

callback – A function that will be called when an object lost event occurs.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("object lost")

opt1.object_lost(foo)

set_light(*args)

Set optical sensor led on or off.

Parameters: value – LedStateType.ON, LedStateType.OFF or power of led, 0 to 100%.

# turn on led with previous intensity
opt1.set_light(LedStateType.ON)

# turn on led with new intensity
opt1.set_light(65)

set_light_power(value: Union[int, float])

Set optical sensor led to the requested power.

Parameters: value – Power of led, 0 to 100%.

opt1.set_light_power(50)

timestamp()

Request the timestanp of last received message from the sensor.

Returns: Timestamp of the last status packet in mS.

class vex.OrientationType

Bases: object

The defined units for inertial sensor orientation.

class OrientationType(value, name)

Bases: vexEnum

Orientation type.

PITCH = PITCH: Pitch, orientation around the Y axis of the Inertial sensor.

ROLL = ROLL: Roll, orientation around the X axis of the Inertial sensor.

YAW = YAW: Yaw, orientation around the Z axis of the Inertial sensor.

vex.PARTNER = PARTNER: A controller defined as a partner controller.

vex.PERCENT = PERCENT: A percentage unit that represents a value from 0% to 100%.

vex.PITCH = PITCH: Pitch, orientation around the Y axis of the Inertial sensor.

vex.PRIMARY = PRIMARY: A controller defined as a primary controller.

class vex.PercentUnits

Bases: object

The measurement units for percentage values.

PERCENT = PERCENT: A percentage unit that represents a value from 0% to 100%.

class PercentUnits(value, name)

Bases: vexEnum

Percent units.

class vex.Pneumatics(port)

Bases: object

Pneumatics class - create a new pneumatics driver class.

p1 = Pneumatics(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the pneumatics.

close()

Set the pneumatics driver to the close state.

p1.close()

open()

Set the pneumatics driver to the open state.

p1.open()

type()

value()

The current state of the pneumatics driver

Returns: 1 or 0.

class vex.Ports

Bases: object

Smartport definitions

PORT1 = 0: Port 0

PORT10 = 9: Port 10

PORT11 = 10: Port 11

PORT2 = 1: Port 1

PORT3 = 2: Port 2

PORT4 = 3: Port 3

PORT5 = 4: Port 4

PORT6 = 5: Port 5

PORT7 = 6: Port 6

PORT8 = 7: Port 8

PORT9 = 8: Port 9

class vex.Potentiometer(port)

Bases: object

Potentiometer class - create a new potentiometer.

pot1 = Potentiometer(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the potentiometer.

angle(units: Union[RotationUnits, PercentUnits] = DEG)

The current angle of the potentiometer.

Parameters: units – A valid RotationUnits type or PERCENT, the default is DEGREES. (optional)
Returns: A value in the range that is specified by the units.

# get potentiometer in range 0 - 250 degrees
angle = pot1.angle()

# get potentiometer in range 0 - 100%
angle = pot1.angle(PERCENT)

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the potentiometer changes.

Parameters

callback – A function that will be called when the value of the potentiometer changes.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
     print("pot changed")

pot1.changed(foo)

type()

value(units: ~typing.Union[~vex.AnalogUnits.AnalogUnits, ~vex.PercentUnits.PercentUnits] = 12BIT)

The current value of the potentiometer.

Parameters: units – A valid AnalogUnits type or PERCENT, the default is 12 bit analog. (optional)
Returns: A value in the range that is specified by the units.

# get potentiometer in range 0 - 4095
value = pot1.value()

# get potentiometer in range 0 - 1023
value = pot1.value(AnalogUnits.TENBIT)

class vex.PotentiometerV2(port)

Bases: object

PotentiometerV2 class - create a new potentiometer.

Parameters: port – The 3wire port to use for the potentiometer
Returns: An instance of the PotentiometerV2 class.

pot1 = PotentiometerV2(brain.three_wire_port.a)

__init__(port)

angle(units: Union[RotationUnits, PercentUnits] = DEG)

The current angle of the potentiometer

Parameters: units – A valid RotationUnits type or PERCENT, the default is DEGREES. (optional)
Returns: A value in the range that is specified by the units.

# get potentiometer in range 0 - 250 degrees
angle = pot1.angle()

# get potentiometer in range 0 - 100%
angle = pot1.angle(PERCENT)

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the potentiometer changes.

Parameters

callback – A function that will be called when the value of the potentiometer changes
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class

def foo():
     print("pot changed")

pot1.changed(foo)

type()

value(units: ~typing.Union[~vex.AnalogUnits.AnalogUnits, ~vex.PercentUnits.PercentUnits] = 12BIT)

The current value of the potentiometer.

Parameters: units – A valid AnalogUnits type or PERCENT, the default is 12 bit analog. (optional)
Returns: A value in the range that is specified by the units.

# get potentiometer in range 0 - 4095
value = pot1.value()

# get potentiometer in range 0 - 1023
value = pot1.value(AnalogUnits.TENBIT)

class vex.PowerUnits

Bases: object

The measurement units for power values.

class PowerUnits(value, name)

Bases: vexEnum

Power units.

WATT = WATT: A power unit that is measured in watts.

class vex.Pwm(port)

Bases: object

Pwm class - create a new pwm output. The pwm class will create raw RC style pwm waveform.

A pwm output of 0% corresponds to pulse width of 1.5mS every 16mS
A pwm output of 100% corresponds to pulse width of 2mS
A pwm output of -100% corresponds to pulse width of 1mS

pwm1 = Pwm(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the pwm output.

state(value, units=PERCENT)

Set the current PWM value in percent.

Parameters

value – The new value for pwm output, -100 to +100 percent.
units – units must be specified in PERCENT. (optional)

# set pwm1 output to 50%
pwm1.state(50)

type()

value()

Read the current PWM value in percent.

Returns: A value in the range -100 to +100 percent.

# get pwm1 current value
value = pwm1.value()

vex.REVERSE = REVERSE: A direction unit that is defined as backward.

vex.RIGHT = LEFT: A turn unit that is defined as right turning.

vex.ROLL = ROLL: Roll, orientation around the X axis of the Inertial sensor.

vex.RPM = RPM: A velocity unit that is measured in rotations per minute.

class vex.Rotation(port, reverse=False)

Bases: object

Rotation class - a class for working with the rotation sensor.

rot1 = Rotation(Ports.PORT1)
rot2 = Rotation(Ports.PORT2, True)

__init__(port, reverse=False)

Ctor.

Parameters

port – The smartport this device is attached to.
reverse – set to reverse the angle and position returned by the sensor. (optional)

angle(units=DEG)

The current angle of the rotation sensor.

Parameters: units – A valid RotationUnits type, the default is DEGREES. (optional)
Returns: A value in the range that is specified by the units.

# get rotation sensor angle
angle = rot1.angle()

changed(callback: Callable[[...], None], arg: tuple = ())

Register a function to be called when the value of the rotation sensor changes

Parameters

callback – A function that will be called when the value of the rotation sensor changes.
arg – A tuple that is used to pass arguments to the callback function. (optional)

Returns

An instance of the Event class.

def foo():
    print("rotation changed")

rot1.changed(foo)

installed()

Check for device connection.

Returns: True or False.

position(units=DEG)

Returns the position of the rotation sensor. The position is an absolute value that continues to increase or decrease as the sensor is rotated.

Parameters: units – The units for the returned position, the default is DEGREES. (optional)
Returns: The rotation sensor in provided units.

reset_position(): Reset the rotation sensor position to 0.

set_position(value, units=DEG)

Set the current position of the rotation sensor. The position returned by the position() function is set to this value. The position is an absolute value that continues to increase or decrease as the sensor is rotated.

Parameters

value – The new posiiton.
units – The units for the provided position, the default is DEGREES.

set_reversed(value)

Set the reveraed flag for the sensor. Usually this would be done in the constructor.

Parameters: value – 1, 0, True or False.

# set reversed flag True
rot1.set_reversed(True)

timestamp()

Request the timestanp of last received message from the sensor.

Returns: Timestamp of the last status packet in mS.

velocity(units=RPM)

Returns the velocity of the rotation sensor.

Parameters: units – The units for the returned velocity, the default is RPM. (optional)
Returns: The rotation sensor velocity in provided units.

class vex.RotationUnits

Bases: object

The measurement units for rotation values.

DEG = DEG: A rotation unit that is measured in degrees.

RAW = RAW: A rotation unit that is measured in raw data form.

REV = REV: A rotation unit that is measured in revolutions.

class RotationUnits(value, name)

Bases: vexEnum

Rotation units.

vex.SECONDS = SECONDS: A time unit that is measured in seconds.

class vex.SerialLink(port, name: str, linktype: VexlinkType, wired=False)

Bases: object

SerialLink class - a class for communicating using VEXlink.

link = SerialLink(Ports.PORT1, 'james', VexlinkType.MANAGER)

__init__(port, name: str, linktype: VexlinkType, wired=False)

Ctor.

Parameters

port – The smartport the VEXlink radio is attached to.
name – The name of this link.
linktype – The type of this link, either VexlinkType.MANAGER or VexlinkType.WORKER.
wired – Set to True if this is a wired link. (optional)

installed()

Check for device connection.

Returns: True or False.

is_linked()

Return link status.

Returns: True if the link is active and connected to the paired brain.

receive(length, timeout=300000)

Receive data in the serial link.

Parameters

length – maximum amount of data to wait for
timeout – An optional timeout value in mS before the function returns. (optional)

# wait for 128 bytes of data for 1000mS
buffer = link.receive(128, 1000)

received(callback: Callable[[...], None])

Register a function to be called when data is received. This will receive a bytearray and a length indicating how much.

Parameters: callback – A function that will be called when data is received

def cb(buffer, length):
     print(buffer, length)

link.received(cb)

send(buffer)

Send a buffer of length length

Parameters: buffer – A string or bytearray, the message to send.

# send the string 'test'
link.send('test')

# send the bytearray 'test' with parameters
link.send('test', 1, 3.14)

class vex.Servo(port)

Bases: object

Servo class - create a new servo output. The Servo class will create raw RC style pwm waveform.

An output of 0 corresponds to pulse width of 1.5mS every 16mS
An output of 50 degrees corresponds to pulse width of 2mS
An output of -50 degrees corresponds to pulse width of 1mS

servo1 = Servo(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the servo output.

set_position(value, units: Union[RotationUnits, PercentUnits] = DEG)

Set the servo position.

Parameters

value – The new value for the servo using the supplied units.
units – The rotation units, default is PERCENT. (optional)

# set servo output to 10 degrees
servo1.set_position(10, DEGREES)

type()

value()

Read the current raw servo pwm value. This is the raw internal pwm value. A servo position of 0 will return 127. A maximum positive servo position will return 255.

Returns: A value in the range 0 to 255.

# get servo1 current value
value = servo1.value()

class vex.Signature(index, p0, p1, p2, p3, p4, p5, sigrange, sigtype)

Bases: object

Signature class - a class for holding vision sensor signatures.

SIG_1 = Signature(1, 6035, 7111, 6572, -1345, -475, -910, 3.000, 0)
vision1 = Vision(Ports.PORT1, 50, SIG_1)

__init__(index, p0, p1, p2, p3, p4, p5, sigrange, sigtype)

Ctor.

Parameters

index – The signature index.
p0 – signature value p0.
p1 – signature value p1.
p2 – signature value p2.
p3 – signature value p3.
p4 – signature value p4.
p5 – signature value p5.
sigrange – signature range.
sigtype – signature type.

id(): Not used, always returns 0.

class vex.SmartDrive(lm, rm, g, wheelTravel: Union[int, float] = 300, trackWidth: Union[int, float] = 320, wheelBase: Union[int, float] = 320, units=MM, externalGearRatio=1.0)

Bases: DriveTrain

SmartDrive class - use this to create a smart drivetrain. A smart drivetrain uses a gyro or similar sensor to turn more accurately. The smartdrive inherits all drivetrain functions.

# A simple two motor smart drivetrain using default values
motor1 = Motor(Ports.PORT1)
motor2 = Motor(Ports.PORT2, True)
imu1 = Inertial()
smart1 = SmartDrive(motor1, motor2, imu1)

# A four motor smart drivetrain using custom values
motor1 = Motor(Ports.PORT1)
motor2 = Motor(Ports.PORT2)
motor3 = Motor(Ports.PORT3, True)
motor4 = Motor(Ports.PORT4, True)
imu1 = Inertial()
mgl = MotorGroup(motor1, motor3)
mgr = MotorGroup(motor2, motor4)
smart1 = SmartDrive(mgl, mgr, imu1, 8.6, 10, 12, INCHES)

__init__(lm, rm, g, wheelTravel: Union[int, float] = 300, trackWidth: Union[int, float] = 320, wheelBase: Union[int, float] = 320, units=MM, externalGearRatio=1.0)

Parameters

lm – Left motor or motorgroup
rm – Right motor or motorgroup
g – The gyro, inertial sensor or gps to use for turns
wheelTravel – The circumference of the driven wheels, default is 300 mm. (optional)
trackWidth – The trackwidth of the drivetrain, default is 320 mm. (optional)
wheelBase – The wheelBase of the drivetrain, default is 320 mm. (optional)
units – The units that wheelTravel, trackWidth and wheelBase are specified in, default is MM. (optional)
externalGearRatio – An optional gear ratio used to compensate drive distances if gearing is used. (optional)

heading(units=DEG)

Read the current heading of the smartdrive. Heading will be returned in the range 0 - 359.99 degrees.

Parameters: units – The units to return the heading in, default is DEGREES. (optional)
Returns: A value for heading in the range that is specified by the units.

# get the current heading for the smartdrive
value = smart1.heading()

is_moving()

Returns the current status of the drive_for command. This function is used when False has been passed as the wait parameter to drive_for. It will return True if the drivetrain is still moving or False if it has completed the move or a timeout occured.

Returns: The current drive_for status.

is_turning()

Returns the current status of the turn_to_heading, turn_to_rotation or turn_for command. This function is used when False has been passed as the wait parameter to turn_to_heading or turn_for. It will return True if the drivetrain is still moving or False if it has completed the move or a timeout occured.

Returns: The current turn_to_heading, turn_to_rotation or turn_for status.

rotation(units=DEG)

Read the current rotation of the smartdrive. Rotation is not limited, it can be both positive and negative and shows the absolute angle of the gyro.

Parameters: units – The units to return the rotation in, default is DEGREES. (optional)
Returns: A value for heading in the range that is specified by the units.

# get the current rotation for the smartdrive
value = smart1.rotation()

set_heading(value, units=DEG)

Set the smartdrive heading to a new value. The new value for heading should be in the range 0 - 359.99 degrees.

Parameters

value – The new value to use for heading.
units – The rotation units type for value, the default is DEGREES. (optional)

# set the value of heading to 180 degrees
smart1.set_heading(180)

set_rotation(value, units=DEG)

Set the smartdrive rotation to a new value.

Parameters

value – The new value to use for rotation.
units – The rotation units type for value, the default is DEGREES. (optional)

# set the value of rotation to 180 degrees
smart1.set_rotation(180)

set_turn_constant(value)

Set the turning constant for the smartdrive. The smartdrive uses a simple P controller when doing turns. This constant, generally known as kp, is the gain used in the equation that turns angular error into motor velocity.

Parameters: value – The new turn constant in the range 0.1 - 4.0, the default is 1.0.

set_turn_direction_reverse(value)

Set the expected turn direction for positive heading change.

Parameters: value – True or False.

set_turn_threshold(value)

Set the turning threshold for the smartdrive. This is the threshold value used to determine that turns are complete. If this is too large then turns will not be accurate, if too small then turns are not complete.

Parameters: value – The new turn threshold in degrees, the default for a smartdrive is 1 degree.

turn_for(direction, angle, units=DEG, velocity=None, units_v=RPM, wait=True)

Turn the smartdrive using the provided arguments. The turn_for command is similar to the motor spin_for command, however, the smartdrive is commanded to turn a specified angle.

Parameters

direction – The direction to turn, LEFT or RIGHT.
angle – The angle to turn.
units – The units for the provided angle, the default is DEGREES. (optional)
velocity – drive using this velocity, the default velocity set by set_drive_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

Returns

None or if wait is True then completion success or failure.

# turn right 90 degrees
smart1.turn_for(RIGHT, 90, DEGREES)
# turn left 180 degrees with motors at 50 rpm
smart1.turn_for(LEFT, 180, DEGREES, 50, RPM)

turn_to_heading(angle, units=DEG, velocity=None, units_v=RPM, wait=True)

Turn the smartdrive to an absolute position using the provided arguments. The turn_to_heading command is similar to the motor spin_to_position command, however, the smartdrive is commanded to turn to a specified angle. This function uses the value of heading() when turning the smartdrive. This function supports keyword arguments.

Parameters

angle – The angle to turn to
units – The units for the provided angle, the default is DEGREES. (optional)
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

# turn to heading 180 degrees
smart1.turn_to_heading(180)

# turn to heading 180 degrees at 25 rpm
smart1.turn_to_heading(180, DEGREES, 25, RPM)

# turn to heading 180 degrees and do not wait for completion
smart1.turn_to_heading(180, DEGREES, False)

# turn to heading 180 degrees and do not wait for completion
smart1.turn_to_heading(180, DEGREES, wait=False)

turn_to_rotation(angle, units=DEG, velocity=None, units_v=RPM, wait=True)

Turn the smartdrive to an absolute position using the provided arguments. The turn_to_rotation command is similar to the motor spin_to_position command, however, the smartdrive is commanded to turn to a specified angle. This function uses the value of rotation() when turning the smartdrive. This function supports keyword arguments.

Parameters

angle – The angle to turn to
units – The units for the provided angle, the default is DEGREES. (optional)
velocity – spin the motor using this velocity, the default velocity set by set_velocity will be used if not provided. (optional)
units_v – The units of the provided velocity, default is RPM. (optional)
wait – This indicates if the function should wait for the command to complete or return immeadiately, default is True. (optional)

# turn to rotation 180 degrees
smart1.turn_to_rotation(180)
# turn to rotation 400 degrees at 25 rpm
smart1.turn_to_rotation(400, DEGREES, 25, RPM)
# turn to rotation 180 degrees and do not wait for completion
smart1.turn_to_rotation(180, DEGREES, False)
# turn to rotation 180 degrees and do not wait for completion
smart1.turn_to_rotation(180, DEGREES, wait=False)

class vex.Sonar(port)

Bases: object

Sonar class - create a new sonar (ultrasonic) sensor. A sonar uses two adjacent 3wire ports. Valid port pairs are a/b, c/d, e/f and g/h. Connect the wire labeled “output” to the lower 3wire port, eg. a

sonar1 = Sonar(brain.three_wire_port.a)

__init__(port)

Ctor.

Parameters: port – The 3wire port to use for the sonar sensor.

distance(units: DistanceUnits)

The current distance the sonar is detecting an object at. The sonar will return a large positive number if no object is detected in range.

Parameters: units – The distance units to return the position value in.
Returns: A value for sonar distance in the specified units.

# get sonar distance in mm
value = sonar1.distance(MM)

found_object()

Check for an object in the range 0 - 1000mm. The sonar will return True if an object is detected closer than 1000mm.

Returns: True of an object is detected.

# is an object closer than 1000mm
if sonar1.found_object():
    print("object found")

type()

value(units: ~typing.Union[~vex.AnalogUnits.AnalogUnits, ~vex.PercentUnits.PercentUnits] = 12BIT)

The current value of the sonar. This method has no practical use, see distance.

Parameters: units – A valid AnalogUnits type or PERCENT, the default is 12 bit analog. (optional)
Returns: A value in the range that is specified by the units.

# get sonar raw value
value = sonar1.value()

class vex.SoundType

Bases: object

Sound type.

ALARM = ALARM: Alarm.

ALARM2 = ALARM2: Alarm 2.

DOOR_CLOSE = DOOR_CLOSE: Door close.

FILLUP = FILLUP: Fillup.

HEADLIGHTS_OFF = HEADLIGHTS_OFF: Headlights off.

HEADLIGHTS_ON = HEADLIGHTS_ON: Headlights on.

POWER_DOWN = POWER_DOWN: Power down.

RATCHET = RATCHET: Ratchet.

RATCHET2 = RATCHET2: Ratchet 2.

SIREN = SIREN: Siren.

SIREN2 = SIREN2: Siren 2.

class SoundType(value, name)

Bases: vexEnum

Sound type.

TADA = TADA: Tada.

TOLLBOOTH = TOLLBOOTH: Tollbooth.

WRENCH = WRENCH: Wrench.

WRONG_WAY = WRONG_WAY: Wrong way.

WRONG_WAY_SLOW = WRONG_WAY_SLOW: Wrong way slow.

vex.TURNS = REV: A rotation unit that is measured in revolutions.

class vex.TemperatureUnits

Bases: object

The measurement units for temperature values.

CELSIUS = CELSIUS: A temperature unit that is measured in celsius.

FAHRENHEIT = FAHRENHEIT: A temperature unit that is measured in fahrenheit.

class TemperatureUnits(value, name)

Bases: vexEnum

Temperature units.

class vex.Thread(callback: Callable[[...], None], arg: tuple = ())

Bases: object

Thread class - create a new thread of execution. This class is used to create a new thread using the vexos scheduler.

def foo():
     print('the callback was called')

t1 = Thread( foo )

def bar(p1, p2):
     print('the callback was called with ', p1, ' and ', p2)

t2 = Thread( bar, (1,2) )

__init__(callback: Callable[[...], None], arg: tuple = ())

Ctor.

Parameters

callback – A function used as the entry point for the thread.
arg – A tuple that is used to pass arguments to the thread entry function. (optional)

static sleep_for(duration: Union[int, float], units=MSEC)

Sleep a thread.

Parameters

duration – time to sleep this thread for.
units – units of time, default is MSEC. (optional)

stop(): Stop a thread

class vex.ThreeWireType

Bases: object

The defined units for 3-wire devices.

ACCELEROMETER = ACCELEROMETER: A 3-wire sensor that is defined as a accelerometer.

ANALOG_IN = ANALOG_IN: A 3-wire sensor that is defined as an analog input.

ANALOG_OUT = ANALOG_OUT: A 3-wire sensor that is defined as an analog output.

DIGITAL_IN = DIGITAL_IN: A 3-wire sensor that is defined as an digital input.

DIGITAL_OUT = DIGITAL_OUT: A 3-wire sensor that is defined as an digital output.

ENCODER = ENCODER: A 3-wire sensor that is defined as a quadrature encoder.

GYRO = GYRO: A 3-wire sensor that is defined as a yaw rate gyro.

LIGHT_SENSOR = LIGHT_SENSOR: A 3-wire sensor that is defined as a light sensor.

LINE_SENSOR = LINE_SENSOR: A 3-wire sensor that is defined as a line sensor.

MOTOR = MOTOR: A 3-wire sensor that is defined as a legacy vex motor.

POTENTIOMETER = POT: A 3-wire sensor that is defined as a potentiometer.

SERVO = SERVO: A 3-wire sensor that is defined as a legacy vex servo.

SLEW_MOTOR = SLEW_MOTOR: A 3-wire sensor that is defined as a legacy vex motor using slew rate control.

SONAR = SONAR: A 3-wire sensor that is defined as an untrasonic sensor (sonar).

SWITCH = BUTTON: A 3-wire sensor that is defined as a switch.

class ThreeWireType(value, name)

Bases: vexEnum

Three wire type;

class vex.TimeUnits

Bases: object

The measurement units for time values.

MSEC = MSEC: A time unit that is measured in milliseconds.

SEC = SECONDS: A time unit that is measured in seconds.

SECONDS = SECONDS: A time unit that is measured in seconds.

class TimeUnits(value, name)

Bases: vexEnum

Time units.

class vex.Timer

Bases: object

Timer class - create a new timer. This class is used to create a new timer. A timer can be used to measure time, access the system time and run a funtion at a time in the future.

t1 = Timer()

__init__()

clear(): Reset the timer to 0.

event(callback: Callable[[...], None], delay: int, arg: tuple = ())

Register a function to be called in the future.

Parameters

callback – A function that will called after the supplied delay.
delay – The delay before the callback function is called.
arg – A tuple that is used to pass arguments to the function. (optional)

def foo(arg):
     print('timer has expired ', arg)

t1 = Timer()
t1.event(foo, 1000, ('Hello',))

reset(): Reset the timer to 0.

system()

Return the system time in mS.

Returns: System time in mS.

system_high_res()

Return the high resolution system time in uS.

Returns: System time in uS.

time(units=MSEC)

Return the current time for this timer.

Parameters: units – the units that the time shound be returned in, default is MSEC. (optional)
Returns: An the current time in specified units.

value()

Return the current time for this timer in seconds.

Returns: An the current time in seconds.

class vex.TorqueUnits

Bases: object

The measurement units for torque values.

INLB = INLB: A torque unit that is measured in Inch Pounds.

NM = NM: A torque unit that is measured in Newton Meters.

class TorqueUnits(value, name)

Bases: vexEnum

Torque units.

class vex.Triport(port)

Bases: object

class TriportPort(port, index)

Bases: object

__init__(port, index)

changed(callback: Callable[[...], None], arg: tuple = ())

pressed(callback: Callable[[...], None], arg: tuple = ())

released(callback: Callable[[...], None], arg: tuple = ())

type(*args)

value(*args)

__init__(port)

index()

installed()

Check for device connection.

Returns: True or False.

timestamp()

Request the timestamp of last received message from the sensor.

Returns: Timestamp of the last status packet in mS.

class vex.TurnType(value, name)

Bases: vexEnum

The defined units for turn values.

LEFT = LEFT: A turn unit that is defined as left turning.

RIGHT = RIGHT: A turn unit that is defined as right turning.

class TurnType(value, name)

Bases: vexEnum

Turn type.

UNDEFINED = UNDEFINED: A turn unit unit used when direction is not known.

vex.VOLT = VOLT: A voltage unit that is measured in volts.

class vex.VelocityUnits

Bases: object

The measurement units for velocity values.

DPS = DPS: A velocity unit that is measured in degrees per second.

PERCENT = PCT: A velocity unit that is measured in percentage.

RPM = RPM: A velocity unit that is measured in rotations per minute.

class VelocityUnits(value, name)

Bases: vexEnum

Velocity units.

class vex.VexlinkType

Bases: object

The defined units for vexlink types.

GENERIC = GENERIC: A vexlink type that is defined as a raw unmanaged link.

MANAGER = MANAGER: A vexlink type that is defined as the manager radio.

class VexlinkType(value, name)

Bases: vexEnum

Vex link type.

WORKER = WORKER: A vexlink type that is defined as the worker radio.

class vex.Vision(port, *args)

Bases: object

Vision class - a class for working with the vision sensor.

SIG_1 = Signature(1, 6035, 7111, 6572, -1345, -475, -910, 3.000, 0)
vision1 = Vision(Ports.PORT1, 50, SIG_1)

__init__(port, *args)

Ctor.

Parameters

port – The smartport this device is attached to.
brightness – Set the brightness value for the vision sensor. (optional)
sigs – One or more signature objects. (optional)

installed()

Check for device connection.

Returns: True or False.

largest_object()

take_snapshot(index, count=1)

Request the vision sensor to filter latest objects to match signature or code.

Parameters

index – A signature, code or signature id.
count – the maximum number of objects to obtain; default is 1. (optional)

Returns

Tuple of VisionObject or None if nothing is available.

# look for and return 1 object matching SIG_1
objects = vision1.take_snapshot(SIG_1)

# look for and return a maximum of 4 objects matching SIG_1
objects = vision1.take_snapshot(SIG_1, 4)

timestamp()

Request the timestanp of last received message from the vision sensor.

Returns: Timestamp of the last status packet in mS.

class vex.VisionObject

Bases: object

A vision object, not instantiated by user programs.

__init__()

class vex.VoltageUnits

Bases: object

The measurement units for voltage values.

MV = mV: A voltage unit that is measured in millivolts.

VOLT = VOLT: A voltage unit that is measured in volts.

class VoltageUnits(value, name)

Bases: vexEnum

Voltage units.

vex.XAXIS = XAXIS: The X axis of the Inertial sensor.

vex.YAW = YAW: Yaw, orientation around the Z axis of the Inertial sensor.

vex.YAXIS = YAXIS: The Y axis of the Inertial sensor.

vex.ZAXIS = ZAXIS: The Z axis of the Inertial sensor.

vex.clear_errors(): Cear any brain on screen errors

vex.info()

Return a string with VEX Python version information.

Returns: Information.

vex.on_screen_errors(value: int)

Enable or disable the display of brain on screen errors.

Parameters: value – True or False.
Returns: None.

vex.sleep(duration: Union[int, float], units=MSEC)

Delay the current thread for the provided number of seconds or milliseconds.

Parameters

duration – The number of seconds or milliseconds to sleep for.
units – The units of duration, optional, default is milliseconds.

Returns

None

class vex.vexEnum(value, name)

Bases: object

Base class for all enumerated types

__init__(value, name)

Parameters

value – Value.
name – Name.

name = '': Name

value = 0: Value

vex.wait(duration: Union[int, float], units=MSEC)

Delay the current thread for the provided number of seconds or milliseconds.

Parameters

duration – The number of seconds or milliseconds to sleep for.
units – The units of duration, optional, default is milliseconds.

Returns

None