Skip to content

README.md

Latest commit

 

History

History
204 lines (154 loc) · 4.71 KB

README.md

File metadata and controls

204 lines (154 loc) · 4.71 KB

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