Package com.diozero.api

Class I2CDevice

java.lang.Object
com.diozero.api.I2CDevice
All Implemented Interfaces:
DeviceInterface, I2CDeviceInterface, I2CSMBusInterface, AutoCloseable
public class I2CDevice
extends Object
implements I2CDeviceInterface
Utility class for interfacing with to I2C devices.
See Also:
I2C Bus Specification

  • Constructor Details

  • Method Details

    • builder

      public static I2CDevice.Builder builder​(int address)
      Builder class for I2C devices
      Parameters:
      address - the I2C device address
      Returns:
      I2C device builder

    • getController

      public int getController()

    • getAddress

      public int getAddress()

    • getAddressSize

      public I2CConstants.AddressSize getAddressSize()

    • getByteOrder

      public ByteOrder getByteOrder()

    • close

      public void close() throws RuntimeIOException
      Close this device
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface DeviceInterface
      Throws:
      RuntimeIOException

    • probe

      public boolean probe​(I2CDevice.ProbeMode mode)
      Probe this I2C device to see if it is connected
      Specified by:
      probe in interface I2CSMBusInterface
      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 interface I2CSMBusInterface
      Parameters:
      bit - The bit to write

    • readByte

      public byte readByte() throws RuntimeIOException

      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 interface I2CSMBusInterface
      Returns:
      The byte data read (note caller needs to handle conversion to unsigned)
      Throws:
      RuntimeIOException - if an I/O error occurs

    • writeByte

      public void writeByte​(byte data) throws RuntimeIOException

      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 interface I2CSMBusInterface
      Parameters:
      data - value to write
      Throws:
      RuntimeIOException - if an I/O error occurs

    • readByteData

      public byte readByteData​(int register) throws RuntimeIOException

      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 interface I2CSMBusInterface
      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

      public void writeByteData​(int register, byte value) throws RuntimeIOException

      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 interface I2CSMBusInterface
      Parameters:
      register - the register to write to
      value - value to write
      Throws:
      RuntimeIOException - if an I/O error occurs

    • readWordData

      public short readWordData​(int register) throws RuntimeIOException

      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 is Little Endian as per the SMBus specification, regardless of the byte order specified in the constructor
      Specified by:
      readWordData in interface I2CSMBusInterface
      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

      public void writeWordData​(int register, short value) throws RuntimeIOException

      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 the byte order for the input value is Little Endian as per the SMBus specification, regardless of the byte order specified in the constructor
      Specified by:
      writeWordData in interface I2CSMBusInterface
      Parameters:
      register - the register to write to
      value - value to write in Little Endian byte order
      Throws:
      RuntimeIOException - if an I/O error occurs

    • readWordSwapped

      public short readWordSwapped​(int register) throws RuntimeIOException

      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 is Big Endian, regardless of the byte order specified in the constructor
      Specified by:
      readWordSwapped in interface I2CSMBusInterface
      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

      public void writeWordSwapped​(int register, short value) throws RuntimeIOException

      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 the byte order for the input value is Big Endian, regardless of the byte order specified in the constructor
      Specified by:
      writeWordSwapped in interface I2CSMBusInterface
      Parameters:
      register - the register to write to
      value - value to write in Big 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 interface I2CSMBusInterface
      Parameters:
      register - the register to write to / read from
      data - 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 interface I2CSMBusInterface
      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 interface I2CSMBusInterface
      Parameters:
      register - the register to write to
      data - 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 interface I2CSMBusInterface
      Parameters:
      register - the register to write to and read from
      txData - 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 interface I2CSMBusInterface
      Parameters:
      register - the register to read from
      buffer - 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

      public void writeI2CBlockData​(int register, byte... data) throws RuntimeIOException

      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 interface I2CSMBusInterface
      Parameters:
      register - the register to write to
      data - values to write
      Throws:
      RuntimeIOException - if an I/O error occurs

    • readBytes

      public int readBytes​(byte[] buffer) throws RuntimeIOException
      Diozero SMBus extension to read the specified number of bytes from the device
      Specified by:
      readBytes in interface I2CSMBusInterface
      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

      public void writeBytes​(byte... data) throws RuntimeIOException
      Diozero SMBus extension to write the specified byte array to the device
      Specified by:
      writeBytes in interface I2CSMBusInterface
      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 interface I2CDeviceInterface

    • readWrite

      public void readWrite​(I2CDeviceInterface.I2CMessage[] messages, byte[] buffer)
      Specified by:
      readWrite in interface I2CDeviceInterface

    • writeByteData

      public void writeByteData​(int register, int data) throws RuntimeIOException
      Utility method that simply casts the int data parameter to byte and calls writeByteData(int, byte)
      Parameters:
      register - the register to write to
      data - value to write
      Throws:
      RuntimeIOException - if an I/O error occurs
      See Also:
      writeByteData(int, byte)

    • readUByte

      public short readUByte​(int register) throws RuntimeIOException
      Utility method that simply converts the response from readByteData(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

      public ByteBuffer readBytesAsByteBuffer​(int length) throws RuntimeIOException
      Utility method that wraps the response from readBytes(int) in a ByteBuffer that is configured to use the byte 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

      public void writeBytes​(ByteBuffer buffer) throws RuntimeIOException
      Utility method that wraps writeBytes(byte[]) to write the available bytes in the specified ByteBuffer. The byte order of data in the ByteBuffer is unchanged.
      Parameters:
      buffer - the ByteBuffer containing the data to write
      Throws:
      RuntimeIOException - if an I/O error occurs
      See Also:
      writeBytes(byte[]), ByteBuffer.put(byte[])

    • readI2CBlockDataByteArray

      public byte[] readI2CBlockDataByteArray​(int register, int length) throws RuntimeIOException
      Utility method that wraps readI2CBlockData(int, byte[]) to read the specified number of bytes and return as a new byte array.
      Parameters:
      register - the register to read from
      length - the number of bytes to read
      Returns:
      the data read
      Throws:
      RuntimeIOException - if an I/O error occurs
      See Also:
      readI2CBlockData(int, byte[])

    • readI2CBlockDataByteBuffer

      public ByteBuffer readI2CBlockDataByteBuffer​(int register, int length) throws RuntimeIOException
      Utility method that wraps readI2CBlockData(int, byte[]) to read the specified number of bytes and return as a ByteBuffer using the byte order specified in the device constructor.
      Parameters:
      register - the register to read from
      length - 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

      public short readShort​(int register) throws RuntimeIOException
      Utility method that invokes either readWordData(int) or readWordSwapped(int) to read a signed short value from the requested register in the byte 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

      public int readUShort​(int register) throws RuntimeIOException
      Utility method that wraps readShort(int) to read an unsigned short value from the requested register using the byte 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

      public int readInt​(int register) throws RuntimeIOException
      Utility method that wraps readI2CBlockDataByteBuffer(int, int) to read a signed int value from the requested register using the byte 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

      public long readUInt​(int register) throws RuntimeIOException
      Utility method that wraps readInt(int) to read an unsigned int value from the requested register using the byte 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

      public long readUInt​(int register, int numBytes) throws RuntimeIOException
      Utility method that wraps readI2CBlockDataByteArray(int, int) to read an unsigned int value on the specified length from the requested register using the byte order specified in the constructor.
      Parameters:
      register - register to read from
      numBytes - 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

      public byte[] readBytes​(int length) throws RuntimeIOException
      Utility method that wraps readBytes(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

      public boolean readBit​(int register, int bit) throws RuntimeIOException
      Utility method that wraps readByteData(int) to check if the specified bit number is set.
      Parameters:
      register - the register to read
      bit - 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

      public void writeBit​(int register, int bit, boolean value) throws RuntimeIOException
      Utility method that wraps readByteData(int) and writeByteData(int, byte) to update the specified bit number
      Parameters:
      register - the register to update
      bit - the bit number to set
      value - the value to set the bit to
      Throws:
      RuntimeIOException - if an I/O error occurs
      See Also:
      readByteData(int), BitManipulation.setBitValue(byte, boolean, int)