com.oracle.deviceaccess.i2cbus

Class I2CCombinedMessage

java.lang.Object

com.oracle.deviceaccess.i2cbus.I2CCombinedMessage

public class I2CCombinedMessage
extends java.lang.Object

The I2CCombinedMessage class allows for constructing a combined message. A combined message may be constituted of at least two reads and/or writes to one or more I2C slaves. A combined message starts with a START bit and ends with a STOP bit. But each of read and write messages constituting the combined message following the very first of these messages starts with a REPEATED START bit (one that is not preceded by a STOP bit).

Here is an example of a combined message to several slaves:

 try (I2CDevice slave1 = PeripheralManager.open("TEMP", I2CDevice.class, null);
         I2CDevice slave2 = PeripheralManager.open("EEPROM", I2CDevice.class, null)) {
     ByteBuffer temp = ByteBuffer.allocateDirect(4);
     byte[] addr = new byte[]{...};
     int byteRead = new I2CCombinedMessage()
             .appendRead(slave1, temp) // Reads the temperature from TEMP sensor
             .appendWrite(slave2, ByteBuffer.wrap(addr)) // Writes the address to EEPROM to select the location
             .appendWrite(slave2, temp) // Writes the temperature at the selected EEPROM address 
             .transfer()[0];
 } catch (IOException ioe) {
     // Handle exception
 }
 

Note that the preceding example is using a try-with-resources statement and that the Peripheral.close() method is automatically invoked by the platform at the end of the statement.

Note that while a combined message containing a single read or a single write or a write followed by a read to the same I2C slave device can be constructed using this class, it is more effective to use directly the I2CDevice.read(), I2CDevice.write(), I2CDevice.read(subaddress,...) I2CDevice.write(subaddress,...) methods for that purpose.

Constructor Summary

Constructors

Constructor and Description
I2CCombinedMessage() Creates a new I2CCombinedMessage instance.

Method Summary

Methods

Modifier and Type	Method and Description
I2CCombinedMessage	appendRead(I2CDevice slave, java.nio.ByteBuffer rxBuf) Appends a read message/operation from the provided I2C slave device.
I2CCombinedMessage	appendRead(I2CDevice slave, int rxSkip, java.nio.ByteBuffer rxBuf) Appends a read message/operation from the provided I2C slave device.
I2CCombinedMessage	appendWrite(I2CDevice slave, java.nio.ByteBuffer txBuf) Appends a write message/operation from the provided I2C slave device.
int[]	transfer() Transfers this combined message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

I2CCombinedMessage

public I2CCombinedMessage()

Creates a new I2CCombinedMessage instance.

Method Detail

appendRead

public I2CCombinedMessage appendRead(I2CDevice slave,
                            java.nio.ByteBuffer rxBuf)
                              throws ClosedPeripheralException

Appends a read message/operation from the provided I2C slave device. Reads up to rwBuf.remaining() bytes of data from this slave device into the buffer rxBuf.

Parameters:

slave - the I2C slave device to read from.

rxBuf - the buffer into which the data is read.

Returns:

a reference to this I2CCombinedMessage object.

Throws:

java.lang.NullPointerException - If rxBuf is null.

java.lang.IllegalStateException - if this message has already been transferred once.

ClosedPeripheralException - if the peripheral has been closed.

java.lang.IllegalArgumentException - if appending the read operation to a slave on a different bus.

appendRead

public I2CCombinedMessage appendRead(I2CDevice slave,
                            int rxSkip,
                            java.nio.ByteBuffer rxBuf)
                              throws java.io.IOException,
                                     ClosedPeripheralException

Appends a read message/operation from the provided I2C slave device. Reads up to rwBuf.remaining() bytes of data from this slave device into the buffer skipping rxBuf the first rxSkip bytes read.

Parameters:

slave - the I2C slave device to read from.

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

rxBuf - the buffer into which the data is read.

Returns:

a reference to this I2CCombinedMessage object.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.NullPointerException - If rxBuf is null.

java.lang.IllegalStateException - if this message has already been transferred once.

ClosedPeripheralException - if the peripheral has been closed.

java.lang.IllegalArgumentException - if rxSkip is negative or if appending the read operation to a slave on a different bus.

appendWrite

public I2CCombinedMessage appendWrite(I2CDevice slave,
                             java.nio.ByteBuffer txBuf)
                               throws java.io.IOException,
                                      ClosedPeripheralException

Appends a write message/operation from the provided I2C slave device. Writes to this slave device txBuff.remaining() bytes from the buffer txBuf.

Parameters:

slave - the I2C slave device to write to.

txBuf - the buffer containing the bytes to write.

Returns:

a reference to this I2CCombinedMessage object.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.NullPointerException - If txBuf is null.

java.lang.IndexOutOfBoundsException - txOff or txLen points or results in pointing outside txBuf.

java.lang.IllegalStateException - if this message has already been transferred once.

ClosedPeripheralException - if the peripheral has been closed.

java.lang.IllegalArgumentException - if appending the write operation to a slave on a different bus.

transfer

public int[] transfer()
               throws java.io.IOException,
                      UnavailablePeripheralException,
                      ClosedPeripheralException

Transfers this combined message. This will result in each of the contained messages/operations to be sent/executed in the same order they have been appended to this combined message.

Once transfer no additional operation can be appended anymore to this combined message. Any such attempt will result in a IllegalStateException to be thrown.
This combined message can be transferred several times.

Returns:

an array containing the number of bytes read for each of the read operations of this combined message; the results of each read operations appear in the very same order the read operations have been appended to this combined message.

Throws:

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if any of the targeted peripherals is not currently available (has been closed).