Robot Control Library
IMU_MPU

Description

A userspace C interface for the invensense MPU6050, MPU6500, MPU9150, and MPU9250.

<rc/mpu.h>

This API allows the user to configure this IMU in two modes: NORMAL and DMP

Normal Mode

The accelerometer, gyroscope, magnetometer, and thermometer can be read directly at any time. To use this mode, call rc_mpu_initialize() with your imu_config and imu_data structs as arguments as defined below. You can then call rc_mpu_read_accel, rc_mpu_read_gyro, rc_mpu_read_mag, or rc_mpu_read_temp at any time to get the latest sensor values.

DMP Mode

Stands for Digital Motion Processor which is a feature of the MPU9250. in this mode, the DMP will sample the sensors internally and fill a FIFO buffer with the data at a fixed rate. Furthermore, the DMP will also calculate a filtered orientation quaternion which is placed in the same buffer. When new data is ready in the buffer, the IMU sends an interrupt to the BeagleBone triggering the buffer read followed by the execution of a function of your choosing set with the rc_mpu_set_dmp_callback() function.

Author
James Strawson
Date
1/19/2018

Data Structures

struct  rc_mpu_config_t
 configuration of the mpu sensor More...
 
struct  rc_mpu_data_t
 data struct populated with new sensor data More...
 

Macros

#define RC_MPU_DEFAULT_I2C_ADDR   0x68
 default i2c address if AD0 is left low More...
 
#define RC_MPU_ALT_I2C_ADDR   0x69
 alternate i2c address if AD0 pin pulled high More...
 
#define TB_PITCH_X   0
 Index of the dmp_TaitBryan[] array corresponding to the Pitch (X) axis. More...
 
#define TB_ROLL_Y   1
 Index of the dmp_TaitBryan[] array corresponding to the Roll (Y) axis. More...
 
#define TB_YAW_Z   2
 Index of the dmp_TaitBryan[] array corresponding to the Yaw (Z) axis. More...
 
#define QUAT_W   0
 First index of the dmp_quat[] quaternion vector. More...
 
#define QUAT_X   1
 Second index of the dmp_quat[] quaternion vector. More...
 
#define QUAT_Y   2
 Third index of the dmp_quat[] quaternion vector. More...
 
#define QUAT_Z   3
 Fourth index of the dmp_quat[] quaternion vector. More...
 
#define DEG_TO_RAD   0.0174532925199
 multiply to convert degrees to radians More...
 
#define RAD_TO_DEG   57.295779513
 multiply to convert radians to degrees More...
 
#define MS2_TO_G   0.10197162129
 multiply to convert m/s^2 to G More...
 
#define G_TO_MS2   9.80665
 multiply to convert G to m/s^2, standard gravity definition More...
 

Typedefs

typedef enum rc_mpu_accel_fsr_t rc_mpu_accel_fsr_t
 accelerometer full scale range options More...
 
typedef enum rc_mpu_gyro_fsr_t rc_mpu_gyro_fsr_t
 gyroscope full scale range options More...
 
typedef enum rc_mpu_accel_dlpf_t rc_mpu_accel_dlpf_t
 accelerometer digital low-pass filter options More...
 
typedef enum rc_mpu_gyro_dlpf_t rc_mpu_gyro_dlpf_t
 gyroscope digital low-pass filter options More...
 
typedef enum rc_mpu_orientation_t rc_mpu_orientation_t
 Orientation of the sensor. More...
 
typedef struct rc_mpu_config_t rc_mpu_config_t
 configuration of the mpu sensor More...
 
typedef struct rc_mpu_data_t rc_mpu_data_t
 data struct populated with new sensor data More...
 

common functions

rc_mpu_config_t rc_mpu_default_config (void)
 Returns an rc_mpu_config_t struct with default settings. More...
 
int rc_mpu_set_config_to_default (rc_mpu_config_t *conf)
 Resets a config struct to defaults. More...
 
int rc_mpu_power_off (void)
 Powers off the MPU. More...
 

normal one-shot sampling functions

