robot-xbox-controller 0.1.0__py3-none-any.whl

robot/xbox_controller.py

@@ -0,0 +1,131 @@
+import math
+import os
+import pygame
+import time
+
+from robot.xbox_state import XboxState
+
+
+class XboxController:
+    EVENT_LOOP_DELAY = 0.05
+    WAITING_LOOP_DELAY = 1.0
+    CLOCK_TICKS = 20
+
+    BUTTON_A = 0
+    BUTTON_B = 1
+    BUTTON_X = 2
+    BUTTON_Y = 3
+    BUTTON_VIEW = 4  #  left middle button
+    BUTTON_XBOX = 5  #  center middle button
+    BUTTON_SHARE = 6  # right middle button
+    BUTTON_LEFT_JOYSTICK = 7
+    BUTTON_RIGHT_JOYSTICK = 8
+    BUTTON_LEFT_BUMPER = 9
+    BUTTON_RIGHT_BUMPER = 10
+    BUTTON_FORWARD = 11
+    BUTTON_BACKWARD = 12
+    BUTTON_LEFT = 13
+    BUTTON_RIGHT = 14
+
+    def __init__(self):
+        self.connected = False
+        self.controller = None
+        self.controller_name = None
+        self.device_index = None
+        self.state = XboxState()
+        self.clock = pygame.time.Clock()
+
+        os.environ["SDL_VIDEODRIVER"] = "dummy"
+
+        pygame.init()
+        pygame.joystick.init()
+
+    def _connect_event(self, event):
+        self.device_index = event.device_index
+        self.controller = pygame.joystick.Joystick(self.device_index)
+        self.controller_name = self.controller.get_name()
+        self.connected = True
+
+        return self
+
+    def connect(self, wait_for_controller_message="Waiting for Xbox Controller"):
+        if wait_for_controller_message:
+            while True:
+                for event in pygame.event.get():
+                    if event.type == pygame.JOYDEVICEADDED:
+                        return self._connect_event(event)
+
+                print(wait_for_controller_message)
+
+                time.sleep(XboxController.WAITING_LOOP_DELAY)
+
+    @classmethod
+    def quit_event(cls, event):
+        if event.type == pygame.QUIT:
+            return True
+
+        if event.type == pygame.JOYBUTTONDOWN:
+            if event.button == 15:
+                return True
+
+        return False
+
+    def run(self, run_method, debugging=False):
+        running = True
+
+        while running:
+            for event in pygame.event.get():
+                if self.quit_event(event):
+                    return False
+                else:
+                    self.state.event(event, debugging)
+
+            running = run_method(self)
+
+    def tick(self, frame_rate):
+        self.clock.tick(frame_rate)
+
+    @classmethod
+    def wheel_speeds(cls, x_axis, y_axis, max_speed=1.0):
+        """
+        Converts controller axes to differential wheel speeds.
+        y_axis: forward/backward (-1 to 1)
+        x_axis: left/right (-1 to 1)
+        """
+        # Simple mapping:
+        # Forward: Y is negative, so invert it
+        # Turn: X is positive to the right
+
+        speed = -y_axis
+        turn = x_axis
+
+        # Calculate speeds
+        left_speed = speed + turn
+        right_speed = speed - turn
+
+        # Normalize/Clamp values to -1.0 to 1.0
+        left_speed = max(-1.0, min(1.0, left_speed)) * max_speed
+        right_speed = max(-1.0, min(1.0, right_speed)) * max_speed
+
+        return round(left_speed, 2), round(right_speed, 2)
+
+    @classmethod
+    def wheel_speed_and_angle(cls, x_axis, y_axis, max_speed=1.0):
+        if abs(x_axis) < 0.25:
+            x_axis = 0.0
+        if abs(y_axis) < 0.25:
+            y_axis = 0.0
+
+        speed = math.sqrt(x_axis**2 + y_axis**2)
+
+        if speed > 1.0:
+            speed = 1.0
+
+        angle_rad = math.atan2(-y_axis, x_axis)
+        angle_deg = math.degrees(angle_rad)
+
+        # if angle_deg < 0:
+        #    angle_deg += 360
+
+        # print("Axis:", x_axis, y_axis, "  speed:", speed, "  angle", angle_deg)
+        return round(speed, 2), round(angle_deg, 2)

robot/xbox_state.py

@@ -0,0 +1,96 @@
+import pygame
+import time
+
+
+class XboxState:
+    JOYSTICK_DRIFT = 0.18
+
+    def __init__(self):
+        self.axis_value = [0.0, 0.0, 0.0, 0.0, -1.0, -1.0]
+        self.button_down_at = [0] * 16
+        pass
+
+    def show_value_string(self, value):
+        return "{:6.2f}".format(value)
+
+    def state_string(self, extra_string=None):
+        s = ""
+        s = s + self.show_value_string(self.left_x())
+        s = s + self.show_value_string(self.left_y())
+        s = s + self.show_value_string(self.right_x())
+        s = s + self.show_value_string(self.right_y())
+        s = s + self.show_value_string(self.left_trigger())
+        s = s + self.show_value_string(self.right_trigger())
+        if extra_string is not None:
+            s = s + " " + extra_string
+
+        for button in range(16):
+            down_seconds = self.button_down_seconds(button)
+
+            if down_seconds > 0:
+                s += f" button{button:3d} down: {down_seconds:4.2f} seconds"
+
+        return s
+
+    def print_state_string(self, extra_string=None):
+        print(self.state_string(extra_string))
+
+    def event(self, event, debugging=False):
+        if event.type == pygame.JOYBUTTONUP:
+            self.button_down_at[event.button] = 0
+        elif event.type == pygame.JOYBUTTONDOWN:
+            self.button_down_at[event.button] = time.perf_counter()
+        elif event.type == pygame.JOYAXISMOTION:
+            value = event.value
+
+            if abs(value) < XboxState.JOYSTICK_DRIFT:
+                value = 0.0
+
+            self.axis_value[event.axis] = round(value, 2)
+        else:
+            print("Unprocessed event:", event)
+
+        if debugging:
+            print(self.state_string())
+
+    def left_x(self):
+        return self.axis_value[0]
+
+    def left_y(self):
+        return self.axis_value[1]
+
+    def left_axis(self):
+        return self.left_x(), self.left_y()
+
+    def right_x(self):
+        return self.axis_value[2]
+
+    def right_y(self):
+        return self.axis_value[3]
+
+    def right_axis(self):
+        return self.right_x(), self.right_y()
+
+    def adjusted_trigger_value(self, value):
+        return round((value + 1.0) / 2.0, 2)
+
+    def left_trigger(self):
+        return self.adjusted_trigger_value(self.axis_value[4])
+
+    def right_trigger(self):
+        return self.adjusted_trigger_value(self.axis_value[5])
+
+    def left_trigger_raw(self):
+        return self.axis_value[4]
+
+    def right_trigger_raw(self):
+        return self.axis_value[5]
+
+    def button_down_seconds(self, button):
+        if self.button_down_at[button] <= 0:
+            return 0
+
+        return time.perf_counter() - self.button_down_at[button]
+
+    def button_down_milliseconds(self, button):
+        return int(self.button_down_seconds(button) * 1000.0)

