AN44207 CapSense Express™ APIs for Register Configuration.pdf

THIS SPEC IS OBSOLETE
Spec No:
001-44207
Spec Title:
AN44207 - CAPSENSE EXPRESS(TM): APIS
FOR REGISTER CONFIGURATION
Replaced by: None
AN44207
CapSense Express™: APIs for Register Configuration
Associated Project: Yes
Associated Part Family: CY8C201xx
Software Version: PSoC Designer™ 5.0 SP6
Related Application Notes: For a complete list, click here.
To get the latest version of this application note, or the associated project file, please
visit http://www.cypress.com/go/AN44207.
AN44207 defines APIs for register configuration. These APIs are used to write to CapSense Express™ registers
through the host microcontroller when the CapSense Express slave device is on board.
Contents
1
2
3
4
5
6
7
1
Introduction ...............................................................1
High Level APIs ........................................................2
Low Level APIs ....................................................... 11
Command Execution .............................................. 12
Important Notes ...................................................... 13
Summary ................................................................ 14
Related Application Notes ...................................... 14
Document History............................................................ 15
Worldwide Sales and Design Support ............................. 16
Products .......................................................................... 16
PSoC® Solutions ............................................................. 16
Cypress Developer Community....................................... 16
Technical Support ........................................................... 16
Introduction
The CapSense Express device provides multifunctional, flexible, cost effective solutions for low IO capacitive sensing
applications. It supports IOs configurable as capacitive sensing inputs or as GPIOs for LED drive, interrupt output,
wakeup on interrupt input, and other digital IO functionalities. This device supports the I2C™ serial communication
interface.
The CapSense Express device is an I2C slave device. After the device is placed onto the system, it is possible to
reconfigure the device parameters through the host microcontroller, provided the host device can communicate through
an I2C bus.
This application note provides APIs that are called directly from the host microcontroller to configure or modify
CapSense Express slave device parameters. These APIs contain code for setting different parameters, which is
achieved by writing the required values to appropriate registers. It is not necessary to take the device out of the system
or make any external connections to write into the device registers and change its configuration. The values are written
directly by the host microcontroller which calls these APIs through its code.
APIs are used to configure the device, read back CapSense values, drive Outputs, and enable sleep.
The APIs described in this application note are divided into two categories according to the operations they perform:


