Modules | Enumerations | Functions
Imu
Sensors

Functions which handle the inertial measurement unit. More...

Modules

 Advanced informations
 

Enumerations

enum  eImuGyroResolution
 clusters all possible values for the maximum angular veloctiy (yaw angle) More...
 
enum  eImuSelectMask
 clusters bit masks for the requests of the imu More...
 
enum  eImuGet
 clusters select values for reading data from the imu More...
 
enum  eImuSet
 clusters select values for writing data to the imu More...
 

Functions

uint8_t imu_calibrate (void)
 Sets the three offsets through simple bias estimation. More...
 

Request Funktions

void imu_request (eImuSelectMask bitmask, eRequestType request)
 Requests new data from the imu. More...
 
eImuSelectMask imu_received (eImuSelectMask bitmask)
 Indicates if new data for the selected data blocks were received. More...
 
eImuSelectMask imu_changed (eImuSelectMask bitmask)
 Indicates if new data changed the selected data blocks. More...
 

Access Funktions

int16_t imu_get (eImuGet select)
 Returns the last stored version of the selected value. More...
 
void imu_set (eImuSet select, int16_t value)
 Sets the selected value of the imu sensors. More...
 

Detailed Description

Functions which handle the inertial measurement unit.

The MPU6050 is an IMU (Inertial Measurement Unit), which is integrated into the TUC-Bot. This IMU contains different sensors for measuring the angular velocities and the acceleration of the x-, y- and z-axis. The MPU6050 also contains a sensor, that can measure the temperature.

With the use of this IMU it is possible to improve the determination of the orientation and position of the TUC-Bot.

MPU6050 mounted on GY-521 breakout board

The IMU will be initialized by executing the function init_tucbot(). To check the success of initialization, call imu_get() with parameter kImuGetStateInit. The IMU might be manually (re-)initialized by using tucbot_imu_reset().

In order to improve the accuracy of the IMU, the function imu_calibrate() needs to be executed. While the IMU is calibrating all its sensors, the TUC-Bot must not be moved for 5-6 seconds! With the use of the functions imu_get() and imu_set() it is possible to either get or set the offsets of the IMU.

To receive data from the IMU, the function imu_request() must be executed.

Note
With the default settings, the maximum angular velocity will be +/-500 degrees/s. For higher accuracy you may change it to +/-250 degrees/s. If the robot is turning very fast, you should increase it to +/-1000 or even +/-2000 degrees/s. Use imu_set().

example

