jdk.dio.i2cbus

Interface I2CDevice

All Superinterfaces:

java.lang.AutoCloseable, BufferAccess<java.nio.ByteBuffer>, java.nio.channels.ByteChannel, java.nio.channels.Channel, java.io.Closeable, Device<I2CDevice>, java.nio.channels.ReadableByteChannel, Transactional, java.nio.channels.WritableByteChannel

public interface I2CDevice
extends Device<I2CDevice>, java.nio.channels.ByteChannel, Transactional, BufferAccess<java.nio.ByteBuffer>

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

An I2C slave device may be identified by the numerical ID and by the name (if any defined) that correspond to its registered configuration. An I2CDevice instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name. When an I2CDevice instance is opened with an ad-hoc I2CDeviceConfig configuration (which includes its hardware addressing information) using one of the DeviceManager.open(config,...) it is not assigned any ID nor name.

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, ByteBuffer dstBuf) throws IOException,
         UnavailableDeviceException {
     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(ByteBuffer.wrap(subaddr, subaddr.length - subaddressSize, subaddressSize)); // Writes the subaddress
         return read(dstBuf); // Read the data at that subaddress
     } finally {
         end();
     }
 }
 

To several salves

An application can issue several reads and/or writes to several slaves using a I2CCombinedMessage object.

When the data exchange is over, an application should call the close method to close 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 ClosedDeviceException been thrown.

Opening an I2CDevice instance is subject to permission checks (see I2CPermission ).

See Also:

I2CPermission, ClosedDeviceException

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	I2CDevice.Bus The Bus interface is a simplified abstraction of an I2C bus providing methods for creating combined messages.

Field Summary

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

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.
I2CDevice.Bus	getBus() Retrieves the Bus instance representing the I2C bus this device is connected to.
int	read() Reads one byte of data from this slave device.
int	read(java.nio.ByteBuffer dst) Reads a sequence of bytes from this slave device into the given buffer.
int	read(int skip, java.nio.ByteBuffer dst) Reads a sequence of bytes from this device into the given buffer, skipping the first skip bytes read.
int	read(int subaddress, int subaddressSize, java.nio.ByteBuffer dst) Reads a sequence of bytes from a subaddress or register address of this slave device into the given buffer.
int	read(int subaddress, int subaddressSize, int skip, java.nio.ByteBuffer dst) Reads a sequence of bytes from a subaddress or register address of this device into the given buffer, skipping the first skip bytes read.
int	write(java.nio.ByteBuffer src) Writes a sequence of bytes to this slave device from the given buffer.
void	write(int srcData) Writes one byte to this slave device.
int	write(int subaddress, int subaddressSize, java.nio.ByteBuffer src) Writes a sequence of bytes to a subaddress or register address of this slave device from the given buffer.

Methods inherited from interface jdk.dio.Device

close, getDescriptor, isOpen, tryLock, unlock

Methods inherited from interface jdk.dio.BufferAccess

getInputBuffer, getOutputBuffer

Method Detail

getBus

I2CDevice.Bus getBus()
                     throws java.io.IOException

Retrieves the Bus instance representing the I2C bus this device is connected to.
Note that even if this device is closed, a Bus instance for this device can still be retrieved.

Returns:

the Bus instance for this I2C device.

Throws:

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

begin

void begin()
           throws java.io.IOException,
                  UnavailableDeviceException,
                  ClosedDeviceException

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:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

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

java.lang.IllegalStateException - if a transaction is already in progress.

end

void end()
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

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

Specified by:

end in interface Transactional

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

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

java.lang.IllegalStateException - if a transaction is not currently in progress.

read

int read()
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

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 some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

read

int read(java.nio.ByteBuffer dst)
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Reads a sequence of bytes from this slave device into the given buffer.

Specified by:

read in interface java.nio.channels.ReadableByteChannel

Parameters:

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.lang.NullPointerException - If dst is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

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

read

int read(int skip,
       java.nio.ByteBuffer dst)
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Reads a sequence of bytes from this device into the given buffer, skipping the first skip bytes read.

Apart from skipping the first skip bytes, this method behaves identically to read(java.nio.ByteBuffer).

Parameters:

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

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.lang.NullPointerException - If dst is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

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

read

int read(int subaddress,
       int subaddressSize,
       java.nio.ByteBuffer dst)
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Reads a sequence of bytes from a subaddress or register address of this slave device into the given buffer. The most significant bytes (MSB) of the subaddress or register address are transferred first.

An attempt is made to read up to r bytes from the device, where r is the number of bytes remaining in the buffer, that is, dst.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is read, where 0 <= n <= r. This byte sequence will be transferred into the buffer so that the first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position at the moment this method is invoked. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

A read operation will block until the requested r bytes are read or an error occurs.

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

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

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.lang.NullPointerException - If dst is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

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

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

read

int read(int subaddress,
       int subaddressSize,
       int skip,
       java.nio.ByteBuffer dst)
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Reads a sequence of bytes from a subaddress or register address of this device into the given buffer, skipping the first skip bytes read. The most significant bytes (MSB) of the subaddress or register address are transferred first.

An attempt is made to read up to r bytes from the device, where r is the number of bytes remaining in the buffer, that is, dst.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is read, where 0 <= n <= r. This byte sequence will be transferred into the buffer so that the first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position at the moment this method is invoked. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

A read operation will block until the requested r bytes are read or an error occurs.

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

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 dst buffer.

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.lang.NullPointerException - If dst is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

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

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

write

int write(java.nio.ByteBuffer src)
          throws java.io.IOException,
                 UnavailableDeviceException,
                 ClosedDeviceException

Writes a sequence of bytes to this slave device from the given buffer.

Specified by:

write in interface java.nio.channels.WritableByteChannel

Parameters:

src - The buffer from which bytes are to be retrieved

Returns:

The number of bytes written, possibly zero

Throws:

java.lang.NullPointerException - If src is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

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

write

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

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

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

write

int write(int subaddress,
        int subaddressSize,
        java.nio.ByteBuffer src)
          throws java.io.IOException,
                 UnavailableDeviceException,
                 ClosedDeviceException

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

An attempt is made to write up to r bytes to the device, where r is the number of bytes remaining in the buffer, that is, src.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is written, where 0 <= n <= r. This byte sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is invoked; the index of the last byte written will be p + n - 1. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

A write operation will return only after writing all of the r requested bytes.

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

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

src - The buffer from which bytes are to be retrieved

Returns:

The number of bytes written, possibly zero

Throws:

java.lang.NullPointerException - If src is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

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

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