Gamepads module

This module contains functions for getting gamepad data.

To use this module, you must first import it:

>>> from api.Gamepads import *

class api.Gamepads.Button

A = 0

B = 1

BACK = 8

DPAD_DOWN = 13

DPAD_LEFT = 14

DPAD_RIGHT = 15

DPAD_UP = 12

L_BUMPER = 4

L_STICK = 10

L_TRIGGER = 6

R_BUMPER = 5

R_STICK = 11

R_TRIGGER = 7

START = 9

X = 2

XBOX = 16

Y = 3

class api.Gamepads.Joystick

LEFT_X = 0

LEFT_Y = 1

RIGHT_X = 2

RIGHT_Y = 3

api.Gamepads.get_all()

Returns a list a list of values for every gamepad connected.

Returns:A list of axes and button data for each connected gamepad Examples:

>>> gpads = Gamepads.get_all()
>>> gamepad0 = gpads[0]

api.Gamepads.get_all_buttons(gamepad_index)

Returns a list of button values corresponding to the specified gamepad.

Each button value is either False (not pressed) or True (pressed). Unlike joysticks, there are no in-between values–it can only be False or True. To see the exact mapping, click on the ‘Details’ button next to a gamepad in Dawn, or refer to https://w3c.github.io/gamepad/#remapping.

Parameters:gamepad_index – The index of the gamepad, usually 0, 1, 2, or 3 Returns:A list of booleans, each corresponding to a button being pressed or not pressed Examples:

>>> all_buttons = get_all_buttons(0)
>>> all_buttons[1]
True

api.Gamepads.get_axis(gamepad_index, axis)

Returns the position of a specified joystick.

Each returned value is between -1 and 1, which represents where the joystick is along that axis. In order to get a better sense of the joystick mappings, click the ‘Details’ button next to a gamepad in Dawn or refer to https://w3c.github.io/gamepad/#remapping.

On a standard gamepad: - Joystick.LEFT_X represents the horizontal axis of the left joystick - Joystick.LEFT_Y represents the vertical axis of the left joystick - Joystick.RIGHT_X represents the horizontal axis of the right joystick - Joystick.RIGHT_Y represent the vertical axis of the right joystick

Parameters:

• gamepad_index – The index of the gamepad, usually 0, 1, 2, or 3
• axis – An enum (LEFT_X,LEFT_Y,RIGHT_X,RIGHT_Y) which specifies the axis.

Returns:

A list of 4 decimal values, each corresponding to a joystick axis.

Examples:

>>> axis = get_axis(0,Joystick.LEFT_X)
>>> axis = get_axis(1,Joystick.RIGHT_Y)

api.Gamepads.get_button(gamepad_index, button)

Returns whether a button is pressed or not.

For a specific button (each button has has a name) the output is either True (pressed) or False (not pressed). To see the exact mapping, click on the ‘Details’ button next to a gamepad in Dawn, or refer to https://w3c.github.io/gamepad/#remapping.

Parameters:

• gamepad_index – The index of the gamepad, usually 0, 1, 2, or 3
• button – Enum of button (e.g. Button.Y), see documentation for more details

Returns:

A boolean either True (pressed) or False (not pressed)

Examples:

>>> button = get_button(0,Button.Y)
>>> button
False

api.Gamepads.get_is_connected(gamepad_index)

Returns whether or not the specified gamepad is connected.

Parameters:gamempad_index – The index of the gamepad, usually 0, 1, 2, or 3 Returns:A boolean value for whether or not that gamepad is connected

api.Gamepads.get_joysticks(gamepad_index)

Returns a list of axes values corresponding to the specified gamepad.

Each returned value is between -1 and 1, which represents where the joystick is along that axis. For example, if axes[0] is -1, then the left joystick has been pushed all the way to the left. In order to get a better sense of the joystick mappings, click the ‘Details’ button next to a gamepad in Dawn or refer to https://w3c.github.io/gamepad/#remapping.

