pybricks.common.IMU: Simplify tilt and up.

When writing the API docs, I realized it was not easy to explain. Instead of having two kwargs to get three options, now use a single kwarg for only two options: Either fully raw or fully fused.

Author: laurensvalk

CHANGELOG.md

@@ -5,10 +5,13 @@
 ## [Unreleased]
 
 ### Changed
-- Changed order of the `DriveBase.arc` method. This method has not yet been
-  released or documented, so this is not a breaking change ([support#1157]).
+- Changed order of the `DriveBase.arc` method parameters. This method has not
+  yet been released or documented, so this is not a breaking change ([support#1157]).
 - Reduced voltage threshold at which the charging light goes from red to green
   to indicate that the battery is full from 8300 to 8190 mV ([pybricks-micropython#292]).
+- Simplified API for `hub.imu.up()` and `hub.imu.tilt()` to only use a single
+  `calibrated` keyword argument instead of separate `use_gyro` options. This
+  had not been released yet so is not a breaking change.
 
 ## [3.6.0b4] - 2025-02-14
 
@@ -31,13 +34,15 @@
   scale and acceleration offset and scale.
 - Added `hub.system.reset_storage` to restore storage and settings to default
   state.
+- Replaced `update_heading_correction` with `_imu_calibrate.py` for 3D
+  calibration ([support#1907]).
 
 ### Changed
 - Enabled UTF-8 support for `str` objects.
 - The method `DriveBase.angle()` now returns a float ([support#1844]). This
   makes it properly equivalent to `hub.imu.heading`.
 - Re-implemented tilt using the gyro data by default. Pure accelerometer tilt
-  can still be obtained with `hub.imu.tilt(use_gyro=False)`.
+  can still be obtained with `hub.imu.tilt(calibrated=False)`.
 - Re-implemented `hub.imu.heading()` to use optionally use the projection of 3D
   orientation to improve performance when the hub is lifted off the ground.
   The 1D-based heading remains the default for now.
@@ -67,6 +72,7 @@
 [support#943]: https://github.com/pybricks/support/issues/943
 [support#1886]: https://github.com/pybricks/support/issues/1886
 [support#1844]: https://github.com/pybricks/support/issues/1844
+[support#1907]: https://github.com/pybricks/support/issues/1907
 [support#1975]: https://github.com/pybricks/support/issues/1975
 [support#1996]: https://github.com/pybricks/support/issues/1996
 [support#2055]: https://github.com/pybricks/support/issues/2055
@@ -151,7 +157,7 @@
 - Allow gyro calibration only while all motors are coasting ([support#1840]) to
   prevent recalibration during very steady moves ([support#1687])
 - Reduced default angular velocity stationary threshold from an undocumented
-  5 deg/s to 3 deg/s to reduce unwanted calibration while moving ([support#1105]).
+  5 deg/s to 2 deg/s to reduce unwanted calibration while moving ([support#1105]).
 - If `imu.reset_heading()` is called while a drive base is actively using the
   gyro, an exception will be raised ([support#1818]).
 

bricks/primehub/modules/_imu_calibrate.py

@@ -16,7 +16,7 @@ def beep(freq):
 
 
 def wait_for_stationary(side):
-    while not hub.imu.stationary() or hub.imu.up() != side:
+    while not hub.imu.stationary() or hub.imu.up(calibrated=False) != side:
         wait(10)
 
 
@@ -42,7 +42,7 @@ def roll_over_axis(axis, new_side):
     print("Roll it towards you, without lifting the hub up!")
 
     angle_start = hub.imu.rotation(axis, calibrated=False)
-    while hub.imu.up() != new_side or not hub.imu.stationary():
+    while hub.imu.up(calibrated=False) != new_side or not hub.imu.stationary():
 
         _, _, z = hub.imu.orientation() * axis
         if abs(z) > 0.07:

lib/pbio/src/imu.c

@@ -590,7 +590,8 @@ void pbio_imu_get_acceleration(pbio_geometry_xyz_t *values, bool calibrated) {
 }
 
 /**
- * Gets the vector that is parallel to the acceleration measurement of the stationary case.
+ * Gets the tilt-based vector that is parallel to the acceleration measurement
+ * if we were stationary.
  *
  * @param [out] values      The acceleration vector.
  */
@@ -639,17 +640,25 @@ pbio_error_t pbio_imu_get_single_axis_rotation(pbio_geometry_xyz_t *axis, float
 /**
  * Gets which side of a hub points upwards.
  *
- * @param [in]  calibrated  Whether to use calibrated or uncalibrated data.
+ * @param [in]  calibrated  Whether to use calibrated/fused (true) or raw data (false).
  *
  * @return                  Which side is up.
  */
 pbio_geometry_side_t pbio_imu_get_up_side(bool calibrated) {
     // Up is which side of a unit box intersects the +Z vector first.
     // So read +Z vector of the inertial frame, in the body frame.
-    // For now, this is the gravity vector. In the future, we can make this
-    // slightly more accurate by using the full IMU orientation.
-    pbio_geometry_xyz_t *acceleration = calibrated ? &acceleration_calibrated : &acceleration_uncalibrated;
-    return pbio_geometry_side_from_vector(acceleration);
+    // This is either the raw acceleration or the third row of the fused
+    // rotation matrix.
+
+    pbio_geometry_xyz_t *vector = &acceleration_uncalibrated;
+    if (calibrated) {
+        // This is similar to pbio_imu_get_tilt_vector, but this should stay
+        // in the hub frame rather than projected into user frame.
+        vector->x = pbio_imu_rotation.m31;
+        vector->y = pbio_imu_rotation.m32;
+        vector->z = pbio_imu_rotation.m33;
+    }
+    return pbio_geometry_side_from_vector(vector);
 }
 
 static float heading_offset_1d = 0;

pybricks/common/pb_type_imu.c

@@ -60,17 +60,16 @@ static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_imu_up_obj, 1, pb_type_imu_up);
 static mp_obj_t pb_type_imu_tilt(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     PB_PARSE_ARGS_METHOD(n_args, pos_args, kw_args,
         pb_type_imu_obj_t, self,
-        PB_ARG_DEFAULT_TRUE(use_gyro),
         PB_ARG_DEFAULT_TRUE(calibrated));
 
     (void)self;
 
     // Read acceleration in the user frame.
     pbio_geometry_xyz_t accl;
-    if (mp_obj_is_true(use_gyro_in)) {
+    if (mp_obj_is_true(calibrated_in)) {
         pbio_imu_get_tilt_vector(&accl);
     } else {
-        pbio_imu_get_acceleration(&accl, mp_obj_is_true(calibrated_in));
+        pbio_imu_get_acceleration(&accl, false);
     }
 
     mp_obj_t tilt[2];
@@ -187,10 +186,10 @@ static mp_obj_t pb_type_imu_settings(size_t n_args, const mp_obj_t *pos_args, mp
         pb_type_imu_obj_t, self,
         PB_ARG_DEFAULT_NONE(angular_velocity_threshold),
         PB_ARG_DEFAULT_NONE(acceleration_threshold),
+        PB_ARG_DEFAULT_NONE(heading_correction),
         PB_ARG_DEFAULT_NONE(angular_velocity_bias),
         PB_ARG_DEFAULT_NONE(angular_velocity_scale),
-        PB_ARG_DEFAULT_NONE(acceleration_correction),
-        PB_ARG_DEFAULT_NONE(heading_correction));
+        PB_ARG_DEFAULT_NONE(acceleration_correction));
 
     (void)self;
 
@@ -308,7 +307,6 @@ static mp_obj_t pb_type_imu_heading(size_t n_args, const mp_obj_t *pos_args, mp_
         PBIO_IMU_HEADING_TYPE_3D : PBIO_IMU_HEADING_TYPE_1D;
 
     return mp_obj_new_float(pbio_imu_get_heading(type));
-    ;
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_imu_heading_obj, 1, pb_type_imu_heading);