com.qualcomm.robotcore.hardware

## Interface I2cDevice

- All Superinterfaces:
    HardwareDevice, I2cControllerPortDevice
  All Known Implementing Classes:
    I2cDeviceImpl

      public interface I2cDevice
      extends I2cControllerPortDevice, HardwareDevice

  The `I2cDevice` interface abstracts the engine used to interact on with a specific I2c device on a port of an `I2cController`.
  See Also:
    `I2cDeviceSynch`

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface com.qualcomm.robotcore.hardware.HardwareDevice

      `HardwareDevice.Manufacturer`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearI2cPortActionFlag()` Clears the flag that `setI2cPortActionFlag()` sets
    `void` | `copyBufferIntoWriteBuffer(byte[] buffer)` Atomically copies the provided buffer into the user portion of the write cache, beginning immediately following the four-byte header.
    `void` | `deregisterForPortReadyBeginEndCallback()` Unregisters any portIsReady() begin / end notifications object if any is present.
    `void` | `deregisterForPortReadyCallback()` Unregisters any callback currently registered.
    `void` | `enableI2cReadMode(I2cAddr i2cAddr, int register, int count)` Enable read mode for this I2C device.
    `void` | `enableI2cWriteMode(I2cAddr i2cAddr, int register, int count)` Enable write mode for this I2C device.
    `int` | `getCallbackCount()` Returns the number of callbacks ever experienced by this I2cDevice instance, whether or not they were ever seen by a registered callback.
    `I2cController` | `getController()` Deprecated. Use of `I2cControllerPortDevice.getI2cController()` is suggested instead
    `byte[]` | `getCopyOfReadBuffer()` Atomically returns a copy of that portion of the read-cache which does not include the initial four-byte header section: that contains the read payload most recently read from the controller.
    `byte[]` | `getCopyOfWriteBuffer()` Atomically returns a copy that portion of the write-cache which does not include the initial four-byte header section.
    `I2cController.I2cPortReadyCallback` | `getI2cPortReadyCallback()` Returns the callback previously registered with `registerForI2cPortReadyCallback(com.qualcomm.robotcore.hardware.I2cController.I2cPortReadyCallback)`, or null if no callback is currently registered.
    `byte[]` | `getI2cReadCache()` Returns access to the read-cache into which data from the controller is read.
    `java.util.concurrent.locks.Lock` | `getI2cReadCacheLock()` Returns access to the lock controlling the read-cache.
    `TimeWindow` | `getI2cReadCacheTimeWindow()` Returns the time window object into which time stamps are written when the read cache is updated
    `byte[]` | `getI2cWriteCache()` Returns access to the write-cache from which data is written to the controller.
    `java.util.concurrent.locks.Lock` | `getI2cWriteCacheLock()` Returns access to the lock controlling the write-cache.
    `int` | `getMaxI2cWriteLatency()` Returns the maximum interval, in milliseconds, from when the controller receives an I2c write transmission over USB to when that write is actually issued to the I2c device.
    `I2cController.I2cPortReadyBeginEndNotifications` | `getPortReadyBeginEndCallback()` Returns the object, if any, currently registered for portIsReady() begin / end notifications
    `boolean` | `isArmed()` Returns whether, as of this instant, this I2cDevice is alive and operational in its normally expected mode; that is, whether it is currently in communication with its underlying hardware or whether it is in some other state
    `boolean` | `isI2cPortActionFlagSet()` Deprecated. this method returns a value that is rarely that which is expected
    `boolean` | `isI2cPortInReadMode()` Queries whether or not the controller has reported that it is in read mode.
    `boolean` | `isI2cPortInWriteMode()` Queries whether or not the controller has reported that it is in write mode.
    `boolean` | `isI2cPortReady()` Returns whether the I2cDevice instance has experienced a callback since the last issuance of work to the controller.
    `void` | `readI2cCacheFromController()` Enqueue a request to the controller to read the range of data from the HW device that was previously indicated in `enableI2cReadMode(I2cAddr, int, int)` and subsequently written to the controller.
    `void` | `readI2cCacheFromModule()` Deprecated. Use of `readI2cCacheFromController()` is suggested instead
    `void` | `registerForI2cPortReadyCallback(I2cController.I2cPortReadyCallback callback)` Registers an object to get `portIsReady()` callbacks at regular intervals from the `I2cDevice`.
    `void` | `registerForPortReadyBeginEndCallback(I2cController.I2cPortReadyBeginEndNotifications callback)` Register for notifications as to when `portIsReady()` begin and end.
    `void` | `setI2cPortActionFlag()` Set the flag in the write cache that indicates that when the write cache is next transferred to the controller an i2c transaction should take place.
    `void` | `writeI2cCacheToController()` Enqueue a request to the controller to write the current contents of the write cache to the HW device.
    `void` | `writeI2cCacheToModule()` Deprecated. Use of `writeI2cCacheToController()` is suggested instead
    `void` | `writeI2cPortFlagOnlyToController()` Enqueue a request to the controller to reissue the previous i2c transaction to the HW device.
    `void` | `writeI2cPortFlagOnlyToModule()` Deprecated. Use of `writeI2cPortFlagOnlyToController()` is suggested instead

    - ### Methods inherited from interface com.qualcomm.robotcore.hardware.I2cControllerPortDevice

      `getI2cController, getPort`

    - ### Methods inherited from interface com.qualcomm.robotcore.hardware.HardwareDevice

      `close, getConnectionInfo, getDeviceName, getManufacturer, getVersion, resetDeviceConfigurationForOpMode`

- - ### Method Detail

    - #### enableI2cReadMode

          void enableI2cReadMode(I2cAddr i2cAddr,
                                 int register,
                                 int count)

      Enable read mode for this I2C device. This simply sets bytes in the header of the write-cache; it does not enqueue or transmit any data.
      Parameters:
        `i2cAddr` - the address of the device on the I2c bus which should be read
        `register` - I2c register number within the device at which to start reading
        `count` - number of bytes to read
      See Also:
        `writeI2cCacheToController()`

    - #### enableI2cWriteMode

          void enableI2cWriteMode(I2cAddr i2cAddr,
                                  int register,
                                  int count)

      Enable write mode for this I2C device. This simply sets bytes in the header of the write-cache; it does not enqueue or transmit any data.
      Parameters:
        `i2cAddr` - the address of the device on the I2c bus which should be written
        `register` - mem address at which to start writing
        `count` - number of bytes to write
      See Also:
        `writeI2cCacheToController()`

    - #### isI2cPortInReadMode

          boolean isI2cPortInReadMode()

      Queries whether or not the controller has reported that it is in read mode.
      Returns:
        whether or not this port is in read mode

    - #### isI2cPortInWriteMode

          boolean isI2cPortInWriteMode()

      Queries whether or not the controller has reported that it is in write mode.
      Returns:
        whether or not this port is in write mode

    - #### readI2cCacheFromController

          void readI2cCacheFromController()

      Enqueue a request to the controller to read the range of data from the HW device that was previously indicated in `enableI2cReadMode(I2cAddr, int, int)` and subsequently written to the controller.

    - #### writeI2cCacheToController

          void writeI2cCacheToController()

      Enqueue a request to the controller to write the current contents of the write cache to the HW device.

    - #### writeI2cPortFlagOnlyToController

          void writeI2cPortFlagOnlyToController()

      Enqueue a request to the controller to reissue the previous i2c transaction to the HW device.

    - #### setI2cPortActionFlag

          void setI2cPortActionFlag()

      Set the flag in the write cache that indicates that when the write cache is next transferred to the controller an i2c transaction should take place. This will be either a read transaction or a write transaction according to whether the `enableI2cReadMode(I2cAddr, int, int)` or `enableI2cWriteMode(I2cAddr, int, int)` has most recently been called.
      See Also:
        `clearI2cPortActionFlag()`

    - #### isI2cPortActionFlagSet

          @Deprecated
          boolean isI2cPortActionFlagSet()

      Deprecated. this method returns a value that is rarely that which is expected
      Returns whether the action flag is set in the read cache. This is rarely what is actually desired by the `I2cDevice` client; it's use generally should be avoided.
      Returns:
        the value of the action flag in the read cache.

    - #### clearI2cPortActionFlag

          void clearI2cPortActionFlag()

      Clears the flag that `setI2cPortActionFlag()` sets
      See Also:
        `setI2cPortActionFlag()`

    - #### getI2cReadCache

          byte[] getI2cReadCache()

      Returns access to the read-cache into which data from the controller is read. The returned byte array may be retained for repeated use; `getI2cReadCache()` need not be repeatedly called. The lock returned by `getI2cReadCacheLock()` must be held whenever the data in the returned byte array is accessed. Note that the returned byte array contains an initial header section, four bytes in size, which contains the information manipulated by `enableI2cReadMode(I2cAddr, int, int)` and `enableI2cWriteMode(I2cAddr, int, int)`.
      Returns:
        the read-cache of this I2cDevice
      See Also:
        `getI2cReadCacheLock()`, `getCopyOfReadBuffer()`

    - #### getI2cReadCacheTimeWindow

          TimeWindow getI2cReadCacheTimeWindow()

      Returns the time window object into which time stamps are written when the read cache is updated
      Returns:
        the time window object into which time stamps are written when the read cache is updated
      See Also:
        `getI2cReadCache()`

    - #### getI2cReadCacheLock

          java.util.concurrent.locks.Lock getI2cReadCacheLock()

      Returns access to the lock controlling the read-cache. This lock must be held a while the data accessible from `getI2cReadCache()` is accessed.
      Returns:
        the lock gating access to the read cache

    - #### getI2cWriteCache

          byte[] getI2cWriteCache()

      Returns access to the write-cache from which data is written to the controller. The returned byte array may be retained for repeated use; `getI2cWriteCache()` need not be repeatedly called. The lock returned by `getI2cWriteCacheLock()` must be held whenever the data in the returned byte array is accessed or written. Note that the returned byte array contains an inital header section, four bytes in size, which contains the information manipulated by `enableI2cReadMode(I2cAddr, int, int)` and `enableI2cWriteMode(I2cAddr, int, int)`.
      Returns:
        the write-cache of this I2cDevice
      See Also:
        `getI2cWriteCacheLock()`, `getCopyOfWriteBuffer()`

    - #### getI2cWriteCacheLock

          java.util.concurrent.locks.Lock getI2cWriteCacheLock()

      Returns access to the lock controlling the write-cache. This lock must be held a while the data accessible from `getI2cWriteCache()` is accessed
      Returns:
        the lock gating access to the write cache

    - #### getCopyOfReadBuffer

          byte[] getCopyOfReadBuffer()

      Atomically returns a copy of that portion of the read-cache which does not include the initial four-byte header section: that contains the read payload most recently read from the controller. The read-cache lock need not be held while executing this method.
      Returns:
        a copy of the read payload
      See Also:
        `getI2cReadCache()`

    - #### getCopyOfWriteBuffer

          byte[] getCopyOfWriteBuffer()

      Atomically returns a copy that portion of the write-cache which does not include the initial four-byte header section. The write-cache lock need not be held to execute this method.
      Returns:
        a copy of the user-data portion of the write-cache
      See Also:
        `getI2cWriteCache()`

    - #### copyBufferIntoWriteBuffer

          void copyBufferIntoWriteBuffer(byte[] buffer)

      Atomically copies the provided buffer into the user portion of the write cache, beginning immediately following the four-byte header. The write-cache lock need not be held to execute this method.
      Parameters:
        `buffer` - the data to copy into the write cache
      See Also:
        `getI2cWriteCache()`

    - #### getMaxI2cWriteLatency

          int getMaxI2cWriteLatency()

      Returns the maximum interval, in milliseconds, from when the controller receives an I2c write transmission over USB to when that write is actually issued to the I2c device.
      Returns:
        the maximum interval, in milliseconds, from when the controller receives an I2c write transmission over USB to when that write is actually issued to the I2c device.

    - #### registerForI2cPortReadyCallback

          void registerForI2cPortReadyCallback(I2cController.I2cPortReadyCallback callback)

      Registers an object to get `portIsReady()` callbacks at regular intervals from the `I2cDevice`. Only one object may be registered for a callback with an `I2cDevice` at any given time.
      Parameters:
        `callback` -
      See Also:
        `getI2cPortReadyCallback()`, `deregisterForPortReadyCallback()`

    - #### getI2cPortReadyCallback

          I2cController.I2cPortReadyCallback getI2cPortReadyCallback()

      Returns the callback previously registered with `registerForI2cPortReadyCallback(com.qualcomm.robotcore.hardware.I2cController.I2cPortReadyCallback)`, or null if no callback is currently registered.
      Returns:
        the currently registered callback

    - #### deregisterForPortReadyCallback

          void deregisterForPortReadyCallback()

      Unregisters any callback currently registered.
      See Also:
        `registerForI2cPortReadyCallback(I2cController.I2cPortReadyCallback)`

    - #### getCallbackCount

          int getCallbackCount()

      Returns the number of callbacks ever experienced by this I2cDevice instance, whether or not they were ever seen by a registered callback. This method is mostly useful for debugging and gathering of statistics.
      Returns:
        the number of port-is-ready callbacks ever experienced by this `I2cDevice` instance

    - #### isI2cPortReady

          boolean isI2cPortReady()

      Returns whether the I2cDevice instance has experienced a callback since the last issuance of work to the controller. It is difficult to use this method effectively; in most circumstances, one is better off registering a `portIsReady()` callback and putting your processing logic there. Inside the callback, the port is, by definition, ready. Alternately, consider using the `I2cDeviceSynch` interface instead.
      Returns:
        whether the port is ready for new work
      See Also:
        `I2cDeviceSynch`, `registerForI2cPortReadyCallback(I2cController.I2cPortReadyCallback)`

    - #### registerForPortReadyBeginEndCallback

          void registerForPortReadyBeginEndCallback(I2cController.I2cPortReadyBeginEndNotifications callback)

      Register for notifications as to when `portIsReady()` begin and end. Only one object may be registered for such notifications with an I2cDevice at any given time.
      Parameters:
        `callback` -
      See Also:
        `getPortReadyBeginEndCallback()`, `deregisterForPortReadyBeginEndCallback()`

    - #### getPortReadyBeginEndCallback

          I2cController.I2cPortReadyBeginEndNotifications getPortReadyBeginEndCallback()

      Returns the object, if any, currently registered for portIsReady() begin / end notifications
      Returns:
        the currently registered notification receiver, or null if none exists
      See Also:
        `registerForPortReadyBeginEndCallback(I2cController.I2cPortReadyBeginEndNotifications)`

    - #### deregisterForPortReadyBeginEndCallback

          void deregisterForPortReadyBeginEndCallback()

      Unregisters any portIsReady() begin / end notifications object if any is present.
      See Also:
        `registerForPortReadyBeginEndCallback(I2cController.I2cPortReadyBeginEndNotifications)`

    - #### isArmed

          boolean isArmed()

      Returns whether, as of this instant, this I2cDevice is alive and operational in its normally expected mode; that is, whether it is currently in communication with its underlying hardware or whether it is in some other state
      Returns:
        the arming status of this I2cDevice

    - #### getController

          @Deprecated
          I2cController getController()

      Deprecated. Use of `I2cControllerPortDevice.getI2cController()` is suggested instead

    - #### readI2cCacheFromModule

          @Deprecated
          void readI2cCacheFromModule()

      Deprecated. Use of `readI2cCacheFromController()` is suggested instead

    - #### writeI2cCacheToModule

          @Deprecated
          void writeI2cCacheToModule()

      Deprecated. Use of `writeI2cCacheToController()` is suggested instead

    - #### writeI2cPortFlagOnlyToModule

          @Deprecated
          void writeI2cPortFlagOnlyToModule()

      Deprecated. Use of `writeI2cPortFlagOnlyToController()` is suggested instead