API Reference

relic_usb_host_gamepad

CircuitPython USB host driver for game controller devices.

  • Author(s): Cooper Dalrymple

Implementation Notes

Hardware:

Software and Dependencies:

relic_usb_host_gamepad.BUTTON_A = 0

The ID of the “A” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_B = 1

The ID of the “B” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_DOWN = 5

The ID of the “D-Pad Down” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_HOME = 10

The ID of the “Home” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_JOYSTICK_DOWN = 18

The ID of the “Joystick Down” button which is triggered when the left joystick exceeds the analog threshold in the down direction. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_JOYSTICK_LEFT = 19

The ID of the “Joystick Left” button which is triggered when the left joystick exceeds the analog threshold in the left direction. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_JOYSTICK_RIGHT = 20

The ID of the “Joystick Right” button which is triggered when the left joystick exceeds the analog threshold in the right direction. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_JOYSTICK_UP = 17

The ID of the “Joystick Up” button which is triggered when the left joystick exceeds the analog threshold in the up direction. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_L1 = 11

The ID of the “L1” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_L2 = 13

The ID of the “L2” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_L3 = 15

The ID of the “L3” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_LEFT = 6

The ID of the “D-Pad Left” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_NAMES = ('A', 'B', 'X', 'Y', 'UP', 'DOWN', 'LEFT', 'RIGHT', 'START', 'SELECT', 'HOME', 'L1', 'R1', 'L2', 'R2', 'L3', 'R3', 'JOYSTICK_UP', 'JOYSTICK_DOWN', 'JOYSTICK_LEFT', 'JOYSTICK_RIGHT', 'TOUCH_PAD')

A list of all button names following the appropriate key number order. Useful for print statements.

relic_usb_host_gamepad.BUTTON_R1 = 12

The ID of the “R1” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_R2 = 14

The ID of the “R2” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_R3 = 16

The ID of the “R3” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_RIGHT = 7

The ID of the “D-Pad Right” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_SELECT = 9

The ID of the “Select” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_START = 8

The ID of the “Start” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_TOUCH_PAD = 21

The ID of the “Touch Pad” button. At the moement, this button is only supported by PlayStation DUALSHOCK 4 controllers. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_UP = 4

The ID of the “D-Pad Up” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_X = 2

The ID of the “X” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

relic_usb_host_gamepad.BUTTON_Y = 3

The ID of the “Y” button. Used as the keypad.Event.key_number attribute in Gamepad.events.

class relic_usb_host_gamepad.Buttons

The class which handles the state of each digital button of a Gamepad device.

Initializes the state of all digital button inputs.

A: bool

Whether or not the “A” button is pressed.

B: bool

Whether or not the “B” button is pressed.

DOWN: bool

Whether or not the “Down” button is pressed.

HOME: bool

Whether or not the “Home” button is pressed.

JOYSTICK_DOWN: bool

Whether or not the “Joystick Down” button is pressed which occurs when the left joystick exceeds the analog threshold in the down direction.

JOYSTICK_LEFT: bool

Whether or not the “Joystick Left” button is pressed which occurs when the left joystick exceeds the analog threshold in the left direction.

JOYSTICK_RIGHT: bool

Whether or not the “Joystick Right” button is pressed which occurs when the left joystick exceeds the analog threshold in the right direction.

JOYSTICK_UP: bool

Whether or not the “Joystick Up” button is pressed which occurs when the left joystick exceeds the analog threshold in the up direction.

L1: bool

Whether or not the “L1” button is pressed.

L2: bool

Whether or not the “L2” button is pressed.

L3: bool

Whether or not the “L3” button is pressed.

LEFT: bool

Whether or not the “Left” button is pressed.

R1: bool

Whether or not the “R1” button is pressed.

R2: bool

Whether or not the “R2” button is pressed.

R3: bool

Whether or not the “R3” button is pressed.

RIGHT: bool

Whether or not the “Right” button is pressed.

SELECT: bool

Whether or not the “Select” button is pressed.

START: bool

Whether or not the “Start” button is pressed.

TOUCH_PAD: bool

Whether or not the “Touch Pad” is pressed. Only supported by PlayStation DUALSHOCK 4 controllers.

UP: bool

Whether or not the “Up” button is pressed.

X: bool

Whether or not the “X” button is pressed.

Y: bool

Whether or not the “Y” button is pressed.

property changed: bool

Whether or not the state of any buttons has changed since the last Gamepad device update.

property events: tuple

A list of all changed button states since the last Gamepad device update represented as keypad.Event objects. The keypad.Event.key_number value represents the button ID.

property pressed: bool

Whether or not any button on the gamepad is pressed.

reset() → None

Reset the state of all buttons to be released.

relic_usb_host_gamepad.DEVICE_NAMES = ('Unknown', 'Switch Pro Controller', 'Adafruit SNES Controller', '8BitDo Zero 2', 'Generic XInput', 'PowerA Wired Controller', 'PlayStation DUALSHOCK 4 Controller', 'HID Joystick')

