ioio.lib.api
Interface CapSense

All Superinterfaces:

Closeable

public interface CapSense
extends Closeable

A pin used for capacitive sensing.

A cap-sense input pin can be used to measure capacitance, most frequently for touch sensing. CapSense instances are obtained by calling IOIO.openCapSense(int).

Capacitance is measured by pushing a known amount of charge into the circuit, and measuring the increase in voltage. As capacitance gets bigger, this increase becomes smaller, and thus less accurate. As capacitance gets smaller, the increase may become fast enough so it can saturate, i.e. reach the maximum voltage. The system has been tuned to effectively sense capacitance values typical of the human body, for touch sensors. The lowest possible capacitance is about 27pF, and at about 2700pF the precision will be around 10% (with high noise level unless filtered). The internal capacitance of the system with some parasitic capacitance will normally be 30pF or more. Human-body capacitance will typically be about 150pF without grounding, and greater with grounding or when touching a large metallic surface.

Floating-point values in pico-Farade units can be obtained by calling read().

For better noise immunity, some low-pass filtering is recommended. This module provides a simple, single-pole IIR filtering, with configurable time- constant. There is a trade-off when selecting the time-constant: a longer time constant will provide better noise filtering, but at the cost of a slower response. In other words, it will take more time for the measured value to reach the actual. The default value of DEFAULT_COEF( 25.0fpF) is a reasonable one in many cases. To change it, call setFilterCoef(float), or use the overload the open method, which gets a filter coefficient argument: IOIO.openCapSense(int, float).

The instance is alive since its creation. The first read() call block for a few milliseconds until the initial value is updated. If the connection with the IOIO drops at any point, the instance transitions to a disconnected state, in which every attempt to use the pin (except Closeable.close()) will throw a ConnectionLostException. Whenever Closeable.close() is invoked the instance may no longer be used. Any resources associated with it are freed and can be reused.

Typical usage:

 CapSense touchSensor = ioio.openCapSense(40);
 if (touchSensor.read() > 50) {
   // Clicked!
   ...
 }

 ...
 touchSensor.close();  // optional. pin 40 can now be used for something else.
 

See Also:

IOIO.openCapSense(int), IOIO.openCapSense(int, float)

Field Summary

static float

DEFAULT_COEF

Method Summary

float	read() Gets the capacitance reading.
float	readSync() This is very similar to read(), but will wait for a new sample to arrive before returning.
void	setFilterCoef(float t) Sets the low-pass filter coefficient.
void	waitOver(float threshold) Block until sensed capacitance becomes greater than a given threshold.
void	waitOverSync(float threshold) This is very similar to #waitOver(), but will wait for a new sample to arrive before returning.
void	waitUnder(float threshold) Block until sensed capacitance becomes less than a given threshold.
void	waitUnderSync(float threshold) This is very similar to #waitUnder(), but will wait for a new sample to arrive before returning.

Methods inherited from interface ioio.lib.api.Closeable

close

Field Detail

DEFAULT_COEF

static final float DEFAULT_COEF

See Also:

Constant Field Values

Method Detail

read

float read()
           throws java.lang.InterruptedException,
                  ConnectionLostException

Gets the capacitance reading.

It typically takes a few milliseconds between when the instance is created and until the first value can be read. In this case, the method may block shortly. If this is a problem, the calling thread can be interrupted.

This value is computed using a filtered signal, which is configured via setFilterCoef(float)

Returns:

The capacitance, in pico-Farade units.

Throws:

java.lang.InterruptedException - The calling thread has been interrupted.

ConnectionLostException - The connection with the IOIO is lost.

readSync

float readSync()
               throws java.lang.InterruptedException,
                      ConnectionLostException

This is very similar to read(), but will wait for a new sample to arrive before returning. This is useful in conjunction with IOIO.sync(), in cases when we want to guarantee the we are looking at a sample that has been captured strictly after certain other commands have been executed.

Returns:

The capacitance, in pico-Farade units.

Throws:

java.lang.InterruptedException - The calling thread has been interrupted.

ConnectionLostException - The connection with the IOIO is lost.

See Also:

read()

setFilterCoef

void setFilterCoef(float t)
                   throws ConnectionLostException

Sets the low-pass filter coefficient. This coefficient is the typical time constant of the system, which gives us an order of magnitude of its response time. Slower response time typically provides better noise immunity at the expense of higher latency.

Parameters:

t - The time constant, in milliseconds.

Throws:

ConnectionLostException - The connection with the IOIO is lost.

waitOver

void waitOver(float threshold)
              throws ConnectionLostException,
                     java.lang.InterruptedException

Block until sensed capacitance becomes greater than a given threshold. For using a touch surface as a digital button, a threshold of 50pF is normally useful, with some hysteresis recommended.

Parameters:

threshold - The threshold value, in pF units.

Throws:

ConnectionLostException - The connection with the IOIO is lost.

java.lang.InterruptedException - The calling thread has been interrupted.

waitOverSync

void waitOverSync(float threshold)
                  throws ConnectionLostException,
                         java.lang.InterruptedException

This is very similar to #waitOver(), but will wait for a new sample to arrive before returning. This is useful in conjunction with IOIO.sync(), in cases when we want to guarantee the we are looking at a sample that has been captured strictly after certain other commands have been executed.

Throws:

java.lang.InterruptedException - The calling thread has been interrupted.

ConnectionLostException - The connection with the IOIO is lost.

See Also:

#waitOver()

waitUnder

void waitUnder(float threshold)
               throws ConnectionLostException,
                      java.lang.InterruptedException

Block until sensed capacitance becomes less than a given threshold. For using a touch surface as a digital button, a threshold of 50pF is normally useful, with some hysteresis recommended.

Parameters:

threshold - The threshold value, in pF units.

Throws:

ConnectionLostException - The connection with the IOIO is lost.

java.lang.InterruptedException - The calling thread has been interrupted.

waitUnderSync

void waitUnderSync(float threshold)
                   throws ConnectionLostException,
                          java.lang.InterruptedException

This is very similar to #waitUnder(), but will wait for a new sample to arrive before returning. This is useful in conjunction with IOIO.sync(), in cases when we want to guarantee the we are looking at a sample that has been captured strictly after certain other commands have been executed.

Throws:

java.lang.InterruptedException - The calling thread has been interrupted.

ConnectionLostException - The connection with the IOIO is lost.

See Also:

#waitUnder()