Package io.helins.linux.i2c

Class I2CBus

  • All Implemented Interfaces:
    AutoCloseable
    public class I2CBus
extends Object
implements AutoCloseable
    Class representing an I2C bus.

    It provides 3 sets of operations for doing IO :

    • Directly reading and writing by using read and write.
    • Doing transactions (ie. uninterrupted reads and writes)
    • Using SMBUS operations as defined in the standard by using the interface via the smbus field.

    SMBUS operations are a subset of what I2C can achieve but propose common interactions. However, getFunctionnalities should be used in order to understand what operations the underlying driver support.

    I2C is a standard but your master device and the slaves devices it talks to probably do not support everything properly. For instance, as is, the Raspberry Pi only supports a few SMBUS operations and do not support transactions involving more than one message at a time (which defeats the purpose of having them in the first place). Furthermore, talking to an Arduino will result in timing issues if it is too slow to answer. Communication between those two is very much possible but requires more preparation and testing. This is an example of how things are not always that simple.

    In this API, `command` is just another word for what is sometimes called `register`. Essentially, it means that before reading or writing bytes, the master writes a byte specifying a command, something to do with the following byte(s). If an SMBUS functionality is not available, this can often be emulated by explicitly sending the command byte and then reading or writing as needed.

    See Also:
    SMBUS operations

    • Field Summary

      Fields 
      Modifier and Type Field Description
      SMBus smbus
      For executing SMBus operations using this I2C bus.

    • Constructor Summary

      Constructors 
      Constructor Description
      I2CBus​(int busNumber)
      Opens an I2C bus by number, `/dev/i2c-$busNumber`.
      I2CBus​(String path)
      Opens an I2C bus on the given path.

    • Field Detail

      • smbus

        public final SMBus smbus
        For executing SMBus operations using this I2C bus.

    • Constructor Detail

      • I2CBus

        public I2CBus​(int busNumber)
       throws IOException
        Opens an I2C bus by number, `/dev/i2c-$busNumber`.
        Parameters:
        busNumber - Number of the bus.
        Throws:
        IOException - When an unplanned error occured.

      • I2CBus

        public I2CBus​(String path)
       throws IOException
        Opens an I2C bus on the given path.
        Parameters:
        path - Path to the bus such as `/dev/i2c-1`.
        Throws:
        FileNotFoundException - When the bus is not found or the user does not have permissions.
        IOException - When an unplanned error occured.

    • Method Detail

      • doTransaction

        public void doTransaction​(I2CTransaction transaction)
                   throws IOException
        Do an uninterrupted transaction of several messages.

        Not all devices support this feature and some only support one message at a time which is not very interesting.

        Parameters:
        transaction - Transaction that will be carried out.
        Throws:
        IllegalStateException - When the I2C bus has been closed.
        IOException - When the bus is not a proper I2C bus or an unplanned error occured.

      • selectSlave

        public void selectSlave​(int address,
                        boolean force,
                        boolean isTenBit)
                 throws IOException
        Selects an available slave device.

        This needs to be called only once if several IO operations are performed on the same slave and has no effect on transactions.

        Parameters:
        address - address of the needed slave.
        force - Should the slave be selected even if it is already used somewhere else ?
        isTenBit - Is the given address in 10-bit resolution ?
        Throws:
        IllegalStateException - When the I2C bus has been closed.
        IOException - When the bus is not a proper I2C bus or an unplanned error occured.

      • setRetries

        public void setRetries​(int nRetries)
                throws IOException
        Sets the number of time a slave should be polled when not acknowledging.

        Does not always have an effect depending on the underlying driver.

        Parameters:
        nRetries - Number of retries.
        Throws:
        IllegalStateException - When the I2C bus has been closed.
        IOException - When the bus is not a proper I2C bus or an unplanned error occured.

      • setTimeout

        public void setTimeout​(int milliseconds)
                throws IOException
        Sets the timeout in milliseconds.

        Does not always have an effect depending on the underlying driver.

        Parameters:
        milliseconds - Timeout in milliseconds.
        Throws:
        IllegalStateException - When the I2C bus has been closed.
        IOException - When the bus is not a proper I2C bus or an unplanned error occured.

      • read

        public void read​(I2CBuffer buffer)
          throws IOException
        Directly reads bytes from the slave device (length is specified by the buffer).
        Parameters:
        buffer - Buffer the answer will be written to.
        Throws:
        IllegalStateException - When the I2C bus has been closed.
        IOException - When the bus is not a proper I2C bus or an unplanned error occured.
        See Also:
        read( I2CBuffer, int )

      • read

        public void read​(I2CBuffer buffer,
                 int length)
          throws IOException
        Directly reads length bytes from the slave device.
        Parameters:
        buffer - Buffer the answer will be written to.
        length - Number of bytes requested.
        Throws:
        IllegalStateException - When the I2C bus has been closed.
        IOException - When the bus is not a proper I2C bus or an unplanned error occured.

      • write

        public void write​(I2CBuffer buffer,
                  int length)
           throws IOException
        Directly writes length bytes to the slave device.
        Parameters:
        buffer - Buffer to write.
        length - Number of bytes.
        Throws:
        IllegalStateException - When the I2C bus has been closed.
        IOException - When the bus is not a proper I2C bus or an unplanned error occured.