ioio.lib.api
Interface TwiMaster

All Superinterfaces:
Closeable

public interface TwiMaster
extends Closeable

An interface for controlling a TWI module, in TWI bus-master mode, enabling communication with multiple TWI-enabled slave modules.

TWI (Two-Wire Interface) is a common hardware communication protocol, enabling half-duplex, synchronous point-to-multi-point data transfer. It requires a physical connection of two lines (SDA, SCL) shared by all the bus nodes, where the SDA is open-drain and externally pulled-up. TwiMaster instances are obtained by calling IOIO.openTwiMaster(int, ioio.lib.api.TwiMaster.Rate, boolean).

TWI is the generic name for the specific I2C and SMBus protocols, differing mostly by the voltage levels they require. This module supports both.

A TWI transaction is comprised of optional sending of a data buffer from the master to a single slave, followed by an optional reception of a data buffer from that slave. Slaves are designated by addresses, which may be 7-bit (common) or 10-bit (less common). TWI transactions may fail, as a result of the slave not responding or as result of the slave NACK'ing the request. Such a transaction is executed using the writeRead(int, boolean, byte[], int, byte[], int) method.

The instance is alive since its creation. If the connection with the IOIO drops at any point, the instance transitions to a disconnected state, in

The instance is alive since its creation. If the connection with the IOIO drops at any point, the instance transitions to a disconnected state, in which every attempt to use it (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:

 // Uses the SDA1/SCL1 pins, I2C volatege levels at 100KHz. 
 TwiMaster twi = ioio.openTwiMaster(1, TwiMaster.RATE_100KHz, false);
 final byte[] request = new byte[]{ 0x23, 0x45 };
 final byte[] response = new byte[3];
 if (twi.writeRead(0x19, false, request, 2, response, 3)) {
   // response is valid
   ...
 } else {
   // handle error
 }
 twi.close();  // free TWI module and pins
 

See Also:
IOIO.openTwiMaster(int, ioio.lib.api.TwiMaster.Rate, boolean)

Nested Class Summary
static class TwiMaster.Rate
           
static interface TwiMaster.Result
          An object that can be waited on for asynchronous calls.
 
Method Summary
 boolean writeRead(int address, boolean tenBitAddr, byte[] writeData, int writeSize, byte[] readData, int readSize)
          Perform a single TWI transaction which includes optional transmission and optional reception of data to a single slave.
 TwiMaster.Result writeReadAsync(int address, boolean tenBitAddr, byte[] writeData, int writeSize, byte[] readData, int readSize)
          Asynchronous version of writeRead(int, boolean, byte[], int, byte[], int).
 
Methods inherited from interface ioio.lib.api.Closeable
close
 

Method Detail

writeRead

boolean writeRead(int address,
                  boolean tenBitAddr,
                  byte[] writeData,
                  int writeSize,
                  byte[] readData,
                  int readSize)
                  throws ConnectionLostException,
                         java.lang.InterruptedException
Perform a single TWI transaction which includes optional transmission and optional reception of data to a single slave. This is a blocking operation that can take a few milliseconds to a few tens of milliseconds. To abort this operation, client can interrupt the blocked thread.

Parameters:
address - The slave address, either 7-bit or 10-bit. Note that in some TWI device documentation the documented addresses are actually 2x the address values used here, as they regard the trailing 0-bit as part of the address.
tenBitAddr - Whether this is a 10-bit addressing mode.
writeData - The request data.
writeSize - The number of bytes to write. Valid value are 0-255.
readData - The array where the response should be stored.
readSize - The expected number of response bytes. Valid value are 0-255.
Returns:
Whether operation succeeded.
Throws:
ConnectionLostException - Connection to the IOIO has been lost.
java.lang.InterruptedException - Calling thread has been interrupted.

writeReadAsync

TwiMaster.Result writeReadAsync(int address,
                                boolean tenBitAddr,
                                byte[] writeData,
                                int writeSize,
                                byte[] readData,
                                int readSize)
                                throws ConnectionLostException
Asynchronous version of writeRead(int, boolean, byte[], int, byte[], int). Returns immediately and provides a TwiMaster.Result object on which the client can wait for the result.

Throws:
ConnectionLostException
See Also:
writeRead(int, boolean, byte[], int, byte[], int)