cork.net.i2c
Interface I2CBusMaster

All Known Implementing Classes:

I2CLineDriver, AbstractLineDriver

public interface I2CBusMaster

Provides a high level interface to the I2C bus master, allowing bytes to be written and read from the bus.

Implementations are expected to use byte buffers in the following manner. When reading and writing to the bus the implementation will take a reference to the devices byte buffer. In this way devices can maintain their own buffers preventing future bus operations from overwriting recieved values. Furthermore, this removes any requirement for the I2CBusMaster to create new buffers that may possibly require garbage collection in the future.

All bus operations may throw an I2CBusException should the bus stall. This might be considered an indicator that the operation you were trying to perform did not complete successfully.

Version:

0.2.1

Author:

Elliot West, Brill Pappin

Method Summary

void	capture(I2CDevice device) Captures the BusMaster for exclusive access by a specific device.
boolean	isCaptured() Indicates that the line driver is in use by another device.
void	read(I2CDevice device, int id, int[] buffer, int count) Reads data from the specified ID.
void	release(I2CDevice device) Releases and frees the BusMaster for capture by another device.
void	start(I2CDevice device) Start communication on the I2C bus.
void	stop(I2CDevice device) Stops communication the I2C bus.
void	tick(I2CDevice device) Ticks over the SCL line.
void	write(I2CDevice device, int id, int[] buffer, int count) Writes data to the specified ID.

Method Detail

start

public void start(I2CDevice device)
           throws I2CException

Start communication on the I2C bus.

Parameters:

device - the device calling the start() method. This device must have first captured the BusMaster.

Throws:

I2CException - throws an I2CException is the device has not captured teh BusMaster.

Since:

0.2.0

stop

public void stop(I2CDevice device)
          throws I2CException

Stops communication the I2C bus.

Parameters:

device - the device calling the stop() method. This device must have first captured the BusMaster.

Throws:

I2CException - throws an I2CException is the device has not captured the BusMaster.

Since:

0.2.0

tick

public void tick(I2CDevice device)
          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.

Parameters:

device - the device calling the tick() method. This device must have first captured the BusMaster.

Throws:

I2CException - throws an I2CException is the device has not captured the BusMaster.

Since:

0.2.1

capture

public void capture(I2CDevice device)
             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.

Parameters:

device - the device wishing to capture the BusMaster

Throws:

I2CException - Description of Exception

Since:

0.2.0

release

public void release(I2CDevice device)
             throws I2CException

Releases and frees the BusMaster for capture by another device. See: I2CBusMaster.capture()::boolean

Parameters:

device - the device wishing to release the BusMaster

Throws:

I2CException - throws an I2CException is the device has not captured teh BusMaster.

Since:

0.2.0

isCaptured

public boolean isCaptured()

Indicates 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

read

public void read(I2CDevice device,
                 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.

device - the device wishing to read the BusMaster. This device must have first captured the BusMaster.

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 void write(I2CDevice device,
                  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.

device - the device wishing to write the BusMaster. This device must have first captured the BusMaster.

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