com.qualcomm.hardware.lynx

Class LynxI2cDeviceSynch

java.lang.Object

com.qualcomm.hardware.lynx.LynxCommExceptionHandler

com.qualcomm.hardware.lynx.LynxController

com.qualcomm.hardware.lynx.LynxI2cDeviceSynch

All Implemented Interfaces:

Engagable, HardwareDevice, HardwareDeviceHealth, I2cAddrConfig, I2cAddressableDevice, I2cDeviceSynchReadHistory, I2cDeviceSynchSimple, RobotConfigNameable, RobotArmingStateNotifier, RobotArmingStateNotifier.Callback

Direct Known Subclasses:

LynxI2cDeviceSynchV1, LynxI2cDeviceSynchV2

public abstract class LynxI2cDeviceSynch
extends LynxController
implements I2cDeviceSynchSimple, I2cDeviceSynchReadHistory

Created by bob on 2016-03-12.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LynxI2cDeviceSynch.BusSpeed Lynx I2C bus speed.

Nested classes/interfaces inherited from class com.qualcomm.hardware.lynx.LynxController

LynxController.PretendLynxModule

Nested classes/interfaces inherited from interface com.qualcomm.robotcore.hardware.HardwareDeviceHealth

HardwareDeviceHealth.HealthStatus

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

HardwareDevice.Manufacturer

Nested classes/interfaces inherited from interface com.qualcomm.robotcore.hardware.usb.RobotArmingStateNotifier

RobotArmingStateNotifier.ARMINGSTATE, RobotArmingStateNotifier.Callback

Field Summary

Fields

Modifier and Type	Field and Description
protected int	bus
protected I2cAddr	i2cAddr
protected LynxUsbUtil.Placeholder<TimestampedData>	readTimeStampedPlaceholder
static java.lang.String	TAG

Fields inherited from class com.qualcomm.hardware.lynx.LynxController

context, hardwareDeviceHealth, isEngaged, isHardwareInitialized, isHooked, registeredCallbacks

Fields inherited from class com.qualcomm.hardware.lynx.LynxCommExceptionHandler

tag

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LynxI2cDeviceSynch(Context context, LynxModule module, int bus)

Method Summary

Modifier and Type	Method and Description
protected <T> T	acquireI2cLockWhile(Supplier<T> supplier)
void	close() Closes this device
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.
java.lang.String	getConnectionInfo() Get connection information about this device in a human readable format
java.lang.String	getDeviceName() Returns a string suitable for display to the user as to the type of device.
java.util.concurrent.BlockingQueue<TimestampedI2cData>	getHistoryQueue() (Advanced) Returns a queue into which, if requested, TimestampedI2cDatas are (optionally) placed as they become available.
int	getHistoryQueueCapacity() Returns the current capacity of the history queue.
I2cAddr	getI2cAddr() Returns the I2C address currently being used by this device client
I2cAddr	getI2cAddress() Returns the I2C address currently in use to communicate with an I2C hardware device
boolean	getLogging()
java.lang.String	getLoggingTag()
protected java.lang.String	getTag()
java.lang.String	getUserConfiguredName() Returns the human-recognizable name of this device, if same has been set.
protected void	internalWaitForWriteCompletions(I2cWaitControl waitControl)
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	isWriteCoalescingEnabled() Answers as to whether write coalescing is currently enabled on this device.
protected TimestampedData	pollForReadResult(I2cAddr i2cAddr, int ireg, int creg)
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.
abstract 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.
void	resetDeviceConfigurationForOpMode() Resets the device's configuration to that which is expected at the beginning of an OpMode.
protected void	sendI2cWriteTx(LynxCommand writeTx)
void	setBusSpeed(LynxI2cDeviceSynch.BusSpeed speed) Sets the bus speed.
void	setHistoryQueueCapacity(int capacity) Sets the maximum number of TimestampedI2cDatas that will simultaneously be stored in the history queue.
void	setI2cAddr(I2cAddr i2cAddr) Sets the I2C address of the underlying client.
void	setI2cAddress(I2cAddr i2cAddr) Configures a new I2C address to use
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	setUserConfiguredName(java.lang.String name) Informs the device of a name by which it would be recognized by the user.
void	waitForWriteCompletions(I2cWaitControl waitControl) Waits for the most recent write to complete according to the behavior specified in writeControl.
void	write(int ireg, byte[] data) Writes data to a set of registers, beginning with the one indicated, using I2cWaitControl.ATOMIC semantics.
void	write(int ireg, byte[] data, I2cWaitControl waitControl) Writes data to a set of registers, beginning with the one indicated.
void	write8(int ireg, int bVal) Writes a byte to the indicated register using I2cWaitControl.ATOMIC semantics.
void	write8(int ireg, int bVal, I2cWaitControl waitControl) Writes a byte to the indicated register.