On a standard gamepad: - axes[0] represents the horizontal axis of the left joystick. - axes[1] represents the vertical axis of the left joystick - axes[2] represents the horizontal axis of the right joystick - axes[3] represent the vertical axis of the right joystick

Parameters:gamepad_index – The index of the gamepad, usually 0, 1, 2, or 3 Returns:A list of 4 decimal values, each corresponding to a joystick axis. Examples:

>>> axes = get_joysticks(0)

Robot module

This module contains functions for reading data from the robot, and for manipulating the robot.

To use this module, you must first import it:

>>> from api import Robot
>>> from api.Robot import *

exception api.Robot.SensorValueOutOfBounds

Bases: exceptions.Exception

api.Robot.calibrate_metal_detector(name)

Calibrates the specified metal sensor

Calibrates to set the current reading of the metal detector to air (0). It is recommended that this is called before every reading to avoid misreading values due to drift.

Parameters:name – A String that identifies the metal detector smart device.

api.Robot.change_PID_constants(value, constant)

Changes a PID constant which error corrects for motor positions.

P - Proportion - changes the constant for present error correcting I - Integral - changes the constant for past error correcting D - Derivative - changes the constant for future errors - decreases response time For more information, refer to a mentor or the wiki page: https://en.wikipedia.org/wiki/PID_controller

Parameters:

• value – A decimal corresponding to the new coefficient of a PID constant.
• constant – A String (“P”, “I”, “D”) corresponding to the constant to be changed.

api.Robot.change_control_mode(mode, motor)

Changes PID mode for specified motors connected to the robot

This changes the control mode for inputing values into the specified motors.

Default mode - No_PID which means one inputs a range of integers from -1 to 1 and the motor runs at a proportion corresponding to that range.

Speed PID - Motors run at encoder ticks per second instead of an integer range. Encoder ticks are a proportion of a rotation, similar to degrees to check for encoder ticks for each motor, see this website: https://www.pololu.com/category/116/37d-mm-gearmotors

Position PID - Motors run until at a certain position, using encoder ticks as units. See above website for number of ticks per degree of rotation.

Parameters:

• mode – A String (‘default’, ‘speed’, ‘position’) corresponding to the wanted control mode for the specified motor.
• motor – A String corresponding to the motor name whose PID mode is to be changed

api.Robot.change_control_mode_all(mode)

Changes PID mode for all motors connected to the robot

This changes the control mode for inputing values into all of the motors. Default mode - No_PID which means one inputs a range of floats from -1 to 1 and the motor runs at a proportion corresponding to that range.

Speed PID - Motors run at encoder ticks per second instead of an integer range. Encoder ticks are a proportion of a rotation, similar to degrees to check for encoder ticks for each motor, see this website: https://www.pololu.com/category/116/37d-mm-gearmotors

Position PID - Motors run until at a certain position, using encoder ticks as units. See above website for number of ticks per degree of rotation.

Parameters:mode – A String (“default”, “speed”, “position”) corresponding to the wanted control mode for all motors.

api.Robot.drive_distance_all(degrees, motors, gear_ratios)

WARNING: THIS METHOD IS NOT GUARANTEED TO WORK. USE WITH CAUTION.

Drives all motors in the list a set number of degrees set by the corresponding index in the distances list.

The specified motor will run until it reaches the specified degree of rotation and will hold the motor there until a grizzly motor method is called again. The gear ratio should be indicated on the physical motor itself. Implementation of this method for users in PID mode: this method translates degrees into encoder ticks and then sets the target in said encoder ticks. When this method is called again on the same motor, current encoder tick position is reset to 0 and the method reruns.

Parameters:

• degrees – A list of integers corresponding to the number of ticks to be moved. The integer at the index of this list should match the motor’s index.
• motor – A list of strings corresponding to the motor names to be rotated. The index of the motor names should match the index of the distance.
• gear_ratios – A list of integers corresponding to the gear ratios of the motors. The integer at the index of this list should match the motor’s index.

