Libraries
Background
tollosAcc.c – accelerometer functions for Tollos
These functions provide basic accelerometer 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 accInit. This indicates which I2C channel the device is on and which port/pin is used for DataReady interrupt. By default the accelerometer range will be at least 2g; this may be changed with accRange.
The latest accelerometer reading can be read safely using accGetXYZ, which returns the three axes in milli-g. The axes directions are as defined by the device manufacturer.
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 accRate.
tollosAcc will buffer up to four accelerometer readings. This allows an update rate of double the application’s wake-up frequency, plus one missed wakeup. An application should therefore call accGetXYZ repeatedly until ‘no data available’ is reported in order to clear queued data and to avoid overrun.
| Functions | |
|---|---|
| accGetXYZ | read latest x, y, and z accelerations |
| accInit | configure and initialize accelerometer |
| accRange | change range of accelerometer |
| accRate | change update rate of accelerometer |
| accStop | stop and power-down accelerometer |
accGetXYZ – read latest x, y, and z accelerations
int accGetXYZ(int *x, int *y, int*z);
x, y, z – receive accelerations [mg: 1000 = 1.000 g], 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-gs (1000 = 1g), without any calibration adjustments.
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 accelerometer interrupt.
accInit – configure and initialize accelerometer
int accInit(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 accInitIO function will set:
- an update rate of at least 25 Hz (but not necessarily higher than that, to save power); call accRate if a different rate is needed
- a range of at least 2g; call accRange if a larger range is needed
- an interrupt on Data Ready (this is handled by tollosAcc).
Note that it can be 40ms or more before the first valid data are available, so an accGetXYX call before that time may report no data available, as might a call that reads the device less than 25ms after the last read.
accRange – change range of accelerometer
int accRange(uint range);
range – range requested in milli-g [1000 = 1 g]
returns the chosen range if changed OK, −1 if error (range too high)
The accelerometer will be set to a smallest available range that is >= the requested range, to maximize the accuracy of returned results.
accRate – change update rate of accelerometer
int accRate(uint rate);
rate – rate requested [Hz, 1..200]
returns the chosen rate if changed OK, −1 if error (rate zero or too high)
The accelerometer will be set to a slowest available rate that is >= the requested rate, to minimize resource usage.
To ensure working with 100kHz I2C, the maximum rate is limited to 200Hz – but note that this may use significant processor bandwidth.
accStop – stop and power-down accelerometer
int accStop(void);
returns 0 if accelerometer stopped OK, negative if an error or it was not running.