Joystick Interface Reference
kevinbotlib.joystick
kevinbotlib.joystick.DefaultControllerMap = ControllerMap({}, {})
module-attribute
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.
button_map
instance-attribute
axis_map
instance-attribute
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.CommandBasedJoystick
Simple command scheduler interface for joystick devices
joystick = joystick
instance-attribute
scheduler = scheduler
instance-attribute
__init__(scheduler, joystick)
Initialize the interface
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduler
|
CommandScheduler
|
Command scheduler instance |
required |
joystick
|
AbstractJoystickInterface
|
Joystick instance |
required |
a()
Create a new command trigger with the A button
Returns:
| Type | Description |
|---|---|
|
Command trigger |
b()
Create a new command trigger with the B button
Returns:
| Type | Description |
|---|---|
|
Command trigger |
x()
Create a new command trigger with the A button
Returns:
| Type | Description |
|---|---|
|
Command trigger |
y()
Create a new command trigger with the A button
Returns:
| Type | Description |
|---|---|
|
Command trigger |
kevinbotlib.joystick.AbstractJoystickInterface
Bases: ABC
Abstract joystick implementation. Use this as a base if you want to create a custom joystick implementation.
polling_hz = 100
instance-attribute
connected = False
instance-attribute
controller_map
property
command
property
Convert the joystick into a command-based joystick.
Returns:
| Type | Description |
|---|---|
CommandBasedJoystick
|
New command joystick |
__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
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.
command
property
Convert the joystick into a command-based joystick.
Returns:
| Type | Description |
|---|---|
CommandBasedJoystick
|
New command joystick |
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()
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.
index = index
instance-attribute
guid = bytes(sdl2.SDL_JoystickGetGUID(sdl2.SDL_GameControllerGetJoystick(self._sdl_joystick)).data)
instance-attribute
running = False
instance-attribute
connected = False
instance-attribute
polling_hz = polling_hz
instance-attribute
on_disconnect = None
instance-attribute
command
property
Convert the joystick into a command-based joystick.
Returns:
| Type | Description |
|---|---|
CommandBasedJoystick
|
New command joystick |
__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()
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
|
|
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
client = client
instance-attribute
joystick = joystick
instance-attribute
key = key.rstrip('/')
instance-attribute
thread = None
instance-attribute
running = False
instance-attribute
__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
client = client
instance-attribute
joystick = joystick_getter
instance-attribute
key = key.rstrip('/')
instance-attribute
thread = None
instance-attribute
running = False
instance-attribute
__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
polling_hz = callback_polling_hz
instance-attribute
connected = False
instance-attribute
running = False
instance-attribute
client
property
key
property
Get the sendable key
Returns:
| Type | Description |
|---|---|
str
|
Sendable key |
command
property
Convert the joystick into a command-based joystick.
Returns:
| Type | Description |
|---|---|
CommandBasedJoystick
|
New command joystick |
__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.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
button_id
|
int | Enum | IntEnum
|
Button |
required |
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()
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.
__init__(client, key, callback_polling_hz=100)
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
|
|
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 |