Methods inherited from class com.qualcomm.hardware.lynx.LynxController

adjustHookingToMatchEngagement, disengage, doHook, doUnhook, engage, finishConstruction, floatHardware, forgetLastKnown, getArmingState, getHealthStatus, getHealthStatusOverride, getManufacturer, getModule, getSerialNumber, getVersion, hook, initializeHardware, isEngaged, moduleNowArmedOrPretending, moduleNowDisarmed, onModuleStateChange, registerCallback, setHealthStatus, setHealthyIfArmed, unhook, unregisterCallback

Methods inherited from class com.qualcomm.hardware.lynx.LynxCommExceptionHandler

handleException, handleSpecificException, handleSpecificException, handleSpecificException, handleSpecificException

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.qualcomm.robotcore.hardware.HardwareDeviceHealth

getHealthStatus, setHealthStatus

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

getManufacturer, getVersion

Field Detail

TAG

public static final java.lang.String TAG

See Also:

Constant Field Values

i2cAddr

protected I2cAddr i2cAddr

bus

protected int bus

readTimeStampedPlaceholder

protected LynxUsbUtil.Placeholder<TimestampedData> readTimeStampedPlaceholder

Constructor Detail

LynxI2cDeviceSynch

protected LynxI2cDeviceSynch(Context context,
                             LynxModule module,
                             int bus)

Method Detail

getTag

protected java.lang.String getTag()

Specified by:

getTag in class LynxController

getDeviceName

public java.lang.String getDeviceName()

Description copied from interface: HardwareDevice

Returns a string suitable for display to the user as to the type of device. Note that this is a device-type-specific name; it has nothing to do with the name by which a user might have configured the device in a robot configuration.

Specified by:

getDeviceName in interface HardwareDevice

Specified by:

getDeviceName in class LynxController

Returns:

device manufacturer and name

getConnectionInfo

public java.lang.String getConnectionInfo()

Description copied from interface: HardwareDevice

Get connection information about this device in a human readable format

Specified by:

getConnectionInfo in interface HardwareDevice

Overrides:

getConnectionInfo in class LynxController

Returns:

connection info

resetDeviceConfigurationForOpMode

public void resetDeviceConfigurationForOpMode()

Description copied from interface: HardwareDevice

Resets the device's configuration to that which is expected at the beginning of an OpMode. For example, motors will reset the their direction to 'forward'.

Specified by:

resetDeviceConfigurationForOpMode in interface HardwareDevice

Overrides:

resetDeviceConfigurationForOpMode in class LynxController

close

public void close()

Description copied from interface: HardwareDevice

Closes this device

Specified by:

close in interface HardwareDevice

Overrides:

close in class LynxController

isArmed

public boolean isArmed()

Description copied from interface: I2cDeviceSynchSimple

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. Note that a device client which is not engaged will never report as armed.

Specified by:

isArmed in interface I2cDeviceSynchSimple

Overrides:

isArmed in class LynxController

Returns:

the arming state of this device client

