XboxControllerPy

[ 中文文档 ]

A Python package for reading and handling Xbox controller input using pygame.

Features

• 🎮 Easy Xbox controller connection and management
• 🕹️ Real-time joystick and button state reading
• 🔫 Trigger button support
• 🎯 Event-based input handling
• 📦 Simple and intuitive API
• 🔧 Context manager support for automatic cleanup
• 🌍 Multi-language support (English and Chinese)

Installation

From PyPI (when published)

pip install xbox-controller-py

From Source

git clone https://github.com/cnctem/XboxControllerPy.git
cd XboxControllerPy
pip install -e .

Requirements

• Python 3.6+
• pygame 2.0.0+

Quick Start

Basic Usage

from xbox_controller import XboxController
import time

# Create controller instance
controller = XboxController()

# Connect to controller
controller.connect()

# Get controller info
info = controller.get_controller_info()
print(f"Connected to: {info['name']}")

# Read controller state
while True:
    state = controller.update_state()
    print(f"Left Stick: {state['left_joystick']}")
    print(f"Right Stick: {state['right_joystick']}")
    print(f"Triggers: {state['triggers']}")
    print(f"Buttons: {state['pressed_buttons']}")
    time.sleep(0.1)

# Disconnect when done
controller.disconnect()

Context Manager (Recommended)

from xbox_controller import XboxController

# Automatic connection and cleanup
with XboxController() as controller:
    info = controller.get_controller_info()
    print(f"Device: {info['name']}")
    
    # Use controller...
    state = controller.get_state()
    # Controller automatically disconnects when exiting the context

API Reference

XboxController Class

Methods

• connect(controller_index=0): Connect to Xbox controller
• disconnect(): Disconnect from controller
• get_controller_info(): Get controller information
• update_state(): Update and get current controller state
• get_state(): Get current controller state without updating
• get_formatted_state(): Get formatted controller state for display

Properties

• connected: Boolean indicating connection status

Utility Functions

• format_axis_value(value): Format axis value to 3 decimal places
• get_controller_state(joystick, buttons, axes): Get state from raw data
• get_button_name(button_id): Get button name from ID
• get_pressed_button_names(buttons): Get list of pressed button names

Examples

Check out the examples/ directory for more detailed examples:

• basic_usage.py: Basic controller reading
• context_manager.py: Using context manager
• event_handling.py: Event-based input handling

Run examples:

python examples/basic_usage.py
python examples/context_manager.py
python examples/event_handling.py

Controller Layout

Button Mapping

• Buttons 0-3: A, B, X, Y
• Buttons 4-5: LB, RB (Shoulder buttons)
• Buttons 6-7: Back, Start
• Buttons 8-9: Left Stick, Right Stick (Click)
• Buttons 12-15: D-pad (Up, Down, Left, Right)

Axis Mapping

• Axes 0-1: Left Joystick (X, Y)
• Axes 2-3: Right Joystick (X, Y)
• Axes 4-5: Left Trigger, Right Trigger

Error Handling

The package includes proper error handling for common scenarios:

try:
    controller = XboxController()
    controller.connect()
    # Use controller...
except SystemExit as e:
    print(f"Connection error: {e}")
except Exception as e:
    print(f"Error: {e}")
finally:
    controller.disconnect()

Development

Setup Development Environment

git clone https://github.com/cnctem/XboxControllerPy.git
cd XboxControllerPy
pip install -e .[dev]

Running Tests

pytest

Code Formatting

black xbox_controller/
flake8 xbox_controller/

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Basic controller connection and state reading
• Context manager support
• Event handling examples
• Multi-language documentation

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check existing issues for solutions
• Review the examples in the examples/ directory

Roadmap

• Support for multiple controllers
• Advanced vibration/haptic feedback
• Configuration file support
• GUI control panel
• Web-based controller monitor
• Support for other controller types