-
Notifications
You must be signed in to change notification settings - Fork 38
/
tsc2003.h
458 lines (412 loc) · 18.2 KB
/
tsc2003.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
/****************************************************************************
**
** Copyright (C) ${COPYRIGHT_YEAR} MikroElektronika d.o.o.
** Contact: https://www.mikroe.com/contact
**
** This file is part of the mikroSDK package
**
** Commercial License Usage
**
** Licensees holding valid commercial NECTO compilers AI licenses may use this
** file in accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The MikroElektronika Company.
** For licensing terms and conditions see
** https://www.mikroe.com/legal/software-license-agreement.
** For further information use the contact form at
** https://www.mikroe.com/contact.
**
**
** GNU Lesser General Public License Usage
**
** Alternatively, this file may be used for
** non-commercial projects under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** The above copyright notice and this permission notice shall be
** included in all copies or substantial portions of the Software.
**
** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
** OF MERCHANTABILITY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
** TO THE WARRANTIES FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
** DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
** OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
** OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
**
****************************************************************************/
/*!
* @file tsc2003.h
* @brief TSC2003 Resistive Touch Controller Driver.
*/
/**
* @brief Command byte representation:
*
* -----------------------------------------
* | C3 | C2 | C1 | C0 | PD1 | PD0 | M | X |
* -----------------------------------------
*
* @b Where:
* @b Cx represents config bits;
* @b PDx represents power down mode;
* @b M represents ADC resolution;
* @b X is not important ( Don't care );
*/
#ifndef _TSC2003_H_
#define _TSC2003_H_
#ifdef __cplusplus
extern "C"{
#endif
#include "drv_digital_out.h"
#include "drv_i2c_master.h"
#include "drv_digital_in.h"
#include "drv_name.h"
#include "tp.h"
/**
* @addtogroup middlewaregroup Middleware
* @brief This section includes the mikroSDK API Reference for Middleware Layer.
* @{
*/
/*!
* @addtogroup tsc2003 TSC2003 Touch Controllers Driver
* @brief TSC2003 Touch Controller Driver API Reference.
* @{
*/
/**
* @defgroup tsc2003_slave_addresses.
* @details I2C device address defined in database.
* @note Address depends on @b A0 and @b A1 jumpers
* on the back of the PCB.
* @{
*/
#define TSC2003_I2C_SLAVE_ADDR_FIXED (0x48)
#define TSC2003_I2C_SLAVE_ADDR_A0 (0x1)
#define TSC2003_I2C_SLAVE_ADDR_A1 (0x2)
#define TSC2003_I2C_SLAVE_ADDR_0 (TSC2003_I2C_SLAVE_ADDR_FIXED)
#define TSC2003_I2C_SLAVE_ADDR_1 (TSC2003_I2C_SLAVE_ADDR_FIXED | \
TSC2003_I2C_SLAVE_ADDR_A0)
#define TSC2003_I2C_SLAVE_ADDR_2 (TSC2003_I2C_SLAVE_ADDR_FIXED | \
TSC2003_I2C_SLAVE_ADDR_A1)
#define TSC2003_I2C_SLAVE_ADDR_3 (TSC2003_I2C_SLAVE_ADDR_FIXED | \
TSC2003_I2C_SLAVE_ADDR_A0 | \
TSC2003_I2C_SLAVE_ADDR_A1)
#ifdef TSC2003_I2C_SLAVE_ADDR_DB
#define TSC2003_I2C_SLAVE_ADDR_DEFAULT (TSC2003_I2C_SLAVE_ADDR_DB)
#else
#define TSC2003_I2C_SLAVE_ADDR_DEFAULT (TSC2003_I2C_SLAVE_ADDR_3)
#endif
/** @} */ // tsc2003_slave_addresses
/**
* @defgroup tsc2003_config_data Macro used to configure data byte.
* @{
*/
#define configureData(c,pd,m) ((c<<4)|(pd<<2)|(m<<1))
/** @} */ // tsc2003_config_data
/**
* @brief Map adequate control pins.
*/
#define TSC2003_MAP_PINS( cfg ) \
cfg.i2c_cfg.scl = CTP_SCL; \
cfg.i2c_cfg.sda = CTP_SDA; \
cfg.int_pin = CTP_INT
/**
* @defgroup tsc2003_bits_cfg Config nibbles.
* @details Higher nibble @b <7:4> used for operand values.
*
* | CONFIG BITS |
* ---------------------
* | C3 | C2 | C1 | C0 |
*
* @note
* Shifted to higher nibble in library.
*/
typedef enum {
tsc2003_bits_cfg_measure_temp0, /**< Measure ambient temperature method 1. */
tsc2003_bits_cfg_measure_vbat1, /**< Measure main battery voltage. */
tsc2003_bits_cfg_measure_in1, /**< Measure auxiliary input 1. */
tsc2003_bits_cfg_measure_temp1 = 0x4, /**< Measure ambient temperature method 2. */
tsc2003_bits_cfg_measure_vbat2, /**< Measure secondary battery voltage. */
tsc2003_bits_cfg_measure_in2, /**< Measure auxiliary input 2. */
tsc2003_bits_cfg_measure_activate_drivers_x = 0x8, /**< Activate X- drivers. */
tsc2003_bits_cfg_measure_activate_drivers_y, /**< Activate Y- drivers. */
tsc2003_bits_cfg_measure_activate_drivers_x_y, /**< Activate X-,Y+ plate drivers. */
tsc2003_bits_cfg_measure_position_x = 0xC, /**< measure X AD conversion. */
tsc2003_bits_cfg_measure_position_y, /**< Measure Y AD conversion. */
tsc2003_bits_cfg_measure_position_z1, /**< Measure Z1 AD conversion result. */
tsc2003_bits_cfg_measure_position_z2 /**< measure Z2 AD conversion result. */
} tsc2003_bits_cfg;
/** @} */ // tsc2003_bits_cfg
/**
* @defgroup tsc2003_bits_pd Power down values.
* @details Bits @b <3:2> used for values.
*
* | POWER DOWN |
* ---------------------
* | PD1 | PD2 |
*
* @note
* Shifted to adequate position in library.
*/
typedef enum {
tsc2003_bits_pd_power_down_between_conversion, /**< Power-Down Between Conversions. */
tsc2003_bits_pd_int_ref_off_adc_on, /**< Internal reference OFF, ADC ON. */
tsc2003_bits_pd_int_ref_on_adc_off, /**< Internal reference ON, ADC OFF. */
tsc2003_bits_pd_int_ref_on_adc_on /**< Internal reference ON, ADC ON. */
} tsc2003_bits_pd;
/** @} */ // tsc2003_bits_pd
/**
* @defgroup tsc2003_bits_m Mode bit values.
* @details Bit <1> used for value.
*
* | MODE |
* --------
* | M |
*
* @note
* Shifted to adequate position in library.
*/
typedef enum {
tsc2003_bits_m_12bit, /**< 12-bit AD conversion mode. */
tsc2003_bits_m_8bit /**< 8-bit AD conversion mode. */
} tsc2003_bits_m;
/** @} */ // tsc2003_bits_m
/**
* @brief Calibration data structure.
* @details Used for converting raw coordinate to actual pixel cordinate.
*/
typedef struct {
/**< Minimum raw x coordinate value. */
uint16_t min_x;
/**< Maximum raw x coordinate value. */
uint16_t max_x;
/**< Minimum raw y coordinate value. */
uint16_t min_y;
/**< Maximum raw y coordinate value. */
uint16_t max_y;
} tsc2003_calibration_data_t;
/**
* @brief Press intensity needed to register touch event.
*/
typedef struct {
uint16_t tsc2003_pressure_threshold_lower; /**< Lower threshold level. Typically 1000. */
uint16_t tsc2003_pressure_threshold_upper; /**< Upper threshold level. Typically 6000. */
} tsc2003_pressure_threshold_t;
/**
* @brief Default calibration data specific for MikroE resistive tft boards.
* @details Data useful for skipping calibration when working with MikroE hardware.
* Gives reasonable touch precision on any size resitive tft board.
*/
extern const tsc2003_calibration_data_t TSC2003_CALIBRATION_DATA_DEFAULT;
/**
* @brief TSC2003 Configuration Object.
* @details Configuration object definition for TSC2003 touch controller.
*/
typedef struct {
pin_name_t int_pin; /**< Interrupt pin. */
i2c_master_config_t i2c_cfg; /**< Configuration of communication module. */
uint16_t width; /**< Touch panel width in pixels. */
uint16_t height; /**< Touch panel height in pixels. */
uint8_t addr_sel; /**< I2C slave address of TSC2003. */
tsc2003_bits_m resolution; /**< AD conversion resolution. */
tsc2003_bits_pd power_down; /**< Power down state between AD conversions. */
/**< Press intensity needed to register touch event. */
tsc2003_pressure_threshold_t pressure_threshold_level;
} tsc2003_cfg_t;
/**
* @brief TSC2003 Context Object.
* @details Context object definition for TSC2003 touch controller.
* This structure holds information about the current state of the controller.
* @warning Changing values inside this structure is not recomended as it can cause unwanted and incorrect
* behaviour when used with @ref tsc2003_process function.
*/
typedef struct {
digital_in_t int_pin; /**< Interrupt pin object. */
i2c_master_t i2c; /**< Communication module object. */
uint16_t width; /**< Touch panel width in pixels. */
uint16_t height; /**< Touch panel height in pixels. */
tp_event_t press_det; /**< Touch pressure event. */
tp_touch_item_t touch; /**< Touch item. */
tp_event_t gesture; /**< Gesture event. */
bool pen_down; /**< Utility helper variable used for interpreting events. */
tsc2003_bits_m resolution; /**< AD conversion resolution. */
tsc2003_bits_pd power_down; /**< Power down state between AD conversions. */
/**< Press intensity needed to register touch event. */
tsc2003_pressure_threshold_t pressure_threshold_level;
/**< Calibration constants used for converting raw ADC touch data to actual pixel coordinates.*/
tsc2003_calibration_data_t calibration_data;
} tsc2003_t;
/**
* @brief TSC2003 configuration object setup function
* @details This function initializes TSC2003 configuration structure to default values.
* Interupt pin will be set to unconnected, screen dimenstion will be set to 0,
* press threshold will be set to default defined values.
* @param[out] cfg TSC2003 configuration object.
* @retval Nothing.
*/
void tsc2003_cfg_setup( tsc2003_cfg_t * cfg );
/**
* @brief TSC2003 Initialization Function.
* @details This function initializes TSC2003 context object using configuration values
* from TSC2003 configuration object and allows touch panel driver interface object
* to be linked with TSC2003 driver functions.
* @note By default, TSC2003 stucture is initialized with calibration constants for
* MikroE harware, in case of different hardware @ref tsc2003_set_calibration_data is available
* for seting already determined calibration constants and @ref tsc2003_calibrate is available
* for determinig new calibraiton constants.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @param[in] cfg TSC2003 configuration object. See @ref tsc2003_cfg_t structure
* definition for detailed explanation.
* @param[out] drv TP driver interface object. See @ref tp_drv_t structure
* definition for detailed explanation.
* @retval @li @c TP_OK OK,
* @li @c TP_ERR_INIT_DRV I2C driver init error,
* @li @c TP_ERR_UNSUPPORTED_PIN Unsupported pin.
* See @ref tp_err_t structure definition for detailed explanation.
*/
tp_err_t tsc2003_init( tsc2003_t * ctx, tsc2003_cfg_t * cfg, tp_drv_t * drv );
/**
* @brief TSC2003 Default Configuration Function.
* @details Configures the device by powering the module down initially.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @retval Nothing.
*/
void tsc2003_default_cfg( tsc2003_t* ctx );
/**
* @brief Copies touch information from context object to touch item object
* @details This function is necessary for interfacing with touch panel library as it's
* address is stored in tp_drv_t driver structure during the TSC2003 context initialization.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @param[out] touch_item
* @return Nothing.
*/
void tsc2003_press_coordinates( tsc2003_t* ctx, tp_touch_item_t * touch_item );
/**
* @brief Press detection function.
* @details Retrives information about press detection from TSC2003.
* @note This function is necessary for interfacing with touch panel library as its
* address is stored in tp_drv_t driver structure during the TSC2003 context initialization.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @retval @li @c TP_EVENT_PRESS_NOT_DET - Touch pressure is not detected.
* @li @c TP_EVENT_PRESS_DET - Touch pressure is detected.
* See @ref tp_err_t structure definition for detailed explanation.
*/
tp_event_t tsc2003_press_detect( tsc2003_t* ctx );
/**
* @brief Function processing events.
* @details This function checks if touch was detected and if it was, reads
* and stores touch information in context structure and checks if it's touch down or up.
* @note This function is necessary for interfacing with touch panel library as its
* address is stored in tp_drv_t driver structure during the TSC2003 context initialization.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @retval Always returns @b TP_OK. see @ref tp_err_t for more details.
*/
tp_err_t tsc2003_process( tsc2003_t * ctx );
/**
* @brief Read gesture information.
* @details Since TSC2003 does not support gestures this function is purely for interfacing
* with the tp library. Gesture returned from the function is always no gesture.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @note This function is necessary for interfacing with touch panel library as it's
* address is stored in tp_drv_t driver structure during the TSC2003 context initialization.
* @param[out] event Touch panel gesture data, always TP_EVENT_GEST_NONE. See @ref tp_event_t * definition
* for detailed explanation.
* @retval Nothing.
*/
void tsc2003_gesture( tsc2003_t* ctx, tp_event_t * event );
/**
* @brief Writes a generic command to the IC.
* @details This function provides easy write access to the TSC2003 IC.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @param[in] reg_addr Register address with adequate configuration.
* @note Register address is defined as follows:
* -----------------------------------------
* | C3 | C2 | C1 | C0 | PD1 | PD0 | M | X |
* -----------------------------------------
* @b Where:
* @b Cx represents config bits; - see @ref tsc2003_bits_cfg
* @b PDx represents power down mode; - see @ref tsc2003_bits_pd
* @b M represents ADC resolution; - see @ref tsc2003_bits_m
* @b X is not important ( Don't care );
* The formatted address will be:
* @b ((Cx<<4) | @b (PDx<<2) | @b (M<<1))
* @retval Nothing.
*/
void tsc2003_write_cmd( tsc2003_t * ctx, uint8_t reg_addr );
/**
* @brief Reads a number of bytes from a register.
* @details This function provides easy read from a TSC2003 register.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @param[in] reg_addr Register address from which single byte will be read.
* @note Register address is defined as follows:
* -----------------------------------------
* | C3 | C2 | C1 | C0 | PD1 | PD0 | M | X |
* -----------------------------------------
* @b Where:
* @b Cx represents config bits; - see @ref tsc2003_bits_cfg
* @b PDx represents power down mode; - see @ref tsc2003_bits_pd
* @b M represents ADC resolution; - see @ref tsc2003_bits_m
* @b X is not important ( Don't care );
* The formatted address will be:
* @b ((Cx<<4) | @b (PDx<<2) | @b (M<<1))
* @param[out] data_buff Buffer for returning read data from IC.
* @param[in] len Number of data to read from the IC.
* @retval Nothing.
*/
void tsc2003_generic_read( tsc2003_t * ctx, uint8_t reg_addr, uint8_t *data_buff, uint8_t len );
/**
* @brief Calibrates variables used for converting raw TSC2003 ADC values to pixel coordinates
* @details Function nees the user to touch all four corners as close to the edges as possible
* to find the extreme values. Function also supports holding a pen and moving it across the screen and
* will use the most extreme coordinates found during that move as corner coordinates, so touching
* a screen and draging a finger over the one of the four edges unitl touch is no longer detected
* will give pretty good calibration data.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @retval Nothing.
*/
void tsc2003_calibrate( tsc2003_t* ctx );
/**
* @brief Utility funciton used for getting a copy of current calibration data.
* @details Function copies data that's being e used for converting raw ADC values
* to actual pixel coordinates.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* @param[out] cdata Pointer to memory where calibration data will be stored.
* @retval Nothing.
*/
void tsc2003_get_calibration_data( tsc2003_t * ctx, tsc2003_calibration_data_t * cdata );
/**
* @brief Utility funciton used for setting calibration data.
* @details Function copies data stored in @p cdata. That information will be be used for
* converting raw ADC values to actual pixel coordinates.
* @param[in] ctx Initialized TSC2003 context structure. See @ref tsc2003_t for more
* information about the context structure.
* @param[out] cdata Pointer to memory from where new calibration will be copied and set.
* @retval Nothing.
*/
void tsc2003_set_calibration_data( tsc2003_t * ctx, const tsc2003_calibration_data_t * cdata );
/**
* @brief Utility funciton used for setting threshold levels.
* @details Function copies data stored in @p pressure. That information will be be used for
* checking if adquate pressure has been applied to the screen.
* @param[out] cfg Initialized TSC2003 context structure. See @ref tsc2003_t for more
* @param[in] pressure Structure with desired threshold levels set.
* See @ref tsc2003_pressure_threshold_t for more information about the structure.
* @retval Nothing.
*/
void tsc2003_set_pressure_threshold_level( tsc2003_cfg_t * cfg, tsc2003_pressure_threshold_t pressure );
/*! @} */ // middlewaregroup
/*! @} */ // tsc2003
#ifdef __cplusplus
}
#endif
#endif // _TSC2003_H_
// ------------------------------------------------------------------------ END