See Also:

Engagable.engage()

setI2cAddress

public void setI2cAddress(I2cAddr i2cAddr)

Description copied from interface: I2cAddrConfig

Configures a new I2C address to use

Specified by:

setI2cAddress in interface I2cAddrConfig

Parameters:

i2cAddr - the new I2C address to use

setI2cAddr

public void setI2cAddr(I2cAddr i2cAddr)

Description copied from interface: I2cDeviceSynchSimple

Sets the I2C address of the underlying client. If necessary, the client may be briefly disengaged (and then automatically reengaged) in the process.

Specified by:

setI2cAddr in interface I2cDeviceSynchSimple

Parameters:

i2cAddr - the new I2C address

getI2cAddress

public I2cAddr getI2cAddress()

Description copied from interface: I2cAddressableDevice

Returns the I2C address currently in use to communicate with an I2C hardware device

Specified by:

getI2cAddress in interface I2cAddressableDevice

Returns:

the I2C address currently in use

getI2cAddr

public I2cAddr getI2cAddr()

Description copied from interface: I2cDeviceSynchSimple

Returns the I2C address currently being used by this device client

Specified by:

getI2cAddr in interface I2cDeviceSynchSimple

Returns:

the current I2C address

setUserConfiguredName

public void setUserConfiguredName(java.lang.String name)

Description copied from interface: RobotConfigNameable

Informs the device of a name by which it would be recognized by the user. Note that the provided name may be null, in which case no such user-recognizable name is provided

Specified by:

setUserConfiguredName in interface RobotConfigNameable

getUserConfiguredName

public java.lang.String getUserConfiguredName()

Description copied from interface: RobotConfigNameable

Returns the human-recognizable name of this device, if same has been set.

Specified by:

getUserConfiguredName in interface RobotConfigNameable

See Also:

RobotConfigNameable.setUserConfiguredName(String)

setLogging

public void setLogging(boolean enabled)

Description copied from interface: I2cDeviceSynchSimple

Turn logging on or off. Logging output can be viewed using the Android Logcat tools.

Specified by:

setLogging in interface I2cDeviceSynchSimple

Parameters:

enabled - whether to enable logging or not

getLogging

public boolean getLogging()

Specified by:

getLogging in interface I2cDeviceSynchSimple

See Also:

I2cDeviceSynchSimple.setLogging(boolean)

setLoggingTag

public void setLoggingTag(java.lang.String loggingTag)

Description copied from interface: I2cDeviceSynchSimple

Set the tag to use when logging is on.

Specified by:

setLoggingTag in interface I2cDeviceSynchSimple

Parameters:

loggingTag - the logging tag to sue

getLoggingTag

public java.lang.String getLoggingTag()

Specified by:

getLoggingTag in interface I2cDeviceSynchSimple

See Also:

I2cDeviceSynchSimple.setLoggingTag(String)

setHistoryQueueCapacity

public void setHistoryQueueCapacity(int capacity)

Description copied from interface: I2cDeviceSynchReadHistory

Sets the maximum number of TimestampedI2cDatas that will simultaneously be stored in the history queue. If the queue is full and new TimestampedI2cDatas become available, older data will be discarded. The history queue initially has a capacity of zero.

Note that calling this method invalidates any history queue retrieved previously through I2cDeviceSynchReadHistory.getHistoryQueue().

Specified by:

setHistoryQueueCapacity in interface I2cDeviceSynchReadHistory

Parameters:

capacity - the maximum number of items that may be stored in the history queue

See Also:

I2cDeviceSynchReadHistory.getHistoryQueue(), I2cDeviceSynchReadHistory.getHistoryQueueCapacity()

getHistoryQueueCapacity

public int getHistoryQueueCapacity()

Description copied from interface: I2cDeviceSynchReadHistory

Returns the current capacity of the history queue.

Specified by:

getHistoryQueueCapacity in interface I2cDeviceSynchReadHistory

