mTouch® Capacitive Sensing Library Module API

Last modified by Microchip on 2023/11/10 11:18

The mTouch® Capacitive Sensing library is customized and generated by the MPLAB® X Code Configurator (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 Application Programming Interfaces (APIs) provided by the mTouch library to access sensor, button proximity sensor, and slider/wheel.

Sensor Module

This module contains the mtouch_sensor.c and mtouch_senor.h files, which provide access to the hardware sensor. More details about the sensor module can be found on the "Hardware Sensor Configuration" page.

Public Types

enum mtouch_sensor_names {Sensor_ANxx,…}

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

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 the Sensor_Service() function to observe the error message if needed.

ConstantValueDescription
MTOUCH_SENSOR_ERROR_none0No error.
MTOUCH_SENSOR_ERROR_invalid_index-1The index of of sensor is invalid.
MTOUCH_SENSOR_ERROR_interrupt_notEnabled-2The global interrupt is not enabled, this error only happens on software Capacitive Voltage Divider (CVD) implementation.
MTOUCH_SENSOR_ERROR_invalid_calibrate-3The analog calibration is out of range.
MTOUCH_SENSOR_ERROR_tooManyRetries-4The 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-5The error happens when a new scan starts before storing the previous result from ADC due to the interruption of other tasks. This only happens on dual ADC with HCVD implementation.
MTOUCH_SENSOR_ERROR_interruptedScan-6The 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.

Back to Top

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.

Back to Top

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, we recommend calling this function to restore the ADC configuration for a mTouch library scan.

Example

while(1)
{
   if(MTOUCH_Service_Mainloop())
    {
        myADC_Initialization();    // Initialize the ADC based on your task
       myADC_Task();               //  Perform the ADC task
       MTOUCH_Sensor_Scan_Initialize();
    }
}

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

void mySensorCallback(enum mtouch_sensor_names sensor)
{
    printf("The sensor %d is sampled.\r\n", sensor);
}

main()
{
    ...

    MTOUCH_Sensor_SetSampledCallback(mySensorCallback);

    ...

   while(1)
    {
       MTOUCH_Service_Mainloop();
    }
}

bool MTOUCH_Sensor_SampleAll(void)

This function behaves differently for different acquisition implementations.

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 non-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

if(MTOUCH_Sensor_isSampling() == false)
{
     myADCC_Initialization();    // Initialize the ADCC based on your task
    myADC_Task();                  // Perform the ADC task
    MTOUCH_Sensor_ADCC_Initialize();
}

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 Sensor_calculate_active_thrs(oversampling) macro.

This can be used to speed up the response time for low power setup. In the example below, 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 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

while (1)
{
   if(MTOUCH_Service_Mainloop())
    {
       if(MTOUCH_Sensor_isActive(Sensor_AN0)==false
       && MTOUCH_Button_isInitialized(Button0)==true )
        {
            SLEEP();         // Wake up by timer interrupt
           NOP();
        }
    }
}

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 MTOUCH_Service_Mainloop() of the mtouch.c file, the flag is reset after all the post sensor acquisition services.

Example

bool MTOUCH_Service_Mainloop(void)
{

   /* In free running mode, the mTouch service will be executed
        once MTOUCH_Service_Mainloop gets called.*/

    mtouch_time_toScan = true;

   if(mtouch_time_toScan)               
    {
       if(MTOUCH_Sensor_SampleAll() == false)     
           return false;           
        MTOUCH_Button_ServiceAll();             
        MTOUCH_Proximity_ServiceAll();          
        mtouch_time_toScan = MTOUCH_needReburst();
        MTOUCH_Sensor_Sampled_ResetAll();  
        MTOUCH_Tick();
       return true;
    }
   else                             
    {
       return false;                
    }
}

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.

Back to Top

Button Module

This module contains the mtouch_button.c and mtouch_button.h files, which provide function to access the buttons. More details about the button module can be found on the "mTouch® Button/Proximity Sensor Configuration" page.

Back to Top

Public Types

enum mtouch_button_names {Buttonxx,…}

This enum describes the button name that you specify in the MCC mTouch Configurator. The value always starts from zero.

Back to Top

Properties

MTOUCH_BUTTONS

Holds the number of buttons in this project.

Back to Top

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() function 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 myButtonPressedCallback(enum mtouch_button_names button)
{
    printf("The button %d is pressed.\r\n", button);
}

void myButtonReleasedCallback(enum mtouch_button_names button)
{
    printf("The button %d is released.\r\n", button);
}

main()
{
    ...

    MTOUCH_Button_SetPressedCallback(myButtonPressedCallback);
    MTOUCH_Button_SetNotPressedCallback(myButtonReleasedCallback);
    ...

   while(1)
    {
       MTOUCH_Service_Mainloop();
    }
}

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

main()
{
    ...

   while(1)
    {
      if(MTOUCH_Service_Mainloop())
       {
          if(MTOUCH_Button_isPressed(Button0))
           {
               printf("Button0 is pressed.\r\n");
           }
          else
           {
               printf("Button0 is released.\r\n");
            }
       }
    }
}

bool MTOUCH_Button_isInitialized(enum mtouch_button_names button)

Returns true if the button is initialized, 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 eight-button project will have return value like shown below:

Button Status Mask bits

R-0R-0R-0R-0R-0R-0R-0R-0
Button7 StatusButton6 StatusButton5 StatusButton4 StatusButton3 StatusButton2 StatusButton1 StatusButton0 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)Reading=Reading×(2filterlevel−1)2filterlevel+SensorRawData2filterlevel

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 on the "mTouch® Button/Proximity Sensor Configuration" page.

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 on the "mTouch® Button/Proximity Sensor Configuration" page.

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 the released state.

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