robot_xbox_controller-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: robot-xbox-controller
+Version: 0.1.0
+Summary: Library for xbox controllers.
+Project-URL: Documentation, https://github.com/fmorton/robot-python-xbox-controller#readme
+Project-URL: Issues, https://github.com/fmorton/robot-python-xbox-controller/issues
+Project-URL: Source, https://github.com/fmorton/robot-python-xbox-controller
+Author-email: Frank Morton <fmorton@mac.com>
+License-Expression: LGPL-3.0-only
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.9
+Requires-Dist: pygame
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: pylint; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: flake8-pyproject; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-mock; extra == 'test'
+Requires-Dist: pytest>=8.3; extra == 'test'
+Description-Content-Type: text/x-rst
+
+========
+Overview
+========
+
+
+.. start-badges
+
+.. list-table::
+    :stub-columns: 1
+
+    * - docs
+      - |docs|
+    * - package
+      - | |version| |wheel| |supported-versions|
+.. |docs| image:: https://readthedocs.org/projects/robot-python-xbox-controller/badge/?style=flat
+    :target: https://robot-xbox-controller.readthedocs.io/
+    :alt: Documentation Status
+
+.. |github-actions| image:: https://github.com/fmorton/robot-python-xbox-controller/actions/workflows/github-actions.yml/badge.svg
+    :alt: GitHub Actions Build Status
+    :target: https://github.com/fmorton/robot-python-xbox-controller/actions
+
+.. |codecov| image:: https://codecov.io/gh/fmorton/robot-xbox-controller/branch/main/graphs/badge.svg?branch=main
+    :alt: Coverage Status
+    :target: https://codecov.io/github/fmorton/robot-xbox-controller
+
+.. |version| image:: https://img.shields.io/pypi/v/robot-xbox-controller.svg
+    :alt: PyPI Package latest release
+    :target: https://pypi.org/project/robot-xbox-controller
+
+.. |wheel| image:: https://img.shields.io/pypi/wheel/robot-xbox-controller.svg
+    :alt: PyPI Wheel
+    :target: https://pypi.org/project/robot-xbox-controller
+
+.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/robot-xbox-controller.svg
+    :alt: Supported versions
+    :target: https://pypi.org/project/robot-xbox-controller
+
+.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/robot-xbox-controller.svg
+    :alt: Supported implementations
+    :target: https://pypi.org/project/robot-xbox-controller
+
+
+.. end-badges
+
+Library for xbox controllers.
+
+* Free software: MIT License
+
+Installation
+============
+
+::
+
+    pip install robot-xbox-controller
+
+You can also install the in-development version with::
+
+    pip install https://github.com/fmorton/robot-xbox-controller/archive/main.zip
+
+
+
+Xbox Controller Example
+=======================
+
+.. code-block:: python
+
+  import pygame
+
+  from robot.xbox_controller import XboxController
+
+  controller = XboxController().connect()
+
+  print("Controller connected")
+
+  running = True
+
+  while running:
+    for event in pygame.event.get():
+        if event.type == pygame.QUIT:
+            running = False
+        elif event.type == pygame.JOYAXISMOTION:
+            print(f"Controller axis {event.axis} value {event.value}")
+        elif event.type == pygame.JOYBUTTONDOWN:
+            print(f"Button {event.button} pressed on controller {event.joy}")
+
+            if event.button == XboxController.BUTTON_XBOX:
+                running = False
+
+
+Xbox Controller Example Using run() and the Controller State
+============================================================
+
+The run() loop maintains the state of the controllers and all buttons for processing by your supplied method, "robot" in the example below.
+
+.. code-block:: python
+
+  from robot.xbox_controller import XboxController
+  from time import sleep
+
+
+  def robot(controller):
+    print("runner", controller.state.state_string())
+
+    if controller.state.button_down_milliseconds(XboxController.BUTTON_XBOX):
+        return False
+
+    sleep(XboxController.EVENT_LOOP_DELAY)
+
+    return True
+
+
+  controller = XboxController().connect()
+
+  controller.run(robot)
+
+
+
+The controller.state has the following methods to retrieve the selections.
+
+.. code-block:: python
+
+  controller.state.left_x()        # returns x value of left controller (-1 means max forward/1 max backward)
+  controller.state.left_y()        # returns y value of left controller (-1 means max left/1 max right)
+  controller.state.left_axis()     # returns left_x, left_y
+
+  controller.state.right_x()       # returns x value of right controller (-1 means max forward/1 max backward)
+  controller.state.right_y()       # returns y value of right controller (-1 means max left/1 max right)
+  controller.state.right_axis()    # returns right_x, right_y
+
+  controller.state.left_trigger()       # returns left trigger value (0 to 1 if fully pressed)
+  controller.state.right_trigger()      # returns right trigger value (0 to 1 if fully pressed)
+
+  controller.state.left_trigger_raw()   # returns left trigger unadjusted value (-1 to 1 if fully pressed)
+  controller.state.right_trigger_raw()   # returns right trigger unadjusted value (-1 to 1 if fully pressed)
+
+  controller.state.button_down_seconds(button)       # how many seconds "button" has been pressed
+  controller.state.button_down_milliseconds(button)  # how many milliseconds "button" has been pressed
+
+
+
+The following button constant values are available in XboxController:
+
+.. code-block:: python
+
+  BUTTON_A = 0
+  BUTTON_B = 1
+  BUTTON_X = 2
+  BUTTON_Y = 3
+  BUTTON_VIEW = 4   #  left middle button
+  BUTTON_XBOX = 5   #  center middle button
+  BUTTON_SHARE = 6  # right middle button
+  BUTTON_LEFT_JOYSTICK = 7
+  BUTTON_RIGHT_JOYSTICK = 8
+  BUTTON_LEFT_BUMPER = 9
+  BUTTON_RIGHT_BUMPER = 10
+  BUTTON_FORWARD = 11
+  BUTTON_BACKWARD = 12
+  BUTTON_LEFT = 13
+  BUTTON_RIGHT = 14
+
+
+
+Testing
+=======
+
+To run all the tests run::
+
+    pytest -s

robot_xbox_controller-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+robot/xbox_controller.py,sha256=nyQVqwWOKkyhaUNx5bYcUsxHaWBt5jxAqlNOTj-aPe8,3599
+robot/xbox_state.py,sha256=y93Akl2pAMnyO3DtejTKeKW9PyY-Yw1GVgE2pDC2UQE,2764
+robot_xbox_controller-0.1.0.dist-info/METADATA,sha256=BOXdPtrDJPdyccicdzH1cbRpcU3s-J0eYs5n6qSeiMM,6453
+robot_xbox_controller-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+robot_xbox_controller-0.1.0.dist-info/licenses/LICENSE,sha256=jg4vPk0w0vVVIE12vUtvLN-8x8yrxoS5z0_WwirTHGo,1092
+robot_xbox_controller-0.1.0.dist-info/RECORD,,

robot_xbox_controller-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

robot_xbox_controller-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Morton (fmorton@base2inc.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.