High level APIs
Low level APIs
www.cypress.com
Document No. 001-44207 Rev. *E
1
CapSense Express™: APIs for Register Configuration
2
High Level APIs
High level APIs contain code to configure different parameters of the CapSense Express device. APIs perform different
functions such as enabling or disabling a CapSense pin or a GPIO, setting CapSense button or slider parameters,
configuring sleep, reading back CapSense values, changing I2C device address, and reading and writing to a particular
port.
Every high level API contains code to set the required parameter by writing to the appropriate CapSense Express
register. These APIs call the host IC hardware specific low level APIs. They then implement the physical I 2C
communication between the host microcontroller and the CapSense Express slave device.
The code in high level APIs is not hardware specific. The same APIs can be used in different hardware environments
without changing the code.
High level APIs are described in the following sections.
1
Prototype
Enable or disable the specified port pin as GPIO. A pin already enabled as CapSense input cannot be
enabled as GPIO using the API. The API returns a value of 0 if the pin cannot be enabled as GPIO;
otherwise, it enables or disables the pin and returns 1. The CapSense Express device must be in Setup
mode before enabling GPIO.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
bEnable
To enable or disable the selected GPIO
CE_ENABLE , CE_ DISABLE
Example
2
Prototype
CE_fEnableGPIO ( 0,1,CE_ENABLE ) enables port pin P0[1] as GPIO.
CE_fEnableGPIO ( 0,1,CE_DISABLE ) disables port pin P0[1].
CE_BOOL CE_fEnableCapSense( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bEnable );
Description
Enable or disable the specified port pin as CapSense input. A pin already enabled as GPIO cannot be
enabled as CapSense using the API. The API returns a value of 0 if the pin cannot be enabled as
CapSense; otherwise, it enables or disables the pin and returns 1. Make sure that the API is called before
calling the API for setting CapSense Finger Threshold and IDAC setting; otherwise, the values of Finger
Threshold and IDAC setting are reset. The CapSense express device must be in Setup mode before
enabling CapSense.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
bEnable
To enable or disable the selected CapSense
input
CE_ENABLE, CE_DISABLE
Example
3
CE_BOOL CE_fEnableGPIO( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bEnable );
Description
CE_fEnableCapSense ( 0,1,CE_ENABLE ) enables port pin P0[1] as CapSense.
CE_fEnableCapSense ( 0,1,CE_DISABLE ) disables port pin P0[1].
Prototype
CE_BOOL CE_fEnableSlider( CE_BYTE bEnable );
Description
Enable or disable the slider. The API returns a value of 0 if the slider is not enabled; otherwise, it enables
or disables the slider and returns 1.
Parameters
Name
Description
Possible Values
bEnable
To enable or disable the slider
CE_ENABLE , CE_DISABLE
Example
CE_EnableSlider ( CE_ENABLE ) enables the slider.
CE_EnableSlider ( CE_DISABLE ) disables the slider.
Example
CE_fEnableCapSense ( 0,1,CE_ENABLE ) enables port pin P0[1] as CapSense.
CE_fEnableCapSense ( 0,1,CE_DISABLE ) disables port pin P0[1].
www.cypress.com
Document No. 001-44207 Rev.*E
2
CapSense Express™: APIs for Register Configuration
4
Prototype
Description
Sets the drive mode for the selected GPIO. Possible values of drive mode are Resistive Pull Up, Strong,
High Impedance, and Open Drain Low. Note that the device must be in Setup mode before setting the
drive mode.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
bDriveMode
Drive mode for the selected GPIO
CE_PULL_UP , CE_ STRONG ,
CE_HIGH_IMPEDANCE ,
CE_OPEN_DRAIN_LOW.
Example
5
Prototype
void CE_SetPortInversion( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bPortInversion );
Inverts the logic of the input ports and status since last read registers.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
bPortinversion
Inversion logic for the selected pin
CE_INVERT ,CE_ NORMAL
Prototype
CE_SetPortInversion (0,1,CE_INVERT ) inverts the logic of port pin P0[1].
CE_SetPortInversion (0,1,CE_NORMAL ) makes the logic of the pin P0[1] as Normal (not inverted).
void CE_SetInterruptMask( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bInterruptMask );
Description
Sets which GPIO (not CapSense pins) generates hardware interrupts on 0-1 and 1-0 transitions. Its main
purpose is to enable wake up from sleep on GPIO changes. Note that the CapSense Express device
must be in Setup mode prior to setting the interrupt mask for GPIO.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
bInterruptMask
To set the interrupt mask for the selected pin
CE_ON , CE_OFF
Example
7
CE_SetDriveMode ( 0,1,STRONG ) sets the drive mode for P0 [1] as Strong.
Description
Example
6
void CE_SetDriveMode( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bDriveMode );
Prototype
CE_SetInterruptMask (0, 1, CE_ON) enables the interrupt for pin P0[1].
CE_SetInterruptMask (0, 1, CE_OFF) disables the interrupt for pin P0[1].
void CE_SetLatchDirection( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bLatchDirection );
Description
Defines which value (0 or 1) is held in Port status since last read registers.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
bLatchDirection
Latch direction for the selected GPIO
CE_FALLING ( latch ‘0’) ,
CE_RISING ( latch ‘1’)
Example
www.cypress.com
CE_SetLatchDirection (0, 2, CE_RISING) latches ‘1’ in the bit corresponding to P0[2] in Port status
since last read register for Port 0.
CE_SetLatchDirection (0, 2, CE_FALLING) latches ‘0’ in the bit corresponding to P0[2] in Port status
since last read register for Port 0.
Document No. 001-44207 Rev.*E
3
CapSense Express™: APIs for Register Configuration
8
Prototype
void CE_SetFingerThreshold( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bFingerThreshold
);
Description
Sets the value of Finger Threshold for the selected CapSense input. The API must be called after
calling the APIs for enabling CapSense, setting settling time, enabling sensor auto reset, enabling
external capacitor, and selecting clock; otherwise, the Finger Threshold value is reset.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
bFingerThreshold
Finger Threshold value
3–255
Example
9
Prototype
CE_SetFingerThreshold ( 1, 2, 100 );
void CE_SetIDACSetting( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bIDACSetting );
Description
Sets the value of IDAC setting for the selected CapSense pin. The API must be called after calling the
APIs for enabling CapSense, setting settling time, enabling sensor auto reset, enabling external
capacitor, and selecting clock; otherwise, the IDAC setting value is reset.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
bIDACSetting
IDAC setting value
1–255
Example
10
Prototype
CE_SetIDACSetting ( 1, 2,10 );
void CE_SetThresholds( CE_BYTE bNoiseThreshold , CE_BYTE bBaselineUpdateThreshold ,
CE_BYTE bNegativeNoiseThreshold , CE_BYTE bLowBaselineReset );
Description
Sets the values of Noise Threshold, Baseline Update Threshold, Negative Noise Threshold, and Low
Baseline Reset for the CapSense system.
Parameters
Name
Description
Possible Values
bNoiseThreshold
Noise Threshold value
3 to 255
bBaselineUpdateThreshold
Baseline Update Threshold
value
0 to 255
bNegativeNoiseThreshold
Negative Noise Threshold value
0 to 255
bLowBaselineReset
Low Baseline Reset value
0 to 255
Example
11
CE_SetThresholds ( 40,100,20,20 );
Prototype
void CE_SetSettlingTime( CE_BYTE bSettlingTime );
Description
Sets the value of the settling time. Make sure that the API is called before calling the API for setting
CapSense Finger Threshold and IDAC setting. Otherwise, the values of Finger Threshold and IDAC
setting are reset. Also note that the CapSense Express device must be in Setup mode before setting
the settling time.
Parameters
Name
Description
Possible Values
bSettlingTime
Settling time value
2–255
Example
12
CE_SetSettlingTime ( 160 );
Prototype
void CE_SetHysteresis( CE_BYTE bHysteresis );
Description
Sets the value of Hysteresis.
Parameters
Name
Description
Possible Values
bHysteresis
Hysteresis value
0 to 255
Example
www.cypress.com
CE_SetHysteresis ( 20 );
Document No. 001-44207 Rev.*E
4
CapSense Express™: APIs for Register Configuration
13
Prototype
void CE_SetDebounce( CE_BYTE bDebounce );
Description
Sets the value of Debounce counter.
Parameters
Name
Description
Possible Values
bDebounce
Debounce counter value
1 to 255
Example
14
CE_SetDebounce ( 3 );
Prototype
void CE_EnableSensorAutoReset( CE_BYTE bEnable );
Description
Decides whether to enable the sensor auto reset or not. If the baseline must be updated at all times,
then pass CE_ENABLE as the parameter to the API. If the baseline must be updated only when the
signal difference is below the noise threshold, then pass CE_DISABLE as the parameter to the API.
Before enabling or disabling the sensor auto reset, the Capsense Express device must be in Setup
mode.
Parameters
Name
Description
Possible Values
bEnable
To enable or disable sensor auto reset
CE_ENABLE, CE_DISABLE
Example
15
CE_EnableSensorAutoReset( CE_ENABLE ) enables sensor auto reset.
CE_EnableSensorAutoReset( CE_DISABLE ) disables sensor auto reset.
Prototype
Void CE_EnableExternalCapacitor( CE_BYTE bEnable );
Description
Selects whether to use the external integrating capacitor or internal capacitor. To configure this option,
the device must be in Setup mode.
Parameters
Name
Description
Possible Values
bEnable
To enable or disable the external
integrating capacitor
CE_ENABLE, CE_DISABLE
Example
16
CE_EnableExternalCapacitor ( CE_ENABLE ) enables the external integrating capacitor.
CE_EnableExternalCapacitor ( CE_DISABLE ) enables the internal capacitor.
Prototype
void CE_SelectClock( CE_BYTE bClock );
Description
Selects the CapSense module frequency of operation. The frequency can be set to IMO, IMO/2, IMO/4,
or IMO/8. Similar to the previous API, this API must only be called after setting the values of Finger
Threshold and IDAC setting for each CapSense button; otherwise, the values of Finger Threshold and
IDAC setting are reset. To set the clock frequency, the CapSense Express device must be in Setup
mode.
Parameters
Name
Description
Possible Values
bClock
CapSense module frequency of
operation
CE_IMO ,CE_ IMO_BY_2,
CE_ IMO_BY_4,
CE_ IMO_BY_8
Example
www.cypress.com
CE_SelectClock (CE_ IMO); sets the CapSense module frequency of operation to IMO.
CE_SelectClock (CE_IMO_BY_4); sets the CapSense module frequency of operation to IMO/4.
Document No. 001-44207 Rev.*E
5
CapSense Express™: APIs for Register Configuration
17
(a)
Prototype
Description
Sets the value of slider resolution to any value from 10 to 1000.
Parameters
Name
Description
Possible Values
WSliderResolution
Slider resolution value
10 to 1000
Example
17
(b)
void CE_SetSliderResolution1( CE_ WORD wSliderResolution );
CE_SetSliderResolution1( 100 );
Prototype
void CE_SetSliderResolution( CE_BYTE bSliderResolution );
Description
Sets the value of the slider resolution to any value among 50, 100, 150, 200, and 250.
This API is specially written for some commonly used values of resolution. Calling this API, the slider
resolution can be set to any of the values among 50, 100, 150, 200, and 250. The advantage of using
this API is that it contains a table look up for these values and so the time to execute the API reduces
drastically. For these values, use this API. If you need to set the slider resolution to any other value,
then you can use the other API described earlier. In the .c file provided with this application note, the
slider API described in 17(a) is commented; uncomment the API before using it.
Parameters
Name
Description
Possible Values
bSliderResolution
Slider resolution value
50,100,150,200,250.
Example
18
CE_SetSliderResolution ( 100 );
Prototype
void CE_ReadButtonValues ( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE *
abButtonReadBackValues );
Description
Reads the values of Baseline, Sensor Difference, and Result (Raw Count) for the specified CapSense
button. A pointer to a 6 byte array is passed as parameter to the API which receives the values of
Baseline, Sensor Difference, and Result in order.
Parameters
Name
Description
Possible Values
bPort
Port number
0,1
bPin
Pin number
0,1,2,3,4
abButtonReadBackVa
lues
Pointer to the 6 byte array
-
Example
www.cypress.com
CE_ReadButtonValues (1, 4, abButtonReadBackValues) reads the values for the button connected at
P1[4] and passes these values to abButtonReadBackValues (pointer to the 6 byte array).
Document No. 001-44207 Rev.*E
6
CapSense Express™: APIs for Register Configuration
19
Prototype
void CE_ReadButton( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bValue, CE_BYTE
*abButtonReadBackValue);
Description
Reads the value of Baseline, Sensor Difference, or Result for the selected CapSense button. A
pointer to a 2 byte array is passed as parameter to the API which receives the read value.
Parameters
Name
Description
Possible Values
bPort
Port number
0,1
bPin
Pin number
0,1,2,3,4
bValue
Value to read Baseline, Sensor
Difference, or Result
CE_BASELINE,CE_RESULT,
CE_SENSOR_DIFFERENCE,
CE_SENSOR_ON_STATUS
abButtonReadBackValue
Pointer to the 2 byte array
-
Example
20
CE_ReadButton (1, 4, CE_BASELINE, abButtonReadBackValue); reads the value of BASELINE for
the button connected at P1 [4] and passes this value to abButtonReadBackValue (pointer to the 2
byte array).
CE_ReadButton( 1,4,CE_RESULT, abButtonReadBackValue ); reads the value of RESULT ( Raw
Count ) for button connected at P1 [4] and passes this value to abButtonReadBackValue ( pointer to
the 2 byte array ).
Prototype
void CE_ReadSliderValues( CE_BYTE *abSliderReadBackValues );
Description
Reads the values of Centroid Position and Centroid Peak. A pointer to a 4 byte array is passed as
parameter to the API which receives the values of Centroid Position and Centroid Peak, in order.
Parameters
Name
Description
Possible Values
abSliderReadBackValues
Pointer to the 4 byte array
-
Example
21
CE_ReadSliderValues (abSliderReadBackValues); receives the values of Centroid Position and
Centroid Peak in order and passes it to abSliderReadBackValues.
Prototype
void CE_ReadDeviceIDStatus( CE_BYTE *abDeviceIDStatus );
Description
Reads device ID and status and passes the values to a pointer to a 2 byte array.
Parameters
Name
Description
Possible Values
abDeviceIDStatus
Pointer to the 2 byte array
-
Example
22
CE_ReadDeviceIDStatus( abDeviceIDStatus)
Prototype
CE_BYTE CE_bReadInputPort( CE_BYTE bPort );
Description
Reads input port and returns the value read.
Parameters
Name
Description
Possible Values
bPort
Port number
0,1
Example
23
CE_bReadInputPort (0); reads Port 0 and returns the value read.
CE_bReadInputPort (1); reads Port 1 and returns the value read.
Prototype
CE_BYTE CE_bReadPortStatus( CE_BYTE bPort );
Description
Reads the value in port status since last read registers and returns the value read.
Parameters
Name
Description
Possible Values
bPort
Port number
0,1
Example
www.cypress.com
CE_ bReadPortStatus (0) returns the value of port status since last register for Port 0.
CE_ bReadPortStatus (1) returns the value of port status since last register for Port 1.
Document No. 001-44207 Rev.*E
7
CapSense Express™: APIs for Register Configuration
24
Prototype
void CE_EnableOutputLogicOperation (CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bEnable);
Description
The function of this API is to decide whether to perform the operation as specified by the operation
select register on the specified GPIO. To enable the logic operation as specified by the operation select
register of the specified pin, pass CE_ENABLE as parameter to the API; to disable, pass
CE_DISABLE.
Parameters
Name
Description
Possible Values
bPort
Port number
0,1
bPin
Pin number
0,1,2,3,4
bEnable
Enable or disable
CE_ENABLE,CE_DISABLE
Example
25
CE_EnableOutputLogicOperation (0,0, CE_ENABLE) ; sets the logic at P0[0] as defined by the
operation select register for the selected GPIO.
Prototype
void CE_SetOutputLogic( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bLogic );
Description
Writes Logic 0 or Logic 1 to the specified GPIO.
Parameters
Name
Description
Possible Values
bPort
Port number
0,1
bPin
Pin number
0,1,2,3,4
bLogic
Logic 0 or Logic
1
CE_LOGIC_0 , CE_LOGIC_1
Example
26
CE_SetOutputLogic(0,0,CE_LOGIC_1); writes LOGIC 1 to P0 [0].
CE_SetOutputLogic(0,0,CE_LOGIC_0); writes LOGIC 0 to P0 [0].
Prototype
void CE_EnterCommandCode( CE_BYTE bCommandCode );
Description
Writes the specified command code to command register.
Parameters
Name
Description
Possible Values
bCommandCode
Command code
‘GET_FIRMWARE_REVISION’ ,
‘STORE_CURRENT_CONFIGURATION_TO_NVM’,
‘RESTORE_FACTORY_CONFIGURATION’,
‘WRITE_POR_DEFAULTS’,
‘READ_POR_DEFAULTS’,
‘READ_DEVICE_CONFIGURATION’,
‘RECONFIGURE_DEVICE’,
‘NORMAL_OPERATION_MODE’,
‘SETUP_OPERATION_MODE’,
Example
CE_EnterCommandCode (NORMAL_OPERATION_MODE); device enters into Normal operation
mode.
CE_EnterCommandCode (SETUP_OPERATION_MODE); device enters into Setup operation mode.
For details on the functions performed by other values for parameter bCommandCode, refer to the
CY8C201xx Register Reference Guide.
www.cypress.com
Document No. 001-44207 Rev.*E
8
CapSense Express™: APIs for Register Configuration
27
Prototype
void CE_ConfigureSleepParameters( CE_BYTE bPort , CE_BYTE bPin , CE_BYTE bReference ,
CE_BYTE bSleepInterval, CE_BYTE bStayAwakeCounter );
Description
The API performs the following functions:
1. Selects sleep control pin
2. Selects reference
3. Sets sleep interval
4. Sets stay awake counter
The CapSense Express device must be in Setup mode to execute this API properly.
Parameters
Name
Description
Possible Values
bPort
Port number
0,1
bPin
Pin number
0,1,2,3,4
bReference
Voltage bandgap
powered or not
CE_ENABLE , CE_DISABLE
bSleepInterval
Sleep interval value
CE_SLEEP_INTERVAL_1_95 ( 1.95 ms),
CE_SLEEP_INTERVAL_15_6 (15.6 ms),
CE_SLEEP_INTERVAL_125 (125 ms),
CE_SLEEP_INTERVAL_1000 (1s).
bStayAwakeCounter
Stay awake counter
value
0–255
Example
28
CE_ConfigureSleepParameters (1, 2,CE_ENABLE,CE_SLEEP_INTERVAL_1_95, 100);
Sets P1 [2] as sleep control pin, enables voltage bandgap reference, sets sleep interval as 1.95 ms,
and sets the stay awake counter to 100.
Prototype
void CE_GoToSleep( CE_BYTE bMode );
Description
Sets the device in sleep (normal sleep mode or deep sleep mode).
Parameters
Name
Description
Possible Values
bMode
To select the sleep
mode
CE_NORMAL_SLEEP_MODE,
CE_DEEP_SLEEP_MODE
Example
29
CE_GoToSleep (CE_NORMAL_SLEEP_MODE); sets the device in normal sleep mode.
Prototype
void CE_DisableSleep( void );
Description
After calling this API the device does not enter into sleep again unless the sleep mode is again set.
Parameters
None
Example
CE_DisableSleep ( );
30
Prototype
CE_BOOL CE_SetDeviceI2CAddress( CE_BYTE bNewDeviceAddress , CE_BYTE
bI2CPinDriveMode );
Description
The function of this API is to set the device I2C address. The address is set in the range 0 to 127. The
I2C pin drive mode is set either as ‘Resistive Pull up’ or ‘Open Drain Low’. If the address passed is
greater than 127, then the API returns 0 (fail); otherwise, it sets the new address and returns 1 (pass).
Parameters
Name
Description
Possible Values
bNewDeviceAddress
I2C device address
0–127
bI2CPinDriveMode
I2C pin drive mode
RESISTIVE_PULL_UP,
OPEN_DRAIN_LOW
Example
www.cypress.com
CE_SetDeviceI2CAddress ( 5, OPEN_DRAIN_LOW ); sets the device’s new address as 5, sets the
I2C pin drive mode as Open Drain Low, and returns 1.
Document No. 001-44207 Rev.*E
9
CapSense Express™: APIs for Register Configuration
31
Prototype
CE_BOOL CE_PWMEnableOutputLogic (CE_BYTE bPort, CE_BYTE bPin, CE_BOOL
PWM_Enable)
Description
The function of this API is to enable PWM output and select the GPIO to route the PWM output. It
returns 1 if the selected GPIO is enabled for PWM output; otherwise, it returns 0. Before selecting any
port pin as PWM output it should be enabled as GPIO.
Parameters
Name
Description
Possible Values
bPort
Port number
0, 1
bPin
Pin number
0, 1, 2, 3, 4
PWM_Enable
PWM output enable
0, 1 (CE_DISABLE, CE_ENABLE)
Example
32
Prototype
CE_BOOL CE_PWMEnableOutputLogic (0, 1, 1)
In the above API, the port 0 pin 1 is enabled for PWM output. This returns 1 if the GPIO is selected as
PWM output; otherwise, the return value is 0.
void CE_SetPWMModeDutyDelay (CE_BYTE Mode, CE_BYTE Duty, CE_BYTE EnableDelay,
CE_BYTE Delay, CE_BOOL Link)
Description
The function of this API is to set PWM parameters such as mode selection and duty cycle selection
for dimming, It also enables the delay and delay value for the dimming functionality and the link
parameter.
Parameters
Name
Description
Possible Values
Mode
Mode of operation
0, 1, 2, 3
Duty
Sets the duty cycle for dimming
0–15. Here 0 = 2.5% and 15 = 99.5%
EnableDelay
Enables the delay value for the PWM.
This delays the dimming functionality.
0, 1 (CE_DISABLE, CE_ENABLE)
Delay
Specifies the delay for dimming
functionality. If Enable Delay is not set,
then this has no effect.
0–254. The value of 255 is
undefined.
0 indicates delay of 0ms
254 indicates delay of 5s
Link
Link between 0/1 logic state of the pin
and the PWM output.
0, 1 (CE_DISABLE, CE_ENABLE)
Example
33
Prototype
CE_SetPWMModeDutyDelay (2, 0, 1, 254, 0) sets the mode 2 operation of PWM, where the GPIO
goes off, after specified delay time of 5s, after the button is pressed. The link parameter is set to zero.
void CE_EnableFilter(CE_BOOL RstBL, CE_BOOL EnableDTS, CE_BOOL EnableAvg,
CE_BYTE NoofSamples)
Description
This function is used to set the required filtering such as Averaging and Drop The Sample filtering.
This is used to improve the noise performance.
Parameters
Name
Description
Possible Values
RstBL
This bit set at ‘1’ forces an immediate
baseline initialization for all sensors
0, 1
EnableDTS
This bit set at ‘1’ enables the I2C “Drop
The Sample” filter
0, 1
EnableAvg
This bit enables or disables the
Averaging filter
0, 1
NoofSamples
These two bits are used to select the
number of CapSense samples to
average
0, 1, 2, 3
Here 0 is for 2 sample average
1 is for 4 sample average
2 is for 8 sample average
3 is for 16 sample average
Example
www.cypress.com
CE_EnableFilter (1, 1, 1, 0) forces immediate baseline initialization for all sensors, enables Drop the
Sample filter, enables Averaging filter, and uses two samples for averaging.
Document No. 001-44207 Rev.*E
10
CapSense Express™: APIs for Register Configuration
In addition to the above APIs, there is one more API that is called to write the complete I2C configuration in one step.
Calling this API, the I2C file generated by the CapSense Express Software Tool (refer AN42137) can be written as it is
to the device. This is a text file containing a string with hexadecimal values for the specific configuration selected in
PSoC Designer™. This string must be arranged in a character array of the required size. The pointer to this array must
be passed to the API. The API receives each character one by one and performs the required operation. This is useful
to change the entire configuration of the device in one step.
34
Prototype
void CE_WriteI2Cfile( const char * acI2CFile );
Description
The API is used to write the whole I2C file generated by PSoC Designer™ in a single step. You
can store all the configuration values together in a character array of required size. The pointer to
that array is passed as a parameter to the API. The API receives each character from the array
one by one and performs the required action.
Parameters
Name
Description
Possible Values
acI2CFile
Pointer to the character array where the set of
values are stored
-
Example
Define the array in main file, using the following method:
const char acI2Cfile [ ] = “w 00 79 3C A5 69 w 00 7C 80 w 00 79 96 5A C3 w 00 A0
08…..”
Then call the API:
CE_WriteI2Cfile (acI2Cfile); writes the whole set of commands.
3
Low Level APIs
Low level APIs are used in the host IC to enable the physical I2C read and write communication between the host
microcontroller and the CapSense Express device.
They contain hardware specific code to read and write to or from the I2C slave device. The code depends on the system
hardware and the CPU. An example of low level APIs for PSoC is provided with this application note.
In the low level APIs provided with this application note, the PSoC I2CHW user module is used to perform read and
write operations and the code is written accordingly.
Low level APIs are described in the following sections.
There are two APIs in this category. One API is to read from the CapSense Express device and the other is to write to
the device. As mentioned earlier, these APIs are hardware specific. The following APIs are for PSoC. These APIs must
be changed according to the system specific hardware.
www.cypress.com
Document No. 001-44207 Rev.*E
11
CapSense Express™: APIs for Register Configuration
1
Prototype
Description
Reads the specified number of bytes from the CapSense Express device.
Parameters
Name
Description
Possible Values
bDeviceAddress
I2C device address
0–127
bAddress
Address of the location from where to start reading
-
bBytesToBeRead
No. of bytes to read
-
RdPrtAddress
Pointer to the array where to store the data read
-
Example
2
CE_Read( 0, 10, 5,bReadBuffer ); reads 5 bytes from the device having address 0, starting from
RAM address 10h, and stores the values to the array ‘bReadBuffer’
Prototype
CE_Write( CE_BYTE bDeviceAddress , CE_BYTE *bArray , CE_BYTE bBytesToBeWritten);
Description
Writes the specified number of bytes to the CapSense Express device.
Parameters
Name
Description
Possible Values
bDeviceAddress
I2C device address
0–127
bArray
Pointer to the array of bytes where data is stored
-
bBytesToBeWritten
No. of bytes to write
-
Example
4
CE_Read( CE_BYTE bDeviceAddress , CE_BYTE bAddress , CE_BYTE bBytesToBeRead ,
CE_BYTE *RdPrtAddress );
CE_Write (0, bWriteBuffer, 5); writes 5 bytes taken from the array ‘bWriteBuffer’ to the I2C device
with address 0.
Command Execution
Commands are executed in CapSense Express device by writing the command code to register 0xA0. The device
cannot be accessed for the time needed to execute the command. The time for which the device cannot be accessed,
after execution of each command, is given in the table below:
Description
Execution Mode
Expected ACK Time
in Normal Mode
Device Inaccessible
Time after ACK
00h
Get Firmware Revision
Setup or Normal
<100 μs
0s
01h
Store Current Configuration to
NVM
Setup or Normal
<100 μs
~120 ms
02h
Restore Factory Configuration
Setup or Normal
<100 μs
~120 ms
03h
Write NVM POR Defaults
Setup or Normal
<100 μs
~120 ms
04h
Read NVM POR Defaults
Setup or Normal
<100 μs
~5 ms
05h
Read Active Device
Configuration (RAM)
Setup or Normal
<100 μs
~5 ms
06h
Reconfigure Device (POR)
Setup
<100 μs
~5 ms (Setup mode)
07h
Set Normal Operation Mode
Setup or Normal
<100 μs
0s
08h
Set Setup Operation Mode
Setup or Normal
<100 μs
1.2 * (loop time1 + 1
ms)
09h
Start CapSense Scan
Setup or Normal
<100 μs
~10 ms
0Ah
Stop CapSense Scan
Setup or Normal
<100 μs
~5 ms
0Bh
Get CapSense Scan Status
Setup or Normal
<100 μs
0s
Command
1
Loop time can be measured by probing any sensor using an oscilloscope and measuring the time between two consecutive scans.
www.cypress.com
Document No. 001-44207 Rev.*E
12
CapSense Express™: APIs for Register Configuration
Accessing the device immediately after the command is sent does not affect the functionality of the system. This is
because CapSense Express simply does not respond to I2C requests.
The following files are provided with this application note:

