This is the QTouch Library for AVR and AVR32 devices that consists of one api header file(touch_api.h) and respective pre-compiled libraries.
All projects using these libraries must also provide the required header file(touch_qt_config.h) used to configure the library. For more information on the Qtouch Library, check www.atmel.com/qtouchlib.
Data Structures | |
| struct | qt_lib_sig_info_t |
| struct | tag_qt_touch_lib_config_data_t |
| struct | tag_qt_touch_lib_measure_data_t |
| struct | tag_qt_touch_status_t |
| struct | tag_sensor_t |
| struct | tag_x_line_info_t |
| struct | tag_y_line_info_t |
Macros | |
| #define | BURST_FUNC_1 BURST_JOIN(burst_qm_, PORT_NUM_1) |
| #define | BURST_FUNC_2 BURST_JOIN(burst_qm_, PORT_NUM_2) |
| #define | BURST_JOIN(A, B) JOIN(A, B) |
| #define | CONCAT(A, B, C) JOIN1( A, B, C ) |
| #define | FILL_OUT_X_LINE_INFO(port_num, x_bit) |
| QTouch libraries are supplied built with a range of charge times. More... | |
| #define | FILL_OUT_Y_LINE_INFO(bit) { bit, (TOUCH_DATA_T)(1u << bit) } |
| Info stored for each y line. More... | |
| #define | FILL_OUT_YA_LINE_INFO(bit) { bit, (uint8_t)(1u << bit) } |
| Info stored for each ya line. More... | |
| #define | FILL_OUT_YB_LINE_INFO(bit) { bit, (uint8_t)(1u << bit) } |
| Info stored for each yb line. More... | |
| #define | JOIN(x, y) x ## y |
| Error Checking For the User Configuration Options ends here. More... | |
| #define | JOIN1(A, B, C) A ## B ## C |
| #define | qt_init_sensing() qt_init_sensing_with_burst() |
| initialise touch sensing. More... | |
| #define | QT_NUM_SENSOR_STATE_BYTES ((QT_NUM_CHANNELS + 7u) / 8u) |
| The number of bytes required to report the maximum possible number of sensors. More... | |
| #define | QTLIB_BURST_AGAIN (uint16_t)0x0100 |
| #define | QTLIB_CHANNEL_REF_CHANGE (uint16_t)0x0008 |
| #define | QTLIB_IN_DETECT (uint16_t)0x0001 |
| #define | QTLIB_NO_ACTIVITY (uint16_t)0x0000 |
| Status flags used with debug. More... | |
| #define | QTLIB_RESOLVE_CAL (uint16_t)0x0200 |
| #define | QTLIB_RESOLVE_DI (uint16_t)0x0800 |
| #define | QTLIB_RESOLVE_FILTERIN (uint16_t)0x0400 |
| #define | QTLIB_RESOLVE_POS_RECAL (uint16_t)0x1000 |
| #define | QTLIB_ROTOR_SLIDER_POS_CHANGE (uint16_t)0x0004 |
| #define | QTLIB_STATUS_CHANGE (uint16_t)0x0002 |
| #define | REG(REGISTER, SIDE) JOIN( REGISTER, SIDE ) |
| Macro to build register writes for controlling ports. More... | |
| #define | TOUCH_DATA_T uint8_t |
| This part of the code below is used for library selection. More... | |
Functions | |
| void | BURST_FUNC_1 (uint8_t channel, TOUCH_DATA_T x_mask) |
| void | BURST_FUNC_2 (uint8_t channel, TOUCH_DATA_T x_mask) |
| void | qt_calibrate_sensing (void) |
| calibrate touch sensing. More... | |
| void | qt_enable_key (channel_t channel, aks_group_t aks_group, threshold_t detect_threshold, hysteresis_t detect_hysteresis) |
| enable a key sensor. More... | |
| void | qt_enable_rotor (channel_t from_channel, channel_t to_channel, aks_group_t aks_group, threshold_t detect_threshold, hysteresis_t detect_hysteresis, resolution_t angle_resolution, uint8_t angle_hysteresis) |
| enable a rotor sensor. More... | |
| void | qt_enable_slider (channel_t from_channel, channel_t to_channel, aks_group_t aks_group, threshold_t detect_threshold, hysteresis_t detect_hysteresis, resolution_t position_resolution, uint8_t position_hysteresis) |
| enable a slider sensor. More... | |
| void | qt_get_library_sig (qt_lib_siginfo_t *lib_sig_ptr) |
| Get the library signature. More... | |
| int16_t | qt_get_sensor_delta (uint8_t sensor) |
| get the current delta on the specified sensor. More... | |
| void | qt_init_sensing_with_burst () |
| uint16_t | qt_measure_sensors (uint16_t current_time_ms) |
| measure touch sensors. More... | |
| void | qt_reset_sensing (void) |
| reset touch sensing. More... | |
| #define BURST_FUNC_1 BURST_JOIN(burst_qm_, PORT_NUM_1) |
| #define BURST_FUNC_2 BURST_JOIN(burst_qm_, PORT_NUM_2) |
| #define BURST_JOIN | ( | A, | |
| B | |||
| ) | JOIN(A, B) |
| #define CONCAT | ( | A, | |
| B, | |||
| C | |||
| ) | JOIN1( A, B, C ) |
| #define FILL_OUT_X_LINE_INFO | ( | port_num, | |
| x_bit | |||
| ) |
QTouch libraries are supplied built with a range of charge times.
Charge time is the duration in which charge is transferred from the AVR onto the measurement capacitor. Shorter charge times result in faster measurements, but may be too fast to completely transfer charge onto the measurement capacitor.
The range of charge times lets the user choose a suitable version for the clock rate their chip is running at.
To make capacitive measurements, a charge time on the order of 0.25us to 2.5us is typically required. The following table shows the charge times corresponding to a range of clock speeds.
Clock speed (MHz) Cycle time (us) Suitable charge times
1 1 1~2 cycles (1us to 2us) 2 0.5 1~5 cycles (0.5us to 2.5us) 4 0.25 1~10 cycles (0.25us to 2.5us) 8 0.125 2~10 cycles (0.25us to 1.25us) 10 0.1 3~25 cycles (0.3us to 2.5us) 16 0.0625 4~25 cycles (0.25us to 1.5625s) 20 0.05 5~50 cycles (0.25us to 2.5us) Error Checking For the User Configuration Options Starts here. Info stored for each x line.
For each X line, enter the port and pin it is on. For instance, if X3 is on PB1, the 4th entry would be FILL_OUT_X_LINE_INFO( 1,1 ), and PORT_X_1 is B
| #define FILL_OUT_Y_LINE_INFO | ( | bit | ) | { bit, (TOUCH_DATA_T)(1u << bit) } |
Info stored for each y line.
For each Y line, enter the pin it is on. For instance, if Y2 is on PA5 and PF5, the 3th entry would be FILL_OUT_Y_LINE_INFO( 5 ) NOTE: 1. The PORTs for YA and YB on which Y lines are going to be needs to be defined as PORT_YA and PORT_YB.
Example: PORT_YA=A and PORT_YB=F in the case above.
| #define FILL_OUT_YA_LINE_INFO | ( | bit | ) | { bit, (uint8_t)(1u << bit) } |
Info stored for each ya line.
For each YA line, enter the pin it is on. For instance, if Y2A is on PA5 , the 3th entry would be FILL_OUT_YA_LINE_INFO( 5 ) NOTE: 1. The PORTs for YA and YB on which Y lines are going to be needs to be defined as PORT_YA and PORT_YB.
Example: PORT_YA=A in the case above.
| #define FILL_OUT_YB_LINE_INFO | ( | bit | ) | { bit, (uint8_t)(1u << bit) } |
Info stored for each yb line.
For each YB line, enter the pin it is on. For instance, if Y2B is on PF3, the 3th entry would be FILL_OUT_YB_LINE_INFO( 3 ) NOTE: 1. The PORTs for YA and YB on which Y lines are going to be needs to be defined as PORT_YA and PORT_YB.
Example: PORT_YB=F in the case above.
| #define JOIN | ( | x, | |
| y | |||
| ) | x ## y |
Error Checking For the User Configuration Options ends here.
Utility macro for expanding port registers.
| #define JOIN1 | ( | A, | |
| B, | |||
| C | |||
| ) | A ## B ## C |
| #define qt_init_sensing | ( | ) | qt_init_sensing_with_burst() |
initialise touch sensing.
This function calculates internal library variables and configures the touch channels, and must be called before qt_measure_sensors().
Referenced by BSP_InitQTouch().
| #define QT_NUM_SENSOR_STATE_BYTES ((QT_NUM_CHANNELS + 7u) / 8u) |
The number of bytes required to report the maximum possible number of sensors.
| #define QTLIB_BURST_AGAIN (uint16_t)0x0100 |
Referenced by Touch_measurement().
| #define QTLIB_CHANNEL_REF_CHANGE (uint16_t)0x0008 |
| #define QTLIB_IN_DETECT (uint16_t)0x0001 |
| #define QTLIB_NO_ACTIVITY (uint16_t)0x0000 |
Status flags used with debug.
| #define QTLIB_RESOLVE_CAL (uint16_t)0x0200 |
| #define QTLIB_RESOLVE_DI (uint16_t)0x0800 |
| #define QTLIB_RESOLVE_FILTERIN (uint16_t)0x0400 |
| #define QTLIB_RESOLVE_POS_RECAL (uint16_t)0x1000 |
| #define QTLIB_ROTOR_SLIDER_POS_CHANGE (uint16_t)0x0004 |
| #define QTLIB_STATUS_CHANGE (uint16_t)0x0002 |
| #define REG | ( | REGISTER, | |
| SIDE | |||
| ) | JOIN( REGISTER, SIDE ) |
Macro to build register writes for controlling ports.
The intermediate JOIN macro is required for correct expansion of the args.
| #define TOUCH_DATA_T uint8_t |
This part of the code below is used for library selection.
This code will not be documented. QMATRIX Start.
| typedef enum tag_aks_group_t aks_group_t |
Which AKS group, if any, a sensor is in.
NO_AKS_GROUP = sensor is not in an AKS group, and cannot be suppressed. AKS_GROUP_x = sensor is in AKS group x.
| typedef enum tag_burst_mask_t burst_mask_t |
| typedef enum tag_channel_t channel_t |
| typedef enum tag_hysteresis_t hysteresis_t |
A sensor detection hysteresis value.
This is expressed as a percentage of the sensor detection threshold.
HYST_x = hysteresis value is x% of detection threshold value (rounded down). NB: a minimum value of 2 is used.
Example: if detection threshold = 20, then: HYST_50 = 10 (50% of 20) HYST_25 = 5 (25% of 20) HYST_12_5 = 2 (12.5% of 20) HYST_6_25 = 2 (6.25% of 20 = 1, but value is hardlimited to 2)
| typedef void(* PF_CHANNEL)(uint8_t channel) |
| typedef void(* PFV)(uint8_t channel, TOUCH_DATA_T line_mask) |
| typedef struct qt_lib_sig_info_t qt_lib_siginfo_t |
| typedef struct tag_qt_touch_lib_config_data_t qt_touch_lib_config_data_t |
| typedef struct tag_qt_touch_lib_measure_data_t qt_touch_lib_measure_data_t |
| typedef struct tag_qt_touch_status_t qt_touch_status_t |
| typedef enum tag_recal_threshold_t recal_threshold_t |
A sensor recalibration threshold.
This is expressed as a percentage of the sensor detection threshold.
RECAL_x = recalibration threshold is x% of detection threshold value (rounded down). NB: a minimum value of 4 is used.
Example: if detection threshold = 40, then: RECAL_100 = 40 (100% of 40) RECAL_50 = 20 (50% of 40) RECAL_25 = 10 (25% of 40) RECAL_12_5 = 5 (12.5% of 40) RECAL_6_25 = 4 (6.25% of 40 = 2, but value is hardlimited to 4)
| typedef enum tag_resolution_t resolution_t |
For rotors and sliders, the resolution of the reported angle or position.
RES_x_BIT = rotor/slider reports x-bit values.
Example: if slider resolution is RES_7_BIT, then reported positions are in the range 0..127.
| typedef struct tag_sensor_t sensor_t |
| typedef enum tag_sensor_type_t sensor_type_t |
| typedef uint8_t threshold_t |
QMATRIX End.
| typedef struct tag_x_line_info_t x_line_info_t |
| typedef struct tag_y_line_info_t y_line_info_t |
| enum tag_aks_group_t |
| enum tag_burst_mask_t |
| enum tag_channel_t |
| enum tag_hysteresis_t |
A sensor detection hysteresis value.
This is expressed as a percentage of the sensor detection threshold.
HYST_x = hysteresis value is x% of detection threshold value (rounded down). NB: a minimum value of 2 is used.
Example: if detection threshold = 20, then: HYST_50 = 10 (50% of 20) HYST_25 = 5 (25% of 20) HYST_12_5 = 2 (12.5% of 20) HYST_6_25 = 2 (6.25% of 20 = 1, but value is hardlimited to 2)
| Enumerator | |
|---|---|
| HYST_50 | |
| HYST_25 | |
| HYST_12_5 | |
| HYST_6_25 | |
A sensor recalibration threshold.
This is expressed as a percentage of the sensor detection threshold.
RECAL_x = recalibration threshold is x% of detection threshold value (rounded down). NB: a minimum value of 4 is used.
Example: if detection threshold = 40, then: RECAL_100 = 40 (100% of 40) RECAL_50 = 20 (50% of 40) RECAL_25 = 10 (25% of 40) RECAL_12_5 = 5 (12.5% of 40) RECAL_6_25 = 4 (6.25% of 40 = 2, but value is hardlimited to 4)
| Enumerator | |
|---|---|
| RECAL_100 | |
| RECAL_50 | |
| RECAL_25 | |
| RECAL_12_5 | |
| RECAL_6_25 | |
| enum tag_resolution_t |
For rotors and sliders, the resolution of the reported angle or position.
RES_x_BIT = rotor/slider reports x-bit values.
Example: if slider resolution is RES_7_BIT, then reported positions are in the range 0..127.
| Enumerator | |
|---|---|
| RES_1_BIT | |
| RES_2_BIT | |
| RES_3_BIT | |
| RES_4_BIT | |
| RES_5_BIT | |
| RES_6_BIT | |
| RES_7_BIT | |
| RES_8_BIT | |
| enum tag_sensor_type_t |
| void BURST_FUNC_1 | ( | uint8_t | channel, |
| TOUCH_DATA_T | x_mask | ||
| ) |
| void BURST_FUNC_2 | ( | uint8_t | channel, |
| TOUCH_DATA_T | x_mask | ||
| ) |
| void qt_calibrate_sensing | ( | void | ) |
calibrate touch sensing.
| void qt_enable_key | ( | channel_t | channel, |
| aks_group_t | aks_group, | ||
| threshold_t | detect_threshold, | ||
| hysteresis_t | detect_hysteresis | ||
| ) |
enable a key sensor.
| channel,: | which touch channel the key sensor uses |
| aks_group,: | which AKS group (if any) the sensor is in |
| detect_threshold,: | the sensor detection threshold |
| detect_hysteresis,: | the sensor detection hysteresis value |
The current state of the key (on or off) can be checked in qt_touch_status.sensor_states.
Referenced by config_sensors().
| void qt_enable_rotor | ( | channel_t | from_channel, |
| channel_t | to_channel, | ||
| aks_group_t | aks_group, | ||
| threshold_t | detect_threshold, | ||
| hysteresis_t | detect_hysteresis, | ||
| resolution_t | angle_resolution, | ||
| uint8_t | angle_hysteresis | ||
| ) |
enable a rotor sensor.
| from_channel,: | the first channel in the rotor sensor |
| to_channel,: | the last channel in the rotor sensor |
| aks_group,: | which AKS group (if any) the sensor is in |
| detect_threshold,: | the sensor detection threshold |
| detect_hysteresis,: | the sensor detection hysteresis value |
| angle_resolution,: | the resolution of the reported angle value |
| angle_hysteresis,: | the hysteresis of the reported angle value |
The current state of the rotor (on or off) can be checked in qt_touch_status.sensor_states.
The rotor value is in qt_touch_status.rotor_slider_values[]. Which array element is used depends on the order in which sensors are enabled. The first rotor or slider enabled will use and so on.
The reported rotor value is valid when the rotor is on.
Referenced by config_sensors().
| void qt_enable_slider | ( | channel_t | from_channel, |
| channel_t | to_channel, | ||
| aks_group_t | aks_group, | ||
| threshold_t | detect_threshold, | ||
| hysteresis_t | detect_hysteresis, | ||
| resolution_t | position_resolution, | ||
| uint8_t | position_hysteresis | ||
| ) |
enable a slider sensor.
| from_channel,: | the first channel in the slider sensor |
| to_channel,: | the last channel in the slider sensor |
| aks_group,: | which AKS group (if any) the sensor is in |
| detect_threshold,: | the sensor detection threshold |
| detect_hysteresis,: | the sensor detection hysteresis value |
| position_resolution,: | the resolution of the reported position value |
| position_hysteresis,: | the hysteresis of the reported position value |
The current state of the slider (on or off) can be checked in qt_touch_status.sensor_states.
The slider value is in qt_touch_status.rotor_slider_values[]. Which array element is used depends on the order in which sensors are enabled. The first rotor or slider enabled will use rotor_slider_values[0], the second will use rotor_slider_values[1], and so on.
The reported slider value is valid when the rotor is on.
| void qt_get_library_sig | ( | qt_lib_siginfo_t * | lib_sig_ptr | ) |
Get the library signature.
| qt_lib_siginfo_t,: | lib_sig_ptr=Pointer to the library signature structure |
| int16_t qt_get_sensor_delta | ( | uint8_t | sensor | ) |
get the current delta on the specified sensor.
| sensor,: | sensor number for which to get the delta. |
| void qt_init_sensing_with_burst | ( | ) |
| uint16_t qt_measure_sensors | ( | uint16_t | current_time_ms | ) |
measure touch sensors.
| current_time_ms,: | the current time, in ms |
The current state of all enabled sensors is reported in the qt_touch_status struct.
Before calling this function, one or more sensors must have been enabled (using qt_enable_xxx()), and qt_init_sensing() must have been called.
Referenced by Touch_measurement().
| void qt_reset_sensing | ( | void | ) |
reset touch sensing.
This may be useful if it is desired to dynamically reconfigure sensing. After calling this function, any required sensors must be re-enabled, and qt_init_sensing() must be called before qt_measure_channels() is called again.
Referenced by BSP_InitQTouch().
| TOUCH_DATA_T tag_y_line_info_t::bit |
| TOUCH_DATA_T tag_x_line_info_t::burst_mask_array_index |
| void(* burst_proc_qm)(uint8_t channel, TOUCH_DATA_T drive_mask) |
| uint16_t tag_qt_touch_lib_measure_data_t::channel_references[QT_NUM_CHANNELS] |
| uint16_t tag_qt_touch_lib_measure_data_t::channel_signals[QT_NUM_CHANNELS] |
Referenced by qt_avr477_filter_cb(), and Touch_measurement().
| uint8_t tag_sensor_t::from_channel |
sensor from and to channels keys: from channel = to channel rotors/sliders run between the from and to channels NB: only need to_channel for keys in rotors/sliders build
| uint8_t tag_sensor_t::general_counter |
| uint8_t tag_sensor_t::index |
| uint16_t qt_lib_sig_info_t::lib_sig_hword |
| uint16_t qt_lib_sig_info_t::lib_sig_lword |
| uint16_t lib_status_flags |
| uint16_t qt_lib_sig_info_t::library_version |
| TOUCH_DATA_T tag_x_line_info_t::mask |
| TOUCH_DATA_T tag_y_line_info_t::mask |
| uint8_t tag_sensor_t::ndil_counter |
| PFV tag_x_line_info_t::p_burst_function |
| uint8_t qt_burst_lengths[QT_NUM_CHANNELS] |
The burst length on each QMatrix channel.
Units: pulses Default value: 64 pulses
| qt_touch_lib_config_data_t qt_config_data |
This configuration data structure parameters if needs to be changed will be changed in the qt_set_parameters function.
| uint8_t tag_qt_touch_lib_config_data_t::qt_di |
Referenced by qt_set_parameters().
| uint8_t tag_qt_touch_lib_config_data_t::qt_drift_hold_time |
Referenced by qt_set_parameters().
| void(* qt_filter_callback)(void) |
This function is called after the library has made capacitive measurements, but before it has processed them. The user can use this hook to apply filter functions to the measured signal values.
Referenced by BSP_InitQTouch().
| uint8_t tag_qt_touch_lib_config_data_t::qt_max_on_duration |
Referenced by qt_set_parameters().
| qt_touch_lib_measure_data_t qt_measure_data |
Referenced by qt_avr477_filter_cb(), and Touch_measurement().
| uint16_t qt_measurement_period_msec |
Referenced by init_timer_isr(), and touch_interrupt_call_back().
| uint8_t tag_qt_touch_lib_config_data_t::qt_neg_drift_rate |
Referenced by qt_set_parameters().
| uint8_t tag_qt_touch_lib_config_data_t::qt_pos_drift_rate |
Referenced by qt_set_parameters().
| uint8_t tag_qt_touch_lib_config_data_t::qt_pos_recal_delay |
Referenced by qt_set_parameters().
| recal_threshold_t tag_qt_touch_lib_config_data_t::qt_recal_threshold |
Referenced by qt_set_parameters().
| qt_touch_status_t tag_qt_touch_lib_measure_data_t::qt_touch_status |
Referenced by Touch_measurement().
| uint8_t tag_qt_touch_status_t::rotor_slider_values[QT_MAX_NUM_ROTORS_SLIDERS] |
Rotor angles or slider positions.
These values are valid when sensor_states shows that the corresponding rotor or slider sensor is in detect.
| uint8_t tag_qt_touch_status_t::sensor_states[QT_NUM_SENSOR_STATE_BYTES] |
The state (on/off) of the library sensors.
Bit 'n' = state of sensor 'n'. Bit 0 = sensor_states[0] bit 0 Bit 1 = sensor_states[0] bit 1 ... Bit 7 = sensor_states[0] bit 7 Bit 8 = sensor_states[1] bit 0 Bit 9 = sensor_states[1] bit 1 ... etc 0 = not in detect, 1 = in detect.
Referenced by Touch_measurement().
| sensor_t sensors[QT_NUM_CHANNELS] |
| uint8_t tag_sensor_t::state |
| uint8_t tag_sensor_t::threshold |
| uint8_t tag_sensor_t::to_channel |
| uint8_t tag_sensor_t::type_aks_pos_hyst |
sensor type, AKS group, positive recal flag, and hysteresis value bits 7..6: sensor type: 00: key 01: rotor 10: slider 11: reserved bits 5..3: AKS group (0..7): 0 = no AKS group bit 2 : positive recal flag bits 1..0: hysteresis
1.8.5