int rc_mpu_initialize (rc_mpu_data_t *data, rc_mpu_config_t conf)
 Sets up the MPU in normal one-shot sampling mode. More...
 
int rc_mpu_read_accel (rc_mpu_data_t *data)
 Reads accelerometer data from the MPU. More...
 
int rc_mpu_read_gyro (rc_mpu_data_t *data)
 Reads gyroscope data from the MPU. More...
 
int rc_mpu_read_temp (rc_mpu_data_t *data)
 Reads thermometer data from the MPU. More...
 
int rc_mpu_read_mag (rc_mpu_data_t *data)
 Reads magnetometer data from the MPU. More...
 

interrupt-driven DMP mode functions

int rc_mpu_initialize_dmp (rc_mpu_data_t *data, rc_mpu_config_t conf)
 Initializes the MPU in DMP mode, see rc_test_dmp example. More...
 
int rc_mpu_set_dmp_callback (void(*func)(void))
 Sets the callback function that will be triggered when new DMP data is ready. More...
 
int rc_mpu_block_until_dmp_data (void)
 blocking function that returns once new DMP data is available More...
 
int64_t rc_mpu_nanos_since_last_dmp_interrupt (void)
 calculates number of nanoseconds since the last DMP interrupt More...
 
int rc_mpu_set_tap_callback (void(*func)(int direction, int counter))
 sets the callback function triggered when a tap is detected More...
 
int rc_mpu_block_until_tap (void)
 blocking function that returns when a tap is detected More...
 
int64_t rc_mpu_nanos_since_last_tap (void)
 calculates nanoseconds since last tap was detected More...
 

calibration functions

int rc_mpu_calibrate_gyro_routine (rc_mpu_config_t conf)
 Runs gyroscope calibration routine. More...
 
int rc_mpu_calibrate_mag_routine (rc_mpu_config_t conf)
 Runs magnetometer calibration routine. More...
 
int rc_mpu_calibrate_accel_routine (rc_mpu_config_t conf)
 Runs accelerometer calibration routine. More...
 
int rc_mpu_is_gyro_calibrated (void)
 Checks if a gyro calibration file is saved to disk. More...
 
int rc_mpu_is_mag_calibrated (void)
 Checks if a magnetometer calibration file is saved to disk. More...
 
int rc_mpu_is_accel_calibrated (void)
 Checks if an accelerometer calibration file is saved to disk. More...
 

Macro Definition Documentation

◆ RC_MPU_DEFAULT_I2C_ADDR

#define RC_MPU_DEFAULT_I2C_ADDR   0x68

default i2c address if AD0 is left low

◆ RC_MPU_ALT_I2C_ADDR

#define RC_MPU_ALT_I2C_ADDR   0x69

alternate i2c address if AD0 pin pulled high

◆ TB_PITCH_X

#define TB_PITCH_X   0

Index of the dmp_TaitBryan[] array corresponding to the Pitch (X) axis.

Examples:
rc_balance.c, and rc_test_dmp.c.

◆ TB_ROLL_Y

#define TB_ROLL_Y   1

Index of the dmp_TaitBryan[] array corresponding to the Roll (Y) axis.

Examples:
rc_test_dmp.c.

◆ TB_YAW_Z

#define TB_YAW_Z   2

Index of the dmp_TaitBryan[] array corresponding to the Yaw (Z) axis.

Examples:
rc_test_dmp.c.

◆ QUAT_W

#define QUAT_W   0

First index of the dmp_quat[] quaternion vector.

Examples:
rc_test_dmp.c.

◆ QUAT_X

#define QUAT_X   1

Second index of the dmp_quat[] quaternion vector.

Examples:
rc_test_dmp.c.

◆ QUAT_Y

#define QUAT_Y   2

Third index of the dmp_quat[] quaternion vector.

Examples:
rc_test_dmp.c.

◆ QUAT_Z

#define QUAT_Z   3

Fourth index of the dmp_quat[] quaternion vector.

Examples:
rc_test_dmp.c.

◆ DEG_TO_RAD

#define DEG_TO_RAD   0.0174532925199

multiply to convert degrees to radians

