|
MEGA-1284P Xplained Example Application
|
touch_api.h
Go to the documentation of this file.
00001 /******************************************************************************* 00002 * Atmel Corporation: http://www.atmel.com 00003 * Support email: touch@atmel.com 00004 ******************************************************************************/ 00005 /* License 00006 * Copyright (c) 2010, Atmel Corporation All rights reserved. 00007 * 00008 * Redistribution and use in source and binary forms, with or without 00009 * modification, are permitted provided that the following conditions are met: 00010 * 00011 * 1. Redistributions of source code must retain the above copyright notice, 00012 * this list of conditions and the following disclaimer. 00013 * 00014 * 2. Redistributions in binary form must reproduce the above copyright notice, 00015 * this list of conditions and the following disclaimer in the documentation 00016 * and/or other materials provided with the distribution. 00017 * 00018 * 3. The name of ATMEL may not be used to endorse or promote products derived 00019 * from this software without specific prior written permission. 00020 * 00021 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 00022 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00023 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY AND 00024 * SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, 00025 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00026 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00027 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 00028 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00029 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 00030 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00031 */ 00032 00033 00034 #ifndef TOUCH_API_H 00035 #define TOUCH_API_H 00036 00037 /*---------------------------------------------------------------------------- 00038 nested include files 00039 ----------------------------------------------------------------------------*/ 00040 #if defined (__GNUC__) || defined (__ICCARM__) ||defined (__CC_ARM) 00041 #include <stdint.h> 00042 #endif 00043 00044 #if !defined (__CC_ARM) 00045 #include <stdbool.h> 00046 #endif 00047 #include <stdlib.h> 00048 #ifndef MAKE_BUILD 00049 #ifdef _QMATRIX_ 00050 #include "touch_qm_config.h" 00051 #elif defined _QTOUCH_ 00052 #if !(defined(__AVR32__) || defined(__ICCAVR32__)) 00053 #include "touch_qt_config.h" 00054 #endif 00055 #else 00056 #error /* please provide any one of the acquisition methods*/ 00057 #endif 00058 #endif 00059 00060 #ifdef __ICCAVR__ 00061 #include <intrinsics.h> 00062 #endif /* (__ICCAVR__) */ 00063 00064 00065 /*---------------------------------------------------------------------------- 00066 Note: choice of library version 00067 ------------------------------------------------------------------------------ 00068 QTouch libraries are supplied built with a range of charge times. 00069 Charge time is the duration in which charge is transferred from the AVR onto 00070 the measurement capacitor. Shorter charge times result in faster measurements, 00071 but may be too fast to completely transfer charge onto the measurement 00072 capacitor. 00073 00074 The range of charge times lets the user choose a suitable version for the clock 00075 rate their chip is running at. 00076 00077 To make capacitive measurements, a charge time on the order of 0.25us to 2.5us 00078 is typically required. The following table shows the charge times corresponding 00079 to a range of clock speeds. 00080 00081 Clock speed (MHz) Cycle time (us) Suitable charge times 00082 ----------------- --------------- --------------------- 00083 1 1 1~2 cycles (1us to 2us) 00084 2 0.5 1~5 cycles (0.5us to 2.5us) 00085 4 0.25 1~10 cycles (0.25us to 2.5us) 00086 8 0.125 2~10 cycles (0.25us to 1.25us) 00087 10 0.1 3~25 cycles (0.3us to 2.5us) 00088 16 0.0625 4~25 cycles (0.25us to 1.5625s) 00089 20 0.05 5~50 cycles (0.25us to 2.5us) 00090 00091 ----------------------------------------------------------------------------*/ 00092 00093 /* *********Error Checking For the User Configuration Options Start********** */ 00094 #ifdef _QMATRIX_ 00095 00096 /* 00097 * Info stored for each x line. 00098 * 00099 * For each X line, enter the port and pin it is on. 00100 * For instance, if X3 is on PB1, the 4th entry would be 00101 * FILL_OUT_X_LINE_INFO( 1,1 ), and PORT_X_1 is B 00102 */ 00103 #define FILL_OUT_X_LINE_INFO( port_num,x_bit ) {JOIN(burst_qm_, port_num) ,(uint8_t)( 1u << x_bit ), BURST_MASK_X_PORT_ ## port_num } 00104 00105 /* 00106 * Info stored for each y line. 00107 * 00108 * For each Y line, enter the pin it is on. 00109 * For instance, if Y2 is on PA5 and PF5, the 3th entry would be 00110 * FILL_OUT_X_LINE_INFO( 5 ) 00111 * NOTE: 1. The PORTs for YA and YB on which Y lines are going to 00112 * be needs to be defined as PORT_YA and PORT_YB. 00113 * 00114 * Example: PORT_YA=A and PORT_YB=F in the case above. 00115 */ 00116 00117 #define FILL_OUT_Y_LINE_INFO( bit ) { bit, (uint8_t)(1u<<bit) } 00118 00119 00120 #ifndef MAKE_BUILD 00121 00122 /* Check necessary definitions */ 00123 #if (NUM_X_PORTS==1) 00124 #if !defined(PORT_X_1) || !defined(PORT_YA) || !defined(PORT_YB) || !defined(QT_DELAY_CYCLES) || !defined(PORT_SMP) || !defined(SMP_BIT) 00125 #error Need to define PORT_X_1, PORT_YA,PORT_YB,PORT_SMP,SMP_BIT and QT_DELAY_CYCLES before including the header file. 00126 #endif 00127 #elif(NUM_X_PORTS==2) 00128 #if !defined(PORT_X_1)||!defined(PORT_X_2) || !defined(PORT_YA) || !defined(PORT_YB) || !defined(QT_DELAY_CYCLES) || !defined(PORT_SMP) || !defined(SMP_BIT) 00129 #error Need to define PORT_X_1,PORT_X_2, PORT_YA,PORT_YB,PORT_SMP,SMP_BIT and QT_DELAY_CYCLES before including the header file. 00130 #endif 00131 #elif(NUM_X_PORTS==3) 00132 #if !defined(PORT_X_1)||!defined(PORT_X_2) ||!defined(PORT_X_3)|| !defined(PORT_YA) || !defined(PORT_YB) || !defined(QT_DELAY_CYCLES) || !defined(PORT_SMP) || !defined(SMP_BIT) 00133 #error Need to define PORT_X_1,PORT_X_2,PORT_X_3, PORT_YA,PORT_YB,PORT_SMP,SMP_BIT and QT_DELAY_CYCLES before including the header file. 00134 #endif 00135 #endif 00136 #ifdef _ROTOR_SLIDER_ 00137 #if (QT_NUM_CHANNELS == 4u) 00138 #if !(QT_MAX_NUM_ROTORS_SLIDERS == 1u) 00139 #error QT_MAX_NUM_ROTORS_SLIDERS should be define as 1 00140 #endif 00141 #elif (QT_NUM_CHANNELS == 8u) 00142 #if !(QT_MAX_NUM_ROTORS_SLIDERS == 2u) 00143 #error QT_MAX_NUM_ROTORS_SLIDERS should be define as 2 00144 #endif 00145 #elif (QT_NUM_CHANNELS == 16u) 00146 #if !((QT_MAX_NUM_ROTORS_SLIDERS == 2u) || (QT_MAX_NUM_ROTORS_SLIDERS == 4u)) 00147 #error QT_MAX_NUM_ROTORS_SLIDERS should be define as 2 or 4 based on library selected 00148 #endif 00149 #elif (QT_NUM_CHANNELS == 32u) 00150 #if !(QT_MAX_NUM_ROTORS_SLIDERS == 4u) 00151 #error QT_MAX_NUM_ROTORS_SLIDERS should be define as 4 based on library selected 00152 #endif 00153 #elif (QT_NUM_CHANNELS == 64u) 00154 #if !((QT_MAX_NUM_ROTORS_SLIDERS == 4u) || (QT_MAX_NUM_ROTORS_SLIDERS == 8u)) 00155 #error QT_MAX_NUM_ROTORS_SLIDERS should be define as 4 or 8 based on library selected 00156 #endif 00157 #endif 00158 #else 00159 #if !(QT_MAX_NUM_ROTORS_SLIDERS == 0u) 00160 #error QT_MAX_NUM_ROTORS_SLIDERS should be define as 0 Or _ROTOR_SLIDER_ Macro Needs to be define 00161 #endif 00162 #endif 00163 00164 #endif /*MAKE_BUILD*/ 00165 00166 #endif/*_QMATRIX_*/ 00167 /* ******************************Error Checking For the User Configuration Options End ***************** */ 00168 00169 /* Total ticks per msec. */ 00170 /* 00171 * TICKS_PER_MS = (CLK_FREQ/TIMER_PRESCALER)*(1/1000) 00172 * 00173 */ 00174 #define TICKS_PER_MS 500 00175 00176 /* Initialization values for the Qtouch library parameters. */ 00177 /* 00178 * Sensor detect integration (DI) limit. 00179 * Default value: 4. 00180 */ 00181 #define DEF_QT_DI 2 00182 00183 /* 00184 * Sensor negative drift rate. 00185 * 00186 * Units: 200ms 00187 * Default value: 20 (4 seconds per LSB). 00188 */ 00189 #define DEF_QT_NEG_DRIFT_RATE 20 /* 4s per LSB */ 00190 00191 /* 00192 * Sensor positive drift rate. 00193 * 00194 * Units: 200ms 00195 * Default value: 5 (1 second per LSB). 00196 */ 00197 #define DEF_QT_POS_DRIFT_RATE 5 /* 1s per LSB */ 00198 00199 /* 00200 * Sensor drift hold time. 00201 * 00202 * Units: 200ms 00203 * Default value: 20 (hold off drifting for 4 seconds after leaving detect). 00204 */ 00205 #define DEF_QT_DRIFT_HOLD_TIME 20 /* 4s */ 00206 00207 /* 00208 * Sensor maximum on duration. 00209 * 00210 * Units: 200ms (e.g., 150 = recalibrate after 30s). 0 = no recalibration. 00211 * Default value: 0 (recalibration disabled). 00212 */ 00213 #define DEF_QT_MAX_ON_DURATION 50 /* disabled */ 00214 00215 /* 00216 * Sensor recalibration threshold. 00217 * 00218 * Default: RECAL_50 (recalibration threshold = 50% of detection threshold). 00219 */ 00220 #define DEF_QT_RECAL_THRESHOLD RECAL_50 /* recal threshold = 50% of detect */ 00221 00222 /* 00223 * Positive recalibration delay. 00224 * 00225 * Default: 3 00226 */ 00227 #define DEF_QT_POS_RECAL_DELAY 3u 00228 00229 /*-------------------------------------------------------------------------- 00230 ---------------------------------------------------------------------------- 00231 ---------------------------------------------------------------------------- 00232 WARNING! Do not edit below this line. 00233 ---------------------------------------------------------------------------- 00234 ---------------------------------------------------------------------------- 00235 ----------------------------------------------------------------------------*/ 00236 00237 /*---------------------------------------------------------------------------- 00238 macros 00239 ----------------------------------------------------------------------------*/ 00240 /* utility macro for expanding port registers */ 00241 #define JOIN( x, y ) x ## y 00242 #define JOIN1( A, B, C ) A ## B ## C 00243 00244 /* Macro to build register writes for controlling ports. The intermediate 00245 * JOIN macro is required for correct expansion of the args. */ 00246 #define REG( REGISTER, SIDE ) JOIN( REGISTER, SIDE ) 00247 #define CONCAT( A, B, C ) JOIN1( A, B, C ) 00248 00249 /* The number of bytes required to report the maximum possible number of 00250 * sensors. */ 00251 #define QT_NUM_SENSOR_STATE_BYTES ( ( QT_NUM_CHANNELS + 7u ) / 8u ) 00252 00253 /* Status flags used with debug */ 00254 /* indicating no activity */ 00255 #define QTLIB_NO_ACTIVITY (uint16_t) 0x0000 00256 /* indicating that at least one sensor is in detect */ 00257 #define QTLIB_IN_DETECT (uint16_t) 0x0001 00258 /* indicating that at least one sensor haschanged ON/OFF state since last call to measure_sensors */ 00259 #define QTLIB_STATUS_CHANGE (uint16_t) 0x0002 00260 /* indicating that at least one rotor slider has changed position since last call to measure_sensors */ 00261 #define QTLIB_ROTOR_SLIDER_POS_CHANGE (uint16_t) 0x0004 00262 /* indicating that at least one reference value has changed since last call to measure_sensors */ 00263 #define QTLIB_CHANNEL_REF_CHANGE (uint16_t) 0x0008 00264 /* indicating that reburst is needed to resolve in FILTERIN or FILTEROUT or RECALIBRATE state. */ 00265 #define QTLIB_BURST_AGAIN (uint16_t) 0x0100 00266 /* indicating that reburst is needed to resolve in CALIBRATION */ 00267 #define QTLIB_RESOLVE_CAL (uint16_t) 0x0200 00268 /* indicating that reburst is needed to resolve in FILTERING */ 00269 #define QTLIB_RESOLVE_FILTERIN (uint16_t) 0x0400 00270 /* indicating that reburst is needed to resolve in RECAL */ 00271 #define QTLIB_RESOLVE_DI (uint16_t) 0x0800 00272 /* indicating that reburst is needed to resolve in RECAL */ 00273 #define QTLIB_RESOLVE_POS_RECAL (uint16_t) 0x1000 00274 00275 00276 00277 /* This part of the code below is used for library selection. This code will not be documented. */ 00278 /****************************************************************************************************/ 00279 #ifdef _QTOUCH_ 00280 00281 00282 #ifdef QTOUCH_STUDIO_MASKS 00283 #define CALCULATE_MASKS NULL 00284 #else 00285 #define CALCULATE_MASKS calc_masks 00286 #endif 00287 00288 #if defined (__AVR32__) || defined (__ICCAVR32__) || defined (_TOUCH_ARM_) 00289 00290 #if (QT_NUM_CHANNELS <= 8u && QT_NUM_CHANNELS != 0u) 00291 #define TOUCH_DATA_T uint8_t 00292 #elif (QT_NUM_CHANNELS > 8u && QT_NUM_CHANNELS <= 16u) 00293 #define TOUCH_DATA_T uint16_t 00294 #elif (QT_NUM_CHANNELS > 16u && QT_NUM_CHANNELS <= 32u) 00295 #define TOUCH_DATA_T uint32_t 00296 #else 00297 #error 'The number of channels specified is not supported.' 00298 #endif 00299 #else 00300 #define TOUCH_DATA_T uint8_t 00301 #endif 00302 00303 #ifndef MAKE_BUILD 00304 #if !(defined(__AVR32__) || defined(__ICCAVR32__)) || defined(_TOUCH_ARM_) 00305 #if (QT_NUM_CHANNELS == 16u) 00306 #ifndef _STATIC_PORT_PIN_CONF_ 00307 #define _STATIC_PORT_PIN_CONF_ 00308 #define QTOUCH_SNS_PORT_COUNT 2u 00309 #endif 00310 #else 00311 #ifdef INTRABURST_1 00312 #ifndef _STATIC_PORT_PIN_CONF_ 00313 #define _STATIC_PORT_PIN_CONF_ 00314 #define QTOUCH_SNS_PORT_COUNT 1u 00315 #endif 00316 #endif 00317 #ifndef SNS1 00318 #define SNS1 SNS 00319 #endif 00320 #ifndef SNSK1 00321 #define SNSK1 SNSK 00322 #endif 00323 #endif 00324 #else 00325 #ifdef INTRABURST_1 00326 #ifndef _STATIC_PORT_PIN_CONF_ 00327 #define _STATIC_PORT_PIN_CONF_ 00328 #define QTOUCH_SNS_PORT_COUNT 1u 00329 #endif 00330 #define SNS1 SNS 00331 #define SNSK1 SNSK 00332 #endif 00333 #endif 00334 #ifdef _ROTOR_SLIDER_ 00335 #if !defined(QT_MAX_NUM_ROTORS_SLIDERS) 00336 #if (QT_NUM_CHANNELS == 4) 00337 #define QT_MAX_NUM_ROTORS_SLIDERS 1 00338 #elif (QT_NUM_CHANNELS == 8) 00339 #define QT_MAX_NUM_ROTORS_SLIDERS 2 00340 #elif (QT_NUM_CHANNELS == 12) 00341 #define QT_MAX_NUM_ROTORS_SLIDERS 3 00342 #elif (QT_NUM_CHANNELS == 16) 00343 #define QT_MAX_NUM_ROTORS_SLIDERS 4 00344 #elif (QT_NUM_CHANNELS == 32) 00345 #define QT_MAX_NUM_ROTORS_SLIDERS 8 00346 #endif 00347 #endif 00348 #else 00349 #define QT_MAX_NUM_ROTORS_SLIDERS 0 00350 #endif 00351 #endif 00352 00353 #if !(defined(__AVR32__) || defined(__ICCAVR32__) || defined(_TOUCH_ARM_)) 00354 /* Macros for string concatenation. */ 00355 #define JOIN3( a, b, c, d, e ) burst_ ## a ## _ ## b ## _ ## c ## d ## _ ## e 00356 #define BURST_JOIN( static_flag, num_ports, intra1, intra2, pow_opt ) JOIN3( static_flag, num_ports, intra1, intra2, pow_opt ) 00357 00358 /* Build pointer to correct burst function */ 00359 #define BURST_FUNC_NAME BURST_JOIN( _STATIC_PORT_PIN_CONF_, QTOUCH_SNS_PORT_COUNT, INTRABURST_1, INTRABURST_2, _POWER_OPTIMIZATION_ ) 00360 00361 00362 /* Burst function prototype. The code itself is stored in the touch library */ 00363 extern void BURST_FUNC_NAME( TOUCH_DATA_T mask_index ); 00364 00365 /* Function pointer used for bursting */ 00366 extern void (*burst_proc)( TOUCH_DATA_T mask_index ); 00367 00368 #else 00369 #ifndef _STATIC_PORT_PIN_CONF_ 00370 00371 /* Select SNS and SNSK port. Choosing the same port for both will 00372 configure intra-port bursting. Options are B,C, and D. */ 00373 #define QT_SNS_PORT SNS 00374 #define QT_SNSK_PORT SNSK 00375 00376 /* Check necessary definitions */ 00377 #if !defined(QT_SNS_PORT) || !defined(QT_SNSK_PORT) || !defined(QT_DELAY_CYCLES) 00378 #error Need to define QT_SNS_PORT, QT_SNSK_PORT, and QT_DELAY_CYCLES before including this header file. 00379 #endif 00380 00381 /* Macros for string concatenation. */ 00382 #define JOIN3( a, b, c ) burst_ ## a ## _ ## b ## c 00383 #define BURST_JOIN( cycles, snsk, sns ) JOIN3( cycles, snsk, sns ) 00384 00385 /* Build pointer to correct burst function */ 00386 #define BURST_FUNC_NAME BURST_JOIN( QT_DELAY_CYCLES, QT_SNSK_PORT , QT_SNS_PORT) 00387 00388 #else 00389 00390 /* static port pin configurability declarations */ 00391 00392 #if (QTOUCH_SNS_PORT_COUNT > 0u) 00393 /* first SNS - SNSK port pin pairing. */ 00394 #define QT_SNS1_PORT SNS1 00395 #define QT_SNSK1_PORT SNSK1 00396 00397 #if !defined(QT_SNS1_PORT) || !defined(QT_SNSK1_PORT) || !defined(QT_DELAY_CYCLES) || !defined(QT_NUM_CHANNELS) || \ 00398 !defined(QT_MAX_NUM_ROTORS_SLIDERS) 00399 #error Need to define QT_SNS1_PORT, QT_SNSK1_PORT, QT_DELAY_CYCLES, QT_NUM_CHANNELS and QT_MAX_NUM_ROTORS_SLIDERS before including this header file. 00400 #endif 00401 #endif 00402 00403 #if (QTOUCH_SNS_PORT_COUNT > 1u) && !defined(_TOUCH_ARM_) 00404 #error 'Maximum of only 1 SNS-SNSK port pairings are supported by the UC3 libraries.' 00405 #elif (QTOUCH_SNS_PORT_COUNT == 0u) 00406 #error 'Invalid QTOUCH_SNS_PORT_COUNT value.' 00407 #endif /* QTOUCH_SNS_PORT_COUNT */ 00408 00409 #if (QTOUCH_SNS_PORT_COUNT > 1u) 00410 /* second SNS - SNSK port pin pairing. */ 00411 #define QT_SNS2_PORT SNS2 00412 #define QT_SNSK2_PORT SNSK2 00413 00414 #if !defined(QT_SNS2_PORT) || !defined(QT_SNSK2_PORT) || !defined(QT_DELAY_CYCLES) || !defined(QT_NUM_CHANNELS) || \ 00415 !defined(QT_MAX_NUM_ROTORS_SLIDERS) 00416 #error Need to define QT_SNS2_PORT, QT_SNSK2_PORT, QT_DELAY_CYCLES, QT_NUM_CHANNELS and QT_MAX_NUM_ROTORS_SLIDERS before including this header file. 00417 #endif 00418 #endif 00419 00420 #if (QTOUCH_SNS_PORT_COUNT == 1u) 00421 00422 /* Macros for string concatenation */ 00423 #define JOIN3( a, b, c, d, z ) burst_ ## a ## _ ## b ## c 00424 #define BURST_JOIN( cycles, snsk1, sns1, ch, rs ) JOIN3( cycles, snsk1, sns1, ch, rs ) 00425 00426 /* Build pointer to correct burst function */ 00427 #define BURST_FUNC_NAME BURST_JOIN( QT_DELAY_CYCLES, QT_SNSK1_PORT , QT_SNS1_PORT, QT_NUM_CHANNELS, \ 00428 QT_MAX_NUM_ROTORS_SLIDERS) 00429 00430 #elif (QTOUCH_SNS_PORT_COUNT == 2u) 00431 #if defined(_TOUCH_ARM_) 00432 /* Macros for string concatenation. */ 00433 #define JOIN3( a, b, c, e, f, d, z ) burst_ ## a ## _ ## b ## c ## _ ## e ## f 00434 #define BURST_JOIN( cycles, snsk1, sns1, snsk2, sns2, ch, rs ) JOIN3( cycles, snsk1, sns1, snsk2, sns2, ch, rs ) 00435 00436 /* Build pointer to correct burst function */ 00437 #define BURST_FUNC_NAME BURST_JOIN( QT_DELAY_CYCLES, QT_SNSK1_PORT , QT_SNS1_PORT, QT_SNSK2_PORT , QT_SNS2_PORT, QT_NUM_CHANNELS, \ 00438 QT_MAX_NUM_ROTORS_SLIDERS) 00439 #endif 00440 #else 00441 #error 'Invalid QTOUCH_SNS_PORT_COUNT value.' 00442 #endif 00443 00444 #endif 00445 00446 /* Burst function prototype. The code itself is stored in the touch library */ 00447 extern void BURST_FUNC_NAME( TOUCH_DATA_T mask_index ); 00448 00449 /* Function pointer used for bursting */ 00450 extern void (*burst_proc)( TOUCH_DATA_T mask_index); 00451 #endif 00452 00453 #endif 00454 00455 /****************************************************************************************************/ 00456 00457 /********************************************QMATRIX Start*************************************************/ 00458 00459 #ifdef _QMATRIX_ 00460 00461 #ifdef __AVR32__ 00462 #define TOUCH_DATA_T uint32_t 00463 #else 00464 #define TOUCH_DATA_T uint8_t 00465 #endif 00466 00467 /* Macros for string concatenation. */ 00468 #define BURST_JOIN(A,B) JOIN(A,B) 00469 #if (NUM_X_PORTS ==1) 00470 #define BURST_FUNC_1 BURST_JOIN(burst_qm_,PORT_NUM_1) 00471 extern void BURST_FUNC_1 (uint8_t channel, TOUCH_DATA_T x_mask); 00472 #elif (NUM_X_PORTS ==2) 00473 #define BURST_FUNC_1 BURST_JOIN(burst_qm_,PORT_NUM_1) 00474 extern void BURST_FUNC_1 (uint8_t channel, TOUCH_DATA_T x_mask); 00475 #define BURST_FUNC_2 BURST_JOIN(burst_qm_,PORT_NUM_2) 00476 extern void BURST_FUNC_2 (uint8_t channel, TOUCH_DATA_T x_mask); 00477 #elif (NUM_X_PORTS ==3) 00478 #define BURST_FUNC_1 BURST_JOIN(burst_qm_,PORT_NUM_1) 00479 extern void BURST_FUNC_1(uint8_t channel, TOUCH_DATA_T x_mask); 00480 #define BURST_FUNC_2 BURST_JOIN(burst_qm_,PORT_NUM_2) 00481 extern void BURST_FUNC_2(uint8_t channel, TOUCH_DATA_T x_mask); 00482 #define BURST_FUNC_3 BURST_JOIN(burst_qm_,PORT_NUM_3) 00483 extern void BURST_FUNC_3(uint8_t channel, TOUCH_DATA_T x_mask); 00484 #endif 00485 00486 /* Function pointer used for bursting */ 00487 extern void (*burst_proc_qm)( uint8_t channel, TOUCH_DATA_T drive_mask ); 00488 00489 /* pointer to function to be called for a channel */ 00490 typedef void (*PF_CHANNEL)( uint8_t channel ); 00491 00492 /* pointer to function returning void */ 00493 typedef void (*PFV)( uint8_t channel, uint8_t line_mask ); 00494 00495 /* info stored for each x line */ 00496 typedef struct tag_x_line_info_t 00497 { 00498 /* ptr to function to burst on this line */ 00499 PFV p_burst_function; 00500 00501 /* bit mask for driving/clamping this x line */ 00502 uint8_t mask; 00503 00504 /* index into array of burst masks */ 00505 uint8_t burst_mask_array_index; 00506 00507 } x_line_info_t; 00508 00509 /* info stored for each y line */ 00510 typedef struct tag_y_line_info_t 00511 { 00512 /* which bit this y line is on */ 00513 uint8_t bit; 00514 /* mask for y line*/ 00515 uint8_t mask; 00516 00517 } y_line_info_t; 00518 00519 /* enumeration of recognised burst masks */ 00520 typedef enum tag_burst_mask_t 00521 { 00522 BURST_MASK_Y, /*mask for y lines*/ 00523 BURST_MASK_X_PORT_1, /*mask for x lines on A*/ 00524 BURST_MASK_X_PORT_2, /*mask for x lines on A*/ 00525 BURST_MASK_X_PORT_3, /*mask for x lines on A*/ 00526 NUM_BURST_MASKS /*Total number of masks*/ 00527 00528 } burst_mask_t; 00529 00530 /* 00531 * The burst length on each QMatrix channel. 00532 * 00533 * Units: pulses 00534 * Default value: 64 pulses 00535 */ 00536 extern uint8_t qt_burst_lengths[QT_NUM_CHANNELS]; 00537 00538 #endif /* _QMATRIX_ */ 00539 00540 /********************************************QMATRIX End **************************************************/ 00541 00542 /* An unsigned 8-bit number setting a sensor detection threshold. */ 00543 typedef uint8_t threshold_t; 00544 00545 /* Options for the sensor types available. */ 00546 typedef enum tag_sensor_type_t 00547 { 00548 SENSOR_TYPE_UNASSIGNED, 00549 SENSOR_TYPE_KEY, 00550 SENSOR_TYPE_ROTOR, 00551 SENSOR_TYPE_SLIDER 00552 } sensor_type_t; 00553 00554 /* Which AKS group, if any, a sensor is in. 00555 * 00556 * NO_AKS_GROUP = sensor is not in an AKS group, and cannot be suppressed. 00557 * AKS_GROUP_x = sensor is in AKS group x. */ 00558 typedef enum tag_aks_group_t 00559 { 00560 NO_AKS_GROUP, 00561 AKS_GROUP_1, 00562 AKS_GROUP_2, 00563 AKS_GROUP_3, 00564 AKS_GROUP_4, 00565 AKS_GROUP_5, 00566 AKS_GROUP_6, 00567 AKS_GROUP_7 00568 } aks_group_t; 00569 00570 /* The channel(s) in a sensor. */ 00571 typedef enum tag_channel_t 00572 { 00573 #if (QT_NUM_CHANNELS > 0u) 00574 CHANNEL_0, 00575 CHANNEL_1, 00576 CHANNEL_2, 00577 CHANNEL_3 00578 #endif 00579 #if (QT_NUM_CHANNELS > 4u) 00580 ,CHANNEL_4, 00581 CHANNEL_5, 00582 CHANNEL_6, 00583 CHANNEL_7 00584 #endif 00585 #if (QT_NUM_CHANNELS > 8u) 00586 ,CHANNEL_8, 00587 CHANNEL_9, 00588 CHANNEL_10, 00589 CHANNEL_11 00590 #endif 00591 #if (QT_NUM_CHANNELS > 12u) 00592 ,CHANNEL_12, 00593 CHANNEL_13, 00594 CHANNEL_14, 00595 CHANNEL_15 00596 #endif 00597 #if (QT_NUM_CHANNELS > 16u) 00598 ,CHANNEL_16, 00599 CHANNEL_17, 00600 CHANNEL_18, 00601 CHANNEL_19, 00602 CHANNEL_20, 00603 CHANNEL_21, 00604 CHANNEL_22, 00605 CHANNEL_23 00606 #endif 00607 #if (QT_NUM_CHANNELS > 24u) 00608 ,CHANNEL_24, 00609 CHANNEL_25, 00610 CHANNEL_26, 00611 CHANNEL_27, 00612 CHANNEL_28, 00613 CHANNEL_29, 00614 CHANNEL_30, 00615 CHANNEL_31 00616 #endif 00617 #if (QT_NUM_CHANNELS > 32u) 00618 ,CHANNEL_32, 00619 CHANNEL_33, 00620 CHANNEL_34, 00621 CHANNEL_35, 00622 CHANNEL_36, 00623 CHANNEL_37, 00624 CHANNEL_38, 00625 CHANNEL_39, 00626 CHANNEL_40, 00627 CHANNEL_41, 00628 CHANNEL_42, 00629 CHANNEL_43, 00630 CHANNEL_44, 00631 CHANNEL_45, 00632 CHANNEL_46, 00633 CHANNEL_47, 00634 CHANNEL_48, 00635 CHANNEL_49, 00636 CHANNEL_50, 00637 CHANNEL_51, 00638 CHANNEL_52, 00639 CHANNEL_53, 00640 CHANNEL_54, 00641 CHANNEL_55 00642 #endif 00643 #if (QT_NUM_CHANNELS > 56u) 00644 ,CHANNEL_56, 00645 CHANNEL_57, 00646 CHANNEL_58, 00647 CHANNEL_59, 00648 CHANNEL_60, 00649 CHANNEL_61, 00650 CHANNEL_62, 00651 CHANNEL_63 00652 #endif 00653 } channel_t; 00654 00655 /* A sensor detection hysteresis value. This is expressed as a percentage of 00656 * the sensor detection threshold. 00657 * 00658 * HYST_x = hysteresis value is x% of detection threshold value (rounded down). 00659 * NB: a minimum value of 2 is used. 00660 * 00661 * Example: if detection threshold = 20, then: 00662 * HYST_50 = 10 (50% of 20) 00663 * HYST_25 = 5 (25% of 20) 00664 * HYST_12_5 = 2 (12.5% of 20) 00665 * HYST_6_25 = 2 (6.25% of 20 = 1, but value is hardlimited to 2) */ 00666 typedef enum tag_hysteresis_t 00667 { 00668 HYST_50, 00669 HYST_25, 00670 HYST_12_5, 00671 HYST_6_25 00672 } hysteresis_t; 00673 00674 /* For rotors and sliders, the resolution of the reported angle or position. 00675 * 00676 * RES_x_BIT = rotor/slider reports x-bit values. 00677 * 00678 * Example: if slider resolution is RES_7_BIT, then reported positions are in 00679 * the range 0..127. */ 00680 typedef enum tag_resolution_t 00681 { 00682 RES_1_BIT, 00683 RES_2_BIT, 00684 RES_3_BIT, 00685 RES_4_BIT, 00686 RES_5_BIT, 00687 RES_6_BIT, 00688 RES_7_BIT, 00689 RES_8_BIT 00690 } resolution_t; 00691 00692 /* A sensor recalibration threshold. This is expressed as a percentage of the 00693 * sensor detection threshold. 00694 * 00695 * RECAL_x = recalibration threshold is x% of detection threshold value 00696 * (rounded down). 00697 * NB: a minimum value of 4 is used. 00698 * 00699 * Example: if detection threshold = 40, then: 00700 * RECAL_100 = 40 (100% of 40) 00701 * RECAL_50 = 20 (50% of 40) 00702 * RECAL_25 = 10 (25% of 40) 00703 * RECAL_12_5 = 5 (12.5% of 40) 00704 * RECAL_6_25 = 4 (6.25% of 40 = 2, but value is hardlimited to 4) */ 00705 typedef enum tag_recal_threshold_t 00706 { 00707 RECAL_100, 00708 RECAL_50, 00709 RECAL_25, 00710 RECAL_12_5, 00711 RECAL_6_25 00712 } recal_threshold_t; 00713 00714 /* The state of the library sensors. */ 00715 typedef struct tag_qt_touch_status_t 00716 { 00717 /* The state (on/off) of the library sensors. 00718 * Bit 'n' = state of sensor 'n'. 00719 * Bit 0 = sensor_states[0] bit 0 00720 * Bit 1 = sensor_states[0] bit 1 00721 * ... 00722 * Bit 7 = sensor_states[0] bit 7 00723 * Bit 8 = sensor_states[1] bit 0 00724 * Bit 9 = sensor_states[1] bit 1 00725 * ... etc 00726 * 0 = not in detect, 1 = in detect.*/ 00727 uint8_t sensor_states[QT_NUM_SENSOR_STATE_BYTES]; 00728 /* Rotor angles or slider positions. 00729 * These values are valid when sensor_states shows that the corresponding 00730 * rotor or slider sensor is in detect.*/ 00731 uint8_t rotor_slider_values[QT_MAX_NUM_ROTORS_SLIDERS]; 00732 } qt_touch_status_t; 00733 00734 00735 /* post processing configuration data that is received from the debug interface. */ 00736 typedef struct tag_qt_touch_lib_config_data_t 00737 { 00738 /* Sensor recalibration threshold. */ 00739 recal_threshold_t qt_recal_threshold; 00740 /* Sensor detect integration (DI) limit. */ 00741 uint8_t qt_di; 00742 /* Sensor drift hold time. */ 00743 uint8_t qt_drift_hold_time; 00744 /* Sensor maximum on duration. */ 00745 uint8_t qt_max_on_duration; 00746 /* Sensor negative drift rate. */ 00747 uint8_t qt_neg_drift_rate; 00748 /* Sensor positive drift rate. */ 00749 uint8_t qt_pos_drift_rate; 00750 /* Positive recalibration delay. */ 00751 uint8_t qt_pos_recal_delay; 00752 } qt_touch_lib_config_data_t; 00753 00754 /* measured touch data that is sent for the debugging and fine tunning. */ 00755 typedef struct tag_qt_touch_lib_measure_data_t 00756 { 00757 /* measured signal on each channel */ 00758 unsigned short channel_signals[QT_NUM_CHANNELS]; // Modified to avoid IAR warning! 00759 /* reference signal for each channel */ 00760 unsigned short channel_references[QT_NUM_CHANNELS]; // Modified to avoid IAR warning! 00761 /* state of sensors */ 00762 qt_touch_status_t qt_touch_status; 00763 } qt_touch_lib_measure_data_t; 00764 00765 /* This will be used to get the library information from the library */ 00766 typedef struct qt_lib_sig_info_t 00767 { 00768 uint16_t lib_sig_lword; 00769 uint16_t lib_sig_hword; 00770 uint16_t library_version; 00771 }qt_lib_siginfo_t; 00772 00773 00774 typedef struct tag_sensor_t 00775 { 00776 /* sensor state (calibrating, on, ...) */ 00777 uint8_t state; 00778 00779 /* general purpose ctr: used for calibration, drifting, etc */ 00780 uint8_t general_counter; 00781 00782 /* DI ctr */ 00783 uint8_t ndil_counter; 00784 00785 /* sensor detection threshold */ 00786 uint8_t threshold; 00787 00788 /* 00789 * sensor type, AKS group, positive recal flag, and hysteresis value 00790 * bits 7..6: sensor type: 00: key 00791 * 01: rotor 00792 * 10: slider 00793 * 11: reserved 00794 * bits 5..3: AKS group (0..7): 0 = no AKS group 00795 * bit 2 : positive recal flag 00796 * bits 1..0: hysteresis 00797 */ 00798 uint8_t type_aks_pos_hyst; 00799 00800 /* 00801 * sensor from and to channels 00802 * keys: from channel = to channel 00803 * rotors/sliders run between the from and to channels 00804 * NB: only need to_channel for keys in rotors/sliders build 00805 */ 00806 uint8_t from_channel; 00807 00808 #ifdef _ROTOR_SLIDER_ 00809 uint8_t to_channel; 00810 00811 /* index into array of rotor/slider values */ 00812 uint8_t index; 00813 #endif /* _ROTOR_SLIDER_ */ 00814 00815 } sensor_t; 00816 00817 /*---------------------------------------------------------------------------- 00818 extern variables 00819 ----------------------------------------------------------------------------*/ 00820 /* This configuration data structure parameters if needs to be changed will be 00821 changed in the qt_set_parameters function */ 00822 extern qt_touch_lib_config_data_t qt_config_data; 00823 /* measurement data */ 00824 extern qt_touch_lib_measure_data_t qt_measure_data; 00825 /* Get sensor delta values */ 00826 extern int16_t qt_get_sensor_delta( uint8_t sensor); 00827 /* variable holding the status flags */ 00828 extern uint16_t lib_status_flags; 00829 /* the library sensors */ 00830 extern sensor_t sensors[QT_NUM_CHANNELS]; 00831 /* timer period in msec */ 00832 extern uint16_t qt_measurement_period_msec; 00833 00834 00835 /*This function is called after the library has made capacitive measurements, 00836 * but before it has processed them. The user can use this hook to apply filter 00837 * functions to the measured signal values. */ 00838 extern void (*qt_filter_callback)( void ); 00839 00840 /*============================================================================ 00841 Name : qt_get_library_sig 00842 ------------------------------------------------------------------------------ 00843 Purpose : Get the library signature 00844 Input : qt_lib_siginfo_t * lib_sig_ptr=Pointer to the library signature structure 00845 Output : n/a 00846 Notes : This API would provide the information of the 00847 library and fill into the structure 00848 ============================================================================*/ 00849 00850 extern void qt_get_library_sig(qt_lib_siginfo_t * lib_sig_ptr); 00851 00852 /*============================================================================ 00853 Name : qt_enable_key 00854 ------------------------------------------------------------------------------ 00855 Purpose : enable a key sensor 00856 Input : channel = which touch channel the key sensor uses 00857 aks_group = which AKS group (if any) the sensor is in 00858 detect_threshold = the sensor detection threshold 00859 detect_hysteresis = the sensor detection hysteresis value 00860 Output : n/a 00861 Notes : The sensor number corresponding to the key depends on the order in 00862 which sensors are enabled. The first sensor enabled is sensor 0, the 00863 second is sensor 1, and so on. 00864 00865 The current state of the key (on or off) can be checked in 00866 qt_touch_status.sensor_states. 00867 ============================================================================*/ 00868 extern void qt_enable_key( channel_t channel, 00869 aks_group_t aks_group, 00870 threshold_t detect_threshold, 00871 hysteresis_t detect_hysteresis ); 00872 00873 /*============================================================================ 00874 Name : qt_init_sensing 00875 ------------------------------------------------------------------------------ 00876 Purpose : initialise touch sensing 00877 Input : n/a 00878 Output : n/a 00879 Notes : Any sensors required must be enabled (using qt_enable_xxx()) before 00880 calling this function. 00881 00882 This function calculates internal library variables and configures 00883 the touch channels, and must be called before qt_measure_sensors(). 00884 ============================================================================*/ 00885 #if defined( _QTOUCH_ ) 00886 00887 #define qt_init_sensing( ) qt_init_sensing_with_burst( BURST_FUNC_NAME ,CALCULATE_MASKS) 00888 extern void qt_init_sensing_with_burst(void (*burst_function)(TOUCH_DATA_T mask_index), void (*calculate_masks)(void)); 00889 extern void calc_masks(void); 00890 #elif defined( _QMATRIX_ ) 00891 00892 #define qt_init_sensing( ) qt_init_sensing_with_burst( ) 00893 extern void qt_init_sensing_with_burst( ); 00894 00895 #endif 00896 00897 00898 /*============================================================================ 00899 Name : qt_measure_sensors 00900 ------------------------------------------------------------------------------ 00901 Purpose : measure touch sensors 00902 Input : current_time_ms = the current time, in ms 00903 Output : outputs the library status bits 00904 Notes : This function performs a capacitive measurement on all enabled 00905 sensors. The measured signals for each sensor are then processed to 00906 check for user touches, releases, changes in rotor angle, changes in 00907 slider position, etc. 00908 00909 The current state of all enabled sensors is reported in the 00910 qt_touch_status struct. 00911 00912 Before calling this function, one or more sensors must have been 00913 enabled (using qt_enable_xxx()), and qt_init_sensing() must 00914 have been called. 00915 ============================================================================*/ 00916 // Modified to avoid IAR warning! 00917 extern unsigned short qt_measure_sensors( unsigned short current_time_ms ); 00918 00919 00920 /*============================================================================ 00921 Name : qt_calibrate_sensing 00922 ------------------------------------------------------------------------------ 00923 Purpose : calibrate touch sensing 00924 Input : n/a 00925 Output : n/a 00926 Notes : This function forces a calibration of all enabled sensors. 00927 00928 This may be useful if, for instance, it is desired to globally 00929 recalibrate all sensors on a change in application operating mode. 00930 ============================================================================*/ 00931 extern void qt_calibrate_sensing( void ); 00932 00933 00934 /*============================================================================ 00935 Name : qt_reset_sensing 00936 ------------------------------------------------------------------------------ 00937 Purpose : reset touch sensing 00938 Input : n/a 00939 Output : n/a 00940 Notes : This function disables all enabled sensors, and returns all library 00941 variables (e.g., qt_di) to their default values. 00942 00943 This may be useful if it is desired to dynamically reconfigure 00944 sensing. After calling this function, any required sensors must be 00945 re-enabled, and qt_init_sensing() must be called before 00946 qt_measure_channels() is called again. 00947 ============================================================================*/ 00948 extern void qt_reset_sensing( void ); 00949 00950 /*============================================================================ 00951 Name : qt_get_sensor_delta 00952 ------------------------------------------------------------------------------ 00953 Purpose : get the current delta on the specified sensor 00954 Input : sensor = sensor number for which to get the delta 00955 Output : returns the delta on the specified sensor 00956 Notes : This function is supplied as a functional replacement for the 00957 sensor_deltas[] array provided in earlier library versions. 00958 ============================================================================*/ 00959 extern int16_t qt_get_sensor_delta( uint8_t sensor ); 00960 00961 #ifdef _ROTOR_SLIDER_ 00962 00963 /*============================================================================ 00964 Name : qt_enable_rotor 00965 ------------------------------------------------------------------------------ 00966 Purpose : enable a rotor sensor 00967 Input : from_channel = the first channel in the rotor sensor 00968 to_channel = the last channel in the rotor sensor 00969 aks_group = which AKS group (if any) the sensor is in 00970 detect_threshold = the sensor detection threshold 00971 detect_hysteresis = the sensor detection hysteresis value 00972 angle_resolution = the resolution of the reported angle value 00973 angle_hysteresis = the hysteresis of the reported angle value 00974 Output : n/a 00975 Notes : The sensor number corresponding to the rotor depends on the order in 00976 which sensors are enabled. The first sensor enabled is sensor 0, the 00977 second is sensor 1, and so on. 00978 00979 The current state of the rotor (on or off) can be checked in 00980 qt_touch_status.sensor_states. 00981 00982 The rotor value is in qt_touch_status.rotor_slider_values[]. Which 00983 array element is used depends on the order in which sensors are 00984 enabled. The first rotor or slider enabled will use 00985 rotor_slider_values[0], the second will use rotor_slider_values[1], 00986 and so on. 00987 00988 The reported rotor value is valid when the rotor is on. 00989 ============================================================================*/ 00990 extern void qt_enable_rotor( channel_t from_channel, 00991 channel_t to_channel, 00992 aks_group_t aks_group, 00993 threshold_t detect_threshold, 00994 hysteresis_t detect_hysteresis, 00995 resolution_t angle_resolution, 00996 uint8_t angle_hysteresis ); 00997 00998 /*============================================================================ 00999 Name : qt_enable_slider 01000 ------------------------------------------------------------------------------ 01001 Purpose : enable a slider sensor 01002 Input : from_channel = the first channel in the slider sensor 01003 to_channel = the last channel in the slider sensor 01004 aks_group = which AKS group (if any) the sensor is in 01005 detect_threshold = the sensor detection threshold 01006 detect_hysteresis = the sensor detection hysteresis value 01007 position_resolution = the resolution of the reported position value 01008 position_hysteresis = the hysteresis of the reported position value 01009 Output : n/a 01010 Notes : The sensor number corresponding to the slider depends on the order in 01011 which sensors are enabled. The first sensor enabled is sensor 0, the 01012 second is sensor 1, and so on. 01013 01014 The current state of the slider (on or off) can be checked in 01015 qt_touch_status.sensor_states. 01016 01017 The slider value is in qt_touch_status.rotor_slider_values[]. Which 01018 array element is used depends on the order in which sensors are 01019 enabled. The first rotor or slider enabled will use 01020 rotor_slider_values[0], the second will use rotor_slider_values[1], 01021 and so on. 01022 01023 The reported slider value is valid when the rotor is on. 01024 ============================================================================*/ 01025 extern void qt_enable_slider( channel_t from_channel, 01026 channel_t to_channel, 01027 aks_group_t aks_group, 01028 threshold_t detect_threshold, 01029 hysteresis_t detect_hysteresis, 01030 resolution_t position_resolution, 01031 uint8_t position_hysteresis ); 01032 01033 #endif 01034 01035 01036 #endif /* TOUCH_API_H */ 01037