Back to Top


Proximity Sensor Module

This module contains the mtouch_proximity.c and mtouch_proximity.h files, which provide function to access the proximity sensors. More details about the proximity sensor module can be found on the "mTouch® Button/Proximity Sensor Configuration" page.

Back to Top

Public Types

enum mtouch_proximity_names{ ProximityXX,…}

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

Back to Top

Properties

MTOUCH_PROXIMITY

Holds the number of proximity sensors in this project.

Back to Top

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 myProxActivateddCallback(enum mtouch_proximity_names prox)
{
    printf("The proximity sensor %d is activated.\r\n", prox);
}

void myProxReleasedCallback(enum mtouch_proximity_names prox)
{
    printf("The proximity sensor %d is released.\r\n", prox);
}

main()
{
    ...

    MTOUCH_Proximity_SetActivatedCallback(myProxActivateddCallback);
    MTOUCH_Proximity_SetNotActivatedCallback(myProxReleasedCallback);
    ...

   while(1)
    {
       MTOUCH_Service_Mainloop();
    }
}

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 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-0R-0R-0R-0R-0R-0R-0R-0
Proximity7 StatusProximity6 StatusProximity5 StatusProximity4 StatusProximity3 StatusProximity2 StatusProximity1 StatusProximity0 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 on the "mTouch® Button/Proximity Sensor Configuration" page.

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 on the "mTouch® Button/Proximity Sensor Configuration" page.

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 zero to eight.

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 one 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 the released state.

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

Back to Top


Slider/Wheel Module

This module contains the mtouch_slider.c and mtouch_slider.h files, which provide function to access the sliders/wheels. More details about the slider/wheel module can be found on the "mTouch® Slider/Wheel Configuration" page.

Back to Top

Public Types

enum mtouch_slider_names {Sliderxx,…}

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

Back to Top

Properties

MTOUCH_SLIDERS

Holds the number of slider and wheel in this project.

Back to Top

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.

uint8_t MTOUCH_Slider_Status_Get(void)

Returns the status of the slider.

The status bits details is shown below:

Slider Status bits

R-0R-0R-0R-0R-0R-0R-0R-0
SURFACE_REBURSTN/AN/AN/AN/APOSITION_CHANGETOUCH_STATETOUCH_STATE
bit 7      bit 0

