Inertial Motion Unit

This section describes the functions for using the built-in Inertial Motion Unit (IMU).

Yozh contains a built-in Inertial Motion Unit (IMU), which is based on ICM42688 chip from TDK Invensense. This chip combines a 3-axis accelerometer and a 3-axis gyro sensor, which provide information about acceleration and rotational speed. Yozh firmware processes the sensor data to provide information about robot’s orientation in space, in the form of Yaw, Pitch, and Roll angles. (Yozh firmware is based on the work of Kris Winer and uses data fusion algorithm invented by Sebastian Madgwick.)

Below is the description of functions related to IMU. You can also check sample code in imu_test example sketch included with Yozh CircuitPython library.

Initialization

By default, the IMU is active. To stop/restart it, use the functions below.

IMU_stop(): Stop the IMU

IMU_start(): Restart the IMU

IMU_status()

Returns IMU status. This function can be used to verify that IMU activation was successful. Possible values are:

0: IMU is inactive
1: IMU is active
2: IMU is currently in the process of calibration

Calibration

Before use, the IMU needs to be calibrated. The calibration process determines and then applies corrections (offsets) to the raw data; without these corrections, the data returned by the sensor is very inaccurate.

If you haven’t calibrated the sensor before (or want to recalibrate it), use the following function:

IMU_calibrate()

This function will determine and apply the corrections; it will also save these corrections in the flash storage of the Yozh secondary microcontroller, where they will be stored for future use. This data is preserved even after you power off the robot (much like the usual USB flash drive).

This function will take about 10 seconds to execute; during this time, the robot must be completely stationary on a flat horizontal surface.

If you had previously calibrated the sensor, you do not need to repeat the calibration process - by default, upon initialization the IMU loads previously saved calibration values.

Note that the IMU is somewhat sensitive to temperature changes, so if the temperature changes (e.g., you moved your robot from indoors to the street for testing), it is advised that you recalibrate the IMU.

Reading Values

Yozh allows you to read both the raw data (accelerometer and gyro readings) and computed orientation, using the following functions:

void IMU_get_accel(): Fetches from the sensor raw acceleration data and saves it using member variables ax, ay, az, which give the acceleration in x-, y-, and z- directions respectively in in units of 1g (9.81 m/sec^2) as floats.

void IMU_get_gyro(): Fetches from the sensor raw gyro data and saves it using member variables gx, gy, gz, which give the angular rotation velocity around x-, y-, and z- axes respectively, in degree/s (as floats).

float IMU_yaw()

float IMU_pitch()

float IMU_roll()

These functions return yaw, pitch, and roll angles for the robot, in degrees. These three angles determine the robot orientation as described below:

yaw is the rotation around the vertical axis (positive angle corresponds to clockwise rotation, i.e. right turns). Note that zero value is rather random (it is not the starting position of the robot!)
pitch is the rotation around the horizontal line, running from left to right. Positive pitch angle corresponds to raising the front of the robot and lowering the back
roll is the rotation around the horizontal line running from front to back. Positive roll angle corresponds to raising the left side of the robot and lowering the right.

For more information about yaw, pitch, and roll angles, please visit https://en.wikipedia.org/wiki/Aircraft_principal_axes

normalize(angle)
A helper function; adds or subtracts 360 to the angle as needed to bring it to the range
[-180,180]. Useful for computing difference of headings, e.g.

start_yaw = bot.IMU_yaw()
# some driving instructiosn here
angle_turned = bot.normalize(bot.IMU_yaw()-start_yaw) # angle will be between -180 and 180