/*******************************************************************************
* examples/imu.c *
* ============== *
* *
* Version: 1.2.0 *
* Date : 05.11.18 *
* Author : Peter Weissig *
* *
* If you are changing this file, you may also consider to update *
* demos/diagnosticTool/diagnosticTool.c *
*******************************************************************************/
//*********************************<Included files>*****************************
#include <tucbot/tucbot.h>
//*********************************<Methods>************************************
void testImu_print(int16_t value, uint8_t digits);
void testImu(void);
int main(void);
//*********************************[testImu_print]******************************
void testImu_print(int16_t value, uint8_t digits) {
int16_t temp_value = value ;
uint8_t temp_digits = digits;
if ((temp_value < 0) && temp_digits) {
temp_digits--;
temp_value = -temp_value;
}
while (temp_digits) {
temp_value/= 10;
temp_digits--;
}
if (temp_value == 0) {
int16tostr(lcdout, value, digits);
} else if (value >= 0) {
while (digits) {
lcdout('+');
digits--;
}
} else {
while (digits) {
lcdout('-');
digits--;
}
}
}
//*********************************[testImu]************************************
void testImu(void) {
uint8_t resolution;
int16_t orientation;
int16_t orientation_display;
uint8_t countdown = 0;
uint8_t flag_redraw_menu = 0xFF;
lcdclr();
lcdxy(0,1);
lcdstr_p(PSTR("x####y#### Z####"));
imu_request(kImuSelectAll, kRequestContinuous);
while (1) {
if (flag_redraw_menu) {
flag_redraw_menu = 0x00;
orientation_display = 0x7FFF; // force update on new data
lcdxy(0,0);
// "Imu ###°C ####°"
lcdstr_p(PSTR("Imu ###" "\xDF" "C ####" "\xDF"));
}
if (buttons_get(kButtonMiddle)) {
leds_set(kLedMiddle, kLedOn );
mdelay(100);
leds_set(kLedMiddle, kLedOff);
lcdxy(4,0);
lcdstr_p(PSTR(" calibrating")); // "Imu calibrating"
mdelay(250);
leds_set(kLedMiddle, kLedOn);
imu_calibrate();
leds_set(kLedMiddle, kLedOff);
flag_redraw_menu = 0xFF;
countdown = 0;
} else if (buttons_get(kButtonRight)) {
leds_set(kLedRight , kLedOn );
mdelay(100);
leds_set(kLedRight , kLedOff);
lcdxy(4,0);
lcdstr_p(PSTR("setRes. ")); // "Imu setRes. "
mdelay(100);
leds_set(kLedRight, kLedOn);
// get current resolution
resolution = imu_get(kImuGetGyroResolution);
// setup and print next resolution
switch (resolution) {
case kImuGyroResolution250:
resolution = kImuGyroResolution500;
lcdstr_p(PSTR(" 500")); // "Imu setRes. 500"
break;
case kImuGyroResolution500:
resolution = kImuGyroResolution1000;
lcdstr_p(PSTR("1000")); // "Imu setRes. 1000"
break;
case kImuGyroResolution1000:
resolution = kImuGyroResolution2000;
lcdstr_p(PSTR("2000")); // "Imu setRes. 2000"
break;
case kImuGyroResolution2000:
resolution = kImuGyroResolution250;
lcdstr_p(PSTR(" 250")); // "Imu setRes. 250"
break;
default:
resolution = kImuGyroResolution500;
lcdstr_p(PSTR("500!")); // "Imu setRes. 500!"
break;
}
// switch to next resolution
imu_set(kImuSetGyroResolution, resolution);
// check for errors
if (imu_get(kImuGetGyroResolution) != resolution) {
lcdxy(12,0);
lcdstr_p(PSTR(" ERR")); // "Imu setRes. ERR"
}
// wait a bit
mdelay(1000);
leds_set(kLedRight, kLedOff);
// reset absolute orientation
imu_set(kImuSetOrientation, 0);
flag_redraw_menu = 0xFF;
countdown = 0;
}
if (countdown) {
countdown--;
} else {
countdown = 5;
if (imu_changed(kImuSelectTemperature)) {
lcdxy(5,0);
testImu_print((imu_get(kImuGetTemperature) + 5)/ 10,3);
}
orientation = imu_get(kImuGetOrientation) / 10;
if (orientation != orientation_display) {
orientation_display = orientation;
lcdxy(11,0); testImu_print(orientation,4);
}
if (imu_changed(kImuSelectAccelerometer)) {
lcdxy( 1,1); testImu_print(imu_get(kImuGetAccelX),4);
lcdxy( 6,1); testImu_print(imu_get(kImuGetAccelY),4);
}
if (imu_changed(kImuSelectGyroscope)) {
lcdxy(12,1); testImu_print(imu_get(kImuGetGyroZ),4);
}
}
mdelay(100);
}
}
//*********************************[main]***************************************
int main (void) {
init_tucbot(0xFF);
buttons_request(kRequestContinuous);
testImu();
return (0);
}

Enumeration Type Documentation

◆ eImuGet

enum eImuGet

clusters select values for reading data from the imu

See also
imu_get()
Enumerator
kImuGetOrientation 

constant ( 1): orientation of robot - around z-axis (16-bit)
1 LSB = 0.1°

kImuGetAccelX 

constant ( 2): linear acceleration along x-axis (16-bit)
1 LSB ~ 0.0006 * m/s^2
value is offset corrected (kImuGetOffsetX)
see also sMI_Accelerometer

kImuGetAccelY 

constant ( 3): linear acceleration along y-axis (16-bit)
1 LSB ~ 0.0006 * m/s^2
value is offset corrected (kImuGetOffsetY)
see also sMI_Accelerometer

kImuGetGyroZ 

constant ( 4): angular velocity around z-axis (16-bit)
1 LSB ~ see eImuGyroResolution
value is offset corrected (kImuGetOffsetZ)
see also sMI_Gyroscope

