Skip to content

Joystick Interface Reference

kevinbotlib.joystick

kevinbotlib.joystick.NamedControllerButtons

Bases: IntEnum

Named controller buttons provided by the SDL2 backend

A = sdl2.SDL_CONTROLLER_BUTTON_A class-attribute instance-attribute

A button

B = sdl2.SDL_CONTROLLER_BUTTON_B class-attribute instance-attribute

B button

X = sdl2.SDL_CONTROLLER_BUTTON_X class-attribute instance-attribute

X button

Y = sdl2.SDL_CONTROLLER_BUTTON_Y class-attribute instance-attribute

Y button

DpadUp = sdl2.SDL_CONTROLLER_BUTTON_DPAD_UP class-attribute instance-attribute

D-Pad Up button

DpadDown = sdl2.SDL_CONTROLLER_BUTTON_DPAD_DOWN class-attribute instance-attribute

D-Pad Down button

DpadLeft = sdl2.SDL_CONTROLLER_BUTTON_DPAD_LEFT class-attribute instance-attribute

D-Pad Left button

DpadRight = sdl2.SDL_CONTROLLER_BUTTON_DPAD_RIGHT class-attribute instance-attribute

D-Pad Right button

LeftBumper = sdl2.SDL_CONTROLLER_BUTTON_LEFTSHOULDER class-attribute instance-attribute

Left bumper button

RightBumper = sdl2.SDL_CONTROLLER_BUTTON_RIGHTSHOULDER class-attribute instance-attribute

Right bumper button

Back = sdl2.SDL_CONTROLLER_BUTTON_BACK class-attribute instance-attribute

Back button

Start = sdl2.SDL_CONTROLLER_BUTTON_START class-attribute instance-attribute

Start button

Guide = sdl2.SDL_CONTROLLER_BUTTON_GUIDE class-attribute instance-attribute

Guide button

LeftStick = sdl2.SDL_CONTROLLER_BUTTON_LEFTSTICK class-attribute instance-attribute

Left stick button

RightStick = sdl2.SDL_CONTROLLER_BUTTON_RIGHTSTICK class-attribute instance-attribute

Right stick button

Misc1 = sdl2.SDL_CONTROLLER_BUTTON_MISC1 class-attribute instance-attribute

Miscellaneous button (may be detected as the Share button on some platforms)

Paddle1 = sdl2.SDL_CONTROLLER_BUTTON_PADDLE1 class-attribute instance-attribute

Paddle 1

Paddle2 = sdl2.SDL_CONTROLLER_BUTTON_PADDLE2 class-attribute instance-attribute

Paddle 2

Paddle3 = sdl2.SDL_CONTROLLER_BUTTON_PADDLE3 class-attribute instance-attribute

Paddle 3

Paddle4 = sdl2.SDL_CONTROLLER_BUTTON_PADDLE4 class-attribute instance-attribute

Paddle 4

Touchpad = sdl2.SDL_CONTROLLER_BUTTON_TOUCHPAD class-attribute instance-attribute

Touchpad button on Playstation-style controllers

kevinbotlib.joystick.NamedControllerAxis

Bases: IntEnum

Named Axis Identifiers provided by the SDL2 backend

LeftX = sdl2.SDL_CONTROLLER_AXIS_LEFTX class-attribute instance-attribute

Left Stick X-Axis

LeftY = sdl2.SDL_CONTROLLER_AXIS_LEFTY class-attribute instance-attribute

Left Stick Y-Axis

RightX = sdl2.SDL_CONTROLLER_AXIS_RIGHTX class-attribute instance-attribute

Right Stick X-Axis

RightY = sdl2.SDL_CONTROLLER_AXIS_RIGHTY class-attribute instance-attribute

Right Stick Y-Axis

LeftTrigger = sdl2.SDL_CONTROLLER_AXIS_TRIGGERLEFT class-attribute instance-attribute

Left Trigger Axis

RightTrigger = sdl2.SDL_CONTROLLER_AXIS_TRIGGERRIGHT class-attribute instance-attribute

Right Trigger Axis

kevinbotlib.joystick.POVDirection

Bases: IntEnum

D-pad directions in degrees.

UP = 0 class-attribute instance-attribute

Up button (0 degrees)

UP_RIGHT = 45 class-attribute instance-attribute

Up and right button (45 degrees)

RIGHT = 90 class-attribute instance-attribute

Right button (90 degrees)

DOWN_RIGHT = 135 class-attribute instance-attribute

Down and right button (135 degrees)

DOWN = 180 class-attribute instance-attribute

Down button (180 degrees)

DOWN_LEFT = 225 class-attribute instance-attribute

Down and left button (225 degrees)

LEFT = 270 class-attribute instance-attribute