Examples:
rc_test_mpu.c.

◆ RAD_TO_DEG

#define RAD_TO_DEG   57.295779513

multiply to convert radians to degrees

Examples:
rc_test_dmp.c.

◆ MS2_TO_G

#define MS2_TO_G   0.10197162129

multiply to convert m/s^2 to G

Examples:
rc_test_mpu.c.

◆ G_TO_MS2

#define G_TO_MS2   9.80665

multiply to convert G to m/s^2, standard gravity definition

Enumeration Type Documentation

◆ rc_mpu_accel_fsr_t

accelerometer full scale range options

The user may choose from 4 full scale ranges of the accelerometer and gyroscope. They have units of gravity (G) and degrees per second (DPS) The defaults values are A_FSR_2G and G_FSR_2000DPS respectively.

Enumerator
ACCEL_FSR_2G 
ACCEL_FSR_4G 
ACCEL_FSR_8G 
ACCEL_FSR_16G 

◆ rc_mpu_gyro_fsr_t

gyroscope full scale range options

The user may choose from 4 full scale ranges of the accelerometer and gyroscope. They have units of gravity (G) and degrees per second (DPS) The defaults values are A_FSR_2G and G_FSR_2000DPS respectively.

Enumerator
GYRO_FSR_250DPS 
GYRO_FSR_500DPS 
GYRO_FSR_1000DPS 
GYRO_FSR_2000DPS 

◆ rc_mpu_accel_dlpf_t

accelerometer digital low-pass filter options

The user may choose from 7 digital low pass filter constants for the accelerometer and gyroscope. The filter runs at 1kz and helps to reduce sensor noise when sampling more slowly. The default values are ACCEL_DLPF_184 GYRO_DLPF_184. Lower cut-off frequencies incur phase-loss in measurements. Number is cutoff frequency in hz.

Enumerator
ACCEL_DLPF_OFF 
ACCEL_DLPF_460 
ACCEL_DLPF_184 
ACCEL_DLPF_92 
ACCEL_DLPF_41 
ACCEL_DLPF_20 
ACCEL_DLPF_10 
ACCEL_DLPF_5 

◆ rc_mpu_gyro_dlpf_t

gyroscope digital low-pass filter options

The user may choose from 7 digital low pass filter constants for the accelerometer and gyroscope. The filter runs at 1kz and helps to reduce sensor noise when sampling more slowly. The default values are ACCEL_DLPF_184 GYRO_DLPF_184. Lower cut-off frequencies incur phase-loss in measurements. Number is cutoff frequency in hz.

Enumerator
GYRO_DLPF_OFF 
GYRO_DLPF_250 
GYRO_DLPF_184 
GYRO_DLPF_92 
GYRO_DLPF_41 
GYRO_DLPF_20 
GYRO_DLPF_10 
GYRO_DLPF_5 

◆ rc_mpu_orientation_t

Orientation of the sensor.

This is only applicable when operating in DMP mode. This is the orientation that the DMP consideres neutral, aka where roll/pitch/yaw are zero.

Enumerator
ORIENTATION_Z_UP 
ORIENTATION_Z_DOWN 
ORIENTATION_X_UP 
ORIENTATION_X_DOWN 
ORIENTATION_Y_UP 
ORIENTATION_Y_DOWN 
ORIENTATION_X_FORWARD 
ORIENTATION_X_BACK 

Function Documentation

◆ rc_mpu_default_config()

rc_mpu_config_t rc_mpu_default_config ( void  )

Returns an rc_mpu_config_t struct with default settings.

Use this as a starting point and modify as you wish.

Returns
Returns an rc_mpu_config_t struct with default settings.
Examples:
rc_altitude.c, rc_balance.c, rc_calibrate_accel.c, rc_calibrate_gyro.c, rc_calibrate_mag.c, rc_test_dmp.c, rc_test_dmp_tap.c, and rc_test_mpu.c.

◆ rc_mpu_set_config_to_default()

int rc_mpu_set_config_to_default ( rc_mpu_config_t conf)

Resets a config struct to defaults.

