CTSU v2 Driver

Table of Contents

• CTSU v2 HAL Module Introduction
  • CTSU v2 HAL Module Features
• CTSU v2 HAL Module Configuration
  • CTSU v2 HAL Module Interrupt Configuration
  • CTSU v2 HAL Module Clock Configuration
  • CTSU v2 HAL Module Pin Configuration
• CTSU v2 HAL Module Usage Notes
  • CTSU v2 HAL Module Sensor ICO Correction
  • CTSU v2 HAL Module Initial Offset Tuning
  • CTSU v2 HAL Module Scan Trigger
  • CTSU v2 HAL Module Self-Capacitance Multi-Scan Mode
  • CTSU v2 HAL Module Mutual-Capacitance Full Scan Mode
  • CTSU v2 HAL Module Self Diagnosis
• CTSU v2 HAL Module Examples
  • CTSU v2 HAL Module Basic Example
  • CTSU v2 HAL Module Multi-Configuration Example
  • CTSU v2 HAL Module Self Diagnosis Example

CTSU v2 HAL Module Introduction

The capacitive touch sensing unit version 2 HAL driver (r_ctsu v2) provides an API to control the CTSU peripheral. This module performs capacitance measurement based on various settings defined by the configuration. This module is configured via the QE for Capacitive Touch.

CTSU v2 HAL Module Features

• Supports both Self-capacitance multi scan mode and Mutual-capacitance full scan mode
• Scans may be started by software or an external trigger
• Returns measured capacitance data on scan completion
• Optional DTC support
• Built-in function that diagnoses its own circuit.

CTSU v2 HAL Module Configuration

Note

This module is configured via the QE for Capacitive Touch. For information on how to use the QE tool, once the tool is installed click Help -> Help Contents in e2 studio and search for "QE".

The following build time configurations are defined in ssp_cfg/r_ctsu_cfg.h:

Build Time Configurations for r_ctsu

Configuration	Options	Default	Description
Parameter Checking	- Default (BSP) - Enabled - Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
Support for using DTC	- Enabled - Disabled	Disabled	Enable DTC support for the CTSU module.
Interrupt priority level	MCU Specific Options		Priority level of all CTSU interrupt (CSTU_WR,CTSU_RD,CTSU_FN)

This module can be added to the Stacks tab via New Stack > Driver > CapTouch > CTSU Driver on r_ctsu. 

Configurations for Driver > CapTouch > CTSU Driver on r_ctsu

Configuration	Options	Default	Description
Scan Start Trigger	MCU Specific Options		CTSU Scan Start Trigger Select

CTSU v2 HAL Module Interrupt Configuration

The first R_CTSU_Open function call sets CTSU peripheral interrupts. The user should provide a callback function to be invoked at the end of the CTSU scan sequence. The callback argument will contain information about the scan status.  

CTSU v2 HAL Module Clock Configuration

The CTSU peripheral module uses PCLKB as its clock source. You can set the PCLKB frequency using the Clocks tab of the RA Configuration editor or by using the CGC Interface at run-time.

Note

The CTSU Drive pulse will be calculated and set by the tooling depending on the selected transfer rate.

CTSU v2 HAL Module Pin Configuration

The TSn pins are sensor pins for the CTSU.

The TSCAP pin is used for an internal low-pass filter and must be connected to an external decoupling capacitor.

CTSU v2 HAL Module Usage Notes

CTSU v2 HAL Module Sensor ICO Correction

In order to improve the measurement accuracy, the correction coefficient is generated at the first R_CTSU_Open.

Therefore, the first R_CTSU_Open process takes about 40ms.  

CTSU v2 HAL Module Initial Offset Tuning

