pybricks._common.IMU: Add imu status.

CHANGELOG.md

@@ -10,7 +10,8 @@
 - Documented ``integral_deadzone`` in ``Control.pid()``.
 - Documented ``Motor.model``. This can be used to view the estimated motor
   state and change its settings.
-- Added `rotation` and `orientation` methods to `IMU` class.
+- Added `rotation`, `orientation`, `ready`, `stationary`
+  and `set_stationary_thresholds`  methods to `IMU` class.
 
 ### Changed
 - Change implementation status of `IMU.heading` and `IMU.reset_heading`. They

doc/main/hubs/essentialhub.rst

@@ -25,6 +25,12 @@ Essential Hub
 
     .. rubric:: Using the IMU
 
+    .. automethod:: pybricks.hubs::EssentialHub.imu.ready
+
+    .. automethod:: pybricks.hubs::EssentialHub.imu.stationary
+
+    .. automethod:: pybricks.hubs::EssentialHub.imu.set_stationary_thresholds
+
     .. automethod:: pybricks.hubs::EssentialHub.imu.up
 
     .. automethod:: pybricks.hubs::EssentialHub.imu.tilt

doc/main/hubs/primehub.rst

@@ -59,6 +59,12 @@ Prime Hub / Inventor Hub
 
     .. rubric:: Using the IMU
 
+    .. automethod:: pybricks.hubs::PrimeHub.imu.ready
+
+    .. automethod:: pybricks.hubs::PrimeHub.imu.stationary
+
+    .. automethod:: pybricks.hubs::PrimeHub.imu.set_stationary_thresholds
+
     .. automethod:: pybricks.hubs::PrimeHub.imu.up
 
     .. automethod:: pybricks.hubs::PrimeHub.imu.tilt

doc/main/hubs/technichub.rst

@@ -21,6 +21,12 @@ Technic Hub
 
     .. rubric:: Using the IMU
 
+    .. automethod:: pybricks.hubs::TechnicHub.imu.ready
+
+    .. automethod:: pybricks.hubs::TechnicHub.imu.stationary
+
+    .. automethod:: pybricks.hubs::TechnicHub.imu.set_stationary_thresholds
+
     .. automethod:: pybricks.hubs::TechnicHub.imu.up
 
     .. automethod:: pybricks.hubs::TechnicHub.imu.tilt

jedi/tests/test_complete_essential_hub.py

@@ -80,8 +80,11 @@ def test_hub_dot_imu_dot():
         "angular_velocity",
         "heading",
         "orientation",
+        "ready",
         "reset_heading",
         "rotation",
+        "set_stationary_thresholds",
+        "stationary",
         "tilt",
         "up",
     ]

jedi/tests/test_complete_prime_hub.py

@@ -98,8 +98,11 @@ def test_hub_dot_imu_dot():
         "angular_velocity",
         "heading",
         "orientation",
+        "ready",
         "reset_heading",
         "rotation",
+        "set_stationary_thresholds",
+        "stationary",
         "tilt",
         "up",
     ]

jedi/tests/test_complete_technic_hub.py

@@ -68,8 +68,11 @@ def test_hub_dot_imu_dot():
         "angular_velocity",
         "heading",
         "orientation",
+        "ready",
         "reset_heading",
         "rotation",
+        "set_stationary_thresholds",
+        "stationary",
         "tilt",
         "up",
     ]

src/pybricks/_common.py

@@ -988,6 +988,54 @@ class Accelerometer(SimpleAccelerometer):
 
 
 class IMU(Accelerometer):
+    def ready(self) -> bool:
+        """ready() -> bool
+
+        Checks if the device is calibrated and ready for use.
+
+        This becomes ``True`` when the robot has been sitting stationary for a
+        few seconds, which allows the device to re-calibrate. It is ``False``
+        if the hub has just been started, or if it hasn't had a chance to
+        calibrate for more than 10 minutes.
+
+        Returns:
+            ``True`` if it is ready for use, ``False`` if not.
+        """
+
+    def stationary(self) -> bool:
+        """stationary() -> bool
+
+        Checks if the device is currently stationary (not moving).
+
+        Returns:
+            ``True`` if stationary for at least a second, ``False`` if it is
+            moving.
+        """
+
+    def set_stationary_thresholds(
+        self, angular_velocity: float, acceleration: float
+    ) -> None:
+        """set_stationary_thresholds(angular_velocity, acceleration)
+
+        When the angular velocity and acceleration measurements are below the
+        given threshold values for at least one second, the sensor is
+        considered stationary. This is when the sensor recalibrates itself.
+
+        If you are in a noisy room with high ambient vibrations (such as a
+        robot competition hall), it is recommended to increase these values
+        slightly to give your robot the chance to calibrate properly.
+
+        To verify that your settings are working, test that
+        the ``stationary()`` method gives ``False`` if your robot is moving,
+        and ``True`` if it is sitting still for at least a second.
+
+        Arguments:
+            angular_velocity (Number, deg/s): The threshold for angular
+                velocity. The default value is 1.5 deg/s.
+            acceleration (Number, mm/s²): The threshold for angular
+                velocity. The default value is 250 mm/s².
+        """
+
     def heading(self) -> float:
         """heading() -> float: deg