Parameters
[out]confPointer to config struct to be overwritten
Returns
0 on success or -1 on failure.

◆ rc_mpu_power_off()

int rc_mpu_power_off ( void  )

Powers off the MPU.

Only call this after powering on the MPU with rc_mpu_initialize or rc_mpu_initialize_dmp. This should geenrally be called at the end of your main function to make sure the MPU is put to sleep.

Returns
0 on success or -1 on failure.
Examples:
rc_altitude.c, rc_balance.c, rc_test_dmp.c, rc_test_dmp_tap.c, and rc_test_mpu.c.

◆ rc_mpu_initialize()

int rc_mpu_initialize ( rc_mpu_data_t data,
rc_mpu_config_t  conf 
)

Sets up the MPU in normal one-shot sampling mode.

First create an instance of the rc_mpu_data_t struct and pass its pointer to rc_mpu_initialize which will then write to. Also pass an rc_mpu_config_t struct with your configruation settings.

This function will populate the accel_to_ms2 and gyro_to_deg fields of the rc_mpu_data_t struct appropriately based on the user-configured full scale ranges.

After this, you may read sensor data at any time with the functions rc_mpu_read_accel(), rc_mpu_read_gyro(), and rc_mpu_read_temp(). The magentometer can also be read with rc_mpu_read_mag() if using an MPU9150 or MPU9250 and the enable_magnetometer field in the rc_mpu_config_t struct has been set to 1.

Be sure to power off the MPU at the end of your program with rc_mpu_power_off().

Parameters
datapointer to user's data struct
[in]confuser congiguration data
Returns
0 on success or -1 on failure.
Examples:
rc_test_mpu.c.

◆ rc_mpu_read_accel()

int rc_mpu_read_accel ( rc_mpu_data_t data)

Reads accelerometer data from the MPU.

Parameters
dataPointer to user's data struct where new data will be written
Returns
0 on success or -1 on failure.
Examples:
rc_test_mpu.c.

◆ rc_mpu_read_gyro()

int rc_mpu_read_gyro ( rc_mpu_data_t data)

Reads gyroscope data from the MPU.

Parameters
dataPointer to user's data struct where new data will be written
Returns
0 on success or -1 on failure.
Examples:
rc_test_mpu.c.

◆ rc_mpu_read_temp()

int rc_mpu_read_temp ( rc_mpu_data_t data)

Reads thermometer data from the MPU.

Note this is the internal termperature of the chip, not abient temperature.

Parameters
dataPointer to user's data struct where new data will be written
Returns
0 on success or -1 on failure.
Examples:
rc_test_dmp.c, and rc_test_mpu.c.

◆ rc_mpu_read_mag()

int rc_mpu_read_mag ( rc_mpu_data_t data)

Reads magnetometer data from the MPU.

Note this requires use of an MPU9150 or MPU9250, the MPU6050 and MPU6500 do not have magnetometers. Additionally, the enable_magnetometer flag must has been set in the user's rc_mpu_config_t when it was passed to rc_mpu_initialize()

Parameters
dataPointer to user's data struct where new data will be written
Returns
0 on success or -1 on failure.
Examples:
rc_test_mpu.c.

◆ rc_mpu_initialize_dmp()

int rc_mpu_initialize_dmp ( rc_mpu_data_t data,
rc_mpu_config_t  conf 
)

Initializes the MPU in DMP mode, see rc_test_dmp example.

After calling this the user does not need to call the normal read functions rc_mpu_read_accel(), rc_mpu_read_gyro(), or rc_mpu_read mag(). Instead the data will automatically be read into the user's data struct at the dmp_sample_rate set in the config struct.

Parameters
dataPointer to user's data struct where new data will be written
[in]confUser's configuration struct
Returns
0 on success or -1 on failure.
Examples:
rc_altitude.c, rc_balance.c, rc_test_dmp.c, and rc_test_dmp_tap.c.

◆ rc_mpu_set_dmp_callback()

int rc_mpu_set_dmp_callback ( void(*)(void)  func)

Sets the callback function that will be triggered when new DMP data is ready.

