org.joshvm.j2me.dio.i2cbus

Interface I2CDevice

All Superinterfaces:

Device

public interface I2CDevice
extends Device

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 numeric 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,...) methods 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 use the methods read(subaddress, subaddressSize,...) and write(subaddress, subaddressSize,...) that rely on combined messages to respectively read and write from slave device subaddresses or register addresses.

To several slaves

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

Since:

1.0

See Also:

I2CCombinedMessage, 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 org.joshvm.j2me.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
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(ByteBuffer dst) Reads a sequence of bytes from this slave device into the given buffer.
int	read(int skip, 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, 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, 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(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, 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 org.joshvm.j2me.dio.Device

close, isOpen, tryLock, unlock

Method Detail

getBus

I2CDevice.Bus getBus()
                     throws IOException

Retrieves the Bus instance representing the I2C bus this device is connected to.
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:

IOException - if some other I/O error occurs.

read

int read()
         throws 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.

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

Returns:

the unsigned 8-bit value read.

Throws:

IOException - if some other I/O error occurs (e.g. a NACK from the slave device was received).

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(ByteBuffer dst)
         throws IOException,
                UnavailableDeviceException,
                ClosedDeviceException

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

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.

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

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

Parameters:

dst - the buffer into which bytes are to be transferred.

Returns:

the number of bytes read into dst, possibly zero.

Throws:

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.

IOException - if some other I/O error occurs (e.g. a NACK from the slave device was received).

read

int read(int skip,
       ByteBuffer dst)
         throws 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 into dst, possibly zero.

Throws:

NullPointerException - if dst is null.

IllegalArgumentException - if skip is negative.

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

ClosedDeviceException - if the device has been closed.

IOException - if some other I/O error occurs (e.g. a NACK from the slave device was received).

read

int read(int subaddress,
       int subaddressSize,
       ByteBuffer dst)
         throws 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.

This method may be invoked at any time. If another thread has already initiated a read or 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 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 into dst, possibly zero.

Throws:

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.

IOException - if some other I/O error occurs (e.g. a NACK from the slave device was received).

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

read

int read(int subaddress,
       int subaddressSize,
       int skip,
       ByteBuffer dst)
         throws 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.

This method may be invoked at any time. If another thread has already initiated a read or 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 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 into dst, possibly zero.

Throws:

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.

IOException - if some other I/O error occurs (e.g. a NACK from the slave device was received).

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

write

int write(ByteBuffer src)
          throws IOException,
                 UnavailableDeviceException,
                 ClosedDeviceException

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

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 read or write operation upon this slave device, however, then an invocation of this method will block until the first operation is complete.

Parameters:

src - the buffer from which bytes are to be retrieved.

Returns:

the number of bytes written from src, possibly zero.

Throws:

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.

IOException - if some other I/O error occurs (e.g. a NACK from the slave device was received).

write

void write(int srcData)
           throws 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.

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

Parameters:

srcData - the byte to be written.

Throws:

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 some other I/O error occurs (e.g. a NACK from the slave device was received).

write

int write(int subaddress,
        int subaddressSize,
        ByteBuffer src)
          throws 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 read or 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 from src, possibly zero.

Throws:

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.

IOException - if some other I/O error occurs (e.g. a NACK from the slave device was received).

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