[Feature] IMU API ideas

[laurensvalk]

Now that we are working on the IMU, we can have a closer look at what the existing and new methods in the IMU API must do.

In particular, we have to choose where and when we want to use:

• 1D vs. 3D orientation
• Fusion vs. no fusion with accelerometer/gyro data

heading()
This seems to be mostly used in 1D applications like a DriveBase. Proposal: 1D, no fusion

In a horizontal 1D application, fusion with the accelerometer has only downsides, so the proposed variant makes it numerically the most accurate/stable. See #989

As a downside, you'd get less accuracy if you do robot missions with ramps. We could either add a keyword argument like heading(fusion=False) or instead recommend that users use the rotation() method below if they need full 3D-based heading. Thoughts?

This 1D-no-fusion variant is usually also the most useful for things like balancers. You could use the heading around Z to drive and use the "heading" around X or Y for balance. So there could be a keyword-argument with heading(axis=Axis.X), only this makes "heading" a bit of a misnomer (?).

tilt()
We could potentially keep this as-is (accelerometer only), or optionally use the fused result. With accelerometer only, the advantage is that it always works, regardless of initial conditions, drift, and so on. The fused result would respond faster, but you could argue that you could use the method below if you really need that.

orientation()
This is a new method. This would give the fused, 3D orientation in a non-singular representation.

This is useful for free motion application (build your own drone, etc), at the price of reduced accuracy when used in pure 1D application.

I think returning the rotation matrix is the most useful, but we could alternatively return the internally used quaternion or MRP.

The user can still use this to derive "heading-based-on-3d-with-fusion" in just a few lines.

# Find out which way the hub X-axis is pointing in the world frame.
cx, cy, cz = hub.imu.orientation() * Axis.X

# The angle that this line makes on the plane is the heading.
fused_heading = atan2(cy, cx)

Assuming we make examples like this, we could consider keeping heading and tilt rather simple (non-fused) as shown above.

Sidenote... if anyone was wondering why we had the geometry module, now you know. This has been the plan all along -- a simple but effective way to manipulate orientation information.

[laurensvalk]

This is what the additional methods could look like. All existing methods remain unchanged.

The rotation method is useful for things like balancers so you don't have to run your own integration loop.

The orientation method is for power users who want to use tilt without singularities. Build your own drone. As a more down-to-earth example, this is useful for building a tilt remote. You could do orientation() * Axis.Z to find out which way an "antenna" on top of the hub is pointing. The x and y values of the resulting vector are good indicators of the "joystick" position, without ever becoming singular.