bit 0-1

TOUCH_STATE: status bits

00 = The slider is initializing.
01 = The slider is released.
10 = The slider is pressed.

bit 2

POSITION_CHANGE: status bit

1 = The touch position is changed.
0 = The touch position is not changed.

bit 3-6

N/A: Reserved

bit 7

SLIDER_REBURST: status bit

1 = The slider requests reburst.
0 = The slider dose not request reburst.

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

main()
{
    ...
    ...

   while(1)
    {
       if(MTOUCH_Service_Mainloop())
        {
            if(MTOUCH_Slider_isPositionChanged(Slider0))
             {
                 printf("The new slider position is %d. \r\n", MTOUCH_Slider_Position_Get(Slider0));
             }
        }
    }
}

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 the 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 mySliderCallback(enum mtouch_slider_names slidername)
{
    printf("The slider %d just changed its postion.\r\n", slidername);
}

main()
{
    ...

    MTOUCH_Slider_SetPositionChangedCallback(mySliderCallback);

    ...

   while(1)
    {
       MTOUCH_Service_Mainloop();
    }
}

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 the 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 the slider/wheel released event. The parameter of this callback function is the name (index) of the slider/wheel, which just gets released.

Back to Top


Surface Module

This module contains the mtouch_surface.c and mtouch_surface.h files, which provide the function to access the surface touch. More details about the surface module can be found on the "mTouch® Surface/Gesture Configuration" page.

Back to Top

Public Functions

void MTOUCH_Surface_InitializeAll(void)

Initializes the surface module in this project. This only needs to be called once after the device reset. Currently, the library only supports one surface per project.

void MTOUCH_Surface_ServiceAll(void)

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

uint8_t MTOUCH_Surface_Status_Get(void)

Returns the status of the surface. The status bits are different for the one-touch position and two-touch position configuration.

The status bits details for one-touch configuration is shown in the accompanying table.

Surface Status bits

R-0R-0R-0R-0R-0R-0R-0R-0
SURFACE_REBURSTN/APOSITION_V_DECPOSITION_V_INCPOSITION_H_DECPOSITION_H_INCPOSITION_CHANGETOUCH_ACTIVE
bit 7      bit 0

bit 0

TOUCH_ACTIVE: status bit

1 = The surface is touched.
0 = The surface is released.

bit 1

POSITION_CHANGE: status bit

1 = The touch position is changed.
0 = The touch position is not changed.

bit 2

POSITION_H_INC: status bit

1 = The horizontal touch position has incremental change.
0 = The horizontal touch position doesn't have incremental change.

bit 3

POSITION_H_DEC: status bit

1 = The horizontal touch position has decremental change.
0 = The horizontal touch position doesn't have decremental change.

bit 4

POSITION_V_INC: status bit

1 = The vertical touch position has incremental change.
0 = The horizontal touch position doesn't have incremental change.

bit 5

POSITION_V_DEC: status bit

1 = The vertical touch position has decremental change.
0 = The horizontal touch position doesn't have decremental change.

bit 6

N/A: Reserved

bit 7

SURFACE_REBURST: status bit

1 = The surface requests reburst.
0 = The surface dose not request reburst.

The status bits details for two-touch configuration is shown below:

Surface Status bits

R-0R-0R-0R-0R-0R-0R-0R-0
SURFACE_REBURSTN/AN/AN/AN/AN/APOSITION_CHANGETOUCH_ACTIVE
bit 7      bit 0

bit 0

TOUCH_ACTIVE: status bit

1 = The surface is touched.
0 = The surface is released.

bit 1

POSITION_CHANGE: status bit

1 = The touch position is changed.
0 = The touch position is not changed.

bit 2

N/A: Reserved

bit 3

N/A: Reserved

bit 4

N/A: Reserved

bit 5

N/A: Reserved

bit 6

N/A: Reserved

bit 7

SURFACE_REBURST: status bit

1 = The surface requests reburst.
0 = The surface dose not request reburst.

