mTouch® Capacitive Sensing Library Module API

The mTouch® Capacitive Sensing library is customized and generated by the MPLAB® X Code Configurator’s (MCC) Graphical User Interface (GUI). The generated library is responsible for signal acquisition, noise handling, button, proximity sensor, and slider/wheel decoding. Your application code can use the APIs provided by the mTouch library to access sensor, button proximity sensor, and slider/wheel.

Sensor Module

This module contains mtouch_sensor.c and mtouch_senor.h files, which provides access to the hardware sensor.

Public Types

enum mtouch_sensor_names {Sensor_ANxx,…}

This enum describes the sensor name which you specify in the MCC mTouch Configurator. The value always starts from 0.

enum mtouch_sensor_error {MTOUCH_SENSOR_ERROR_none,…}

This enum describes the error happening during the sensor acquisition. Please note that the error information will not be propagated to the application level, and can only be used inside the sensor acquisition stage, so you need to use debug mode and stop the execution at the end of Sensor_Service() function to observe the error message if needed.

Constant Value Description
MTOUCH_SENSOR_ERROR_none 0 No error.
MTOUCH_SENSOR_ERROR_invalid_index -1 The index of of sensor is invalid.
MTOUCH_SENSOR_ERROR_interrupt_notEnabled -2 The globle interrupt is not enabled, this error only happens on software Capacitive Voltage Divider (CVD) implementation.
MTOUCH_SENSOR_ERROR_invalid_calibrate -3 The analog calibration is out of range.
MTOUCH_SENSOR_ERROR_tooManyRetries -4 The packet of sensor scan will be retried if the scan is interrupted by other tasks. This only happens on software CVD and dual Analog-to-Digital Converter (ADC) with Hardware Capacitive Voltage Divider (HCVD) implementation.
MTOUCH_SENSOR_ERROR_scanOverrun -5 The error happens when a new scan starts before storing the previous result from ADC due to interruption of other tasks. This only happens on dual ADC with HCVD implementation.
MTOUCH_SENSOR_ERROR_interruptedScan -6 The error happens when the application layer nofities that there is an interrupt ocurring during the scan by calling MTOUCH_Sensor_NotifyInterruptOccurred() function . This only happens on dual ADC with HCVD implementation.

Properties

MTOUCH_SENSORS

Holds the number of sensors in this project.

MTOUCH_SCAN_GROUPS

Holds the number of scan groups in this project. This only exists in dual ADC with HCVD implementation, as it groups two sensors from the two ADCs to scan simultaneously.

Public Functions

enum mtouch_sensor_error MTOUCH_Sensor_Initialize(enum mtouch_sensor_names sensor)

Initializes the assigned hardware sensor pin. Normally, you don't need to re-initialize the sensor pin at run-time.

void MTOUCH_Sensor_InitializeAll(void)

Initializes all the hardware sensor pins. This only needs to be called once after the device reset.

void MTOUCH_Sensor_Scan_Initialize(void)

Initializes the ADC, peripheral pin select (PPS), and timer module if needed for sensor scan. If the ADC has been used for other tasks, it is recommended to call this function to restore the ADC configuration for an mTouch library scan.

Example

void MTOUCH_Sensor_ADCC_Initialize(void)

Initializes the Analog-to-Digital Converter with Computation (ADCC) module for sensor scan, this is only available for devices that have ADCC module. The usage is similar with MTOUCH_Sensor_Scan_Initialize() function.

void MTOUCH_Sensor_SetSampledCallback(void (*callback)(enum mtouch_sensor_names sensor))

Sets the callback function of sampling completion. The parameter of this callback function is the name(index) of the sensor, which just finishes its sampling.

Example

bool MTOUCH_Sensor_SampleAll(void)

This function behaves differently for different acquisition implementation.

For software CVD and dual ADC with HCVD implementation, this is a blocking function, which scans all the enabled sensors. If there is an error happening during the scan, the function returns false, otherwise, it returns true after the completion of the sensor scan.

For ADCC with HCVD implementation, this is a none-blocking function, which initiates the sensor scan if the ADCC is not scanning. Then, it only checks the sampled flag of each sensor, because the sensor scan is autonomous using ADCC. If all the sensors' sampled flag is set, then it returns true, otherwise, it returns false.

bool MTOUCH_Sensor_isSampling(void)

Checks if the ADCC is scanning the sensors, which is only available for ADCC devices. When you want to use ADCC for other tasks, like temperature measurement, voltage measurement, you should check the status of the ADCC using this function. When this function returns true, it means the ADCC is scanning the sensor, otherwise, it is not.

