public interface I2CDevice extends Peripheral, Transactional
I2CDevice
interface provides methods for sending and receiving data to/from an I2C slave device.
Each I2C slave device is identified by a numerical ID and by a name. I2CDevice
instance can be opened by a call to one of the PeripheralManager.open()
methods.
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, byte[] dstBuf, int dstOff, int dstLen) throws IOException, PeripheralNotAvailableException { 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(subaddr, subaddr.length - subaddressSize, subaddressSize); // Writes the subaddress return read(dstBuf, dstOff, dstLen); // Read the data at that subaddress } finally { end(); } }
I2CDevice.close()
method to release
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 PeripheralNotAvailableException
been thrown.
XXX: the current API does not allow for reading/writing subsequently to/from different buffers without sending a
repeated start between subsequent reads or writes.PeripheralNotAvailableException
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN, UNDEFINED_ID
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(byte[] dstBuf,
int dstOff,
int dstLen)
Reads up to
dstLen bytes of data from this slave device into an array of bytes. |
int |
read(int skip,
byte[] dstBuf,
int dstOff,
int dstLen)
Reads up to
dstLen bytes of data from this slave device into an array of bytes skipping the first
skip bytes read. |
int |
read(int subaddress,
int subaddressSize,
byte[] dstBuf,
int dstOff,
int dstLen)
Reads up to
dstLen bytes of data from a subaddress or register address of this slave device into an array
of bytes. |
int |
read(int subaddress,
int subaddressSize,
int skip,
byte[] dstBuf,
int dstOff,
int dstLen)
Reads up to
dstLen bytes of data from a subaddress or register address of this slave device into an array
of bytes skipping the first skip bytes read. |
void |
write(byte[] srcBuf,
int srcOff,
int srcLen)
Writes to this slave device
srcLen bytes from buffer srcBuf . |
void |
write(int srcData)
Writes one byte to this slave device.
|
void |
write(int subaddress,
int subaddressSize,
byte[] srcBuf,
int srcOff,
int srcLen)
Writes to a subaddress or register address of this slave device
srcLen bytes from buffer srcBuf . |
close, getID, getName, getProperties, isOpen
void begin() throws java.io.IOException, PeripheralNotAvailableException
begin
in interface Transactional
PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).java.io.IOException
- if an IO error occurred.InvalidStateException
- if a transaction is already in progress.void end() throws java.io.IOException, PeripheralNotAvailableException
end
in interface Transactional
PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).java.io.IOException
- if an IO error occurred.InvalidStateException
- if a transaction is not currently in progress.int read() throws java.io.IOException, PeripheralNotAvailableException
int
in the range 0
to
255
.java.io.IOException
- if an I/O error occurs.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int read(byte[] dstBuf, int dstOff, int dstLen) throws java.io.IOException, PeripheralNotAvailableException
dstLen
bytes of data from this slave device into an array of bytes.dstBuf
- the buffer into which the data is read.dstOff
- the offset in dstBuf
where to start copying the bytes read.dstLen
- the maximum number of bytes to read.java.io.IOException
- if an IO error occurred.java.lang.NullPointerException
- If dstBuf
is null
.java.lang.IndexOutOfBoundsException
- dstOff
or dstLen
points or results in pointing outside dstBuf
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int read(int skip, byte[] dstBuf, int dstOff, int dstLen) throws java.io.IOException, PeripheralNotAvailableException
dstLen
bytes of data from this slave device into an array of bytes skipping the first
skip
bytes read.skip
- the number of read bytes that must be ignored/skipped before filling in the dstBuf
buffer.dstBuf
- the buffer into which the data is read.dstOff
- the offset in dstBuf
where to start copying the bytes read.dstLen
- the maximum number of bytes to read.java.io.IOException
- if an IO error occurred.java.lang.NullPointerException
- If dstBuf
is null
.java.lang.IndexOutOfBoundsException
- dstOff
or dstLen
points or results in pointing outside dstBuf
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int read(int subaddress, int subaddressSize, byte[] dstBuf, int dstOff, int dstLen) throws java.io.IOException, PeripheralNotAvailableException
dstLen
bytes of data from a subaddress or register address of this slave device into an array
of bytes. The most significant bytes (MSB) of the subaddress or register address are transferred first.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).dstBuf
- the buffer into which the data is read.dstOff
- the offset in dstBuf
where to start copying the bytes read.dstLen
- the maximum number of bytes to read.java.io.IOException
- if an IO error occurred.java.lang.NullPointerException
- If dstBuf
is null
.java.lang.IndexOutOfBoundsException
- dstOff
or dstLen
points or results in pointing outside dstBuf
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).java.lang.IllegalArgumentException
- if subaddress
is negative or subaddressSize
is not between 1
and 4
.int read(int subaddress, int subaddressSize, int skip, byte[] dstBuf, int dstOff, int dstLen) throws java.io.IOException, PeripheralNotAvailableException
dstLen
bytes of data from a subaddress or register address of this slave device into an array
of bytes skipping the first skip
bytes read. The most significant bytes (MSB) of the subaddress or
register address are transferred first.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 dstBuf
buffer.dstBuf
- the buffer into which the data is read.dstOff
- the offset in dstBuf
where to start copying the bytes read.dstLen
- the maximum number of bytes to read.java.io.IOException
- if an IO error occurred.java.lang.NullPointerException
- If dstBuf
is null
.java.lang.IndexOutOfBoundsException
- dstOff
or dstLen
points or results in pointing outside dstBuf
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).java.lang.IllegalArgumentException
- if subaddress
is negative or subaddressSize
is not between 1
and 4
.void write(byte[] srcBuf, int srcOff, int srcLen) throws java.io.IOException, PeripheralNotAvailableException
srcLen
bytes from buffer srcBuf
.srcBuf
- the buffer containing the bytes to write.srcOff
- the offset in srcBuf
of the first byte to write.srcLen
- the number of bytes from srcBuf
to write.java.io.IOException
- if an IO error occurred.java.lang.NullPointerException
- If srcBuf
is null
.java.lang.IndexOutOfBoundsException
- srcOff
or srcLen
points or results in pointing outside srcBuf
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).void write(int srcData) throws java.io.IOException, PeripheralNotAvailableException
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 occurredPeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).void write(int subaddress, int subaddressSize, byte[] srcBuf, int srcOff, int srcLen) throws java.io.IOException, PeripheralNotAvailableException
srcLen
bytes from buffer srcBuf
.
The most significant bytes (MSB) of the subaddress or register address are transferred first.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).srcBuf
- the buffer containing the bytes to write.srcOff
- the offset in srcBuf
of the first byte to write.srcLen
- the number of bytes from srcBuf
to write.java.io.IOException
- if an IO error occurred.java.lang.NullPointerException
- If srcBuf
is null
.java.lang.IndexOutOfBoundsException
- srcOff
or srcLen
points or results in pointing outside srcBuf
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).java.lang.IllegalArgumentException
- if subaddress
is negative or subaddressSize
is not between 1
and 4
.Copyright (c) 2012, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.