uint8_t MTOUCH_Surface_Contact_Status_Get(uint8_t contact)

Returns the surface contact status. This is only available for two-touch position configuration.

Surface Status bits

R-0R-0R-0R-0R-0R-0R-0R-0
N/AN/APOSITION_V_DECPOSITION_V_INCPOSITION_H_DECPOSITION_H_INCPOSITION_CHANGETOUCH_ACTIVE
bit 7      bit 0

bit 0

TOUCH_ACTIVE: status bit

1 = The surface is touched.
0 = The surface is released.

bit 1

POSITION_CHANGE: status bit

1 = The touch position is changed.
0 = The touch position is not changed.

bit 2

POSITION_H_INC: status bit

1 = The horizontal touch position has incremental change.
0 = The horizontal touch position doesn't have incremental change.

bit 3

POSITION_H_DEC: status bit

1 = The horizontal touch position has decremental change.
0 = The horizontal touch position doesn't have decremental change.

bit 4

POSITION_V_INC: status bit

1 = The vertical touch position has incremental change.
0 = The horizontal touch position doesn't have incremental change.

bit 5

POSITION_V_DEC: status bit

1 = The vertical touch position has decremental change.
0 = The horizontal touch position doesn't have decremental change.

bit 6

N/A: Reserved

bit 6

N/A: Reserved

uint16_t MTOUCH_Surface_Position_Get(uint8_t ver_or_hor)

Returns the surface position value. The input parameter ver_or_hor determines whether the output is the vertical position or horizontal position. 0 is for horizontal position, 1 is for vertical position, or the macro HORIZONTAL and VERTICAL can be used as the input. Note that this function is only available when 1 finger touch surface is configured.

Example

main()
{
    ...
    ...

   while(1)
    {
       if(MTOUCH_Service_Mainloop())
        {
            if(MTOUCH_Surface_Status_Get() & TOUCH_ACTIVE)
             {
                 printf("The surface touch position is (%d,%d).\r\n" ,
                 MTOUCH_Surface_Position_Get(HORIZONTAL),MTOUCH_Surface_Position_Get(VERTICAL));
             }
        }
    }
}

uint16_t MTOUCH_Surface_Position_Get(uint8_t ver_or_hor, uint8_t contact)

Returns the surface position value of the selected contact point. The input parameter ver_or_hor determines whether the output is the vertical position or horizontal position. 0 is for horizontal position, 1 is for vertical position, or the macro HORIZONTAL and VERTICAL can be used as the input. The second parameter contact determines which contact point, 0 is for the first contact point, and 1 is for the second contact point. Note that this function is only available when two finger touch surface is configured.

uint8_t MTOUCH_Surface_Resolution_Get(void)

Returns the surface resolution in bits. The default is 8-bit resolution.

uint8_t MTOUCH_Surface_Resolution_Get(void)

Sets the surface resolution in bits.

uint8_t MTOUCH_Surface_Deadband_Get(void)

Returns the surface deadband percentage.

uint8_t MTOUCH_Surface_Deadband_Set(void)

Sets the surface deadband percentage.

Back to Top


Surface Gesture Module

This module contains the mtouch_gesture.c and mtouch_gesture.h files, which provide the function to access the surface gesture. More details about the surface gesture module can be found on the "mTouch® Surface/Gesture Configuration" page.

Back to Top

Public Functions

void MTOUCH_Gesture_Initialize(void)

Initializes the surface gesture module in this project. This only needs to be called once after the device reset.

void MTOUCH_Gesture_Service(void)

Processes the touch position data from the surface module and determines the surface gesture. This should be called after MTOUCH_Surface_ServiceAll().

bool MTOUCH_Gesture_isGestureDetected(void)

Returns true is gesture is detected. This module will hold the last deteced gesture until MTOUCH_Gesture_clearGesture() is called.

void MTOUCH_Gesture_clearGesture(void)

Clears the last detected gesture, and prepares for the next gesture detection.

uint8_t MTOUCH_Gesture_GestureID_Get(void)