Example

bool MTOUCH_Sensor_isActive(enum mtouch_sensor_names sensor)

Checks if the sensor has a larger variation from sample to sample. If the sample to sample variation is over the active threshold, then the sensor is active and the function returns true, otherwise, it returns false. The active threshold is set in the mtouch_sensor.c file, using the macro Sensor_calculate_active_thrs(oversampling).

This can be used to speed up the response time for low power setup. In the example below, the SLEEP() is inserted between the sensor scans to put the MCU in power down mode to lower the average power consumption, the MCU wakes up with a fixed time interval using a timer based on LFINTOSC. When the sensor is active due to a touch, the system should skip the SLEEP() to speed up touch scan and processing rate. The example also uses MTOUCH_Button_isInitialized() to check if the button is initialized or not. More information of this button API can be found in the button API section.

Example

bool MTOUCH_Sensor_wasSampled(enum mtouch_sensor_names sensor)

Checks if the sensor has been scanned and has new data for processing. The sampled status can only be cleared by calling MTOUCH_Sensor_Sampled_ResetAll().

bool MTOUCH_Sensor_isCalibrated(enum mtouch_sensor_names sensor)

Checks if the sensor has been analog calibrated. This only applies for HCVD devices when analog calibration is enabled.

bool MTOUCH_Sensor_isEnabled(enum mtouch_sensor_names sensor)

Checks if the sensor is enabled or not. If the sensor is not enabled, then it won't be scanned until it is re-enabled.

void MTOUCH_Sensor_Sampled_ResetAll(void)

Resets the sample flag for all sensors so that you can use MTOUCH_Sensor_wasSampled to check if there is new data available later.

In the MTOUCH_Service_Mainloop() of mtouch.c file, the flag is reset after all the post sensor acquisition services.
Example

void MTOUCH_Sensor_Disable (enum mtouch_sensor_names sensor)

Disables the assigned sensor from scanning. This is used by the button and proximity sensor modules for disabling or suspending button or proximity sensor.

void MTOUCH_Sensor_Enable (enum mtouch_sensor_names sensor)

Enables the assigned sensor. If the sensor is already enabled, then calling this function will not cause any change. This is used by the button and proximity modules to resume button or proximity sensor.

void MTOUCH_Sensor_Calibrate (enum mtouch_sensor_names sensor)

Triggers the analog calibration of the assigned sensor. This only applies for HCVD devices when analog calibration is enabled.

mtouch_sensor_sample_t MTOUCH_Sensor_RawSample_Get(enum mtouch_sensor_names sensor)

Returns the oversampled sensor reading from the ADC. This is used by the higher level module, like button and proximity sensor modules. It is also useful if you want to implement their own high-level decoding, such as humidity sensor, liquid level sensor, etc.


Button Module

This module contains mtouch_button.c and mtouch_button.h files, which provides function to access the buttons.

Public Types

enum mtouch_button_names {Buttonxx,…}

This enum describes the button name which you specify in the MCC mTouch Configurator. The value always starts from '0'.

Properties

MTOUCH_BUTTONS

Holds the number of buttons in this project.

Public Functions

void MTOUCH_Button_Initialize(enum mtouch_button_names button)

Initializes the button, setting the button to initialization state and trigger its sensor analog calibration if supported. When this function gets called, the button does not finish initialization immediately, it takes multiple cycles of scans, the number of scans is specified by the MTOUCH_BUTTON_BASELINE_INIT in the mtouch_button.h file. The MTOUCH_Button_isInitialized() can be used to check if the button has been initialized or not.

void MTOUCH_Button_InitializeAll(void)

Initializes all the buttons. This only needs to be called once after the device reset.

void MTOUCH_Button_ServiceAll(void)

Processes the data from the sensors and determines the state of the buttons. This should be called after MTOUCH_Sensor_SampleAll() returns true in the mtouch.c file.

void MTOUCH_Button_Tick(void)

Increments the internal counter for the button timeout.

void MTOUCH_Button_SetPressedCallback(void (*callback)(enum mtouch_button_names button))

Sets the callback function of the button press event. The parameter of this callback function is the name (index) of the pressed button.

void MTOUCH_Button_SetNotPressedCallback(void (*callback)(enum mtouch_button_names button))

Sets the callback function of the button release event. The parameter of this callback function is the name (index) of the released button.

Example

void MTOUCH_Button_Reburst_Request(enum mtouch_button_names button)

Issues a reburst request to the button service. This is used by the higher level service, like slider/wheel service.
This API is only available if the reburst feature is enabled in MCC.