Returns:

the current capacity of the history queue.

See Also:

I2cDeviceSynchReadHistory.setHistoryQueueCapacity(int), I2cDeviceSynchReadHistory.getHistoryQueue()

getHistoryQueue

public java.util.concurrent.BlockingQueue<TimestampedI2cData> getHistoryQueue()

Description copied from interface: I2cDeviceSynchReadHistory

(Advanced) Returns a queue into which, if requested, TimestampedI2cDatas are (optionally) placed as they become available.

To access these TimestampedI2cDatas, call I2cDeviceSynchReadHistory.setHistoryQueueCapacity(int) to enable the history queue. Once enabled, the history queue can be accessed using I2cDeviceSynchReadHistory.getHistoryQueue() and the methods thereon used to access TimestampedI2cDatas as they become available.

When I2cDeviceSynchReadHistory.setHistoryQueueCapacity(int) is called, any history queue returned previously by I2cDeviceSynchReadHistory.getHistoryQueue() becomes invalid and must be re-fetched.

Specified by:

getHistoryQueue in interface I2cDeviceSynchReadHistory

Returns:

a queue through which I2c TimestampedI2cDatas may be retrieved.

See Also:

I2cDeviceSynchReadHistory.setHistoryQueueCapacity(int)

read

public byte[] read(int ireg,
                   int creg)

Description copied from interface: I2cDeviceSynchSimple

Read a contiguous set of device I2C registers. See I2cDeviceSynchSimple.readTimeStamped(int, int) for a complete description.

Specified by:

read in interface I2cDeviceSynchSimple

Parameters:

ireg - the register number of the first byte register to read

creg - the number of bytes / registers to read

Returns:

the data which was read

See Also:

I2cDeviceSynchSimple.read8(int), I2cDeviceSynchSimple.readTimeStamped(int, int), I2cDeviceSynch.ensureReadWindow(I2cDeviceSynch.ReadWindow, I2cDeviceSynch.ReadWindow)

read8

public byte read8(int ireg)

Description copied from interface: I2cDeviceSynchSimple

Read the byte at the indicated register. See I2cDeviceSynchSimple.readTimeStamped(int, int) for a complete description.

Specified by:

read8 in interface I2cDeviceSynchSimple

Parameters:

ireg - the register number to read

Returns:

the byte that was read

See Also:

I2cDeviceSynchSimple.read(int, int), I2cDeviceSynchSimple.readTimeStamped(int, int), I2cDeviceSynch.ensureReadWindow(I2cDeviceSynch.ReadWindow, I2cDeviceSynch.ReadWindow)

readTimeStamped

public abstract TimestampedData readTimeStamped(int ireg,
                                                int creg)

Description copied from interface: I2cDeviceSynchSimple

Reads and returns a contiguous set of device I2C registers, together with a best-available timestamp of when the actual I2C read occurred. Note that this can take many tens of milliseconds to execute, and thus should not be called from the loop() thread.

You 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 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.

Specified by:

readTimeStamped in interface I2cDeviceSynchSimple

Parameters:

ireg - the register number of the first byte register to read

creg - the number of bytes / registers to read

Returns:

the data which was read, together with the timestamp

See Also:

I2cDeviceSynchSimple.read(int, int), I2cDeviceSynchSimple.read8(int), I2cDeviceSynch.ensureReadWindow(I2cDeviceSynch.ReadWindow, I2cDeviceSynch.ReadWindow)

write

public void write(int ireg,
                  byte[] data)

Description copied from interface: I2cDeviceSynchSimple

Writes data to a set of registers, beginning with the one indicated, using I2cWaitControl.ATOMIC semantics.

Specified by:

write in interface I2cDeviceSynchSimple

Parameters:

ireg - the first of the registers which is to be written

data - the data which is to be written to the registers

See Also:

I2cDeviceSynchSimple.write(int, byte[], I2cWaitControl)

write8