api.Robot.drive_distance_degrees(degrees, motor, gear_ratio)

WARNING: THIS METHOD IS NOT GUARANTEED TO WORK. USE WITH CAUTION.

Drives the specified motor a set number of degrees and holds the motor there.

The specified motor will run until it reaches the specified degree of rotation and will hold the motor there until a grizzly motor method is called again. The gear ratio should be indicated on the physical motor itself. Implementation of this method for users in PID mode: this method translates degrees into encoder ticks and then sets the target in said encoder ticks. When this method is called again on the same motor, current encoder tick position is reset to 0 and the method reruns.

Parameters:

• degrees – An integer corresponding to the number of degrees to be moved
• motor – A String corresponding to the motor name to be rotated
• gear_ratio – An integer corresponding to the gear ratio of the motor (19 or 67)

api.Robot.drive_distance_rotations(rotations, motor, gear_ratio)

WARNING: THIS METHOD IS NOT GUARANTEED TO WORK. USE WITH CAUTION.

Drives the specified motor a set number of rotations and holds the motor there.

The specified motor will run until it reaches the specified degree of rotation and will hold the motor there until a grizzly motor method is called again. The gear ratio should be indicated on the physical motor itself. Implementation of this method for users in PID mode: this method translates degrees into encoder ticks and then sets the target in said encoder ticks. When this method is called again on the same motor, current encoder tick position is reset to 0 and the method reruns.

Parameters:

• rotations – An integer corresponding to the number of rotations to be moved
• motor – A String corresponding to the motor name to be rotated
• gear_ratio – An integer corresponding to the gear ratio of the motor (19 or 67)

api.Robot.get_PID_constants()

Returns a dictionary with the key being the constants and the corresponding item as the value of the constant

Returns a list of 3 tuples with the key containing a String (“P”, “I”, or “D”) corresponding to each of the constants. The item of the dictionary is that constant’s current value.

api.Robot.get_all_motors()

Returns the current power values for every connected motor.

api.Robot.get_distance_sensor(name)

Returns the distance away from the sensor an object is, measured in centimeters

Parameters:name – A String that identifies the distance sensor Returns:A double representing how many centimeters away the object is from the sensor Examples:

>>> distance = get_distance_sensor("distance1")
>>> distance
10.76

api.Robot.get_hue(name)

Returns the hue detected at the specified color sensor.

This uses the red, green, and blue sensors on the color sensor to return the detected hue, which is represented as a double between 0 and 360. See https://en.wikipedia.org/wiki/Hue for more information on hue.

Parameters:name – A string that identifies the color sensor Returns:A double between 0 and 360 representing the detected hue Examples:

>>> hue = get_hue("color1")
>>> hue
254.01

api.Robot.get_limit_switch(name)

Returns whether a specified limit switch on the identified device is pressed or not

The specified limit switch returns a boolean, either True (pressed) or False (not pressed).

Parameters:name – A String that identifies the limit switch Returns:A boolean value, where True is pressed and False is not pressed. Examples:

>>> switch = get_limit_switch("switch1")
>>> switch
True

api.Robot.get_line_sensor(name)

Returns a value used to determine whether the selected sensor is over a line or not

If the selected sensor (left, center, or right) is over a line/reflective surface, this will return an double close to 0; Over the ground or dark material, this will return an double close to 1.

Parameters:name – A String that identifies the reflecting smart device. Returns:An double that specifies whether it is over the tape (0 - 1)

>>> line_sensor = get_line_sensor("line_sensor_1")
>>> line_sensor
0.03

api.Robot.get_luminosity(name)

Returns the luminosity for the specified color sensor.

The color sensor returns the luminosity detected by the color sensor, represnted by a decimal where larger numbers indicates higher intensity.

Parameters:name – A string that identifies the color sensor Returns:A double where a larger number indicates a higher intensity Examples:

>>> lum_berry = get_luminosity("color1")

api.Robot.get_metal_detector(name)

Returns the sensor reading of the specified metal detector