bool MTOUCH_Button_Reburst_Service(void);

Checks if there is any active reburst request, and returns true if a reburst is requested, returns false otherwise.
This API is only available if the reburst feature is enabled in MCC.

bool MTOUCH_Button_isPressed(enum mtouch_button_names button)

Returns true if button is pressed, returns false otherwise.

Example

bool MTOUCH_Button_isInitialized(enum mtouch_button_names button)

Returns true if button is intialized, returnsfalse otherwise.

mtouch_buttonmask_t MTOUCH_Button_Buttonmask_Get(void)

Returns all the button press status in one button mask variable. The length of the mtouch_buttonmask_t is determined by the number of buttons in the project.

For example, an 8 button project will have return value like shown below:

Button Status Mask bits

R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0
Button7 Status Button6 Status Button5 Status Button4 Status Button3 Status Button2 Status Button1 Status Button0 Status
bit 7 bit 0

bit 7-0

ButtonN Status: Button pressed status

1 = The button is pressed.
0 = The button is released.

mtouch_button_deviation_t MTOUCH_Button_Deviation_Get(enum mtouch_button_names button)

Returns the difference between the button reading and the baseline.
The output is a signed 8-bit value, and if the actual value is not in the range of -128 to 127, it is set to -128 or 127 based on the actual value.

mtouch_button_reading_t MTOUCH_Button_Reading_Get(enum mtouch_button_names button)

Returns the button reading value. This is an unsigned 16-bit value.

The button reading is a low pass filtered version of the sensor raw data. The filter strength is determined by the reading filter level in the MCC Button Setting panel.

(1)
\begin{align} Reading = \frac{Reading \times(2^{filterlevel}-1)}{2^{filter level}} + \frac{Sensor Raw Data}{ 2^{filter level}} \end{align}

mtouch_button_reading_t MTOUCH_Button_Baseline_Get(enum mtouch_button_names button)

Returns the button baseline value. This is an unsigned 16-bit value.

The button baseline is a conditional low pass filtered version of the button reading. The filter strength is determined by the baseline gain in the MCC Button Setting panel. The baseline will be updated periodically if the button is not pressed.

mtouch_button_scaling_t MTOUCH_Button_Scaling_Get(enum mtouch_button_names button)

Returns the scaling factor of the button.

More information for scaling can be found at: http://microchipdeveloper.com/touch:button-proximity-sensor-configuration.

mtouch_button_threshold_t MTOUCH_Button_Threshold_Get(enum mtouch_button_names button)

Returns the threshold of the button.

More information for the threshold can be found at: http://microchipdeveloper.com/touch:button-proximity-sensor-configuration.

void MTOUCH_Button_Scaling_Set(enum mtouch_button_names button,mtouch_button_scaling_t scaling)

Sets the scaling factor for the button. The range for scaling factor is from 0 to 8.

void MTOUCH_Button_Threshold_Set(enum mtouch_button_names button,mtouch_button_threshold_t threshold)

Sets the threshold of the button. The range for scaling factor is from 1 to 127.

void MTOUCH_Button_Disable(enum mtouch_button_names button)

Disables the button.

The sensor linked to this button does not get scanned. The button baseline is not updated until the button is resumed.

To use this feature, you need to enable the disable/suspend feature in the MCC Button Setting panel.

void MTOUCH_Button_Suspend(enum mtouch_button_names button)

Suspends the button.

The sensor linked to this button is not scanned for most of the time, but the button baseline is updated at the regular rate(baseline update rate) by scanning the sensor temporarily.

To use this feature, you need to enable the 'disable/suspend' feature in the MCC Button Setting panel.

void MTOUCH_Button_Resume(enum mtouch_button_names button)

Resumes the full functionality of the button.

If the button resumes from the suspended state, then the button will be set to released state.

If the button resumes from the disabled state, then the button will be set to initialization state to re-established the baseline.


Proximity Sensor Module

This module contains mtouch_proximity.c and mtouch_proximity.h files, which provides function to access the proximity sensors.

Public Types

enum mtouch_proximity_names{ ProximityXX,…}

This enum describes the proximity sensor name which you specify in the MCC mTouch Configurator. The value always starts from 0.

Properties

MTOUCH_PROXIMITY

Holds the number of proximity sensors in this project.

Public Functions

void MTOUCH_Proximity_Initialize(enum mtouch_proximity_names prox)

Initializes the proximity sensor, setting the proximity sensor to initialization state and trigger its sensor analog calibration if supported. When this function gets called, the proximity sensor will not finish initialization immediately, it will take multiple cycles of scans, the number of scans is specified by the MTOUCH_PROXIMITY_BASELINE_INIT in the mtouch_proximity.h file. The MTOUCH_Proximity_isInitialized() can be used to check if the proximity sensor is initialized or not.

