v4.1.1

doc/common/extensions/requirements-static.py

@@ -56,7 +56,14 @@ HUB_FEATURES = {
         "hub-network",
     }
     | FEATURES_MEDIUM,
-    "ev3brick": {"ev3devices", "nxtdevices", "image", "hub-network"} | FEATURES_MEDIUM,
+    "ev3brick": {
+        "ev3devices",
+        "nxtdevices",
+        "image",
+        "hub-network",
+        "playstation-controller",
+    }
+    | FEATURES_MEDIUM,
 }
 
 

doc/main/index.rst

@@ -23,14 +23,10 @@ Pybricks Reference Manual
              learn more about Pybricks and to start coding, visit
              the `Pybricks website`_
 
-   .. note:: Are you using LEGO MINDSTORMS EV3? Check out the
-            `EV3 documentation`_ instead.
-
 Click on any device below to see its documentation. Use the menu on the left
 to find documentation for additional modules. You may need to click the ☰ icon
 above to reveal this menu.
 
-.. _EV3 documentation: https://pybricks.com/ev3-micropython/
 .. _Pybricks website: https://pybricks.com/
 .. _Pybricks learn: https://pybricks.com/learn/
 

doc/main/iodevices/index.rst

@@ -13,8 +13,9 @@ Wireless devices
    :hidden:
 
    xboxcontroller
+   playstationcontroller
 
-.. pybricks-requirements:: pybricks-iodevices
+.. pybricks-requirements:: xbox-controller
 
 .. pybricks-classlink:: XboxController
 
@@ -22,6 +23,10 @@ Wireless devices
    :width: 40 %
    :target: xboxcontroller.html
 
+.. pybricks-requirements:: playstation-controller
+
+.. pybricks-classlink:: PlayStationController
+
 LEGO protocol devices
 ---------------------
 

doc/main/iodevices/playstationcontroller.rst

@@ -0,0 +1,81 @@
+.. pybricks-requirements:: playstation-controller
+
+PlayStation Controller
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. blockimg:: pybricks_variables_set_xbox_controller
+
+.. autoclass:: pybricks.iodevices.PlayStationController
+  :no-members:
+
+  .. automethod:: pybricks.iodevices::PlayStationController.name
+
+  .. blockimg:: pybricks_blockButtonIsPressed_XboxController
+
+  .. automethod:: pybricks.iodevices::PlayStationController.buttons.pressed
+
+    Buttons include:
+
+      * ``Button.A`` (cross), ``Button.B`` (circle), ``Button.X`` (square),
+        and ``Button.Y`` (triangle).
+      * ``Button.UP``, ``Button.DOWN``, ``Button.LEFT``, ``Button.RIGHT``
+        (direction pad). At most two of these can be pressed at the same time.
+      * ``Button.LB`` and ``Button.RB`` (L1 and R1).
+      * ``Button.LJ`` and ``Button.RJ`` (L3 and R3, pressing the joysticks).
+      * ``Button.VIEW`` (share or create), ``Button.MENU`` (options),
+        ``Button.GUIDE`` (the PlayStation logo), and ``Button.UPLOAD``
+        (pressing the touchpad).
+
+    .. note:: The buttons are currently reported using the names of the
+       equivalent buttons on the Xbox controller, as listed above. This will
+       change in a future version.
+
+  .. blockimg:: pybricks_blockJoystickValue_xbox_lj_x
+
+  .. blockimg:: pybricks_blockJoystickValue_xbox_lj_y
+
+  .. automethod:: pybricks.iodevices::PlayStationController.joystick_left
+
+  .. blockimg:: pybricks_blockJoystickValue_xbox_rj_x
+
+  .. blockimg:: pybricks_blockJoystickValue_xbox_rj_y
+
+  .. automethod:: pybricks.iodevices::PlayStationController.joystick_right
+
+  .. blockimg:: pybricks_blockJoystickValue_xbox_lt
+
+  .. blockimg:: pybricks_blockJoystickValue_xbox_rt
+
+  .. automethod:: pybricks.iodevices::PlayStationController.triggers
+
+  .. blockimg:: pybricks_blockJoystickValue_xbox_dpad
+
+  .. automethod:: pybricks.iodevices::PlayStationController.dpad
+
+.. _playstation-controller-pairing:
+
+PlayStation Controller Pairing Instructions
+===========================================
+
+The first time you use a controller with a hub, you will need to pair them
+using the hub menu:
+
+1. On the hub, go to the settings tab and choose ``Add new gamepad``.
+2. Put the controller in pairing mode: press and hold the share (or create)
+   button and the PlayStation button at the same time until the light starts
+   flashing rapidly.
+3. Select the controller on the hub when it appears in the list.
+
+When the connection is successful, the light on the controller stops flashing.
+You can now start your program. Only one controller can be connected at a
+time.
+
+Repeat Connections
+------------------
+
+If you keep using the same controller with the same hub, you can simply
+press the PlayStation button on the controller the next time and it will
+connect to the hub automatically.
+
+If you connect the controller to your console or to another device in the
+meantime, you will need to pair it with the hub again as described above.

