Package com.diozero.api

Class I2CDevice

    • Method Detail

      • 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()

      • getByteOrder

        public ByteOrder getByteOrder()

      • 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 up to 32 bytes from a device, using the specified register address.

        I2C commands: 
         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 up to a maximum of 32 bytes
        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 up to 32 bytes of data to a device, to the specified register address. 

         S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P

        Note that command lengths of 0, 2, or more bytes are supported as they are indistinguishable from data.

        Specified by:
        writeI2CBlockData in interface I2CSMBusInterface
        Parameters:
        register - the register to write to
        data - values to write with a maximum length of 32 bytes
        Throws:
        RuntimeIOException - if an I/O error occurs

      • readBytes

        public int readBytes​(byte[] buffer)
              throws RuntimeIOException
        Read the specified number of bytes from the device without the 32 byte limit imposed by SMBus. I2C commands: 
         S Addr Rd [A] [Data] [A] [Data] [A] ... [A] [Data] NA P
        Specified by:
        readBytes in interface I2CDeviceInterface
        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
        Write the specified byte array to the device without the 32 byte limit imposed by SMBus. I2C commands: 
         S Addr Wr [A] [Data] [A] [Data] [A] ... [A] [Data] NA P
        Specified by:
        writeBytes in interface I2CDeviceInterface
        Parameters:
        data - the data to write
        Throws:
        RuntimeIOException - if an I/O error occurs

      • readWrite

        public void readWrite​(I2CDeviceInterface.I2CMessage[] messages,
                      byte[] buffer)

        Low-level I2C interface to execute a series of commands in a single I2C transaction. Allows multiple read and write commands to be executed at the same time as well as control over the I2C flags that are sent with each command, e.g. NO-START.

        The data buffer MUST align with the commands that are being issued. For example, to read 2 bytes from register 0x40 and then write 3 bytes to register 0x50, the message array and buffer would be as follows: 

         Message array and corresponding data buffer:
 Idx  Flags     Len  Buffer
 [0]  I2C_M_WR  1    [0] 0x40 - the register address to read from
 [1]  I2C_M_RD  2    [1..2] leave blank, will be overridden with the data read from the device
 [2]  I2C_M_WR  1    [3] 0x50 - the register address to write to
 [3]  I2C_M_WR  3    [4..6] the 3 bytes of data to write
        Specified by:
        readWrite in interface I2CDeviceInterface
        Parameters:
        messages - array of commands to send to the device
        buffer - the data buffer that is associated with the commands

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

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

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