public void write8(int ireg,
                   int bVal)

Description copied from interface: I2cDeviceSynchSimple

Writes a byte to the indicated register using I2cWaitControl.ATOMIC semantics.

Specified by:

write8 in interface I2cDeviceSynchSimple

Parameters:

ireg - the register number that is to be written

bVal - the byte which is to be written to that register

See Also:

I2cDeviceSynchSimple.write(int, byte[], I2cWaitControl)

write8

public void write8(int ireg,
                   int bVal,
                   I2cWaitControl waitControl)

Description copied from interface: I2cDeviceSynchSimple

Writes a byte to the indicated register. See also I2cDeviceSynchSimple.write(int, byte[], I2cWaitControl).

Specified by:

write8 in interface I2cDeviceSynchSimple

Parameters:

ireg - the register number that is to be written

bVal - the byte which is to be written to that register

waitControl - controls the behavior of waiting for the completion of the write

See Also:

I2cDeviceSynchSimple.write(int, byte[], I2cWaitControl)

write

public void write(int ireg,
                  byte[] data,
                  I2cWaitControl waitControl)

Description copied from interface: I2cDeviceSynchSimple

Writes data to a set of registers, beginning with the one indicated. The data will be written to the I2C device in an expeditious manner. Once data is accepted by this API, it is guaranteed that (barring catastrophic failure) the data will be transmitted to the USB controller module before the I2cDeviceSync is closed. The call itself may or may block until the data has been transmitted to the USB controller module according to a caller-provided parameter.

Specified by:

write in interface I2cDeviceSynchSimple

Parameters:

ireg - the first of the registers which is to be written

data - the data which is to be written to the registers

waitControl - controls the behavior of waiting for the completion of the write

waitForWriteCompletions

public void waitForWriteCompletions(I2cWaitControl waitControl)

Description copied from interface: I2cDeviceSynchSimple

Waits for the most recent write to complete according to the behavior specified in writeControl.

Specified by:

waitForWriteCompletions in interface I2cDeviceSynchSimple

Parameters:

waitControl - controls the behavior of waiting for the completion of the write Note that a value of I2cWaitControl.NONE is essentially a no-op.

enableWriteCoalescing

public void enableWriteCoalescing(boolean enable)

Description copied from interface: I2cDeviceSynchSimple

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. By default, write coalescing is disabled.

Specified by:

enableWriteCoalescing in interface I2cDeviceSynchSimple

Parameters:

enable - whether to enable write coalescing or not

See Also:

I2cDeviceSynchSimple.isWriteCoalescingEnabled()

isWriteCoalescingEnabled

public boolean isWriteCoalescingEnabled()

Description copied from interface: I2cDeviceSynchSimple

Answers as to whether write coalescing is currently enabled on this device.

Specified by:

isWriteCoalescingEnabled in interface I2cDeviceSynchSimple

Returns:

whether write coalescing is currently enabled or not.

See Also:

I2cDeviceSynchSimple.enableWriteCoalescing(boolean)

sendI2cWriteTx

protected void sendI2cWriteTx(LynxCommand writeTx)
                       throws LynxNackException,
                              java.lang.InterruptedException

Throws:

LynxNackException

java.lang.InterruptedException

acquireI2cLockWhile

protected <T> T acquireI2cLockWhile(Supplier<T> supplier)
                             throws java.lang.InterruptedException,
                                    RobotCoreException,
                                    LynxNackException

Throws:

java.lang.InterruptedException

RobotCoreException

LynxNackException

internalWaitForWriteCompletions

protected void internalWaitForWriteCompletions(I2cWaitControl waitControl)

pollForReadResult

protected TimestampedData pollForReadResult(I2cAddr i2cAddr,
                                            int ireg,
                                            int creg)

setBusSpeed

public void setBusSpeed(LynxI2cDeviceSynch.BusSpeed speed)

Sets the bus speed.

Parameters:

speed - new bus speed