ioio.lib.api
Interface TwiMaster

All Superinterfaces:
Closeable
All Known Implementing Classes:
TwiMasterImpl

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, 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, 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)