void MTOUCH_Proximity_InitializeAll(void)

Initializes all the proximity sensors. This only needs to be called once after the device reset.

void MTOUCH_Proximity_ServiceAll(void)

Processes the data from the sensors and determines the state of the proximity sensors. This should be called after MTOUCH_Sensor_SampleAll() returns true in the mtouch.c file.

void MTOUCH_Proximity_Tick(void)

Increments the internal counter for the proximity timeout.

void MTOUCH_Proximity_SetActivatedCallback(void (*callback)(enum mtouch_proximity_names prox))

Sets the callback function of the proximity activated event. The parameter of this callback function is the name (index) of the activated proximity sensor.

void MTOUCH_Proximity_SetNotActivatedCallback(void (*callback)(enum mtouch_proximity_names prox))

Sets the callback function of the proximity release event. The parameter of this callback function is the name(index) of the released proximity sensor.

Example

void MTOUCH_Proximity_Reburst_Request(enum mtouch_proximity_names prox)

Issues a reburst request to the proximity service.
This API is only available if the reburst feature is enabled in the MCC.

bool MTOUCH_Proximity_Reburst_Service(void);

Checks if there is any active reburst request, and will return true if reburst is requested, returns false otherwise.
This API is only available if the reburst feature is enabled in the MCC.

bool MTOUCH_Proximity_isActivated(enum mtouch_proximity_names prox)

Returns true if proximity sensor is activated, returns false otherwise.

bool MTOUCH_Proximity_isInitialized(enum mtouch_proximity_names prox)

Returns true if proximity sensor is intialized, returns false otherwise.

mtouch_proxmask_t MTOUCH_Proximity_Proximitymask_Get(void)

Returns all the proximity sensor activation status in one proximity sensor mask variable. The length of the mtouch_proxmask_t is determined by the number of the proximity sensors in the project.

For example, an eight proximity sensor project will have a return value like shown below:

Proximity Sensor Status Mask bits

R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0
Proximity7 Status Proximity6 Status Proximity5 Status Proximity4 Status Proximity3 Status Proximity2 Status Proximity1 Status Proximity0 Status
bit 7 bit 0

bit 7-0

ProximityN Status: proximity sensor activation status

1 = The proximity sensor is activated.
0 = The proximity sensor is released.

mtouch_prox_deviation_t MTOUCH_Proximity_Deviation_Get(enum mtouch_proximity_names prox)

Returns the proximity sensor deviation value.

The proximity deviation is different than the button deviation. To increase the sensitivity of the proximity sensor, the difference between reading and baseline is integrated by a low pass filter with gain. The gain is set in the MCC proximity sensor setting panel. The output of the digital integrator is the deviation of this proximity sensor.

The output ranges from 0 to 127, and if the actual value is not in the range of 0 to 127, it will be set to 0 or 127 based on the actual value.

mtouch_prox_reading_t MTOUCH_Proximity_Reading_Get(enum mtouch_proximity_names prox)

Returns the proximity sensor reading value. This is an unsigned 16-bit value.

The proximity sensor reading is a low pass filtered version of the sensor raw data. The filter strength is determined by the reading filter level in the MCC Proximity Sensor Setting panel.

mtouch_prox_reading_t MTOUCH_Proximity_Baseline_Get(enum mtouch_proximity_names prox)

Returns the proximity sensor baseline value. This is an unsigned 16-bit value.

The proximity sensor baseline is a conditional low pass filtered version of the proximity sensor reading. The filter strength is determined by the baseline gain in the MCC Proximity Sensor Setting panel. The baseline is updated periodically if the proximity sensor is not activated.

mtouch_prox_scaling_t MTOUCH_Proximity_Scaling_Get(enum mtouch_proximity_names prox)

Returns the scaling factor of the proximity sensor.

More information for scaling can be found at: http://microchipdeveloper.com/touch:button-proximity-sensor-configuration.

mtouch_prox_threshold_t MTOUCH_Proximity_Threshold_Get(enum mtouch_proximity_names prox)

Returns the threshold of the proximity sensor.

More information for the threshold can be found at: http://microchipdeveloper.com/touch:button-proximity-sensor-configuration.

void MTOUCH_Proximity_Scaling_Set(enum mtouch_proximity_names prox,mtouch_prox_scaling_t scaling)

Sets the scaling factor for the proximity sensor. The range for scaling factor is from 0 to 8.

