public final class I2cDeviceSynchImpl extends java.lang.Object implements I2cDeviceSynch, Engagable
I2cDeviceSynchImpl is a utility class that makes it easy to read or write data to
an instance of I2cDevice. Its functionality is exposed through the I2cDeviceSynch
interface. Please see that interface, and the I2cDeviceSynchImpl constructor here, for
further information.| Modifier and Type | Class and Description |
|---|---|
protected class |
I2cDeviceSynchImpl.Callback |
protected static class |
I2cDeviceSynchImpl.CONTROLLER_PORT_MODE |
protected static class |
I2cDeviceSynchImpl.READ_CACHE_STATUS |
protected static class |
I2cDeviceSynchImpl.WRITE_CACHE_STATUS |
I2cDeviceSynch.HeartbeatAction, I2cDeviceSynch.ReadMode, I2cDeviceSynch.ReadWindow, I2cDeviceSynch.TimestampedData| Modifier and Type | Field and Description |
|---|---|
protected I2cDeviceSynchImpl.Callback |
callback |
protected java.lang.Object |
callbackLock |
protected java.lang.Object |
concurrentClientLock |
protected I2cController |
controller |
protected I2cDeviceSynchImpl.CONTROLLER_PORT_MODE |
controllerPortMode |
protected int |
cregWrite |
protected static int |
dibCacheOverhead |
protected java.lang.Object |
engagementLock |
protected boolean |
hasReadWindowChanged |
protected I2cDeviceSynch.HeartbeatAction |
heartbeatAction |
protected java.util.concurrent.ExecutorService |
heartbeatExecutor |
protected int |
i2cAddr8Bit |
protected I2cDevice |
i2cDevice |
protected int |
iregWriteFirst |
protected boolean |
isClosing |
protected boolean |
isEngaged |
protected boolean |
isHooked |
protected boolean |
isI2cDeviceOwned |
protected boolean |
isReadWindowSentToControllerInitialized |
protected boolean |
isWriteCoalescingEnabled |
protected boolean |
loggingEnabled |
protected java.lang.String |
loggingTag |
protected static int |
msCallbackLockAbandon |
protected static int |
msCallbackLockWaitQuantum |
protected int |
msHeartbeatInterval |
protected long |
nanoTimeReadCacheValid |
protected byte[] |
readCache |
protected java.util.concurrent.locks.Lock |
readCacheLock |
protected I2cDeviceSynchImpl.READ_CACHE_STATUS |
readCacheStatus |
protected java.util.concurrent.atomic.AtomicInteger |
readerWriterCount |
protected java.util.concurrent.locks.ReadWriteLock |
readerWriterGate |
protected java.util.concurrent.atomic.AtomicInteger |
readerWriterPreventionCount |
protected I2cDeviceSynch.ReadWindow |
readWindow |
protected I2cDeviceSynch.ReadWindow |
readWindowActuallyRead |
protected I2cDeviceSynch.ReadWindow |
readWindowSentToController |
protected RobotUsbModule |
robotUsbModule |
protected ElapsedTime |
timeSinceLastHeartbeat |
protected byte[] |
writeCache |
protected java.util.concurrent.locks.Lock |
writeCacheLock |
protected I2cDeviceSynchImpl.WRITE_CACHE_STATUS |
writeCacheStatus |
| Constructor and Description |
|---|
I2cDeviceSynchImpl(I2cDevice i2cDevice,
int i2cAddr8Bit,
boolean isI2cDeviceOwned)
Instantiate an
I2cDeviceSynchImpl instance on the indicated I2cDevice
using the indicated I2C address. |
| Modifier and Type | Method and Description |
|---|---|
protected void |
acquireReaderLockShared() |
protected void |
adjustHooking() |
void |
close()
Close this device
|
protected static byte[] |
concatenateByteArrays(byte[] left,
byte[] right) |
protected void |
disableReadsAndWrites() |
void |
disengage()
Disengage the object from underlying services it uses to render its function.
|
protected void |
enableReadsAndWrites() |
void |
enableWriteCoalescing(boolean enable)
Enables or disables an optimization wherein writes to two sets of adjacent register
ranges may be coalesced into a single I2c transaction if the second write comes along
while the first is still queued for writing.
|
void |
engage()
(Re)enage the object with its underlying services.
|
void |
ensureReadWindow(I2cDeviceSynch.ReadWindow windowNeeded,
I2cDeviceSynch.ReadWindow windowToSet)
Ensure that the current register window covers the indicated set of registers.
|
protected void |
forceDrainReadersAndWriters() |
java.lang.String |
getConnectionInfo()
Get connection information about this device in a human readable format
|
java.lang.String |
getDeviceName()
Device Name
|
I2cDeviceSynch.HeartbeatAction |
getHeartbeatAction()
Returns the current action, if any, to take upon expiration of the heartbeat interval.
|
int |
getHeartbeatInterval()
Returns the interval within which communication must be received by the I2C device lest
a timeout occur.
|
int |
getI2cAddr()
Returns the I2C address currently being used by this device client
|
I2cDeviceSynch.ReadWindow |
getReadWindow()
Returns the current register window used for reading.
|
int |
getVersion()
Version
|
protected void |
gracefullyDrainReadersAndWriters() |
protected void |
hook() |
boolean |
isArmed()
Returns whether, as of this instant, this device client 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 |
isEngaged()
Returns whether the object is currently in the engaged state.
|
protected boolean |
isOpenForReading() |
protected boolean |
isOpenForWriting() |
boolean |
isWriteCoalescingEnabled()
Answers as to whether write coalescing is currently enabled on this device.
|
protected void |
log(int verbosity,
java.lang.String message) |
protected void |
log(int verbosity,
java.lang.String format,
java.lang.Object... args) |
protected I2cDeviceSynch.TimestampedData |
makeFakeData(int ireg,
int creg) |
protected boolean |
newReadsAndWritesAllowed() |
byte[] |
read(int ireg,
int creg)
Read a contiguous set of device I2C registers.
|
byte |
read8(int ireg)
Read the byte at the indicated register.
|
protected boolean |
readCacheIsValid() |
protected boolean |
readCacheValidityCurrentOrImminent() |
I2cDeviceSynch.TimestampedData |
readTimeStamped(int ireg,
int creg)
Reads and returns a contiguous set of device I2C registers, together with a best-available
timestamp of when the actual I2C read occurred.
|
I2cDeviceSynch.TimestampedData |
readTimeStamped(int ireg,
int creg,
I2cDeviceSynch.ReadWindow readWindowNeeded,
I2cDeviceSynch.ReadWindow readWindowSet)
Advanced: Atomically calls ensureReadWindow() with the last two parameters and then
readTimeStamped() with the first two without the possibility of a concurrent client
interrupting in the middle.
|
protected byte[] |
readWriteCache() |
protected void |
releaseReaderLockShared() |
void |
setHeartbeatAction(I2cDeviceSynch.HeartbeatAction action)
Sets the action to take when the current heartbeat interval expires.
|
void |
setHeartbeatInterval(int msHeartbeatInterval)
Sets the interval within which communication must be received by the I2C device lest
a timeout may occur.
|
void |
setI2cAddr(int i2cAddr8Bit)
Sets the I2C address of the underlying client.
|
void |
setLogging(boolean enabled)
Turn logging on or off.
|
void |
setLoggingTag(java.lang.String loggingTag)
Set the tag to use when logging is on.
|
void |
setReadWindow(I2cDeviceSynch.ReadWindow newWindow)
Set the set of registers that we will read and read and read again on every hardware cycle
|
protected void |
setReadWindowInternal(I2cDeviceSynch.ReadWindow newWindow) |
protected void |
unhook() |
protected void |
waitForIdleWriteCache() |
protected void |
waitForValidReadCache() |
protected void |
waitForWriteCompletionInternal() |
void |
waitForWriteCompletions()
Waits for any previously issued writes to be written to the USB controller module.
|
void |
write(int ireg,
byte[] data)
Writes data to a set of registers, beginning with the one indicated.
|
void |
write(int ireg,
byte[] data,
boolean waitForCompletion)
Writes data to a set of registers, beginning with the one indicated.
|
void |
write8(int ireg,
int data)
Writes a byte to the indicated register.
|
void |
write8(int ireg,
int data,
boolean waitforCompletion)
Writes a byte to the indicated register.
|
protected int i2cAddr8Bit
protected I2cDevice i2cDevice
protected boolean isI2cDeviceOwned
protected I2cController controller
protected RobotUsbModule robotUsbModule
protected boolean isHooked
protected boolean isEngaged
protected java.util.concurrent.atomic.AtomicInteger readerWriterPreventionCount
protected java.util.concurrent.locks.ReadWriteLock readerWriterGate
protected java.util.concurrent.atomic.AtomicInteger readerWriterCount
protected boolean isClosing
protected I2cDeviceSynchImpl.Callback callback
protected boolean loggingEnabled
protected java.lang.String loggingTag
protected ElapsedTime timeSinceLastHeartbeat
protected byte[] readCache
protected byte[] writeCache
protected static final int dibCacheOverhead
protected java.util.concurrent.locks.Lock readCacheLock
protected java.util.concurrent.locks.Lock writeCacheLock
protected static final int msCallbackLockWaitQuantum
protected static final int msCallbackLockAbandon
protected boolean isWriteCoalescingEnabled
protected final java.lang.Object engagementLock
protected final java.lang.Object concurrentClientLock
protected final java.lang.Object callbackLock
protected volatile I2cDeviceSynch.ReadWindow readWindow
protected volatile I2cDeviceSynch.ReadWindow readWindowActuallyRead
protected volatile I2cDeviceSynch.ReadWindow readWindowSentToController
protected volatile boolean isReadWindowSentToControllerInitialized
protected volatile boolean hasReadWindowChanged
protected volatile long nanoTimeReadCacheValid
protected volatile I2cDeviceSynchImpl.READ_CACHE_STATUS readCacheStatus
protected volatile I2cDeviceSynchImpl.WRITE_CACHE_STATUS writeCacheStatus
protected volatile I2cDeviceSynchImpl.CONTROLLER_PORT_MODE controllerPortMode
protected volatile int iregWriteFirst
protected volatile int cregWrite
protected volatile int msHeartbeatInterval
protected volatile I2cDeviceSynch.HeartbeatAction heartbeatAction
protected volatile java.util.concurrent.ExecutorService heartbeatExecutor
public I2cDeviceSynchImpl(I2cDevice i2cDevice, int i2cAddr8Bit, boolean isI2cDeviceOwned)
I2cDeviceSynchImpl instance on the indicated I2cDevice
using the indicated I2C address.i2cDevice - the I2cDevice that the new I2cDeviceSynchImpl is
to be a client ofi2cAddr8Bit - the 8bit I2C address to which communications will be targeted
The datasheet of many manufacturers will provide a 7bit value for their
I2c addresses. But the I2cDevice and I2cController interfaces take the
address in an 8bit format, where the lower bit is always zero. To convert
the former to the latter, multiply by two.isI2cDeviceOwned - If true, then when this I2cDeviceSynchImpl closes, the
underlying I2cDevice is closed as well; otherwise, it is
not. Typically, if the provided I2cDevice is retrieved from
an OpMode's hardware map, one passes false to isI2cDeviceOwned,
as such @link I2cDevice}s should remain functional across multiple
OpMode invocations.HardwareDevice.close(),
HardwareDevice.close()public void setI2cAddr(int i2cAddr8Bit)
I2cDeviceSynchsetI2cAddr in interface I2cDeviceSynchi2cAddr8Bit - the new I2C addresspublic int getI2cAddr()
I2cDeviceSynchgetI2cAddr in interface I2cDeviceSynchpublic void engage()
Engagableprotected void hook()
protected void adjustHooking()
public boolean isEngaged()
Engagablepublic boolean isArmed()
I2cDeviceSynchisArmed in interface I2cDeviceSynchEngagable.engage()public void disengage()
Engagableprotected void unhook()
protected void disableReadsAndWrites()
protected void enableReadsAndWrites()
protected boolean newReadsAndWritesAllowed()
protected void gracefullyDrainReadersAndWriters()
protected void forceDrainReadersAndWriters()
public java.lang.String getDeviceName()
HardwareDevicegetDeviceName in interface HardwareDevicepublic java.lang.String getConnectionInfo()
HardwareDevicegetConnectionInfo in interface HardwareDevicepublic int getVersion()
HardwareDevicegetVersion in interface HardwareDevicepublic void close()
HardwareDeviceclose in interface HardwareDevicepublic void setReadWindow(I2cDeviceSynch.ReadWindow newWindow)
I2cDeviceSynchsetReadWindow in interface I2cDeviceSynchnewWindow - the register window to read. May be null, indicating that no reads are to occur.I2cDeviceSynch.getReadWindow()protected void setReadWindowInternal(I2cDeviceSynch.ReadWindow newWindow)
public I2cDeviceSynch.ReadWindow getReadWindow()
I2cDeviceSynchgetReadWindow in interface I2cDeviceSynchI2cDeviceSynch.setReadWindow(ReadWindow)public void ensureReadWindow(I2cDeviceSynch.ReadWindow windowNeeded, I2cDeviceSynch.ReadWindow windowToSet)
I2cDeviceSynchensureReadWindow in interface I2cDeviceSynchwindowNeeded - Test the current register window, if any, against this window
to see if an update to the current register window is needed in
order to cover it. May be null, indicating that an update to the
current register window is always neededwindowToSet - If an update to the current register window is needed, then this
is the window to which it will be set. May be null.I2cDeviceSynch.setReadWindow(ReadWindow),
I2cDeviceSynch.read8(int)public byte read8(int ireg)
I2cDeviceSynchI2cDeviceSynch.readTimeStamped(int, int) for a
complete description.read8 in interface I2cDeviceSynchireg - the register number to readI2cDeviceSynch.read(int, int),
I2cDeviceSynch.readTimeStamped(int, int),
I2cDeviceSynch.ensureReadWindow(ReadWindow, ReadWindow)public byte[] read(int ireg,
int creg)
I2cDeviceSynchI2cDeviceSynch.readTimeStamped(int, int) for a
complete description.read in interface I2cDeviceSynchireg - the register number of the first byte register to readcreg - the number of bytes / registers to readI2cDeviceSynch.read8(int),
I2cDeviceSynch.readTimeStamped(int, int),
I2cDeviceSynch.ensureReadWindow(ReadWindow, ReadWindow)public I2cDeviceSynch.TimestampedData readTimeStamped(int ireg, int creg)
I2cDeviceSynchYou can always just call this method without worrying at all about
read windows,
that will work, but usually it is more efficient to take some thought and care as to what set
of registers the I2C device controller is being set up to read, as adjusting that window
of registers incurs significant extra time.
If the current read window can't be used to read the requested registers, then
a new read window will automatically be created as follows. If the current read window is non
null and wholly contains the registers to read but can't be read because it is a used-up
I2cDeviceSynch.ReadMode.ONLY_ONCE window,
a new read fresh window will be created with the same set of registers. Otherwise, a
window that exactly covers the requested set of registers will be created.
readTimeStamped in interface I2cDeviceSynchireg - the register number of the first byte register to readcreg - the number of bytes / registers to readI2cDeviceSynch.read(int, int),
I2cDeviceSynch.read8(int),
I2cDeviceSynch.ensureReadWindow(ReadWindow, ReadWindow)protected boolean isOpenForReading()
protected boolean isOpenForWriting()
protected void acquireReaderLockShared()
throws java.lang.InterruptedException
java.lang.InterruptedExceptionprotected void releaseReaderLockShared()
protected I2cDeviceSynch.TimestampedData makeFakeData(int ireg, int creg)
public I2cDeviceSynch.TimestampedData readTimeStamped(int ireg, int creg, I2cDeviceSynch.ReadWindow readWindowNeeded, I2cDeviceSynch.ReadWindow readWindowSet)
I2cDeviceSynchreadTimeStamped in interface I2cDeviceSynchireg - the register number of the first byte register to readcreg - the number of bytes / registers to readreadWindowNeeded - the read window we requirereadWindowSet - the read window to set if the required read window is not currentI2cDeviceSynch.ensureReadWindow(ReadWindow, ReadWindow),
I2cDeviceSynch.readTimeStamped(int, int)protected boolean readCacheValidityCurrentOrImminent()
protected boolean readCacheIsValid()
public void write8(int ireg,
int data)
I2cDeviceSynchI2cDeviceSynch.write(int, byte[], boolean).write8 in interface I2cDeviceSynchireg - the register number that is to be writtendata - the byte which is to be written to that registerI2cDeviceSynch.write(int, byte[], boolean)public void write8(int ireg,
int data,
boolean waitforCompletion)
I2cDeviceSynchI2cDeviceSynch.write(int, byte[], boolean).write8 in interface I2cDeviceSynchireg - the register number that is to be writtendata - the byte which is to be written to that registerwaitforCompletion - whether or not to wait until the write has been sent to the controllerI2cDeviceSynch.write(int, byte[], boolean)public void write(int ireg,
byte[] data)
I2cDeviceSynchI2cDeviceSynch.write(int, byte[], boolean).write in interface I2cDeviceSynchireg - the first of the registers which is to be writtendata - the data which is to be written to the registersI2cDeviceSynch.write(int, byte[], boolean)public void write(int ireg,
byte[] data,
boolean waitForCompletion)
I2cDeviceSynchwrite in interface I2cDeviceSynchireg - the first of the registers which is to be writtendata - the data which is to be written to the registerswaitForCompletion - whether or not to wait until the write has been sent to the controllerprotected static byte[] concatenateByteArrays(byte[] left,
byte[] right)
public void waitForWriteCompletions()
I2cDeviceSynchwaitForWriteCompletions in interface I2cDeviceSynchprotected byte[] readWriteCache()
protected void waitForWriteCompletionInternal()
throws java.lang.InterruptedException
java.lang.InterruptedExceptionprotected void waitForIdleWriteCache()
throws java.lang.InterruptedException
java.lang.InterruptedExceptionprotected void waitForValidReadCache()
throws java.lang.InterruptedException
java.lang.InterruptedExceptionwaitForIdleWriteCache()public void enableWriteCoalescing(boolean enable)
I2cDeviceSynchenableWriteCoalescing in interface I2cDeviceSynchenable - whether to enable write coalescing or notI2cDeviceSynch.isWriteCoalescingEnabled()public boolean isWriteCoalescingEnabled()
I2cDeviceSynchisWriteCoalescingEnabled in interface I2cDeviceSynchI2cDeviceSynch.enableWriteCoalescing(boolean)public void setLogging(boolean enabled)
I2cDeviceSynchsetLogging in interface I2cDeviceSynchenabled - whether to enable logging or notpublic void setLoggingTag(java.lang.String loggingTag)
I2cDeviceSynchsetLoggingTag in interface I2cDeviceSynchloggingTag - the logging tag to suepublic int getHeartbeatInterval()
I2cDeviceSynchgetHeartbeatInterval in interface I2cDeviceSynchI2cDeviceSynch.setHeartbeatInterval(int)public void setHeartbeatInterval(int msHeartbeatInterval)
I2cDeviceSynchsetHeartbeatInterval in interface I2cDeviceSynchmsHeartbeatInterval - the new hearbeat interval, in millisecondsI2cDeviceSynch.getHeartbeatInterval()public void setHeartbeatAction(I2cDeviceSynch.HeartbeatAction action)
I2cDeviceSynchsetHeartbeatAction in interface I2cDeviceSynchaction - the action to take at each heartbeat.I2cDeviceSynch.getHeartbeatAction(),
I2cDeviceSynch.setHeartbeatInterval(int)public I2cDeviceSynch.HeartbeatAction getHeartbeatAction()
I2cDeviceSynchgetHeartbeatAction in interface I2cDeviceSynchI2cDeviceSynch.setHeartbeatAction(HeartbeatAction)protected void log(int verbosity,
java.lang.String message)
protected void log(int verbosity,
java.lang.String format,
java.lang.Object... args)