Left button (270 degrees)

UP_LEFT = 315 class-attribute instance-attribute

Up and left button (315 degrees)

NONE = -1 class-attribute instance-attribute

Centered (no buttons)

kevinbotlib.joystick.ControllerMap

Controller mapping for joystick events.

map_button(button_id)

Maps a button using the controller map.

Parameters:

Name Type Description Default
button_id int

Raw input button

required

Returns:

Type Description
int

Mapped button

map_axis(axis_id)

Maps an axis using the controller map.

Parameters:

Name Type Description Default
axis_id int

Raw input axis

required

Returns:

Type Description
int

Mapped Axis

kevinbotlib.joystick.LocalJoystickIdentifiers

Static class to handle joystick identification queries.

get_count() staticmethod

Returns the number of connected joysticks.

Returns:

Type Description
int

Controller count

get_names() staticmethod

Returns a dictionary of joystick indices and their corresponding names.

Returns:

Type Description
dict[int, str]

Dictionary of names from index keys

get_guids() staticmethod

Returns a dictionary of joystick indices and their corresponding GUIDs.

Returns:

Type Description
dict[int, bytes]

Dictionary of GUIDs from index keys

kevinbotlib.joystick.AbstractJoystickInterface

Bases: ABC

Abstract joystick implementation. Use this as a base if you want to create a custom joystick implementation.

controller_map property

Get the applied controller map

Returns:

Type Description
ControllerMap

Applied controller map

__init__()

Initialize the abstract joystick

apply_map(controller_map) abstractmethod

Apply a controller map

Parameters:

Name Type Description Default
controller_map ControllerMap

Controller map

required

get_button_state(button_id) abstractmethod

Get the state of a button by index or named button. Args: button_id: Button

Returns:

Type Description
bool

Is the button pressed?

get_axis_value(axis_id, precision=3) abstractmethod

Get the state of an axis by index or named axis.

Parameters:

Name Type Description Default
axis_id int | IntEnum

Axis

required
precision int

Decimal precision

3

Returns:

Type Description
float

Axis value

get_buttons() abstractmethod

Get a list of all pressed buttons

Returns:

Type Description
list[int | Enum | IntEnum]

List of pressed buttons

get_axes() abstractmethod

Get a list of all axis values.

Returns:

Type Description
list[int | Enum | IntEnum]

List of all axis values

get_pov_direction() abstractmethod

Get the current D-Pad direction.

Returns:

Type Description
POVDirection

D-Pad direction

register_button_callback(button_id, callback) abstractmethod

Register a new callback when a button is pressed.

Parameters:

Name Type Description Default
button_id int | Enum | IntEnum

Button index or named button

required
callback Callable[[bool], Any]

Callback to be triggered when the specified button is pressed

required

register_pov_callback(callback) abstractmethod

Register a new callback when the D-Pad direction is changed.

Parameters:

Name Type Description Default
callback Callable[[POVDirection], Any]

Callback to be triggered when the D-Pad changes direction

required

is_connected() abstractmethod

Detect if the joystick device is connnected

Returns:

Type Description
bool

Connected?

kevinbotlib.joystick.NullJoystick

Bases: AbstractJoystickInterface

A fake joystick implementation that will do nothing.

get_button_state(_)

Get the state of a button. Args: _: Button index or named button

Returns:

Type Description
bool

False

get_axis_value(_, __=3)

Get the state of an axis. Args: _: Axis index or named axis __: Decimal precision

Returns:

Type Description
float

0.0

get_buttons()

Get a list of all pressed buttons by index

Returns:

Type Description
list[int | Enum | IntEnum]

[]

get_axes()

Get a list of all axes.

Returns:

Type Description
list[int | Enum | IntEnum]

[]

get_pov_direction()

Get the current D-Pad direction.

Returns:

Type Description
POVDirection

POVDirection.NONE

register_button_callback(_, __)

Register a new callback when a button is pressed.

Parameters:

Name Type Description Default
_ int | Enum | IntEnum

Button index or named button

required
__ Callable[[bool], Any]

Callback to be triggered when the specified button is pressed

required

register_pov_callback(_)

Register a new callback when the D-Pad direction is changed.

Parameters:

Name Type Description Default
_ Callable[[POVDirection], Any]

Callback to be triggered when the D-Pad changes direction

required

is_connected()

Detect if the joystick device is connnected

Returns:

Type Description
bool

False

apply_map(_controller_map)

Apply a controller map

Parameters:

Name Type Description Default
_controller_map ControllerMap

Controller map

required

kevinbotlib.joystick.RawLocalJoystickDevice

Bases: AbstractJoystickInterface

Gamepad-agnostic polling and event-based joystick input with disconnect detection.

