jdk.dio.i2cbus

Interface I2CCombinedMessage

public interface I2CCombinedMessage

The I2CCombinedMessage interface provides methods 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 = DeviceManager.open("TEMP", I2CDevice.class, null);
         I2CDevice slave2 = DeviceManager.open("EEPROM", I2CDevice.class, null)) {
     ByteBuffer temp = ByteBuffer.allocateDirect(4);
     byte[] addr = new byte[]{...};
     int byteRead = slave1.getBus().createCombinedMessage()
             .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 I2CDevice.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.

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.

Method Detail

appendRead

I2CCombinedMessage appendRead(I2CDevice slave,
                            java.nio.ByteBuffer rxBuf)
                              throws java.io.IOException,
                                     ClosedDeviceException

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.

ClosedDeviceException - if the device has been closed.

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

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

appendRead

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

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.lang.NullPointerException - If rxBuf is null.

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

ClosedDeviceException - if the device has been closed.

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

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

appendWrite

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

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.lang.NullPointerException - If txBuf is null.

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

ClosedDeviceException - if the device has been closed.

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

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

transfer

int[] transfer()
               throws java.io.IOException,
                      UnavailableDeviceException,
                      ClosedDeviceException

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:

UnavailableDeviceException - if any of the targeted devices is not currently available - such as it is locked by another application.

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

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