![]() |
MBot Software Library
v1.0
An API documentation to mbot_firmware repository
|
A userspace C interface for the invensense MPU6050, MPU6500, MPU9150, and MPU9250. More...
Classes | |
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 | ARRAY_SIZE(array) sizeof(array)/sizeof(array[0]) |
#define | min(a, b) ((a < b) ? a : b) |
#define | __unused __attribute__ ((unused)) |
#define | unlikely(x) __builtin_expect (!!(x), 0) |
#define | likely(x) __builtin_expect (!!(x), 1) |
#define | FLASH_TARGET_OFFSET (PICO_FLASH_SIZE_BYTES - FLASH_SECTOR_SIZE) |
#define | FIFO_LEN_QUAT_TAP 20 |
#define | FIFO_LEN_QUAT_ACCEL_GYRO_TAP 32 |
#define | MAX_FIFO_BUFFER (FIFO_LEN_QUAT_ACCEL_GYRO_TAP*5) |
#define | QUAT_ERROR_THRESH (1L<<16) |
#define | QUAT_MAG_SQ_NORMALIZED (1L<<28) |
#define | QUAT_MAG_SQ_MIN (QUAT_MAG_SQ_NORMALIZED - QUAT_ERROR_THRESH) |
#define | QUAT_MAG_SQ_MAX (QUAT_MAG_SQ_NORMALIZED + QUAT_ERROR_THRESH) |
#define | GYRO_CAL_THRESH 50 |
#define | ACCEL_CAL_THRESH 100 |
#define | GYRO_OFFSET_THRESH 500 |
#define | DMP_AUTO_CAL_GYRO 0 |
#define | DMP_FETCH_ACCEL_GYRO 0 |
#define | DMP_INIT_ORIENTATION ORIENTATION_Z_UP |
#define | DMP_TAP_THRESHOLD 210 |
#define | DMP_CFG_SAMPLE_RATE 100 |
#define | DMP_ENABLE_MAGNETOMETER 0 |
#define | DEBUG_OUTPUT 0 |
#define | rc_MPU_DEFAULT_I2C_ADDR 0x68 |
default i2c address if AD0 is left low | |
#define | rc_MPU_ALT_I2C_ADDR 0x69 |
alternate i2c address if AD0 pin pulled high | |
#define | rc_MPU_INTERRUPT_GPIO 22 |
#define | rc_MPU_I2C_BAUDRATE 400000 |
baudrate of MPU i2c bus 400kHz | |
#define | TB_PITCH_X 0 |
Index of the dmp_TaitBryan[] array corresponding to the Pitch (X) axis. | |
#define | TB_ROLL_Y 1 |
Index of the dmp_TaitBryan[] array corresponding to the Roll (Y) axis. | |
#define | TB_YAW_Z 2 |
Index of the dmp_TaitBryan[] array corresponding to the Yaw (Z) axis. | |
#define | QUAT_W 0 |
First index of the dmp_quat[] quaternion vector. | |
#define | QUAT_X 1 |
Second index of the dmp_quat[] quaternion vector. | |
#define | QUAT_Y 2 |
Third index of the dmp_quat[] quaternion vector. | |
#define | QUAT_Z 3 |
Fourth index of the dmp_quat[] quaternion vector. | |
#define | DEG_TO_RAD 0.0174532925199 |
multiply to convert degrees to radians | |
#define | RAD_TO_DEG 57.295779513 |
multiply to convert radians to degrees | |
#define | MS2_TO_G 0.10197162129 |
multiply to convert m/s^2 to G | |
#define | G_TO_MS2 9.80665 |
multiply to convert G to m/s^2, standard gravity definition | |
#define | PI M_PI |
#define | TWO_PI (2.0 * M_PI) |
#define | GYRO_TO_DEG 2000.0/32768.0; |
#define | HAS_MAG |
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 enum rc_mpu_cfg_offset_t | rc_mpu_cfg_offset_t |
Offset in memory of config data. 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... | |
Enumerations | |
enum | rc_mpu_accel_fsr_t { ACCEL_FSR_2G , ACCEL_FSR_4G , ACCEL_FSR_8G , ACCEL_FSR_16G } |
accelerometer full scale range options More... | |
enum | rc_mpu_gyro_fsr_t { GYRO_FSR_250DPS , GYRO_FSR_500DPS , GYRO_FSR_1000DPS , GYRO_FSR_2000DPS } |
gyroscope full scale range options More... | |
enum | rc_mpu_accel_dlpf_t { ACCEL_DLPF_OFF , ACCEL_DLPF_460 , ACCEL_DLPF_184 , ACCEL_DLPF_92 , ACCEL_DLPF_41 , ACCEL_DLPF_20 , ACCEL_DLPF_10 , ACCEL_DLPF_5 } |
accelerometer digital low-pass filter options More... | |
enum | rc_mpu_gyro_dlpf_t { GYRO_DLPF_OFF , GYRO_DLPF_250 , GYRO_DLPF_184 , GYRO_DLPF_92 , GYRO_DLPF_41 , GYRO_DLPF_20 , GYRO_DLPF_10 , GYRO_DLPF_5 } |
gyroscope digital low-pass filter options More... | |
enum | rc_mpu_orientation_t { ORIENTATION_Z_UP = 136 , ORIENTATION_Z_DOWN = 396 , ORIENTATION_X_UP = 14 , ORIENTATION_X_DOWN = 266 , ORIENTATION_Y_UP = 112 , ORIENTATION_Y_DOWN = 336 , ORIENTATION_X_FORWARD = 133 , ORIENTATION_X_BACK = 161 } |
Orientation of the sensor. More... | |
enum | rc_mpu_cfg_offset_t { MPU_GYRO_CONFIG_ADDR = 0 , MPU_ACCEL_CONFIG_ADDR = 6 , MPU_MAG_CONFIG_ADDR = 54 } |
Offset in memory of config data. More... | |
Functions | |
void | rc_dmp_callback (uint gpio, uint32_t events) |
void | mpu9250_read_raw (i2c_inst_t *i2c, int16_t accel[3], int16_t gyro[3], int16_t mag[3], int16_t *temp) |
physical connection configuration | |
int | rc_mpu_config_t::gpio_interrupt_pin |
gpio pin, default 21 on Robotics Cape and BB Blue | |
i2c_inst_t * | rc_mpu_config_t::i2c_bus |
i2c instance | |
uint8_t | rc_mpu_config_t::i2c_addr |
default is 0x68, pull pin ad0 high to make it 0x69 | |
int | rc_mpu_config_t::show_warnings |
set to 1 to print i2c_bus warnings for debug | |
accelerometer, gyroscope, and magnetometer configuration | |
rc_mpu_accel_fsr_t | rc_mpu_config_t::accel_fsr |
accelerometer full scale range, default ACCEL_FSR_8G | |
rc_mpu_gyro_fsr_t | rc_mpu_config_t::gyro_fsr |
gyroscope full scale range, default GYRO_FSR_2000DPS | |
rc_mpu_accel_dlpf_t | rc_mpu_config_t::accel_dlpf |
internal low pass filter cutoff, default ACCEL_DLPF_184 | |
rc_mpu_gyro_dlpf_t | rc_mpu_config_t::gyro_dlpf |
internal low pass filter cutoff, default GYRO_DLPF_184 | |
int | rc_mpu_config_t::enable_magnetometer |
magnetometer use is optional, set to 1 to enable, default 0 (off) | |
DMP settings, only used with DMP mode | |
int | rc_mpu_config_t::dmp_sample_rate |
sample rate in hertz, 200,100,50,40,25,20,10,8,5,4 | |
int | rc_mpu_config_t::dmp_fetch_accel_gyro |
set to 1 to optionally raw accel/gyro when reading DMP quaternion, default: 0 (off) | |
int | rc_mpu_config_t::dmp_auto_calibrate_gyro |
set to 1 to let DMP auto calibrate the gyro while in use, default: 0 (off) | |
rc_mpu_orientation_t | rc_mpu_config_t::orient |
DMP orientation matrix, see rc_mpu_orientation_t. | |
double | rc_mpu_config_t::compass_time_constant |
time constant (seconds) for filtering compass with gyroscope yaw value, default 25 | |
int | rc_mpu_config_t::read_mag_after_callback |
reads magnetometer after DMP callback function to improve latency, default 1 (true) | |
int | rc_mpu_config_t::mag_sample_rate_div |
magnetometer_sample_rate = dmp_sample_rate/mag_sample_rate_div, default: 4 | |
int | rc_mpu_config_t::tap_threshold |
threshold impulse for triggering a tap in units of mg/ms | |
base sensor readings in real units | |
double | rc_mpu_data_t::accel [3] |
accelerometer (XYZ) in units of m/s^2 | |
double | rc_mpu_data_t::gyro [3] |
gyroscope (XYZ) in units of degrees/s | |
double | rc_mpu_data_t::mag [3] |
magnetometer (XYZ) in units of uT | |
double | rc_mpu_data_t::temp |
thermometer, in units of degrees Celsius | |
16 bit raw adc readings and conversion rates | |
int16_t | rc_mpu_data_t::raw_gyro [3] |
raw gyroscope (XYZ)from 16-bit ADC | |
int16_t | rc_mpu_data_t::raw_accel [3] |
raw accelerometer (XYZ) from 16-bit ADC | |
double | rc_mpu_data_t::accel_to_ms2 |
conversion rate from raw accelerometer to m/s^2 | |
double | rc_mpu_data_t::gyro_to_degs |
conversion rate from raw gyroscope to degrees/s | |
DMP data | |
double | rc_mpu_data_t::dmp_quat [4] |
normalized quaternion from DMP based on ONLY Accel/Gyro | |
double | rc_mpu_data_t::dmp_TaitBryan [3] |
Tait-Bryan angles (roll pitch yaw) in radians from DMP based on ONLY Accel/Gyro. | |
int | rc_mpu_data_t::tap_detected |
set to 1 if there was a tap detect on the last dmp sample, reset to 0 on next sample | |
int | rc_mpu_data_t::last_tap_direction |
direction of last tap, 1-6 corresponding to X+ X- Y+ Y- Z+ Z- | |
int | rc_mpu_data_t::last_tap_count |
current counter of rapid consecutive taps | |
fused DMP data filtered with magnetometer | |
double | rc_mpu_data_t::fused_quat [4] |
fused and normalized quaternion | |
double | rc_mpu_data_t::fused_TaitBryan [3] |
fused Tait-Bryan angles (roll pitch yaw) in radians | |
double | rc_mpu_data_t::compass_heading |
fused heading filtered with gyro and accel data, same as Tait-Bryan yaw | |
double | rc_mpu_data_t::compass_heading_raw |
unfiltered heading from magnetometer | |
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... | |
calibration functions | |||||||
Sets the callback function that will be triggered when new DMP data is ready.
sets the callback function triggered when a tap is detected
| |||||||
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_reset_accel_cal (i2c_inst_t *i2c) | ||||||
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... | |||||||
int | rc_print_gyro_calibration (i2c_inst_t *i2c) | ||||||
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
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.
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.
#define DMP_AUTO_CAL_GYRO 0 |
Static defines from the config used in RC Control Lib
typedef enum rc_mpu_accel_dlpf_t 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.
typedef enum rc_mpu_accel_fsr_t 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.
typedef enum rc_mpu_cfg_offset_t rc_mpu_cfg_offset_t |
Offset in memory of config data.
Add this to the
typedef struct rc_mpu_config_t rc_mpu_config_t |
configuration of the mpu sensor
Configuration struct passed to rc_mpu_initialize and rc_mpu_initialize_dmp. It is best to get the default config with rc_mpu_default_config() function first and modify from there.
typedef struct rc_mpu_data_t rc_mpu_data_t |
data struct populated with new sensor data
This is the container for holding the sensor data. The user is intended to make their own instance of this struct and pass its pointer to imu read functions. new data will then be written back into the user's instance of the data struct.
typedef enum rc_mpu_gyro_dlpf_t 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.
typedef enum rc_mpu_gyro_fsr_t 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.
typedef enum rc_mpu_orientation_t 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.
enum 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.
enum 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.
enum rc_mpu_cfg_offset_t |
Offset in memory of config data.
Add this to the
enum 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.
enum 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.
enum 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.
void rc_dmp_callback | ( | uint | gpio, |
uint32_t | events | ||
) |
Function headers
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.
[in] | conf | Config struct, only used to configure i2c bus and address. |
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.
[in] | conf | Config struct, only used to configure i2c bus and address. |
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.
[in] | conf | Config struct, only used to configure i2c bus and address. |
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.
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().
data | pointer to user's data struct | |
[in] | conf | user congiguration data |
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.
data | Pointer to user's data struct where new data will be written | |
[in] | conf | User's configuration struct |
enbale quaternion feature and accel/gyro if requested
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.
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.
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.
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.
int rc_mpu_read_accel | ( | rc_mpu_data_t * | data | ) |
Reads accelerometer data from the MPU.
data | Pointer to user's data struct where new data will be written |
int rc_mpu_read_gyro | ( | rc_mpu_data_t * | data | ) |
Reads gyroscope data from the MPU.
data | Pointer to user's data struct where new data will be written |
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()
data | Pointer to user's data struct where new data will be written |
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.
data | Pointer to user's data struct where new data will be written |
int rc_mpu_set_config_to_default | ( | rc_mpu_config_t * | conf | ) |
Resets a config struct to defaults.
[out] | conf | Pointer to config struct to be overwritten |
int rc_print_gyro_calibration | ( | i2c_inst_t * | i2c | ) |
Loads steady state gyro offsets from the flash and puts them in the IMU's gyro offset register. If no calibration file exists then make a new one.