mTouch Framework: mTouch.h Source File

Go to the documentation of this file.
00001 /*************************************************************************
00002  *  � 2012 Microchip Technology Inc.                                       
00003  *  
00004  *  Project Name:    mTouch Framework v2.1
00005  *  FileName:        mTouch.h
00006  *  Dependencies:    mTouch_config.h
00007  *                   includes/mTouch_HardwareProfile_*******.h
00008  *                      (Based on current PIC� configuration)
00009  *                   mTouchCVD_macroLibrary_PIC****.h
00010  *                      (Based on current PIC� processor core)
00011  *                   See documentation for more information about which
00012  *                   files are required for compiling.
00013  *
00014  *  Processor:       See documentation for supported PIC� microcontrollers 
00015  *  Compiler:        HI-TECH Ver. 9.81 or later
00016  *  IDE:             MPLAB� IDE v8.50 (or later) or MPLAB� X                        
00017  *  Hardware:         
00018  *  Company:         
00019  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
00020  *  Description:     Master mTouch Framework Include File
00021  *                   - No application code should be implemented in this
00022  *                     or any other mTouch framework file. This will allow
00023  *                     for better customer support and easier upgrades to
00024  *                     later firmware versions. Use the main.c and user-
00025  *                     generated files to implement your application.
00026  *                   - This is THE ONLY REQUIRED INCLUDE FILE for any
00027  *                     application implementing mTouch. 
00028  *                   - See the documentation located in the docs/ folder
00029  *                     for a more information about how the framework is
00030  *                     implemented.
00031  *************************************************************************/
00032 /**************************************************************************
00033  * MICROCHIP SOFTWARE NOTICE AND DISCLAIMER: You may use this software, and 
00034  * any derivatives created by any person or entity by or on your behalf, 
00035  * exclusively with Microchip's products in accordance with applicable
00036  * software license terms and conditions, a copy of which is provided for
00037  * your referencein accompanying documentation. Microchip and its licensors 
00038  * retain all ownership and intellectual property rights in the 
00039  * accompanying software and in all derivatives hereto. 
00040  * 
00041  * This software and any accompanying information is for suggestion only. 
00042  * It does not modify Microchip's standard warranty for its products. You 
00043  * agree that you are solely responsible for testing the software and 
00044  * determining its suitability. Microchip has no obligation to modify, 
00045  * test, certify, or support the software. 
00046  * 
00047  * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, WHETHER 
00048  * EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED 
00049  * WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A 
00050  * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE, ITS INTERACTION WITH 
00051  * MICROCHIP'S PRODUCTS, COMBINATION WITH ANY OTHER PRODUCTS, OR USE IN ANY 
00052  * APPLICATION. 
00053  * 
00054  * IN NO EVENT, WILL MICROCHIP BE LIABLE, WHETHER IN CONTRACT, WARRANTY, 
00055  * TORT (INCLUDING NEGLIGENCE OR BREACH OF STATUTORY DUTY), STRICT 
00056  * LIABILITY, INDEMNITY, CONTRIBUTION, OR OTHERWISE, FOR ANY INDIRECT, 
00057  * SPECIAL, PUNITIVE, EXEMPLARY, INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, 
00058  * FOR COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE SOFTWARE, 
00059  * HOWSOEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE POSSIBILITY 
00060  * OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT ALLOWABLE BY LAW, 
00061  * MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY RELATED TO THIS 
00062  * SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, THAT YOU HAVE PAID 
00063  * DIRECTLY TO MICROCHIP FOR THIS SOFTWARE. 
00064  * 
00065  * MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF 
00066  * THESE TERMS. 
00067  *************************************************************************/
00068  
00069 //================================================================================================
00070 //  __  __       _                 _____                _       _   _                _           
00071 // |  \/  | __ _(_)_ __    _ __ __|_   _|__  _   _  ___| |__   | | | | ___  __ _  __| | ___ _ __ 
00072 // | |\/| |/ _` | | '_ \  | '_ ` _ \| |/ _ \| | | |/ __| '_ \  | |_| |/ _ \/ _` |/ _` |/ _ \ '__|
00073 // | |  | | (_| | | | | | | | | | | | | (_) | |_| | (__| | | | |  _  |  __/ (_| | (_| |  __/ |   
00074 // |_|  |_|\__,_|_|_| |_| |_| |_| |_|_|\___/ \__,_|\___|_| |_| |_| |_|\___|\__,_|\__,_|\___|_| 
00075 //
00076 //================================================================================================
00077 //
00078 //  NOTE:   To CONFIGURE the mTouch framework, start in the 'includes/mTouch_config.h' file.
00079 //
00080 //================================================================================================
00084 #ifndef __MTOUCH_H
00085 #define __MTOUCH_H
00086 
00087 
00088 //================================================================================================
00089 //  ___            _           _           
00090 // |_ _|_ __   ___| |_   _  __| | ___  ___ 
00091 //  | || '_ \ / __| | | | |/ _` |/ _ \/ __|
00092 //  | || | | | (__| | |_| | (_| |  __/\__ \
00093 // |___|_| |_|\___|_|\__,_|\__,_|\___||___/
00094 //                                                                    
00095 //================================================================================================
00096 
00097 #if defined(HI_TECH_C)
00098     #include <htc.h>                            // Provides PIC microcontroller SFR information
00099     #include <stdint.h>                         // Provides "uint#_t" typedefs for each compiler
00100 #else
00101     #include <p18cxxx.h>
00102 #endif
00103 
00104     #include "mTouch_config.h"                  // Stores the mTouch Framework's configuration details
00105     #include "mTouch_processConfiguration.h"    // Validates and processes the mTouch configuration for compiling
00106     #include "mTouch_modes.h"
00107 
00108     #if defined(MTOUCH_PROXIMITY_ENABLED)
00109     #include "mTouch_proximity.h"
00110     #endif
00111     
00112 
00113     #include "mComm.h"                          // mTouch communication module header file
00114     
00115 
00116 //================================================================================================
00117 //  ____  _                   _       
00118 // / ___|| |_ _ __ _   _  ___| |_ ___ 
00119 // \___ \| __| '__| | | |/ __| __/ __|
00120 //  ___) | |_| |  | |_| | (__| |_\__ \
00121 // |____/ \__|_|   \__,_|\___|\__|___/
00122 //                                
00123 //================================================================================================
00124 
00125 
00130     typedef struct 
00131     {        
00132         unsigned state              :2;         
00133         unsigned baselineCorrection :1;         
00134         
00135         #if (MTOUCH_BUTTON_TIMEOUT > 0)
00136         unsigned timeout            :1;
00137         #endif
00138         
00139         MTOUCH_STATE_BASELINE_COUNT ();         
00140         MTOUCH_STATE_TIMER          ();         
00141         #if defined(MTOUCH_STATE_DEBOUNCE)
00142         MTOUCH_STATE_DEBOUNCE       ();         
00143         #endif
00144     } mTouch_SensorVariables;
00145    
00146 
00147     
00148     
00155     typedef struct 
00156     {
00157         #if (CVD_STATE_SPS_BITS > 8)
00158         uint16_t                sampleCounter;
00159         #else
00160         uint8_t                 sampleCounter;
00161         #endif
00162         
00163         #if (MTOUCH_NUM_MODES > 1)   
00164         #if MTOUCH_SLEEP_INACTIVE_RESET > 255
00165         uint16_t                inactivity;     
00166         #else
00167         uint8_t                 inactivity;     
00168         #endif
00169         #endif
00170 
00171         mTouch_SensorVariables  sensor[MTOUCH_NUMBER_SENSORS];
00172             
00173     } mTouch_StateVariables;
00174 
00210     typedef union                       
00211     {                                   
00212         uint32_t  all;              
00213 
00214         struct                          
00215         {                               
00216             uint16_t    invalid;        
00217             uint16_t    v;              
00218         } result;                   
00219         
00220         struct                          
00221         {                               
00222             uint24_t    v;              
00223             uint8_t     invalid;        
00224         } accumulator;              
00225        
00226     } mTouch_AcquisitionData;
00227 
00228 
00232     typedef struct 
00233     {
00234         unsigned dataReady          :1; 
00235         unsigned areInitialized     :1; 
00236         unsigned buttonStateChange  :1; 
00237         
00238         #if (MTOUCH_INTEGRATION_TYPE == MTOUCH_CALLED_FROM_MAINLOOP)
00239         unsigned isrServiced        :1; 
00240         unsigned isRepeatScan       :1; 
00241         #endif
00242         
00243         #if (MTOUCH_NUM_MODES > 1)
00244         unsigned allReleased        :1; 
00245         unsigned skippedDecode      :1; 
00246         unsigned change             :1; 
00247         unsigned justChanged        :1;
00248         #endif
00249         
00250         #if (MTOUCH_INTEGRATION_TYPE == MTOUCH_CALLED_FROM_MAINLOOP)
00251         unsigned scanningEnabled    :1; 
00252         #endif
00253         
00254         #if defined(MTOUCH_ERROR_DETECTION_ENABLED)
00255         unsigned error              :1;
00256         #endif
00257         
00258     } mTouch_State; 
00259     
00260     #if defined(MTOUCH_MOST_PRESSED_ONLY) || defined(MTOUCH_MATRIX_ENABLED)
00261     typedef struct 
00262     {   
00263         uint16_t    maxValue;
00264         uint8_t     maxIndex;
00265     } mTouch_MostPressedData;
00266     
00267     typedef struct 
00268     {        
00269         uint8_t     start;
00270         uint8_t     end;
00271     } mTouch_MostPressedIndex;
00272     #endif
00273     
00274 //================================================================================================
00275 // __     __         _       _     _                      ____ _       _           _ 
00276 // \ \   / /_ _ _ __(_) __ _| |__ | | ___  ___           / ___| | ___ | |__   __ _| |
00277 //  \ \ / / _` | '__| |/ _` | '_ \| |/ _ \/ __|  _____  | |  _| |/ _ \| '_ \ / _` | |
00278 //   \ V / (_| | |  | | (_| | |_) | |  __/\__ \ |_____| | |_| | | (_) | |_) | (_| | |
00279 //    \_/ \__,_|_|  |_|\__,_|_.__/|_|\___||___/          \____|_|\___/|_.__/ \__,_|_|
00280 // 
00281 //================================================================================================
00282     // mTouch RAM Variables
00283     extern mTouch_State             mTouch_state;       
00284     extern mTouch_StateVariables    mTouch_stateVars;   
00285     extern uint16_t                 mTouch_sensorData   [MTOUCH_NUMBER_SENSORS];    
00286     extern mTouch_AcquisitionData   mTouch_acqData      [MTOUCH_NUMBER_SENSORS];    
00287     extern uint16_t                 mTouch_average      [MTOUCH_NUMBER_SENSORS];    
00288     
00289     #if defined(MCOMM_ENABLED)
00290     #if (MTOUCH_NUMBER_SENSORS <= 8)
00291     extern uint8_t                  mTouch_stateMask;   
00292     #elif (MTOUCH_NUMBER_SENSORS <= 16)
00293     extern uint16_t                 mTouch_stateMask;   
00294     #elif (MTOUCH_NUMBER_SENSORS <= 24)
00295     extern uint24_t                 mTouch_stateMask;   
00296     #elif (MTOUCH_NUMBER_SENSORS <= 32)
00297     extern uint32_t                 mTouch_stateMask;   
00298     #endif
00299     #endif
00300     
00301     #if defined(MTOUCH_SLIDERS_ENABLED) 
00302     #if defined(MTOUCH_SLIDER_SCALING_ENABLED)
00303     extern uint8_t                  mTouch_slider       [MTOUCH_NUMBER_OF_SLIDERS]; 
00304     #else
00305     extern uint16_t                 mTouch_slider       [MTOUCH_NUMBER_OF_SLIDERS]; 
00306     #endif
00307     #endif
00308     
00309     #if defined(MTOUCH_TOGGLE_ENABLED)
00310     #if (MTOUCH_NUMBER_SENSORS <= 8)
00311     extern uint8_t                  mTouch_toggle;      
00312     #elif (MTOUCH_NUMBER_SENSORS <= 16)
00313     extern uint16_t                 mTouch_toggle;      
00314     #elif (MTOUCH_NUMBER_SENSORS <= 24)
00315     extern uint24_t                 mTouch_toggle;      
00316     #elif (MTOUCH_NUMBER_SENSORS <= 32)
00317     extern uint32_t                 mTouch_toggle;      
00318     #endif
00319     #endif
00320         
00321     #if defined(MTOUCH_SLIDERS_ENABLED) || defined(MTOUCH_MOST_PRESSED_ONLY) || defined(MTOUCH_MATRIX_ENABLED) 
00322     extern uint16_t                 mTouch_deltas       [MTOUCH_NUMBER_SENSORS];            
00323     #endif
00324         
00325     #if defined(MTOUCH_MATRIX_ENABLED)
00326     extern uint8_t                  mTouch_matrix;          
00327     extern uint8_t                  mTouch_matrix_latch;    
00328     #endif
00329     
00330     // ISR Helper Variables
00331     #if (MTOUCH_INTEGRATION_TYPE != MTOUCH_CONTROLS_ISR) & defined(_PIC14)
00332     extern near     uint8_t         int_w;              
00333     extern near     uint8_t         int_status;         
00334     extern near     uint8_t         int_fsr;            
00335     extern near     uint8_t         int_pclath;         
00336     #elif defined(_PIC18) || defined(__18CXX)
00337     extern          uint8_t         int_w;              
00338     extern          uint8_t         int_status;         
00339     extern          uint8_t         int_bsr;            
00340     #endif
00341     
00342     // Constant arrays
00343     #if !defined(MTOUCH_EEPROM_ENABLED)
00344     extern const    uint16_t        mTouch_pressThreshold   [MTOUCH_NUMBER_SENSORS];    
00345     extern const    uint16_t        mTouch_releaseThreshold [MTOUCH_NUMBER_SENSORS];    
00346     #endif
00347     
00348     #if defined(MTOUCH_EEPROM_ENABLED) && defined(MTOUCH_EEPROM_STORED_IN_RAM)
00349     extern          uint8_t         mTouch_configOptions    [MTOUCH_EEPROM_START_ADR + MTOUCH_EEPROM_SIZE];
00350     #endif
00351     
00352     #if (MTOUCH_NUMBER_SENSORS > 1)
00353         #if (MTOUCH_NUM_MODES > 1)
00354     extern          uint8_t         mTouch_modeIndex; 
00355     extern const    uint8_t*        mTouch_currentScan;
00356         #define                     MTOUCH_CURRENTSCAN_VALUE    (*mTouch_currentScan)
00357         #else
00358     extern          uint8_t         mTouch_currentScan;
00359         #define                     MTOUCH_CURRENTSCAN_VALUE    mTouch_currentScan
00360         #endif
00361     #else
00362     #define                         MTOUCH_CURRENTSCAN_VALUE    0
00363     #endif
00364     
00365     #if MTOUCH_NUM_MODES > 1
00366     extern const    uint8_t*  const mTouch_mode [MTOUCH_NUM_MODES];
00367     #endif
00368     
00369 //================================================================================================
00370 //  _____                           
00371 // | ____|_ __  _   _ _ __ ___  ___ 
00372 // |  _| | '_ \| | | | '_ ` _ \/ __|
00373 // | |___| | | | |_| | | | | | \__ \
00374 // |_____|_| |_|\__,_|_| |_| |_|___/
00375 //                               
00376 //================================================================================================
00378     enum    mTouch_enum_ButtonState 
00379             {
00380                 MTOUCH_INITIALIZING,        
00381                 MTOUCH_RELEASED,            
00382                 MTOUCH_PRESSED              
00383             };  
00384 
00385     #if defined(MTOUCH_TOGGLE_ENABLED)
00386 
00387     enum    mTouch_enum_ToggleState
00388             {
00389                 MTOUCH_TOGGLE_OFF,          
00390                 MTOUCH_TOGGLE_ON            
00391             };
00392     #endif
00393   
00394     #if defined(MTOUCH_PROXIMITY_ENABLED)
00395 
00396     enum    mTouch_Prox_enum_SensorState
00397             {
00398                 MTOUCH_PROX_INITIALIZING,   
00399                 MTOUCH_PROX_NOT_ACTIVATED,  
00400                 MTOUCH_PROX_ACTIVATED       
00401             };
00402     #endif
00403 
00404 
00405 //================================================================================================
00406 //  _____                 _   _                            ____ _       _           _ 
00407 // |  ___|   _ _ __   ___| |_(_) ___  _ __  ___           / ___| | ___ | |__   __ _| |
00408 // | |_ | | | | '_ \ / __| __| |/ _ \| '_ \/ __|  _____  | |  _| |/ _ \| '_ \ / _` | |
00409 // |  _|| |_| | | | | (__| |_| | (_) | | | \__ \ |_____| | |_| | | (_) | |_) | (_| | |
00410 // |_|   \__,_|_| |_|\___|\__|_|\___/|_| |_|___/          \____|_|\___/|_.__/ \__,_|_| 
00411 //
00412 //================================================================================================
00413     void    mTouch_Init             (void);     // Initializes the mTouch Framework
00414     void    mTouch_Decode           (void);     // DO NOT USE: Call mTouch_Service() macro instead.
00415 
00416     #if MTOUCH_NUM_MODES > 1
00417     void mTouch_ChangeMode          (uint8_t);
00418     #else
00419     void mTouch_ChangeMode          (void);
00420     #endif
00421     
00422     #if     (MTOUCH_INTEGRATION_TYPE == MTOUCH_CALLED_FROM_ISR)
00423     void    mTouch_Scan             (void);     // Service function if calling from main ISR
00424     #elif   (MTOUCH_INTEGRATION_TYPE == MTOUCH_CALLED_FROM_MAINLOOP)
00425     uint8_t mTouch_Scan             (void);     // DO NOT USE: Call mTouch_isDataReady() macro instead.
00426     #endif
00427 
00428     #if defined(MTOUCH_SLIDERS_ENABLED)  
00429     void    mTouch_SliderDecode     (void);     // DO NOT USE: Called from within mTouch_Decode().
00430     #endif
00431     
00432     #if defined(MTOUCH_ERROR_DETECTION_ENABLED)
00433     void    mTouch_ErrorDetect      (void);     // Checks all sensor I/Os for shorts to Vss or Vdd
00434     #endif
00435     
00436 //================================================================================================
00437 //          _____                _          _    ____ ___ 
00438 //  _ __ __|_   _|__  _   _  ___| |__      / \  |  _ \_ _|
00439 // | '_ ` _ \| |/ _ \| | | |/ __| '_ \    / _ \ | |_) | | 
00440 // | | | | | | | (_) | |_| | (__| | | |  / ___ \|  __/| | 
00441 // |_| |_| |_|_|\___/ \__,_|\___|_| |_| /_/   \_\_|  |___|
00442 // 
00443 //================================================================================================
00444 
00462     #define     mTouch_GetButtonState(i)            mTouch_stateVars.sensor[i].state     
00463     
00471     #define     mTouch_GetAverage(i)                mTouch_average[i]   
00472     
00480     #define     mTouch_GetSensor(i)                 mTouch_sensorData[i]                        
00481 
00482     
00483     // Slider
00484     #if defined(MTOUCH_SLIDERS_ENABLED)
00485 
00492         #define     mTouch_GetSlider(i)             mTouch_slider[i]                            
00493     #endif
00494     
00495     // Toggle
00496     #if defined(MTOUCH_TOGGLE_ENABLED)
00497 
00504         #define     mTouch_GetToggleState(i)        ((uint8_t)(mTouch_toggle >> i) & 0x01)
00505 
00524         #if (MTOUCH_NUMBER_SENSORS <= 8)
00525             #define     mTouch_ToggleToggle(i)      mTouch_toggle ^=  (uint8_t) (0x01 << i)
00526             #define     mTouch_SetToggle(i)         mTouch_toggle |=  (uint8_t) (0x01 << i)     
00527             #define     mTouch_ClearToggle(i)       mTouch_toggle &= ~(uint8_t) (0x01 << i)     
00528         #elif (MTOUCH_NUMBER_SENSORS <= 16)
00529             #define     mTouch_ToggleToggle(i)      mTouch_toggle ^=  (uint16_t)(0x01 << i)
00530             #define     mTouch_SetToggle(i)         mTouch_toggle |=  (uint16_t)(0x01 << i)
00531             #define     mTouch_ClearToggle(i)       mTouch_toggle &= ~(uint16_t)(0x01 << i)
00532         #elif (MTOUCH_NUMBER_SENSORS <= 24)
00533             #define     mTouch_ToggleToggle(i)      mTouch_toggle ^=  (uint24_t)(0x01 << i)
00534             #define     mTouch_SetToggle(i)         mTouch_toggle |=  (uint24_t)(0x01 << i)
00535             #define     mTouch_ClearToggle(i)       mTouch_toggle &= ~(uint24_t)(0x01 << i)
00536         #elif (MTOUCH_NUMBER_SENSORS <= 32)
00537             #define     mTouch_ToggleToggle(i)      mTouch_toggle ^=  (uint32_t)(0x01 << i)
00538             #define     mTouch_SetToggle(i)         mTouch_toggle |=  (uint32_t)(0x01 << i)
00539             #define     mTouch_ClearToggle(i)       mTouch_toggle &= ~(uint32_t)(0x01 << i)
00540         #endif
00541         
00542     #endif
00543     
00544 
00557     #if (MTOUCH_INTEGRATION_TYPE == MTOUCH_CALLED_FROM_MAINLOOP)
00558         #define     mTouch_EnableScanning()     mTouch_state.scanningEnabled = 1;
00559         #define     mTouch_DisableScanning()    mTouch_state.scanningEnabled = 0;       
00560     #else
00561         #define     mTouch_EnableScanning()     MTOUCH_ISR_TMRxIF = 0; MTOUCH_ISR_TMRxIE = 1;
00562         #define     mTouch_DisableScanning()    MTOUCH_ISR_TMRxIE = 0;
00563     #endif
00564 
00565 
00566 
00576     #define mTouch_Service()                    mTouch_state.dataReady = 0; mTouch_Decode() 
00577 
00578 
00595     #if (MTOUCH_INTEGRATION_TYPE == MTOUCH_CALLED_FROM_MAINLOOP)
00596         #define mTouch_isDataReady()                mTouch_Scan()                               
00597     #else
00598         #define mTouch_isDataReady()                (mTouch_state.dataReady)                    
00599     #endif
00600 
00608     #define mTouch_checkInterrupt()                 (MTOUCH_ISR_TMRxIF && MTOUCH_ISR_TMRxIE)
00609     
00610     #if defined(MTOUCH_MATRIX_ENABLED)
00611     #define mTouch_Matrix_hasChanged()              (mTouch_matrix != mTouch_matrix_latch)
00612     #define mTouch_Matrix_latchNewValue()           mTouch_matrix_latch = mTouch_matrix
00613     #define mTouch_Matrix_isPressed()               (mTouch_matrix != 0xFF)
00614     #define mTouch_Matrix_getColumn()               mTouch_matrix >> MTOUCH_MATRIX_ROW_OFFSET
00615     #define mTouch_Matrix_getRow()                  mTouch_matrix & MTOUCH_MATRIX_ROW_MASK
00616     #endif
00617 
00618 #endif      // end: ifndef __MTOUCH_H
00619 
00620