Capacitive Sensor low-level library

The Capacitive Sensor low-level library provides support for power-efficient capacitive sensing.

The number of supported capacitive pads is equal to the number of available analog channels – 8.

This library has two different implementations, depending on whether you want to use the COMP module:

• One option is to use SAADC to provide the capacitive sensing feature. This solution requires some hardware customizations.

Note

Until Anomaly 84 (ISOURCE not functional) is fixed, the COMP solution cannot provide production-level quality. Use the SAADC solution instead.

• Another option is to use COMP. Using COMP gives more accurate results than SAADC, because it is specifically designed to provide this kind of functionality.

Implementation details

Despite the two different implementations, the library uses the same API in both cases. To choose the implementation of this library, change the value of USE_COMP.

When using the implementation involving SAADC, the module measures voltage on the pad that is touched. An additional pin is needed to charge the pad through a resistor. On every measurement, the pad is charged and then discharged using the SAADC module. If the pad is touched during measurement, its capacitance is higher. This is detected by ADC which receives a greater value of the measured voltage. Therefore, to set up this solution, you must know the value of the ADC measurement when the pad is idle to decide when it is touched.

When using the implementation involving COMP, ISOURCE is used. For details, refer to Capacitive sensing.

Resource usage

You can create only one instance of this library. Additionally, the number of channels is limited to the number of analog channels, which is eight.

Depending on the selected implementation, the library uses the following resources:

For SAADC implementation:

• The SAADC module.

For COMP implementation:

• Two instances of timer. Make sure to edit the library configuration file to specify which timers will be used in the solution.
• Three PPI channels.
• The COMP module.

  Note

  Until Anomaly 84 (ISOURCE not functional) is fixed, the COMP implementation is not a production-level solution.

  Important: If the Capacitive Sensor low-level library is used for analog input, it cannot be used by ADC, COMP, or LPCOMP as these three modules share resources.

Hardware setup

Because the COMP implementation uses a different method for detecting touch, it requires a different hardware setup than when using SAADC.

The following example setup shows how to connect two pads while using the COMP implementation:

Diagram 1. Example hardware setup for the COMP implementation.

When using SAADC, you need an additional resistor for charging capacitors connected to the pads:

Diagram 2. Example hardware setup for SAADC implementation.

Set the values of the resistor in such a way that the pad is charged during every single measurement period. It means that the resistor's values should be around 100k ohms when using GPIO as the charge source (typically 3V3 in high state).

Initialization and starting

There are two functions that you must run before you can start working with this library.

ret_code_t err_code;
nrf_drv_csense_config_t csense_config; 
#ifdef USE_COMP
csense_config.output_pin = OUTPUT_PIN;
#endif //USE_COMP
err_code = nrf_drv_csense_init(&csense_config, csense_handler);
APP_ERROR_CHECK(err_code);
nrf_drv_csense_channels_enable(analog_input_4 | analog_input_5 | analog_input_7);

err_code = nrf_drv_csense_sample();
APP_ERROR_CHECK(err_code);

First, you must initialize the module. If you are using the SAADC implementation, the only required configuration is to provide the number of the output pin that will be used to charge the pads. For the COMP implementation, initialize the module without specifying any additional configuration parameters.

After the module is initialized, all channels are automatically disabled. To enable the channels, you must run the function nrf_drv_csense_channels_enable. After that, you can start the measurement by calling nrf_drv_csense_sample.

Note

For the COMP implementation, even if all channels are disabled, there is always one channel that remains enabled after the COMP driver initialization. This channel cannot be used for ADC or LPCOMP because of sharing resources. After deinitializing COMP, the channel is available again.

Reading values from the pads

You can now start working with the module. Every time you call the nrf_drv_csense_sample function, the conversion of all enabled channels is performed. You can read the result through a handler or at any time after the conversion. However, data is overwritten after each conversion, so it can be read only until the next conversion.

uint8_t channel;
void csense_handler(nrf_drv_csense_evt_t * p_event_struct)
{ 
 //print result of conversion on screen
 printf("Channel: %d, \t value: %d.\n", p_event_struct->analog_channel,
 p_event_struct->read_value);
 channel = p_event_struct->analog_channel;
} 
int main(void)
{ 
 (…)
 printf("From main - channel: %d, value: %d.\n", channel,
 app_capsense_button_read(channel));
 (…) 
} 

Example

See the Capacitive Sensor Low-level Example for a full example that uses the Capacitive Sensor low-level library.