public interface I2CDevice extends Peripheral<I2CDevice>, java.nio.channels.ByteChannel, Transactional, BufferAccess<java.nio.ByteBuffer>
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
PeripheralManager.open(id,...)
methods using its ID or by a call to one of the
PeripheralManager.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
PeripheralManager.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:
read()
methods. write()
methods.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, UnavailablePeripheralException { 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(); } }
I2CCombinedMessage
object.
I2CDevice.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 ClosedPeripheralException
been thrown.
Opening an I2CDevice
instance is subject to permission checks (see I2CPermission
).I2CPermission
,
ClosedPeripheralException
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN
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.
|
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 ofthis 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.
|
close, getDescriptor, isOpen, tryLock, unlock
getInputBuffer, getOutputBuffer
void begin() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
begin
in interface Transactional
UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- if some other I/O error occurs.java.lang.IllegalStateException
- if a transaction is already in progress.void end() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
end
in interface Transactional
UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- if some other I/O error occurs.java.lang.IllegalStateException
- if a transaction is not currently in progress.int read() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
int
in the range 0
to
255
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int read(java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
read
in interface java.nio.channels.ReadableByteChannel
dst
- The buffer into which bytes are to be transferred-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If dst
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursint read(int skip, java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
skip
bytes read.
Apart from skipping the first skip
bytes, this method behaves identically to
read(java.nio.ByteBuffer)
.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-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If dst
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursint read(int subaddress, int subaddressSize, java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.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-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If dst
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursjava.lang.IllegalArgumentException
- if subaddress
is negative or subaddressSize
is not between 1
and 4
.int read(int subaddress, int subaddressSize, int skip, java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.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-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If dst
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursjava.lang.IllegalArgumentException
- if subaddress
is negative or subaddressSize
is not between 1
and 4
.int write(java.nio.ByteBuffer src) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
write
in interface java.nio.channels.WritableByteChannel
src
- The buffer from which bytes are to be retrievedjava.lang.NullPointerException
- If src
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursvoid write(int srcData) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
data
are written. The 24
high-order bits of srcData
are ignored.srcData
- the byte to be writtenjava.io.IOException
- if an I/O error occurredUnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int write(int subaddress, int subaddressSize, java.nio.ByteBuffer src) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.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 retrievedjava.lang.NullPointerException
- If src
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursjava.lang.IllegalArgumentException
- if subaddress
is negative or subaddressSize
is not between 1
and 4
.Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved.
Legal Notices