Returns the detected gesture ID. All the gesture IDs can be found in the mtouch_gesture.h file.

uint8_t MTOUCH_Gesture_GestureValue_Get(void)

Returns the additional information for wheel and pinch-zoom gesture. For wheel gesture, it returns a wheel counter that counts the rotations. For pinch-zoom, it returns the distance that the fingers are moving toward or away from each other.

Example

main()
{
    ...
    ...

   while(1)
    {
       if(MTOUCH_Service_Mainloop())
        {
           if(MTOUCH_Gesture_isGestureDetected())
            {
                uint8_t gesture_which_gesture = MTOUCH_Gesture_GestureID_Get();

                 /*  This value is only applicable to wheel gesture and pinch/zoom*/
                 uint8_t gesture_info = MTOUCH_Gesture_GestureValue_Get();

                 /* process the gesture */
            }

        }
    }
}

void MTOUCH_Gesture_update_timer(uint16_t time_elapsed_since_update)

Increments the internal gesture timer for time-based gesture detection.

uint8_t MTOUCH_Gesture_GestureConfigAddress_Get(void)

Returns the address of the gesture configuration variable.

Back to Top


Host Interface Module

This module contains the mtouch_memory.c and mtouch_memory.h files, which provide functions to access the custom field of the memory map. More details about the host interface module can be found on the "Host Interface Configuration" page.

Back to Top

Public Functions

void MTOUCH_Memory_i2cSetCustomAddrReadHandler(readHandler handler)

Sets the read handler function when the device receives a read request from the host. This handler function will be called if the read address is equal to or greater than the custom field starting address.

void MTOUCH_Memory_i2cSetCustomAddrWriteHandler(readHandler handler)

Sets the write handler function when the device receives a write request from the host. This handler function will be called if the write address is equal to or greater than the custom field starting address.

Example

In this example, besides touch, the device also implements an LED and temperature sensor, so the host also wants to control the LED and read out the temperature sensor information.

If the user has defined the custom field start address as 0xF0, then with the implementation below, a host read from address 0xF0 will return the temperature sensor reading, and a read from address 0xF1 will return the LED brightness. A host write to address 0xF0 will not do anything as the temperature is read-only and a write to address 0xF1 will set the brightness of the LED.

uint8_t myReadHandler(uint8_t index)
{
   switch(index)
    {
       case 0: return getTempSensorReading();
       case 1: return getLEDBrightness();

       default: return 0;
    }
}

void myWriteHandler(uint8_t index,uint8_t value)
{
   switch(index)
    {
       case 0: break; /* Do nothing as the temperature is read-only */
       case 1: setLEDBrightness(value); break;
       default: break;
    }
}

main()
{
    ...
    ...
    MTOUCH_Memory_i2cSetCustomAddrReadHandler(myReadHandler);
    MTOUCH_Memory_i2cSetCustomAddrWriteHandler(myWriteHandler);

   while(1)
    {
       if(MTOUCH_Service_Mainloop())
        {
              ...
         }
            /*Application Code*/
             ...
        }
    }
}

Back to Top


Low Power Module

The low power feature is technically not a dedicated module. It sits on top of all the other modules and manages the power mode transition between low power and normal power mode. The implementation is in the mtouch.c file, and the APIs will be available by including the mtouch.h file. More details about the low power module can be found on the "mTouch® Low-Power Configuration" page.

Back to Top

Public Functions

bool MTOUCH_Service_LowpowerState_Get(void)

Returns true if the system is in low power mode, otherwise, return false.

void MTOUCH_Service_enableLowpower(void)

Enables the low power feature at run-time.

void MTOUCH_Service_disableLowpower(void)

Disables the low power feature at run-time.

void MTOUCH_Service_enterLowpower(void)

Puts the system into low power mode. The low power feature has to be enabled in order to enter low power mode.

void MTOUCH_Service_exitLowpower(void)

Shifts the system out of low power mode temporarily. The system will go back to low power mode if there is no touch event happening before the active timeout.

Back to Top