pybricks._common.IMU: Add rotation and orientation.

Also update implementation status for heading and reset_heading.

CHANGELOG.md

@@ -10,6 +10,11 @@
 - 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.
+
+### Changed
+- Change implementation status of `IMU.heading` and `IMU.reset_heading`. They
+  are now implemented, with some limitations as noted in a note box.
 
 ## 3.2.0 - 2022-12-20
 

doc/main/hubs/essentialhub.rst

@@ -37,6 +37,10 @@ Essential Hub
 
     .. automethod:: pybricks.hubs::EssentialHub.imu.reset_heading
 
+    .. automethod:: pybricks.hubs::EssentialHub.imu.rotation
+
+    .. automethod:: pybricks.hubs::EssentialHub.imu.orientation
+
     .. rubric:: Using the battery
 
     .. automethod:: pybricks.hubs::EssentialHub.battery.voltage

doc/main/hubs/primehub.rst

@@ -71,6 +71,10 @@ Prime Hub / Inventor Hub
 
     .. automethod:: pybricks.hubs::PrimeHub.imu.reset_heading
 
+    .. automethod:: pybricks.hubs::PrimeHub.imu.rotation
+
+    .. automethod:: pybricks.hubs::PrimeHub.imu.orientation
+
     .. rubric:: Using the speaker
 
     .. automethod:: pybricks.hubs::PrimeHub.speaker.volume

doc/main/hubs/technichub.rst

@@ -33,6 +33,10 @@ Technic Hub
 
     .. automethod:: pybricks.hubs::TechnicHub.imu.reset_heading
 
+    .. automethod:: pybricks.hubs::TechnicHub.imu.rotation
+
+    .. automethod:: pybricks.hubs::TechnicHub.imu.orientation
+
     .. rubric:: Using the battery
 
     .. automethod:: pybricks.hubs::TechnicHub.battery.voltage

jedi/tests/test_complete_essential_hub.py

@@ -79,7 +79,9 @@ def test_hub_dot_imu_dot():
         "acceleration",
         "angular_velocity",
         "heading",
+        "orientation",
         "reset_heading",
+        "rotation",
         "tilt",
         "up",
     ]

jedi/tests/test_complete_prime_hub.py

@@ -97,7 +97,9 @@ def test_hub_dot_imu_dot():
         "acceleration",
         "angular_velocity",
         "heading",
+        "orientation",
         "reset_heading",
+        "rotation",
         "tilt",
         "up",
     ]

jedi/tests/test_complete_technic_hub.py

@@ -67,7 +67,9 @@ def test_hub_dot_imu_dot():
         "acceleration",
         "angular_velocity",
         "heading",
+        "orientation",
         "reset_heading",
+        "rotation",
         "tilt",
         "up",
     ]

jedi/tests/test_get_signature.py

@@ -308,12 +308,19 @@ METHOD_PARAMS = [
         [(["axis: Axis"], "float"), ([], "Matrix")],
     ),
     pytest.param("pybricks.hubs", "TechnicHub", "imu.heading", [([], "float")]),
+    pytest.param("pybricks.hubs", "TechnicHub", "imu.orientation", [([], "Matrix")]),
     pytest.param(
         "pybricks.hubs",
         "TechnicHub",
         "imu.reset_heading",
         [(["angle: Number"], "None")],
     ),
