Metadata-Version: 1.1
Name: xbox360controller
Version: 1.0.0
Summary: A pythonic Xbox360 controller API built on top of the xpad Linux kernel driver.
Home-page: https://github.com/linusg/xbox360controller
Author: Linus Groh
Author-email: mail@linusgroh.de
License: MIT
Download-URL: https://pypi.python.org/pypi/xbox360controller/
Description-Content-Type: UNKNOWN
Description: # xbox360controller
        > A pythonic Xbox360 controller API built on top of the xpad Linux kernel driver.
        
        [![PyPI Version][pypi-image]][pypi-url] [![Build Status][travis-image]][travis-url] [![Code Health][landscape-image]][landscape-url]
        
        This Python Package aims to provide a pythonic and complete API for your Xbox360 and similar game controllers.
        Currently it's built on top of the Linux kernel driver `xpad` so you can use it on almost any Linux distribution including your Rasperry Pi projects etc.
        
        The following features are supported:
        
        - Registering callbacks for **all** Buttons, Axes, Triggers and Hat in a `gpiozero`-inspired way
        - Setting the LED circle; all `xpad` provided options are possible: blinking, rotating, setting individual LEDs on and off, ...
        - Rumbling, both the left and right side can be controlled from 0 to 100 percent
        
        ## Installation
        
        Any Linux distribution:
        
        ```
        pip3 install -U xbox360controller
        ```
        
        You might also use a _virtual environment_, or do a per-user install by providing the `--user` flag to above command.
        Global installations might require the usage of `sudo` or working directly from a root shell but are **not recommended**.
        
        If the `pip3` command cannot be found, try `pip` or make sure to have pip installed properly:
        
        ```
        sudo apt-get install python3-pip
        ```
        
        ## Usage
        
        ### Basics
        
        ```python
        import signal
        from xbox360controller import Xbox360Controller
        
        
        def on_axis_moved(axis):
            print('Axis {0} moved to {1} {2}'.format(axis.name, axis.x, axis.y))
        
        try:
            with Xbox360Controller() as controller:
                controller.axis_l.when_moved = on_axis_moved
                controller.axis_r.when_moved = on_axis_moved
        
                signal.pause()
        except KeyboardInterrupt:
            pass
        ```
        
        The above code will run until `Ctrl+C` is pressed. Each time on of the left or right axis is moved, the event will be processed.
        Please note, there seems to be a bug left that the KeyboardInterrupt will not show up directly when raised, but when the next controller event is registered. In case the program hangs on `Ctrl+C`, just press or move any of the controller's buttons or axes.
        
        ### `Xbox360Controller` parameters
        
        The [`Xbox360Controller`](https://github.com/linusg/xbox360controller/blob/master/xbox360controller/controller.py#L131) classes constructor takes [a few parameters](https://github.com/linusg/xbox360controller/blob/master/xbox360controller/controller.py#L158):
        
        - `index`: the index of the controller to use. If you have connected two controllers connected, the first one would be `0`, the second on `1` and so on. Defaults to `0` (obviously).
        - `axis_threshold`: minimum value of an axis for its event to be triggered. This is useful to not get a flood of useless events with ridiculously small values even if the axis is at `(0, 0)`. Applies to all axes and triggers. Defaults to `0.2`.
        - `raw_mode`: This tells the controller class to nod use a hardcoded set of axes, buttons, triggers and the hat expected for a regular Xbox360 controller but to use the `xpad` detection features. This allows support for basically every joystick or game controller supported by `xpad`, but is badly documented and currently very limited.
          Will probably improve the situation soon, though.
        
        ### Rumbling
        
        ```python
        from xbox360controller import Xbox360Controller
        
        with Xbox360Controller() as controller:
            controller.set_rumble(0.5, 0.5, 1000)
        ```
        
        This will enable rumble on both sides of the controller with each 50% strength for one second (1000ms).
        
        ### LED
        
        ```python
        import time
        from xbox360controller import Xbox360Controller
        
        with Xbox360Controller(0) as controller:
            controller.set_led(Xbox360Controller.LED_ROTATE)
            time.sleep(1)
            controller.set_led(Xbox360Controller.LED_OFF)
        ```
        
        This will let the LED circle rotate for one second and then turn it off.
        Available modes are:
        
        - `LED_OFF`
        - `LED_BLINK`
        - `LED_TOP_LEFT_BLINK_ON`
        - `LED_TOP_RIGHT_BLINK_ON`
        - `LED_BOTTOM_LEFT_BLINK_ON`
        - `LED_BOTTOM_RIGHT_BLINK_ON`
        - `LED_TOP_LEFT_ON`
        - `LED_TOP_RIGHT_ON`
        - `LED_BOTTOM_LEFT_ON`
        - `LED_BOTTOM_RIGHT_ON`
        - `LED_ROTATE`
        - `LED_BLINK_PREV`
        - `LED_BLINK_SLOW_PREV`
        - `LED_ROTATE_TWO`
        - `LED_BLINK_SLOW`
        - `LED_BLINK_ONCE_PREV`
        
        ### Available attributes and methods in non-raw mode
        
        `controller` is an instance of `Xbox360Controller` with `raw_mode=False`.
        
        - `Xbox360Controller.get_available()`: return a list of `Xbox360Controller` instances containing each available controller
        - `controller.driver_version`: return the driver versions returned by `ioctl` with `JSIOCGVERSION` on the device file and `EVIOCGVERSION` on the event file. TBH, I'm not even sure what these mean :confused:
        - `controller.num_axes`: return the total number of axes, triggers and hats
        - `controller.num_buttons`: return the total number of buttons
        - `controller.name`: return the controller's name as reported by `xpad`
        - `controller.has_rumble`: return whether the controller supports rumbling or not
        - `controller.has_led`: return whether the program will be able to set the led or not, this might also return `False` because of permission issues. See the LED section below.
        - `controller.info()`: print some debug info, collected from the attributes stated above
        - `controller.set_rumble(left, right, duration=1000)`: set the left and right rumbling strength for a given duration to the given percentage (`0.0`-`1.0`)
        - `controller.set_led(status)`: set the LED circle's status, available are listed above
        - `controller.close()`: close all open file objects, recommended for cleanup if not using the `with` statement.
        
        `button` is an instance of `Button` and one of `controller.button_a`, `controller.button_b`, `controller.button_x`, `controller.button_y`, `controller.button_trigger_l`,  `controller.button_trigger_r`, `controller.button_thumb_l`, `controller.button_thumb_r`, `controller.button_select`, `controller.button_start`, `controller.button_mode`.
        
        - `button.when_pressed`: holds callable object to be called when the button is pressed
        - `button.when_released`: holds callable object to be called when the button is released
        - `button.is_pressed`: holds boolean whether the button is currently pressed or not
        
        `axis` is an instance of `Axis` and one of `controller.axis_l`, `controller.axis_r`, `controller.hat`
        
        - `axis.when_moved`: holds callable object to be called when the axis is moved
        - `axis.x`: holds the X value of the axis
        - `axis.y`: holds the Y value of the axis
        
        The axis values will be one of `1`, `0` or `-1`; from top to bottom or right to left.
        
        `axis` is an instance of `RawAxis` and one of `controller.trigger_l`, `controller.trigger_r`
        
        - `axis.when_moved`: holds callable object to be called when the axis is moved
        - `axis.value`: holds the value of the axis
        
        Advised to being used for internal stuff only, until properly documented:
        
        - `controller.get_event()`: return the most recent controller event as a `ControllerEvent`
        - `controller.process_event(event)`: process a `ControllerEvent` and update the controller's input device instances
        
        ### Debug information
        
        ```python
        from xbox360controller import Xbox360Controller
        
        with Xbox360Controller() as controller:
            controller.info()
        ```
        
        ## Development/contributing
        
        This project is still in its early days and I really appreciate all kinds of contributions - may it be new or improved code, documentation or just a simple typo fix.
        Just provide me a PR and I'll be happy to include your work!
        
        For feature requests, general questions or problems you face regarding this package please [open an issue](https://github.com/linusg/xbox360controller/issues/new).
        
        ## Release History
        
        Please see [`CHANGES.md`](https://github.com/linusg/xbox360controller/blob/master/CHANGES.md) for a complete release history.
        
        ## Authors
        
        - Linus Groh ([**@linusg**](https://github.com/linusg/)) – mail@linusgroh.de
        
        ## License
        
        All the code and documentation are distributed under the MIT license. See [`LICENSE`](https://github.com/linusg/xbox360controller/blob/master/LICENSE) for more information.
        
        [pypi-image]: https://img.shields.io/pypi/v/xbox360controller.svg?style=flat-square
        [pypi-url]: https://pypi.org/project/xbox360controller/
        [travis-image]: https://img.shields.io/travis/linusg/xbox360controller/master.svg?style=flat-square
        [travis-url]: https://travis-ci.org/linusg/xbox360controller
        [landscape-image]: https://landscape.io/github/linusg/xbox360controller/master/landscape.svg?style=flat-square
        [landscape-url]: https://landscape.io/github/linusg/xbox360controller
        
        
Keywords: xbox,xbox360,controller,gamepad,game,raspberry pi,event,led,rumble
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: Utilities
