Libraries
Background
tollosGyro.c – gyroscope functions for Tollos
These functions provide basic gyroscope functions for Tollos, intended to be device-independent (although at the moment an I2C connection is assumed).To use, the device must be initialized using gyroInit. This indicates which I2C channel the device is on and which port/pin is used for the DataReady interrupt. The gyroscope range is determined by the device used. (For example, for the ITG3200 it is +/- 2000 degrees/sec.)
The latest gyroscope reading can be read safely using gyroGetXYZ, which returns the three axes in milli-degrees/sec. The axis directions are as defined by the device manufacturer. Note that gyroscopes will generally have some constant offset, or drift, that will indicate a rate of turn on a ‘static’ device; this may be partly compensated for by adjusting for the die temperature, available using gyroTemperature.
The default update rate is selected by the device driver code and will be at least 25Hz (that is, the data will be no more than 40ms old). Update is not necessarily synchronous with the Tollos tick rate. The rate can be changed with gyroRate; the low pass-filter bandwidth is set to match or exceed the rate.
tollosGyro will buffer up to four gyroscope readings. This allows an update rate of double the application’s wake-up frequency, plus one missed wakeup. An application should therefore call gyroGetXYZ repeatedly until ‘no data available’ is reported in order to clear queued data and to avoid overrun.
| Functions | |
|---|---|
| gyroGetXYZ | read latest x, y, and z angular rates |
| gyroInit | configure and initialize gyroscope |
| gyroRate | change update rate of gyroscope |
| gyroStop | stop and power-down gyroscope |
| gyroTemperature | return current gyroscope die temperature |
gyroGetXYZ – read latest x, y, and z angular rates
int gyroGetXYZ(int *x, int *y, int*z);
x, y, z – receive angular rates [milli-degrees/sec: 1000 = 1.000 degrees/second]; or are unchanged if no data are available.
returns 0 if data good, +1 if data is good but an overrun has occurred since the last read, −1 if no good data from read, or −2 if the device is not initialized.
Results are returned scaled to milli-degrees/second.
When +1 (overrun) is returned the overrun status is cleared and future good reads will return 0 until another overrun occurs.
This must not be called from an interrupt level with higher priority than the gyroscope interrupt.
gyroInit – configure and initialize gyroscope
int gyroInit(uint channel, uint drport, uint drpin);
channel – I2C channel on which device is to be found
drport – port for the Data Ready interrupt pin
drpin – pin number (not bit mask) for the Data Ready interrupt pin
returns 0 if initialized OK, negative if error
This sets up the pin and interrupt handler for the Data Ready interrupt from the device then calls the device driver initialization function to start the device.
The gyroInitIO function will set:
- an update rate of at least 25 Hz (but not necessarily higher than that, to save power); this may be changed with gyroRate
- an interrupt on Data Ready (this is handled by tollosGyro).
Note that it can be 50ms or more before the first valid data are available, so a gyroGetXYX call before that time may report no data available, as might a call that reads the device less than 25ms after the last read.
gyroRate – change update rate of gyroscope
int gyroRate(uint rate);
rate – rate requested [Hz, 1..200]
returns the rate chosen if the rate was changed OK, or −1 if error (rate zero or too high, or a bus error)
The gyroscope will be set to a slowest available rate that is >= the requested rate, to minimize resource usage. The low-pass filter (if any) bandwidth is set to match or exceed the chosen rate.
To ensure working with 100kHz I2C, the maximum rate is limited to 200Hz – but note that this may use significant processor bandwidth.
gyroStop – stop and power-down gyroscope
int gyroStop(void);
returns 0 if gyroscope stopped OK, negative if an error or it was not running.
gyroTemperature – return current gyroscope die temperature
int gyroTemperature(void);
returns the latest temperature reading in milli-degrees Celsius, or GYRO_NOTEMP if no reading is available
Many gyroscope devices provide the temperature of the chip die, which can be used to compensate for drift due to temperature change. GYRO_NOTEMP is returned if no temperature reading is available or the Gyro device is stopped.