ioio.lib.api
Interface AnalogInput

All Superinterfaces:

Closeable

public interface AnalogInput
extends Closeable

A pin used for analog input.

An analog input pin can be used to measure voltage. AnalogInput instances are obtained by calling IOIO.openAnalogInput(int).

Floating-point values scaled from 0 to 1 can be obtained by calling read(). Absolute voltage levels can be obtained by calling getVoltage().

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:

 AnalogInput potentiometer = ioio.openAnalogInput(40);
 float value = potentiometer.read();
 ...
 potentiometer.close();  // pin 40 can now be used for something else.
 
 

An alternate usage allows reading periodically sampled data without missing samples. The setBuffer(int) method must first be called, for setting up an internal buffer for queuing samples. Then, samples can be obtained by calling readBuffered() or getVoltageBuffered(). These methods will block until a sample is available. If this is undesirable, the available() method can be called first to check how many samples are ready in the buffer. In case the buffer overflows, as result of the client not reading fast enough, old samples will be dropped, and the client can check getOverflowCount() to determine how many samples have been lost. The sample rate used for capturing samples can be obtained by calling getSampleRate().

The non-buffered versions of the read methods will still behave normally when buffering is enabled. The read() and getVoltage() methods will always return the most recent value, regardless of the buffer state.

Typical usage:

 AnalogInput potentiometer = ioio.openAnalogInput(40);
 potentiometer.setBuffer(256);
 for (int i = 0; i < 1024; ++i) {
   // next line will block until at least one sample is available
   float sample = potentiometer.readBuffered();
   ...
 }
 ...
 potentiometer.close();  // pin 40 can now be used for something else.
 

See Also:

IOIO.openAnalogInput(int)

Method Summary

int	available() Gets the number of samples currently in the buffer.
int	getOverflowCount() Gets the number of samples that have been dropped as result of overflow, since setBuffer(int) has been called.
float	getReference() Gets the maximum value against which read() values are scaled.
float	getSampleRate() Gets the sample rate used for obtaining buffered samples.
float	getVoltage() Gets the analog input reading, as an absolute voltage in Volt units.
float	getVoltageBuffered() Read a sample from the internal buffer.
float	getVoltageSync() This is very similar to getVoltage(), but will wait for a new sample to arrive before returning.
float	read() Gets the analog input reading, as a scaled real value between 0 and 1.
float	readBuffered() Read a sample from the internal buffer.
float	readSync() This is very similar to read(), but will wait for a new sample to arrive before returning.
void	setBuffer(int capacity) Initializes or destroys an internal buffer, used for queuing sampled data.

Methods inherited from interface ioio.lib.api.Closeable

close

Method Detail

getVoltage

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

Gets the analog input reading, as an absolute voltage in Volt units.

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.

If a scaled value is desired, consider using read().

Returns:

The voltage, in Volt units.

Throws:

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

ConnectionLostException - The connection with the IOIO is lost.

See Also:

read()

getVoltageSync

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

This is very similar to getVoltage(), 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:

Throws:

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

ConnectionLostException - The connection with the IOIO is lost.

See Also:

getVoltage(), readSync()

getReference

float getReference()

Gets the maximum value against which read() values are scaled.

Returns:

The voltage, in Volts.

read

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

Gets the analog input reading, as a scaled real value between 0 and 1.

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.

If an absolute value is desired, consider using getVoltage().

Returns:

The voltage, in scaled units.

Throws:

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

ConnectionLostException - The connection with the IOIO is lost.

See Also:

getVoltage()

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 voltage, in scaled units.

Throws:

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

ConnectionLostException - The connection with the IOIO is lost.

See Also:

read(), getVoltageSync()

setBuffer

void setBuffer(int capacity)
               throws ConnectionLostException

Initializes or destroys an internal buffer, used for queuing sampled data. When called with a positive argument, an internal buffer will be created, and start storing sampled data. The client can then call readBuffered() or getVoltageBuffered() for obtaining buffered samples.

When called with argument of 0, the internal buffer is destroyed.

Parameters:

capacity - The maximum number of unread samples that can be buffered before overflow occurs.

Throws:

ConnectionLostException - The connection with the IOIO is lost.

getOverflowCount

int getOverflowCount()
                     throws ConnectionLostException

Gets the number of samples that have been dropped as result of overflow, since setBuffer(int) has been called.

Returns:

The number of dropped samples.

Throws:

ConnectionLostException - The connection with the IOIO is lost.

available

int available()
              throws ConnectionLostException

Gets the number of samples currently in the buffer. Reading that many samples is guaranteed not to block.

Returns:

The number of samples available in the buffer.

Throws:

ConnectionLostException - The connection with the IOIO is lost.

readBuffered

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

Read a sample from the internal buffer. This method will block until at least one sample is available, the instance is closed (via Closeable.close()), the thread is interrupted (via Thread.interrupt() or connection is lost. setBuffer(int) must be called prior to this method for setting up an internal buffer for storing samples.

Returns:

The earliest (oldest) sample available in the buffer, scaled to the range [0,1].

Throws:

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

ConnectionLostException - The connection with the IOIO is lost.

See Also:

getVoltageBuffered()

getVoltageBuffered

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

Read a sample from the internal buffer. This method will block until at least one sample is available, the instance is closed (via Closeable.close()), the thread is interrupted (via Thread.interrupt() or connection is lost. setBuffer(int) must be called prior to this method for setting up an internal buffer for storing samples.

Returns:

The earliest (oldest) sample available in the buffer, in Volt units.

Throws:

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

ConnectionLostException - The connection with the IOIO is lost.

See Also:

readBuffered()

getSampleRate

float getSampleRate()
                    throws ConnectionLostException

Gets the sample rate used for obtaining buffered samples.

Returns:

The sample rate, in Hz units.

Throws:

ConnectionLostException - The connection with the IOIO is lost.