MMA845x.h

00001 /**
00002  * @file    MMA845x.h
00003  * @brief   Device driver - MMA845x 3-axis accelerometer IC
00004  * @author  Tim Barr
00005  * @version 1.0
00006  * @see     http://cache.freescale.com/files/sensors/doc/data_sheet/MMA8451Q.pdf
00007  * @see     http://cache.freescale.com/files/sensors/doc/data_sheet/MMA8452Q.pdf
00008  * @see     http://cache.freescale.com/files/sensors/doc/data_sheet/MMA8453Q.pdf
00009  *
00010  * Copyright (c) 2015
00011  *
00012  * Licensed under the Apache License, Version 2.0 (the "License");
00013  * you may not use this file except in compliance with the License.
00014  * You may obtain a copy of the License at
00015  *
00016  *     http://www.apache.org/licenses/LICENSE-2.0
00017  *
00018  * Unless required by applicable law or agreed to in writing, software
00019  * distributed under the License is distributed on an "AS IS" BASIS,
00020  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00021  * See the License for the specific language governing permissions and
00022  * limitations under the License.
00023  * Forked from
00024  */
00025 
00026 #ifndef MMA845X_H
00027 #define MMA845X_H
00028 
00029 #include "mbed.h"
00030 
00031 /** Using the Sparkfun SEN-10955
00032  *
00033  * Example:
00034  * @code
00035  *  #include "mbed.h"
00036  *  #include "MMA845x.h"
00037  *
00038 
00039  *
00040  *  int main()
00041  *  {
00042 
00043  *  }
00044  * @endcode
00045  */
00046 
00047 
00048 /**
00049  *  @class MMA845x_DATA
00050  *  @brief API abstraction for the MMA845x 3-axis accelerometer IC data
00051  */
00052 class MMA845x_DATA
00053 {
00054 public:
00055 
00056     volatile int16_t _x ;   /*!< volatile data variable */
00057     volatile int16_t _y ;   /*!< volatile data variable */
00058     volatile int16_t _z ;   /*!< volatile data variable */
00059 
00060     /** Create the MMA845x_DATA object initialized to the parameter (or 0 if none)
00061      *  @param x - the init value of _x
00062      *  @param y - the init value of _y
00063      *  @param x - the init value of _z
00064      */
00065     MMA845x_DATA(int16_t x = 0, int16_t y = 0, int16_t z = 0) : _x (x), _y (y), _z (z) {}
00066 
00067     /** Overloaded '=' operator to allow shorthand coding, assigning objects to one another
00068      *  @param rhs - an object of the same type to assign ourself the same values of
00069      *  @return this
00070      */
00071     MMA845x_DATA &operator= (MMA845x_DATA const &rhs) {
00072         _x  = rhs._x ;
00073         _y  = rhs._y ;
00074         _z  = rhs._z ;
00075 
00076         return *this;
00077     }
00078 
00079     /** Overloaded '=' operator to allow shorthand coding, assigning objects to one another
00080      *  @param val - Assign each data member (_x, _y, _z) this value
00081      *  @return this
00082      */
00083     MMA845x_DATA &operator= (int16_t const val) {
00084         _x  = _y  = _z  = val;
00085 
00086         return *this;
00087     }
00088 
00089     /** Overloaded '==' operator to allow shorthand coding, test objects to one another
00090      *  @param rhs - the object to compare against
00091      *  @return 1 if the data members are the same and 0 otherwise
00092      */
00093     bool operator== (MMA845x_DATA const &rhs) const {
00094         return ((_x  == rhs._x )&&(_y  == rhs._y )&&(_z  == rhs._z )) ? 1 : 0;
00095     }
00096 };
00097 
00098 /**
00099  *  @class MMA845x
00100  *  @brief API abstraction for the MMA845x 3-axis accelerometer IC
00101  *  initial version will be polling only. Interrupt service and rtos support will
00102  *  be added at a later point
00103  */
00104 class MMA845x
00105 {
00106 public:
00107 
00108     /**
00109      *  @enum SA0
00110      *  @brief Possible terminations for the ADDR pin
00111      */
00112     enum SA0 {
00113         SA0_VSS  = 0, /*!< SA0 connected to VSS */
00114         SA0_VDD       /*!< SA0 connected to VDD */
00115     };
00116 
00117     /**
00118      *  @enum WHO_AM_I_VAL
00119      *  @brief Device ID's that this class is compatible with
00120      */
00121     enum WHO_AM_I_VAL {
00122         MMA8451  = 0x1A, /*!< MMA8451 WHO_AM_I register content */
00123         MMA8452  = 0x2A, /*!< MMA8452 WHO_AM_I register content */
00124         MMA8453  = 0x3A, /*!< MMA8453 WHO_AM_I register content */
00125     };
00126 
00127     /**
00128      * @enum SYS_MODE
00129      * @brief operating mode of MMA845x
00130      */
00131     enum SYS_MODE {
00132         STANDBY = 0,
00133         AWAKE, SLEEP
00134     };
00135 
00136     /**
00137      * @enum STATUS
00138      * @brief flags for data overwrite and data ready
00139      */
00140     enum STATUS {
00141         XDR   = 0x01,
00142         YDR   = 0x02,
00143         ZDR   = 0x04,
00144         XYZDR = 0x08,
00145         XOW   = 0x10,
00146         YOW   = 0x20,
00147         ZOW   = 0x40,
00148         XYZOW = 0x80
00149     };
00150 
00151     /**
00152        * @enum RANGE
00153        * @brief values for measurement range positive and negative
00154        */
00155     enum RANGE {
00156         RANGE_2g = 0,
00157         RANGE_4g, RANGE_8g
00158     };
00159 
00160     /**
00161      * @enum RESOLUTION
00162      * @brief selections for resolution of data, 8 bit or maximum
00163      */
00164     enum RESOLUTION {
00165         RES_MAX = 0,   /* Read back full resolution - normal mode*/
00166         RES_8BIT = 2   /* Read back 8 bit values only - fast mode*/
00167     };
00168 
00169     /**
00170      *  @enum LOW_NOISE
00171      *  @brief Low Noise mode Note: 4g max reading when on
00172      */
00173     enum LOW_NOISE {
00174         LN_OFF = 0x00, /* Low Noise mode off */
00175         LN_ON = 0x04  /* Low Noise mode on, 4g max readings */
00176     };
00177 
00178     /**
00179      *  @enum HPF_MODE
00180      *  @brief High Pass Filter mode
00181      */
00182     enum HPF_MODE {
00183         HPF_OFF = 0x00, /* High Pass Filter mode off */
00184         HPF_ON = 0x10  /* High Pass Filter mode on */
00185     };
00186 
00187     /**
00188     * @enum DATA_RATE
00189     * @brief values for normal output data rate in Hz
00190     */
00191     enum DATA_RATE {
00192         DR_800  = 0x00,
00193         DR_400  = 0x08,
00194         DR_200  = 0x10,
00195         DR_100  = 0x18,
00196         DR_50   = 0x20,
00197         DR_12_5 = 0x28,
00198         DR_6_25 = 0x30,
00199         DR_1_56 = 0x38
00200     };
00201     /**
00202      * @enum ASLP_DATA_RATE
00203      * @brief values for auto_sleep mode data rate in HZ
00204      */
00205     enum ASLP_DATA_RATE {
00206         ASLPDR_50   = 0x00,
00207         ALSPDR_12_5 = 0x40,
00208         ASLPDR_6_25 = 0x80,
00209         ASLPDR_1_56 = 0xB0
00210     };
00211 
00212     /**
00213      *  @enum OVERSAMPLE_MODE
00214      *  @brief sets the oversample mode, Normal, Low power and noise, High resolution, or low power
00215      */
00216     enum OVERSAMPLE_MODE {
00217         OS_NORMAL = 0,
00218         OS_LO_PN, OS_HI_RES, OS_LO_POW
00219     };
00220 
00221     /**
00222      *  @enum INTERRUPT_CFG_AND_ENABLE
00223      *  @brief used to {configure, enable, detect source of} interrupts for corresponding functions
00224      *  (INT_FIFO used only in MMA8451)
00225      */
00226     enum INTERRUPT_CFG_EN_SOURCE {
00227         INT_DRDY = 0x01,
00228         // 0x20 missing,
00229         INT_FF_MT = 0x04,
00230         INT_PULSE = 0x08,
00231         INT_LNDPRT = 0x10,
00232         INT_TRANS = 0x20,
00233         INT_FIFO = 0x40,
00234         INT_ASLP = 0x80
00235     };
00236     /**
00237      *  @enum INTERRUPT_PIN
00238      *  @brief chooses interrupt pin used to signal interrupt condition
00239      */
00240     enum INTERRUPT_PIN {
00241         INT1 = 1,
00242         INT2 = 0,
00243         INT_NONE = 2
00244     };
00245 
00246     /**
00247      *  @enum REGISTER
00248      *  @brief The device register map
00249      */
00250     enum REGISTER {
00251         STATUS = 0x00,
00252         OUT_X_MSB, OUT_X_LSB, OUT_Y_MSB, OUT_Y_LSB, OUT_Z_MSB, OUT_Z_LSB,
00253 
00254         F_SETUP = 0x09, TRIG_CFG, // only available on the MMA8451 variant
00255 
00256         SYSMOD = 0x0B,
00257         INT_SOURCE, WHO_AM_I, XYZ_DATA_CFG, HP_FILTER_CUTOFF, PL_STATUS,
00258         PL_CFG, PL_COUNT, PL_BF_ZCOMP, P_L_THS_REG, FF_MT_CFG, FF_MT_SRC,
00259         FF_MT_THS, FF_MT_COUNT,
00260 
00261         TRANSIENT_CFG = 0x1D,
00262         TRANSIENT_SRC, TRANSIENT_THS, TRANSIENT_COUNT, PULSE_CFG, PULSE_SRC,
00263         PULSE_THSX, PULSE_THSY, PULSE_THSZ, PULSE_TMLT, PULSE_LTCY, PULSE_WIND,
00264         ASLP_COUNT, CTRL_REG1, CTRL_REG2, CTRL_REG3, CTRL_REG4, CTRL_REG5,
00265         OFF_X, OFF_Y, OFF_Z
00266     };
00267 
00268     /** Create the MMA845x object
00269      *  @param i2c - A defined I2C object
00270      *  @param int1 - A defined InterruptIn object pointer. Default NULL for polling mode
00271      *  @param int2 - A defined InterruptIn object pointer. Default NULL for polling mode
00272      *  @param i2c_addr - state of pin SA0
00273      *  TODO - need to add interrupt support
00274      */
00275     MMA845x(I2C &i2c, SA0 const i2c_addr = SA0_VSS , InterruptIn* int1 = NULL, InterruptIn* int2 = NULL);
00276 
00277     /** Get the X data
00278      *  @return The last valid X-axis reading from the accelerometer
00279      */
00280     int16_t getX(void);
00281 
00282     /** Get the Y data
00283      *  @return The last valid Y-axis reading from the accelerometer
00284      */
00285     int16_t getY(void);
00286 
00287     /** Get the Z data
00288      *  @return The last Z-axis valid reading from the accelerometer
00289      */
00290     int16_t getZ(void);
00291 
00292     /** Get the XYZ data structure
00293      *  @return The last valid X, Y, and Z-axis readings from the accelerometer
00294      */
00295     MMA845x_DATA getXYZ(void);
00296 
00297     /** Get the XYZ data structure
00298      *  @return accelerometer ID code. Test versus the WHO_AM_I_VAL enum
00299      */
00300     char getWhoAmI(void) const;
00301 
00302     /** Setup the MMA845x for standard accelerometer read mode
00303      *  @range - set the measurement range using RANGE enum
00304      *  @resolution - set the ADC resolution using the RESOLUTION enum
00305      *  @lo_noise - Set the Low-Noise mode using the LOW_NOISE enum
00306      *  @data_rate - set the aquisition rate using the DATA_RATE enum
00307      *  @os_mode - Set the Over sample mode suing the OVERSAMPLE_MODE enum
00308      *  @hpf_mode - Set the Hi pass filter mode using the HPF_MOSE enum
00309      *  @return status of command
00310      *
00311      *  This sets the resolution, range, data rate, oversample
00312      *  mode, hi and lo pass filter.
00313      *  Also sets the device to active mode, so no further configuration will take an effect.
00314      *  To perform any configuration, switch to standby.
00315      */
00316     uint8_t setCommonParameters(RANGE range, RESOLUTION resolution, LOW_NOISE lo_noise,
00317                                 DATA_RATE data_rate, OVERSAMPLE_MODE os_mode, HPF_MODE hpf_mode ) const;
00318 
00319     /** Ebnable Motion detect mode and interrupt handler
00320      *  @return status of command
00321      *  TODO - need to implement function
00322      */
00323     uint8_t enableMotionDetect(void) const;
00324 
00325     /** Enable Pulse Detect mode and interrupt handler
00326      *  @char x_threshold - tap/double tap detection threshold for x axis. resolution of 0.063 g/LSB, min value 1, max value 127, use 0 to disable
00327      *  @char y_threshold - tap/double tap detection threshold for y axis. resolution of 0.063 g/LSB, min value 1, max value 127, use 0 to disable
00328      *  @char z_threshold - tap/double tap detection threshold for z axis. resolution of 0.063 g/LSB, min value 1, max value 127, use 0 to disable
00329      *  @char window - pulse must fit within window (raise and fall below threshold) in order "to be considered a valid pulse."
00330      *  @char latency - period, that starts after a pulse has been detected, during all pulses are ignored. Kind of debouncing
00331      *  @pin - an interrupt has to be attached to some pin, even if this pin is NC
00332      *  @return status of command
00333      *  TODO - implement conversion from some arbitrary units to ms for window and latency, double tap, way of fetching pulse events
00334      */
00335     uint8_t enablePulseDetect(char x_threshold, char y_threshold, char z_threshold, char window, char latency, INTERRUPT_PIN pin) const;
00336 
00337     /** Enable Orientation mode and interrupt handler
00338      *  @debounce_steps - how long a state has to last to trigger orientation change. step varies from 1.25 to 160 ms.
00339      *  @pin - an interrupt has to be attached to some pin, even if this pin is NC
00340      *  @return status of command
00341      *  TODO - add trip angles change (only when MMA8451), way of fetching orientation events
00342      */
00343     uint8_t enableOrientationDetect(uint8_t debounce_steps, INTERRUPT_PIN pin = INT_NONE) const;
00344 
00345     /** Enable Transient detect mode and interrupt handler
00346      *  @return status of command
00347      *  TODO - need to implement function
00348      */
00349     uint8_t enableTransientDetect(void) const;
00350 
00351     /** Enable Autosleep function and interrupt handler
00352      *  @return status of command
00353      *  TODO - need to implement function
00354      */
00355     uint8_t enableAutoSleep(void) const;
00356 
00357     /** Enbale FIFO function and interrupt handler
00358      *  @return status of command
00359      *  TODO - need to implement function
00360      */
00361     uint8_t enableFIFO(void) const;
00362 
00363     /** Put the MMA845x in the Standby mode
00364      *  @return status of command
00365      */
00366     uint8_t standbyMode(void) const;
00367 
00368     /** Put the MMA845x in the active mode
00369      *  @return status of command
00370      */
00371     uint8_t activeMode(void) const;
00372 
00373     /** Check the MMA845x status register
00374          *  @return status byte
00375          */
00376     uint8_t getStatus(void) const;
00377 
00378     /** Write to a register (exposed for debugging reasons)
00379      *  Note: most writes are only valid in stop mode
00380      *  @param reg - The register to be written
00381      *  @param data - The data to be written
00382      */
00383     uint8_t writeRegister(uint8_t const reg, uint8_t const data) const;
00384 
00385     /** Read from a register (exposed for debugging reasons)
00386      *  @param reg - The register to read from
00387      *  @return The register contents
00388      */
00389     uint8_t readRegister(uint8_t const reg, uint8_t count, char* data) const;
00390     
00391     /** Enable disable interrupt triggering for a given function.
00392      *  @function - a internal funcion capable to trigger an interrupt
00393      *  @pin - which phy pin assign to interrupt condition. If no pin is specified, interrupt is disabled
00394      *  @return
00395      */
00396     uint8_t configInterrupt(INTERRUPT_CFG_EN_SOURCE function, INTERRUPT_PIN pin) const;
00397     
00398 private:
00399 
00400     I2C         *_i2c;
00401     InterruptIn *_int1;
00402     InterruptIn *_int2;
00403     uint8_t      _i2c_addr;
00404     char         _who_am_i;
00405     MMA845x_DATA _data;
00406     bool         _polling_mode;
00407 
00408     uint8_t init(void);
00409 
00410 };
00411 
00412 #endif