Touch Sensing Software API Reference Manual - Reference manual

Touch Sensing Software
API Reference Manual
TSSAPIRM
Rev. 8
08/2013
How to Reach Us:
Information in this document is provided solely to enable system and software
Home Page:
freescale.com
implementers to use Freescale products. There are no express or implied copyright
Web Support:
freescale.com/support
information in this document.
licenses granted hereunder to design or fabricate any integrated circuits based on the
Freescale reserves the right to make changes without further notice to any products
herein. Freescale makes no warranty, representation, or guarantee regarding the
suitability of its products for any particular purpose, nor does Freescale assume any
liability arising out of the application or use of any product or circuit, and specifically
disclaims any and all liability, including without limitation consequential or incidental
damages. “Typical” parameters that may be provided in Freescale data sheets and/or
specifications can and do vary in different applications, and actual performance may
vary over time. All operating parameters, including “typicals,” must be validated for each
customer application by customer’s technical experts. Freescale does not convey any
license under its patent rights nor the rights of others. Freescale sells products pursuant
to standard terms and conditions of sale, which can be found at the following address:
freescale.com/SalesTermsandConditions
Freescale, the Freescale logo, ColdFire, ColdFire+, and Kinetis are trademarks of
Freescale Semiconductor, Inc., Reg. U.S. Pat. & Tm. Off. Tower is a trademark of
Freescale Semiconductor, Inc. All other product or service names are the property of
their respective owners. ARM, ARM Cortex-M4, and ARM Cortex-M0 are registered
trademarks of ARM Limited.
© 2013 Freescale Semiconductor, Inc.
Document Number: TSSAPIRM
Rev. 8, 08/2013
Chapter 1
Touch Sensing Software Library Overview
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Library features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Library architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
System base modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
1.4.1 System setup module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
1.4.2 GPIO module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.4.3 Hardware timer module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Signal sensing modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
1.5.1 GPIO low level sensor method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
1.5.2 TSI low level sensor method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
1.5.3 TSI Lite low level sensor method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Key detector modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
1.6.1 Basic key detector module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
1.6.2 AFID key detector module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
1.6.3 Noise key detector module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Decoder module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
System configuration and management module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Chapter 2
TSS System setup parameters
Chapter 3
Application Interface
3.1
3.2
3.3
3.4
3.5
TSS initialization function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
TSS task function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
TSS task sequenced function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
TSS Library Configuration Save and Restore Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
3.4.1 Save and restore electrode data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
3.4.2 Save and restore module data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
3.4.3 Save and restore all system data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
TSS Library Configuration and Status Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3.5.1 Writing to the Configuration and Status Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3.5.2 Reading the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
3.5.3 Configuration and Status registers list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
3.5.4 Faults register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
3.5.5 System Configuration register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
3.5.6 Number of Samples register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
3.5.7 DC Tracker Rate register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
iv
3.6
3.7
3.8
3.5.8 Slow DC Tracker Factor register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.9 Response Time register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.10 Stuck-key Timeout register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.11 Low Power Electrode register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.12 Low-Power Electrode Sensitivity register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.13 System Trigger register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.14 Sensitivity Configuration register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.15 Electrode enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.16 Electrode status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.17 Baseline register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.18 Dc-Tracker enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.19 Configuration Checksum Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Keypad decoder API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.1 Writing to the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.2 Reading the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.3 Configuration and Status registers list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.4 Control ID register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.5 Control Configuration register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.6 Buffer Pointer register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.7 BufferReadIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.8 BufferWriteIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.9 Event Control and Status register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.10 MaxTouches register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.11 Auto Repeat Rate register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.12 Auto Repeat Start register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.13 Keypad Callback function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Slider and Rotary decoder API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.1 Writing to the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.2 Reading the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.3 Configuration and Status registers list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.4 Control ID register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.5 Control configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.6 Dynamic Status register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.7 Static Status register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.8 Events Control register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.9 Auto-repeat Rate register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.10 Movement Timeout register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.11 Callback function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Analog slider and analog rotary decoder API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1 Writing to the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.2 Reading the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.3 Configuration and Status registers list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.4 Control ID register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.5 Control configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.6 Dynamic Status register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-16
3-16
3-16
3-17
3-18
3-18
3-19
3-19
3-20
3-20
3-21
3-21
3-22
3-22
3-23
3-25
3-26
3-26
3-27
3-28
3-28
3-29
3-30
3-31
3-31
3-32
3-32
3-33
3-34
3-36
3-36
3-37
3-37
3-38
3-39
3-40
3-40
3-41
3-41
3-42
3-43
3-45
3-46
3-46
3-47
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
v
3.9
3.8.7 Position register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.8 Events Control register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.9 Auto-repeat Rate register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.10 Movement Timeout register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.11 Range register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.12 Callback function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Matrix decoder API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.1 Writing to the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.2 Reading the Configuration and Status registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.3 Configuration and Status registers list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.4 Control ID register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.5 Control configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.6 Events Control register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.7 Auto-repeat Rate register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.8 Movement Timeout register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.9 Dynamic Status X register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.10 Dynamic Status Y register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.11 Position X register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.12 Position Y register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.13 Gesture distance X register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.14 Gesture distance Y register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.15 Range X register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.16 Range Y register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.17 Matrix callback function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-48
3-48
3-49
3-50
3-50
3-51
3-51
3-51
3-52
3-54
3-55
3-56
3-56
3-58
3-58
3-59
3-59
3-60
3-60
3-61
3-61
3-62
3-62
3-63
Chapter 4
Library Intermediate Layer Interfaces
4.1
4.2
Capacitive sensing and key detector interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.1 Electrode sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.2 Low-level initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Decoder interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.1 Decoder main function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.2 Writing the decoder schedule counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.3 Reading the decoder schedule counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.4 Reading the instant delta in the control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-1
4-1
4-2
4-4
4-4
4-5
4-5
4-6
Chapter 5
C++ wrapper
5.1
TSSSystem class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 TSSTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.2 isElecTouched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.3 isElecEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-1
5-1
5-2
5-2
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
vi
5.2
5.3
5.4
5.5
5.1.4 enableElec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.1.5 disableElec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.1.6 setSensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.1.7 getSensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.1.8 enableDCTracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.1.9 disableDCTracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.1.10 setBaseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.1.11 getBaseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.1.12 enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.1.13 disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.1.14 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
5.1.15 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
5.1.16 callbackSysFaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
5.1.17 onFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
5.1.18 regCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.1.19 unregCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
TSSControlFactory class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.2.1 createTSSControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.2.2 getTSSControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
TSSControl class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.3.1 callbackControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.3.2 enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
5.3.3 disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
5.3.4 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
5.3.5 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
TSSKeypad class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
5.4.1 callbackControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
5.4.2 enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
5.4.3 disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
5.4.4 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
5.4.5 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
5.4.6 getControlStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
5.4.7 regCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
5.4.8 unregCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
5.4.9 onTouch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
5.4.10 onRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
5.4.11 onExceededKeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
TSSASlider class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
5.5.1 callbackControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
5.5.2 enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
5.5.3 disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
5.5.4 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
5.5.5 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
5.5.6 getControlStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20
5.5.7 regCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
vii
5.6
5.7
5.8
5.9
5.5.8 unregCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.9 onInitialTouch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.10 onAllRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.11 onMovement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TSSARotary class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.1 callbackControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.2 enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.3 disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.4 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.5 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.6 getControlStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.7 regCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.8 unregCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.9 onInitialTouch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.10 onAllRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.11 onMovement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TSSSlider class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.1 callbackControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.2 enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.3 disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.4 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.5 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.6 getControlStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.7 regCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.8 unregCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.9 onInitialTouch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.10 onAllRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.11 onMovement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TSSRotary class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.1 callbackControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.2 enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.3 disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.4 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.5 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.6 getControlStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.7 regCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.8 unregCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.9 onInitialTouch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.10 onAllRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8.11 onMovement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TSSMatrix class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.9.1 callbackControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.9.2 enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.9.3 disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.9.4 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-20
5-21
5-21
5-21
5-22
5-22
5-22
5-23
5-23
5-24
5-24
5-24
5-25
5-25
5-26
5-26
5-26
5-26
5-27
5-27
5-28
5-28
5-29
5-29
5-30
5-30
5-30
5-31
5-31
5-31
5-31
5-32
5-32
5-33
5-33
5-34
5-34
5-35
5-35
5-35
5-36
5-36
5-36
5-36
5-37
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
viii
5.9.5
5.9.6
5.9.7
5.9.8
5.9.9
5.9.10
5.9.11
5.9.12
get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getControlStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
regCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
unregCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
onInitialTouch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
onAllRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
onMovement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
onGestures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-37
5-38
5-38
5-39
5-39
5-40
5-40
5-40
Touch Sensing Software API Reference Manual, Rev. 8
ix
Freescale Semiconductor
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
x
Revision History
To provide the most up-to-date information, the revision of our documents on the World Wide Web are the
most current. Your printed copy may be an earlier revision. To verify you have the latest information
available, see freescale.com.
The following revision history table summarizes changes in this document.
Revision
Number
Revision
Date
Rev. 1
07/2009
Launch Release for TSS 0.2.1
Rev. 2
10/2009
Updated for TSS 1.0 release
Rev. 3
11/2009
Updated for TSS 1.1 release
Rev. 4
06/2010
Updated for TSS 2.0 release
Rev. 5
04/2011
Updated for TSS 2.5 release
Rev. 6
03/2012
Updated for TSS 2.6 release
Rev. 7
08/2012
Updated for TSS 3.0 release
Added a new text with the sections “Signal normalization”,“Automatic sensitivity calibration”,”Baseline
initialization”,”Electrodes groups”,“Analog slider and analog rotary decoder API”,“Reading the instant
delta in the control”,”Proximity function”,”Automatic Sensitivity Calibration”,”Shielding function and
Water tolerance”,”Water tolerance mode”,”Analog rotary”,”Analog Slider”,”Matrix”
Rev. 8
08/2013
Updated for TSS 3.1 release
Added a new text with the sections “Key detector modules”, “Basic key detector module”,“AFID key
detector module”,“Noise key detector module”,“TSS Library Configuration Save and Restore
Functions”,“Save and restore electrode data”,“Save and restore module data”,“Save and restore all
system data”,“Slow DC Tracker Factor register”,“Baseline register”,“Dc-Tracker enablers”,
Removed sections 2.2, 2.3, 3.4.10, 3.4.14, 4.2.4, Appendix
Description of Changes
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
iii
Touch Sensing Software API Reference Manual, Rev. 8
iv
Freescale Semiconductor
Chapter 1
Touch Sensing Software Library Overview
This chapter describes features, architecture, and software modules of the Touch Sensing Software (TSS)
library. The following chapters describe library API functions and the use of resources.
1.1
Introduction
The TSS library enables capacitive sensing for all Freescale S08 and ColdFire V1, ColdFire+, Kinetis
Microcontroller families based on ARM®Cortex™-M4 and ARM®Cortex™-M0+ cores, providing the
common touch sense decoding structures such as keypad, rotary, slider, analog slider, analog rotary, and
matrix. It is implemented in a software-layered architecture to enable easy integration into the application
code and migration to other Freescale MCUs and customer customization.
1.2
Library features
The TSS library features include:
• Configurable number of electrodes from 1 to 64
• Configurable number of keypads, rotaries, sliders, analog sliders, analog rotaries, and matrixes
• Automatic electrode sensitivity calibration
• Three key detector methods (Basic, AFID and Noise)
• False detection prevention against external environment
• Electrode fault detection
• IIR and noise amplitude filters
• Shielding function
• Support for water-resistant touch systems
• Use of any standard MCU I/O as an electrode
• Touch Sense Input (TSI) module support
• TSI noise mode support
• One or more timer modules used with GPIO sampling algorithm
• Capability to wake from the MCU’s low power mode via the TSI module
• Three triggering modes (ALWAYS, SW, and AUTO when the TSI module is used)
• MISRA-compliant library encoding
• Easy application integration achieved by a modular software layer architecture
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
1-1
Touch Sensing Software Library Overview
1.3
Library architecture
The TSS library is implemented by using modular software layering shown in the Figure 1-1. It provides
a framework for Freescale touch sensing solutions and allows further integration of new modules for
application-specific needs. It is structured only for linking the user application with the modules used in
the application code. Additionally, it supports module use for any layer in the user application library.
Section 1.4, “System base modules” describes each module of the library.
Decoders
Rotary
Keypad
Analog Slider
Dec X
Slider
Analog Rotary
Matrix
System
Configuration
and
Management
Key Detector
GPIO
METHOD
System
Setup
Noise
AFID
Basic
TSI
METHOD
TSI Noise Mode
Timer
GPIO
Figure 1-1. TSS library architecture
Figure 1-2 is an example of the application project using the ARM Cortex-M4 version of library files. As
shown, the TSS folder contains all TSS library files.
Touch Sensing Software API Reference Manual, Rev. 8
1-2
Freescale Semiconductor
Touch Sensing Software Library Overview
Figure 1-2. Touch sensing software project
1.4
System base modules
This section provides an overview of the libary modules and the source and header files that constitute
these modules. The user configuration and API of each module are explained in Chapter 2, “TSS System
setup parameters.”
1.4.1
System setup module
Module description
The system setup module enables a compile time configuration interface. In this module, a user can
configure a set of parameters that require a pre-compile definition, such as, electrode numbers, MCU pins
for each electrode, measurement method used by each electrode, and number of controls.
Module files
This module contains the following files in open source:
•
•
•
TSS_SystemSetup.h — Edit the TSS_SystemSetup.h file to customize it for the application
particular electrode structure requirements.
TSS_SystemSetupVal.h — This file checks whether the application configuration, defined in the
TSS_SystemSetup.h file, is consistent. Do not edit the TSS_SystemSetupVal.h file.
TSS_SystemSetupData.c — This file creates the variables required for the TSS library and
dependent on the electrode structure of a particular application. Do not edit this file.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
1-3
Touch Sensing Software Library Overview
1.4.2
GPIO module
Module description
The GPIO module provides an interface between the upper layers of the library and the MCU GPIO pins.
This GPIO module is used by low-level routines for the default GPIO measurement method (detecting
timeout condition). It provides the following functionalities:
• Configure GPIO as input
• Configure GPIO as output
• Read GPIO value
• Set GPIO bit value (write a 1 to the GPIO bit on its specific data register)
• Clear GPIO bit value (write a 0 to the GPIO bit on its specific data register)
• Determine GPIO electrode port register address and mask of this pin
• Set GPIO pin output strength high or low
• Read GPIO pin output strength value
• Set GPIO pin slew rate high or low
• Read GPIO pin slew rate
Module files
The TSS_GPIO.h file implements the GPIO module. It defines macros to configure and access the MCU
I/O pin values, pin output strength, and slew rate settings. The upper layer uses these macros to manipulate
the MCU I/O pins.
1.4.3
Hardware timer module
Module description
The hardware timer module provides the interface between the upper layers and the hardware timer
specified at compile time. This timer module is used by low-level routines for the default GPIO method to
detect a timeout condition.
This module covers the following functions:
• Timer configuration
— Enable and disable interrupt
— Set prescaler
— Set and read timer module
• Timer start
• Timer stop
• Timer reset
• Set timer limit
• Read timer count
• Read 8 bits (low and high) of a timer count
Touch Sensing Software API Reference Manual, Rev. 8
1-4
Freescale Semiconductor
Touch Sensing Software Library Overview
•
•
•
Read 16 bits of a timer count
Hardware timer interrupt vector number assignment
TPM, FTM, and MTIM8 timer modules are supported
Module files
The TSS_Timer.h file implements macros in the source code, which are required to access the timer
hardware. The hardware timer interrupt service routine is implemented in the TSS_Sensor.c file.
1.5
Signal sensing modules
This section provides an overview of the low-level capacitance measurement modules and the source and
header files that constitute these modules.
1.5.1
GPIO low level sensor method
Method description
The GPIO low level sensing method measures the capacitance by using the GPIO capacitive touch sensing
method described in the Touch Sensing User Guide. This method is located in source code and provides
the following functions:
• Configuration of all electrodes to a default state. The default state is output-high to achieve lower
power consumption with external pull-up resistors.
• Initialization of the GPIO sensor method
• Capacitance measurement of a specific electrode using GPIO method
• Hardware timer interrupt handling
• Driving an electrode pin as low-output state if a timer charge timeout is detected (probably
electrode shorted to the ground)
• Noise amplitude filter function
To improve noise immunity and increase system sensitivity, the electrode sampling function can integrate
several subsequent electrode sampling values.
The HCS08 and ColdFire V1 version of the TSS library automatically allocate the
TSS_HWTimerIsr(void) interrupt service routine for the appropriate interrupt vector. The ColdFire+,
ARM Cortex-M0, and ARM Cortex-M4 version of the TSS library require manual allocation of the
interrupt service routine.
Method files
The TSS_SensorGPIO.c, TSS_SensorGPIO_def.h, and TSS_SensorGPIO.h files implement the GPIO
low level sensor method. This method uses the GPIO and the timer modules.
1.5.2
TSI low level sensor method
Method description
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
1-5
Touch Sensing Software Library Overview
The TSI low level sensor method uses the TSI hardware (HW) peripheral module. Each TSI pin
implements the capacitive measurement of an electrode having individual programmable detection
thresholds and result registers. The TSI module can be functional in several low-power modes and it can
be used to wake the CPU when a touch-event or a proximity-event is detected. The TSI method provides
an interface between the upper layers and the hardware. This module has the following functions:
• TSI HW module initialization
• TSI HW module autocalibration
• MCU wakes from low power mode by a touch detection
• Triggering in all available modes (ALWAYS, software (SW), and AUTO)
• Obtaining measured values
The HCS08 and ColdFire V1 version of the TSS library automatically allocate TSS_TSIxIsr(void)
interrupt service routine in the appropriate interrupt vector. The ColdFire+, ARM Cortex-M0+, and ARM
Cortex-M4 version of the TSS library requires manual allocation of the interrupt service routine.
Method files
The files TSS_SensorTSI.c, TSS_SensorTSI.h and TSS_SensorTSI_def.h implement the TSI sensing
method.
1.5.3
TSI Lite low level sensor method
Method Description
The TSI Lite Low-Level Sensor method is a simplified algorithm for the second generation of the Touch
Sensing Input (TSI) HW peripheral module. Unlike the “full” TSI method and ARM Cortex-M0+ version
of TSI Lite, the HCS08 version does not support waking the device from the low power mode. The TSI
method provides an interface between the upper layers and the hardware. This module has the following
functions:
• TSI HW module initialization
• TSI HW module autocalibration
• MCU wakes from low power mode by a touch detection on ARM Cortex-M0 version of TSI Lite
• Triggering in all available modes (ALWAYS, SW, and AUTO with external RTC, or LPTMR
trigger source)
• Starting the capacitance measurement on the pin
• Starting the noise measurement on TSI modules supporting noise mode (Kinetis L ARM
Cortex-M0+ family)
• Obtaining measured values
The HCS08 version of the TSS library automatically allocates TSS_TSIxIsr(void) interrupt service routine
in the appropriate interrupt vector. The ARM Cortex-M0 version of the TSS library requires manual
allocation of the interrupt service routine.
Method Files
Touch Sensing Software API Reference Manual, Rev. 8
1-6
Freescale Semiconductor
Touch Sensing Software Library Overview
The files TSS_SensorTSIL.c, TSS_SensorTSIL_def.h and TSS_SensorTSIL.h implement the TSI Lite
method.
1.6
Key detector modules
The key detector modules determine which electrodes are pressed or released based on the values obtained
by the capacitive sensing layer.
The key detector modules also detect, report, and act on fault conditions during the scanning process. The
two main fault conditions are electrode short-circuit to supplying voltage or grounding. The same
conditions can be caused by a small capacitance (equal to a short circuit to supply voltage) or by a large
capacitance (equals to a short circuit to ground).
The main output of these modules is the indication of a finger presence or an absence in each of the active
electrodes.
The current version of TSS provides these key detector methods:
• Basic key detector
• AFID key detector
• Noise key detector
1.6.1
Basic key detector module
Module description
Module description implements algorithms for identification of touched and released electrodes by
obtaining a baseline value (which is the "DC" value of the capacitance when a finger is not present) and
comparing it to the immediate capacitance value. A user can manually select this key detector in the TSS
configuration.
The baseline is obtained by a low pass IIR-based filter which removes slow environment changes that
could cause a false electrode press detection, such as, air humidity, temperature, and other external
variables. A de-bounce function is also implemented in this module to eliminate false detections caused
by instantaneous noise.
The shielding functionality is also processed in the module. The shielding feature uses a shielding
electrode, which measures the overall environment noise, to compensate for a signal drift on an electrode.
It eliminates low frequency noise modulated on the capacitance signal and protects the guarded system
from detecting false touches caused by water drops.
The key detector provides an automatic sensitivity calibration function. The function periodically adjusts
the level of electrode sensitivity, which is calculated according to the estimated noise level and
touch-tracking information. Although the sensitivity no longer has to be set manually, the settings are still
available for more precise tuning.
Main functions of the basic key detector module:
• Active electrodes detection pressed or not pressed
• Electrode detection debouncing
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
1-7
Touch Sensing Software Library Overview
•
•
•
•
•
•
•
Baseline generation
IIR filtering of current capacitance signal
Shielding
Proximity detection
Sensitivity Autocalibration
Electrode status reporting
Fault reporting
Module files
The key detector module is implemented in the object code integrated inside the TSS_S08.lib,
TSS_CFV1.a, TSS_KXX_M4.a/.lib, TSS_KXX_M4_FPU.a, and TSS_KXX_M0.a/.lib library files.
For more information regarding the electrode touch detection method, see the Touch Sensing User Guide.
1.6.2
AFID key detector module
Module description
The AFID (Advanced Filtering and Integrating Detection) key detector operates by using two IIR filters
with different depths (one short/fast, the other long/slow) and, then, integrating the difference between the
two filtered signals. Although this algorithm is more immune to noise, it is not compatible with other
noise-cancellation techniques such as shielding. The AFID key detector can be manually selected in the
TSS configuration.
The key detector also provides an automatic-sensitivity calibration. The calibration periodically adjusts the
level of electrode sensitivity, which is calculated according to touch-tracking information. Although the
sensitivity no longer has to be manually set, the settings are still available for more precise tuning.
The standard baseline, which is set according to the low pass IIR filter, is also calculated for analog
decoders and proximity function. A de-bounce function is implemented in this module to eliminate false
detections caused by instantaneous noise.
Main functions of the AFID key detector module:
• Two filters with integration for touch detection
• Electrode detection debouncing
• Baseline generation
• IIR filtering of current capacitance signal
• Proximity detection
• Sensitivity autocalibration
• Electrode status reporting
• Fault reporting
Module files
The key detector module is implemented in the object code integrated inside the TSS_S08.lib,
TSS_CFV1.a, TSS_KXX_M4.a/.lib, TSS_KXX_M4_FPU.a, and TSS_KXX_M0.a/.lib library files.
Touch Sensing Software API Reference Manual, Rev. 8
1-8
Freescale Semiconductor
Touch Sensing Software Library Overview
For more information regarding the electrode touch detection method, see the Touch Sensing User Guide.
1.6.3
Noise key detector module
Module description
This key detector processes noise signals only from the TSI module which supports the noise mode. This
feature is currently supported by TSI modules in Kinetis L ARM Cortex-M0+ family. The noise mode
feature is an alternative hardware measurement method intended for touch detection in an extremely noisy
environment.
The noise key detector cannot be selected as a standalone key detector. Instead, it is intended to be a
supplement for either Basic or AFID key detectors. The measurement and the touch detection are executed
automatically at a defined rate. The key detector provides only the initial sensitivity calibration function.
The sensitivity is not updated after the initial calibration.
The algorithm provides the touch information only and is not compatible with analog decoders, low power,
shielding, or proximity features. A de-bounce function is implemented in this module to eliminate false
detections caused by instantaneous noise.
Main functions of the noise key detector module:
• Switching between capacitance mode and noise mode, and measurement scheduling
• Electrode detection debouncing
• IIR filtering of a current noise signal
• Initial sensitivity calibration
• Fault reporting
Module files
The key detector module is implemented in the object code integrated inside the TSS_S08.lib,
TSS_CFV1.a, TSS_KXX_M4.a/.lib, TSS_KXX_M4_FPU.a, and TSS_KXX_M0.a/.lib library files.
For more information regarding the electrode touch detection method, see the Touch Sensing User Guide.
1.7
Decoder module
Module Description
Decoders provide the highest level of abstraction in the library. In this layer, the information regarding
touched and untouched electrodes is interpreted and shows the status of a control in a behavioral way.
Additional functionalities can be provided by the decoders, such as FIFOs. Note that the decoder-related
code exists only once in memory, which implies that, despite the number of rotary controls in the system,
only one rotary decoder resides in the memory. Decoders can be described as classes of an object-oriented
language where each control has a decoder associated with it. Therefore, the control becomes an instance
of the decoder (an object). However, not all decoders are necessarily instantiated in every system.
Decoder types supported by the library:
• Rotary
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
1-9
Touch Sensing Software Library Overview
•
•
•
•
•
Slider
Keypad
Analog rotary
Analog slider
Matrix
Module Files
The decoder module is implemented in the object code integrated in the TSS_S08.lib, TSS_CFV1.a,
TSS_KXX_M4.a/.lib, TSS_KXX_M4_FPU.a, and TSS_KXX_M0.a/.lib library files. For more
information about the Decoders functionality, see the Touch Sensing User Guide.
1.8
System configuration and management module
Module description
This module implements the configuration and management functions required to integrate the library in
the user application. The module contains the following functions:
• TSS_Init()— This function initializes the TSS library.
• TSS_Task()— The function must be called periodically by the user application to provide the CPU
time to the TSS library. All electrodes are processed during a single execution of this function, but
the measured data are evaluated after at least two executions. The process status is reported by the
return value.
• TSS_TaskSeq()— This function is an alternative to the TSS_Task() function. It must be called
periodically by the user application to provide the CPU time to the TSS library. One electrode is
processed in one function execution. When the function is executed periodically, it processes all
electrodes and decoders. The process status is reported by the return value.
• TSS_SetSystemConfig()— Provides configuring the TSS library during run-time.
• TSS_GetSystemConfig()— Provides reading of the TSS library registers during run-time.
If this module is enabled, it can perform integrity verification of the TSS RAM variables by executing a
Checksum check. The verification is embedded in all functions provided by this module.
Module files
The system configuration and management module is implemented in the object code integrated in the
TSS_S08.lib, TSS_CFV1.a, TSS_KXX_M4.a/.lib, TSS_KXX_M4_FPU.a, and TSS_KXX_M0.a/.lib
library files.
The TSS_API.h file provides headers and macros required to integrate functions and variables defined in
the library files.
Touch Sensing Software API Reference Manual, Rev. 8
1-10
Freescale Semiconductor
TSS System setup parameters
Chapter 2
TSS System setup parameters
Table 2-1 provides a summary of the TSS static configuration options available in the TSS_SystemSetup.h
file. For more information regarding the each configuration parameter, see the Touch Sensing User Guide.
Table 2-1. System setup parameters
Parameter
Range
Description
Used
Features Configuration
TSS_USE_KEYDETECTOR_VERSION
1 Basic
2 AFID
Defines main key detector Optional, default 1
method
TSS_USE_NOISE_MODE
0–1
Enables the noise key
detector as supplement of
main keydetector defined
by key detector version
parameter
Optional, default 0.
Available only if TSI
module supports noise
mode
TSS_USE_SIMPLE_LOW_LEVEL
0–1
Enables the Simple Low
Level routines option
Optional, default value
depends on availability
for the MCU
TSS_USE_DELTA_LOG
0–1
Enables the instant delta
feature
Optional, default 0
TSS_USE_SIGNAL_LOG
0–1
Enables the instant signal
feature
Optional, default 0
TSS_USE_INTEGRATION_DELTA_LOG
0-1
Enables the instant
integration signal from
AFID key detector
Optional, default 0
TSS_USE_NOISE_SIGNAL_LOG
0–1
Enables the instant noise
signal
Optional, default 0
TSS_USE_FREEMASTER_GUI
0–1
Enables FreeMASTER
GUI support
Optional, default 0
TSS_USE_CONTROL_PRIVATE_DATA
0–1
Enables Control Private
Data feature
Optional, default 0
TSS_USE_AUTO_SENS_CALIBRATION
0–1
Enables automatic
sensitivity calibration
Optional, default 0
TSS_USE_AUTO_SENS_CALIB_INIT_DURATION
0–255
Sets duration of an
automatic sensitivity
calibration initialization
Optional, default 100
TSS_USE_AUTO_SENS_CALIB_LOW_LIMIT
0–1
Enables automatic
sensitivity low limit
Optional, default 0
TSS_USE_BASELINE_INIT_DURATION
0–255
Sets duration of a baseline Optional, default 0
initialization
TSS_USE_LOWPOWER_THRESHOLD_BASELINE
0-1
Enables to use dc-tracker Optional, default 0
baseline for calculation of
low power wake-up
threshold
Touch Sensing Software API Reference Manual, Rev.8
Freescale Semiconductor
2-1
TSS System setup parameters
Table 2-1. System setup parameters (continued)
Parameter
Range
Description
Used
TSS_USE_LOWPOWER_CALIBRATION
0-1
Optional, default 0
Enables workaround for
low power errata on TSI
modules in Kinetis silicon
versions 2 and 3
TSS_USE_AFID_FAST_FILTER_RATIO
4, 5, 6, 7, 8, 9, 10, 15,
20, 25, 30, 35, 40, 45,
50, 55, 60, 65, 70, 75,
80, 85, 90, 95, 100, 110,
120, 130, 140, 150,
160, 170, 180, 190,
200, 220, 240, 260,
280, 300, 350, 400,
500, 600, 700, 800,
900, 1000
Defines weight of the fast Optional, default 50
filter in AFID keydetector
in the form of ratio
fsample/fcutoff
TSS_USE_AFID_SLOW_FILTER_RATIO
AFID Fast Filter Ratio 4, 5, 6, 7, 8, 9, 10, 15,
20, 25, 30, 35, 40, 45,
50, 55, 60, 65, 70, 75,
80, 85, 90, 95, 100, 110,
120, 130, 140, 150,
160, 170, 180, 190,
200, 220, 240, 260,
280, 300, 350, 400,
500, 600, 700, 800,
900, 1000
Defines weight of the slow Optional, default 200
filter in AFID keydetector
in the form of ratio
fsample/fcutoff
Signal Control Options
TSS_USE_GPIO_STRENGTH
0–1
Enables strength on usable Optional, default 0.
pins for GPIO method.
Used only for the GPIO
method.
TSS_USE_GPIO_SLEW_RATE
0–1
Enables slew rate on
usable pins for GPIO
method.
Optional, default 0.
Used only for the GPIO
method.
TSS_USE_IIR_FILTER
0–1
Enables IIR filter
Optional, default 0
TSS_USE_NOISE_AMPLITUDE_FILTER
0–1
Enables noise amplitude
filter for GPIO method.
Optional, default 0.
Used only for the GPIO
method.
TSS_USE_SIGNAL_SHIELDING
0–1
Enables Signal Shielding
function
Optional, default 0
TSS_USE_SIGNAL_DIVIDER
0–1
Enables signal divider
Optional, default 0
TSS_USE_SIGNAL_MULTIPLIER
0–1
Enables signal multiplier
Optional, default 0
TSS_USE_DEFAULT_ELECTRODE_LEVEL_LOW
0–1
Sets low electrode level
Optional, default 0.
between measurements for Used only for the GPIO
GPIO method.
method.
Callbacks Definition
Touch Sensing Software API Reference Manual, Rev.8
2-2
Freescale Semiconductor
TSS System setup parameters
Table 2-1. System setup parameters (continued)
Parameter
Range
Description
Used
TSS_ONFAULT_CALLBACK
Any valid function
name. This callback
function must be
provided by the user.
This is the name of a
function that matches the
OnFault callback
prototype
Optional. If the macro is
not defined, the callback
is disabled.
TSS_ONINIT_CALLBACK
Any valid function
name. This callback
function must be
provided by the user.
This is the name of a
function that matches the
OnInit callback prototype
Optional. If macro is not
defined, ‘TSS_fOnInit’
name is used.
TSS_ONPROXIMITY_CALLBACK
Any valid function
name. This callback
function must be
provided by the user.
This is the name of a
function that matches the
OnProximity callback
prototype
Optional. If macro is not
defined, the proximity
function is disabled.
Definition of Function Control Source
TSS_USE_AUTOTRIGGER_SOURCE
RTC, LPTMR, TSI,
TSI0, TSI1, UNUSED
Name of the hardware
device used for
management of TSS
AUTO triggering
Optional, default
UNUSED
TSS_USE_LOWPOWER_CONTROL_SOURCE
TSI, TSI0, TSI1,
UNUSED
Name of hardware device
used for management of
the Low Power mode
Optional, default
UNUSED
Code Size Reduction Options
TSS_USE_DATA_CORRUPTION_CHECK
0–1
Enables compilation of
Optional, default 1
TSS RAM data
consistency check function
TSS_USE_TRIGGER_FUNCTION
0-1
Enables compilation of
Triggering function
Optional, default 0
TSS_USE_STUCK_KEY
0-1
Enables compilation of
Stuck Key detection
function
Optional, default 1
TSS_USE_NEGATIVE_BASELINE_DROP
0-1
Enables compilation of
Negative Baseline Drop
function
Optional, default 1
TSS_USE_AUTO_HW_RECALIBRATION
0-1
Enables automatic
hardware recalibration
Optional, default 1
Enables diagnostic
messages during
compilation
Optional, default 0
Sets the number of
electrodes to be used by
the application
Always
Debug Options
TSS_ENABLE_DIAGNOSTIC_MESSAGES
0–1
Electrodes Configuration
TSS_N_ELECTRODES
1–64
Touch Sensing Software API Reference Manual, Rev.8
Freescale Semiconductor
2-3
TSS System setup parameters
Table 2-1. System setup parameters (continued)
Parameter
Range
Description
Used
TSS_Ex_P
Any valid GPIO port on Configures the MCU
the MCU
GPIO port to be used for
each electrode
Always, except TSI
module electrode
TSS_Ex_B
Any valid GPIO pin on Configures the MCU
the MCU
GPIO pin to be used for
each electrode
Always, except TSI
module electrode
TSS_Ex_TYPE
GPIO, TSInCHm
Determines the
measurement method for
an electrode
Optional, default GPIO
TSS_Ex_NOISE_AMPLITUDE_FILTER_SIZE
2–255
Determines the size of the Optional, default 255
noise amplitude filter for
an electrode
TSS_Ex_SHIELD_ELECTRODE
0-63
Determines the number of Optional, if defined then
shielding electrode
the electrode is shielded.
assigned to this electrode
TSS_Ex_SIGNAL_DIVIDER
0-255
Determines the value of
signal divider for this
electrode
Optional, if defined or
non zero then the
electrode uses divider.
TSS_Ex_SIGNAL_MULTIPLIER
0-255
Determines the value of
signal multiplier for this
electrode
Optional, if defined or
non zero then the
electrode uses
multiplier.
Always
Controls Configuration
TSS_N_CONTROLS
0-16
Sets the number of
controls to be used by the
application
TSS_Cn_TYPE
TSS_CT_KEYPAD
TSS_CT_SLIDER
TSS_CT_ROTARY
TSS_CT_ASLIDER
TSS_CT_AROTARY
TSS_CT_MATRIX
Determines the type of the Always, if Controls > 0
control
TSS_Cn_INPUTS
Any valid array with
number of items:
1-16 for keypad
2-16 for slider
3-16 for rotary
2-16 for analog slider
3-16 for analog rotary
3-16 for matrix
Determines the electrodes
that composes the control
TSS_Cn_INPUTS_NUM_X
2-14
Determines the amount of Always, if matrix
electrodes that compose
control is used
the matrix control on X
axis
Always, if Controls > 0
Touch Sensing Software API Reference Manual, Rev.8
2-4
Freescale Semiconductor
TSS System setup parameters
Table 2-1. System setup parameters (continued)
Parameter
Range
Description
Used
TSS_Cn_STRUCTURE
Any valid name
selected by the user
Indicates the name of the Always, if Controls > 0
configuration and status
structure of the control. It
is used to create the
configuration and status
structure in a different file.
This structure is not
declared by users.
TSS_Cn_CALLBACK
Any valid function
name. This callback
function is created by
the user.
This is the name of a valid Always, if Controls > 0
function that matches the
callback prototype
TSS_Cn_KEYS
Any valid array defined
by an user with
maximum length 65536
items
Defines the groups of
electrodes for group
decoder. Valid only for
keypad control.
Optional.
Peripheral Specific Configuration
TSS_HW_TIMER
TPMx, FTMx, MTIMx Name of hardware timer
used for GPIO method.
Always for GPIO
method.
TSS_SENSOR_PRESCALER
NA, depends on used
timer
Prescaler for all used
timers
Optional, default 2. If
the GPIO method is
used.
TSS_SENSOR_TIMEOUT
128-65535, except
HCS08 where
128-511(2047 if IIR
filter is disabled) is
used
Defines timeout for all
used timers
Optional, default 511. If
the GPIO method is
used.
TSS_TSI_RESOLUTION
1–16 bits
Defines resolution of TSI
in bits for autocalibration
Optional, default 11.
If the TSI module is
used.
TSS_TSI_EXTCHRG_LOW_LIMIT
0 — TSI module
EXTCHRG range
Defines low limit of
EXTCHRG for TSI
autocalibration
Optional, default 0.
If the TSI module is
used.
TSS_TSI_EXTCHRG_HIGH_LIMIT
EXTCHRG low limit
— TSI module
EXTCHRG range
Defines high limit of
EXTCHRG for TSI
autocalibration
Optional, default 7.
If the TSI module is
used.
TSS_TSI_PS_LOW_LIMIT
0–7
Defines low limit of PS for Optional, default 0.
TSI autocalibration
If the TSI module is
used.
TSS_TSI_PS_HIGH_LIMIT
PS low limit – 7
Defines high limit of PS
for TSI autocalibration
Optional, default 7. If
the TSI module is used.
TSS_TSI_AMCLKS
0 Bus Clock
1 MCGIRCLK
2 OSCERCLK
3 Not valid
Defines TSI Active mode
Clock Source
Optional, default 0. If
the TSI module supports
AMCLKS function. If
the TSI module is used.
Touch Sensing Software API Reference Manual, Rev.8
Freescale Semiconductor
2-5
TSS System setup parameters
Table 2-1. System setup parameters (continued)
Parameter
Range
Description
Used
TSS_TSI_AMCLKDIV
0 divider set to 1
1 divider set to 2048
Defines TSI Active Mode
Clock Divider
Optional, default 1. if
the TSI module supports
AMCLKDIV register. If
the TSI module is used.
TSS_TSI_AMPSC
0 divided by 1
1 divided by 2
2 divided by 4
3 divided by 8
4 divided by 16
5 divided by 32
6 divided by 64
7 divided by 128
Defines TSI Active Mode
Prescaler
Optional, default 0. If
TSI module supports
AMPSC register. If the
TSI module is used.
TSS_TSI_LPCLKS
0 LPOCLK
1 VLPOSCCLK
Defines TSI Low Power
Mode Clock Source
Optional, default 0. If
TSI module supports
LPCLKS register. If the
TSI module is used.
TSS_TSI_DVOLT
NA, depends on used
TSI module
Defines TSI Delta Voltage Optional, with default
value
maximum value. If TSI
module provides
DVOLT register.
TSS_TSI_SMOD
0-255
Defines TSI Scan Modulo Optional, default 0. If
TSI module provides
SMOD register.
TSS_TSI_LPSCNITV
0 for 1 ms
1 for 5 ms
2 for 10 ms
3 for 15 ms
4 for 20 ms
5 for 30 ms
6 for 40 ms
7 for 50 ms
8 for 75 ms
9 for 100 ms
10 for 125 ms
11for 150 ms
12 for 200 ms
13 for 300 ms
14 for 400 ms
15 for 500 ms
Defines TSI Low Power
Mode Scan Interval
Optional, default 0. If
TSI module provides
LPSCNITV register.
TSS_TSI_NOISE_PS
0 divided by 1
1 divided by 2
2 divided by 4
3 divided by 8
4 divided by 16
5 divided by 32
6 divided by 64
7 divided by 128
Defines External
Oscillator Prescaler for
TSI noise mode
Optional, default 3. If
TSI module provides PS
register and noise mode.
Touch Sensing Software API Reference Manual, Rev.8
2-6
Freescale Semiconductor
TSS System setup parameters
Table 2-1. System setup parameters (continued)
Parameter
Range
Description
Used
TSS_TSI_NOISE_FILTER
0 for 3 bits
1 for 2 bits
2 for 1 bit
3 for disabled
Defines Number Of Filter
Bits for TSI noise mode
Optional, default 0. If
TSI module provides
EXTCHRG register and
noise mode.
TSS_TSI_NOISE_RS
0 for 32 kOhm
1 for 187 kOhm
Defines Series Resistance
for TSI noise mode
Optional, default 0. If
TSI module provides
EXTCHRG register and
noise mode.
TSS_TSI_NOISE_REFCHRG
0 for 500 nA
1 for 1 ?A
2 for 2 ?A
3 for 4 ?A
4 for 8 ?A
5 for 16 ?A
6 for 32 ?A
7 for 64 ?A
Defines Reference
Oscillator Charge Current
for TSI noise mode
Optional, default 0. If
TSI module provides
REFCHRG register and
noise mode.
Proximity Specific Configuration
TSS_SENSOR_PROX_PRESCALER
NA, depends on used
timer
Prescaler for all used
timers in proximity mode
Optional, default 2. If
the GPIO method is
used.
TSS_SENSOR_PROX_TIMEOUT
128-65535, except
HCS08 where
128-511(2047 if IIR
filter is disabled) is
used
Defines timeout for all
used timers in proximity
mode
Optional, default 511. If
the GPIO method is
used.
TSS_TSI_PROX_RESOLUTION
1–16 bits
Defines resolution of TSI
in bits for autocalibration
in proximity mode
Optional, default 11.
If the TSI module is
used.
TSS_TSI_PROX_EXTCHRG_LOW_LIMIT
0 — TSI module
EXTCHRG range
Defines low limit of
EXTCHRG for TSI
autocalibration in
proximity mode
Optional, default 0.
If the TSI module is
used.
TSS_TSI_PROX_EXTCHRG_HIGH_LIMIT
0 — TSI module
EXTCHRG range
Defines high limit of
EXTCHRG for TSI
autocalibration in
proximity mode
Optional, default 7.
If theTSI module is
used.
TSS_TSI_PROX_PS_LOW_LIMIT
0–7
Defines low limit of PS for Optional, default 0.
TSI autocalibration in
If the TSI module is
proximity mode
used.
TSS_TSI_PROX_PS_HIGH_LIMIT
0– 7
Defines high limit of PS
for TSI autocalibration in
proximity mode
Optional, default 7.
If the TSI module is
used.
Touch Sensing Software API Reference Manual, Rev.8
Freescale Semiconductor
2-7
TSS System setup parameters
Touch Sensing Software API Reference Manual, Rev.8
2-8
Freescale Semiconductor
Application Interface
Chapter 3
Application Interface
This section describes the TSS library initialization task function and its usage. It also describes the
configuration and status structure of the library and how to manipulate it by using the
TSS_SetSystemConfig function.
Each control in the application has a configuration and a status structure assigned to it. Control parameters
depend on the control type. This section describes the following:
• Configuration and status structure for each control type
• How to manipulate configuration and status structures by using the control configuration function
• Callback functions for each control type
The TSS_API.h file contains the function prototypes and variables declaration of the application interface.
This file must be included in the applications source code that manages the TSS library.
3.1
TSS initialization function
This function initializes the data structures and low level routines of the library with default values. The
OnInit callback is executed during the function call. The MCU and peripherals clock must be configured
before calling the TSS_Init()function or before the OnInit callback.
Function prototype
The TSS initialization function has the following prototype defined in the TSS_API.h file:
uint8_t TSS_Init(void);
Input parameters
None
Return value
The return value is an unsigned byte with the following possible return values defined in the file
TSS_StatusCodes.h:
Return Value
3.2
Description
TSS_STATUS_OK
TSS initialization has successfully finished
TSS_STATUS_RECALIBRATION_FAULT
The fault occurred during the recalibration of low level hardware
TSS task function
The application calls this function periodically to provide the CPU time for the TSS library. The
TSS_Task() routine handles measurement initialization by acquiring the sample and processing the
capacitance signal values. Depending on the measurement method selected for given electrodes, the
physical sampling is either performed by the Hardware module (for example TSI) or directly by the
TSS_Task() routine. This influences the duration of the TSS_Task() execution and the number of times
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-1
Application Interface
it must be called before one full set of samples is taken and processed. Processing status is reported by the
TSS_Task() return value.
Function prototype
The TSS task function has the following prototype defined in the TSS_API.h file:
uint8_t TSS_Task(void);
Input parameters
None
Return value
The return value is an unsigned byte with the following possible return values, as defined in the
file TSS_StatusCodes.h:
Return Value
Description
TSS_STATUS_OK
TSS task finished the measurement of all electrodes and has
evaluated the values
TSS_STATUS_PROCESSING
Measurement of electrodes in progress or the TSS task has not
finished the evaluation
TSS_STATUS_BUSY
TSS_Task() was executed during the TSS register changes
performed by TSS_SetSystemConfig().
NOTE
It is not recommended to perform any TSS register changes during electrode
processing until the TSS_Task() returns TSS_STATUS_OK.
3.3
TSS task sequenced function
The function TSS_TaskSeq() is a more “atomic” alternative to TSS_Task(). The application calls the
TSS_TaskSeq()periodically to provide the CPU time to the TSS library. Only one electrode is processed
during a single call. Therefore, the execution takes less time and enables a smoother multitasking for other
processes which are running simultaneously with the TSS_Task(). The two-phase processing principle for
electrodes is the same as processing in the TSS_Task(). Because the function is periodically executed, it
processes all electrodes and decoders.
Function prototype
The TSS task sequenced function has the following prototype defined in the TSS_API.h file:
uint8_t TSS_TaskSeq(void);
Input parameters
None
Return value
The return value is an unsigned byte with the following possible return values defined in the file
TSS_StatusCodes.h:
Touch Sensing Software API Reference Manual, Rev. 8
3-2
Freescale Semiconductor
Application Interface
Return Value
Description
TSS_STATUS_OK
TSS sequenced task finished measurement of all electrodes and
evaluated the values
TSS_STATUS_PROCESSING
Measurement of electrodes is in progress or the TSS sequenced task
has not finished the evaluation
TSS_STATUS_BUSY
TSS_TaskSeq() was executed during the TSS register changes
performed by TSS_SetSystemConfig().
NOTE
It is not recommended to perform any TSS register changes during electrode
processing until the TSS_TaskSeq() returns TSS_STATUS_OK.
3.4
TSS Library Configuration Save and Restore Functions
The TSS library provides functions for saving and restoring the TSS configuration. The purpose of these
functions is to recover the TSS configuration after low power wake up which causes an MCU to reset.
There are several functions available for saving and restoring the TSS configuration. The following
chapters describe each function.
3.4.1
Save and restore electrode data
The electrode data consists of the electrode sensitivity and the baseline values in the basic keydetector. The
data consist of immediate filter values, electrode sensitivity, and baseline values in the AFID keydetector.
To save the data of a single electrode, the TSS_StoreElectrodeData function must be called at any time.
The function is declared in the TSS_API.h file.
Function prototype
int16_t TSS_StoreElectrodeData(uint8_t u8Electrode, void *pDestAddr, uint16_t u16Length)
Input parameters
Type
Name
Valid Range and Values
Description
uint8_t
u8Electrode
Any of the electrode number within maximum Parameter defines electrode number which configuration
used number of electrodes.
will be saved
void*
pDestAddr
Valid address of the destination memory area
Pointer to begin of memory area where data will be saved
Valid number with unsigned integer range
Size of available memory area in bytes
uint16_t u16Length
Return value
The return value is either a signed integer value defining number of saved bytes, or return error status
values defined in the file TSS_StatusCodes.h:
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-3
Application Interface
Return Value
Description
Any valid unsigned number
If return value is higher than u16Length parameter, more
memory is needed and the operation is unsuccessful.
Otherwise, the return value defines a number of saved bytes
and the operation is successful.
TSS_ERROR_DATASYS_OUT_OF_RANGE
An electrode number is higher than the maximum number
of electrodes.
TSS_ERROR_DATASYS_MEM_NULL
Pointer address is not valid.
To restore the data of a single electrode, the TSS_LoadElectrodeData function must be called. The function
can be called only during TSS initialization time, between TSS_Init call and the first TSS_Task call. The
function is declared in the TSS_API.h file.
Function prototype
int16_t TSS_LoadElectrodeData(uint8_t u8Electrode, void *pSourceAddr)
Input parameters
Type
Name
Valid Range and Values
Description
uint8_t
u8Electrode
Any electrode number within maximum used
number of electrodes
Parameter defines an electrode number which restores the
configuration.
void*
pSourceAddr
Valid address of the source memory area
A pointer to the beginning of the memory area where the
source data is stored.
Return value
The return value is either a signed integer value defining a number of saved bytes, or return error status
values defined in the file TSS_StatusCodes.h:
Return Value
Description
Any valid unsigned number
Return value defines a number of saved bytes and the
operation is successful.
TSS_ERROR_DATASYS_OUT_OF_RANGE
Electrode number is higher than the maximum number of
electrodes.
TSS_ERROR_DATASYS_MEM_NULL
Pointer address is not valid.
TSS_ERROR_DATASYS_READ_ONLY
TSS is not in the initialization phase between TSS_Init call
and the first TSS_Task call.
3.4.2
Save and restore module data
Module data is a configuration of all used low-level measurement modules. If a TSI module is used, the
data includes a configuration of the TSI autocalibration. The GPIO method does not provide this data.
To save the used module data, the TSS_StoreModulesData function must be called. The function can be
called at any time and is declared in the TSS_API.h file.
Touch Sensing Software API Reference Manual, Rev. 8
3-4
Freescale Semiconductor
Application Interface
Function prototype
int16_t TSS_StoreModulesData(void *pDestAddr, uint16_t u16Length)
Input parameters
Type
void*
Name
pDestAddr
uint16_t u16Length
Valid Range and Values
Description
Valid address of the destination memory area
A pointer to the beginning of the memory area where data
is saved.
Valid number with unsigned integer range
A size of the available memory area in bytes.
Return value
The return value is either a signed integer value defining a number of saved bytes, or a possible return error
status value defined in the file TSS_StatusCodes.h:
Return Value
Description
Any valid unsigned number
If a return value is higher than the u16Length parameter,
more memory is needed and the operation is unsuccessful.
Otherwise, a return value defines a number of saved bytes
and operation is successful.
TSS_ERROR_DATASYS_MEM_NULL
A pointer address is not valid.
To restore the module data, the TSS_LoadModulesData function must be called. The function can be
called only during TSS initialization time, between TSS_Init call and the first TSS_Task call and is
declared in the TSS_API.h file.
Function prototype
int16_t TSS_LoadModulesData(void *pSourceAddr)
Input parameters
Type
void*
Name
pSourceAddr
Valid Range and Values
Valid address of the source memory area
Description
Pointer to begin of memory area where are source data
stored
Return value
The return value is either a signed integer value defining a number of saved bytes, or return error status
values defined in the file TSS_StatusCodes.h:
Return Value
Description
Any valid unsigned number
A return value defines a number of saved bytes and the
operation is successful.
TSS_ERROR_DATASYS_MEM_NULL
A pointer address is not valid.
TSS_ERROR_DATASYS_READ_ONLY
TSS is not in the initialization phase between TSS_Init call
and the first TSS_Task call.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-5
Application Interface
3.4.3
Save and restore all system data
The system data consist of electrode and module data. The data is described in Section 3.4.1, “Save and
restore electrode data” and Section 3.4.2, “Save and restore module data”.
To save the system data, the TSS_StoreAllSystemData function must be called. The function can be called
at any time and is declared in the TSS_API.h file.
Function prototype
int16_t TSS_StoreAllSystemData(void *pDestAddr, uint16_t u16Length)
Input parameters
Type
void*
Name
pDestAddr
uint16_t u16Length
Valid Range and Values
Description
Valid address of the destination memory area
A pointer to the beginning of the memory area where data
is saved.
Valid number with unsigned integer range
The size of available memory area in bytes.
Return value
The return value is either a signed integer value defining number of saved bytes, or return error status
values defined in the file TSS_StatusCodes.h:
Return Value
Description
Any valid unsigned number
If the return value is higher than the u16Length parameter,
more memory is needed and operation is unsuccessful.
Otherwise, the return value defines a number of saved bytes
and operation is successful.
TSS_ERROR_DATASYS_MEM_NULL
A pointer address is not valid.
To restore the system data, the TSS_LoadAllSystemData function must be called. The function can be
called only during TSS initialization time, between TSS_Init call and the first TSS_Task call and is
declared in the TSS_API.h file.
Function prototype
int16_t TSS_LoadAllSystemData(void *pSourceAddr)
Input parameters
Type
void*
Name
pSourceAddr
Valid Range and Values
Valid address of the source memory area
Description
A pointer to the beginning of the memory area where
source data is stored.
Return value
The return value is either a signed integer value defining number of saved bytes, or return error status
values defined in the file TSS_StatusCodes.h:
Touch Sensing Software API Reference Manual, Rev. 8
3-6
Freescale Semiconductor
Application Interface
Return Value
Description
Any valid unsigned number
The return value defines a number of saved bytes and the
operation is successful.
TSS_ERROR_DATASYS_CHECKSUM
Data in the source memory area is corrupted.
TSS_ERROR_DATASYS_MEM_NULL
A pointer address is not valid.
TSS_ERROR_DATASYS_NOT_ENOUGH_DATA
Not enough data is provided in the source memory area.
TSS_ERROR_DATASYS_READ_ONLY
The TSS is not in an initialization phase between TSS_Init
call and the first TSS_Task call.
3.5
TSS Library Configuration and Status Registers
The TSS library Control and Status (C&S) registers constitute the main application interface to the TSS
library. The application may use the registers to customize the library operation and determine its status.
Although the C&S registers are located in RAM, they are read-only and declared as constant values. This
prevents a user from modifying status values or corrupting them with invalid configuration values.
3.5.1
Writing to the Configuration and Status Registers
The TSS_SetSystemConfig function is called to change values in the Configuration and Status registers.
If necessary, the function can reinitialize the low-level hardware. The function is declared in the
TSS_API.h file.
Function prototype
uint8_t TSS_SetSystemConfig(uint8_t u8Parameter, uint16_t u16Value)
Input parameters
Type
uint8_t
Name
u8Parameter
uint16_t u16Value
Valid Range and Values
Any of the parameter codes provided by the
configuration and status management
Description
Code indicating the parameter configured
Depends on the specific parameter configured The new desired value for the respective configuration
register
Return value
The return value is an unsigned byte with the following possible return values defined in the file
TSS_StatusCodes.h:
Return Value
Description
TSS_STATUS_OK
Configuration was done successfully
TSS_ERROR_CONFSYS_BUSY
TSS_SetSystemConfig() was executed during the electrode
measurement.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-7
Application Interface
Return Value
Description
TSS_ERROR_CONFSYS_ILLEGAL_PARAMETER
The configuration is not successful due to illegal parameter
number.
TSS_ERROR_CONFSYS_READ_ONLY_PARAMETER
The configuration is not successful because the user
attempted to modify a read-only parameter.
TSS_ERROR_CONFSYS_OUT_OF_RANGE
The configuration is not successful because the new value
is out of range.
TSS_ERROR_CONFSYS_LOWPOWER_SOURCE_NA
The configuration is not successful because the low-power
control source device is not selected.
TSS_ERROR_CONFSYS_INCORRECT_LOWPOWER_EL
The configuration is not successful because the selected
electrode does not belong to the low-power control source
device.
TSS_ERROR_CONFSYS_TRIGGER_SOURCE_NA
The configuration is not successful because the trigger
source device is not selected.
TSS_ERROR_CONFSYS_PROXIMITY_CALLBACK_NA
The configuration is not successful because the proximity
callback is not defined.
TSS_ERROR_CONFSYS_RECALIBRATION_FAULT
The configuration is not successful because the fault
occurred during the recalibration of the low level hardware.
TSS_ERROR_CONFSYS_SHIELD_NA
The configuration is not successful because the shielding
functionality is not enabled.
TSS_ERROR_CONFSYS_HWRECALIB_PENDING
The configuration is not successful because the hardware
recalibration is in progress.
TSS_ERROR_CONFSYS_MANRECALIB_PENDING
The configuration is not successful because the manual
recalibration is in progress.
TSS_ERROR_CONFSYS_DCTRACKER_RATE_ZERO
The configuration is not successful because dc tracker rate
register is set to zero value.
TSS_ERROR_CONFSYS_STUCKKEY_TIMEOUT_ZERO
The configuration is not successful because the stuckey
timeout register is set to zero value.
3.5.2
Reading the Configuration and Status registers
To read values from the Configuration and Status register, the application can either access the system
structures directly or it can use the TSS_GetSystemConfig function. The function is declared in the
TSS_API.h file.
Function prototype
uint16_t TSS_GetSystemConfig(uint8_t u8Parameter)
Input parameters
Type
uint8_t
Name
u8Parameter
Valid Range and Values
Any of the parameter codes provided by the
configuration and status management
Description
Code indicating the parameter configured
Return value
Touch Sensing Software API Reference Manual, Rev. 8
3-8
Freescale Semiconductor
Application Interface
The return value corresponds to an unsigned integer value of a register specified by the u8Parameter, or
error values defined in the file TSS_StatusCodes.h:
Return Value
Description
Any valid unsigned integer value
Value corresponds to an actual unsigned integer value of a
register specified by u8Parameter
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Read was not successful due to illegal parameter
TSS_ERROR_GETCONF_ILLEGAL_CONTROL_TYPE
Read was not successful due to illegal control type
In the TSS register structure, Configuration and Status registers of the library are divided into two types.
One set of registers is contained inside a structure, while the others are declared in global arrays. Register
structure is defined as follows.
typedef struct{
volatile
volatile
volatile
volatile
volatile
volatile
volatile
volatile
volatile
volatile
} TSS_CSSystem;
const
const
const
const
const
const
const
const
const
const
TSS_SYSTEM_FAULTS Faults;
TSS_SYSTEM_SYSCONF SystemConfig;
uint8_t NSamples;
uint8_t DCTrackerRate;
uint8_t SlowDCTrackerFactor;
uint8_t ResponseTime;
uint8_t StuckKeyTimeout;
uint8_t LowPowerElectrode;
uint8_t LowPowerElectrodeSensitivity;
TSS_SYSTEM_TRIGGER SystemTrigger;
//Note 1
//Note 2
//Note 3
NOTE
1. The TSS_SYSTEM_FAULTS type is an eight bit-field structure described in Section 3.5.4, “Faults
register"”
2. The TSS_SYSTEM_SYSCONF type is an 16 bit-field structure described in Section 3.5.5,
“System Configuration register"”
3. The TSS_SYSTEM_TRIGGER type is an eight bit-field structure described in Section 3.5.13,
“System Trigger register"”
The TSS library configuration and control structure instance is named as follows:
tss_CSSys
To read any variable inside this structure, use the standard C structure read statements. Access example of
the Fault register in C:
Temp = tss_CSSys.Faults;
To access to the electrode-specific most critical configuration registers quickly, the library defines the
following registers as global arrays.
•
•
•
•
const
const
const
const
uint8_t
uint8_t
uint8_t
uint8_t
tss_au8Sensitivity[TSS_N_ELECTRODES];
tss_au8ElectrodeEnablers[((TSS_N_ELECTRODES–1)/8)+1];
tss_au8ElectrodeStatus[((TSS_N_ELECTRODES–1)/8)+1];
tss_au8ElectrodeDCTrackerEnablers[((TSS_N_ELECTRODES-1)/8)+1];
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-9
Application Interface
To read any of these registers, use the standard C array read statements. Access an example of the
au8Sensitivity register in C:
Temp = tss_au8Sensitivity[ Electrode ];
Although the registers can be read directly as the part of the configuration structure or from global arrays,
they must be written to by using the TSS_SetSystemConfig() function. For more details, see Section 3.5.1,
“Writing to the Configuration and Status Registers".
3.5.3
Configuration and Status registers list
Table 3-1. Configuration and Status registers
Register
Number
Size [bytes]
Register Name
Section
Initial value
Brief Description
0x00
1
Faults
Section 3.5.4, “Faults 0x00
register"
RW — Shows the faults generated
by the system.
0x01
2
SystemConfig
Section 3.5.5,
“System
Configuration
register"
0x00
RW — Main configuration of the
TSS library.
0x02
1
NSamples
Section 3.5.6,
“Number of Samples
register"
0x08
RW — Determines the number of
samples scanned for a single
measurement.
0x03
1
DCTrackerRate
Section 3.5.7, “DC
0x64
Tracker Rate register"
RW — Determines how often the
baseline is updated for common
electrodes. This number represents
the number of calls to the TSS task
function required before dc tracker
execution.
0x04
1
SlowDCTrackerFactor
Section 3.5.8, “Slow
DC Tracker Factor
register”
0x64
RW — Determines how often the
baseline will be updated for
proximity and shielding electrodes.
This number is a multiplication
factor used with standard
DCTrackerRate register value .
0x05
1
ResponseTime
Section 3.5.9,
“Response Time
register"
0x04
RW — Configures the number of
TSS task calls necessary to
determine whether a key is pressed
or not.
0x06
1
StuckKeyTimeout
Section 3.5.10,
“Stuck-key Timeout
register"
0x00
RW — Configures the number of
TSS task calls necessary to detect a
stuck key.
0x07
1
LowPowerElectrode
Section 3.5.11, “Low
Power Electrode
register"
0x00
RW — Number of electrodes
scanned in low-power mode and
proximity mode.
0x08
1
LowPowerElectrodeSensitivi Section 3.5.12,
ty
“Low-Power
Electrode Sensitivity
register"
0x3F
RW — Sensitivity of an electrode
scanned in low power-mode and
proximity mode.
Touch Sensing Software API Reference Manual, Rev. 8
3-10
Freescale Semiconductor
Application Interface
Table 3-1. Configuration and Status registers (continued)
Register
Number
Size [bytes]
Register Name
Section
Initial value
Brief Description
0x09
1
SystemTrigger
Section 3.5.13,
“System Trigger
register"
0x01
RW — Configures TSS system
triggering modes.
0x0A
A = number
of elec.
Sensitivity
Section 3.5.14,
“Sensitivity
Configuration
register"
0x3F
RW — Each byte represents the
sensitivity for each electrode. This
value is the required difference
between any instant value and the
baseline to indicate a touch.
Section 3.5.15,
“Electrode enablers"
All electrodes
enabled (all
bytes in 0xFF)
RW — Each bit represents the
enabler of an electrode. If a bit is 0,
then the corresponding electrode is
not scanned.
0x0A + A + C = (number ElectrodeStatus
B
of elec. / 8) +
1
Section 3.5.16,
“Electrode status"
All electrodes in R — Each bit represents the current
0x00
status of an electrode. 1 is electrode
detected as touched, and 0 is
electrode detected as untouched.
0x0A + A + D = 2x
B+C
number of
electrodes
Section 3.5.17,
“Baseline register"
All electrodes in R (W - after TSS_Init() call) —
0
Each integer represents the
dc-tracker baseline for each
electrode.
0x0A + A
B = (number ElectrodeEnablers
of elec. / 8) +
1
Baseline
0x0A + A + E = (number DCTrackerEnablers
B + C + D/2 of elec. / 8) +
1
Section 3.5.18,
All electrodes
“Dc-Tracker enablers" enabled (all
bytes in 0xFF)
RW — Each bit represents the
dc-tracker enabler of an electrode.
If a bit is 0, then the baseline of the
corresponding electrode is not
updated by the dc-tracker.
0x0A + A + 1
B + C + D/2
+E
Section 3.5.18,
undetermined
“Dc-Tracker enablers"
R — This register contains the
checksum value to guarantee the
validity of the information
contained in C&S registers.
3.5.4
ConfigChecksum
Faults register
This register describes why an electrode cannot be read. Additionally, it describes other issues which may
have occured in the system. When this kind of error occurs, the library stores the information about the
causes of the error. The HCS08 version of the library allows enabling a software interrupt to read the Faults
register and determine what caused the error. All HCS08, ColdFire V1, Coldfire+ , ARM Cortex-M0+, and
ARM Cortex-M4 version support using the OnFault callback to handle the error as indicated by the Fault
register.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-11
Application Interface
Register Number = 0x00
7
6
5
Reserved
Reserved
Reserved
-
-
-
R
W
Reset:
4
3
NoiseMode SmallTriggerP
eriod
0
2
1
0
Data
Corruption
Small
Capacitor
Charge
Timeout
0
0
0
0
Figure 3-1. Faults register
Table 3-2. Faults register description
Signal
Description
NoiseMode
Indicates whether the TSS is in the noise-measurement mode and whether the Noise keydetector is active. The Noise
key detector processes the noise signal from TSI module, which supports the noise mode, and is an extension of the
Basic or AFID key detectors. The measurement is executed automatically in a defined rate (once during response
time rate) and, if noise is detected, the keydetector is switched to the permanent noise touch detection mode. This
bit is automatically cleared if the noise mode is inactive. The noise mode feature must be enabled in the
TSS_SystemSetup.h.
1 — Noise mode is active
0 — Noise mode is not active
SmallTriggerPe Indicates whether the trigger period is long enough to allow all active electrodes to be scanned. This bit must be
riod
cleared by writing a zero (0) to it by using the configuration function. If the SWI is enabled in the System
Configuration register, an interrupt is generated. If the OnFault callback is enabled, the callback is generated. The
system is disabled to prevent a cyclic error and needs to be reenabled.
1 — SmallTriggerPeriod detected
0 — No SmallTriggerPeriod detected
Data
Corruption
Indicates if a change in the system configuration data is detected through an invalid direct access to memory. This
bit must be cleared by writing a zero (0) to it by using the configuration function. If the SWI is enabled in the System
Configuration register, an interrupt is generated. If the OnFault callback is enabled, then the callback is generated.
The system is disabled to prevent a cyclic error and needs to be reenabled. If the data corruption check function is
not enabled in the TSS_SystemSetup.h, the bit is not functional. For more information, see the Touch Sensing User
Guide.
1 — Unaccounted change detected
0 — No invalid change detected
Touch Sensing Software API Reference Manual, Rev. 8
3-12
Freescale Semiconductor
Application Interface
Table 3-2. Faults register description (continued)
Signal
Description
Small
Capacitor
Indicates whether the small capacitance is detected on the electrode. The reason for this occurrence depends on the
measurement method:
• TSI method - The measured signal is below ten percent (10%) of the required TSI resolution
• GPIO method - The required voltage level change is detected too fast. The measured signal is below forty (40).
This bit must be cleared by writing a 0 to it by using the configuration function. If the SWI is enabled in the System
Configuration register, an interrupt will be produced. If the OnFault callback is enabled, the callback is generated.
The system disables the electrode(s) that caused the error. If the automatic hardware recalibration is enabled in the
TSS_SystemSetup.h and there is a problem with an electrode, the hardware recalibration is executed.
1 — Small capacitor detected
0 — No small capacitor detected
Charge
Timeout
Indicates whether a high capacitance is detected on the electrode. The reason for this occurrence depends on the
measurement method:
• TSI method - The measured signal is higher than 0xFFFF minus the 10% of the required TSI resolution
• GPIO method - The required voltage level is not reached. The hardware timer timeout is exceeded.
This bit must be cleared by writing a 0 to it by using the configuration function. If the SWI is enabled in the System
Configuration register, an interrupt is generated. If the OnFault callback is enabled, then the callback is generated.
The system disables the electrode(s) that caused this error. If the automatic hardware recalibration is enabled in the
TSS_SystemSetup.h and there is a problem with an electrode, the hardware recalibration is executed.
1 — Charge timeout detected
0 — No timeout fault detected
3.5.5
System Configuration register
This register is used to enable the library features. Depending on the application needs, the features can be
modified.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-13
Application Interface
Register Number = 0x01
15
14
R
W
System Enabler SWI Enabler
Reset
R
W
Reset
13
12
11
10
9
8
DC-Tracker
Enabler
Stuck-key
Enabler
Reserved
Reserved
Reserved
Water
Tolerance
Enabler
0
0
0
0
-
-
-
0
7
6
5
4
3
2
1
0
Proximity
Enabler
Low Power
Enabler
Reserved
Reserved
Reserved
Hardware
Recalibratio
n Starter
System
Reset
Manual
Recalibration
Starter
0
0
-
-
-
0
0
0
Figure 3-2. System Configuration register
Table 3-3. System Configuration register descriptions
Signal
Description
System Enabler 1 — System is enabled
0 — System is disabled
SWI Enabler
If any error occurs (see the Faults register), an SWI is generated. This bit affects only the HCS08 version of the TSS
library. The OnFault callback can be used for the same purpose on all HCS08, ColdfireV1, ARMCortex-M4 and
ARMCortex-M0+ versions of the TSS library.
1 — SWI is generated with any fault
0 — No SWI is generated by faults
DC-Tracker
Enabler
DC Tracker function enabling. The bit has higher priority than DC-tracker enablers register.
1 — The DC Tracker filtering mechanism is enabled
0 — The DC Tracker filtering mechanism is disabled
Stuck-key
Enabler
1 — Stuck-key is enabled
0 — Stuck-key is disabled
Water
Tolerance
Enabler
1 — Water tolerance is enabled
0 — Water tolerance is disabled
Proximity
Enabler
1 — Proximity Mode is enabled
0 — Proximity Mode is disabled
Low Power
Enabler
1 — Low Power Mode is enabled
0 — Low Power Mode is disabled
Hardware
Recalibration
Starter
Writing a one (1) to this register schedules a low-level hardware calibration next time the TSS task is executed. The
recalibration is performed only on electrodes which are not touched. If more electrodes belong to the same hardware
module, they need to be released.
System Reset
Writing a one (1) to this register resets the system immediately
Manual
Recalibration
Starter
Writing a one (1) to this register schedules a baseline calibration next time the TSS task is executed
Touch Sensing Software API Reference Manual, Rev. 8
3-14
Freescale Semiconductor
Application Interface
3.5.6
Number of Samples register
Register Number = 0x02
7
6
5
Reserved
Reserved
-
-
4
3
2
1
0
0
0
0
R
NSamples
W
Reset:
0
0
1
Figure 3-3. Number of Samples register
Table 3-4. Number of Samples register descriptions
Signal
Description
NSamples
If an electrode uses the GPIO method, the value determines the number of capacitance samples required to obtain
a single measurement. If the electrode uses the TSI method, the value sets the NSCN register directly in the TSI
module.
1–32 — n samples taken
3.5.7
DC Tracker Rate register
Register Number = 0x03
7
6
5
4
3
2
1
0
1
0
0
R
DC Tracker Exec Rate
W
Reset:
0
1
1
0
0
Figure 3-4. DC Tracker Rate register
Table 3-5. DC Tracker Rate register description
Signal
Description
DC Tracker
Exec Rate
Determines how often the DC tracker function occurs. This number represents the number of calls to the TSS task
function required before the DC tracker function is executed. If enabled, the DC tracker performs a baseline update
and a negative baseline drop. If this register is set to zero (0), the DC tracker feature is disabled.
0 — DC tracker feature disabled
1–255 — DC tracker executed every n task executions
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-15
Application Interface
3.5.8
Slow DC Tracker Factor register
Register Number = 0x04
7
6
5
4
3
2
1
0
1
0
0
R
Slow DC Tracker Factor
W
Reset:
0
1
1
0
0
Figure 3-5. Slow DC Tracker Factor register
Table 3-6. Slow DC Tracker Factor register description
Signal
Description
Slow DC
Determines the baseline updating frequency for the proximity and shielding electrodes. This number is a
Tracker Factor multiplication factor used with standard DCTrackerRate register value .
0 — Slow DC tracker feature disabled
1–255 — Slow DC tracker executed every (n x dc_tracker_rate) task executions
3.5.9
Response Time register
Register Number = 0x05
7
6
5
Reserved
Reserved
-
-
4
3
2
1
0
1
0
0
R
Response time
W
Reset:
0
0
0
Figure 3-6. Response Time register
Table 3-7. Response Time register description
Signal
Description
Response Time Determines the number of measurements required to perform the following:
• Status change in any electrode
• Single noise mode measurement to detect whether the noise is present in the system. The noise mode feature must
be enabled.
A single measurement of all electrodes is taken per TSS_Task execution until TSS_STATUS_OK is reported.
1–32 — n measurements used
3.5.10
Stuck-key Timeout register
This register configures a number of times that the library task must keep detecting a touch before it
performs a forced release. The forced release is done by resetting a baseline value to a current signal value.
This feature protects the application from false permanent touches caused by an external increase of the
electrode capacitance. An electrode is only considered touched until the forced release is invoked. If the
stuck-key function is not enabled in the TSS_SystemSetup.h, it is not possible to write to this register. For
more information, see the Touch Sense User Guide.
Touch Sensing Software API Reference Manual, Rev. 8
3-16
Freescale Semiconductor
Application Interface
Register Number = 0x06
7
6
5
4
3
2
1
0
0
0
0
R
Stuck Key Timeout
W
Reset:
0
0
0
0
0
Figure 3-7. Stuck-key Timeout register
Table 3-8. Stuck-key Timeout register description
Signal
Description
Stuck Key
Timeout
Determines how many task executions it takes for an electrode to be detected as touched before recalibrating that
electrode and then detect that it was untouched. If this value is set to zero (0), the stuck key feature is disabled.
0 — Stuck key feature disabled
1–255 — Electrode recalibrated after n task executions.
3.5.11
Low Power Electrode register
This register represents the electrode number scanned either in a low power mode or in a proximity mode.
Both in the low power mode and in the proximity mode, only one pin is active and is able to perform
electrode capacitance measurements.
The low power electrode number must be selected from the module related to the low power control source
defined by TSS_USE_LOWPOWER_CONTROL_SOURCE in the TSS_SystemSetup.h. If an electrode
does not meet this condition, the System Setup Config Error is generated. If neither the low power control
source nor the proximity callback defined in TSS_SystemSetup.h is selected, writing to this register is not
possible. For more information, see the Touch Sensing User Guide.
If the TSI module is used as a low power control source, the register content is used to set up the
TSI_PEN[LPSP].
]
Register Number = 0x07
7
6
5
4
3
2
1
0
0
0
0
R
Low Power Electrode Number
W
Reset:
0
0
0
0
0
Figure 3-8. Low Power Electrode register
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-17
Application Interface
Table 3-9. Low Power Electrode register description
Signal
Description
Low Power
Electrode
Number
3.5.12
Number of the electrode scanned in the low power mode or in the proximity mode. The range of the electrode
numbers is 0 – 63
Low-Power Electrode Sensitivity register
The Low-Power Sensitivity register defines the sensitivity value used to wake the system either from the
low-power mode or from the sensitivity threshold for proximity detection. This sensitivity indicates the
relative delta threshold value from a baseline level.
The low-power control source device manages scanning the selected electrode during the low-power
mode. When the electrode value exceeds a defined value, the TSS wakes the device from the low-power
mode and initializes active mode. If neither the low-power control source is selected nor the proximity
callback defined in TSS_SystemSetup.h, writing to this register is not possible. See the Touch Sensing
User Guide.
Register Number = 0x08
7
6
5
4
3
2
1
0
1
1
R
Reserved
Low Power Electrode Sensitivity
W
Reset:
0
0
1
1
1
1
Figure 3-9. Low Power Electrode Sensitivity register
Table 3-10. Low Power Electrode Sensitivity register description
Signal
Description
Low Power
Electrode
Sensitivity
3.5.13
The sensitivity value of the electrode scanned in the low power mode or in the proximity mode. The range of the
sensitivity is 1–127.
System Trigger register
This register enables and sets up library trigger features. If the trigger function is not enabled in the
TSS_SystemSetup.h, writing to this register is not possible. See the Touch Sensing User Guide for more
information.
Touch Sensing Software API Reference Manual, Rev. 8
3-18
Freescale Semiconductor
Application Interface
.
Register Number = 0x09
7
6
5
4
3
2
1
Reserved
Reserved
Reserved
Reserved
Reserved
SWTrigger
-
-
-
-
-
0
0
R
TriggerMode TriggerMode
W
Reset
0
1
Figure 3-10. System Trigger register
Table 3-11. System Trigger register descriptions
Signal
Description
TriggerMode
SWTrigger
3.5.14
0x00 —> TSS_TRIGGER_MODE_AUTO
0x01 —> TSS_TRIGGER_MODE_ALWAYS
0x10 —> TSS_TRIGGER_MODE_SW
0x11 —> Reserved
TriggerMode is not set if SWTrigger bit is set in the same moment.
Write only bit. This bit controls software triggering scan execution. In case the TSS_TRIGGER_MODE_SW is
selected, write 1 to the software trigger performs one scan cycle execution, otherwise the bit is not functional.
Sensitivity Configuration register
This set of registers contains a sensitivity value for each electrode. The sensitivity value is an 8-bit value
that represents the minimum difference between an instant signal value and the baseline, which is required
to indicate a touch. The sensitivity does not need to be set if Automatic Sensitivity Calibration is enabled.
For more information, see the Touch Sensing User Guide.
Register Number = 0x0A
7
6
5
4
3
2
1
0
1
1
1
R
Sensitivity
W
Reset:
-
0
1
1
1
Figure 3-11. Sensitivity Configuration register
Table 3-12. Sensitivity Configuration register description
Signal
Description
Sensitivity
3.5.15
When an electrode is detected as touched, represents the threshold in a signal delta.
2–127 — Electrode sensitivity
Electrode enablers
This set of registers inform which electrode is enabled. Each bit represents one electrode where a bit value
one (1) represents an enabled electrode, and a bit value zero (0) represents a disabled electrode.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-19
Application Interface
All dc-tracker enabler bits are enabled after reset.
Because certain errors automatically disable electrodes, the application must re-enable them. If an
automatic hardware recalibration is enabled in the TSS_SystemSetup.h, the hardware recalibration bit is
automatically set in the System Config register which results in hardware recalibration whenever the next
TSS_Task() is executed.
Note that enabling or disabling controls also enables or disables all electrodes assigned to the control.
However, setting the register manually is always allowed.
The arrangement of electrodes with bits is as follows:
• Register 0, bit 0 — Electrode 0
• Register 0, bit 1 — Electrode 1
• Register 0, bit 7 — Electrode 7
• Register 1, bit 0 — Electrode 8
• Register 1, bit 7 — Electrode 15
• etc.
If the electrode enabler settings are changed, a hardware recalibration is scheduled to configure the system
to the new electrode configurations. The hardware recalibration starter bit in the System Configuration
register is automatically set for this purpose. For more information, see Section 3.5.5, “System
Configuration register”.
3.5.16
Electrode status
This set of registers provides the electrode status (touched or untouched). Each bit represents one
electrode. A value one (1) represents a touched electrode, while a value (0) represents an untouched
electrode.
The arrangement of electrodes with bits is as follows:
• Register 0, bit 0 — Electrode 0
• Register 0, bit 1 — Electrode 1
• Register 0, bit 7 — Electrode 7
• Register 1, bit 0 — Electrode 8
• Register 1, bit 7 — Electrode 15
• etc.
3.5.17
Baseline register
This register is used to read and write dc-tracker baseline values. Writing is allowed only after TSS_Init()
call and before the first TSS_Task() execution.
Touch Sensing Software API Reference Manual, Rev. 8
3-20
Freescale Semiconductor
Application Interface
Register Number = 0x0A + A + B + C
15
14
13
12
11
10
9
8
R
Baseline
W - Init
Reset
0
0
0
0
0
0
0
0
7
6
5
4
3
2
1
0
0
0
0
0
R
Baseline
W- Init
Reset
0
0
0
0
Figure 3-12. Baseline register
Table 3-13. Baseline register descriptions
Signal
Description
Baseline
3.5.18
Represents the dc-tracker baseline value. Writing is allowed only after TSS_Init() call and before the first
TSS_Task() execution.
0–65535 — Electrode baseline
Dc-Tracker enablers
This set of registers detect which electrode has an enabled update of the dc-tracker baseline. Each bit
represents one electrode. Bit value one (1) represents an enabled dc-tracker on an electrode, while a value
(0) represents a disabled dc-tracker on an electrode. All dc-tracker enabler bits are enabled after reset.
If one control electrode is touched, analog decoders automatically disable a dc-tracker on all electrodes
assigned to the control . If all electrodes from the control are released, the dc-tracker automatically
re-enables these electrodes. Setting the register manually is also an option.
The Dc-tracker enabler bit in the System Configuration register is a global enabler of the dc-tracker
function with a higher priority than the dc-tracker enablers.
The arrangement of dc-tracker enablers with bits is as follows:
• Register 0, bit 0 — Dc-tracker on electrode 0
• Register 0, bit 1 — Dc-tracker on electrode 1
• Register 0, bit 7 — Dc-tracker on electrode 7
• Register 1, bit 0 — Dc-tracker on electrode 8
• Register 1, bit 7 — Dc-tracker on electrode 15
• etc
3.5.19
Configuration Checksum Register
This read-only register contains the checksum value to guarantee the validity of the information contained
in C&S registers. When the TSS_SetSystemConfig() function is called to update a C&S register, a
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-21
Application Interface
checksum algorithm is performed and the result is stored in this register. The TSS_Task() function checks
the integrity of this checksum. If it fails, the data corruption bit of the fault register is set. This function
can be disabled in the TSS_SystemSetup.h by defining the TSS_USE_DATA_CORRUPTION_CHECK.
For more information, see the Touch Sensing User Guide.
NOTE
If you write to the Configuration and Status registers directly, without using
the TSS_SetSystemConfig() function, the Checksum register will not be
updated and the data corruption bit will be set on the next execution of the
TSS_Task() function.
3.6
Keypad decoder API
This section describes the keypad decoder API. It describes the keypad Configuration and Status registers,
the TSS_SetKeypadConfig() function used to write to these registers, and the data structure used for
reading this register. This section also describes the callback function and its parameters for the keypad
control.
Each application keypad control has its respective Configuration and Status register and a callback
function.
3.6.1
Writing to the Configuration and Status registers
To change values in the Configuration and Status register, use the TSS_SetKeypadConfig function
declared in the TSS_API.h file.
Function prototype
uint8_t TSS_SetKeypadConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter, uint8_t
u8Value);
Input parameters
Return valueReturn value
Type
Name
TSS_CONTROL_ID u8ControlId
Valid range/values
Description
Any valid control Id of the
appropriate control type
Identifier of the control
configured, stored in the first
element of the control’s C&S
structure
uint8_t
u8Parameter
Any of the parameter codes
provided by keypad decoder
Code indicating the parameter
configured
uint8_t
u8Value
Depends on the specific
parameter configured
New desired value, for the
respective configuration register
Return value
The return value is an unsigned byte with the following possible return values defined in the file
TSS_StatusCodes.h:
Touch Sensing Software API Reference Manual, Rev. 8
3-22
Freescale Semiconductor
Application Interface
Return Value
Description
TSS_STATUS_OK
Configuration is successful.
TSS_ERROR_KEYPAD_ILLEGAL_CONTROL_TYPE
Configuration is not executed. The Id parameter does not match the
control type structure that the user was trying to modify.
TSS_ERROR_KEYPAD_READ_ONLY_PARAMETER
Configuration is not executed whenever the user attempts to modify a
read-only parameter.
TSS_ERROR_KEYPAD_ILLEGAL_VALUE
Configuration is not executed because of an illegal value number.
TSS_ERROR_KEYPAD_OUT_OF_RANGE
Configuration is not executed because the new value was out of the
established boundaries.
TSS_ERROR_KEYPAD_ILLEGAL_PARAMETER
Configuration is not executed because of an illegal parameter number.
3.6.2
Reading the Configuration and Status registers
The two options to read the keypad Configuration and Status register structure involve either using the TSS
function declared in the TSS_API.h file or directly accessing the configuration and status structure for
specific data. The following describes the first option.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-23
Application Interface
Function prototype
uint8_t TSS_GetKeypadConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter);
Input parameters
Type
Name
TSS_CONTROL_ID u8ControlId
uint8_t
u8Parameter
Valid range/values
Description
Any valid control Id of the
appropriate control type
Identifier of the control
configured, stored in the first
element of the control’s C&S
structure
Any of the parameter codes
provided by each decoder
Code indicating the parameter
configured
Return value
The return value corresponds either to an actual unsigned byte value of a register specified by u8Parameter,
or error values defined in the file TSS_StatusCodes.h:
Return Value
Description
Any valid unsigned byte value
Value corresponds to an actual unsigned byte value of a
register specified by u8Parameter.
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Read is not successful because the parameter is illegal.
TSS_ERROR_GETCONF_ILLEGAL_CONTROL_TYPE
Read is not successful because the control type is illegal.
The second option to read the keypad Configuration and Status register structure involves directly
accessing the configuration and status structure for specific data. The structure name is defined by the
application in the TSS_SystemSetup.h file by using the following definition:
#define TSS_Cn_STRUCTURE cKey0
Where n is the Control number starting from zero (0) to the number of controls minus one.
The cKey0 name is just an example. The user can define any other name for each control configuration
and status structure.
typedef struct{
const TSS_CONTROL_ID ControlId;
const TSS_KEYPAD_CONTCONF ControlConfig;
uint8_t BufferReadIndex;
const uint8_t BufferWriteIndex;
const TSS_KEYPAD_EVENTS Events;
const uint8_t MaxTouches;
const uint8_t AutoRepeatRate;
const uint8_t AutoRepeatStart;
const uint8_t * const BufferPtr;
} TSS_CSKeypad;
//Note 1
//Note 2
//Note 3
NOTE
1. The TSS_CONTROL_ID type is an eight bit-field structure described in Section 3.6.4, “Control
ID register"”
Touch Sensing Software API Reference Manual, Rev. 8
3-24
Freescale Semiconductor
Application Interface
2. The TSS_KEYPAD_CONTCONF type is an eight bit-field structure described in Section 3.6.5,
“Control Configuration register"”
3. The TSS_KEYPAD_EVENTS type is an eight bit-field structure described in Section 3.6.9,
“Event Control and Status register"”
The following command shows how to read the Control ID register by using the example of the structure
cKey0:
Temp = cKey0.ControlId;
3.6.3
Configuration and Status registers list
The following table describes the keypad control Configuration and Status registers, and the Control ID
Register.
Table 3-14. Keypad Control Configuration and Status registers
Register
Number
Size [bytes]
Register Name
Section
Initial value
Brief Description
0x00
1
ControlId
Section 3.6.4, “Control ID Application
register"”
dependable
R — Displays the control
type and control number.
0x01
1
ControlConfig
Section 3.6.5, “Control
Configuration register"”
0x00
RW — Configures overall
enablers of the object.
0x02
1
BufferReadIndex
Section 3.6.7,
“BufferReadIndex"”
0x00
RW — Index of the first
unread element of the
events buffer
0x03
1
BufferWriteIndex
Section 3.6.8,
“BufferWriteIndex"”
0x00
R — Index of the first free
element of the buffer
0x04
1
Event Control and
Status Register
Section 3.6.9, “Event
Control and Status
register"”
0x00
RW — Configures the
events that will be reported
by the controller. This
Register holds the Max
Key and Buffer Overflow
Flags
0x05
1
MaxTouches
Section 3.6.10,
“MaxTouches register"”
0x00
RW — Configures the
maximum number of keys
that can be pressed at the
same time.
0x06
1
AutoRepeatRate
Section 3.6.11, “Auto
Repeat Rate register"”
0x00
RW — Configures the rate
at which keys will be
reported when they are
kept pressed and no
movement is detected.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-25
Application Interface
Table 3-14. Keypad Control Configuration and Status registers (continued)
Register
Number
Size [bytes]
Register Name
Section
Initial value
Brief Description
0x07
1
AutoRepeatStart
Section 3.6.12, “Auto
Repeat Start register"”
0x00
RW — Configures the time
between a touch and an
auto-repeat event when the
key is kept pressed.
0x08
1
BufferPtr
Section 3.6.6, “Buffer
Pointer register"”
Assigned at
precompile
time
R — Address of the buffer
where the events for each
controller are stored
3.6.4
Control ID register
This read-only register contains the identifier code of the control.
Register Number = 0x00
7
R
6
5
4
3
Control Type
2
1
0
Control Number
W
Reset:
1
—1
—
—
—
—
—
—
—
Application dependable.
Figure 3-13. Control ID Register
Encoding
Control Type
001
Keypad
010
Slider
011
Rotary
100
Analog slider
101
Analog rotary
110
Matrix
100-111
Reserved
NOTE
The control number is assigned in the system setup module. This value is
unique for all controls, indicating that each control has a particular number
regardless of its type. The first assigned control number is zero.
3.6.5
Control Configuration register
This register configures the overall behavior of the object.
Touch Sensing Software API Reference Manual, Rev. 8
3-26
Freescale Semiconductor
Application Interface
Register Number = 0x01
7
6
5
4
3
2
1
0
Control Enabler
Callback
Enabler
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
0
0
-
-
-
-
-
-
R
W
Reset:
Figure 3-14. Control Configuration register
Table 3-15. Control Configuration register description
Signal
Description
Control
Enabler
Global enabler for the control. This determines if the control electrodes are scanned for touch detection. The bit
either enables or disables all control electrodes in the Electrode Enablers register.
1 — Control enabled
0 — Control disabled
Callback
Enabler
Enables or disables the use of the callback function. If it is enabled, the function will be called when one of the active
events in the Events Configuration registers occurs.
1 — Callback enabled
0 — Callback disabled
3.6.6
Buffer Pointer register
This register defines the base address of the event buffer for a specific control. The event buffer is a circular
buffer with 16 elements. It stores every touch or release event that occurs in the control depending on the
events enabled in the Events Register.
The Keypad Events Register has the following 8-bit format:
Register Number = 0x02
7
R
6
5
4
3
Reserved
Reserved
Reserved
—
—
—
2
1
0
—
—
Key Number
Event Type
W
Reset:
1
—1
—
—
Assigned at TSS_Init
Figure 3-15. Buffer Pointer register
Table 3-16. Buffer Pointer register description
Signal
Event Type
Key Number
Description
Indicates the type of event registered in the buffer.
1 — Release event
0 – Touch event
Determines the key within keypad control on which the event has occurred.
0–15 — Key presenting the event
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-27
Application Interface
3.6.7
BufferReadIndex
This register stores the index of the first unread element of the events buffer. This index is used to start
reading the data from the buffer until it reaches the value of the Buffer Write Index. The user is responsible
for updating this value after the read operation, which can be done automatically by using the
TSS_KEYPAD_BUFFER_READ macro.
Register Number = 0x03
7
6
5
4
3
Reserved
Reserved
Reserved
Reserved
-
-
-
-
2
1
0
0
0
R
Index value
W
Reset:
0
0
Figure 3-16. BufferReadIndex register
Table 3-17. BufferReadIndex Register description
Signal
Description
Index value
Determines the index of the first unread event in the events buffer.
0–15 — Index of first unread element
Macro prototype
#define TSS_KEYPAD_BUFFER_READ(destvar,kpcsStruct)
This macro allows you to store the first unread element from the event buffer and update the value of the
Buffer Write Index register. When using this macro, provide two parameters: destvar and kpcsStruct.
Input parameters
Type
Name
uint8_t
destvar
CSKeypad
kpcsStruct
Description
Name of the variable where the first unread element is stored.
Name of the controller structure defined in the TSS_SystemSetup.h header
file. See the Touch Sensing User Guide for more details about the structure
name.
Return value
None
3.6.8
BufferWriteIndex
This register stores the index value of the first free element in the buffer which is located one element after
the last captured event. This register is automatically updated when new events are stored in the buffer and
is provided for reference during the read operations. The user should read the buffer until this index is
reached. This section also describes the TSS_KEYPAD_BUFFER_EMPTY macro.
Touch Sensing Software API Reference Manual, Rev. 8
3-28
Freescale Semiconductor
Application Interface
Register Number = 0x04
7
6
5
4
3
Reserved
Reserved
Reserved
Reserved
-
-
-
-
2
R
1
0
0
0
Index value
W
Reset:
0
0
Figure 3-17. BufferWriteIndex register
Table 3-18. BufferWriteIndex register description
Signal
Description
Index value
Determines the index of the first free element in the events buffer.
0–15 — Index of the first free element
Macro prototype
#define TSS_KEYPAD_BUFFER_EMPTY(kpcsStruct)
This macro indicates when the events buffer is empty. The macro performs a comparison between the
Buffer Read Index and the Buffer Write Index.
Input parameters
Type
Name
CSKeypad
kpcsStruct
Description
Name of the controller structure defined by the user in the
TSS_SystemSetup.h header file. See the Touch Sensing User
Guide for more details about the structure name.
Return value
The macro performs a comparison between the first unread element index and the first free element index
in the buffer. It indicates that all elements in the buffer have been read when the two indexes are equal. If
all elements have been read, the macro returns one (1), if not, it returns zero (0).
3.6.9
Event Control and Status register
This register contains bits used to enable or disable events that call the control callback function. It also
contains the maximum keys and buffer overflow status flags.
Register Number = 0x05
7
6
5
4
3
2
1
0
Max Keys Flag
Buffer
Overflow
Flag
Reserved
Keys
Exceeded
Enabler
Buffer
Full/Overflow
Enabler
Auto-Repeat
Enabler
Release
Event
Enabler
Touch Event
Enabler
0
0
0
0
0
0
0
0
R
W
Reset:
Figure 3-18. Event Control and Status register
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-29
Application Interface
Table 3-19. Event Control and Status register description
Signal
Description
Max Keys Fault A flag that indicates whether the limit of keys pressed at the same time has been exceeded. The limit is defined by
the MaxTouches Register. In this case, any further key touches will be ignored until at least one key is released. This
flag will be automatically cleared after the fault condition turns false.
1 — Limit exceeded
0 — No excess keys
Buffer
This flag indicates whether more events have been produced than the buffer free space allows. In this case the
Overflow Flag newest events are lost and no more events can be logged. This flag is cleared by writing a zero (0) to this bit.
1 — Buffer overflowed
0 — Free space available
Keys Exceeded If this bit is set and the callback function enabled, the decoder calls the control callback function after the limit for
Enabler
pressed keys is exceeded.
1 — Event enabled
0 — Event disabled
Buffer
Overflow
Enabler
If this bit is set and the callback function enabled, the decoder calls the control callback function after the circular
buffer for events is full or overflown.
1 — Event enabled
0 — Event disabled
Auto-repeat
Enabler
If this bit is set, the decoder stores a new touch event in the events buffer at the specified rate in case at least one
key remains pressed for the time configured in the Auto-repeat Start register. If the control’s callback function is
enabled, it is called at the same rate.
1 — Auto-repeat enabled
0 — Auto-repeat disabled
Release Event If this bit is set, the decoder stores released events in the events buffer. If the control callback function is enabled, it
Enabler
is called when an event occurs.
1 — Event enabled
0 — Event disabled
Touch Event
Enabler
If this bit is set, the decoder stores touch events in the events buffer. If the control callback function is enabled, it is
called when an event occurs.
1 — Event enabled
0 — Event disabled
NOTE
If touch and release events are both disabled, the control is automatically
disabled and must be re-enabled by the user in the Control Configuration
Register.
3.6.10
MaxTouches register
The MaxTouches register defines the maximum number of keys reported per touch. This feature controls
the function when a larger area than expected is touched. For example, a multiplexed array of electrodes
where only two keys are needed to detect a value or a function. In this case, the MaxTouches register is
configured with a value of two.
Touch Sensing Software API Reference Manual, Rev. 8
3-30
Freescale Semiconductor
Application Interface
Register Number = 0x06
7
6
5
4
3
Reserved
Reserved
Reserved
Reserved
-
-
-
-
2
1
0
R
Max Number of Touches
W
Reset:
0
0
0
0
Figure 3-19. MaxTouches register
Table 3-20. MaxTouches register description
Signal
Description
Max Number of Sets the limit for simultaneous active keys. If set to zero (0), no limit is established.
Touches
0 — No limit established
1–15 — Limit set to n keys
3.6.11
Auto Repeat Rate register
This register contains the rate value at which the pressed keys are reported when kept pressed.
Register Number = 0x07
7
6
5
4
3
2
1
0
0
0
0
0
R
Auto-repeat rate
W
Reset:
0
0
0
0
Figure 3-20. Auto Repeat Rate register
Figure 3-21. Auto Repeat Rate register description
Signal
Description
Auto-repeat
Rate
Sets the rate where the pressed keys are reported when kept pressed. This value is a multiplier of the touch sensing
task execution rate. If set to zero (0), no auto-repeat occurs and the event is automatically disabled in the Events
Register. The user must manually re-enable this event if desired.
0 — Auto-repeat feature disabled
1–255 — Touch event reported every n execution times
3.6.12
Auto Repeat Start register
This register defines the time difference between a touch event and its auto-repeat, which is ensuring that
the key remains touched. During this time, no event is generated. After this time elapses, a new event is
generated and the auto-repeat rate register controls the new event timing by generating new touch events
at a specified rate. After this, the value of this register is not used by the decoder until a different touch
event is detected.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-31
Application Interface
Register Number = 0x08
7
6
5
4
3
2
1
0
0
0
0
R
Auto-repeat Start
W
Reset:
0
0
0
0
0
Figure 3-22. Auto Repeat Start register
Table 3-21. Auto Repeat Start register description
Signal
Description
Auto-repeat
Start
Sets the length a key must remain pressed before generating new events at the auto-repeat rate. This value is a
multiplier of the touch sensing task execution rate. If set to 0, the auto-repeat state will be entered immediately after
the last touch.
0–255 — Wait n execution times before auto-repeat.
3.6.13
Keypad Callback function
This function is called by the decoder module if an event occurs and the callback function is enabled.
Callback functions are assigned to controls in the system setup module and one callback may be assigned
to different controls in the system.
Function prototype
void CallbackFuncName(uint8_t u8ControlId)
CallbackFuncName for each control is defined in the following TSS_SystemSetup.h file macro:
#define TSS_Cn_CALLBACK fCallBack1
Where:
• n is the number of the control
• fCallBack1 is a name example
Input parameters
Type
uint8_t
Name
u8ControlId
Valid range/values
Any valid control ID of any
control in the system.
Description
It indicates the control that
generated the event. This
parameter matches the controlled
field in the control C&S register.
Return Value
None
3.7
Slider and Rotary decoder API
This section describes the API for slider and rotary decoder. Because the rotary decoder API is similar to
the slider API, this section describes the slider decoder and the differences between the two. The
Touch Sensing Software API Reference Manual, Rev. 8
3-32
Freescale Semiconductor
Application Interface
TSS_SetSliderConfig() and TSS_SetRotaryConfig() function are used to write to the decoder registers.
The TSS_GetSliderConfig() and TSS_GetRotaryConfig() are used for reading the registers. This section
describes the callback function and its parameters for a slider and rotary controls. Each application slider
and rotary control has its respective Configuration and Status registers and a callback function.
3.7.1
Writing to the Configuration and Status registers
To change values in the Configuration and Status registers, call TSS_SetSystemConfig function. This is
declared in the TSS_API.h file.
Function prototype for Slider
uint8_t TSS_SetSliderConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter, uint8_t
u8Value);
Function prototype for Rotary
uint8_t TSS_SetRotaryConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter, uint8_t
u8Value);
Input parameters
Type
Name
Valid range/values
Description
TSS_CONTROL_ID
u8ControlId
Any valid control Id of the
appropriate control type
Identifier of the control
configured which is stored in the
first element of the control’s C&S
structure.
uint8_t
u8Parameter
Any of the parameter codes
provided by slider decoder
Code indicating that the
parameter is configured.
uint8_t
u8Value
Depends on the specific
parameter configured
New desired value for the
respective configuration registers
Return value for Slider
The return value is an unsigned integer with the following possible return values defined in the file
TSS_API.h:
Return Value
Description.
TSS_STATUS_OK
Configuration is successful.
TSS_ERROR_ SLIDER _ILLEGAL_PARAMETER
Configuration is not executed because of an illegal parameter number.
TSS_ERROR_ SLIDER _READ_ONLY_PARAMETER
Configuration is not executed whenever the user attempts to modify a
read-only parameter.
TSS_ERROR_ SLIDER _OUT_OF_RANGE
Configuration is not executed because the new value is out of range of
the established boundaries.
TSS_ERROR_ SLIDER _ILLEGAL_CONTROL_TYPE
Configuration is not executed because the u8ControlId parameter
does not match the control type structure that the user was trying to
modify.
Return value for Rotary
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-33
Application Interface
The return value is an unsigned integer with the following possible return values defined in the file
TSS_StatusCodes.h.
Return Value
Description
TSS_STATUS_OK
Configuration is successful.
TSS_ERROR_ROTARY_ILLEGAL_PARAMETER
Configuration is not executed because of the illegal parameter
number.
TSS_ERROR_ROTARY_READ_ONLY_PARAMETER
Configuration is not executed whenever the user attempts to modify
a read-only parameter.
TSS_ERROR_ROTARY_ILLEGAL_VALUE
Configuration is not executed because of an illegal value number.
TSS_ERROR_ROTARY_OUT_OF_RANGE
Configuration is not executed because the new value was out of the
established boundaries
TSS_ERROR_ROTARY_ILLEGAL_CONTROL_TYPE
Configuration is not succesful because the u8ControlId parameter
does not match the control type structure that the user is trying to
modify.
3.7.2
Reading the Configuration and Status registers
The two options to access Configuration and Status register structure involve using theTSS function
declared in the TSS_API.h file and directly accessing the configuration and status structure for specific
data. This following content describes the first option.
Function prototype for Slider
uint8_t TSS_GetSliderConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter);
Function prototype for Rotary
uint8_t TSS_GetRotaryConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter);
Input parameters
Return value
Type
Name
TSS_CONTROL_ID u8ControlId
uint8_t
u8Parameter
Valid range/values
Description
Any valid control Id of the
appropriate control type
Identifier of the control
configured which is stored in the
first element of the control’s C&S
structure
Any of the parameter codes
provided by each decoder
Code indicating the parameter
configured
Return value
The return value corresponds to either a register unsigned byte value specified by the u8Parameter, or error
values defined in the file TSS_StatusCodes.h:
Touch Sensing Software API Reference Manual, Rev. 8
3-34
Freescale Semiconductor
Application Interface
Return Value
Description
Any valid unsigned byte value
Value corresponds to an unsigned byte value of a register
specified by u8Parameter.
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Read was not successful because of the illegal parameter.
TSS_ERROR_GETCONF_ILLEGAL_CONTROL_TYPE
Read was not successful because of the illegal control type.
The second option to access Configuration and Status register structure involves direct access to the
configuration and status structure for specific data. The application defines the structure name in the
TSS_SystemSetup.h file by using the following definition:
#define TSS_Cn_STRUCTURE
cStructure
Where n is the Control number starting from 0 going up to the number of controls minus one.
The cStructure name is just an example. The user can define any other name for each control configuration
and status structure.
typedef struct{
const TSS_CONTROL_ID ControlId;
const TSS_SLIDER_CONTROL ControlConfig;
const TSS_SLIDER_DYN DynamicStatus;
const TSS_SLIDER_STAT StaticStatus;
const TSS_SLIDER_EVENTS Events;
const uint8_t AutoRepeatRate;
const uint8_t MovementTimeout;
} TSS_CSSlider;
typedef struct{
const TSS_CONTROL_ID ControlId;
const TSS_SLIDER_CONTROL ControlConfig;
const TSS_SLIDER_DYN DynamicStatus;
const TSS_SLIDER_STAT StaticStatus;
const TSS_SLIDER_EVENTS Events;
const uint8_t AutoRepeatRate;
const uint8_t MovementTimeout;
} TSS_CSRotary;
1.
2.
3.
4.
5.
//Note
//Note
//Note
//Note
//Note
1
2
3
4
5
//Note
//Note
//Note
//Note
//Note
1
2
3
4
5
NOTE
The TSS_CONTROL_ID type is an eight bit-field structure described in Section 3.7.4, “Control
ID register"”
The TSS_SLIDER_CONTROL type is an eight bit-field structure described in Section 3.7.5,
“Control configuration"”
The TSS_SLIDER_DYN type is an eight bit-field structure described in Section 3.7.6, “Dynamic
Status register"”
The TSS_SLIDER_STAT type is an eight bit-field structure described in Section 3.7.7, “Static
Status register"”
The SLIDER_EVENTS type is an eight bit-field structure described in Section 3.7.8, “Events
Control register"”
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-35
Application Interface
The following command is an example command used to read the Control ID register:
Temp = cStructure.ControlId;
3.7.3
Configuration and Status registers list
The following table contains the control Configuration and Status registers.
Table 3-22. Control Configuration and Status registers
Register
Number
Size
[bytes]
Register Name
Section
Initial value
Brief Description
0x00
1
ControlId
Section 3.7.4, “Control ID Application
register"”
dependable
R — Displays the control
type and control number.
0x01
1
ControlConfig
Section 3.7.5, “Control
configuration"”
0x00
RW — This register
configures overall enablers
of the object.
0x02
1
DynamicStatus
Section 3.7.6, “Dynamic
Status register"”
0x00
R — Displays movement,
direction and displacement
information.
0x03
1
StaticStatus
Section 3.7.7, “Static
Status register"”
0x00
R — Displays touch and
absolute position
information. Hold the
invalid position status flag.
0x04
1
Events
Section 3.7.8, “Events
Control register"”
0x00
RW — Configures the
events that call the callback
function.
0x05
1
AutoRepeatRate
Section 3.7.9,
“Auto-repeat Rate
register"”
0x00
RW — Configures the rate
at which keys are reported
when they are kept pressed
and no movement is
detected.
0x06
1
MovementTimeout
Section 3.7.10,
“Movement Timeout
register"”
0x00
RW — Number of times
the decoder must detect a
no displacement before
reporting a hold event and
no movement.
3.7.4
Control ID register
This read-only register contains the control identifier code.
Register Number = 0x00
7
R
6
5
4
3
Control Type
2
1
0
Control Number
W
Reset:
1
—1
—
—
—
—
—
—
—
Application dependable.
Touch Sensing Software API Reference Manual, Rev. 8
3-36
Freescale Semiconductor
Application Interface
Figure 3-23. Control ID register
Encoding
Control Type
001
Keypad
010
Slider
011
Rotary
100
Analog Slider
101
Analog Rotary
110
Matrix
111
Reserved
NOTE
The control number is assigned in the system setup module. This value is
unique for all controls and indicates that each control has a particular
number regardless of its type. The first assigned control number is zero.
3.7.5
Control configuration
This register configures overall enablers of the object.
Register Number = 0x01
7
6
5
4
3
2
1
0
Control Enabler
Callback
Enabler
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
0
0
-
-
-
-
-
-
R
W
Reset:
Figure 3-24. Control Configuration register
Table 3-23. Control Configuration register description
Signal
Description
Control
Enabler
Global enabler for the control. This determines if the electrodes of the control are scanned for detection. The bit
enables or disables all control electrodes in the Electrode enablers register.
1 — Control enabled
0 — Control disabled
Callback
Enabler
Enables or disables the use of the callback function. If it is enabled, the function is called whenever an active event
occurs in the Events Configuration registers.
1 — Callback enabled
0 — Callback disabled
3.7.6
Dynamic Status register
This register describes the movement of the control over the electrodes.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-37
Application Interface
Register Number = 0x02
7
R Movement Flag
6
5
4
Direction
0
0
0
0
0
3
2
1
0
0
0
Displacement
W
Reset:
0
0
0
Figure 3-25. Dynamic Status register
Table 3-24. Dynamic Status register description
Signal
Description
Movement
Flag
Indicates whether movement is detected at the moment of reading.
1 — Movement detected
0 — Movement not detected
Direction
Indicates the direction of the movement. This bit remains with its last value even if movement stops and is no longer
detected.
1 — Incremental (from Ex to Ey, where x < y)
0 — Decremental (from Ex to Ey, where x > y)
Displacement
3.7.7
This value indicates the difference in positions from the last status to the new one. This indicates how many
positions have been advanced in the current movement direction.
0–15 — Number of positions.
Static Status register
This register displays events, flags, and status of the electrodes in the control when no movement over the
electrodes is detected.
Register Number = 0x03
R
7
6
5
Touch Flag
Invalid Position
Flag
0
0
0
0
4
3
2
1
0
0
0
Position
W
Reset:
0
0
0
Figure 3-26. Static Status register
Table 3-25. Static Status register description
Signal
Touch Flag
Description
Indicates whether a touch is detected in the control at the moment of reading.
1 — Touch detected
0 — Touch not detected
Touch Sensing Software API Reference Manual, Rev. 8
3-38
Freescale Semiconductor
Application Interface
Signal
Description
Invalid Position Indicates if an invalid combination of touched electrodes is being detected.
Flag
1 — Invalid position detected
0 — Valid position detected
Position
3.7.8
This value indicates the absolute position within the control that is actuated.
0–31 — Absolute position
Events Control register
The register contains bits used to enable or disable events that call the control callback function.
Register Number = 0x04
7
6
5
4
Reserved
Reserved
Reserved
Release
Event
Enabler
0
0
0
0
R
W
Reset:
3
2
Hold AutoHold Event
Repeat Enabler
Enabler
0
0
1
0
Movement
Event
Enabler
Initial Touch
Event
Enabler
0
0
Figure 3-27. Events Control register
Table 3-26. Events Control Register description
Signal
Description
Release Event If this bit is set and the callback function is enabled, the callback is executed when all touched electrodes in the
Enabler
control are released.
1 — Release event enabled
0 — Release event disabled
Hold
Auto-repeat
Enabler
If this bit is set, the Hold Event Enabler and the callback function are enabled. The callback is executed at the rate
specified in the Auto-repeat Rate register for as long as one valid position is detected as touched in the control, and
no movement is detected.
1 — Auto-repeat feature enabled
0 — Auto-repeat disabled
Hold Event
Enabler
If this bit is set and the callback function enabled, the decoder calls the control callback function when the movement
stops and, after a certain period of time, a constant touched position is detected. The time is configurable in the
Movement Timeout register.
1 — Event enabled
0 — Event disabled
Movement
If this bit is set and the callback function enabled, the decoder calls the control callback function every time a
Event Enabler displacement is detected.
1 — Event enabled
0 — Event disabled
Initial Touch If this bit is set and the callback function enabled, the decoder calls the control callback function when the control
Event Enabler transitions from an idle to an active state.
1 — Event enabled
0 — Event disabled
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-39
Application Interface
NOTE
If none of the events are enabled, the control is automatically disabled and
must be re-enabled by the user in the Control Configuration Register.
3.7.9
Auto-repeat Rate register
The Auto-repeat Rate register contains the rate value where a hold event is reported when it is kept pressed
without movement.
Register Number = 0x05
7
6
5
4
3
2
1
0
0
0
0
R
Auto-repeat Rate
W
Reset:
0
0
0
0
0
Figure 3-28. Auto-repeat Rate register
Table 3-27. Auto-repeat Rate register description
Signal
Description
Auto-repeat
Rate
The decoder calls the control callback function at a specified rate provided that a valid position is continuously
detected, the auto-repeat feature is enabled and no displacement occurs. If this register is set to 0, the auto-repeat
feature will be disabled in the events register.
0 — Auto-repeat feature disabled
1–254 — Callback is called every n task executions
NOTE
The auto-repeat function works only if a hold event is presented. The hold
event is delayed by the Movement Timeout function. If the Movement
Timeout register is set to zero (0), the Auto-repeat function stops to generate
callback because the Hold event is no longer reported.
3.7.10
Movement Timeout register
The register value defines how long the movement event stays reported after the hold event is detected.
The delay is defined in number of TSS_Task() executions. The hold indicates the instance when the
movement stops and a constant touched position is detected.
Register Number = 0x06
7
6
5
4
3
2
1
0
0
0
0
R
Movement timeout
W
Reset:
0
0
0
0
0
Figure 3-29. Movement Timeout register
Touch Sensing Software API Reference Manual, Rev. 8
3-40
Freescale Semiconductor
Application Interface
Table 3-28. Movement Timeout register description
Signal
Description
Movement
Timeout
3.7.11
Determines how many execution times the decoder must detect that there is no displacement before reporting no
movement and a hold event.
0 — No limit established. Movement is reported until the control is detected as idle.
1–254 — Reports a hold event after n task executions.
Callback function
The decoder module calls this function if an event occurs and the user enables the callback function.
Callback functions are assigned to controls in the system setup module. One callback may be assigned to
several different controls in the system.
Function prototype
void CallbackFuncName(uint8_t u8ControlId)
The CallbackFuncName for each control is defined in the following TSS_SystemSetup.h file macro:
#define TSS_Cn_CALLBACK fCallBack3
/* Identifier of the user's callback */
Where:
• n is the number of the control
• fCallBack3 is a name example
Input parameters
Type
uint8_t
Name
u8ControlId
Valid Range/Values
Any valid Control ID of any
control in the system.
Description
This parameter indicates which control
generates the event. This parameter
matches the controlled field in the control
C&S structure.
Return value
None
3.8
Analog slider and analog rotary decoder API
This section describes the API for the analog slider and the analog rotary decoder. Because the analog
rotary decoder API is similar to the analog slider, this section describes both the analog slider decoder and
differences between the two. The TSS_SetASliderConfig() and TSS_ASetRotaryConfig() function are
used to write to the decoder registers. The TSS_GetASliderConfig() and TSS_GetARotaryConfig() are
used for reading the registers. This section describes the callback function and its parameters for an analog
slider and a analog rotary control. Each application analog slider and an analog rotary control has the
corresponding Configuration and Status registers and a callback function.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-41
Application Interface
3.8.1
Writing to the Configuration and Status registers
To change values in the Configuration and Status register, call the TSS_SetSystemConfig function. This
function is declared in the TSS_API.h file.
Function prototype for Analog Slider
uint8_t TSS_SetASliderConfig (TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter, uint8_t
u8Value)
Function prototype for Analog Rotary
uint8_t TSS_SetARotaryConfig (TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter, uint8_t
u8Value)
Input parameters
Type
Name
Valid range and values
Description
TSS_CONTROL_ID
u8ControlId
Any valid control Id of the
appropriate control type
Identifier of the control
configured which is stored in the
first element of the control’s C&S
structure.
uint8_t
u8Parameter
Any of the parameter codes
provided by the decoder
Code indicating the parameter
configured
uint8_t
u8Value
Depends on the specific
parameter configured
New desired value, for the
respective configuration registers
Return value for Analog Slider
The return value is an unsigned integer with the following possible return values defined in the file
TSS_StatusCodes.h.
Return Value
Description
TSS_STATUS_OK
Configuration is executed successfully.
TSS_ERROR_ASLIDER_ILLEGAL_PARAMETER
Configuration is not executed because of the illegal parameter
number.
TSS_ERROR_ASLIDER_ILLEGAL_VALUE
Configuration is not executed because of the illegal value.
TSS_ERROR_ASLIDER_READ_ONLY_PARAMETER
Configuration is not executed whenever the user attempts to modify
a read-only parameter.
TSS_ERROR_ASLIDER_ILLEGAL_VALUE
Configuration is not executed because of the illegal value number.
TSS_ERROR_ASLIDER_OUT_OF_RANGE
Configuration is not executed because the new value was out of
range of the established boundaries.
TSS_ERROR_ASLIDER_ILLEGAL_CONTROL_TYPE
Configuration is not executed because the u8ControlId parameter
does not match the control type structure that the user is trying to
modify.
Return value for Analog Rotary
The return value is an unsigned integer with the following possible return values defined in the file
TSS_StatusCodes.h.
Touch Sensing Software API Reference Manual, Rev. 8
3-42
Freescale Semiconductor
Application Interface
Return Value
Description
TSS_STATUS_OK
Configuration is executed successfully.
TSS_ERROR_AROTARY_ILLEGAL_PARAMETER
Configuration is not executed because of the illegal parameter
number.
TSS_ERROR_AROTARY_ILLEGAL_VALUE
Configuration is not executed because of the illegal value.
TSS_ERROR_AROTARY_READ_ONLY_PARAMETER
Configuration is not executed whenever the user attempts to modify
a read-only parameter.
TSS_ERROR_AROTARY_ILLEGAL_VALUE
Configuration is not executed because of the illegal value number.
TSS_ERROR_AROTARY_OUT_OF_RANGE
Configuration is not executed because the new value is out of range
of the established boundaries.
TSS_ERROR_AROTARY_ILLEGAL_CONTROL_TYPE
Configuration is not executed because the u8ControlId parameter
does not match the control type structure that the user is trying to
modify.
3.8.2
Reading the Configuration and Status registers
The two options to access the rotary Configuration and Status register structure involve using the TSS
function declared in the TSS_API.h file and directly accessing the configuration and status structure for
specific data. The following content describes the first option.
Function prototype for Analog Slider
uint8_t TSS_GetASliderConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter);
Function prototype for Analog Rotary
uint8_t TSS_GetARotaryConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter);
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-43
Application Interface
Input parameters
Type
Name
Valid range/values
Description
TSS_CONTROL_ID
u8ControlId
Any valid control Id of the
appropriate control type
Identifier of the control
configured which is stored in the
first element of the control C&S
structure.
uint8_t
u8Parameter
Any of the parameter codes
provided by each decoder
Code indicating the parameter
configured
Return value
The return value corresponds either to a control register unsigned byte value specified by the u8Parameter,
or to error values defined in the file TSS_StatusCodes.h:
Return Value
Description
Any valid unsigned byte value
Value corresponds to an unsigned byte value of a register
specified by the u8Parameter.
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Read is not successful because of the illegal parameter.
TSS_ERROR_GETCONF_ILLEGAL_CONTROL_TYPE
Read is not successful because of the illegal control type.
The second option enables direct access to the configuration and status structure for specific data. The
application defines the structure name in the TSS_SystemSetup.h file by using the following definition:
#define TSS_Cn_STRUCTURE
cStructure
Where n is the control number starting from 0 going up to the number of controls minus one.
The cStructure name is an example. The user can define any other name for each control configuration and
status structure.
typedef struct{
const TSS_CONTROL_ID ControlId;
const TSS_ASLIDER_CONTROL ControlConfig;
const TSS_ASLIDER_DYN DynamicStatus;
const uint8_t Position;
const TSS_ASLIDER_EVENTS Events;
const uint8_t AutoRepeatRate;
const uint8_t MovementTimeout;
const uint8_t Range;
} TSS_CSASlider;
typedef struct{
const TSS_CONTROL_ID ControlId;
const TSS_ASLIDER_CONTROL ControlConfig;
const TSS_ASLIDER_DYN DynamicStatus;
const uint8_t Position;
const TSS_ASLIDER_EVENTS Events;
const uint8_t AutoRepeatRate;
//Note 1
//Note 2
//Note 3
//Note 4
//Note 1
//Note 2
//Note 3
//Note 4
Touch Sensing Software API Reference Manual, Rev. 8
3-44
Freescale Semiconductor
Application Interface
const uint8_t MovementTimeout;
const uint8_t Range;
} TSS_CSARotary;
1.
2.
3.
4.
NOTE
The TSS_CONTROL_ID type is an eight bit-field structure described in Section 3.8.4, “Control
ID register".”
The TSS_ASLIDER_CONTROL type is an eight bit-field structure described in Section 3.8.5,
“Control configuration".”
The TSS_ASLIDER_DYN type is an eight bit-field structure described in Section 3.8.6, “Dynamic
Status register"”
The TSS_ASLIDER_EVENTS type is an eight bit-field structure described in Section 3.8.8,
“Events Control register"”
The following command is an example to read the Control ID:
Temp = cStructure.ControlId;
3.8.3
Configuration and Status registers list
The following table shows the control Configuration and Status registers.
Table 3-29. Control Configuration and Status registers
Register
Number
Size [bytes]
Register Name
Section
Initial value
Brief Description
0x00
1
ControlId
Section 3.8.4,
“Control ID
register"”
Application
dependable
R — Displays the control
type and control number
0x01
1
ControlConfig
Section 3.8.5,
“Control
configuration"”
0x00
RW — This register
configures overall enablers
of the object
0x02
1
DynamicStatus
Section 3.8.6,
“Dynamic Status
register"”
0x00
R — Displays movement,
direction, and
displacement information
0x03
1
Position
Section 3.8.7,
“Position register"”
0x00
R — Displays absolute
position information
within a defined range.
0x04
1
Events
Section 3.8.8,
“Events Control
register"”
0x00
RW — Configures the
events that execute the
callback function.
0x05
1
AutoRepeatRate
Section 3.8.9,
“Auto-repeat Rate
register"”
0x00
RW — Configures the rate
at which keys are reported
when they are kept pressed
and no movement is
detected.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-45
Application Interface
Table 3-29. Control Configuration and Status registers (continued)
Register
Number
Size [bytes]
Register Name
Section
Initial value
Brief Description
0x06
1
MovementTimeout
Section 3.8.10,
0x00
“Movement Timeout
register"”
RW — Number of times
the decoder must detect a
no-displacement before
reporting a hold event and
no movement.
0x07
1
Range
Section 3.8.11,
“Range register"”
RW - Defines the absolute
range within the position.
3.8.4
0x40
Control ID register
This read-only register contains the control identifier code.
Register Number = 0x00
7
R
6
5
4
3
Control Type
2
1
0
Control Number
W
Reset:
1
—1
—
—
—
—
—
—
—
Application dependable.
Figure 3-30. Control ID register
Encoding
Control Type
001
Keypad
010
Slider
011
Rotary
100
Analog slider
101
Analog rotary
110
Matrix
111
Reserved
NOTE
The control number is assigned in the system setup module. This value is
unique for all controls, indicating that each control has a particular number
regardless of its type. The first assigned control number is zero.
3.8.5
Control configuration
This register configures overall enablers of the object.
Touch Sensing Software API Reference Manual, Rev. 8
3-46
Freescale Semiconductor
Application Interface
Register Number = 0x01
7
6
5
4
3
2
1
0
Control Enabler
Callback
Enabler
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
0
0
-
-
-
-
-
-
R
W
Reset:
Figure 3-31. Control Configuration register
Table 3-30. Control configuration description
Signal
Description
Control Enabler Global enabler for the control. This determines if the control electrodes are scanned for detection. The bit enables
or disables all control electrodes in the Electrode enablers register.
1 — Control enabled
0 — Control disabled
Callback
Enabler
3.8.6
Enables or disables the use of the callback function. If it is enabled, the function is called whenever an active event
in the Events Configuration registers occurs.
1 — Callback enabled
0 — Callback disabled
Dynamic Status register
This register describes the movement over the electrodes which are assigned to the controller.
Register Number = 0x02
7
R Movement Flag
6
5
4
3
Direction
2
1
0
0
0
0
Displacement
W
Reset:
0
0
0
0
0
Figure 3-32. Dynamic Status register
Table 3-31. Dynamic Status register description
Signal
Description
Movement
Indicates whether the movement is being detected at the moment of reading.
1 — Movement detected
0 — Movement not detected
Direction
Indicates the direction of the movement. This bit remains with its last value even if movement has stopped and is
no longer detected.
1 — Incremental (from PositionX to PositionY, where X< Y)
0 — Decremental (from PositionX to PositionY, where X> Y)
Displacement
This value indicates the difference in positions from the last status to the new status. This indicates how many
positions are advanced in the current movement direction.
0–63 — Number of positions.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-47
Application Interface
3.8.7
Position register
The Position register contains an absolute position within a defined range.
Register Number = 0x03
7
6
5
4
R
3
2
1
0
0
0
0
0
Position
W
Reset:
0
0
0
0
Figure 3-33. Static Status register
Table 3-32. Position register description
Signal
Description
Position
3.8.8
Indicates the calculated absolute position within a defined range.
0—Range - Number of the actual position
Events Control register
The Event Control register contains the bits used to enable or disable events that call the control callback
function.
Register Number = 0x05
7
6
5
4
Touch
Invalid
Position
Reserved
Release
Event
Enabler
0
0
-
0
R
W
Reset:
3
2
Hold AutoHold Event
Repeat Enabler
Enabler
0
0
1
0
Movement
Event
Enabler
Initial Touch
Event
Enabler
0
0
Figure 3-34. Events Control register
Table 3-33. Events Control register description
Signal
Touch
Description
This bit indicates whether the touch is detected on the control.
1 — Touch detected
0 — Touch not detected
Invalid Position Indicates whether an invalid combination of touched electrodes is being detected.
1 — Invalid position detected
0 — Invalid position not detected
Release Event If this bit is set and the callback function is enabled, the callback is called when all touched electrodes in the control
Enabler
are released.
1 — Release event enabled
0 — Release event disabled
Touch Sensing Software API Reference Manual, Rev. 8
3-48
Freescale Semiconductor
Application Interface
Table 3-33. Events Control register description
Signal
Description
Hold
Auto-repeat
Enabler
If this bit is set, the hold event enabler and the callback function are enabled and the callback is called at the rate
specified in the Auto-repeat Rate register as long as one valid position is detected as touched in the control and no
movement is detected.
1 — Auto-repeat feature enabled
0 — Auto-repeat disabled
Hold Event
Enabler
If this bit is set and the callback function enabled, the decoder calls the control callback function when the movement
stops and, after a certain period of time, a constant touched position is detected. This time is configurable in the
Movement Timeout Register.
1 — Event enabled
0 — Event disabled
Movement
If this bit is set and the callback function enabled, the decoder calls the control callback function each time a
Event Enabler displacement is detected.
1 — Event enabled
0 — Event disabled
Initial Touch If this bit is set and the callback function enabled, the decoder calls the control callback function whenever the
Event Enabler control transitions from an idle to an active state.
1 — Event enabled
0 — Event disabled
NOTE
If the events are not enabled, the control is automatically disabled and must
be re-enabled by the user in the Control Configuration Register.
3.8.9
Auto-repeat Rate register
The Auto-repeat Rate register contains the rate value whereby a hold event is reported when kept pressed
without movement.
Register Number = 0x05
7
6
5
4
3
2
1
0
0
0
0
R
Auto-repeat start
W
Reset:
0
0
0
0
0
Figure 3-35. Auto-repeat Rate register
Table 3-34. Auto-repeat Rate register description
Signal
Auto-repeat
Rate
Description
The decoder calls the control callback function at the specified rate as long as a valid position is continuously
detected, the auto-repeat feature is enabled, and no displacement occurs. If this register is set to zero (0), the
auto-repeat feature will be disabled in the events register.
0 — Auto-repeat feature disabled
1–254 — Callback is called every n task executions
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-49
Application Interface
NOTE
The Auto-repeat function works only if a hold event is presented. The hold
event is delayed by the Movement Timeout function. If the Movement
Timeout register is set to zero (0), the Auto-repeat function stops to generate
a callback, because the hold event is no longer reported.
3.8.10
Movement Timeout register
The register value defines how long the movement event stays reported after a hold event is detected. The
delay is defined in number of TSS_Task() executions. The hold event indicates an instance when the
movement stops and a constant touched position is detected.
Register Number = 0x06
7
6
5
4
3
2
1
0
0
0
0
R
Movement timeout
W
Reset:
0
0
0
0
0
Figure 3-36. Movement Timeout register
Table 3-35. Movement Timeout register description
Signal
Description
Movement
Timeout
Determines how many execution times the decoder must detect a no-displacement before reporting no movement
and a hold event.
0 — No limit established. Movement is reported until the control is detected to be idle.
1–254 — Reports a hold event after n task executions.
3.8.11
Range register
The range register value defines the absolute range within the position.
Register Number = 0x06
7
6
5
4
3
2
1
0
0
0
0
0
R
Range
W
Reset:
0
1
0
0
Figure 3-37. Range register
Touch Sensing Software API Reference Manual, Rev. 8
3-50
Freescale Semiconductor
Application Interface
Table 3-36. Range register description
Signal
Description
Range
3.8.12
Defines the absolute range within the position.
2— 255 for Analog slider
3— 255 for Analog rotary
Callback function
The decoder module calls this function if an event occurs and if the user enables the callback function.
Callback functions are assigned to controls in the system setup module. One callback may be assigned to
several different controls in the system.
Function prototype
void CallbackFuncName(uint8_t u8ControlId)
The CallbackFuncName for each control is defined in the following TSS_SystemSetup.h file macro:
#define TSS_Cn_CALLBACK fCallBack4
Where:
• n is the number of the control
• fCallBack4 is a name example
Input parameters
Type
uint8_t
Name
u8ControlId
Valid range/values
Any valid control ID of any
control in the system
Description
It indicates the control that
generates the event. This
parameter matches the controlled
field in the control C&S register.
Return value
None
3.9
Matrix decoder API
This section describes Matrix Decoder API, Matrix C&S registers, the TSS_SetMatrixConfig() function
used to write to these registers, and the TSS_GetMatrixConfig() function and data structure used for
reading the register. This section also describes the callback function and its parameters for a Matrix
control. Each Application Matrix control has corresponding Configuration and Status registers and a
callback function.
3.9.1
Writing to the Configuration and Status registers
To change values in the Configuration and Status register, call the TSS_SetSystemConfig function. This
function is declared in the TSS_API.h file.
Function prototype
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-51
Application Interface
uint8_t TSS_SetMatrixConfig (TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter, uint8_t
u8Value)
Input parameters
Type
Name
Valid range and values
Description
TSS_CONTROL_ID
u8ControlId
Any valid control Id of the
appropriate control type
Identifier of the control
configured which is stored in the
first element of the control’s C&S
structure.
uint8_t
u8Parameter
Any of the parameter codes
provided by matrix decoder
Code indicating the parameter
configured
uint8_t
u8Value
Depends on the specific
parameter configured
New desired value for the
respective configuration registers
Return value
The return value is an unsigned integer with the following possible return values defined in the file
TSS_StatusCodes.h.
Return Value
Description
TSS_STATUS_OK
Configuration is executed successfully.
TSS_ERROR_MATRIX_ILLEGAL_PARAMETER
Configuration is not executed because of the illegal parameter
number.
TSS_ERROR_MATRIX_ILLEGAL_VALUE
Configuration is not executed because of the illegal value.
TSS_ERROR_MATRIX_READ_ONLY_PARAMETER
Configuration is not executed whenever the user attempts to modify
a read-only parameter.
TSS_ERROR_MATRIX_ILLEGAL_VALUE
Configuration is not executed becaus of the illegal value number.
TSS_ERROR_MATRIX_OUT_OF_RANGE
Configuration is not executed because the new value is out of range
of the established boundaries
TSS_ERROR_MATRIX_ILLEGAL_CONTROL_TYPE
Configuration is not executed because the u8ControlId parameter
does not match the control type structure the user is trying to modify.
3.9.2
Reading the Configuration and Status registers
The two options to access the Configuration and Status register structure involve using the TSS function
declared in the TSS_API.h file and directly accessing the configuration and status structure for specific
data. The following content describes the first option.
Function prototype
uint8_t TSS_GetMatrixConfig(TSS_CONTROL_ID u8ControlId, uint8_t u8Parameter);
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
3-52
Freescale Semiconductor
Application Interface
Return value
Type
Name
Valid range/values
TSS_CONTROL_ID u8ControlId
uint8_t
u8Parameter
Description
Any valid control Id of the
appropriate control type
Identifier of the control
configured, stored in the first
element of the control’s C&S
structure
Any of the parameter codes
provided by each decoder
Code indicating the parameter
configured
Return value
The return value corresponds either to a control register unsigned byte value specified by the u8Parameter,
or to error values defined in the file TSS_StatusCodes.h:
Return Value
Description
Any valid unsigned byte value
Value corresponds to a register unsigned byte value
specified by the u8Parameter.
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Read is not successful because of the illegal parameter.
TSS_ERROR_GETCONF_ILLEGAL_CONTROL_TYPE
Read is not successful because of the illegal control type.
The second option to access the Configuration and Status register structure involves direct access to the
configuration and status structure for specific data. The application defines the structure name in the
TSS_SystemSetup.h file by using the following definition:
#define TSS_Cn_STRUCTURE
cMatrix
Where n is the control number starting from zero (0) going up to the number of controls minus one.
The cMatrix name is an example. The user can define any other name for each control configuration and
status structure.
typedef struct{
const TSS_CONTROL_ID ControlId;
const TSS_MATRIX_CONTROL ControlConfig;
const TSS_MATRIX_EVENTS Events;
const uint8_t AutoRepeatRate;
const uint8_t MovementTimeout;
const TSS_MATRIX_DYN DynamicStatusX;
const TSS_MATRIX_DYN DynamicStatusY;
const uint8_t PositionX;
const uint8_t PositionY;
const uint8_t GestureDistanceX;
const uint8_t GestureDistanceY;
const uint8_t RangeX;
const uint8_t RangeY;
} TSS_CSMatrix
//Note 1
//Note 2
//Note 3
//Note 4
NOTE
1. The TSS_CONTROL_ID type is an eight bit-field structure described in Section 3.9.4, “Control
ID register"”
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-53
Application Interface
2. The TSS_MATRIX_CONTROL type is an eight bit-field structure described in Section 3.9.5,
“Control configuration"”
3. The TSS_MATRIX_EVENTS type is an eight bit-field structure described in Section 3.9.6,
“Events Control register"”
4. The TSS_MATRIX_DYN type is an eight bit-field structure described in Section 3.9.9, “Dynamic
Status X register"”
Using the example of the structure named cMatrix, to read Control ID use:
Temp = cMatrix.ControlId;
3.9.3
Configuration and Status registers list
The following table describes the matrix control configuration and status registers.
Table 3-37. Matrix Control Configuration and Status registers
Register
Number
Size [bytes]
Register Name
Section
Initial value
Brief Description
0x00
1
ControlId
Section 3.9.4,
“Control ID
register"”
Application
dependable
R — Displays the control
type and control number.
0x01
1
ControlConfig
Section 3.9.5,
“Control
configuration"”
0x00
RW — This register
configures overall enablers
of the object.
0x02
1
Events
Section 3.9.6,
“Events Control
register"”
0x00
RW — Configures the
events that call the callback
function.
0x03
1
AutoRepeatRate
Section 3.9.7,
“Auto-repeat Rate
register"”
0x00
RW — Configures the rate
at which keys are reported
when they are kept pressed
and no movement is
detected.
0x04
1
MovementTimeout
Section 3.9.8,
0x00
“Movement Timeout
register"”
RW — Number of times
the decoder must detect a
no-displacement before
reporting a hold event and
no movement.
0x05
1
DynamicStatusX
Section 3.9.9,
“Dynamic Status X
register"”
0x00
R — Displays movement,
direction, and
displacement information
on the X axis
0x06
1
DynamicStatusY
Section 3.9.10,
“Dynamic Status Y
register"”
0x00
R — Displays movement,
direction, and
displacement information
on the Y axis
0x07
1
PositionX
Section 3.9.11,
“Position X
register"”
0x00
R — Displays absolute
position information
within a defined range on
the X axis.
Touch Sensing Software API Reference Manual, Rev. 8
3-54
Freescale Semiconductor
Application Interface
Table 3-37. Matrix Control Configuration and Status registers (continued)
Register
Number
Size [bytes]
Register Name
Section
Initial value
Brief Description
0x08
1
PositionY
Section 3.9.12,
“Position Y
register"”
0x00
R — Displays absolute
position information
within a defined range on
the Y axis.
0x09
1
GestureDistanceX
Section 3.9.13,
“Gesture distance X
register"”
0x00
R — Displays relative
distance between two or
more positions within a
defined range on the X
axis.
0x0A
1
GestureDistanceY
Section 3.9.14,
“Gesture distance Y
register"”
0x00
R — Displays relative
distance between two or
more positions within a
defined range on the Y
axis.
0x0B
1
RangeX
Section 3.9.15,
“Range X register"”
0x40
R — Defines the absolute
range on the X axis.
0x0C
1
RangeY
Section 3.9.15,
“Range X register"”
0x40
R — Defines the absolute
range on the Y axis
3.9.4
Control ID register
This read-only register contains the control identifier code.
Register Number = 0x00
7
R
6
5
4
3
Control Type
2
1
0
Control Number
W
Reset:
1
—1
—
—
—
—
—
—
—
Application dependable.
Figure 3-38. Control ID register
Encoding
Control Type
001
Keypad
010
Slider
011
Rotary
100
Analog slider
101
Analog rotary
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-55
Application Interface
Encoding
Control Type
100
Matrix
111
Reserved
NOTE
The control number is assigned in the system setup module. This value is
unique for all controls, indicating that each control has a particular number
regardless of its type. The first assigned control number is zero.
3.9.5
Control configuration
This register configures overall enablers of the object.
Register Number = 0x01
7
6
5
4
3
2
1
0
Control Enabler
Callback
Enabler
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
0
0
0
0
0
0
0
0
R
W
Reset:
Figure 3-39. Control Configuration register
Table 3-38. Control configuration description
Signal
Description
Control Enabler Global control enabler. This determines whether the control electrodes are scanned for detection. The bit enables or
disables all control electrodes in the Electrode enablers register.
1 — Control enabled
0 — Control disabled
Callback
Enabler
3.9.6
Enables or disables the use of the callback function. If it is enabled, the function is called when one of the active
events in the Events Configuration registers occurs.
1 — Callback enabled
0 — Callback disabled
Events Control register
The Event Control register contains the bits used to enable or disable events that call the control callback
function.
Touch Sensing Software API Reference Manual, Rev. 8
3-56
Freescale Semiconductor
Application Interface
Register Number = 0x02
7
6
5
4
Touch
Gesture
Gestures
Enabler
Release
Event
Enabler
0
0
0
0
R
W
Reset:
3
2
Hold AutoHold Event
Repeat Enabler
Enabler
0
0
1
0
Movement
Event
Enabler
Initial Touch
Event
Enabler
0
0
Figure 3-40. Events Control register
Table 3-39. Events Control register description
Signal
Touch
Description
This bit indicates whether the touch has been detected on the control.
1 — Touch detected
0 — Touch not detected
Gesture
This bit indicates whether the gesture has been detected on the control. The gesture is reported if at least two isolated
touches are detected within the control.
1 — Gesture detected
0 — Gesture not detected
Gestures
Enabler
If this bit is set, the gesture evaluation is enabled and the information about gesture starts writing into the Gesture
Distance registers. This option also enables generating callbacks on all enabled events. However, the event source
is Gesture Distance register and not the Position register.
1 — Gestures enabled
0 — Gestures disabled
Release Event If this bit is set and the callback function is enabled, the callback is called when all touched electrodes in the control
Enabler
are released.
1 — Release event enabled
0 — Release event disabled
Hold
Auto-repeat
Enabler
If this bit is set, the hold event enabler and the callback function are enabled, the callback is called at the rate
specified in the Auto-repeat Rate register as long as one valid position is detected as touched in the control and no
movement is detected.
1 — Auto-repeat feature enabled
0 — Auto-repeat disabled
Hold Event
Enabler
If this bit is set and the callback function enabled, the decoder calls the control callback function when the movement
stops and a constant touched position is detected after a certain period of time. This time is configurable in the
Movement Timeout Register.
1 — Event enabled
0 — Event disabled
Movement
If this bit is set and the callback function enabled, the decoder calls the control callback function every time a
Event Enabler displacement is detected.
1 — Event enabled
0 — Event disabled
Initial Touch If this bit is set and the callback function enabled, the decoder calls the control callback function when the control
Event Enabler transitions from an idle to an active state.
1 — Event enabled
0 — Event disabled
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-57
Application Interface
NOTE
If no events are enabled, the control is automatically disabled and must be
re-enabled by the user in the Control Configuration Register.
3.9.7
Auto-repeat Rate register
The Auto-repeat Rate register contains the rate value where a hold event is reported when kept pressed
without movement.
Register Number = 0x03
7
6
5
4
3
2
1
0
0
0
0
R
Auto-repeat start
W
Reset:
0
0
0
0
0
Figure 3-41. Auto-repeat Rate register
Table 3-40. Auto-repeat Rate register description
Signal
Description
Auto-repeat
Rate
The decoder calls the control callback function at the specified rate as long as a valid position is continuously
detected, the auto-repeat feature is enabled and no displacement occurs. If this register is set to zero (0), the
auto-repeat feature is disabled in the events register.
0 — Auto-repeat feature disabled
1–254 — Callback is called every n task executions
NOTE
The Auto-repeat function works only if a hold event is presented. The hold
event is delayed by the Movement Timeout function. If the Movement
Timeout register is set to zero (0), the Auto-repeat function stops to generate
a callback, because the Hold event is no longer reported.
3.9.8
Movement Timeout register
The register value defines how long the movement event stays reported after a hold event is detected. The
delay is defined in a number of TSS_Task() executions. The hold event represents an instance when the
movement stops and a constant touched position is detected.
Register Number = 0x04
7
6
5
4
3
2
1
0
0
0
0
R
Movement timeout
W
Reset:
0
0
0
0
0
Figure 3-42. Movement Timeout register
Touch Sensing Software API Reference Manual, Rev. 8
3-58
Freescale Semiconductor
Application Interface
Table 3-41. Movement Timeout register description
Signal
Description
Movement
Timeout
Determines how many execution times the decoder must detect a no-displacement before reporting no movement
and reporting a hold event.
0 — No limit established. Movement is reported until the control is detected as idle.
1–254 — Reports a hold event after n task executions.
3.9.9
Dynamic Status X register
This register describes the movement on the horizontal X axis over the electrodes assigned to the control.
The information is based on a Position X or a Gesture Distance X register information.
Register Number = 0x05
7
R Movement Flag
6
5
4
3
Direction
2
1
0
0
0
0
Displacement
W
Reset:
0
0
0
0
0
Figure 3-43. Dynamic Status X register
Table 3-42. Dynamic Status X register description
Signal
Description
Movement
Indicates if any movement on the X axis is being detected at the moment of reading.
1 — Movement detected
0 — Movement not detected
Direction
Indicates the direction of the movement on X axis. This bit remains with its last value even if movement has stopped
and is no longer detected.
1 — Incremental (from PositionN to PositionM, where N < M)
0 — Decremental (from PositionN to PisitionM, where N > M)
Displacement
This value indicates the difference in positions on X axis from the last status to the new status. This indicates how
many positions have been advanced in the current movement direction.
0–63 — Number of positions.
3.9.10
Dynamic Status Y register
This register describes the movement on Y vertical axis over the electrodes assigned to the control. The
information is based on a position Y or a gesture distance Y register information.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-59
Application Interface
Register Number = 0x06
7
R Movement Flag
6
5
4
3
Direction
2
1
0
0
0
0
Displacement
W
Reset:
0
0
0
0
0
Figure 3-44. Dynamic Status Y register
Table 3-43. Dynamic Status Y register description
Signal
Description
Movement
Indicates whether any movement on Y axis is being detected at the moment of reading.
1 — Movement detected
0 — Movement not detected
Direction
Indicates the movement direction on Y axis. This bit remains with its last value even if movement has stopped and
is no longer detected.
1 — Incremental (from PositionN to PositionM, where N < M)
0 — Decremental (from PositionN to PisitionM, where N > M)
Displacement
This value indicates the difference in positions on Y axis from the last status to the new status. This indicates how
many positions have been advanced in the current movement direction.
0–63 — Number of positions.
3.9.11
Position X register
This Position X register contains an absolute analog position within a defined range on X horizontal axis.
Register Number = 0x07
7
6
5
4
R
3
2
1
0
0
0
0
0
Position X
W
Reset:
0
0
0
0
Figure 3-45. Position X register
Table 3-44. Position X register description
Signal
Description
Position
3.9.12
Indicates the calculated absolute analog position within a defined range.
0—Range - Number of the actual position
Position Y register
The Position Y register contains an absolute analog position within a defined range on Y vertical axis.
Touch Sensing Software API Reference Manual, Rev. 8
3-60
Freescale Semiconductor
Application Interface
Register Number = 0x08
7
6
5
4
R
3
2
1
0
0
0
0
0
Position Y
W
Reset:
0
0
0
0
Figure 3-46. Position Y register
Table 3-45. Position Y register description
Signal
Description
Position
3.9.13
Indicates the calculated absolute analog position within a defined range.
0—Range - Number of the actual position
Gesture distance X register
The Gesture Distance X register contains a calculated maximum distance between gesture analog positions
on X horizontal axis. The gesture event is reported if at least two isolated touches are detected within a
control range.
Register Number = 0x09
7
6
5
R
4
3
2
1
0
0
0
0
Gesture Distance X
W
Reset:
0
0
0
0
0
Figure 3-47. Gesture Distance X register
Table 3-46. Gesture Distance X register description
Signal
Description
Position
3.9.14
Indicates a calculated maximum distance between gesture analog positions on X horizontal axis.
0—Range - Number of the actual position
Gesture distance Y register
The Gesture Distance Y register contains a calculated maximum distance between gesture analog positions
on Y vertical axis. The gesture event is reported if at least two isolated touches are detected within a control
range.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-61
Application Interface
Register Number = 0x09
7
6
5
R
4
3
2
1
0
0
0
0
Gesture Distance Y
W
Reset:
0
0
0
0
0
Figure 3-48. Gesture Distance Y register
Table 3-47. Gesture Distance Y register description
Signal
Description
Position
3.9.15
Indicates calculated maximum distance between gesture analog positions on Y vertical axis.
0—Range - Number of the actual position
Range X register
The range register value defines the absolute range within the position on X horizontal axis.
Register Number = 0x06
7
6
5
4
3
2
1
0
0
0
0
0
R
Range X
W
Reset:
0
1
0
0
Figure 3-49. Range X register
Table 3-48. Range X register description
Signal
Range
3.9.16
Description
Defines the absolute range within the position on X horizontal axis.
2— 255 - Range value
Range Y register
The range register value defines the absolute range within the position on Y vertical axis.
Register Number = 0x06
7
6
5
4
3
2
1
0
0
0
0
0
R
Range Y
W
Reset:
0
1
0
0
Figure 3-50. Range Y register
Touch Sensing Software API Reference Manual, Rev. 8
3-62
Freescale Semiconductor
Application Interface
Table 3-49. Range Y register description
Signal
Description
Range
3.9.17
Defines the absolute range within the position on Y vertical axis.
2— 255 - Range value
Matrix callback function
The decoder module calls this function if an event occurs and the user enables the callback function.
Callback functions are assigned to controls in the system setup module. One callback may be assigned to
several different controls in the system.
Function prototype
void CallbackFuncName(uint8_t u8ControlId)
The CallbackFuncName for each control is defined in the following TSS_SystemSetup.h file macro:
#define TSS_Cn_CALLBACK fCallBack5
Where:
• n is the number of the control
• fCallBack5 is a name example
Input parameters
Type
uint8_t
Name
u8ControlId
Valid range/values
Any valid control ID of any
control in the system
Description
It indicates the control that
generates the event. This
parameter matches the controlled
field in the control C&S register.
Return value
None
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
3-63
Application Interface
Touch Sensing Software API Reference Manual, Rev. 8
3-64
Freescale Semiconductor
Library Intermediate Layer Interfaces
Chapter 4
Library Intermediate Layer Interfaces
The TSS library architecture supports module implementation depending on the application requirements.
Applications can be customized by using a suitable library layer. To implement modules, it is necessary to
understand how modules exchange information and communicate with each other. This section describes
the parameters and functions used by the library to establish communication between layers. For more
details about the TSS library architecture, see Section 1.3, “Library architecture.”
4.1
Capacitive sensing and key detector interface
The capacitive sensing layer senses each electrode declared in the system. Based on the information
provided by the capacitive sensing layer, the key detector layer determines whether an electrode is being
pressed or not. Table 4-1 shows the global value where the charging time is stored.
Table 4-1. Global variable description
Parameter
tss_u16CapSample
Description
Global 16 bits variable used to store the electrode charging time.
The tss_u16CapSample global variable passes the acquired sensing data from the capacitive sensing layer
to the key detector layer. When the capacitive sensing layer senses an electrode, it stores the charging time
information in the tss_u16CapSample global variable. To use a custom capacitive sensing module, the
acquired value from the sensing module is passed to the upper layer by storing this value in the
tss_u16CapSample global variable.
4.1.1
Electrode sampling
The exchange of information between the capacitive sensing and key detector layers is accomplished by
using the sensing function.
Function prototype
uint8_t (* const tss_faSampleElectrode[])(uint8_t u8ElecNum, uint8_t u8Command)
Function description
The key detector layer calls the sensing function each time it needs to sense an electrode. The
function
uint8_t (* const tss_faSampleElectrode[])(uint8_t u8ElecNum, uint8_t u8Command)
is used to select the appropriate sensing function according to the defined low level method (TSI,
GPIO, etc.) The sensing function allows both layers to exchange parameters. When the key
detector layer calls this function, it provides the electrode number that needs to be scanned and a
command for a measurement routine. When the sensing is completed, the capacitive sensing layer
returns the sensing state to the upper layer.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
4-1
Library Intermediate Layer Interfaces
Input parameters
Type
Name
Valid range/values
Description
uint8_t
u8ElecNum
Any valid Electrode number
Number of electrodes to be scanned by the
capacitive sensing layer
uint8_t
u8Command
Any valid command:
TSS_SAMPLE_COMMAND_DUMMY
TSS_SAMPLE_COMMAND_RESTART
TSS_SAMPLE_COMMAND_PROCESS
TSS_SAMPLE_COMMAND_RECALIB
TSS_SAMPLE_COMMAND_GET_NEXT_ELECTRODE
TSS_SAMPLE_COMMAND_ENABLE_ELECTRODE
TSS_SAMPLE_COMMAND_RESTART_NOISE
TSS_SAMPLE_COMMAND_GET_NOISE_VALUE
TSS_SAMPLE_COMMAND_SET_LOWLEVEL_CONFIG
TSS_SAMPLE_COMMAND_GET_LOWLEVEL_CONFIG
These commands are used for
management of the measurement process
and setting of the electrode from the upper
level.
Return value
The function returns the resulting status of the electrode sensing to the key detector layer.
Possible return values are described below:
Return Value
Description
TSS_SAMPLE_STATUS_OK
Electrode sensing is successfully executed.
TSS_SAMPLE_STATUS_PROCESSING
The electrode sensing process is still running.
TSS_SAMPLE_STATUS_CALIBRATION_CHANGED
Electrode is recalibrated
TSS_SAMPLE_RECALIB_REQUEST_LOCAP
Electrode sensing is not successful becacuse of the small
capacitance. Hardware recalibration is needed. If the TSI method is
used, the measured signal is below 20% of the required TSI
resolution.
TSS_SAMPLE_RECALIB_REQUEST_HICAP
Electrode sensing is not successful done because of the high
capacitance. Hardware recalibration is needed. If the TSI method is
used, the measured signal is higher than 0xFFFF minus the 20% of
required TSI resolution.
TSS_SAMPLE_ERROR_SMALL_TRIGGER_PERIOD
A small trigger period is detected.
TSS_SAMPLE_ERROR_CHARGE_TIMEOUT
Electrode sensing is not successful because of the charge timeout.
TSS_SAMPLE_ERROR_SMALL_CAP
Electrode sensing is not successful because of the small capacity.
TSS_SAMPLE_ERROR_RESULT_NA
A requested value, or a feature is not available.
When an error occurs, the key detector layer determines whether the sense capacitance was too small or
too large, whether the hardware recalibration is needed, or whether another, non-standard, state is detected.
4.1.2
Low-level initialization
The initialization of low level hardware from the Key Detector layers is performed by the Sensor Init
function.
Touch Sensing Software API Reference Manual, Rev. 8
4-2
Freescale Semiconductor
Library Intermediate Layer Interfaces
Function prototype
uint8_t TSS_SensorInit(uint8_t u8Command)
Function description
The key detector layer calls the Sensor Init function each time it needs to change either the
configuration of the low level hardware or an electrode. The function uint8_t
TSS_SensorInit(uint8_t u8Command) is used to reconfigure the entire low level, all electrodes,
regardless of the measurement method. The Sensor Init function allows both layers to exchange
parameters. When the key detector layer calls this function, it provides a command for this
function. When the configuration of low level is completed, the Sensor Init function returns the
state to the upper layer.
Input parameters
Type
uint8_t
Name
u8Command
Valid range/values
Description
Any valid command:
• TSS_INIT_COMMAND_DUMMY
• TSS_INIT_COMMAND_INIT_MODULES
• TSS_INIT_COMMAND_ENABLE_ELECTRODES
• TSS_INIT_COMMAND_SET_NSAMPLES
• TSS_INIT_COMMAND_INIT_TRIGGER
• TSS_INIT_COMMAND_SW_TRIGGER
• TSS_INIT_COMMAND_INIT_LOWPOWER
• TSS_INIT_COMMAND_GOTO_LOWPOWER
• TSS_INIT_COMMAND_RECALIBRATE
• TSS_INIT_COMMAND_ENABLE_LOWPOWER_CALIB
• TSS_INIT_COMMAND_MODE_CAP
• TSS_INIT_COMMAND_MODE_NOISE
• TSS_INIT_COMMAND_MODE_GET
These commands are used to set the entire
low level hardware from the upper level.
Return value
The function returns the resulting status of the configuration to the key detector layer.
Possible return values are described below.
Return Value
Description
TSS_INIT_STATUS_OK
Configuration is successful.
TSS_INIT_STATUS_LOWPOWER_SET
Configuration of Low Power function is successful.
TSS_INIT_STATUS_LOWPOWER_ELEC_SET
Configuration of Low Power electrode is successful.
TSS_INIT_STATUS_TRIGGER_SET
Configuration of Trigger is successful.
TSS_INIT_STATUS_AUTOTRIGGER_SET
Configuration of Auto Trigger mode is successful.
TSS_INIT_STATUS_CALIBRATION_CHANGED
Calibration is changed.
TSS_INIT_ERROR_RECALIB_FAULT
Calibration is unsuccessful.
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
4-3
Library Intermediate Layer Interfaces
4.2
Decoder interface
The decoders provide the highest level of abstraction in the library. In this layer, the key detector
information about touched and untouched electrodes is interpreted to present the control status in a
behavioral way. Decoder-related code exists only once in memory. Decoders are similar to classes of an
object oriented language. Because each control has a decoder associated with it, the control becomes an
instance of the decoder (an object). However, not all decoders are necessarily instantiated in every system.
The TSS library supports Rotary, Slider, Analog rotary, Analog slider, Matrix, and Keypad inside the
precompiled library files. Additionally, there is an interface to support other decoders externally. For more
information about the decoder functionality, see the Touch Sensing User Guide.
4.2.1
Decoder main function
The exchange of information between the decoder and key detector layer is performed by using the
following function.
Function prototype
uint8_t (* const tss_faDecoders[])(uint8_t u8CtrlNum, uint16_t u16TouchFlag, uint8_t
u8NumberOfElec, uint8_t u8Command)
Function description
The key detector layer calls the decoder function everytime electrodes are measured. The decoder
function allows both layers to exchange parameters. When the key detector layer calls this
function, it provides the control number which is processed, pointer to the data which provides the
electrode state information with signal change, and a command. When the decoder function
finishes processing, it returns the status to the lower layer.
The electrode state buffer always provides a pointer to the data of the electrodes related to the
control. The data consists of two 16-bit variables. The first variable provides information about the
touch state of the electrodes in the form of bit flags relative to the control (logic one is touch state,
zero is release state). The second variable provides information about the signal change of the
electrodes in the form of bit flags relative to the control (logic one represents signal change).
Input parameters
Type
Name
Valid range/values
Description
uint8_t
u8CtrlNum
Any valid control number
Number of control to be processed
uint16_t
u16TouchFlag
16 bit mask
Unsigned integer variable where each
bit represents touch status of electrodes
assigned to the control
uint8_t
u8NumberOfElec
1 - 16
Number of electrodes assigned to the
control
uint8_t
u8Command
Any valid command:
TSS_DECODER_COMMAND_DUMMY
TSS_DECODER_COMMAND_PROCESS
TSS_DECODER_COMMAND_INIT
These commands are used for decoder
process management and decoder
setting from lower level
Return value
Touch Sensing Software API Reference Manual, Rev. 8
4-4
Freescale Semiconductor
Library Intermediate Layer Interfaces
The function returns the resulting status of the decoder to the key detector layer.
Possible return values are described below:
Return Value
Description
TSS_DECODER_STATUS_OK
Decoder processing successfully finished
TSS_DECODER_ERROR_ILLEGAL_CONTROL_TYPE
Called decoder type does not match with control type
TSS_DECODER_STATUS_BUSY
Decoder is not ready to perform processing.
4.2.2
Writing the decoder schedule counter
The Key Detector provides an internal counter that can schedule decoder calls periodically after a defined
number of TSS_Task measurement cycles. The initialization of the control schedule counter is performed
by this function.
Function prototype
void TSS_KeyDetectorSetControlScheduleCounter(uint8_t u8CntrlNum, uint8_t u8Value)
Function description
The key detector layer decrements the control schedule counter after each electrode measurement
cycle is finished.
Input parameters
Type
Name
Valid range/values
Description
uint8_t
u8CntrlNum
Any valid control number
Control index
uint8_t
u8Value
1-255
Number of TSS_Task measurement cycles
Return value
None
4.2.3
Reading the decoder schedule counter
The key detector provides an internal counter that can schedule a decoder call after a defined number of
TSS_Task measurement cycles. The status of this counter can be read by this function.
Function prototype
uint8_t TSS_KeyDetectorGetControlScheduleCounter(uint8_t u8CntrlNum)
Function description
The key detector layer decrements control schedule counter after each measurement cycle. The
function returns actual state of the counter
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
4-5
Library Intermediate Layer Interfaces
Type
Name
uint8_t
u8CntrlNum
Valid range/values
Any valid control number
Description
Control index
Return value
The status of the control schedule counter.
4.2.4
Reading the instant delta in the control
The key detector provides information about the electrode instant delta value.
Function prototype
int8_t TSS_KeyDetectorGetInstantDelta(uint8_t u8ElecNum)
Function description
The function returns instant delta value for a defined electrode.
Input parameters
Type
uint8_t
Name
u8ElecNum
Valid range/values
Any valid electrode number
Description
Number of instant delta electrode
Return value
The instant delta value of a defined electrode.
Touch Sensing Software API Reference Manual, Rev. 8
4-6
Freescale Semiconductor
Chapter 5
C++ wrapper
This chapter describes the C++ wrapper of the TSS library. It extends the C library with simplified API.
This API makes usaging the TSS more convenient.
All definitions are contained within namespace called “tss”. Doxygen documentation is part of all headers.
The definition of available flags, constants, and commands are in TSS_cpp_const header file.
The following are the application requirements:
• If any control is used, TSS_USE_CONTROL_PRIVATE_DATA should be enabled. It’s used to
store the C++ “this” pointer for a control.
• Faults are managed by callbackFaultHelper function which should be set as onFault callback
• Each control should register callbackControlHelper function as general control callback
5.1
TSSSystem class
Class TSSSystem represents the main TSS class used for system configuration. Because this class is a
singleton, only one instance of the TSSSystem exists in an application.
This class provides the API for configuring the TSS. A TSSSystem object can be used without any controls
(polling electrode status method).
5.1.1
TSSTask
The TSSTask method should be periodically called to provide a CPU time to the TSS.
Function prototype
static uint8_t TSSTask(void)
Function description
Static method which invokes the library TSS_Task() function.
Input parameters
None
Return value
The return value is uint8_t with the following possible return values:
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-1
C++ wrapper
Return Value
Description
TSS_STATUS_OK
TSS task finished the measurement of all electrodes and has
evaluated the values
TSS_STATUS_PROCESSING
Measurement of electrodes in progress or the TSS task has not
finished the evaluation
5.1.2
isElecTouched
Returns boolean value if the specified electrode is touched.
Function prototype
bool isElecTouched(uint8_t elec_num) const
Input parameters
Type
Name
uint8_t
elec_num
Valid Range and Values
0 - TSS_N_ELECTRODES
Description
The number of the electrode to be checked
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
An electrode is touched
false
An electrode is released
5.1.3
isElecEnabled
Returns boolean value if the specified electrode is enabled.
Function prototype
bool isElecEnabled(uint8_t elec_num) const
Input parameters
Type
uint8_t
Name
elec_num
Valid Range and Values
0 - TSS_N_ELECTRODES
Description
The number of the electrode to be checked
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
An electrode is enabled
false
An electrode is disabled
Touch Sensing Software API Reference Manual, Rev. 8
5-2
Freescale Semiconductor
C++ wrapper
5.1.4
enableElec
Enables the specified electrode.
Function prototype
bool enableElec(uint8_t elec_num)
Input parameters
Type
Name
uint8_t
elec_num
Valid Range and Values
0 - TSS_N_ELECTRODES
Description
The number of the electrode to be enabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The electrode is enabled.
false
Failed
5.1.5
disableElec
Disables the specified electrode.
Function prototype
bool disableElec(uint8_t elec_num)
Input parameters
Type
Name
uint8_t
elec_num
Valid Range and Values
0 - TSS_N_ELECTRODES
Description
The number of the electrode to be disabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The electrode is disabled.
false
Failed
5.1.6
setSensitivity
Sets a sensitivity value for a specified electrode.
Function prototype
bool setSensitivity(uint8_t elec_num, uint8_t value)
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-3
C++ wrapper
Type
Name
Valid Range and Values
Description
uint8_t
elec_num
0 - TSS_N_ELECTRODES
The number of the electrode
uint8_t
value
1-127
The sensitivity value to be set
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The sensitivity is set.
false
Failed
5.1.7
getSensitivity
Retrieves a sensitivity value for a specified electrode.
Function prototype
uint8_t getSensitivity(uint8_t elec_num)
Input parameters
Type
uint8_t
Name
elec_num
Valid Range and Values
0 - TSS_N_ELECTRODES
Description
The number of an electrode.
Return value
The return value is uint16_t with the following possible return values:
Return Value
Description
0
Non-valid value
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Bad parameter
A value between 2-127
Returned sensitivity value
5.1.8
enableDCTracker
Enables DC tracker for the specified electrode.
Function prototype
bool enableDCTracker(uint8_t elec_num)
Input parameters
Type
uint8_t
Name
elec_num
Valid Range and Values
0 - TSS_N_ELECTRODES
Description
The number of the electrode
Return value
Touch Sensing Software API Reference Manual, Rev. 8
5-4
Freescale Semiconductor
C++ wrapper
The return value is boolean with the following possible return values:
Return Value
Description
true
The DC tracker is enabled for a specified electrode
false
Failed
5.1.9
disableDCTracker
Disables DC tracker for a specified electrode.
Function prototype
bool disableDCTracker(uint8_t elec_num)
Input parameters
Type
Name
uint8_t
elec_num
Valid Range and Values
0 - TSS_N_ELECTRODES
Description
The number of the electrode
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The DC tracker is disabled for the specified electrode.
false
Failed
5.1.10
setBaseline
Sets a baseline for the specified electrode.
Function prototype
bool setBaseline(uint8_t elec_num, uint16_t value)
Input parameters
Type
uint8_t
Name
elec_num
uint16_t value
Valid Range and Values
Description
0 - TSS_N_ELECTRODES
The number of the electrode
0 - UINT16 MAX
The baseline value
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The baseline is set.
false
Failed
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-5
C++ wrapper
5.1.11
getBaseline
Returns a value of the baseline for a specified electrode.
Function prototype
uint16_t getBaseline(uint8_t elec_num)
Input parameters
Type
Name
uint8_t
elec_num
Valid Range and Values
0 - TSS_N_ELECTRODES
Description
The number of the electrode
Return value
The return value is boolean with the following possible return values:
Return Value
Description
1 - UINT16 MAX
The baseline value
0
Failed
5.1.12
enable
Enables TSS System features.
Function prototype
bool enable(TSSSystemFlag flag)
Input parameters
Type
Name
TSSSys flag
temFla
g
Valid Range and Values
TSSSystemFlag enum values
Description
The TSS System feature to be enabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The feature is set.
false
Failed
5.1.13
disable
Disables TSS System features.
Function prototype
bool disable(TSSSystemFlag flag)
Touch Sensing Software API Reference Manual, Rev. 8
5-6
Freescale Semiconductor
C++ wrapper
Input parameters
Type
Name
TSSSys flag
temFla
g
Valid Range and Values
TSSSystemFlag enum values
Description
The TSS System feature to be disabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The feature is set.
false
Failed
5.1.14
set
Sets a specified value in the TSS System register.
Function prototype
bool set(TSSSystemConfig command, uint8_t value)
Input parameters
Type
Name
Valid Range and Values
Description
TSSSys command
temCon
fig
TSSSystemConfig enum value
The TSS System register to be set
uint8_t
Valid range for the specific register
The value to be stored
value
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The register value is updated.
false
Failed
5.1.15
get
Retrieves a specified value from the TSS System register.
Function prototype
uint16_t get(TSSSystemConfig command)
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-7
C++ wrapper
Type
Name
TSSSys command
temCon
fig
Valid Range and Values
TSSSystemConfig enum value
Description
The TSS System register to be retrieved
Return value
The return value corresponds to an actual uint16_t value of a register specified by the first parameter - the
command.
5.1.16
callbackSysFaults
This is a callback which invokes the user’s fault callback and the onFault callback if an error occurs.
Function prototype
void callbackSysFaults(TSSSystemEvent event, uint8_t elec_num)
Input parameters
Type
Name
Valid Range and Values
Description
TSSSyst event
emEvent
TSSSystemEvent enum value
A specific error which has occurred.
uint8_t
0 - TSS_N_ELECTRODES
The electrode number
elec_num
Return value
None
5.1.17
onFault
This is a virtual callback which invokes the user’s callback and the onFault callback if an error occurs.
Function prototype
virtual void onFault(TSSSystemEvent event, uint8_t elec_num)
Input parameters
Type
Name
Valid Range and Values
Description
TSSSyst event
emEvent
TSSSystemEvent enum value
A specific fault which has occurred
uint8_t
0 - TSS_N_ELECTRODES
The electrode number
elec_num
Return value
None
Touch Sensing Software API Reference Manual, Rev. 8
5-8
Freescale Semiconductor
C++ wrapper
5.1.18
regCallback
This method registers user callback for a specified event.
Function prototype
bool regCallback(TSS_fSystemCallback callback, TSSSystemEvent state)
Input parameters
Type
Name
Valid Range and Values
Description
TSS_fS callback
ystemC
allbac
k
Pointer to a function
A function invoked when a specified state occurs
TSSSys state
temEve
nt
One of values from TSSSystemEvent
The TSS System’s event to be registered
Return value
None
5.1.19
unregCallback
This method unregisters user callback for a specified event.
Function prototype
bool unregCallback(TSSSystemEvent state)
Input parameters
Type
Name
TSSSys state
temEve
nt
Valid Range and Values
One of values from TSSSystemEvent
Description
The TSS System event to be unregistered
Return value
None
5.2
TSSControlFactory class
Class TSSControlFactory is a factory interface for handling TSS controls.
5.2.1
createTSSControl
Creates new class which represents the TSS control or returns pointer to an already created class.
Function prototype
static TSSControl* createTSSControl(uint8_t control_number = 0)
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-9
C++ wrapper
Input parameters
Type
Name
uint8_ control_nu
t
mber
Valid Range and Values
0-15
Description
The control number which corresponds to a control in the
TSSSystemSetup header file
Return value
A pointer to the newly created class which represents the TSS control.
5.2.2
getTSSControl
This method returns a pointer to the existing class representing the TSS control.
Function prototype
static TSSControl* getTSSControl(uint8_t control_number)
Input parameters
Type
Name
uint8_ control_nu
t
mber
Valid Range and Values
0-15
Description
The control number which corresponds to a control in the
TSSSystemSetup header file
Return value
A pointer to the existing class representing the TSS control.
5.3
TSSControl class
TSSControl class defines an interface for TSS controls. This is a base class for specific TSS control
classes. It does not provide any registration of callbacks because they are specific for each type of control.
See a specific control class for implementation.
5.3.1
callbackControl
An interface for a specific callback handler for a control.
Function prototype
virtual void callbackControl(void) = 0
Input parameters
None
Return value
None
Touch Sensing Software API Reference Manual, Rev. 8
5-10
Freescale Semiconductor
C++ wrapper
5.3.2
enable
An interface to enable specific control flags.
Function prototype
virtual bool enable(TSSControlFlag flag) = 0
Input parameters
Type
Name
TSSCon flag
trolFl
ag
Valid Range and Values
One of values from TSSControlFlag
Description
TSSControlFlag to be enabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated
false
Failed
5.3.3
disable
An interface to disable specific control flags.
Function prototype
virtual bool disable(TSSControlFlag flag) = 0
Input parameters
Type
Name
TSSCon flag
trolFl
ag
Valid Range and Values
One of values from TSSControlFlag
Description
TSSControlFlag to be disabled
Return value
The return value is a bool with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-11
C++ wrapper
5.3.4
set
An interface to set specific control flags.
Function prototype
virtual bool set(TSSControlConfig config, uint8_t value) = 0
Input parameters
Type
Name
Valid Range and Values
Description
TSSCon config
trolFl
ag
One of values from TSSControlFlag
TSSControlFlag to be disabled
uint8_ value
t
A valid value for specific control flag
The value to be set
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
5.3.5
get
An interface to get specific control flags.
Function prototype
virtual uint16_t get(TSSControlConfig config) const = 0
Input parameters
Type
Name
TSSCon config
trolFl
ag
Valid Range and Values
One of values from TSSControlFlag
Description
TSSControlFlag to be retrieved
Return value
The return value is uint16_t with the following possible return values:
Touch Sensing Software API Reference Manual, Rev. 8
5-12
Freescale Semiconductor
C++ wrapper
Return Value
Description
A valid value
A returned value is valid.
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Failed
5.4
TSSKeypad class
The class TSSKeypad defines the implementation of the keypad control.
5.4.1
callbackControl
This is the callback handler for the keypad control.
Function prototype
virtual void callbackControl(void)
Input parameters
None
Return value
None
5.4.2
enable
A method to enable the keypad control flag.
Function prototype
bool enable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFlag
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the keypad control
Description
TSSControlFlag to be enabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-13
C++ wrapper
5.4.3
disable
A method to disable the keypad control flag.
Function prototype
bool disable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFl
ag
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the keypad control
Description
TSSControlFlag to be disabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
5.4.4
set
A method to set the keypad control values.
Function prototype
virtual bool set(TSSControlConfig command, uint8_t value) = 0
Input parameters
Type
Name
Valid Range and Values
Description
TSSCon command
trolFlag
One of the values from the TSSControlFlag
which is valid for the keypad control
TSSControlFlag to be disabled
uint8_t
A valid value for specific control flag
The value to be set
value
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The value is updated.
false
Failed
Touch Sensing Software API Reference Manual, Rev. 8
5-14
Freescale Semiconductor
C++ wrapper
5.4.5
get
A method to retrieve the keypad control value.
Function prototype
virtual uint16_t get(TSSControlConfig config) const
Input parameters
Type
Name
TSSCon config
trolConf
ig
Valid Range and Values
One of values from TSSControlFlag which is
valid for the keypad control
Description
TSSControlFlag to be retrieved
Return value
The return value is uint16_t with the following possible return values:
Return Value
Description
A valid value
A returned value is valid.
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Failed
5.4.6
getControlStruct
A method which returns a pointer to the keypad control structure.
Function prototype
const TSS_CSKeypad* getControlStruct(void) const
Input parameters
None
Return value
A pointer to the Keypad control structure.
5.4.7
regCallback
This method registers user callback for a specified event.
Function prototype
bool regCallback(fKeypadCallback callback, KeypadEvent state)
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-15
C++ wrapper
Type
Name
Valid Range and Values
Description
fKeypad callback
Callback
Pointer to a function
A function to be invoked when the specified state occurs
Keypad
Event
One of values from KeypadEvent
The keypad event to be registered
state
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback is registered.
false
Failed
5.4.8
unregCallback
This method unregisters user callback for a specified event.
Function prototype
bool unregCallback(KeypadEvent state)
Input parameters
Type
Name
TSSSyst state
emEvent
Valid Range and Values
One of the values from the KeypadEvent
Description
The keypad event to be unregistered
Return value
None
5.4.9
onTouch
A callback which is invoked when a touch flag is enabled and a touch event occurs .
Function prototype
virtual void onTouch(uint8_t elec_num)
Input parameters
Type
uint8_t
Name
elec_num
Valid Range and Values
Within the number of electrodes defined in
System setup header file
Description
The number of the electrode
Return value
None
Touch Sensing Software API Reference Manual, Rev. 8
5-16
Freescale Semiconductor
C++ wrapper
5.4.10
onRelease
A callback which is invoked when the release flag is enabled and a release event occurrs .
Function prototype
virtual void onRelease(uint8_t elec_num)
Input parameters
Type
uint8_t
Name
elec_num
Valid Range and Values
Within the number of electrodes defined in
System setup header file
Description
The number of the electrode
Return value
None
5.4.11
onExceededKeys
A callback which is invoked when an exceeded flag is enabled and maximum touch regsiter value is
exceeded.
Function prototype
virtual void onExceededKeys(uint8_t max_touches)
Input parameters
Type
uint8_t
Name
max_touche
s
Valid Range and Values
0-255
Description
The number of the maximum touches register
Return value
None
5.5
TSSASlider class
The class TSSASlider defines the implementation of the slider control.
5.5.1
callbackControl
This is the callback handler for the analog slider control.
Function prototype
virtual void callbackControl(void)
Input parameters
None
Return value
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-17
C++ wrapper
None
5.5.2
enable
A method to enable the analog slider control flag.
Function prototype
bool enable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFlag
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the analog slider control
Description
TSSControlFlag to be enabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
5.5.3
disable
A method to disable the analog slider control flag.
Function prototype
bool disable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFl
ag
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the analog slider control
Description
TSSControlFlag to be disabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
Touch Sensing Software API Reference Manual, Rev. 8
5-18
Freescale Semiconductor
C++ wrapper
5.5.4
set
A method to set the analog slider control values.
Function prototype
virtual bool set(TSSControlConfig command, uint8_t value)
Input parameters
Type
Name
Valid Range and Values
Description
TSSCon command
trolFlag
One of the values from the TSSControlFlag
which is valid for the analog slider control
TSSControlFlag to be disabled
uint8_t
A valid value for analog slider control flag
The value to be set
value
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The value is updated.
false
Failed
5.5.5
get
A method to retrieve the analog slider control value.
Function prototype
virtual uint16_t get(TSSControlConfig config) const
Input parameters
Type
Name
TSSCon config
trolConf
ig
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the slider control
Description
TSSControlFlag to be retrieved
Return value
The return value is uint16_t with the following possible return values:
Return Value
Description
A valid value
A returned value is valid.
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Failed
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-19
C++ wrapper
5.5.6
getControlStruct
A method which returns a pointer to the control structure of the analog slider.
Function prototype
const TSS_CSASlider* getControlStruct(void) const
Input parameters
None
Return value
A pointer to the control structure of the analog slider.
5.5.7
regCallback
This method registers user callback for the specified event.
Function prototype
bool regCallback(fASliderCallback callback, ASliderEvent state)
Input parameters
Type
Name
Valid Range and Values
Description
fASlid callback
erCall
back
A pointer to a function
A function to be invoked when the specified state occurs
ASlide state
rEvent
One of values from ASliderEvent
An analog slider event to be registered
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback is registered.
false
Failed
5.5.8
unregCallback
This method unregisters user callback for a specified event.
Function prototype
bool unregCallback(ASliderEvent state)
Input parameters
Type
ASlider
Event
Name
state
Valid Range and Values
One of values from ASliderEvent
Description
The analog slider event to be unregistered
Touch Sensing Software API Reference Manual, Rev. 8
5-20
Freescale Semiconductor
C++ wrapper
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback is unregistered.
false
Failed
5.5.9
onInitialTouch
A callback which is invoked when the initial touch flag is enabled and an initial touch event occurrs .
Function prototype
virtual void onInitialTouch(uint8_t elec_num)
Input parameters
Type
uint8_t
Name
elec_num
Valid Range and Values
Within the number of electrodes defined in
System setup header file
Description
The number of the electrode
Return value
None
5.5.10
onAllRelease
A callback which is invoked when the release flag is enabled and all electrodes assigned to a control have
entered a release state.
Function prototype
virtual void onAllRelease(uint8_t position)
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
5.5.11
onMovement
A callback which is invoked when the movement flag is enabled and a movement has been detected.
Function prototype
virtual void onMovement(uint8_t position)
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-21
C++ wrapper
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
5.6
TSSARotary class
The class TSSARotary defines the implementation of the analog rotary control.
5.6.1
callbackControl
This is the callback handler for the analog rotary control.
Function prototype
virtual void callbackControl(void)
Input parameters
None
Return value
None
5.6.2
enable
A method to enable the control flag of the analog rotary.
Function prototype
bool enable(TSSControlFlag flag)
Input parameters
Type
TSSCon flag
trolFlag
Name
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the analog rotary control
Description
TSSControlFlag to be enabled
Return value
The return value is boolean with the following possible return values:
Touch Sensing Software API Reference Manual, Rev. 8
5-22
Freescale Semiconductor
C++ wrapper
Return Value
Description
true
The flag is updated.
false
Failed
5.6.3
disable
A method to disable the control flag of the analog rotary.
Function prototype
bool disable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFl
ag
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the analog rotary control
Description
TSSControlFlag to be disabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
5.6.4
set
A method to set the control value of the analog rotary.
Function prototype
virtual bool set(TSSControlConfig command, uint8_t value)
Input parameters
Type
Name
Valid Range and Values
Description
TSSCon command
trolFlag
One of the values from the TSSControlFlag
which is valid for the analog rotary control
TSSControlFlag to be disabled
uint8_t
A valid value for analog rotary control’s flag
The value to be set
value
Return value
The return value is boolean with the following possible return values:
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-23
C++ wrapper
Return Value
Description
true
The value is updated.
false
Failed
5.6.5
get
A method to retrieve the control value of the analog rotary.
Function prototype
virtual uint16_t get(TSSControlConfig config) const
Input parameters
Type
Name
TSSCon config
trolConf
ig
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the analog rotary control
Description
TSSControlFlag to be retrieved
Return value
The return value is uint16_t with the following possible return values:
Return Value
Description
A valid value
A returned value is valid.
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Failed
5.6.6
getControlStruct
A method which returns a pointer to the control structure of the analog rotary.
Function prototype
const TSS_CSARotary* getControlStruct(void) const
Input parameters
None
Return value
A pointer to the control strucutre of the analog rotary.
5.6.7
regCallback
This method registers user callback for a specified event.
Function prototype
bool regCallback(fARotaryCallback callback, ARotaryEvent state)
Touch Sensing Software API Reference Manual, Rev. 8
5-24
Freescale Semiconductor
C++ wrapper
Input parameters
Type
Name
Valid Range and Values
Description
fARotar callback
yCallbac
k
Pointer to a function
A function to be invoked when a specified state occurs
ARotary state
Event
One of values from ARotaryEvent
A rotary event to be registered
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback is registered.
false
Failed
5.6.8
unregCallback
This method unregisters the user callback for a specified event.
Function prototype
bool unregCallback(ARotaryEvent state)
Input parameters
Type
Name
ARotary state
Event
Valid Range and Values
One of the values from the ARotaryEvent
Description
The analog rotary event to be unregistered
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback is unregistered.
false
Failed
5.6.9
onInitialTouch
A callback which is invoked when the initial touch flag is enabled and an initial touch event occurs .
Function prototype
virtual void onInitialTouch(uint8_t elec_num)
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-25
C++ wrapper
Type
uint8_t
Name
elec_num
Valid Range and Values
Within the number of electrodes defined in
System setup header file
Description
The number of the electrode
Return value
None
5.6.10
onAllRelease
A callback which is invoked when the release flag is enabled and all electrodes assigned to a control enter
a release state.
Function prototype
virtual void onAllRelease(uint8_t position)
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
5.6.11
onMovement
A callback which is invoked when the movement flag is enabled and a movement is detected.
Function prototype
virtual void onMovement(uint8_t position)
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
5.7
TSSSlider class
The class TSSASlider defines the implementation of the slider control.
5.7.1
callbackControl
This is the callback handler for the slider control.
Touch Sensing Software API Reference Manual, Rev. 8
5-26
Freescale Semiconductor
C++ wrapper
Function prototype
virtual void callbackControl(void)
Input parameters
None
Return value
None
5.7.2
enable
A method to enable the control flag of the slider.
Function prototype
bool enable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFlag
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the slider control
Description
TSSControlFlag to be enabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
5.7.3
disable
A method to disable the slider control flag.
Function prototype
bool disable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFl
ag
Valid Range and Values
One of the values from the TSSControlFlag
which is valid for the slider control
Description
TSSControlFlag to be disabled
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-27
C++ wrapper
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag is updated.
false
Failed
5.7.4
set
A method to set the slider control values.
Function prototype
virtual bool set(TSSControlConfig command, uint8_t value)
Input parameters
Type
Name
Valid Range and Values
Description
TSSCon command
trolFlag
One of the values from the TSSControlFlag
which is valid for the slider control
TSSControlFlag to be disabled
uint8_t
A valid value for slider control’s flag
The value to be set
value
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The value was updated
false
Failed
5.7.5
get
A method to retrieve the slider’s control value.
Function prototype
virtual uint16_t get(TSSControlConfig config) const
Input parameters
Type
Name
TSSCon config
trolConf
ig
Valid Range and Values
One of values from TSSControlFlag which is
valid for the slider control
Description
TSSControlFlag to be retrieved
Touch Sensing Software API Reference Manual, Rev. 8
5-28
Freescale Semiconductor
C++ wrapper
Return value
The return value is uint16_t with the following possible return values:
Return Value
Description
A valid value
A returned value is valid
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Failed
5.7.6
getControlStruct
A method which returns a pointer to the slider’s control structure.
Function prototype
const TSS_CSSlider* getControlStruct(void) const
Input parameters
None
Return value
A pointer to the slider’s control structure.
5.7.7
regCallback
This method registers user’s callback for a specified event.
Function prototype
bool regCallback(fSliderCallback callback, SliderEvent state)
Input parameters
Type
Name
Valid Range and Values
Description
fSlide callback
rCallb
ack
A pointer to a function
A function to be invoked when the specified state occurs
Slider state
Event
One of values from SliderEvent
A slider’s event to be registered
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback was registered
false
Failed
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-29
C++ wrapper
5.7.8
unregCallback
This method unregisters user’s callback for a specified event.
Function prototype
bool unregCallback(SliderEvent state)
Input parameters
Type
Name
SliderEv state
ent
Valid Range and Values
One of values from SliderEvent
Description
A slider’s event to be unregistered
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback was unregistered
false
Failed
5.7.9
onInitialTouch
A callback which is invoked when the initial touch flag is enabled and an initial touch event has occurred .
Function prototype
virtual void onInitialTouch(uint8_t position)
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
5.7.10
onAllRelease
A callback which is invoked when the release flag is enabled and all electrodes assigned to a control has
gone to a release state.
Function prototype
virtual void onAllRelease(uint8_t position)
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
5-30
Freescale Semiconductor
C++ wrapper
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
5.7.11
onMovement
A callback which is invoked when the movement flag is enabled and a movement has been detected.
Function prototype
virtual void onMovement(uint8_t position)
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
5.8
TSSRotary class
The class TSSRotary defines the implementation of the rotary control.
5.8.1
callbackControl
This is the callback handler for the rotary control.
Function prototype
virtual void callbackControl(void)
Input parameters
None
Return value
None
5.8.2
enable
A method to enable the analog rotary’s control flag.
Function prototype
bool enable(TSSControlFlag flag)
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-31
C++ wrapper
Type
Name
TSSCon flag
trolFlag
Valid Range and Values
One of values from TSSControlFlag which is
valid for the analog rotary control
Description
TSSControlFlag to be enabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag was updated
false
Failed
5.8.3
disable
A method to disable the rotary’s control flag.
Function prototype
bool disable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFl
ag
Valid Range and Values
One of values from TSSControlFlag which is
valid for the analog rotary control
Description
TSSControlFlag to be disabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag was updated
false
Failed
5.8.4
set
A method to set the rotary’s control values.
Function prototype
virtual bool set(TSSControlConfig command, uint8_t value)
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
5-32
Freescale Semiconductor
C++ wrapper
Type
Name
Valid Range and Values
Description
TSSCon command
trolFlag
One of values from TSSControlFlag which is
valid for the rotary control
TSSControlFlag to be disabled
uint8_t
A valid value for rotary control’s flag
The value to be set
value
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The value was updated
false
Failed
5.8.5
get
A method to retrieve the rotary’s control value.
Function prototype
virtual uint16_t get(TSSControlConfig config) const
Input parameters
Type
Name
TSSCon config
trolConf
ig
Valid Range and Values
One of values from TSSControlFlag which is
valid for the rotary control
Description
TSSControlFlag to be retrieved
Return value
The return value is uint16_t with the following possible return values:
Return Value
Description
A valid value
A returned value is valid
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Failed
5.8.6
getControlStruct
A method which returns a pointer to the rotary’s control structure.
Function prototype
const TSS_CSRotary* getControlStruct(void) const
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-33
C++ wrapper
None
Return value
A pointer to the rotary’s control structure.
5.8.7
regCallback
This method registers user’s callback for a specified event.
Function prototype
bool regCallback(fRotaryCallback callback, ARotaryEvent state)
Input parameters
Type
Name
Valid Range and Values
Description
fRotary callback
Callback
The pointer to a function
The function to be invoked when the specified state occurs
RotaryE state
vent
One of values from RotaryEvent
The rotary’s event to be registered
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback was registered
false
Failed
5.8.8
unregCallback
This method unregisters user’s callback for a specified event.
Function prototype
bool unregCallback(RotaryEvent state)
Input parameters
Type
RotaryE state
vent
Name
Valid Range and Values
One of values from RotaryEvent
Description
A rotary’s event to be unregistered
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback was unregistered
false
Failed
Touch Sensing Software API Reference Manual, Rev. 8
5-34
Freescale Semiconductor
C++ wrapper
5.8.9
onInitialTouch
A callback which is invoked when the initial touch flag is enabled and an initial touch event has occurred .
Function prototype
virtual void onInitialTouch(uint8_t position)
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position of a control
Return value
None
5.8.10
onAllRelease
A callback which is invoked when the release flag is enabled and the last touched electrode has switched
back to a release state.
Function prototype
virtual void onAllRelease(uint8_t position)
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
5.8.11
onMovement
A callback which is invoked when a movement flag is enabled and a movement has been detected.
Function prototype
virtual void onMovement(uint8_t position)
Input parameters
Type
uint8_t
Name
position
Valid Range and Values
0-255
Description
The actual position
Return value
None
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-35
C++ wrapper
5.9
TSSMatrix class
The class TSSMatrix defines the implementation of the matrix control.
5.9.1
callbackControl
This is the callback handler for the matrix control.
Function prototype
virtual void callbackControl(void)
Input parameters
None
Return value
None
5.9.2
enable
A method to enable the matrix’s control flag.
Function prototype
bool enable(TSSControlFlag flag)
Input parameters
Type
Name
TSSCon flag
trolFlag
Valid Range and Values
One of values from TSSControlFlag which is
valid for the analog rotary control
Description
TSSControlFlag to be enabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag was updated
false
Failed
5.9.3
disable
A method to disable the matrix’s control flag.
Function prototype
bool disable(TSSControlFlag flag)
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
5-36
Freescale Semiconductor
C++ wrapper
Type
Name
TSSCon flag
trolFl
ag
Valid Range and Values
One of values from TSSControlFlag which is
valid for the matrix control
Description
TSSControlFlag to be disabled
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The flag was updated
false
Failed
5.9.4
set
A method to set the matrix’s control values.
Function prototype
virtual bool set(TSSControlConfig command, uint8_t value)
Input parameters
Type
Name
Valid Range and Values
Description
TSSCon command
trolFlag
One of values from TSSControlFlag which is
valid for the matrix control
TSSControlFlag to be disabled
uint8_t
A valid value for matrix control’s flag
The value to be set
value
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The value was updated
false
Failed
5.9.5
get
A method to retrieve the matrix’s control value.
Function prototype
virtual uint16_t get(TSSControlConfig config) const
Input parameters
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-37
C++ wrapper
Type
Name
TSSCon config
trolConf
ig
Valid Range and Values
One of values from TSSControlFlag which is
valid for the matrix control
Description
TSSControlFlag to be retrieved
Return value
The return value is uint16_t with the following possible return values:
Return Value
Description
A valid value
A returned value is valid
TSS_ERROR_GETCONF_ILLEGAL_PARAMETER
Failed
5.9.6
getControlStruct
A method which returns a pointer to the matrix’s control structure.
Function prototype
const TSS_CSMatrix* getControlStruct(void) const
Input parameters
None
Return value
A pointer to the rotary’s control structure.
5.9.7
regCallback
This method registers user’s callback for a specified event.
Function prototype
bool regCallback(fMatrixCallback callback, MatrixEvent state)
Input parameters
Type
Name
Valid Range and Values
Description
fMatrix callback
Callback
The pointer to a function
The function to be invoked when the specified state occurs
MatrixE state
vent
One of values from MatrixEvent
The rotary’s event to be registered
Return value
The return value is boolean with the following possible return values:
Touch Sensing Software API Reference Manual, Rev. 8
5-38
Freescale Semiconductor
C++ wrapper
Return Value
Description
true
The callback was registered
false
Failed
5.9.8
unregCallback
This method unregisters user’s callback for a specified event.
Function prototype
bool unregCallback(MatrixEvent state)
Input parameters
Type
Name
MatrixE state
vent
Valid Range and Values
One of values from MatrixEvent
Description
A matrix’s event to be unregistered
Return value
The return value is boolean with the following possible return values:
Return Value
Description
true
The callback was unregistered
false
Failed
5.9.9
onInitialTouch
A callback which is invoked when the initial touch flag is enabled and an initial touch event has occurred .
Function prototype
virtual void onInitialTouch(uint8_t position_x, uint8_t position_y)
Input parameters
Type
Name
Valid Range and Values
Description
uint8_t
position_x
0-255
The actual position on x axis
uint8_t
position_y
0-255
The actual position on y axis
Return value
None
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-39
C++ wrapper
5.9.10
onAllRelease
A callback which is invoked when the release flag is enabled and the last touched electrode has switched
back to a release state.
Function prototype
virtual void onAllRelease(uint8_t position_x, uint8_t position_y)
Input parameters
Type
Name
Valid Range and Values
Description
uint8_t
position_x
0-255
The actual position on x axis
uint8_t
position_y
0-255
The actual position on y axis
Return value
None
5.9.11
onMovement
A callback which is invoked when the movement flag is enabled and a movement has been detected.
Function prototype
virtual void onMovement(uint8_t position_x, uint8_t position_y)
Input parameters
Type
Name
Valid Range and Values
Description
uint8_t
position_x
0-255
The actual gesture’s position x
uint8_t
position_y
0-255
The actual gesture’s position y
Return value
None
5.9.12
onGestures
A callback which is invoked when the gesture flag is enabled and a gesture has been detected.
Function prototype
virtual void onGestures(uint8_t ges_distance_x, uint8_t ges_distance_y)
Input parameters
Type
Name
Valid Range and Values
Description
uint8_t
ges_distance_x 0-255
A gesture’s distance on x axis
uint8_t
ges_distance_y 0-255
A gesture’s distance on y axis
Touch Sensing Software API Reference Manual, Rev. 8
5-40
Freescale Semiconductor
C++ wrapper
Return value
None
Touch Sensing Software API Reference Manual, Rev. 8
Freescale Semiconductor
5-41
C++ wrapper
Touch Sensing Software API Reference Manual, Rev. 8
5-42
Freescale Semiconductor