kImuGetTemperature 

constant ( 5): temperature (16-bit)
1 LSB = 0.1°C
see also sMI_Temperature

kImuGetStateInit 

constant ( 6): initialization of imu
boolean value (0x00: not initialized; other: ok)
see also tucbot_imu_reset()

kImuGetUseSmallFilter 

constant ( 7): small-velocity-filter
boolean value (0x00: use all; other: filter small velocities)
see also kImuSmallFilterLimit

kImuGetUseMotorFilter 

constant ( 8): motor-filter
boolean value (0x00: use all; other: filter no/low motor power)
see also kImuMotorFilterLimit and kImuMotorFilterTimeOut

kImuGetGyroResolution 

constant ( 9): maximum angular velocity
The data is directly retrieved from the imu. Internally the TwiWrapper will be used. This will enable interrupts, take some time and may even fail!
result will be of type eImuGyroResolution

kImuGetOffsetX 

constant (10): offset for linear accel. along x-axis (16-bit)
1 LSB ~ 0.0006 * m/s^2
see also kImuGetAccelX

kImuGetOffsetY 

constant (11): offset for linear accel. along y-axis (16-bit)
1 LSB ~ 0.0006 * m/s^2
see also kImuGetAccelY

kImuGetOffsetZ 

constant (12): offset for angular vel. around z-axis (16-bit)
1 LSB ~ 0.0076 * °/s
The resolution of the gyro sensors can be changed. Nevertheless, the resolution of the offset stays constant (lowest possible LSB).
see also kImuGetGyroZ

kImuGetAccelZ 

constant (13): linear acceleration along z-axis (16-bit)
1 LSB ~ 0.0006 * m/s^2
see also sMI_Accelerometer

kImuGetGyroX 

constant (14): angular velocity around x-axis (16-bit)
1 LSB ~ see eImuGyroResolution
see also sMI_Gyroscope

kImuGetGyroY 

constant (15): angular velocity around y-axis (16-bit)
1 LSB ~ see eImuGyroResolution
see also sMI_Gyroscope

◆ eImuGyroResolution

enum eImuGyroResolution

clusters all possible values for the maximum angular veloctiy (yaw angle)

The values correlate to the GYRO_CONFIG register of the IMU.

The current resolution for the gyro registers (e.g. kImuRegGyroZ) depend on the maximum angular velocity:
1 LSB = max_velocity / 2^15; // Not 2^16, since 1 bit is needed for the signedness.

See also
imu_set() and imu_get()
Enumerator
kImuGyroResolution250 

constant (0x00): +/-250 degree/s
kImuGetGyroZ: 1 LSB ~ 0.0076 * °/s

kImuGyroResolution500 

constant (0x08): +/-500 degree/s
kImuGetGyroZ: 1 LSB ~ 0.0153 * °/s

kImuGyroResolution1000 

constant (0x10): +/-1000 degree/s
kImuGetGyroZ: 1 LSB ~ 0.0305 * °/s

kImuGyroResolution2000 

constant (0x18): +/-2000 degree/s
kImuGetGyroZ: 1 LSB ~ 0.0610 * °/s

kImuGyroResolutionDefault 

constant (kImuGyroResolution500): default setting on startup

kImuGyroResolutionError 

constant: indicating error during readout
if accidentally passed to imu_set(), the default settings will be used

◆ eImuSelectMask

enum eImuSelectMask

clusters bit masks for the requests of the imu

See also
imu_request(), imu_received() and imu_changed()
Enumerator
kImuSelectNone 

bit mask (0x00): select no data block

kImuSelectAccelerometer 

bit mask (0x01): linear accelerations (16-bit)
see also sMI_Accelerometer

kImuSelectTemperature 

bit mask (0x02): temperature (16-bit)
see also sMI_Temperature

kImuSelectGyroscope 

bit mask (0x04): angular velocities (16-bit)

kImuSelectAll 

bit mask (0x07): select all data blocks

◆ eImuSet

enum eImuSet

clusters select values for writing data to the imu

See also
imu_set()
Enumerator
kImuSetOrientation 

constant (kImuGetOrientation): orientation of robot - around z-axis (16-bit)
This can be used to reset the absolute orientation.

kImuSetUseSmallFilter 

constant (kImuGetUseSmallFilter): small-velocity-filter (boolean)

kImuSetUseMotorFilter 

constant (kImuGetUseMotorFilter): motor-filter (boolean)

kImuSetGyroResolution 

constant (kImuGetGyroResolution): maximum angular velocity
The data is directly send to the imu. Internally the TwiWrapper will be used. This will enable interrupts, take some time and may even fail! To check if resolution was changed, call imu_get() with kImuGetGyroResolution.
data must be of type eImuGyroResolution

kImuSetOffsetX 

constant (kImuGetOffsetX): offset of linear accel. along x-axis (16-bit)

kImuSetOffsetY 

constant (kImuGetOffsetY): offset of linear accel. along y-axis (16-bit)

kImuSetOffsetZ 

constant (kImuGetOffsetZ): offset of angular vel. around z-axis (16-bit)

Function Documentation

◆ imu_calibrate()

uint8_t imu_calibrate ( void  )

Sets the three offsets through simple bias estimation.

This function will automatically request the imu data and try to estimates the offsets.

The TUC-Bot must not move during the calibration.

Note
This whole procedure will take some time!
Returns
8-bit unsigned integer which is a boolean value
If the IMU is not initialized, this function will return false (0x00) immediatly.
See also
kImuCalibrationTime
Examples
imu.c.

◆ imu_changed()

eImuSelectMask imu_changed ( eImuSelectMask  bitmask)

Indicates if new data changed the selected data blocks.

Parameters
bitmaskbit mask of the selected data blocks - see also eImuSelectMask
The parameter is used to only return the value of the masked changed-bits. All other values(bits) are set to 0.
Returns
bitfield of the selected data blocks - see also eImuSelectMask
If a data block is changed its related bit will be 1, otherwise 0.
If only one data block is selected the return value can be interpreted as a boolean expression.
See also
imu_received(), imu_request(), imu_get()
Examples
imu.c.

◆ imu_get()

int16_t imu_get ( eImuGet  select)

Returns the last stored version of the selected value.

This function relies on the internal data blocks sMI_Accelerometer, sMI_Temperature and sMI_Gyroscope - for new data use imu_request()

Note
The absolute orientation of robot is calculated by integrating the angular velocity around the z-axis. Therefore, the data block sMI_Gyroscope must be requested continuous.
The absolute orientation and the internal offsets are stored in the local variable tucbot_imu. Getting and setting those will cause no transfer on the twi.
Parameters
selectvalue of the selected data - see also eImuGet
Returns
16-bit integer
select decription
kImuGetOrientation absolute orientation of robot
kImuGetAccelX
kImuGetAccelY 		linear acceleration (offset corrected)
kImuGetGyroZ angular velocity (offset corrected)
kImuGetTemperature temperature
... for more details see also eImuGet
See also
imu_request()
Examples
imu.c.

◆ imu_received()

eImuSelectMask imu_received ( eImuSelectMask  bitmask)

Indicates if new data for the selected data blocks were received.

Parameters
bitmaskbit mask of the selected data blocks - see also eImuSelectMask
The parameter is used to only return the value of the masked received-bits. All other values(bits) are set to 0.
Returns
bitfield of the selected data blocks - see also eImuSelectMask
If a data block is received its related bit will be 1, otherwise 0.
If only one data block is selected the return value can be interpreted as a boolean expression.
See also
imu_changed(), imu_request(), imu_get()

◆ imu_request()

void imu_request ( eImuSelectMask  bitmask,
eRequestType  request 
)

Requests new data from the imu.

For details on the request schema see The general request.

Involved data blocks are:
sMI_Accelerometer, sMI_Temperature and sMI_Gyroscope

Parameters
bitmaskbit mask of the selected data blocks - see also eImuSelectMask
requestSee also eRequestType
See also
imu_get()
Examples
imu.c.

◆ imu_set()

void imu_set ( eImuSet  select,
int16_t  value 
)

Sets the selected value of the imu sensors.

