Class I2CDevice
- All Implemented Interfaces:
DeviceInterface
,I2CDeviceInterface
,I2CSMBusInterface
,AutoCloseable
public class I2CDevice extends Object implements I2CDeviceInterface
- See Also:
- I2C Bus Specification
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
I2CDevice.Builder
I2C device builder.static class
I2CDevice.ProbeMode
Nested classes/interfaces inherited from interface com.diozero.api.I2CDeviceInterface
I2CDeviceInterface.I2CMessage
-
Field Summary
Fields inherited from interface com.diozero.api.I2CSMBusInterface
MAX_I2C_BLOCK_SIZE
-
Constructor Summary
Constructors Constructor Description I2CDevice(int controller, int address)
I2CDevice(int controller, int address, I2CConstants.AddressSize addressSize)
Use thedefault
byte order
I2CDevice(int controller, int address, I2CConstants.AddressSize addressSize, ByteOrder byteOrder)
Use the default native device factoryI2CDevice(int controller, int address, ByteOrder byteOrder)
Use the default7-bit
address sizeI2CDevice(I2CDeviceFactoryInterface deviceFactory, int controller, int address, I2CConstants.AddressSize addressSize, ByteOrder byteOrder)
Construct an I2C device using the specified I2C bus / controller, device address, address size and byte order. -
Method Summary
Modifier and Type Method Description byte[]
blockProcessCall(int register, byte... txData)
SMBus Block Write - Block Read Process Callstatic I2CDevice.Builder
builder(int address)
Builder class for I2C devicesvoid
close()
Close this deviceint
getAddress()
I2CConstants.AddressSize
getAddressSize()
ByteOrder
getByteOrder()
int
getController()
boolean
probe(I2CDevice.ProbeMode mode)
Probe this I2C device to see if it is connectedshort
processCall(int register, short data)
SMBus Process Callboolean
readBit(int register, int bit)
Utility method that wrapsreadByteData(int)
to check if the specified bit number is set.byte[]
readBlockData(int register)
SMBus Block Read:i2c_smbus_read_block_data()
byte
readByte()
SMBus Receive Byte:i2c_smbus_read_byte()
byte
readByteData(int register)
SMBus Read Byte:i2c_smbus_read_byte_data()
int
readBytes(byte[] buffer)
Diozero SMBus extension to read the specified number of bytes from the devicebyte[]
readBytes(int length)
Utility method that wrapsreadBytes(byte[])
to read the specified number of bytes.ByteBuffer
readBytesAsByteBuffer(int length)
Utility method that wraps the response fromreadBytes(int)
in aByteBuffer
that is configured to use thebyte order
specified in the constructor.int
readI2CBlockData(int register, byte[] buffer)
I2C Block Read:i2c_smbus_read_i2c_block_data()
byte[]
readI2CBlockDataByteArray(int register, int length)
Utility method that wrapsreadI2CBlockData(int, byte[])
to read the specified number of bytes and return as a new byte array.ByteBuffer
readI2CBlockDataByteBuffer(int register, int length)
Utility method that wrapsreadI2CBlockData(int, byte[])
to read the specified number of bytes and return as aByteBuffer
using thebyte order
specified in the device constructor.int
readInt(int register)
Utility method that wrapsreadI2CBlockDataByteBuffer(int, int)
to read a signed int value from the requested register using thebyte order
specified in the constructor.int
readNoStop(byte registerAddress, int rxLength, byte[] rxData, boolean repeatedStart)
short
readShort(int register)
Utility method that invokes eitherreadWordData(int)
orreadWordSwapped(int)
to read a signed short value from the requested register in thebyte order
specified in the constructor.short
readUByte(int register)
Utility method that simply converts the response fromreadByteData(int)
to an unsigned byte.long
readUInt(int register)
Utility method that wrapsreadInt(int)
to read an unsigned int value from the requested register using thebyte order
specified in the constructor.long
readUInt(int register, int numBytes)
Utility method that wrapsreadI2CBlockDataByteArray(int, int)
to read an unsigned int value on the specified length from the requested register using thebyte order
specified in the constructor.int
readUShort(int register)
Utility method that wrapsreadShort(int)
to read an unsigned short value from the requested register using thebyte order
specified in the constructor.short
readWordData(int register)
SMBus Read Word:i2c_smbus_read_word_data()
short
readWordSwapped(int register)
SMBus Read Word Swapped:i2c_smbus_read_word_swapped()
void
readWrite(I2CDeviceInterface.I2CMessage[] messages, byte[] buffer)
void
writeBit(int register, int bit, boolean value)
Utility method that wrapsreadByteData(int)
andwriteByteData(int, byte)
to update the specified bit numbervoid
writeBlockData(int register, byte... data)
SMBus Block Write:i2c_smbus_write_block_data()
void
writeByte(byte data)
SMBus Send Byte:i2c_smbus_write_byte()
void
writeByteData(int register, byte value)
SMBus Write Byte:i2c_smbus_write_byte_data()
void
writeByteData(int register, int data)
Utility method that simply casts the int data parameter to byte and callswriteByteData(int, byte)
void
writeBytes(byte... data)
Diozero SMBus extension to write the specified byte array to the devicevoid
writeBytes(ByteBuffer buffer)
Utility method that wrapswriteBytes(byte[])
to write the available bytes in the specifiedByteBuffer
.void
writeI2CBlockData(int register, byte... data)
I2C Block Write:i2c_smbus_write_i2c_block_data()
void
writeQuick(byte bit)
SMBus Quick Commandvoid
writeWordData(int register, short value)
SMBus Write Word:i2c_smbus_write_word_data()
void
writeWordSwapped(int register, short value)
SMBus Write Word Swapped:i2c_smbus_write_word_swapped()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface com.diozero.api.I2CSMBusInterface
probe
-
Constructor Details
-
I2CDevice
- Parameters:
controller
- I2C bus controller numberaddress
- I2C device address- Throws:
RuntimeIOException
- If an I/O error occurred- See Also:
- I2C Bus Specification
-
I2CDevice
Use the default7-bit
address size- Parameters:
controller
- I2C bus controller numberaddress
- I2C device addressbyteOrder
- Thebyte order
that is only used in the additional non-SMBus I2C device utility methods- Throws:
RuntimeIOException
- If an I/O error occurred- See Also:
- I2C Bus Specification
-
I2CDevice
public I2CDevice(int controller, int address, I2CConstants.AddressSize addressSize) throws RuntimeIOExceptionUse thedefault
byte order
- Parameters:
controller
- I2C bus controller numberaddress
- I2C device addressaddressSize
- I2C device address size. Can be 7 or 10- Throws:
RuntimeIOException
- If an I/O error occurred- See Also:
- I2C Bus Specification
-
I2CDevice
public I2CDevice(int controller, int address, I2CConstants.AddressSize addressSize, ByteOrder byteOrder) throws RuntimeIOExceptionUse the default native device factory- Parameters:
controller
- I2C bus controller numberaddress
- I2C device addressaddressSize
- I2C device address size. Can be 7 or 10byteOrder
- thebyte order
that is only used in the additional non-SMBus I2C device utility methods- Throws:
RuntimeIOException
- If an I/O error occurred.- See Also:
- I2C Bus Specification
-
I2CDevice
public I2CDevice(I2CDeviceFactoryInterface deviceFactory, int controller, int address, I2CConstants.AddressSize addressSize, ByteOrder byteOrder) throws RuntimeIOExceptionConstruct an I2C device using the specified I2C bus / controller, device address, address size and byte order. Note that thebyte order
is only used in the utility methods.- Parameters:
deviceFactory
- Device factory to use to provision this devicecontroller
- I2C bus controller numberaddress
- I2C device addressaddressSize
- I2C device address size. Can be 7 or 10byteOrder
- thebyte order
that is only used in the additional non-SMBus I2C device utility methods- Throws:
RuntimeIOException
- If an I/O error occurred- See Also:
- I2C Bus Specification
-
-
Method Details
-
builder
Builder class for I2C devices- Parameters:
address
- the I2C device address- Returns:
- I2C device builder
-
getController
public int getController() -
getAddress
public int getAddress() -
getAddressSize
-
getByteOrder
-
close
Close this device- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceDeviceInterface
- Throws:
RuntimeIOException
-
probe
Probe this I2C device to see if it is connected- Specified by:
probe
in interfaceI2CSMBusInterface
- Parameters:
mode
- Probe mode- Returns:
- True if the probe is successful and the device is connected
-
writeQuick
public void writeQuick(byte bit)SMBus Quick Command
This sends a single bit to the device, at the place of the Rd/Wr bit.
A Addr Rd/Wr [A] P
- Specified by:
writeQuick
in interfaceI2CSMBusInterface
- Parameters:
bit
- The bit to write
-
readByte
SMBus Receive Byte:
i2c_smbus_read_byte()
This reads a single byte from a device, without specifying a device register. Some devices are so simple that this interface is enough; for others, it is a shorthand if you want to read the same register as in the previous SMBus command.
S Addr Rd [A] [Data] NA P
- Specified by:
readByte
in interfaceI2CSMBusInterface
- Returns:
- The byte data read (note caller needs to handle conversion to unsigned)
- Throws:
RuntimeIOException
- if an I/O error occurs
-
writeByte
SMBus Send Byte:
i2c_smbus_write_byte()
This operation is the reverse of Receive Byte: it sends a single byte to a device. See Receive Byte for more information.
S Addr Wr [A] Data [A] P
- Specified by:
writeByte
in interfaceI2CSMBusInterface
- Parameters:
data
- value to write- Throws:
RuntimeIOException
- if an I/O error occurs
-
readByteData
SMBus Read Byte:
i2c_smbus_read_byte_data()
This reads a single byte from a device, from a designated register. The register is specified through the Comm byte.
S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
- Specified by:
readByteData
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to read from- Returns:
- data read as byte (note caller needs to handle conversion to unsigned)
- Throws:
RuntimeIOException
- if an I/O error occurs
-
writeByteData
SMBus Write Byte:
i2c_smbus_write_byte_data()
This writes a single byte to a device, to a designated register. The register is specified through the Comm byte. This is the opposite of the Read Byte operation.
S Addr Wr [A] Comm [A] Data [A] P
- Specified by:
writeByteData
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to write tovalue
- value to write- Throws:
RuntimeIOException
- if an I/O error occurs
-
readWordData
SMBus Read Word:
i2c_smbus_read_word_data()
This operation is very like Read Byte; again, data is read from a device, from a designated register that is specified through the Comm byte. But this time, the data is a complete word (16 bits) in
Little Endian
order as per the SMBus specification.S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
Note that the byte order for the returned word data isLittle Endian
as per the SMBus specification, regardless of thebyte order
specified in the constructor- Specified by:
readWordData
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to read from- Returns:
- data read as a signed short in
Little Endian
byte order - Throws:
RuntimeIOException
- if an I/O error occurs
-
writeWordData
SMBus Write Word:
i2c_smbus_write_word_data()
This is the opposite of the Read Word operation. 16 bits of data is written to a device, to the designated register that is specified through the Comm byte. Note that the data is written in
Little Endian
byte order as per the SMBus specification.S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
Note that thebyte order
for the input value isLittle Endian
as per the SMBus specification, regardless of thebyte order
specified in the constructor- Specified by:
writeWordData
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to write tovalue
- value to write inLittle Endian
byte order- Throws:
RuntimeIOException
- if an I/O error occurs
-
readWordSwapped
SMBus Read Word Swapped:
i2c_smbus_read_word_swapped()
This operation is very like Read Byte; again, data is read from a device, from a designated register that is specified through the Comm byte. But this time, the data is a complete word (16 bits). Note this is the convenience function for reads where the two data bytes are the other way around (not SMBus compliant, but very popular.)
S Addr Wr [A] Comm [A] S Addr Rd [A] [DataHigh] A [DataLow] NA P
Note that the byte order for the returned word data isBig Endian
, regardless of thebyte order
specified in the constructor- Specified by:
readWordSwapped
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to read from- Returns:
- data read as a signed short in
Big Endian
byte order - Throws:
RuntimeIOException
- if an I/O error occurs
-
writeWordSwapped
SMBus Write Word Swapped:
i2c_smbus_write_word_swapped()
This is the opposite of the Read Word operation. 16 bits of data is written to a device, to the designated register that is specified through the Comm byte. Note that this is the convenience function for writes where the two data bytes are the other way around (not SMBus compliant, but very popular.)
S Addr Wr [A] Comm [A] DataHigh [A] DataLow [A] P
Note that thebyte order
for the input value isBig Endian
, regardless of thebyte order
specified in the constructor- Specified by:
writeWordSwapped
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to write tovalue
- value to write inBig Endian
byte order- Throws:
RuntimeIOException
- if an I/O error occurs
-
processCall
public short processCall(int register, short data)SMBus Process Call
This command selects a device register (through the Comm byte), sends 16 bits of data to it, and reads 16 bits of data in return.
S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
- Specified by:
processCall
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to write to / read fromdata
- value to write- Returns:
- the value read
-
readBlockData
public byte[] readBlockData(int register)SMBus Block Read:
i2c_smbus_read_block_data()
This command reads a block of up to 32 bytes from a device, from a designated register that is specified through the Comm byte. The amount of data is specified by the device in the Count byte.
S Addr Wr [A] Comm [A] S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
- Specified by:
readBlockData
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to read from- Returns:
- the data read up to 32 bytes in length
-
writeBlockData
public void writeBlockData(int register, byte... data)SMBus Block Write:
i2c_smbus_write_block_data()
The opposite of the Block Read command, this writes up to 32 bytes to a device, to a designated register that is specified through the Comm byte. The amount of data is specified in the Count byte.
S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
- Specified by:
writeBlockData
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to write todata
- the data to write (up to 32 bytes)
-
blockProcessCall
public byte[] blockProcessCall(int register, byte... txData)SMBus Block Write - Block Read Process Call
SMBus Block Write - Block Read Process Call was introduced in Revision 2.0 of the specification.
This command selects a device register (through the Comm byte), sends 1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.S Addr Wr [A] Comm [A] Count [A] Data [A] ... S Addr Rd [A] [Count] A [Data] ... A P
- Specified by:
blockProcessCall
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to write to and read fromtxData
- the byte array from which the data is written (up to 32 bytes)- Returns:
- the data read (up to 32 bytes)
-
readI2CBlockData
public int readI2CBlockData(int register, byte[] buffer)I2C Block Read:
i2c_smbus_read_i2c_block_data()
This command reads a block of bytes from a device, from a designated register that is specified through the Comm byte.
S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
- Specified by:
readI2CBlockData
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to read frombuffer
- the buffer to read the data into, the buffer length specifies the number of bytes to read- Returns:
- the number of bytes actually read
-
writeI2CBlockData
I2C Block Write:
i2c_smbus_write_i2c_block_data()
The opposite of the Block Read command, this writes bytes to a device, to a designated register that is specified through the Comm byte. Note that command lengths of 0, 2, or more bytes are supported as they are indistinguishable from data.
S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
- Specified by:
writeI2CBlockData
in interfaceI2CSMBusInterface
- Parameters:
register
- the register to write todata
- values to write- Throws:
RuntimeIOException
- if an I/O error occurs
-
readBytes
Diozero SMBus extension to read the specified number of bytes from the device- Specified by:
readBytes
in interfaceI2CSMBusInterface
- Parameters:
buffer
- byte array to populate, the length of the byte array indicates the number of bytes to read- Returns:
- the number of bytes read
- Throws:
RuntimeIOException
- if an I/O error occurs
-
writeBytes
Diozero SMBus extension to write the specified byte array to the device- Specified by:
writeBytes
in interfaceI2CSMBusInterface
- Parameters:
data
- the data to write- Throws:
RuntimeIOException
- if an I/O error occurs
-
readNoStop
public int readNoStop(byte registerAddress, int rxLength, byte[] rxData, boolean repeatedStart)- Specified by:
readNoStop
in interfaceI2CDeviceInterface
-
readWrite
- Specified by:
readWrite
in interfaceI2CDeviceInterface
-
writeByteData
Utility method that simply casts the int data parameter to byte and callswriteByteData(int, byte)
- Parameters:
register
- the register to write todata
- value to write- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
writeByteData(int, byte)
-
readUByte
Utility method that simply converts the response fromreadByteData(int)
to an unsigned byte. A short is returned to ensure that the returned value is unsigned- Parameters:
register
- the register to read from- Returns:
- byte data returned converted to unsigned byte (represented as a short)
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readByteData(int)
-
readBytesAsByteBuffer
Utility method that wraps the response fromreadBytes(int)
in aByteBuffer
that is configured to use thebyte order
specified in the constructor.- Parameters:
length
- number of bytes to read- Returns:
- A
ByteBuffer
containing the bytes read using the byte order specified in the constructor - Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readBytes(int)
,ByteBuffer.wrap(byte[])
-
writeBytes
Utility method that wrapswriteBytes(byte[])
to write the available bytes in the specifiedByteBuffer
. The byte order of data in the ByteBuffer is unchanged.- Parameters:
buffer
- theByteBuffer
containing the data to write- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
writeBytes(byte[])
,ByteBuffer.put(byte[])
-
readI2CBlockDataByteArray
Utility method that wrapsreadI2CBlockData(int, byte[])
to read the specified number of bytes and return as a new byte array.- Parameters:
register
- the register to read fromlength
- the number of bytes to read- Returns:
- the data read
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readI2CBlockData(int, byte[])
-
readI2CBlockDataByteBuffer
Utility method that wrapsreadI2CBlockData(int, byte[])
to read the specified number of bytes and return as aByteBuffer
using thebyte order
specified in the device constructor.- Parameters:
register
- the register to read fromlength
- the number of bytes to read- Returns:
- the data read
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readI2CBlockData(int, byte[])
,ByteBuffer.wrap(byte[])
-
readShort
Utility method that invokes eitherreadWordData(int)
orreadWordSwapped(int)
to read a signed short value from the requested register in thebyte order
specified in the constructor.- Parameters:
register
- register to read from- Returns:
- the signed short value read
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readWordData(int)
,readWordSwapped(int)
-
readUShort
Utility method that wrapsreadShort(int)
to read an unsigned short value from the requested register using thebyte order
specified in the constructor.- Parameters:
register
- register to read from- Returns:
- the unsigned short value read
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readShort(int)
-
readInt
Utility method that wrapsreadI2CBlockDataByteBuffer(int, int)
to read a signed int value from the requested register using thebyte order
specified in the constructor.- Parameters:
register
- register to read from- Returns:
- the signed int value read
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readI2CBlockDataByteBuffer(int, int)
-
readUInt
Utility method that wrapsreadInt(int)
to read an unsigned int value from the requested register using thebyte order
specified in the constructor.- Parameters:
register
- register to read from- Returns:
- the unsigned int value read
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readInt(int)
-
readUInt
Utility method that wrapsreadI2CBlockDataByteArray(int, int)
to read an unsigned int value on the specified length from the requested register using thebyte order
specified in the constructor.- Parameters:
register
- register to read fromnumBytes
- number of bytes to read (1..4)- Returns:
- the unsigned int value read
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readI2CBlockDataByteArray(int, int)
-
readBytes
Utility method that wrapsreadBytes(byte[])
to read the specified number of bytes.- Parameters:
length
- the number of bytes to read- Returns:
- the bytes read from the device
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readBytes(byte[])
-
readBit
Utility method that wrapsreadByteData(int)
to check if the specified bit number is set.- Parameters:
register
- the register to readbit
- the bit number to check- Returns:
- true if the specified bit number is set
- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
BitManipulation.isBitSet(byte, int)
,readByteData(int)
-
writeBit
Utility method that wrapsreadByteData(int)
andwriteByteData(int, byte)
to update the specified bit number- Parameters:
register
- the register to updatebit
- the bit number to setvalue
- the value to set the bit to- Throws:
RuntimeIOException
- if an I/O error occurs- See Also:
readByteData(int)
,BitManipulation.setBitValue(byte, boolean, int)
-