Overview

The section describes the programming interface of the TSI Peripheral driver

Overview

The TSI peripheral driver measures the capacitance of electrodes (touch sensing) in various modes and provides API functions for input/output operations.

TSI Driver Block Diagram

TSI Initialization

To initialize TSI, the application defines the startup configuration and handles to the initialization routine.

Include the "fsl_tsi_driver.h" header file in source files to use TSI driver and operate touch sensing functionality.

This is an example of the TSI driver initialization (with example of configuration) and simple measurement:

#include "fsl_tsi_driver.h"
// Declaration of TSI callback function
static void tsi_irq_callback(uint32_t instance, void* usrData);
// Set up the HW configuration for normal mode of TSI
static const tsi_config_t tsi_HwConfig =
{
  .ps = kTsiElecOscPrescaler_2div,       

Files
file	fsl_tsi_driver.h

Data Structures
struct	tsi_user_config_t
	User configuration structure for TSI driver. More...

struct	tsi_operation_mode_t
	Driver operation mode data hold structure. More...

struct	tsi_state_t
	Driver data storage place. More...

Typedefs
typedef void(*	tsi_callback_t )(uint32_t instance, void *usrData)
	Call back routine of TSI driver. More...

Enumerations
enum	tsi_modes_t { tsi_OpModeNormal = 0, tsi_OpModeProximity, tsi_OpModeLowPower, tsi_OpModeNoise, tsi_OpModeCnt, tsi_OpModeNoChange }
	Driver operation mode definition. More...

Variables
TSI_Type *const	g_tsiBase []
	Table of base addresses for TSI instances. More...

const IRQn_Type	g_tsiIrqId [TSI_INSTANCE_COUNT]
	Table to save TSI IRQ enumeration numbers defined in CMSIS header file. More...

tsi_state_t *	g_tsiStatePtr [TSI_INSTANCE_COUNT]
	Table to save pointers to context data. More...

Initialization
tsi_status_t	TSI_DRV_Init (uint32_t instance, tsi_state_t tsiState, const tsi_user_config_t tsiUserConfig)
	Initializes a TSI instance for operation. More...

tsi_status_t	TSI_DRV_DeInit (uint32_t instance)
	Shuts down the TSI by disabling interrupts and the peripheral. More...

tsi_status_t	TSI_DRV_EnableElectrode (uint32_t instance, const uint32_t channel, const bool enable)
	Enables/disables one electrode of the TSI module. More...

uint32_t	TSI_DRV_GetEnabledElectrodes (uint32_t instance)
	Returns a mask of the enabled electrodes of the TSI module. More...

tsi_status_t	TSI_DRV_Measure (uint32_t instance)
	Starts the measure cycle of the enabled electrodes. More...

tsi_status_t	TSI_DRV_MeasureBlocking (uint32_t instance)
	Starts the measure cycle of the enabled electrodes in blocking mode. More...

tsi_status_t	TSI_DRV_AbortMeasure (uint32_t instance)
	Aborts the measure cycle in non standard use of the driver. More...

tsi_status_t	TSI_DRV_GetCounter (uint32_t instance, const uint32_t channel, uint16_t *counter)
	Returns the last measured value. More...

tsi_status_t	TSI_DRV_GetStatus (uint32_t instance)
	Returns the current status of the driver. More...

tsi_status_t	TSI_DRV_EnableLowPower (uint32_t instance)
	Enters the low power mode of the TSI driver. More...

tsi_status_t	TSI_DRV_DisableLowPower (uint32_t instance, const tsi_modes_t mode)
	This function returns back the TSI driver from the low power to standard operation. More...

tsi_status_t	TSI_DRV_Recalibrate (uint32_t instance, uint32_t *lowestSignal)
	Automatically recalibrates all important TSI settings. More...

tsi_status_t	TSI_DRV_SetCallBackFunc (uint32_t instance, const tsi_callback_t pFuncCallBack, void *usrData)
	Sets the callback function that is called when the measure cycle ends. More...

tsi_status_t	TSI_DRV_ChangeMode (uint32_t instance, const tsi_modes_t mode)
	Changes the current working operation mode. More...

tsi_modes_t	TSI_DRV_GetMode (uint32_t instance)
	Returns the current working operation mode. More...

tsi_status_t	TSI_DRV_LoadConfiguration (uint32_t instance, const tsi_modes_t mode, const tsi_operation_mode_t *operationMode)
	Loads the new configuration into a specific mode. More...

tsi_status_t	TSI_DRV_SaveConfiguration (uint32_t instance, const tsi_modes_t mode, tsi_operation_mode_t *operationMode)
	Saves the TSI driver configuration for a specific mode. More...

Data Structure Documentation

struct tsi_user_config_t

Use an instance of this structure with TSI_DRV_Init(). This allows you to configure the most common settings of the TSI peripheral with a single function call. Settings include:

Data Fields
tsi_config_t *	config

tsi_callback_t	pCallBackFunc

void *	usrData

Field Documentation

tsi_config_t* tsi_user_config_t::config

A pointer to hardware configuration. Can't be NULL.

tsi_callback_t tsi_user_config_t::pCallBackFunc

A pointer to call back function of end of measurement.

void* tsi_user_config_t::usrData

A user data of call back function.

struct tsi_operation_mode_t

This is the operation mode data hold structure. The structure is keep all needed data to be driver able to switch the operation modes and properly set up HW peripheral.

Data Fields
uint16_t	enabledElectrodes

tsi_config_t	config

Field Documentation

uint16_t tsi_operation_mode_t::enabledElectrodes

The back up of enabled electrodes for operation mode

tsi_config_t tsi_operation_mode_t::config

A hardware configuration.

struct tsi_state_t

It must be created by the application code and the pointer is handled by the TSI_DRV_Init function to driver. The driver keeps all context data for itself run. Settings include:

Data Fields
tsi_status_t	status

tsi_callback_t	pCallBackFunc

void *	usrData

semaphore_t	irqSync

mutex_t	lock

mutex_t	lockChangeMode

bool	isBlockingMeasure

tsi_modes_t	opMode

tsi_operation_mode_t	opModesData [tsi_OpModeCnt]

uint16_t	counters [FSL_FEATURE_TSI_CHANNEL_COUNT]

Field Documentation

tsi_status_t tsi_state_t::status

Current status of the driver.

tsi_callback_t tsi_state_t::pCallBackFunc

A pointer to call back function of end of measurement.

void* tsi_state_t::usrData

A user data pointer handled by call back function.

semaphore_t tsi_state_t::irqSync

Used to wait for ISR to complete its measure business.

mutex_t tsi_state_t::lock

Used by whole driver to secure the context data integrity.

mutex_t tsi_state_t::lockChangeMode

Used by change mode function to secure the context data integrity.

bool tsi_state_t::isBlockingMeasure

Used to internal indication of type of measurement.

tsi_modes_t tsi_state_t::opMode

Storage of current operation mode.

tsi_operation_mode_t tsi_state_t::opModesData[tsi_OpModeCnt]

Data storage of individual operational modes.

uint16_t tsi_state_t::counters[FSL_FEATURE_TSI_CHANNEL_COUNT]

The mirror of last state of counter registers

Typedef Documentation

typedef void(* tsi_callback_t)(uint32_t instance, void *usrData)

The function is called on end of the measure of the TSI driver. The function can be called from interrupt, so the code inside the callback should be short and fast.

Parameters

instance	- instance of the TSI peripheral
usrData	- user data (type is void*), the user data are specified by function TSI_DRV_SetCallBackFunc

Returns: - none

Enumeration Type Documentation

enum tsi_modes_t

The operation name definition used for TSI driver.

Enumerator
tsi_OpModeNormal	The normal mode of TSI.
tsi_OpModeProximity	The proximity sensing mode of TSI.
tsi_OpModeLowPower	The low power mode of TSI.
tsi_OpModeNoise	The noise mode of TSI. This mode is not valid with TSI HW, valid only for the TSIL HW.
tsi_OpModeCnt	Count of TSI modes - for internal use.
tsi_OpModeNoChange	The special value of operation mode that allows call for example TSI_DRV_DisableLowPower function without change of operation mode.

Function Documentation

tsi_status_t TSI_DRV_Init	(	uint32_t	instance,
		tsi_state_t *	tsiState,
		const tsi_user_config_t *	tsiUserConfig
	)

This function initializes the run-time state structure and prepares the entire peripheral to measure the capacitances on electrodes.

static tsi_state_t myTsiDriverStateStructure;
tsi_user_config_t myTsiDriveruserConfig =
{
 .config =
    {
       ...
    },
  .pCallBackFunc = APP_myTsiCallBackFunc,
  .usrData = myData,
};
if(TSI_DRV_Init(0, &myTsiDriverStateStructure, &myTsiDriveruserConfig) != kStatus_TSI_Success)
{
   // Error, the TSI is not initialized
}

Parameters

instance	The TSI module instance.
tsiState	A pointer to the TSI driver state structure memory. The user is only responsible to pass in the memory for this run-time state structure where the TSI driver will take care of filling out the members. This run-time state structure keeps track of the current TSI peripheral and driver state.
tsiUserConfig	The user configuration structure of type tsi_user_config_t. The user populates the members of this structure and passes the pointer of this structure into the function.

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_DeInit ( uint32_t instance )

This function disables the TSI interrupts and the peripheral.

if(TSI_DRV_DeInit(0) != kStatus_TSI_Success)
{
   // Error, the TSI is not de-initialized
}

Parameters

instance The TSI module instance.

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_EnableElectrode	(	uint32_t	instance,
		const uint32_t	channel,
		const bool	enable
	)

Function must be called for each used electrodes after initialization of TSI driver.

    // On the TSI instance 0, enable electrode with index 5
if(TSI_DRV_EnableElectrode(0, 5, TRUE) != kStatus_TSI_Success)
{
    // Error, the TSI 5'th electrode is not enabled
}

Parameters

instance	The TSI module instance.
channel	Index of TSI channel.
enable	TRUE - for channel enable, FALSE for disable.

Returns: An error code or kStatus_TSI_Success.

uint32_t TSI_DRV_GetEnabledElectrodes ( uint32_t instance )

The function returns the mask of the enabled electrodes of the current mode.

uint32_t enabledElectrodeMask;

enabledElectrodeMask = TSI_DRV_GetEnabledElectrodes(0);

Parameters

instance The TSI module instance.

Returns: Mask of enabled electrodes for current mode.

tsi_status_t TSI_DRV_Measure ( uint32_t instance )

The function is non blocking. Therefore, the results can be obtained after the driver completes the measure cycle. The end of the measure cycle can be checked by pooling the TSI_DRV_GetStatus function or wait for registered callback function by using the TSI_DRV_SetCallBackFunc or TSI_DRV_Init.

// Example of the pooling style of use of TSI_DRV_Measure() function
if(TSI_DRV_Measure(0) != kStatus_TSI_Success)
{
    // Error, the TSI 5'th electrode is not enabled
}
while(TSI_DRV_GetStatus(0) != kStatus_TSI_Initialized)
{
    // Do something useful - don't waste the CPU cycle time
}

Parameters

instance The TSI module instance.

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_MeasureBlocking ( uint32_t instance )

This function is blocking. Therefore, after the function call, the result of measured electrodes is available and can be obtained by calling the TSI_DRV_GetCounter function.

// Example of the TSI_DRV_Measure() function pooling style
if(TSI_DRV_MeasureBlocking(0) != kStatus_TSI_Success)
{
    // Error, the TSI 5'th electrode is not enabled
}else
{
    // Get the result by TSI_DRV_GetCounter function
}

Parameters

instance The TSI module instance.

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_AbortMeasure ( uint32_t instance )

This function aborts the running measure cycle. It is designed for unexpected situations and not targeted for standard use.

// Start measure by @ref TSI_DRV_Measure() function
if(TSI_DRV_Measure(0) != kStatus_TSI_Success)
{
    // Error, the TSI 5'th electrode is not enabled
}
if(isNeededAbort) // I need abort measure from any application reason
{
    TSI_DRV_AbortMeasure(0);
}

Parameters

instance The TSI module instance.

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_GetCounter	(	uint32_t	instance,
		const uint32_t	channel,
		uint16_t *	counter
	)

This function returns the last measured value in the previous measure cycle. The data is buffered inside the driver.

// Get the counter value from TSI instance 0 and 5th channel
uint32_t result;
if(TSI_DRV_GetCounter(0, 5, &result) != kStatus_TSI_Success)
{
    // Error, the TSI 5'th electrode is not read
}

Parameters

instance	The TSI module instance.
channel	The TSI electrode index.
counter	The pointer to 16 bit value where will be stored channel counter value.

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_GetStatus ( uint32_t instance )

This function returns the current working status of the driver.

// Get the current status of TSI driver
tsi_status_t status;
status = TSI_DRV_GetStatus(0);

Parameters

instance The TSI module instance.

Returns: An current status of the driver.

tsi_status_t TSI_DRV_EnableLowPower ( uint32_t instance )

This function switches the driver to low power mode and immediately enables the low power functionality of the TSI peripheral. Before calling this function, the low power mode must be configured - Enable the right electrode and recalibrate the low power mode to get the best performance for this mode.

// Switch the driver to the low power mode
uint16_t signal;
// The first time is needed to configure the low power mode configuration
(void)TSI_DRV_ChangeMode(0, tsi_OpModeLowPower); // I don't check the result because I believe in.
// Enable the right one electrode for low power AKE up operation
(void)TSI_DRV_EnableElectrode(0, 5, true);
// Recalibrate the mode to get the best performance for this one electrode
(void)TSI_DRV_Recalibrate(0, &signal);
if(TSI_DRV_EnableLowPower(0) != kStatus_TSI_Success)
{
    // Error, the TSI driver can't go to low power mode
}

Parameters

instance The TSI module instance.

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_DisableLowPower	(	uint32_t	instance,
		const tsi_modes_t	mode
	)

Function switch the driver back form low power mode and it can immediately change the operation mode to any other or keep the driver in low power configuration, to be able go back to low power state.

// Switch the driver from the low power mode
if(TSI_DRV_DisableLowPower(0, tsi_OpModeNormal) != kStatus_TSI_Success)
{
    // Error, the TSI driver can't go from low power mode
}

Parameters

instance	The TSI module instance.
mode	The new operation mode request

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_Recalibrate	(	uint32_t	instance,
		uint32_t *	lowestSignal
	)

This function forces the driver to start the recalibration procedure for the current operation mode to get the best possible TSI hardware settings. The computed setting is stored into the operation mode data and can be loaded and saved by the TSI_DRV_LoadConfiguration or the TSI_DRV_SaveConfiguration functions.

Warning: The function could take more time to return and is blocking.

// Recalibrate current mode
uint16_t signal;
// Recalibrate the mode to get the best performance for this one electrode
if(TSI_DRV_Recalibrate(0, &signal) != kStatus_TSI_Success)
{
    // Error, the TSI driver can't recalibrate this mode
}

Parameters

instance	The TSI module instance.
lowestSignal	The pointer to variable where will be store the lowest signal of all electrodes

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_SetCallBackFunc	(	uint32_t	instance,
		const tsi_callback_t	pFuncCallBack,
		void *	usrData
	)

This function sets up or clears, (parameter pFuncCallBack = NULL), the callback function pointer which is called after each measure cycle ends. The user can also set the custom user data, that is handled by the parameter to a call back function. One function can be called by more sources.

// Clear previous call back function
if(TSI_DRV_SetCallBackFunc(0, NULL, NULL) != kStatus_TSI_Success)
{
    // Error, the TSI driver can't set up the call back function at the moment
}
// Set new call back function
if(TSI_DRV_SetCallBackFunc(0, myFunction, (void*)0x12345678) != kStatus_TSI_Success)
{
    // Error, the TSI driver can't set up the call back function at the moment
}

Parameters

instance	The TSI module instance.
pFuncCallBack	The pointer to application call back function
usrData	The user data pointer

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_ChangeMode	(	uint32_t	instance,
		const tsi_modes_t	mode
	)

This function changes the working operation mode of the driver.

// Change operation mode to low power
if(TSI_DRV_ChangeMode(0, tsi_OpModeLowPower) != kStatus_TSI_Success)
{
    // Error, the TSI driver can't change the operation mode into low power
}

Parameters

instance	The TSI module instance.
mode	The requested new operation mode

Returns: An error code or kStatus_TSI_Success.

tsi_modes_t TSI_DRV_GetMode ( uint32_t instance )

This function returns the current working operation mode of the driver.

// Gets current operation mode of TSI driver
tsi_modes_t mode;
mode = TSI_DRV_GetMode(0);

Parameters

instance The TSI module instance.

Returns: An current operation mode of TSI driver.

tsi_status_t TSI_DRV_LoadConfiguration	(	uint32_t	instance,
		const tsi_modes_t	mode,
		const tsi_operation_mode_t *	operationMode
	)

This function loads the new configuration into a specific mode. This can be used when the calibrated data are stored in any NVM to load after startup of the MCU to avoid run recalibration that takes more time.

// Load operation mode configuration
extern const tsi_operation_mode_t * myTsiNvmLowPowerConfiguration;
if(TSI_DRV_LoadConfiguration(0, tsi_OpModeLowPower, myTsiNvmLowPowerConfiguration) != kStatus_TSI_Success)
{
    // Error, the TSI driver can't load the configuration
}

Parameters

instance	The TSI module instance.
mode	The requested new operation mode
operationMode	The pointer to storage place of the configuration that should be loaded

Returns: An error code or kStatus_TSI_Success.

tsi_status_t TSI_DRV_SaveConfiguration	(	uint32_t	instance,
		const tsi_modes_t	mode,
		tsi_operation_mode_t *	operationMode
	)

This function saves the configuration of a specific mode. This can be used when the calibrated data should be stored in any backup memory to load after the start of the MCU to avoid running the recalibration that takes more time.

// Save operation mode configuration
extern tsi_operation_mode_t  myTsiNvmLowPowerConfiguration;
if(TSI_DRV_SaveConfiguration(0, tsi_OpModeLowPower, &myTsiNvmLowPowerConfiguration) != kStatus_TSI_Success)
{
    // Error, the TSI driver can't save the configuration
}

Parameters

instance	The TSI module instance.
mode	The requested new operation mode
operationMode	The pointer to storage place of the configuration that should be save

Returns: An error code or kStatus_TSI_Success.

Variable Documentation

TSI_Type* const g_tsiBase[]

const IRQn_Type g_tsiIrqId[TSI_INSTANCE_COUNT]

tsi_state_t* g_tsiStatePtr[TSI_INSTANCE_COUNT]

Overview

Overview

TSI Initialization

Files

Data Structures

Typedefs

Enumerations

Variables

Initialization

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation