org.joshvm.j2me.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 (connected to the same bus). 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 bytesRead = 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
 }
 

The preceding example is using a try-with-resources statement; the I2CDevice.close method is automatically invoked by the platform at the end of the statement.

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.

Since:

1.0

Method Summary

Methods

Modifier and Type	Method and Description
I2CCombinedMessage	appendRead(I2CDevice slave, ByteBuffer rxBuf) Appends a read message/operation from the provided I2C slave device.
I2CCombinedMessage	appendRead(I2CDevice slave, int rxSkip, ByteBuffer rxBuf) Appends a read message/operation from the provided I2C slave device.
I2CCombinedMessage	appendWrite(I2CDevice slave, 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,
                            ByteBuffer rxBuf)
                              throws IOException,
                                     ClosedDeviceException

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

Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffer until the operation has completed - that is: until the transfer method has been invoked and has returned.

The appended operation will have a behavior equivalent to that of the I2CDevice#read(java.nio.ByteBuffer) method.

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:

NullPointerException - if rxBuf is null.

IllegalStateException - if this message has already been assembled and transferred once.

ClosedDeviceException - if the device has been closed.

IllegalArgumentException - if appending the read operation to a slave on a different bus than the one this I2CCombinedMessage object was created for.

IOException - if some other I/O error occurs.

appendRead

I2CCombinedMessage appendRead(I2CDevice slave,
                            int rxSkip,
                            ByteBuffer rxBuf)
                              throws IOException,
                                     ClosedDeviceException

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

Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffer until the operation has completed - that is: until the transfer method has been invoked and has returned.

The appended operation will have a behavior equivalent to that of the I2CDevice#read(int, java.nio.ByteBuffer) method.

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:

NullPointerException - if rxBuf is null.

IllegalStateException - if this message has already been assembled and transferred once.

ClosedDeviceException - if the device has been closed.

IllegalArgumentException - if rxSkip is negative or if appending the read operation to a slave on a different bus than the one this I2CCombinedMessage object was created for.

IOException - if some other I/O error occurs.

appendWrite

I2CCombinedMessage appendWrite(I2CDevice slave,
                             ByteBuffer txBuf)
                               throws IOException,
                                      ClosedDeviceException

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

Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffer until the operation has completed - that is: until the transfer method has been invoked and has returned.

The appended operation will have a behavior equivalent to that of the I2CDevice#write(java.nio.ByteBuffer) method.

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:

NullPointerException - if txBuf is null.

IllegalStateException - if this message has already been assembled and transferred once.

ClosedDeviceException - if the device has been closed.

IllegalArgumentException - if appending the write operation to a slave on a different bus than the one this I2CCombinedMessage object was created for.

IOException - if some other I/O error occurs.

transfer

int[] transfer()
               throws 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.

This method may be invoked at any time. If another thread has already initiated a read or write operation upon any of the targeted slave devices, however, then an invocation of this method will block until the first operation is complete.

Once transferred no additional operation can be appended anymore to this combined message. Any such attempt will result in a IllegalStateException to be thrown. Nevertheless, this I2CCombinedMessage object can be reused several times to perform the same sequence of operations. The data transferred to or from each of the provided ByteBuffers is determined by their respective current position and remaining attributes at the time this method is call.
Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffers until the transfer has completed.

Returns:

an array (possibly empty) 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).

IOException - if some other I/O error occurred