System Setup (mTouch_config.h) | |
These configuration options must be uniquely set for each application. They define the manner in which the framework will be implemented in the application. | |
| #define | _XTAL_FREQ |
| The oscillator frequency of your system in Hz. | |
| #define | MTOUCH_INTEGRATION_TYPE |
| Defines the manner in which the framework will integrate with the application. | |
| #define | MTOUCH_ISR_TIMER |
| If the mTouch scanning routine is called from the ISR, this defines which timer's interrupt flag is used. | |
| #define | MTOUCH_SCAN_FUNCTIONALITY |
| Determines how many sensors are scanned in a single 'scan' function call. | |
| #define | MTOUCH_ADC_CONTROL |
| Determines whether or not the framework controls the ADC at all times. | |
Sensor Setup (mTouch_config.h) | |
These configuration options initialize the sensors in the framework by defining which analog pins are to be scanned and how much sensitivity is expected from them (thresholds). | |
| #define | MTOUCH_NUMBER_SENSORS |
| Number of active-mode mTouch sensor inputs to scan. | |
| #define | MTOUCH_SENSOR0 |
| Analog port assignment for the active-mode sensor with index 0. | |
| #define | THRESHOLD_PRESS_SENSOR0 |
| Defines the press threshold of the active-mode sensor with index 0. | |
| #define | MTOUCH_RELEASE_THRESH_FACTOR |
| Defines the hysteresis relationship between the press and release thresholds. | |
UART-PC Communications Setup (mComm_config.h) | |
These configuration options define if and how the mTouch framework is to communicate with a PC.
| |
| #define | MCOMM_TYPE |
| Defines one of four available communication options: MCOMM_UART_ONE_WAY, MCOMM_UART_TWO_WAY, MCOMM_I2C_TWO_WAY, and MCOMM_SPI_TWO_WAY. | |
| #define | MCOMM_UART_BAUDRATE |
| If UART is being used, this defines the communication baud rate. | |
Filtering Setup (mTouch_config.h) | |
These configuration options define if and how the mTouch framework is to communicate with a PC. | |
| #define | MTOUCH_SAMPLES_PER_SCAN |
| Determines the degree of oversampling and the sample rate of your system. | |
| #define | MTOUCH_BASELINE_WEIGHT |
| Determines the weight given to the raw value when updating the baseline. | |
| #define | MTOUCH_BASELINE_RATE |
| Sets the update rate of the baseline when unpressed. | |
| #define | MTOUCH_JITTER_BITS |
| Defines the number of bits to use to implement a random delay between mTouch scans. | |
| #define | MTOUCH_DECIMATION_MAX_STEP |
| Maximum allowed change of the framework's latched mTouch result variable from a single mTouch sample. | |
| #define | MTOUCH_SCALING |
| mTouch post-scaler of reading value | |
Decoding Setup (mTouch_config.h) | |
These configuration options will adjust the decoding behavior of the mTouch Framework. Editting these values is optional but allows for a more highly customized final result. | |
| #define | MTOUCH_POWER_UP_SAMPLES |
| Number of times each sensor should be scanned and decoded before exitting the initialization state and entering the released state. | |
| #define | MTOUCH_BUTTON_TIMEOUT |
| Number of mTouch decode function calls where the sensor is consecutively pressed before resetting the sensor to its released state. | |
| #define | MTOUCH_DEBOUNCE_RELEASE |
| Number of consecutive scans a sensor must be decoded as released before changing states. | |
| #define | MTOUCH_DEBOUNCE_PRESS |
| Number of consecutive scans a sensor must be decoded as pressed before changing states. | |
| #define | MTOUCH_MOST_PRESSED_THRESHOLD |
| This configuration option determines how much more pressed the most-pressed sensor must be above all other sensors in order to allow activation. | |
| #define | MTOUCH_MATRIX_ROW_START |
| Defines which MTOUCH_SENSORx sensor is the start-index of the 'row' sensors. | |
| #define | MTOUCH_MATRIX_ROW_END |
| Defines which MTOUCH_SENSORx sensor is the final-index of the 'row' sensors. | |
| #define | MTOUCH_MATRIX_COLUMN_START |
| Defines which MTOUCH_SENSORx sensor is the start-index of the 'column' sensors. | |
| #define | MTOUCH_MATRIX_COLUMN_END |
| Defines which MTOUCH_SENSORx sensor is the final-index of the 'column' sensors. | |
Slider and Wheel Setup (mTouch_config_slider.h) | |
These options will configure if there are any sliders and wheels in your application as well as how they are decoded. The framework is able to support up to 10 sliders and 8 sensors per slider. (The framework does not support 80 unique sensors - if an application actually used all 10 sliders with 8 sensors per slider, it would need to re-use some active-mode sensors multiple times.) | |
| #define | MTOUCH_NUMBER_OF_SLIDERS |
| Defines the number of sliders to be implemented. | |
| #define | MTOUCH_NUMBER_SLIDER0_SENSORS |
| Required for each slider. Defines the number of sensors that make up slider 0. | |
| #define | MTOUCH_SLIDER0_SENSOR0 |
| Required for each sensor of each slider. Defines the active-mode sensor index of Slider 0's first sensor. | |
| #define | MTOUCH_SLIDER_STEP_SIZE |
| Defines the maximum value that the latched slider output value is allowed to change based on one new reading. Similar to MTOUCH_DECIMATION_MAX_STEP. | |
| #define | MTOUCH_SLIDER_SCALING_ENABLED |
| If defined, slider output values will always fall between 0 and 255, regardless of the number of sensors. If not, the maximum value will be based on the number of sensors in the slider. | |
Proximity Sensor Configuration | |
These options define which sensors are proximity sensors and how the framework is to implement the median filter. Read this guide for more information about proximity sensors and configuration. | |
| #define | MTOUCH_NUMBER_PROXIMITY |
| Defines how many proximity sensors are activated. | |
| #define | MTOUCH_PROX_BUFFER_SIZE |
| Determines the size of the buffer used in the proximity median filter. | |
| #define | MTOUCH_PROX_REMOVE_EXTREME |
| The median filter's N largest and N smallest values are not included in the filter's output value. Must be less than half the buffer size. | |
| #define | MTOUCH_PROX_USE_32BIT_ACCUM |
| If defined, the accumulator used during the decoding process of the proximity sensor will be implemented as a 32-bit value. | |
Advanced CVD Scan Controls (mTouch_config_cvdAdvanced.h) | |
These controls provide additional, more advanced options for adjusting the behavior of the CVD scan. Incorrect configuration of these options can result in very strange, erratic behavior. | |
| #define | CVD_SETTLING_DELAY |
| Determines the amount of time provided for the external sensor and internal hold capacitor to balance their voltages during the CVD scanning process. | |
| #define | CVD_CHOLD_CHARGE_DELAY |
| Determines the amount of time provided for charging the internal hold capacitor of the ADC during the CVD scanning process. | |
| #define | CVD_SWITCH_DELAY |
| Determines the amount of added NOPs between when the sensor is set to an input and the ADC mux is pointed to the sensor. | |
| #define | CVD_GUARD_PORT |
| If CVD_GUARD_IO_ENABLED is defined, this determines which port to use for the guard. | |
| #define | CVD_GUARD_PIN |
| If CVD_GUARD_IO_ENABLED is defined, this determines which pin to use for the guard. | |
| #define | CVD_GUARD_DACCON0_A |
| If CVD_GUARD_DACOUT_ENABLED is defined, this determines what value is loaded into the DACCON0 register prior to the first ADC sample of the differential CVD scan. | |
| #define | CVD_GUARD_DACCON1_A |
| If CVD_GUARD_DACOUT_ENABLED is defined, this determines what value is loaded into the DACCON1 register prior to the first ADC sample of the differential CVD scan. | |
| #define | CVD_GUARD_DACCON0_B |
| If CVD_GUARD_DACOUT_ENABLED is defined, this determines what value is loaded into the DACCON0 register prior to the second ADC sample of the differential CVD scan. | |
| #define | CVD_GUARD_DACCON1_B |
| If CVD_GUARD_DACOUT_ENABLED is defined, this determines what value is loaded into the DACCON1 register prior to the second ADC sample of the differential CVD scan. | |
| #define | CVD_MUTUAL_LAT |
| If CVD_MUTUAL_ENABLED is defined, determines what LAT register is used for the mutual sensor. | |
| #define | CVD_MUTUAL_TRIS |
| If CVD_MUTUAL_ENABLED is defined, determines which pin is used for the mutual sensor. | |
The mTouch Configuration Options provide an easy way to manipulate the behavior of the framework while staying focused on the end application. Detailed explanations of each option are provided below.
| #define _XTAL_FREQ |
The oscillator frequency of your system in Hz.
| #define CVD_CHOLD_CHARGE_DELAY |
Determines the amount of time provided for charging the internal hold capacitor of the ADC during the CVD scanning process.
If this value is too small: There will be noticable crosstalk between closely-indexed sensors that is not related to the hardware layout of the application.
If this value is too large: The mTouch ISR will take an unnecessarily long amount of time to execute.
To correctly set this value:
Your MLA Directory/mTouchCapDemos/Utilities/PIC12F PIC16F Utilities/mTouch One-Way GUI | #define CVD_GUARD_DACCON0_A |
If CVD_GUARD_DACOUT_ENABLED is defined, this determines what value is loaded into the DACCON0 register prior to the first ADC sample of the differential CVD scan.
| #define CVD_GUARD_DACCON0_B |
If CVD_GUARD_DACOUT_ENABLED is defined, this determines what value is loaded into the DACCON0 register prior to the second ADC sample of the differential CVD scan.
| #define CVD_GUARD_DACCON1_A |
If CVD_GUARD_DACOUT_ENABLED is defined, this determines what value is loaded into the DACCON1 register prior to the first ADC sample of the differential CVD scan.
| #define CVD_GUARD_DACCON1_B |
If CVD_GUARD_DACOUT_ENABLED is defined, this determines what value is loaded into the DACCON1 register prior to the second ADC sample of the differential CVD scan.
| #define CVD_GUARD_PIN |
If CVD_GUARD_IO_ENABLED is defined, this determines which pin to use for the guard.
| #define CVD_GUARD_PORT |
If CVD_GUARD_IO_ENABLED is defined, this determines which port to use for the guard.
| #define CVD_MUTUAL_LAT |
If CVD_MUTUAL_ENABLED is defined, determines what LAT register is used for the mutual sensor.
| #define CVD_MUTUAL_TRIS |
If CVD_MUTUAL_ENABLED is defined, determines which pin is used for the mutual sensor.
| #define CVD_SETTLING_DELAY |
Determines the amount of time provided for the external sensor and internal hold capacitor to balance their voltages during the CVD scanning process.
If this value is too small: The sensors will not be as sensitive as they could be and your sensor's readings will be VDD dependant.
If this value is too large: The noise immunity of the system will not be as robust as it could be.
To correctly set this value:
Your MLA Directory/mTouchCapDemos/Utilities/PIC12F PIC16F Utilities/mTouch One-Way GUI Once this has occurred, the settling time has been correctly tuned to provide the maximum amount of sensitivity while minimizing the framework's susceptibility to noise.
| #define CVD_SWITCH_DELAY |
Determines the amount of added NOPs between when the sensor is set to an input and the ADC mux is pointed to the sensor.
This option was created due to a rare behavior that can appear in some devices.
The ideal value of this option for noise immunity is 0. This will minimize the amount of time the sensor is set as an input.
CVD_SWITCH_DELAY should only be increased if the output driver is not disabling itself quickly enough, causing the sensor's output driver to affect the internal ADC's hold voltage as soon as the mux is connected. The effect will be noticeable on the second sample of the waveform: the settling point will be slightly unstable and will be visibly coupling to VDD.
The behavior is most-noticeable on the second scan due to P-type transistors being less ideal than N-type transistors. The behavior is most-common when Fosc is a high value (16MHz or greater).
If you are seeing the behavior, the correct value for this option will vary based on Fosc and the microcontroller in question; but, in general, 1-3 NOPs for 16MHz, 3-5 for 32MHz.
| #define MCOMM_TYPE |
Defines one of four available communication options: MCOMM_UART_ONE_WAY, MCOMM_UART_TWO_WAY, MCOMM_I2C_TWO_WAY, and MCOMM_SPI_TWO_WAY.
| #define MCOMM_UART_BAUDRATE |
If UART is being used, this defines the communication baud rate.
Valid UART baudrate options depend on whether the UART communications will be implemented in hardware or software.
Choose one of the listed speeds and compile. If the mComm module is unable to support the requested speed given your current Fosc value, error messages will guide you to choosing a better alternative.
(bps)
* Bolded options are compatible with the software-implementation of the UART in most Fosc configurations.
| #define MTOUCH_ADC_CONTROL |
Determines whether or not the framework controls the ADC at all times.
Valid options:
| #define MTOUCH_BASELINE_RATE |
Sets the update rate of the baseline when unpressed.
This value is used to seed a counter variable that will cause the baseline to be updated only once every Nth new reading value, where N is MTOUCH_BASELINE_RATE.
Example:
If MTOUCH_BASELINE_RATE is 2, the baseline will use every other new reading to update itself.
Allowed Values :: 1 - 65535
| #define MTOUCH_BASELINE_WEIGHT |
Determines the weight given to the raw value when updating the baseline.
When the average updates itself using a new reading, this value determines what weight is given to the reading variable in the calculation of the new baseline.
The reading variable will have a weight of 1/MTOUCH_BASELINE_WEIGHT in the baseline calculation.
Example:
If MTOUCH_BASELINE_WEIGHT is 4, the baseline calculation would be:
baseline = (1/4)*reading + (3/4)*baseline
Allowed Values :: 1 - 4
| #define MTOUCH_BUTTON_TIMEOUT |
Number of mTouch decode function calls where the sensor is consecutively pressed before resetting the sensor to its released state.
This feature will reset the sensor's state if it remains in the 'pressed' state for too long.
For example:
Let's assume the dataReady flag is set once every 100ms due to the MTOUCH_SAMPLES_PER_SCAN option. If we want a timeout of 10sec, the MTOUCH_BUTTON_TIMEOUT value should be set to 100. If we want a timeout of 7.4 seconds, then BUTTON_TIMEOUT should be set to 74.
Timeout Duration = dataReady Toggle Rate * BUTTON_TIMEOUT
Setting to '0' or commenting the define will disable the timeout feature.
Allowable Range :: [ 0, 2 - 255 ]
| #define MTOUCH_DEBOUNCE_PRESS |
Number of consecutive scans a sensor must be decoded as pressed before changing states.
Increasing this value will significantly slow response time, so make sure the scan rate is fast enough to continue to provide the desired response rate.
| #define MTOUCH_DEBOUNCE_RELEASE |
Number of consecutive scans a sensor must be decoded as released before changing states.
Increasing this value will significantly slow response time, so make sure the scan rate is fast enough to continue to provide the desired response rate.
| #define MTOUCH_DECIMATION_MAX_STEP |
Maximum allowed change of the framework's latched mTouch result variable from a single mTouch sample.
To achieve maximum noise immunity, this value should be set to '1'. If the reading is having trouble keeping up with the level of sensitivity in your application, however, this value can be used to increase the maximum speed of the sensor's reading.
| #define MTOUCH_INTEGRATION_TYPE |
Defines the manner in which the framework will integrate with the application.
Valid options:
| #define MTOUCH_ISR_TIMER |
If the mTouch scanning routine is called from the ISR, this defines which timer's interrupt flag is used.
8-bit Timers Only. Not compatible with TMR1/3/5.
| #define MTOUCH_JITTER_BITS |
Defines the number of bits to use to implement a random delay between mTouch scans.
A random value is loaded into the interrupt timer to vary the interrupt's rate. The maximum number of bits of the random value is determined by this option. It is set to a value of '6' by default. More bits = more randomness.
Allowed Values :: 0 - 8
| #define MTOUCH_MATRIX_COLUMN_END |
Defines which MTOUCH_SENSORx sensor is the final-index of the 'column' sensors.
| #define MTOUCH_MATRIX_COLUMN_START |
Defines which MTOUCH_SENSORx sensor is the start-index of the 'column' sensors.
| #define MTOUCH_MATRIX_ROW_END |
Defines which MTOUCH_SENSORx sensor is the final-index of the 'row' sensors.
| #define MTOUCH_MATRIX_ROW_START |
Defines which MTOUCH_SENSORx sensor is the start-index of the 'row' sensors.
| #define MTOUCH_MOST_PRESSED_THRESHOLD |
This configuration option determines how much more pressed the most-pressed sensor must be above all other sensors in order to allow activation.
If the value is '10', the most pressed sensor's shift value must be at least 10 counts higher than the second-most-pressed sensor's shift.
For example, if Sensor0's shift is 400 counts, all other sensor's shifts must be 390 or lower to activate this sensor.
| #define MTOUCH_NUMBER_OF_SLIDERS |
Defines the number of sliders to be implemented.
Any non-zero value will enable this module.
| #define MTOUCH_NUMBER_PROXIMITY |
Defines how many proximity sensors are activated.
There must be one MTOUCH_SENSORx_IS_PROX definition per enabled proximity sensor. The value of the definition must be it's "proximity-id" value.
"Proximity-ID" is used as an index to the proximity variables. In total, the IDs should start at 0 and end with MTOUCH_NUMBER_PROXIMITY-1.
The order is arbitrary.
#define MTOUCH_NUMBER_PROXIMITY 2 #define MTOUCH_SENSOR5_IS_PROX 0 // MTOUCH_SENSOR5 is a proximity sensor with index 0 #define MTOUCH_SENSOR2_IS_PROX 1 // MTOUCH_SENSOR2 is a proximity sensor with index 1
| #define MTOUCH_NUMBER_SENSORS |
Number of active-mode mTouch sensor inputs to scan.
| #define MTOUCH_NUMBER_SLIDER0_SENSORS |
Required for each slider. Defines the number of sensors that make up slider 0.
| #define MTOUCH_POWER_UP_SAMPLES |
Number of times each sensor should be scanned and decoded before exitting the initialization state and entering the released state.
Allowable Range: 1-65535
| #define MTOUCH_PROX_BUFFER_SIZE |
Determines the size of the buffer used in the proximity median filter.
This number determines the history length of the median filter. Each value is an integer, so '5' requires 10-bytes per proximity sensor.
Options -
| #define MTOUCH_PROX_REMOVE_EXTREME |
The median filter's N largest and N smallest values are not included in the filter's output value. Must be less than half the buffer size.
| #define MTOUCH_PROX_USE_32BIT_ACCUM |
If defined, the accumulator used during the decoding process of the proximity sensor will be implemented as a 32-bit value.
This solves overflow problems - at the cost of additional temporary RAM requirements.
| #define MTOUCH_RELEASE_THRESH_FACTOR |
Defines the hysteresis relationship between the press and release thresholds.
This value will be multiplied by each of the THRESHOLD_PRESS_SENSOR# values to calculate individual release thresholds for each sensor.
If your system is not releasing quickly enough, make this number slightly larger to raise the threshold. If your system is releasing too quickly, make this number slightly smaller.
For example:
RELEASE_THRESHOLD_FACTOR is 0.5
THRESHOLD_PRESS_SENSOR0 is 100.
THRESHOLD_PRESS_SENSOR1 is 150.
THRESHOLD_RELEASE_SENSOR0 = THRESHOLD_PRESS_SENSOR0 * RELEASE_THRESHOLD_FACTOR
This means the reading on the active-mode sensor with index '0' will need to shift up, during a press, more than 100 counts above the baseline in order to trigger a press. Once there, the baseline will stop updating and the sensor will remain in the pressed state until the reading returns to within 50 counts of the baseline or until the press timeout counter has completed. Likewise, the active-mode sensor with index '1' will need to shift up by 150 and then down to below 75 in order to enter and exit the pressed state.
| #define MTOUCH_SAMPLES_PER_SCAN |
Determines the degree of oversampling and the sample rate of your system.
This is the number of times each sensor will be scanned before asserting the mTouch_state.dataReady bit. If the application requires a specific response time, there are several variables that will be important to the calculation of this parameter.
| #define MTOUCH_SCALING |
mTouch post-scaler of reading value
This option will determine the amount of post-scaling that is implemented on the acquisition's accumulator register before being stored in the results register. The scaling factor should be set so that it is not possible for the result register to overflow (Max output value is 65535.)
Set this option to the number of times the framework should right shift the accumulator value to achieve the reading. When in doubt, '4' is usually a good option.
| #define MTOUCH_SCAN_FUNCTIONALITY |
Determines how many sensors are scanned in a single 'scan' function call.
Valid options:
| #define MTOUCH_SENSOR0 |
Analog port assignment for the active-mode sensor with index 0.
| #define MTOUCH_SLIDER0_SENSOR0 |
Required for each sensor of each slider. Defines the active-mode sensor index of Slider 0's first sensor.
| #define MTOUCH_SLIDER_SCALING_ENABLED |
If defined, slider output values will always fall between 0 and 255, regardless of the number of sensors. If not, the maximum value will be based on the number of sensors in the slider.
| #define MTOUCH_SLIDER_STEP_SIZE |
Defines the maximum value that the latched slider output value is allowed to change based on one new reading. Similar to MTOUCH_DECIMATION_MAX_STEP.
| #define THRESHOLD_PRESS_SENSOR0 |
Defines the press threshold of the active-mode sensor with index 0.
This is how far the reading must deviate from the average/baseline before it exits the MTOUCH_RELEASED state and enters the MTOUCH_PRESSED state. The default values are only placeholders and should be edited to fit your design.
The release threshold is automatically calculated off this value and the value of MTOUCH_RELEASE_THRESH_FACTOR. This allows the user to focus on where to place a single threshold and the other value will follow it automatically.