Each metal detector returns an integer, which changes based on the prescence of metal. After callibration, the value should increase in the presence of steel and decrease in the presence of aluminum. There is random drift of around 8 so your code should callibrate in air often.

Parameters:name – A String that identifies the metal detector smart device. Returns:An integer (large) which represents whether metal is detected or not.

api.Robot.get_motor(name)

Returns the current power value for a motor.

Parameters:name – A string that identifies the motor Returns:A value between -1 and 1, which is the power level of that motor. Examples:

>>> motor = get_motor("motor1")

api.Robot.get_potentiometer(name)

Returns the sensor reading of a potentiometer

The potentiometer returns a decimal between 0 and 1, indicating the angle detected, where 0 and 1 are the two extreme angles.

Parameters:name – A string that identifies the potentiometer smart device (contains four potentiometers) Returns:A decimal between 0 and 1 representing the angle.

>>> potentiometer = get_potentiometer("potentiometer1")
>>> potentiometer
0.364

api.Robot.get_rgb(name)

Returns a list of rgb values from the specified color sensor.

Each value for red, green, and blue will return a number between 0 and 255, where 255 indicates a higher intensity. This function returns the result from one specific color sensor.

Parameters:name – A string that identifies the color sensor Returns:A list of integers in the order of values for red, green, blue Examples:

>>> color = get_color_sensor("color1")
>>> color
[100, 240, 150]

api.Robot.get_sensor(name)

Returns the value, or reading corresponding to the specified sensor.

WARNING: This is a default get method and should only be used if the sensor in question does not have a specific get function. You should always use a specific sensor’s get function if specified in this doc.

Parameters:name – A string that identifies the sensor. Returns:The reading of the sensor at the current point in time. Examples:

>>> get_sensor("sensor1")

api.Robot.get_servo(name)

Gets the degree that a servo is set to.

Each servo is set to an integer degree value (0-180). This function returns what value the servo is currently set to.

Parameters:name – A string that identifies the servo Examples:

>>> get_servo("servo1")
45

api.Robot.is_autonomous()

Returns the autonomous state of the game.

Returns:A boolean. Examples:

>>> if is_autonomous():
        set_motor('motor1', 0.5)

api.Robot.is_enabled()

Returns whether the robot is enabled.

Returns:A boolean. Examples:

>>> if is_enabled():
        set_motor('motor1', 0.5)

api.Robot.set_drive_mode(mode)

Sets the drive mode of all the motors between coasting and full breaking.

Enter a string (“coast” or “brake”) to specify if the motors should fully break after movement or coast to a stop. Default mode is breaking after movement

Parameters:mode – A String (“coast” or “brake”) corresponding to the selected drive mode.

>>> set_drive_mode("coast")

api.Robot.set_led(num, value)

Sets a specific LED on the team flag

Parameters:

• num – The number of the LED (0, 1, 2, or 3)
• value – A boolean value

Examples:

>>> set_LED(0, False)
>>> set_LED(1, True)

api.Robot.set_motor(name, value)

Sets a motor to the specified power value.

Parameters:

• name – A string that identifies the motor.
• value – A decimal value between -1 and 1, the power level you want to set.

Examples:

>>> set_motor("motor1", .50)

api.Robot.set_servo(name, value)

Sets a degree for a specific servo to turn.

One servo, as specified by its name, is set to turn to an integer amount of degrees (0-180)

Parameters:

• name – A string that identifies the servo
• value – An integer between 0 and 180 which sets the amount to turn to in degrees

Examples:

>>> set_servo("servo1",90)
>>> set_servo("servo3",150)

api.Robot.toggle_light(name, status)

Turns the light on specfied color sensor on or off.

Takes in the name of the specified color sensor and a boolean (True for on, False for off).

Parameters:

• name – A string that identifies the color sensor.
• status – A boolean that determines whether the light should be on (True) or off (False)

>>> toggle_light("color1", True)
>>> toggle_light("color2", False)