com.oracle.deviceaccess.i2cbus

Interface I2CDevice

All Superinterfaces:

Peripheral, Transactional

public interface I2CDevice
extends Peripheral, Transactional

The I2CDevice interface provides methods for sending and receiving data to/from an I2C slave device.

Each I2C slave device is identified by a numerical ID and by a name.
An I2CDevice instance can be opened by a call to one of the PeripheralManager.open() methods.

On an I2C bus, data is transferred between the I2C master device and an I2C slave device through single or combined messages:

Single Messages

The I2C master reads data from an I2C slave device. An application can read from an I2C slave device using one of the read() methods.
The I2C master writes data to an I2C slave device. An application can write to an I2C slave device using one of the write() methods.

Combined Messages Messages

The I2C master issues at least two reads and/or writes to one or more slaves.

To a single slave

An application can explicitly start a combined message using begin(), issues several read or write operations using the read() and write() methods then end the combined message using end(). An application can also use the convenience methods read(subaddress, subaddressSize,...) and write(subaddress, subaddressSize,...) that respectively read and write from slave device subaddresses or register addresses. The following example illustrates the use of begin() and end() to implement the read(subaddress, subaddressSize,...) method:

 public int read(int subaddress, int subaddressSize, byte[] dstBuf, int dstOff, int dstLen) throws IOException,
         PeripheralNotAvailableException {
     if (subaddress < 0 || subaddressSize < 1 || subaddressSize > 4)
         throw IllegalArgumentException();
     byte[] subaddr = new byte[] { (byte) ((subaddress >> 24) & 0xFF), (byte) ((subaddress >> 16) & 0xFF),
             (byte) ((subaddress >> 8) & 0xFF), (byte) ((subaddress >> 0) & 0xFF), };
     try {
         begin();
         write(subaddr, subaddr.length - subaddressSize, subaddressSize); // Writes the subaddress
         return read(dstBuf, dstOff, dstLen); // Read the data at that subaddress
     } finally {
         end();
     }
 }
 

To several salves

Issuing several reads and/or writes to several slaves is not supported.

When the data exchange is over, an application should call the I2CDevice.close() method to release the I2C slave device. Any further attempt to write to or read from an I2C slave device which has been closed will result in a PeripheralNotAvailableException been thrown.

See Also:

PeripheralNotAvailableException

Field Summary

Fields inherited from interface com.oracle.deviceaccess.Peripheral

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN, UNDEFINED_ID

Method Summary

Methods

Modifier and Type	Method and Description
void	begin() Demarcates the beginning of an I2C transaction so that the subsequent read and write operations will be part of the same I2C combined message.
void	end() Demarcates the end of a transaction hence ending the I2C combined message.
int	read() Reads one byte of data from this slave device.
int	read(byte[] dstBuf, int dstOff, int dstLen) Reads up to dstLen bytes of data from this slave device into an array of bytes.
int	read(int skip, byte[] dstBuf, int dstOff, int dstLen) Reads up to dstLen bytes of data from this slave device into an array of bytes skipping the first skip bytes read.
int	read(int subaddress, int subaddressSize, byte[] dstBuf, int dstOff, int dstLen) Reads up to dstLen bytes of data from a subaddress or register address of this slave device into an array of bytes.
int	read(int subaddress, int subaddressSize, int skip, byte[] dstBuf, int dstOff, int dstLen) Reads up to dstLen bytes of data from a subaddress or register address of this slave device into an array of bytes skipping the first skip bytes read.
void	write(byte[] srcBuf, int srcOff, int srcLen) Writes to this slave device srcLen bytes from buffer srcBuf.
void	write(int srcData) Writes one byte to this slave device.
void	write(int subaddress, int subaddressSize, byte[] srcBuf, int srcOff, int srcLen) Writes to a subaddress or register address of this slave device srcLen bytes from buffer srcBuf.

Methods inherited from interface com.oracle.deviceaccess.Peripheral

close, getID, getName, getProperties, isOpen

Method Detail

begin

void begin()
           throws java.io.IOException,
                  PeripheralNotAvailableException

Demarcates the beginning of an I2C transaction so that the subsequent read and write operations will be part of the same I2C combined message.

Specified by:

begin in interface Transactional

Throws:

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.io.IOException - if an IO error occurred.

InvalidStateException - if a transaction is already in progress.

end

void end()
         throws java.io.IOException,
                PeripheralNotAvailableException

Demarcates the end of a transaction hence ending the I2C combined message.

Specified by:

end in interface Transactional

Throws:

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.io.IOException - if an IO error occurred.

InvalidStateException - if a transaction is not currently in progress.

read

int read()
         throws java.io.IOException,
                PeripheralNotAvailableException

Reads one byte of data from this slave device. The byte is returned as an int in the range 0 to 255.

Returns:

the unsigned 8-bit value read.

Throws:

java.io.IOException - if an I/O error occurs.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

read

int read(byte[] dstBuf,
       int dstOff,
       int dstLen)
         throws java.io.IOException,
                PeripheralNotAvailableException