__init__(index, polling_hz=100)

Initialize the joystick system

Parameters:

Name Type Description Default
index int

Controller index

required
polling_hz int

Polling rate. Defaults to 100hz.

100

is_connected()

Get if the controller is connected

Returns:

Type Description
bool

Connected?

get_button_count()

Returns the total number of buttons on the joystick.

Returns:

Type Description
int

Button count

get_button_state(button_id)

Returns the state of a button (pressed: True, released: False).

Parameters:

Name Type Description Default
button_id int

Button index

required

Returns:

Type Description
bool

Button state

get_axis_value(axis_id, precision=3)

Returns the current value of the specified axis (-1.0 to 1.0).

Parameters:

Name Type Description Default
axis_id int

Axis index

required
precision int

Decimal precision

3

Returns:

Type Description
float

Axis value

get_buttons()

Get a list of all pressed buttons

Returns:

Type Description
list[int]

List of pressed buttons

get_axes(precision=3)

Get a list of all axis values.

Parameters:

Name Type Description Default
precision int

Decimal precision

3

Returns: List of all axis values

get_pov_direction()

Get the current D-Pad direction.

Returns:

Type Description
POVDirection

D-Pad direction

rumble(low_power, high_power, duration)

Set the controller rumble motors.

Parameters:

Name Type Description Default
low_power float

Low powered motor percent (0 to 1)

required
high_power float

High powered motor percent (0 to 1)

required
duration float

Duration of rumble in seconds

required

register_button_callback(button_id, callback)

Register a new callback when a button is pressed.

Parameters:

Name Type Description Default
button_id int

Button index or named button

required
callback Callable[[bool], Any]

Callback to be triggered when the specified button is pressed

required

register_pov_callback(callback)

Register a new callback when the D-Pad direction is changed.

Parameters:

Name Type Description Default
callback Callable[[POVDirection], Any]

Callback to be triggered when the D-Pad changes direction

required

apply_map(controller_map)

Apply a controller map

Parameters:

Name Type Description Default
controller_map ControllerMap

Controller map

required

start_polling()

Starts the polling loop in a separate thread.

stop()

Stops event handling and releases resources.

kevinbotlib.joystick.LocalNamedController

Bases: RawLocalJoystickDevice

Controller with named buttons and axes.

get_button_state(button)

Returns the state of a button (pressed: True, released: False).

Parameters:

Name Type Description Default
button NamedControllerButtons

Named button

required

Returns:

Type Description
bool

Button state

get_buttons()

Get a list of all pressed buttons

Returns:

Type Description
list[NamedControllerButtons]

List of pressed buttons

register_button_callback(button, callback)

Register a new callback when a button is pressed.

Parameters:

Name Type Description Default
button NamedControllerButtons

Named button

required
callback Callable[[bool], Any]

Callback to be triggered when the specified button is pressed

required

get_dpad_direction()

Gets the D-Pad direction. Functionally the same as get_pov_direction.

Returns:

Type Description
POVDirection

POV Direction

get_trigger_value(trigger, precision=3)

Returns the current value of the specified trigger (0.0 to 1.0).

Parameters:

Name Type Description Default
trigger NamedControllerAxis

NamedControllerAxis.LeftTrigger or NamedControllerAxis.RightTrigger

required
precision int

Decimal precision

3

Returns:

Type Description
float

Trigger value

get_axis_value(axis_id, precision=3)

Returns the current value of the specified axis (-1.0 to 1.0).

Parameters:

Name Type Description Default
axis_id int | IntEnum

Named axis

required
precision int

Decimal precision

3

Returns:

Type Description
float

Axis value

get_triggers(precision=3)

Get the current value of the trigger axes (0.0 to 1.0).

Parameters:

Name Type Description Default
precision int

Decimal precision

3

Returns:

Type Description
tuple[float, float]

Both trigger axes

get_left_stick(precision=3)

Get the left stick values Args: precision: Decimal precision

Returns:

Type Description
tuple[float, float]

X and Y axes

get_right_stick(precision=3)

Get the right stick values Args: precision: Decimal precision

Returns:

Type Description
tuple[float, float]

X and Y axes

register_dpad_callback(callback)

Register a new callback when the D-Pad direction is changed. Functionally the same as register_pov_callback

Parameters:

Name Type Description Default
callback Callable[[POVDirection], Any]

Callback to be triggered when the D-Pad changes direction

required

kevinbotlib.joystick.JoystickSender

Joystick data sender for RedisCommClient

__init__(client, joystick, key)

Initialize the joystick sender

Parameters:

Name Type Description Default
client RedisCommClient

Communication client to send data

required
joystick AbstractJoystickInterface

Joystick interface to poll

required
key str