jedi/tests/test_complete_import.py

@@ -108,6 +108,7 @@ def test_from_pybricks_iodevices_import():
         "I2CDevice",
         "LUMPDevice",
         "LWP3Device",
+        "PlayStationController",
         "PUPDevice",
         "UARTDevice",
         "XboxController",

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "4.1.0"
+version = "4.1.1"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
 authors = ["The Pybricks Authors <team@pybricks.com>"]
 maintainers = ["Laurens Valk <laurens@pybricks.com>", "David Lechner <david@pybricks.com>" ]

src/pybricks/iodevices.py

@@ -574,7 +574,7 @@ class XboxController:
         """
 
     def joystick_left(self) -> tuple[int, int]:
-        """joystick_left() -> tuple
+        """joystick_left() -> tuple[int, int]: %
 
         Gets the left joystick position as percentages between -100%
         and 100%. The center position is (0, 0). A square deadzone is applied:
@@ -588,7 +588,7 @@ class XboxController:
         """
 
     def joystick_right(self) -> tuple[int, int]:
-        """joystick_right() -> tuple
+        """joystick_right() -> tuple[int, int]: %
 
         Gets the right joystick position as percentages between -100%
         and 100%. The center position is (0, 0). A square deadzone is applied:
@@ -602,7 +602,7 @@ class XboxController:
         """
 
     def triggers(self) -> tuple[int, int]:
-        """triggers() -> tuple
+        """triggers() -> tuple[int, int]: %
 
         Gets the left and right trigger positions as percentages between 0%
         and 100%.
@@ -683,6 +683,110 @@ class XboxController:
         """
 
 
+class PlayStationController:
+    """Use a Sony® PlayStation® controller as a sensor in your projects to
+    control them remotely.
+
+    This has been tested on the DUALSHOCK®4 wireless controller for
+    PlayStation®4 and the DualSense™ wireless controller for PlayStation®5, but
+    similar gamepads may also work.
+
+    Pair the controller in the hub menu first. When your program
+    runs, it uses the controller that is currently connected.
+
+    For tips on connectivity and pairing, see
+    :ref:`below <playstation-controller-pairing>`.
+
+    .. versionadded:: 4.1
+    """
+
+    buttons = _common.Keypad([])
+
+    def __init__(self, joystick_deadzone: int = 10):
+        """__init__(joystick_deadzone=10)
+
+        Arguments:
+            joystick_deadzone (Number, %): Joystick deadzone (0 to 100). Values
+                below this threshold in both axes will be reported as 0 to
+                prevent stick drift.
+
+        Raises:
+            OSError: If the controller is not connected.
+        """
+
+    def name(self) -> str | None:
+        """name() -> str | None
+
+        Gets the Bluetooth name of the connected controller.
+
+        Returns:
+            Bluetooth name of the controller, or ``None`` if it is not known.
+
+        Raises:
+            OSError: If the controller is not connected.
+        """
+
+    def joystick_left(self) -> tuple[int, int]:
+        """joystick_left() -> tuple[int, int]: %
+
+        Gets the left joystick position as percentages between -100%
+        and 100%. The center position is (0, 0). A square deadzone is applied:
+        if both axes are within the deadzone, both are reported as 0.
+
+        Returns:
+            Tuple of X (horizontal) and Y (vertical) position.
+
+        Raises:
+            OSError: If the controller is not connected.
+        """
+
+    def joystick_right(self) -> tuple[int, int]:
+        """joystick_right() -> tuple[int, int]: %
+
+        Gets the right joystick position as percentages between -100%
+        and 100%. The center position is (0, 0). A square deadzone is applied:
+        if both axes are within the deadzone, both are reported as 0.
+
+        Returns:
+            Tuple of X (horizontal) and Y (vertical) position.
+
+        Raises:
+            OSError: If the controller is not connected.
+        """
+
+    def triggers(self) -> tuple[int, int]:
+        """triggers() -> tuple[int, int]: %
+
+        Gets the left (L2) and right (R2) trigger positions as percentages
+        between 0% and 100%.
+
+        Returns:
+            Tuple of left and right trigger positions.
+
+        Raises:
+            OSError: If the controller is not connected.
+        """
+
+    def dpad(self) -> int:
+        """dpad() -> int
+
+        Gets the direction-pad value. ``1`` is up, ``2`` is up-right, ``3``
+        is right, ``4`` is down-right, ``5`` is down, ``6`` is down-left,
+        ``7`` is left, ``8`` is up-left, and ``0`` is not pressed.
+
+        This is essentially the same as reading the state of the
+        ``Button.UP``, ``Button.RIGHT``, ``Button.DOWN``, and ``Button.LEFT``
+        buttons, but this method conveniently returns a number that indicates
+        a direction.
+
+        Returns:
+            Direction-pad position, indicating a direction.
+
+        Raises:
+            OSError: If the controller is not connected.
+        """
+
+
 # Hide type-only names from jedi completions in the module namespace.
 if TYPE_CHECKING:
     del MaybeAwaitable