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

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