A list of all device names following the appropriate device type id. Useful for print statements.

relic_usb_host_gamepad.DEVICE_TYPE_8BITDO_ZERO2 = 3

The type of a usb gamepad device which has been identified as an 8BitDo Zero 2 controller.

relic_usb_host_gamepad.DEVICE_TYPE_ADAFRUIT_SNES = 2

The type of a usb gamepad device which has been identified as an Adafruit SNES controller.

relic_usb_host_gamepad.DEVICE_TYPE_HID_JOYSTICK = 7

The type of a usb joystick device which is HID-compatible.

relic_usb_host_gamepad.DEVICE_TYPE_PLAYSTATION_DS4 = 6

The type of a usb gamepad device which has been identified as a wired Sony PlayStation DUALSHOCK 4 controller.

relic_usb_host_gamepad.DEVICE_TYPE_POWERA_WIRED = 5

The type of a usb gamepad device which has been identified as a PowerA Wired Controller.

relic_usb_host_gamepad.DEVICE_TYPE_SWITCH_PRO = 1

The type of a usb gamepad device which has been identified as a Switch Pro Controller.

relic_usb_host_gamepad.DEVICE_TYPE_UNKNOWN = 0

An unknown usb device.

relic_usb_host_gamepad.DEVICE_TYPE_XINPUT = 4

The type of a usb gamepad device which has been identified as an X-Input compatible controller.

class relic_usb_host_gamepad.Gamepad(port: int = None, debug: bool = False)

Helper class which coordinates device identification, initialization and reading for supported USB gamepad devices.

Initializes the Gamepad device helper.

Parameters:

  • port – If using a USB hub such as the CH334F, you can specify the desired physical port to communicate with. This is useful for reading from multiple gamepad devices with a specific device location for each. Use None to allow this class to communicate with devices on any USB port.

  • debug – Set this value to True to generate verbose debug messages over REPL.

property buttons: Buttons

The object which handles the state of all digital button inputs.

property connected: bool

Whether or not a usb gamepad device is connected.

property device_type: int

The id of the device type if a usb gamepad device is connected. Otherwise, it will be DEVICE_TYPE_UNKNOWN.

disconnect() → bool

Disconnect from the usb gamepad device if one is currently active.

Returns:

If there is no active device, it will return False. Otherwise, True.

property events: tuple

A tuple of all changed button states since the last successful update as keypad.Event objects. The keypad.Event.key_number value represents the button ID.

property joystick_deadzone: float

A value from 0.0 to 1.0 which controls the area at which an analog joystick is treated as 0. All values above the deadzone will be scaled to the full range. Defaults to 0.1.

property joystick_threshold: float

A value from 0.0 to 1.0 which controls the level at which the left analog joystick will activate the JOYSTICK_UP, JOYSTICK_DOWN, JOYSTICK_LEFT, or JOYSTICK_RIGHT buttons. Defaults to 0.25.

property left_joystick: tuple

The position of the left analog joystick on each axis from -1.0 to 1.0 represented as a tuple with the format (x, y).

property left_joystick_invert_x: bool

Whether or not the invert the direction of the X-axis of Gamepad.left_joystick. Also affects JOYSTICK_LEFT, and JOYSTICK_RIGHT buttons. Changes take effect after the next successful device update. Defaults to False.

property left_joystick_invert_y: bool

Whether or not the invert the direction of the Y-axis of Gamepad.left_joystick. Also affects JOYSTICK_UP, and JOYSTICK_DOWN buttons. Changes take effect after the next successful device update. Defaults to False.

property left_trigger: float

The value of the analog left trigger from 0.0 to 1.0.

property port: int

The designated port number when the gamepad was initialized.

property right_joystick: tuple

The position of the right analog joystick on each axis from -1.0 to 1.0 represented as a tuple with the format (x, y).

property right_joystick_invert_x: bool

Whether or not the invert the direction of the X-axis of Gamepad.right_joystick. Changes take effect after the next successful device update. Defaults to False.

property right_joystick_invert_y: bool

Whether or not the invert the direction of the Y-axis of Gamepad.right_joystick. Changes take effect after the next successful device update. Defaults to False.

property right_trigger: float

The value of the analog right trigger from 0.0 to 1.0.

property trigger_threshold: float

A value from 0.0 to 1.0 which controls the level at which an analog trigger will activate the BUTTON_L2 or BUTTON_R2 buttons. Defaults to 0.5.

update() → bool

Update the gamepad device. If no device is current active, it will attempt to identify and connect with a USB device at most once every second. If a device is active, it will poll it and update the gamepad state. If the device is deemed that it is no longer responsive, it will be automatically disconnected.

Returns:

Whether or not the state of the gamepad was updated.