Reads up to dstLen bytes of data from this slave device into an array of bytes.

Parameters:

dstBuf - the buffer into which the data is read.

dstOff - the offset in dstBuf where to start copying the bytes read.

dstLen - the maximum number of bytes to read.

Returns:

the total number of bytes read into the buffer.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.NullPointerException - If dstBuf is null.

java.lang.IndexOutOfBoundsException - dstOff or dstLen points or results in pointing outside dstBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

read

int read(int skip,
       byte[] dstBuf,
       int dstOff,
       int dstLen)
         throws java.io.IOException,
                PeripheralNotAvailableException

Reads up to dstLen bytes of data from this slave device into an array of bytes skipping the first skip bytes read.

Parameters:

skip - the number of read bytes that must be ignored/skipped before filling in the dstBuf buffer.

dstBuf - the buffer into which the data is read.

dstOff - the offset in dstBuf where to start copying the bytes read.

dstLen - the maximum number of bytes to read.

Returns:

the total number of bytes read into the buffer.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.NullPointerException - If dstBuf is null.

java.lang.IndexOutOfBoundsException - dstOff or dstLen points or results in pointing outside dstBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

read

int read(int subaddress,
       int subaddressSize,
       byte[] dstBuf,
       int dstOff,
       int dstLen)
         throws java.io.IOException,
                PeripheralNotAvailableException

Reads up to dstLen bytes of data from a subaddress or register address of this slave device into an array of bytes. The most significant bytes (MSB) of the subaddress or register address are transferred first.

Parameters:

subaddress - the slave device's subaddress or register address from where to start reading.

subaddressSize - the slave device's subaddress or register address size (1-4 bytes).

dstBuf - the buffer into which the data is read.

dstOff - the offset in dstBuf where to start copying the bytes read.

dstLen - the maximum number of bytes to read.

Returns:

the total number of bytes read into the buffer.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.NullPointerException - If dstBuf is null.

java.lang.IndexOutOfBoundsException - dstOff or dstLen points or results in pointing outside dstBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.lang.IllegalArgumentException - if subaddress is negative or subaddressSize is not between 1 and 4.

read

int read(int subaddress,
       int subaddressSize,
       int skip,
       byte[] dstBuf,
       int dstOff,
       int dstLen)
         throws java.io.IOException,
                PeripheralNotAvailableException

Reads up to dstLen bytes of data from a subaddress or register address of this slave device into an array of bytes skipping the first skip bytes read. The most significant bytes (MSB) of the subaddress or register address are transferred first.

Parameters:

subaddress - the slave device's subaddress or register address from where to start reading.

subaddressSize - the slave device's subaddress or register address size (1-4 bytes).

skip - the number of read bytes that must be ignored/skipped before filling in the dstBuf buffer.

dstBuf - the buffer into which the data is read.

dstOff - the offset in dstBuf where to start copying the bytes read.

dstLen - the maximum number of bytes to read.

Returns:

the total number of bytes read into the buffer.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.NullPointerException - If dstBuf is null.

java.lang.IndexOutOfBoundsException - dstOff or dstLen points or results in pointing outside dstBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.lang.IllegalArgumentException - if subaddress is negative or subaddressSize is not between 1 and 4.

write

void write(byte[] srcBuf,
         int srcOff,
         int srcLen)
           throws java.io.IOException,
                  PeripheralNotAvailableException

Writes to this slave device srcLen bytes from buffer srcBuf.

Parameters:

srcBuf - the buffer containing the bytes to write.

srcOff - the offset in srcBuf of the first byte to write.

srcLen - the number of bytes from srcBuf to write.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.NullPointerException - If srcBuf is null.

java.lang.IndexOutOfBoundsException - srcOff or srcLen points or results in pointing outside srcBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

write

void write(int srcData)
           throws java.io.IOException,
                  PeripheralNotAvailableException

Writes one byte to this slave device. The eight low-order bits of the argument data are written. The 24 high-order bits of srcData are ignored.

Parameters:

srcData - the byte to be written

Throws:

java.io.IOException - if an I/O error occurred

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

write

void write(int subaddress,
         int subaddressSize,
         byte[] srcBuf,
         int srcOff,
         int srcLen)
           throws java.io.IOException,
                  PeripheralNotAvailableException

Writes to a subaddress or register address of this slave device srcLen bytes from buffer srcBuf. The most significant bytes (MSB) of the subaddress or register address are transferred first.

Parameters:

subaddress - the slave device's subaddress or register address where to start writing.

subaddressSize - the slave device's subaddress or register address size (1-4 bytes).

srcBuf - the buffer containing the bytes to write.

srcOff - the offset in srcBuf of the first byte to write.

srcLen - the number of bytes from srcBuf to write.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.NullPointerException - If srcBuf is null.

java.lang.IndexOutOfBoundsException - srcOff or srcLen points or results in pointing outside srcBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.lang.IllegalArgumentException - if subaddress is negative or subaddressSize is not between 1 and 4.