Note
The absolute orientation and the internal offsets are stored in the local variable tucbot_imu. Getting and setting those will cause no transfer on the twi.
Parameters
selectvalue of the selected data - see also eImuSet
value16-bit integer
value to be stored within the selected data
See also
imu_transmitted() and imu_get()
Examples
imu.c.
leds_set
void leds_set(eLedMask bitmask, uint8_t bool)
Sets the selected leds on or off.
kImuGetAccelX
@ kImuGetAccelX
Definition: imu.h:289
buttons_get
eButtonMask buttons_get(eButtonMask bitmask)
Returns the last stored value of the selected buttons.
kImuSetGyroResolution
@ kImuSetGyroResolution
Definition: imu.h:373
kButtonMiddle
@ kButtonMiddle
bit mask (0x08): middle button
Definition: buttons.h:35
kImuGyroResolution250
@ kImuGyroResolution250
Definition: imu.h:128
imu_calibrate
uint8_t imu_calibrate(void)
Sets the three offsets through simple bias estimation.
kImuGetGyroZ
@ kImuGetGyroZ
Definition: imu.h:299
kImuGetAccelY
@ kImuGetAccelY
Definition: imu.h:294
kLedOn
@ kLedOn
constant (0xFF): turn leds on
Definition: leds.h:63
kLedRight
@ kLedRight
bit mask (0x04): right led
Definition: leds.h:46
kImuSetOrientation
@ kImuSetOrientation
Definition: imu.h:364
kButtonRight
@ kButtonRight
bit mask (0x10): right button
Definition: buttons.h:37
kImuSelectGyroscope
@ kImuSelectGyroscope
bit mask (0x04): angular velocities (16-bit)
Definition: imu.h:273
imu_changed
eImuSelectMask imu_changed(eImuSelectMask bitmask)
Indicates if new data changed the selected data blocks.
buttons_request
void buttons_request(eRequestType request)
Requests new data from the buttons.
int16tostr
void int16tostr(void *out, int16_t number, uint8_t digits)
Converts an integer to a string and passes it to an output function.
kImuSelectAccelerometer
@ kImuSelectAccelerometer
Definition: imu.h:267
kImuGetTemperature
@ kImuGetTemperature
Definition: imu.h:305
kImuGetGyroResolution
@ kImuGetGyroResolution
Definition: imu.h:322
kRequestContinuous
@ kRequestContinuous
constant (3): request continuous updates
Definition: update.h:37
kLedMiddle
@ kLedMiddle
bit mask (0x08): middle led
Definition: leds.h:44
kLedOff
@ kLedOff
constant (0x00): turn leds off
Definition: leds.h:61
kImuGyroResolution500
@ kImuGyroResolution500
Definition: imu.h:131
kImuGyroResolution1000
@ kImuGyroResolution1000
Definition: imu.h:134
imu_set
void imu_set(eImuSet select, int16_t value)
Sets the selected value of the imu sensors.
lcdclr
void lcdclr(void)
Clears the display.
lcdxy
void lcdxy(uint8_t x, uint8_t y)
Moves the cursor to a postion on the display.
imu_request
void imu_request(eImuSelectMask bitmask, eRequestType request)
Requests new data from the imu.
orientation
#define orientation
deprecated constant: see kLausTrackerGetSelfOrientation
Definition: backward.h:880
imu_get
int16_t imu_get(eImuGet select)
Returns the last stored version of the selected value.
kImuGetOrientation
@ kImuGetOrientation
Definition: imu.h:285
lcdstr_p
void lcdstr_p(const char *send_data)
Writes a string located in the flash to the display.
lcdout
void lcdout(uint8_t data)
Writes one byte to the display.
init_tucbot
void init_tucbot(uint8_t enable_interrupts)
Initiates the TUC-Bot.
mdelay
void mdelay(uint16_t mseconds)
Waits for the given time in milliseconds.
kImuSelectAll
@ kImuSelectAll
bit mask (0x07): select all data blocks
Definition: imu.h:275
kImuGyroResolution2000
@ kImuGyroResolution2000
Definition: imu.h:137
kImuSelectTemperature
@ kImuSelectTemperature
Definition: imu.h:270
Generated on Wed Mar 1 2023 09:00:05 for TUC-Bot library by   doxygen 1.8.17