void MTOUCH_Proximity_Threshold_Set(enum mtouch_proximity_names prox,mtouch_prox_threshold_t threshold)

Sets the threshold of the proximity sensor. The range for scaling factor is from 1 to 127.

void MTOUCH_Proximity_Disable(enum mtouch_proximity_names prox)

Disables the proximity sensor.

The sensor linked to this proximity sensor is not scanned. The proximity sensor baseline is not updated until the proximity sensor is resumed.

To use this feature, you need to enable the disable/suspend feature in the MCC Proximity Sensor Setting panel.

void MTOUCH_Proximity_Suspend(enum mtouch_proximity_names prox)

Suspends the proximity sensor.

The sensor linked to this proximity sensor is not scanned for the most time, but the proximity sensor baseline is updated at the regular rate(baseline update rate) by scanning the sensor temporarily.

To use this feature, you need to enable the disable/suspend feature in the MCC Proximity Sensor Setting panel.

void MTOUCH_Proximity_Resume(enum mtouch_proximity_names prox)

Resume the full functionality of the proximity sensor.

If the proximity sensor resumes from the suspended state, then the proximity sensor is set to released state.

If the proximity sensor resumes from the disabled state, then the proximity sensor is set to initialization state to re-established the baseline.


Slider/Wheel Module

This module contains mtouch_slider.c and mtouch_slider.h files, which provides function to access the sliders/wheels.

Public Types

enum mtouch_slider_names {Sliderxx,…}

This enum describes the slider/wheel name which you specify in the MCC mTouch Configurator. The value always starts from 0.

Properties

MTOUCH_SLIDERS

Holds the number of slider and wheel in this project.

Public Functions

void MTOUCH_Slider_InitializeAll(void)

Initializes all the slider and wheel in this project. This only needs to be called once after the device reset.

void MTOUCH_Proximity_ServiceAll(void)

Processes the data from the slider/wheel segment buttons and determines the state and position of the slider/wheel. This should be called after MTOUCH_Button_ServiceAll().

bool MTOUCH_Slider_isInitialized(enum mtouch_slider_names sliderName

Returns true if the slider/wheel is intialized, returns false otherwise.

bool MTOUCH_Slider_isPressed(enum mtouch_slider_names sliderName)

Returns true if the slider/wheel is pressed, returns false otherwise.

bool MTOUCH_Slider_isReburstRequest(enum mtouch_slider_names sliderName)

Returns true if the slider/wheel is requesting reburst, returns false otherwise.

This can only be used when the reburst feature is enabled in the button module in MCC Button Control panel.

bool MTOUCH_Slider_Reburst_Service()

Processes the slider/wheel reburst request. Return true if any slider/wheel needs reburst, returns false otherwise.

bool MTOUCH_Slider_isPositionChanged(enum mtouch_slider_names sliderName)

Returns true if the slider/wheel position is changed, returns false otherwise.

uint16_t MTOUCH_Slider_Position_Get(enum mtouch_slider_names sliderName)

Returns the slider/wheel position value.

The range of the output is determined by the resolution bit setting in the MCC Slider Configuration panel.

Example

uint16_t MTOUCH_Slider_Threshold_Get(enum mtouch_slider_names sliderName)

Returns the threshold for the slider/wheel.

uint16_t MTOUCH_Slider_Deviation_Get(enum mtouch_slider_names sliderName)

Returns the deviation for the slider/wheel. This is also known as the contact size of the slider/wheel.

The contact size is the sum of deviations from the two neighboring segments, which have the highest deviation. To activate the slider/wheel, the contact size must be larger than the slider/wheel threshold.

void MTOUCH_Slider_SetPositionChangedCallback(void (*callback)(enum mtouch_slider_names))

Sets the callback function of slider/wheel position changed event. The parameter of this callback function is the name (index) of the slider/wheel, which has its position changed.

Example

void MTOUCH_Slider_SetPositionChangedCallback(void (*callback)(enum mtouch_slider_names))

Sets the callback function of slider/wheel position changed event. The parameter of this callback function is the name (index) of the slider/wheel, which has its position changed.

void MTOUCH_Slider_SetPressedCallback(void (*callback)(enum mtouch_slider_names))

Sets the callback function of slider/wheel pressed event. The parameter of this callback function is the name (index) of the slider/wheel, which just gets pressed.

void MTOUCH_Slider_SetReleasedCallback(void (*callback)(enum mtouch_slider_names))

Sets the callback function of slider/wheel released event. The parameter of this callback function is the name (index) of the slider/wheel, which just gets released.

© 2018 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.