Parameters
[in]funcuser's callback function
Returns
0 on success or -1 on failure.
Examples:
rc_altitude.c, rc_balance.c, and rc_test_dmp.c.

◆ rc_mpu_block_until_dmp_data()

int rc_mpu_block_until_dmp_data ( void  )

blocking function that returns once new DMP data is available

Returns
Returns 0 once new data is available, 1 if the MPU is shutting down due to rc_mpu_power_off, or -1 on error.

◆ rc_mpu_nanos_since_last_dmp_interrupt()

int64_t rc_mpu_nanos_since_last_dmp_interrupt ( void  )

calculates number of nanoseconds since the last DMP interrupt

Returns
nanoseconds since last interrupt, or -1 if no interrupt received yet.

◆ rc_mpu_set_tap_callback()

int rc_mpu_set_tap_callback ( void(*)(int direction, int counter)  func)

sets the callback function triggered when a tap is detected

Parameters
[in]funcuser's callback function
Returns
0 on success or -1 on failure.
Examples:
rc_test_dmp_tap.c.

◆ rc_mpu_block_until_tap()

int rc_mpu_block_until_tap ( void  )

blocking function that returns when a tap is detected

Returns
Returns 0 once a tap is detected, 1 if the MPU is shutting down due to rc_mpu_power_off(), or -1 on error.

◆ rc_mpu_nanos_since_last_tap()

int64_t rc_mpu_nanos_since_last_tap ( void  )

calculates nanoseconds since last tap was detected

Returns
nanoseconds since last tap, or -1 if no tap has been detected yet.

◆ rc_mpu_calibrate_gyro_routine()

int rc_mpu_calibrate_gyro_routine ( rc_mpu_config_t  conf)

Runs gyroscope calibration routine.

This should generally not be used by the user unless they absolutely want to calibrate the gyroscope inside their own program. Instead call the rc_calibrate_gyro example program.

Parameters
[in]confConfig struct, only used to configure i2c bus and address.
Returns
0 on success, -1 on failure
Examples:
rc_balance.c, and rc_calibrate_gyro.c.

◆ rc_mpu_calibrate_mag_routine()

int rc_mpu_calibrate_mag_routine ( rc_mpu_config_t  conf)

Runs magnetometer calibration routine.

This should generally not be used by the user unless they absolutely want to calibrate the magnetometer inside their own program. Instead call the rc_calibrate_mag example program.

Parameters
[in]confConfig struct, only used to configure i2c bus and address.
Returns
0 on success, -1 on failure
Examples:
rc_calibrate_mag.c.

◆ rc_mpu_calibrate_accel_routine()

int rc_mpu_calibrate_accel_routine ( rc_mpu_config_t  conf)

Runs accelerometer calibration routine.

This should generally not be used by the user unless they absolutely want to calibrate the accelerometer inside their own program. Instead call the rc_calibrate_accel example program.

Parameters
[in]confConfig struct, only used to configure i2c bus and address.
Returns
0 on success, -1 on failure
Examples:
rc_calibrate_accel.c.

◆ rc_mpu_is_gyro_calibrated()

int rc_mpu_is_gyro_calibrated ( void  )

Checks if a gyro calibration file is saved to disk.

generally used to warn the user that they are running a program without calibration. Can also be used to decide if calibration should be done at the beginning of user's program.

Returns
1 if calibrated, 0 if not
Examples:
rc_balance.c.

◆ rc_mpu_is_mag_calibrated()

int rc_mpu_is_mag_calibrated ( void  )

Checks if a magnetometer calibration file is saved to disk.

generally used to warn the user that they are running a program without calibration. Can also be used to decide if calibration should be done at the beginning of user's program.

Returns
1 if calibrated, 0 if not

◆ rc_mpu_is_accel_calibrated()

int rc_mpu_is_accel_calibrated ( void  )

Checks if an accelerometer calibration file is saved to disk.

generally used to warn the user that they are running a program without calibration. Can also be used to decide if calibration should be done at the beginning of user's program.

Returns
1 if calibrated, 0 if not