Network key to set data on

required

start()

Start sending data

stop()

Stop sending data

kevinbotlib.joystick.DynamicJoystickSender

Joystick data sender for RedisCommClient that can switch out joystick classes while running

__init__(client, joystick_getter, key)

Initialize the joystick sender

Parameters:

Name Type Description Default
client RedisCommClient

Communication client to send data

required
joystick_getter Callable[[], AbstractJoystickInterface]

Joystick interface to poll

required
key str

Network key to set data on

required

start()

Start sending data

stop()

Stop sending data

kevinbotlib.joystick.RemoteRawJoystickDevice

Bases: AbstractJoystickInterface

Joystick interface for JoystickSender

client property

Get the connected client

Returns:

Type Description
RedisCommClient

Communication client

key property

Get the sendable key

Returns:

Type Description
str

Sendable key

__init__(client, key, callback_polling_hz=100)

Initialize the joystick interface

Parameters:

Name Type Description Default
client RedisCommClient

Communication client

required
key str

Network sendable key

required
callback_polling_hz int

Polling rate. Defaults to 100hz.

100

is_connected()

Get if the controller is connected

Returns:

Type Description
bool

Connected?

get_button_state(button_id)

Get the state of a button by index or named button. Args: button_id: Button

Returns:

Type Description
bool

Is the button pressed?

get_axis_value(axis_id, precision=3)

Get the state of an axis by index or named axis.

Parameters:

Name Type Description Default
axis_id int

Axis

required
precision int

Decimal precision

3

Returns:

Type Description
float

Axis value

get_buttons()

Get a list of all pressed buttons

Returns:

Type Description
list[int | Enum | IntEnum]

List of pressed buttons

get_axes()

Get a list of all axis values.

Returns:

Type Description
list[float]

List of all axis values

get_pov_direction()

Get the current D-Pad direction.

Returns:

Type Description
POVDirection

D-Pad direction

register_button_callback(button_id, callback)

Register a new callback when a button is pressed.

Parameters:

Name Type Description Default
button_id int | Enum | IntEnum

Button index or named button

required
callback Callable[[bool], Any]

Callback to be triggered when the specified button is pressed

required

register_pov_callback(callback)

Register a new callback when the D-Pad direction is changed.

Parameters:

Name Type Description Default
callback Callable[[POVDirection], Any]

Callback to be triggered when the D-Pad changes direction

required

apply_map(controller_map)

Apply a controller map

Parameters:

Name Type Description Default
controller_map ControllerMap

Controller map

required

start_polling()

Starts the polling loop in a separate thread.

stop()

Stops the polling thread.

kevinbotlib.joystick.RemoteNamedController

Bases: RemoteRawJoystickDevice

Remote controller with named buttons and axes.

get_button_state(button)

Returns the state of a button (pressed: True, released: False).

Parameters:

Name Type Description Default
button NamedControllerButtons

Named button

required

Returns:

Type Description
bool

Button state

get_buttons()

Get a list of all pressed buttons

Returns:

Type Description
list[NamedControllerButtons]

List of pressed buttons

get_axes(precision=3)

Get a list of all axis values.

Parameters:

Name Type Description Default
precision int

Decimal precision

3

Returns: List of all axis values

register_button_callback(button, callback)

Register a new callback when a button is pressed.

Parameters:

Name Type Description Default
button NamedControllerButtons

Button index or named button

required
callback Callable[[bool], Any]

Callback to be triggered when the specified button is pressed

required

register_dpad_callback(callback)

Register a new callback when the D-Pad direction is changed. Functionally the same as register_pov_callback

Parameters:

Name Type Description Default
callback Callable[[POVDirection], Any]

Callback to be triggered when the D-Pad changes direction

required

get_dpad_direction()

Gets the D-Pad direction. Functionally the same as get_pov_direction.

Returns:

Type Description
POVDirection

POV Direction

get_trigger_value(trigger, precision=3)

Returns the current value of the specified trigger (0.0 to 1.0).

Parameters:

Name Type Description Default
trigger NamedControllerAxis

NamedControllerAxis.LeftTrigger or NamedControllerAxis.RightTrigger

required
precision int

Decimal precision

3

Returns:

Type Description
float

Trigger value

get_triggers(precision=3)

Get the current value of the trigger axes (0.0 to 1.0).

Parameters:

Name Type Description Default
precision int

Decimal precision

3

Returns:

Type Description
list[float]

Both trigger axes

get_left_stick(precision=3)

Get the left stick values Args: precision: Decimal precision

Returns:

Type Description
list[float]

X and Y axes

get_right_stick(precision=3)

Get the right stick values Args: precision: Decimal precision

Returns:

Type Description
list[float]

X and Y axes