mTouch Configuration Options

Required, Basic Configuration Options

These configuration options must be uniquely set for each application.


#define _XTAL_FREQ
 The Fosc frequency of your system in Hz.
#define TMR0_PRESCALER
 The TMR0 prescaler value of your system.
#define CVD_NUMBER_SENSORS
 Number of CVD Sensor Inputs.
#define CVD_SENSOR0
 Analog port assignment for Sensor 0.
#define CVD_SAMPLES_PER_SCAN
 Determines the degree of oversampling and the sample rate of your system.
#define CVD_DEBUG_SPEED
 Determines the output transfer speed of the communications module. Valid options: 9600 (preferred) or 115200.
#define CVD_Software_Revision
 Used to determine what communication protocol to use when sending data to the mTouch GUI. Leave set to 0002.

Adjusting the Framework's Behavior

These configuration options will adjust the acquisition and decoding behavior of the mTouch Framework. Editting these values is optional.


#define THRESHOLD_PRESS_SENSOR0
 Determines the press threshold of sensor 0.
#define CVD_SCALING
 mTouch CVD post-scaler of reading value
#define POWER_UP_SAMPLES
 Number of total scans that should be taken across all sensors before they will be considered initialized.
#define BUTTON_TIMEOUT
 Number of press decisions before resetting sensor to released state.
#define AVG_UPDATE
 Determines the weight given to the raw value when updating the average.
#define AVG_RATE
 Sets the update rate of the average when unpressed.
#define RELEASE_THRESHOLD_FACTOR
 Defines the hysteresis relationship between the press and release thresholds.
#define CVD_JITTER_TYPE
 Selects between two acquisition jittering implementations.
#define DEBOUNCE_COUNT_RELEASE
 Number of consecutive scans a sensor must be decoded as released before changing states.
#define DEBOUNCE_COUNT_PRESS
 Number of consecutive scans a sensor must be decoded as pressed before changing states.
#define NEGATIVE_CAPACITANCE
 Determines the method used to handle a negative capacitance shift on the readings.
#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_DEBUG_OUTPUT_RAW
 When defined, the communications module will output raw data in its information packet.

Advanced Options - Not recommended except for debugging

These configuration options will adjust a fundamental section of the framework to perform differently. Care should be taken by anyone using these options as they will have a significant effect on the operation and noise performance of the system.


#define AVG_ENABLE
 Enables/Disables implementation of a baseline average. Turning this off is highly discouraged.
#define CVD_JITTER_ENABLE
 Enables/Disables implementation of the TMR0 jittering feature. Turning this off is highly discouraged due to noise immunity concerns.

Unimplemented

These options are still under development and are not yet implemented.


#define CVD_DEBUG_PIN
 Not currently implemented.
#define CVD_Frame_Revision
 Not currently implemented.
#define CVD_Board_Revision
 Not currently implemented.

Detailed Description

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 Documentation

#define _XTAL_FREQ

The Fosc frequency of your system in Hz.

Definition at line 69 of file mTouchCVD_Config.h.

#define AVG_ENABLE

Enables/Disables implementation of a baseline average. Turning this off is highly discouraged.

Turning this off is highly discouraged unless further editting of the decode logic is going to be performed.

Definition at line 296 of file mTouchCVD_Config.h.

#define AVG_RATE

Sets the update rate of the average when unpressed.

This value is used to seed a counter variable that will cause the average to be updated only once every Nth new reading value, where N is AVG_RATE.

Example:

If AVG_RATE is 2, the average will use every other new reading to update itself.

Definition at line 316 of file mTouchCVD_Config.h.

#define AVG_UPDATE

Determines the weight given to the raw value when updating the average.

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 average.

The reading variable will have a weight of 1/AVG_UPDATE in the average calculation.

Example:

If AVG_UPDATE is 4, the average calculation would be:

 average = (1/4)*reading + (3/4)*average

Allowed Values :: 1, 2, 4, 8, 16

Definition at line 303 of file mTouchCVD_Config.h.

#define BUTTON_TIMEOUT

Number of press decisions before resetting sensor to released state.