+    pytest.param(
+        "pybricks.hubs",
+        "TechnicHub",
+        "imu.rotation",
+        [(["axis: Axis"], "float")],
+    ),
     pytest.param("pybricks.hubs", "TechnicHub", "battery.voltage", [([], "int")]),
     pytest.param("pybricks.hubs", "TechnicHub", "battery.current", [([], "int")]),
     pytest.param(
@@ -400,12 +407,19 @@ METHOD_PARAMS = [
         [(["axis: Axis"], "float"), ([], "Matrix")],
     ),
     pytest.param("pybricks.hubs", "PrimeHub", "imu.heading", [([], "float")]),
+    pytest.param("pybricks.hubs", "PrimeHub", "imu.orientation", [([], "Matrix")]),
     pytest.param(
         "pybricks.hubs",
         "PrimeHub",
         "imu.reset_heading",
         [(["angle: Number"], "None")],
     ),
+    pytest.param(
+        "pybricks.hubs",
+        "PrimeHub",
+        "imu.rotation",
+        [(["axis: Axis"], "float")],
+    ),
     pytest.param(
         "pybricks.hubs",
         "PrimeHub",
@@ -483,12 +497,19 @@ METHOD_PARAMS = [
         [(["axis: Axis"], "float"), ([], "Matrix")],
     ),
     pytest.param("pybricks.hubs", "EssentialHub", "imu.heading", [([], "float")]),
+    pytest.param("pybricks.hubs", "EssentialHub", "imu.orientation", [([], "Matrix")]),
     pytest.param(
         "pybricks.hubs",
         "EssentialHub",
         "imu.reset_heading",
         [(["angle: Number"], "None")],
     ),
+    pytest.param(
+        "pybricks.hubs",
+        "EssentialHub",
+        "imu.rotation",
+        [(["axis: Axis"], "float")],
+    ),
     pytest.param("pybricks.hubs", "EssentialHub", "battery.voltage", [([], "int")]),
     pytest.param("pybricks.hubs", "EssentialHub", "battery.current", [([], "int")]),
     pytest.param("pybricks.hubs", "EssentialHub", "charger.connected", [([], "bool")]),

src/pybricks/_common.py

@@ -983,7 +983,7 @@ class Accelerometer(SimpleAccelerometer):
         along the x-axis.
 
         Returns:
-            Tuple of pitch and roll angles.
+            Tuple of pitch and roll angles in degrees.
         """
 
 
@@ -998,7 +998,18 @@ class IMU(Accelerometer):
         For a vehicle viewed from the top, this means that
         a positive heading value corresponds to a counterclockwise rotation.
 
-        .. note:: This method is not yet implemented.
+        The heading value continously increments as the robot keeps turning. It
+        does *not* wrap around after reaching 180 degrees.
+
+        .. note:: *For now, this method only keeps track of the heading while
+                  the robot is on a flat surface.*
+
+                  This means that the value is
+                  no longer correct if you lift it from the table. To solve
+                  this, you can call ``reset_heading`` to reset the heading to
+                  a known value *after* you put it back down. For example, you
+                  could align your robot with the side of the competition table
+                  and reset the heading 90 degrees as the new starting point.
 
         Returns:
             Heading angle relative to starting orientation.
@@ -1010,8 +1021,6 @@ class IMU(Accelerometer):
 
         Resets the accumulated heading angle of the robot.
 
-        .. note:: This method is not yet implemented.
-
         Arguments:
             angle (Number, deg): Value to which the heading should be reset.
         """
@@ -1040,6 +1049,41 @@ class IMU(Accelerometer):
             this returns a vector of accelerations along all axes.
         """
 
+    def rotation(self, axis: Axis) -> float:
+        """
+        rotation(axis) -> float: deg
+
+        Gets the rotation of the device along a given axis in
+        the :ref:`robot reference frame <robotframe>`.
+
+        This value is useful if your robot *only* rotates along the requested
+        axis. For general three-dimensional motion, use the
+        ``orientation()`` method instead.
+
+        The value starts counting from ``0`` when you initialize this class.
+
+        Arguments:
+            axis (Axis): Axis along which the rotation should be measured.
+        Returns:
+            The rotation angle.
+        """
+
+    def orientation(self) -> Matrix:
+        """
+        orientation() -> Matrix
+
+        Gets the three-dimensional orientation of the robot in
+        the :ref:`robot reference frame <robotframe>`.
+
+        It returns a rotation matrix whose columns represent the ``X``, ``Y``,
+        and ``Z`` axis of the robot.
+
+        .. note:: This method is not yet implemented.
+
+        Returns:
+            The rotation matrix.
+        """
+
 
 class CommonColorSensor:
     """Generic color sensor that supports Pybricks color calibration."""