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 @@
+
+
\ 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 @@
+
+
\ 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 @@
+
+
\ 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