ce_201xx_high_api.c
This file contains the definition for all high level APIs that are used to configure the various device parameters.

ce_201xx_low_api.c
This file contains low level APIs. The code is written for PSoC master. The code in these APIs must be changed
for other microcontrollers, as explained in the previous sections.

ce_201xx.h
This file contains the prototype for all APIs, the system types used, and the constants used in the APIs
5
Important Notes

The device address is stored in a CE_BYTE variable (bDeviceAddress) in the .c file provided with this application
note. The address is initialized to 0x00. The low level APIs perform the read and write operations on the address
specified by this variable. If the address of CapSense Express device in the system is not 0x00 or if you change
the address by calling the API for changing the device address, then reinitialize this variable to a new value in .c
file on the next power on or reset.

For any parameter, pass only the values which are mentioned in the application note. Passing any value outside
the range causes unexpected behavior.

Always make sure that before writing Logic 0 or Logic 1 to any GPIO, the output logic operation as specified by the
operation select register is disabled. To do this, call the following API:
CE_EnableOutputLogicOperation (CE_DISABLE) first and then call the API, CE_SetOutputLogic(CE_LOGIC_1)
or CE_SetOutputLogic (CE_LOGIC_0).

The two APIs CE_SetFingerThreshold and CE_SetIDACSetting must be called only after calling the following APIs:
CE_fEnableCapSense,
CE_SetsettlingTime,
CE_EnableSensorAutoReset,
CE_EnableExternalCapacitor,
CE_SelectClock,
Otherwise, the values of Finger Threshold and IDAC setting are reset.