This feature will reset the sensor's state if it remains in the 'pressed' state for too long. This number is based off the amount of time between dataReady flag toggles.

For example:

Let's assume the dataReady flag is set once every 100ms due to the CVD_SAMPLES_PER_SCAN option. If we want a timeout of 10sec, the 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 ]

Definition at line 274 of file mTouchCVD_Config.h.

#define CVD_Board_Revision

Not currently implemented.

Definition at line 238 of file mTouchCVD_Config.h.

#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:

  1. Set this value to 0, compile and program.
  2. Look at the raw values on the mTouch GUI or through a terminal program.
  3. Press as hard as you can on the sensor with the highest amount of capacitance. (This usually corresponds to the sensor with the highest unpressed raw value.)
    • Do you notice a strange crosstalk behavior on a different sensor? If no, leave this value to 0. If yes...
  4. Increase the delay until the crosstalk behavior is eliminated.

Definition at line 452 of file mTouchCVD_Config.h.

#define CVD_DEBUG_OUTPUT_RAW

When defined, the communications module will output raw data in its information packet.

If only raw values are output, the packet will be:

 SensorStateMask;RawSensor0;RawSensor1;RawSensor2;...;RawSensorN (CR) (LF)

If raw and average values are output, the packet will be:

 SensorStateMask;RawSensor0;AvgSensor0;RawSensor1;AvgSensor1;...;RawSensorN;AvgSensorN (CR) (LF)

See also - CVD_DEBUG_OUTPUT_AVG

Definition at line 225 of file mTouchCVD_Config.h.

#define CVD_DEBUG_PIN

Not currently implemented.

Definition at line 221 of file mTouchCVD_Config.h.

#define CVD_DEBUG_SPEED

Determines the output transfer speed of the communications module. Valid options: 9600 (preferred) or 115200.

Definition at line 220 of file mTouchCVD_Config.h.

#define CVD_Frame_Revision

Not currently implemented.

Definition at line 236 of file mTouchCVD_Config.h.

#define CVD_JITTER_ENABLE

Enables/Disables implementation of the TMR0 jittering feature. Turning this off is highly discouraged due to noise immunity concerns.

The only time you may want to comment this out is if you are looking at the sensor's waveform on a scope. In that case, turning this off will allow you to see a clear waveform.

Definition at line 340 of file mTouchCVD_Config.h.

#define CVD_JITTER_TYPE

Selects between two acquisition jittering implementations.

This option will choose between two 'random' seeds for a random number generator that is used to implement the jittering functionality in the acquisition process.

Options:

  • 0 - The least significant bits of the ADRESL register are used. This is the smallest and fastest jittering option but may not provide the same amount of randomness that the other option can provide.
  • 1 - For a slightly higher processing and memory cost, this jittering routine implements a linear feedback shift register to maximize the randomness. Requires one byte of memory and 5 additional instruction cycles to execute.

Definition at line 349 of file mTouchCVD_Config.h.

#define CVD_NUMBER_SENSORS

Number of CVD Sensor Inputs.

Definition at line 73 of file mTouchCVD_Config.h.

#define CVD_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 mTouchCVD_dataReady() bit. If the application requires a specific response time, there are several variables that will be important to the calculation of this parameter.

  • _XTAL_FREQ is the PICs oscillation frequency and will determine how quickly the TMR0 counter will increment.
  • TMR0_PRESCALER also determines how quickly the TMR0 counter will increment. This value, located in the OPTION register, is not set by the framework.
  • CVD_NUMBER_SENSORS defines how many times the ISR will interrupt between each decrement of the sample counter. The sample counter is initialized with CVD_SAMPLES_PER_SCAN as its value.

Definition at line 123 of file mTouchCVD_Config.h.

#define CVD_SCALING

mTouch CVD 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.)

When in doubt, 16 is usually the best option.

Options:

  • 1 - No scaling is performed. 1:1 relationship between accumulator and result.
  • 16 - 16:1 relationship between accumulator and result.
  • 256 - 256:1 relationship between accumulator and result.

Definition at line 186 of file mTouchCVD_Config.h.

#define CVD_SENSOR0

Analog port assignment for Sensor 0.

Definition at line 75 of file mTouchCVD_Config.h.

#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:

  1. Set this value to 0, compile and program.
  2. Look at the raw values on the mTouch GUI or through a terminal program while powering the system at the desired VDD level.
  3. Adjust VDD by plus and minus 0.5V
    • Do you notice any change in the unpressed value as VDD is changing? If no, leave this value alone. If yes...
  4. Increase the delay until the sensor's reading no longer changes as VDD changes.

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.

Definition at line 427 of file mTouchCVD_Config.h.

#define CVD_Software_Revision

Used to determine what communication protocol to use when sending data to the mTouch GUI. Leave set to 0002.

May also be used to develop your own output data stream and allow for easy toggling between types using this field.

Definition at line 240 of file mTouchCVD_Config.h.

#define DEBOUNCE_COUNT_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.

Definition at line 377 of file mTouchCVD_Config.h.

#define DEBOUNCE_COUNT_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.

Definition at line 370 of file mTouchCVD_Config.h.

#define NEGATIVE_CAPACITANCE

Determines the method used to handle a negative capacitance shift on the readings.

This option determines the method used to handle a negative capacitance shift. In other words, how the system will respond to a reading value shift in the opposite direction of a normal shift caused by a finger.

These shifts occur for a variety of reasons and you may want to adjust this behavior based on your system.

Options:

  • 0 - Normal Average Behavior
    (DEFAULT) No special behavior. The average will update at the normal rate, as always. For Metal-over-Capacitive systems, a negative shift usually means a neighboring sensor is being pressed, so this is the best option to keep the current state of the sensor and allow it to be pressed quickly after a neighbor has been pressed.
  • 1 - Increase Average Speed
    The average will ignore the AVG_RATE counter and update itself after each new reading value. This has the effect of speeding up the average until it catches up with the negative shift.
  • 2 - Average Directly Follows Reading
    The average will instantly follow a negative shift. This behavior is best for a system that needs a very fast response time. It will help prevent quick, repeated presses from being missed due to the average not updating quickly enough.

Definition at line 383 of file mTouchCVD_Config.h.

#define POWER_UP_SAMPLES

Number of total scans that should be taken across all sensors before they will be considered initialized.

For example:

Let's assume the dataReady flag is set once every 100ms due to the CVD_SAMPLES_PER_SCAN option and there are 8 sensors in our system. If we want a 3 second initialization time, we set POWER_UP_SAMPLES to 240.

Allowable Range: 1-65535

 Initialization Duration = (dataReady Toggle Rate / CVD_NUMBER_SENSORS) * POWER_UP_SAMPLES

Definition at line 257 of file mTouchCVD_Config.h.

#define RELEASE_THRESHOLD_FACTOR

Defines the hysteresis relationship between the press and release thresholds.

RELEASE_THRESHOLD_FACTOR 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 index 0 will need to shift up, during a press, more than 100 counts above the average in order to trigger a press. Once there, the average will stop updating and the sensor will remain in the pressed state until the reading returns to within 50 counts of the average or until the press timeout counter has completed. Likewise, index 1 will need to shift up by 150 and then down to below 75 in order to enter and exit the pressed state.

Definition at line 325 of file mTouchCVD_Config.h.

#define THRESHOLD_PRESS_SENSOR0

Determines the press threshold of sensor 0.

This is how far the reading must deviate from the average/baseline before it exits the CVD_RELEASED state and enters the CVD_PRESSED state. The default values are only placeholders and should be edited to fit a design.

The release threshold is automatically calculated off this value and RELEASE_THRESHOLD_FACTOR. This allows this user to focus on where to place a single threshold and the other value will follow it automatically.

Attention:
To determine this value, it is highly recommended to look at the communications output and see how your sensors are behaving. This is the only way to safely choose a threshold on any new design.

Definition at line 157 of file mTouchCVD_Config.h.

#define TMR0_PRESCALER

The TMR0 prescaler value of your system.

Definition at line 70 of file mTouchCVD_Config.h.