CTSU v2 has a current offset mechanism to cancel the parasitic capacitance. This module automatically adjusts to be within the dynamic range of the Sensor ICO, taking into account the amount of current that changes with touch. This adjustment uses normal measurement process and requires several R_CTSU_ScanStart and R_CTSU_DataGet. R_CTSU_DataGet returns SSP_ERR_CTSU_INCOMPLETE_TUNING if it is being adjusted. The member "so" of ctsu_element_cfg_t is used as the starting point for adjustment, so if this value is appropriate, it can be completed quickly. Normally, this value uses the value adjusted by QE for Capacitive Touch.

CTSU v2 HAL Module Scan Trigger

Scanning of sensors may begin by either a software trigger or an external event initiated by the Event Link Controller (ELC). This trigger can be set with the member "cap" of ctsu_cfg_t. Typically, a software trigger is used. Common usage is to have a periodic timer initiate scans. For software triggers, a periodic timer such as the CMT is configured whose interval is large enough to allow for all sensors to be scanned and data to be updated. Software triggers are issued by calling R_CTSU_ScanStart. Using an external trigger is processed almost identically to using software triggers. Call R_CTSU_ScanStart before starting the timer to set the measurement and prepare for external trigger measurement. After that, when the timer is started, the measurement start trigger is applied.

CTSU v2 HAL Module Self-Capacitance Multi-Scan Mode

In self-capacitance mode each TS pin is assigned to one touch button. Electrodes of multiple TS pins can be physically aligned to create slider or wheel interfaces.

• Scan Order
  •     The hardware scans the specified pins in ascending order.
  •     For example, if pins TS05, TS08, TS02, TS03, and TS06 are specified in your application, the hardware will scan them in the order TS02, TS03, TS05, TS06, TS08.
• Element
  •     -n element refers to the index of a pin within the scan order. Using the previous example, TS05 is element 2.
• Scan Time
  •     Scanning is handled directly by the CTSU peripheral and does not utilize any main processor time.
  •     It takes approximately 500us to scan a single sensor.
  •     If DTC is not used additional overhead is required for the main processor to transfer data to/from registers when each sensor is scanned.

Set CTSU_MODE_SELF_MULTI_SCAN to "md" of ctsu_cfg_t. Also, add the number of terminals used for this measurement to CTSU_CFG_NUM_SELF_ELEMENTS. For details, refer to the configuration and sample application output by QE for Capacitive Touch.  

CTSU v2 HAL Module Mutual-Capacitance Full Scan Mode

In mutual-capacitance mode each TS pin acts as either a 'row' or 'column' in an array of sensors. As a result, this mode uses fewer pins when more than five sensors are configured. Mutual-capacitance mode is ideal for applications where many touch sensors are required, like keypads, button matrices and pads.

As an example, consider a standard phone keypad comprised of a matrix of four rows and three columns.

In mutual capacitance mode only 7 pins are necessary to scan 12 buttons. In self mode, 12 pins would be required.

• Scan Order
  • The hardware scans the matrix by iterating over the TX pins first and the RX pins second.
  • For example, if pins TS10, TS11, and TS03 are specified as RX sensors and pins TS02, TS07, and TS04 are specified as TX sensors, the hardware will scan them in the following sensor-pair order:
    TS03-TS02, TS03-TS04, TS03-TS07, TS10-TS02, TS10-TS04, TS10-TS07, TS11-TS02, TS11-TS04, TS11-TS07
• Element
  • An element refers to the index of a sensor-pair within the scan order. Using the previous example, TS10-TS07 is element 5.
• Scan Time
  • Because mutual-capacitance scans two patterns for one element it takes twice as long as self-capacitance (1ms vs 0.5ms per element).

Set CTSU_MODE_MUTUAL_FULL_SCAN to "md" of ctsu_cfg_t. Also, add the number of matrix used for this measurement to CTSU_CFG_NUM_MUTUAL_ELEMENTS. For details, refer to the configuration and sample application output by QE for Capacitive Touch.  

CTSU v2 HAL Module Self Diagnosis

The CTSU peripheral has a built-in function that diagnoses its own inner circuit. The diagnostic requirements are providing 5 types of diagnosis. The diagnosis function is executed by calling the R_CTSU_Diagnosis() API function. This is executed independently from the other measurements and does not affect them. 

