cork.net.i2c
Class AbstractI2CDevice

java.lang.Object
  |
  +--cork.device.AbstractDevice
        |
        +--cork.net.i2c.AbstractI2CDevice
All Implemented Interfaces:
Device, I2CDevice
Direct Known Subclasses:
CMPS03, PCF8574, SRF08

public abstract class AbstractI2CDevice
extends AbstractDevice
implements I2CDevice

All I2C capable devices should use this base class for communitcating with the I2C bus.

Version:
0.2.1
Author:
Brill Pappin

Constructor Summary
protected AbstractI2CDevice(int address)
          Constructor for the AbstractDevice object
 
Method Summary
 void capture()
          Captures the BusMaster for exclusive access by a specific device.
 void destroy()
          Provides notification that bus is about to be destroyed.
 I2CBusMaster getBusMaster()
          Gets the bus master this device is using.
 int getDeviceAddress()
          Gets the I2C device address for this device.
abstract  I2CDevice getI2CDevice()
          This must be implemented by all I2C devices, and must return it's own instance.
 boolean isCaptured()
          Indicated that the line driver is in use by another device.
 void read(int id, int[] buffer, int count)
          Reads data from the specified ID.
 void release()
          Releases and frees the BusMaster for capture by another device.
 void start()
          Start communication on the I2C bus.
 void stop()
          Stops communication the I2C bus.
 void tick()
          Ticks over the SCL line.
 void write(int id, int[] buffer, int count)
          Writes data to the specified ID.
 
Methods inherited from class cork.device.AbstractDevice
addEventListener, removeEventListener, sendDeviceEvent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface cork.device.Device
getDeviceDestription, getDeviceName
 

Constructor Detail

AbstractI2CDevice

protected AbstractI2CDevice(int address)
Constructor for the AbstractDevice object
Parameters:
address - Description of Parameter
Since:
0.2.0
Method Detail

destroy

public void destroy()
Provides notification that bus is about to be destroyed. This methods should *not* throw an exception or hold the running thread for any length of time.

The default implementation of this method does nothing.

Since:
0.2.0

start

public final void start()
                 throws I2CException
Start communication on the I2C bus.
Throws:
I2CException - throws an I2CException is the device has not captured teh BusMaster.
Since:
0.2.0

stop

public final void stop()
                throws I2CException
Stops communication the I2C bus.
Throws:
I2CException - throws an I2CException is the device has not captured the BusMaster.
Since:
0.2.0

tick

public final void tick()
                throws I2CException
Ticks over the SCL line. Some devices may require an extra clock tick before releasing data, signaling an interrupt or properly filling a register.
Throws:
I2CException - throws an I2CException is the device has not captured the BusMaster.
Since:
0.2.1

capture

public final void capture()
                   throws I2CException
Captures the BusMaster for exclusive access by a specific device. It is possible in a multi-threaded environment for two or more devices to try and use the i2c line at the same time. This method acts as a sort fo thread mutex so that one device can finish its communication without interruption from another device.

How this method deals with with a wait state is implementaion dependant, but it is suggested to implementors that this method should block until the I2C line is free for communitaction.

Throws:
I2CException - throws an I2CException is the capture method produced an error, or was unable to capture the BusMaster for some reason.
Since:
0.2.0

release

public final void release()
                   throws I2CException
Releases and frees the BusMaster for capture by another device. See: I2CBusMaster.capture()::boolean
Throws:
I2CException - throws an I2CException is the device has not previously captured the BusMaster.
Since:
0.2.0

read

public final void read(int id,
                       int[] buffer,
                       int count)
                throws I2CException,
                       java.lang.ArrayIndexOutOfBoundsException
Reads data from the specified ID. The capture and start method must have been called first.
Parameters:
id - the id we're addressing the bytes to.
buffer - the buffer that the bytes will be added to.
count - the number of bytes to read into the buffer.
Throws:
I2CException - throws an I2CException is the device has not captured the BusMaster. Also thrown if the or if there was some other problem reading from the bus.
java.lang.ArrayIndexOutOfBoundsException - if the count is larger than the buffer, or the count os less than 1.
Since:
0.2.0

write

public final void write(int id,
                        int[] buffer,
                        int count)
                 throws I2CException,
                        java.lang.ArrayIndexOutOfBoundsException
Writes data to the specified ID. The capture and start method must have been called first.
Parameters:
id - the id we're addressing the bytes to.
buffer - the buffer the the bytes will be written from.
count - the number of bytes ro write.
Throws:
I2CException - throws an I2CException is the device has not captured the BusMaster. or if there was some other problem writing to the bus.
java.lang.ArrayIndexOutOfBoundsException - if the count is larger than the buffer, or the count os less than 1.
Since:
0.2.0

getI2CDevice

public abstract I2CDevice getI2CDevice()
This must be implemented by all I2C devices, and must return it's own instance.
Returns:
This instance of an I2C device.
Since:
0.2.0

getDeviceAddress

public final int getDeviceAddress()
Gets the I2C device address for this device.

The address is an array to support future expansion of devices to the new I2C protocol that allows 2 byte addresses. For most devices the array will have a length of 1.

Specified by:
getDeviceAddress in interface I2CDevice
Returns:
int[] the device address.
Since:
0.1.0

getBusMaster

public final I2CBusMaster getBusMaster()
Gets the bus master this device is using.
Specified by:
getBusMaster in interface I2CDevice
Returns:
The busMaster value
Since:
0.2.0

isCaptured

public final boolean isCaptured()
Indicated that the line driver is in use by another device. See: I2CBusMaster.capture()::boolean
Returns:
true if the BusMaster is already in use, false otherwise.
Since:
0.2.0