Package edu.wpi.first.wpilibj

Class I2C

java.lang.Object
edu.wpi.first.wpilibj.I2C
All Implemented Interfaces:
AutoCloseable
public class I2C
extends Object
implements AutoCloseable
I2C bus interface class.

This class is intended to be used by sensor (and other I2C device) drivers. It probably should not be used directly.

The Onboard I2C port is subject to system lockups. See WPILib Known Issues page for details.

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  I2C.Port
    I2C connection ports.

  • Constructor Summary

    Constructors 
    Constructor Description
    I2C​(I2C.Port port, int deviceAddress)
    Constructor.

  • Method Summary

    Modifier and Type Method Description
    boolean addressOnly()
    Attempt to address a device on the I2C bus.
    void close()  
    int getDeviceAddress()
    Returns I2C device address.
    int getPort()
    Returns I2C port.
    boolean read​(int registerAddress, int count, byte[] buffer)
    Execute a read transaction with the device.
    boolean read​(int registerAddress, int count, ByteBuffer buffer)
    Execute a read transaction with the device.
    boolean readOnly​(byte[] buffer, int count)
    Execute a read only transaction with the device.
    boolean readOnly​(ByteBuffer buffer, int count)
    Execute a read only transaction with the device.
    boolean transaction​(byte[] dataToSend, int sendSize, byte[] dataReceived, int receiveSize)
    Generic transaction.
    boolean transaction​(ByteBuffer dataToSend, int sendSize, ByteBuffer dataReceived, int receiveSize)
    Generic transaction.
    boolean verifySensor​(int registerAddress, int count, byte[] expected)
    Verify that a device's registers contain expected values.
    boolean write​(int registerAddress, int data)
    Execute a write transaction with the device.
    boolean writeBulk​(byte[] data)
    Execute a write transaction with the device.
    boolean writeBulk​(byte[] data, int size)
    Execute a write transaction with the device.
    boolean writeBulk​(ByteBuffer data, int size)
    Execute a write transaction with the device.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • I2C

      public I2C​(I2C.Port port, int deviceAddress)
      Constructor.
      Parameters:
      port - The I2C port the device is connected to.
      deviceAddress - The address of the device on the I2C bus.

  • Method Details

    • getPort

      public int getPort()
      Returns I2C port.
      Returns:
      I2C port.

    • getDeviceAddress

      public int getDeviceAddress()
      Returns I2C device address.
      Returns:
      I2C device address.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • transaction

      public boolean transaction​(byte[] dataToSend, int sendSize, byte[] dataReceived, int receiveSize)
      Generic transaction.

      This is a lower-level interface to the I2C hardware giving you more control over each transaction. If you intend to write multiple bytes in the same transaction and do not plan to receive anything back, use writeBulk() instead. Calling this with a receiveSize of 0 will result in an error.

      Parameters:
      dataToSend - Buffer of data to send as part of the transaction.
      sendSize - Number of bytes to send as part of the transaction.
      dataReceived - Buffer to read data into.
      receiveSize - Number of bytes to read from the device.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • transaction

      public boolean transaction​(ByteBuffer dataToSend, int sendSize, ByteBuffer dataReceived, int receiveSize)
      Generic transaction.

      This is a lower-level interface to the I2C hardware giving you more control over each transaction.

      Parameters:
      dataToSend - Buffer of data to send as part of the transaction.
      sendSize - Number of bytes to send as part of the transaction.
      dataReceived - Buffer to read data into.
      receiveSize - Number of bytes to read from the device.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • addressOnly

      public boolean addressOnly()
      Attempt to address a device on the I2C bus.

      This allows you to figure out if there is a device on the I2C bus that responds to the address specified in the constructor.

      Returns:
      Transfer Aborted... false for success, true for aborted.

    • write

      public boolean write​(int registerAddress, int data)
      Execute a write transaction with the device.

      Write a single byte to a register on a device and wait until the transaction is complete.

      Parameters:
      registerAddress - The address of the register on the device to be written.
      data - The byte to write to the register on the device.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • writeBulk

      public boolean writeBulk​(byte[] data)
      Execute a write transaction with the device.

      Write multiple bytes to a register on a device and wait until the transaction is complete.

      Parameters:
      data - The data to write to the device.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • writeBulk

      public boolean writeBulk​(byte[] data, int size)
      Execute a write transaction with the device.

      Write multiple bytes to a register on a device and wait until the transaction is complete.

      Parameters:
      data - The data to write to the device.
      size - The number of data bytes to write.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • writeBulk

      public boolean writeBulk​(ByteBuffer data, int size)
      Execute a write transaction with the device.

      Write multiple bytes to a register on a device and wait until the transaction is complete.

      Parameters:
      data - The data to write to the device.
      size - The number of data bytes to write.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • read

      public boolean read​(int registerAddress, int count, byte[] buffer)
      Execute a read transaction with the device.

      Read bytes from a device. Most I2C devices will auto-increment the register pointer internally allowing you to read consecutive registers on a device in a single transaction.

      Parameters:
      registerAddress - The register to read first in the transaction.
      count - The number of bytes to read in the transaction.
      buffer - A pointer to the array of bytes to store the data read from the device.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • read

      public boolean read​(int registerAddress, int count, ByteBuffer buffer)
      Execute a read transaction with the device.

      Read bytes from a device. Most I2C devices will auto-increment the register pointer internally allowing you to read consecutive registers on a device in a single transaction.

      Parameters:
      registerAddress - The register to read first in the transaction.
      count - The number of bytes to read in the transaction.
      buffer - A buffer to store the data read from the device.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • readOnly

      public boolean readOnly​(byte[] buffer, int count)
      Execute a read only transaction with the device.

      Read bytes from a device. This method does not write any data to prompt the device.

      Parameters:
      buffer - A pointer to the array of bytes to store the data read from the device.
      count - The number of bytes to read in the transaction.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • readOnly

      public boolean readOnly​(ByteBuffer buffer, int count)
      Execute a read only transaction with the device.

      Read bytes from a device. This method does not write any data to prompt the device.

      Parameters:
      buffer - A pointer to the array of bytes to store the data read from the device.
      count - The number of bytes to read in the transaction.
      Returns:
      Transfer Aborted... false for success, true for aborted.

    • verifySensor

      public boolean verifySensor​(int registerAddress, int count, byte[] expected)
      Verify that a device's registers contain expected values.

      Most devices will have a set of registers that contain a known value that can be used to identify them. This allows an I2C device driver to easily verify that the device contains the expected value.

      Parameters:
      registerAddress - The base register to start reading from the device.
      count - The size of the field to be verified.
      expected - A buffer containing the values expected from the device.
      Returns:
      true if the sensor was verified to be connected
      Pre-Condition
      The device must support and be configured to use register auto-increment.