To
retain
the
configuration
changes
made,
call
API:
CE_EnterCommandCode(STORE_CURRENT_CONFIGURATION_TO_NVM) after all other APIs are called. This
retains the changes made on the next power on or reset.

The low level APIs for PSoC call the User module (I2CHardWare) inside it. When placing user module into the
project, rename the module as I2CHW. Otherwise, to retain the module name according to the project, the user
must update the user module name in the low level APIs:
CE_Read (CE_BYTE bDeviceAddress,
*RdPrtAddress)
CE_BYTE bAddress,
CE_BYTE bBytesToBeRead,
CE_BYTE
CE_Write (CE_BYTE bDeviceAddress, CEs_BYTE *bArray , CE_BYTE bBytesToBeWritten).
www.cypress.com
Document No. 001-44207 Rev.*E
13
CapSense Express™: APIs for Register Configuration
6
Summary
AN44207 defines APIs for register configuration. These APIs are used to write to CapSense Express™ registers
through the host microcontroller when the CapSense Express slave device is on board.
7
Related Application Notes
AN42137 – CapSense™ Express Software Tool
AN44208 – CapSense® Express™ - I2C Communication Timing Analysis
AN44209 – CapSense® Express™ Power and Sleep Considerations
www.cypress.com
Document No. 001-44207 Rev.*E
14
CapSense Express™: APIs for Register Configuration
Document History
Document Title: AN44207 - CapSense Express™: APIs for Register Configuration
Document Number: 001-44207
Revision
ECN
Orig. of
Change
Submission
Date
Description of Change
**
2345367
MOHD
04/11/08
New application note.
*A
2559285
MOHD
08/29/08
Updated text in all instances across the document.
Updated High Level APIs:
Added two APIs.
Added two APIs in attached associated project.
*B
3249521
SLAN
05/05/11
Updated Software Version as “PSoC Designer 5.0 SP6” in page 1.
Updated attached associated project to PSoC Designer 5.0.
*C
4387056
PRIA
05/22/2014
Updated Command Execution:
Updated details in “Device Inaccessible Time after ACK” column corresponding to
“08h” Command in the table.
Updated Related Application Notes:
Removed references of AN44203, and AN47716 as these application notes are
obsolete.
Updated to new template.
Completing Sunset Review.
*D
5031306
PRIA
12/01/2015
Updated to new template.
*E
5092581
PRIA
01/19/2016
Obsoleting the Application Note
www.cypress.com
Document No. 001-44207 Rev.*E
15
CapSense Express™: APIs for Register Configuration
Worldwide Sales and Design Support
Cypress maintains a worldwide network of offices, solution centers, manufacturer’s representatives, and distributors. To find the
office closest to you, visit us at Cypress Locations.
PSoC® Solutions
Products
Automotive
cypress.com/go/automotive
psoc.cypress.com/solutions
Clocks & Buffers
cypress.com/go/clocks
PSoC 1 | PSoC 3 | PSoC 4 | PSoC 5LP
Interface
cypress.com/go/interface
Cypress Developer Community
Lighting & Power Control
cypress.com/go/powerpsoc
Memory
cypress.com/go/memory
PSoC
cypress.com/go/psoc
Touch Sensing
cypress.com/go/touch
USB Controllers
cypress.com/go/usb
Wireless/RF
cypress.com/go/wireless
Community | Forums | Blogs | Video | Training
Technical Support
cypress.com/go/support
PSoC is a registered trademark of Cypress Semiconductor Corp. "Programmable System-on-Chip," PSoC Designer are trademarks of Cypress
Semiconductor Corp. All other trademarks or registered trademarks referenced herein are the property of their respective owners.
Cypress Semiconductor
198 Champion Court
San Jose, CA 95134-1709
Phone
Fax
Website
: 408-943-2600
: 408-943-4730
: www.cypress.com
© Cypress Semiconductor Corporation, 2008-2016. The information contained herein is subject to change without notice. Cypress Semiconductor
Corporation assumes no responsibility for the use of any circuitry other than circuitry embodied in a Cypress product. Nor does it convey or imply any
license under patent or other rights. Cypress products are not warranted nor intended to be used for medical, life support, life saving, critical control or
safety applications, unless pursuant to an express written agreement with Cypress. Furthermore, Cypress does not authorize its products for use as
critical components in life-support systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The
inclusion of Cypress products in life-support systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies
Cypress against all charges.
This Source Code (software and/or firmware) is owned by Cypress Semiconductor Corporation (Cypress) and is protected by and subject to worldwide
patent protection (United States and foreign), United States copyright laws and international treaty provisions. Cypress hereby grants to licensee a
personal, non-exclusive, non-transferable license to copy, use, modify, create derivative works of, and compile the Cypress Source Code and derivative
works for the sole purpose of creating custom software and or firmware in support of licensee product to be used only in conjunction with a Cypress
integrated circuit as specified in the applicable agreement. Any reproduction, modification, translation, compilation, or representation of this Source Code
except as specified above is prohibited without the express written permission of Cypress.
Disclaimer: CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress reserves the right to
make changes without further notice to the materials described herein. Cypress does not assume any liability arising out of the application or use of any
product or circuit described herein. Cypress does not authorize its products for use as critical components in life-support systems where a malfunction or
failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress’ product in a life-support systems application implies
that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges.
Use may be limited by and subject to the applicable Cypress software license agreement.
www.cypress.com
Document No. 001-44207 Rev.*E
16
Similar pages