From 2d0cf6c28c2afd679d377e1e544d3b3cd9eca94e Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Thu, 21 Mar 2024 17:06:41 +0100 Subject: [PATCH] pybricks.iodevices.XboxController: Add rumble. --- .../pybricks_blockGamepadRumble_default.svg | 989 ++++++++++++++++++ ...s_blockGamepadRumble_default_with_list.svg | 989 ++++++++++++++++++ ...bricks_blockGamepadRumble_with_options.svg | 989 ++++++++++++++++++ doc/main/iodevices/xboxcontroller.rst | 12 + src/pybricks/iodevices.py | 45 +- 5 files changed, 3020 insertions(+), 4 deletions(-) create mode 100644 doc/main/blockimg/pybricks_blockGamepadRumble_default.svg create mode 100644 doc/main/blockimg/pybricks_blockGamepadRumble_default_with_list.svg create mode 100644 doc/main/blockimg/pybricks_blockGamepadRumble_with_options.svg diff --git a/doc/main/blockimg/pybricks_blockGamepadRumble_default.svg b/doc/main/blockimg/pybricks_blockGamepadRumble_default.svg new file mode 100644 index 0000000..4ffee22 --- /dev/null +++ b/doc/main/blockimg/pybricks_blockGamepadRumble_default.svg @@ -0,0 +1,989 @@ + +controller100%200msrumble atfor \ No newline at end of file diff --git a/doc/main/blockimg/pybricks_blockGamepadRumble_default_with_list.svg b/doc/main/blockimg/pybricks_blockGamepadRumble_default_with_list.svg new file mode 100644 index 0000000..5bdbc92 --- /dev/null +++ b/doc/main/blockimg/pybricks_blockGamepadRumble_default_with_list.svg @@ -0,0 +1,989 @@ + +controller5001000list with200msrumble atfor \ No newline at end of file diff --git a/doc/main/blockimg/pybricks_blockGamepadRumble_with_options.svg b/doc/main/blockimg/pybricks_blockGamepadRumble_with_options.svg new file mode 100644 index 0000000..d649829 --- /dev/null +++ b/doc/main/blockimg/pybricks_blockGamepadRumble_with_options.svg @@ -0,0 +1,989 @@ + +controller100%200msrumble atfor1times with pause100ms \ No newline at end of file diff --git a/doc/main/iodevices/xboxcontroller.rst b/doc/main/iodevices/xboxcontroller.rst index 8e7a1c2..f5522f3 100644 --- a/doc/main/iodevices/xboxcontroller.rst +++ b/doc/main/iodevices/xboxcontroller.rst @@ -18,6 +18,8 @@ Xbox Controller Buttons include: * ``Button.A``, ``Button.B``, ``Button.X``, ``Button.Y``. + * ``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`` (bumpers). * ``Button.LJ`` and ``Button.RJ`` (pressing the joysticks). * ``Button.VIEW``, ``Button.MENU``, ``Button.GUIDE`` (the Xbox logo), and ``Button.UPLOAD``. @@ -54,6 +56,16 @@ Xbox Controller .. automethod:: pybricks.iodevices::XboxController.profile + .. blockimg:: pybricks_blockGamepadRumble_default + + .. blockimg:: pybricks_blockGamepadRumble_default_with_list + :stack: + + .. blockimg:: pybricks_blockGamepadRumble_with_options + :stack: + + .. automethod:: pybricks.iodevices::XboxController.rumble + .. _xbox-controller-pairing: Xbox Controller Pairing Instructions diff --git a/src/pybricks/iodevices.py b/src/pybricks/iodevices.py index 10343a8..068ad9f 100644 --- a/src/pybricks/iodevices.py +++ b/src/pybricks/iodevices.py @@ -12,6 +12,7 @@ from .parameters import Port as _Port if TYPE_CHECKING: from ._common import MaybeAwaitable, MaybeAwaitableTuple + from .parameters import Number class PUPDevice: @@ -384,12 +385,17 @@ class XboxController: def dpad(self) -> int: """dpad() -> int - Gets the direction-pad position. ``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. + 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. + Direction-pad position, indicating a direction. """ def profile(self) -> int: @@ -402,8 +408,39 @@ class XboxController: Profile number. """ + def rumble( + self, + power: Number | Tuple[Number, Number, Number, Number] = 100, + duration: int = 200, + count: int = 1, + delay: int = 100, + ) -> MaybeAwaitable: + """rumble(power=100, duration=200, count=1, delay=100) + + Makes the builtin actuators rumble, creating force feedback. + + If you give a single ``power`` value, the left and right main actuators + will both rumble with that power. For more fine-grained control, set + ``power`` as a tuple of four values, which control the left main + actuator, right main actuator, left trigger actuator, and the right + trigger actuator, respectively. For example, ``power=(0, 0, 100, 0)`` + makes the left trigger rumble at full power. + + The rumble runs in the background while your program continues. To + make your program wait, just pause the program for a matching duration. + For one rumble, this equals ``duration``. For multiple rumbles, this + equals ``count * (duration + delay)``. + + Arguments: + power (Number, % or tuple): Rumble power. + duration (Number, ms): Rumble duration. + count (int): Rumble count. + delay (Number, ms): Delay before each rumble. Only if ``count > 1``. + """ + # hide from jedi if TYPE_CHECKING: del MaybeAwaitable del MaybeAwaitableTuple + del Number