Note

To enable the diagnosis function, set CTSU_CFG_DIAG_SUPPORT_ENABLE to 1.

A 27pF condenser should be connected externally.

CTSU v2 HAL Module Examples

CTSU v2 HAL Module Basic Example

This is a basic example of minimal use of the CTSU in an application.

volatile bool g_scan_flag = false;
void ctsu_callback (ctsu_callback_args_t * p_args)
{
   if (CTSU_EVENT_SCAN_COMPLETE == p_args->event)
   {
       g_scan_flag = true;
   }
}
void ctsu_basic_example (void)
{
   ssp_err_t err = SSP_SUCCESS;
   uint16_t  data[CTSU_CFG_NUM_SELF_ELEMENTS];
   
   err = R_CTSU_Open(&g_ctsu_ctrl, &g_ctsu_cfg);
   
   /* Handle any errors. This function should be defined by the user. */
   handle_error(err);
   
   
   while (true)
   {
       err = R_CTSU_ScanStart(&g_ctsu_ctrl);
       handle_error(err);
       while (!g_scan_flag)
       {
           /* Wait for scan end callback */
       }
       g_scan_flag = false;
       err = R_CTSU_DataGet(&g_ctsu_ctrl, data);
       if (SSP_SUCCESS == err)
       {
           /* Application specific data processing. */
       }
   }
   
   
}

CTSU v2 HAL Module Multi-Configuration Example

This is a optional example of using both Self-capacitance and Mutual-capacitance configurations in the same project.

void ctsu_optional_example (void)
{
   ssp_err_t err = SSP_SUCCESS;
   uint16_t  data[CTSU_CFG_NUM_SELF_ELEMENTS + (CTSU_CFG_NUM_MUTUAL_ELEMENTS * 2)];
   err = R_CTSU_Open(&g_ctsu_ctrl, &g_ctsu_cfg);
   handle_error(err);
   err = R_CTSU_Open(&g_ctsu_ctrl_mutual, &g_ctsu_cfg_mutual);
   handle_error(err);
   while (true)
   {
       R_CTSU_ScanStart(&g_ctsu_ctrl);
       while (!g_scan_flag)
       {
           /* Wait for scan end callback */
       }
       g_scan_flag = false;
       R_CTSU_ScanStart(&g_ctsu_ctrl_mutual);
       while (!g_scan_flag)
       {
           /* Wait for scan end callback */
       }
       g_scan_flag = false;
       err = R_CTSU_DataGet(&g_ctsu_ctrl, data);
       handle_error(err);
       if (SSP_SUCCESS == err)
       {
           /* Application specific data processing. */
       }
       err = R_CTSU_DataGet(&g_ctsu_ctrl_mutual, data);
       handle_error(err);
       if (SSP_SUCCESS == err)
       {
           /* Application specific data processing. */
       }
   }
}

CTSU v2 HAL Module Self Diagnosis Example

This is an example code of using self-diagnosis functionality.

ssp_err_t err;
uint16_t  dummy;
/* Open the Diagnosis function */
R_CTSU_Open(g_qe_ctsu_instance_diagnosis.p_ctrl, g_qe_ctsu_instance_diagnosis.p_cfg);
/* Scan the Diagnosis function */
R_CTSU_ScanStart(g_qe_ctsu_instance_diagnosis.p_ctrl);
while (0 == g_qe_touch_flag) {}
g_qe_touch_flag = 0;
err = R_CTSU_DataGet(g_qe_ctsu_instance_diagnosis.p_ctrl,&dummy);
/* Call diagnosis function when the return value of R_CTSU_DataGet is SSP_SUCCESS. */
if (SSP_SUCCESS == err)
{
   err = R_CTSU_Diagnosis(g_qe_ctsu_instance_diagnosis.p_ctrl);
   if ( SSP_SUCCESS  == err )
   {
           /* Diagnosis is done successfully */
   }
}