DOCSEARCHbyAlgolia
Submit Docs

pydualsense

repository·master·Indexed 41 days ago

https://github.com/flok/pydualsense

A Python library for interacting with PlayStation 5 DualSense controllers. It allows developers to read controller button states, analog trigger values, and motion data (gyro/accelerometer), as well as control hardware features including haptics, rumble motors, adaptive triggers, and LED colors. The library features an event-driven system for managing input callbacks and requires hidapi for operation on Windows and Linux.

Tokens
6.2K
Snippets
26
Records
37
Agent score
50%

What's inside pydualsense

  1. Overview of pydualsense

    master

    pydualsense is a Python library designed for interacting with the PlayStation 5 DualSense controller. It provides functionality to:

    • Read the current state of the controller (inputs, sensors, etc.).
    • Update controller settings, such as trigger effects and other hardware options.

  2. Overview of the pydualsense package structure

    master

    The pydualsense package is organized into several specialized submodules that handle different aspects of interacting with the DualSense controller:

    • pydualsense.enums: Contains enumeration types used for controller states, settings, and commands.
    • pydualsense.event_system: Manages the event-driven architecture for handling controller inputs and notifications.
    • pydualsense.hidguardian: Provides functionality related to HID (Human Interface Device) management, likely for handling device access or conflicts.
    • pydualsense.pydualsense: The core module containing the primary controller interface and logic.

  3. How the pydualsense event system works

    master
    The Event System in pydualsense is responsible for managing and dispatching button callbacks. It allows you to register functions that are automatically triggered when specific input events (like button presses or releases) occur on the DualSense controller. This system decouples the low-level input detection from your application logic by providing a structured way to handle user interactions via callbacks.

  4. Use pydualsense enums to update controller state

    master
    The pydualsense.enums module contains the enumeration classes used throughout the library. These enums are passed as parameters to various functions to define and update the state of the DualSense controller (e.g., setting specific haptic patterns, LED colors, or trigger modes).

  5. Handle controller input events

    master

    The pydualsense class features an event-based system that allows you to register callback functions to monitor changes in input states. You can use the += operator to attach listeners to specific event attributes.

    Available Event Types

    • Buttons: triangle_pressed, circle_pressed, cross_pressed, square_pressed.
    • D-pad: dpad_up, dpad_down, dpad_left, dpad_right.
    • Triggers: l1_changed, l2_changed, l3_changed, r1_changed, r2_changed, r3_changed, l2_value_changed, r2_value_changed.
    • Motion: gyro_changed, accelerometer_changed.
    • Joysticks: left_joystick_changed, right_joystick_changed.
    • Other: ps_pressed, touch_pressed, microphone_pressed, share_pressed, option_pressed.

    Usage Example

    # Monitor button presses
def on_circle_pressed(state):
    print(f"Circle button {'pressed' if state else 'released'}")

ds.circle_pressed += on_circle_pressed

# Monitor trigger analog values
def on_l2_value_changed(value):
    print(f"L2 trigger value: {value}")

ds.l2_value_changed += on_l2_value_changed

# Monitor motion data
def on_gyro_changed(pitch, yaw, roll):
    print(f"Gyro: P={pitch}, Y={yaw}, R={roll}")

ds.gyro_changed += on_gyro_changed

  6. Install pydualsense on Linux

    master

    Installing on Linux requires setting up udev rules for hardware access and installing the hidapi development headers.

    1. Configure udev rules to allow non-root access to the controller:
      sudo cp 70-ps5-controller.rules /etc/udev/rules.d
sudo udevadm control --reload-rules
sudo udevadm trigger
    2. **Install hidapi development files**. On Ubuntu/Debian systems, use:
   ```bash
sudo apt install libhidapi-dev
    1. Install the Python package:
      pip install --upgrade pydualsense
    sudo apt install libhidapi-dev
pip install --upgrade pydualsense

  9. Initialize the pydualsense controller

    master

    To use the DualSense controller, you must first create an instance of the pydualsense class and call its .init() method to establish a connection.

    from pydualsense import pydualsense

# Create controller instance
ds = pydualsense()

# Initialize connection
ds.init()
    from pydualsense import pydualsense

# Create controller instance
ds = pydualsense()
    
# Initialize connection
ds.init()

  12. Initialize and connect to a DualSense controller

    master

    To use the library, instantiate the pydualsense class and then call the .init() method. The .init() method performs device discovery, determines the connection type (USB or Bluetooth), and starts a background thread to handle input/output reports.

    Note: You must call .init() to connect; the constructor only initializes the library object.

    from pydualsense import pydualsense

# Initialize the library object
dualsense = pydualsense(verbose=False)

# Connect to the controller
dualsense.init()

# ... use the controller ...

# Always close the connection when finished
dualsense.close()