14. API - Inertial Measurement Unit (IMU)

The Inertial Measurement Unit (IMU) on the Sense HAT has myriad uses in all sorts of projects from High Altitude Balloon (HAB) flights, robotics, detecting magnetic fields, or making novel user interfaces. It is represented in pisense by the SenseIMU class, and provides readings as IMUState, IMUVector and IMUOrient tuples.

14.1. SenseIMU

class pisense.SenseIMU(settings=None, emulate=False)[source]

The SenseIMU class represents the Inertial Measurement Unit (IMU) on the Sense HAT. Users can either instantiate the class themselves, or can access an instance from SenseHAT.imu.

The settings parameter can be used to point to alternate settings files but it is strongly recommended you leave this at the default as this can affect the calibration of the IMU.

If the emulate parameter is True, the instance will connect to the IMU in the desktop Sense HAT emulator instead of the “real” Sense HAT IMU.

close()[source]

Call the close() method to close the inertial measurement unit interface and free up any background resources. The method is idempotent (you can call it multiple times without error) and after it is called, any operations on the inertial measurement unit may return an error (but are not guaranteed to do so).

read()[source]

Return the current state of the inertial measurement unit as an IMUState tuple.

Note

This method will wait until the next set of readings are available, and then return them. Hence it is suitable for use in a loop without additional waits, although it may be simpler to simply treat the instance as an iterator in that case.

This is in contrast to reading the gyro, accel, compass, and orient attributes which always return immediately.

accel

Return the current reading from the accelerometer as a 3-dimensional IMUVector tuple. The reading is measured in standard gravities.

compass

Return the current reading from the magnetometer as a 3-dimensional IMUVector tuple. The reading is measured in in µT (micro-teslas).

gyro

Return the current reading from the gyroscope as a 3-dimensional IMUVector tuple. The reading is measured in radians-per-second.

name

Returns the name of the IMU chip. On the Sense HAT this should always be “LSM9DS1”.

orient

Return the current calculated orientation of the board as a IMUOrient tuple containing roll, pitch, and yaw in radians.

Note

The sensors that are used in determining the orientation are specified in the sensors property.

The orientation of the board is only calculated when the sensors are read. The drift of certain sensors (the gyroscope in particular) mean that reading the orientation more frequently can result in greater accuracy.

rotation

Specifies the rotation about the Z axis applied to IMU readings as a multiple of 90 degrees. When rotation is 0 (the default), positive X is toward the joystick, and positive Y is away from the GPIO pins:

_images/rotation_0.svg

When rotation is 90, positive X is toward the GPIO pins, and positive Y is toward the joystick:

_images/rotation_90.svg

The other two rotations are trivial to derive from this.

Note

This property is updated by the unifying SenseHAT.rotation attribute.

sensors

Controls which sensors are used for calculating the orient property.

14.2. IMUState

class pisense.IMUState(compass, gyro, accel, orient)[source]

A namedtuple() representing a single reading from the Inertial Measurement Unit (IMU). The fields are as follows:

compass

An IMUVector tuple containing the raw values from the magnetometer in µT (micro-teslas).

gyro

An IMUVector tuple containing the raw values from the gyroscope in radians / second.

accel

An IMUVector tuple containing the raw values from the accelerometer in standard gravities (g).

orient

The orientation of the HAT, as calculated from the three sensors, presented as an IMUOrient instance.

14.3. IMUVector

class pisense.IMUVector(x, y, z)[source]

A namedtuple() representing a three-dimensional vector with x, y, and z components. This is used to represent the output of the three IMU sensors (magnetometer, gryoscope, and accelerometer).

Attention

TODO Add HAT-specific vector directions diagram

14.4. IMUOrient

class pisense.IMUOrient(roll, pitch, yaw)[source]

A namedtuple() representing the orientation of the Sense HAT in radians (though the display is provided in degrees for human convenience) as roll, pitch, and yaw.

Attention

TODO add HAT-specific roll, pitch, yaw diagram

14.5. SenseSettings

class pisense.SenseSettings(settings_file=None, emulate=False)[source]

Represents the calibration settings for the Sense HAT.

The settings_file refers to the INI-style file containing all calibration settings for the Sense HAT. For no particularly good reason, the underlying library requires that this filename ends with ‘.ini’.

Warning

If the specified file does not exist, it will be created with default calibration settings. Hence you should ensure that the location specified either exists or is writeable by the current user. Furthermore, if the file successfully loads the underlying library will attempt to overwrite it with “cleaned” values. If you wish to keep modifications to the file (comments, etc.) ensure that the file is effectively read-only for the executing user.

Yes, this is a ridiculous requirement and while I would dearly love to re-write this chunk of the underlying library, it’s not something I have time for currently!

settings

Returns the underlying RTIMULib settings object.