com.cinterion.io

Class I2cBusConnection

java.lang.Object

com.cinterion.io.I2cBusConnection

public class I2cBusConnection
extends Object

This interface defines a logical connection to an I2C bus.

An I2C bus is accessed using an explicit bus identifier and optional baudrate.

Only one application may be connected to a particular I2C bus at a given time. An java.io.IOException is thrown, if an attempt is made to open the I2C bus with I2cBusConnection.open() and the connection is already open.

Note : Now the 'delay after read' and 'delay after write' are not supported currently.

Specifying Delay Time for I2C

The following figures are provided to assist you in specifying appropriate values for the parameters <delayone> and <delaytwo>. All delays are relative to the data transfer rate. To calculate the delay use the formula and the values given below.

Formula for calculating the delay:

Table with values for calculating the delay:

Parameters	Values
Delay value	Value set with parameter writeDelay or readDelay
Master clock	13 MHz
Default data transfer rate	400 bps
User data transfer rate	Baud rate given as parameter of connection, for example 100 kbps or 400 kbps
Delay_min for Write	7.4 盜 at 100 kbps 2.0 盜 at 400 kbps
Delay_min for Read	9.9 盜 at 100 kbps 2.6 盜 at 400 kbps

Delay time on I2C after write:

Delay time on I2C after read:

Transmitting Data

This section provides information on the protocol used for data transmission to or from I2C devices and explains the data mode. It is assumed that you are familiar with the I2C specification.

ASCII Protocol for I2C communication:

For transfer and response, special characters are defined, such as Start and Stop to mark a single message and Close to disconnect the data channel. All valid special characters are listed below:

Direction	Function in protocol	Special character	Hex value	Description
master -> slave	Start Transfer Message	<	0x3C	Special character sent to the I2C slave to start sending
master -> slave	Stop Transfer Message	>	0x3E	Special character sent to the I2C slave to stop sending.
slave -> master	Start Response Message	{	0x7B	Special character sent to the I2C master to mark the beginning of a response message
slave -> master	Stop Response Message	}	0x7D	Special character sent to the I2C master to mark the end of a response message
slave -> master	Protocol error	!	0x21	Reports to the I2C master that the transfer frame does not comply with the protocol definition (syntax error).
slave -> master	Transmission OK (in I2C protocol referred to as ACK)	+	0x2B	Notifies the I2C master: data were successfully transmitted the I2C slave address was recognized.
slave -> master	Transmission error (in I2C protocol referred to as NAK)	-	0x2D	Notifies the I2C master: either that data transmission failed the I2C slave address was not recognized the faulty data byte (16 bit byte counter) is identified

Message syntax:

Each Message consists of a Start and Stop character, a Message-ID, further protocol data and user data. The notation of all elements is explained below.

Notation of Message-ID:

• All ASCII characters between 0x00...0x7F. It is recommended to use only the characters 0...9, A...Z, a...z
• Length of the Message-ID: only one character

Notation of protocol data (except Message-ID) and user data:

• Hex (0...9, a...f, A...F)
• Without "0x" (0x01 -> 01)
• Each hex value consists of 2 characters (1 -> 01)
• Without delimiters such as comma, semicolon, space etc. (0xAE 0x01 0xA5 -> AE01A5)
• In a Transfer Message, the number of all characters after the Message ID shall be even. If it is odd, a protocol error will be reported. On the I2C bus, this applies to the I2C Slave Address and all subsequent written user data. Keep in mind that the number of all characters transmitted between Start "<" and Stop ">" of the Transfer Frame shall always be odd because the ID is one character only.
• Length of I2C Slave Address and user data: = 2048 bytes

The first element of each message is the Start character ("<" for Transfer, "{" for the Response). Accordingly, the last character of a message is the Stop character (">" for Transfer, "}" for the Response).

The second element of each message is the Message ID (1 character). The Message ID serves the user to distinguish between different messages. It is only relevant on protocol level (between Java interface and I2C device driver), i.e. it is not sent to the I2C slave device.

Each transfer to the device is followed by a Response Message sent from the driver to the Java interface. The response includes the Message ID and either OK ("+") or error characters ("-" or "!"). A successful response to a Read Message contains the OK character and the read data. If an error occurs on the I2C bus, the response consists of an error character followed by a 16 bit code specifying the faulty byte.

After each Transfer Message, wait for the Response Message before sending the next Transfer Message.

All characters entered outside a valid message (i.e. not input between Start character "<" and Stop character ">") are ignored.

Structure of Messages on the I2C Bus:

Frame	Format
Write Transfer Message	<_ID SlaveAddress Data> Maximum length: 2048 bytes for I2C Slave Address and written data. LSB of I2C Slave Address = "0".
Read Transfer Message	<_ID SlaveAddress ReadLength> Read Length = 2048 bytes. LSB I2C of Slave Address = "1".
Response Message Write OK Read of x bytes OK NAK for xth byte if Read or Write Protocol error in xth byte	{ID +} {ID + Data} {ID - xxxx} {ID ! xxxx}

On the I2C bus, read and write data are handled in two separate frames transmitted one after the other. This is because the I2C bus has only two bus lines, I2CDAT (I2CDAT_SPIDO) for the serial data and I2CCLK (I2CCLK_SPICLK) for the serial clock. Write data are packed into a Transfer Frame. Read data are packed into a Response Frame. The Transfer Frame contains a Receive or Transmit Request (R/W Request) for the I2C master.

In a Transfer Message (Read or Write), the third element is the 7-bit I2C Slave Address (2 characters) that identifies each single device connected to the bus. The 8th bit of this byte is the LSB that determines the direction of the message. If the LSB is "0" the master will write information to the selected slave. If the LSB is "1" the master will read information sent from the slave.

In a Read Transfer Message on the I2C bus, the size of the expected data must be specified explicitly. This is an element of 4 characters stating the number of bytes to be read. It must be placed after the I2C Slave Address.

Error Handling on the I2C Bus

Protocol error:
If a protocol error is detected the ASCII value "!" is sent to the AT interface. Also, a Stop Condition is sent to the I2C device. A protocol error occurs if:

• any data / address characters do not equal 0...9, a...f and A...F
• the length of a read word is smaller or greater than 16 bits
• the number of ASCII data is odd (e.g. "af1" instead of "af01")
• the Read or Write request is greater than 2 KB (0x0800).

Acknowledge:
Once a transmission has completed successfully (Write or Read), the special character "+" (ACK) is included in the Response sent to the AT interface. During a Write Transfer, the I2C driver acknowledges each transferred byte, but the Response contains only one ACK which is transmitted only if all bytes are successfully transferred. During a Read Transfer, an ACK is sent when the I2C slave device notifies that it has recognized the I2C Slave Address.

Not Acknowledge:
During a Transmit Transfer, a NAK is given when the I2C Slave Device notifies a failure to receive either the I2C Slave Address or a data byte. In this case, a Stop Condition is sent to the I2C device. During a Receive Transfer, a NAK is transmitted only when the I2C does not receive any reponse for the I2C Slave Address. The I2C device never acknowledges the validity of the received data (by sending an ACK the master acknowledges each received byte to the slave).

Example

The following example shows how a I2cBusConnection shall be used to access a I2C device.

• Open I2C connection and data streams:

   I2cBusConnection cc = I2cBusConnection.open(0, 400);
  
   int baudrate = cc.getBaudRate();
   InputStream inStream = cc.openInputStream();
   OutputStream outStream = cc.openOutputStream();
   

• Write Transfer Frame, where a = message ID, AE = Slave Address and write request:

   String data = "<aAE000102030405060708090A0B0C0E0F>";
   outStream.write(data.getBytes(), 0, data.length());
   outStream.flush();
   

• Read response message: {a+} where a = message ID:

   byte[] inBuf = new byte[<size>];
   if (inStream.available())
    int inBufLen = inStream.read(inBuf);
  
   Note that the read method blocks the thread until at least one byte has been read.
   To avoid blocking infinitely in case the I2C bus does not respond, check please first
   if there is data available. If the bus sends a big amount of data, the data will be read
   in pieces and the implementation has to poll until the end of the data.
   

• Close data streams and connection:

   inStream.close();
   outStream.close();
   cc.close();
   

Method Summary

Modifier and Type	Method and Description
void	close() Closes the I2C bus connection.
int	getBaudRate() Gets the baudrate for the I2C connection.
int	getDelayAfterRead() Gets the given delay after reading for the I2C connection.
int	getDelayAfterWrite() Gets the given delay after writing for the I2C connection.
static I2cBusConnection	open(int busId) Open a new instance of a logical connection to an I2C bus.
static I2cBusConnection	open(int busId, int baudrate) Open a new instance of a logical connection to an I2C bus.
InputStream	openInputStream() Returns an InputStream for this connection.
OutputStream	openOutputStream() Returns an OutputStream for this connection.

Methods inherited from class java.lang.Object

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

Method Detail

open

public static I2cBusConnection open(int busId)
                             throws IOException

Open a new instance of a logical connection to an I2C bus.

An I2C bus is accessed using an explicit bus identifier. The baud rate is 400kpbs by default.

Only one application may be connected to a particular I2C bus at a given time.

Parameters:

busId - I2C bus identifier.

Returns:

New I2cBusConnection instance.

Throws:

IOException - A java.io.IOException is thrown, if an attempt is made to open the I2C bus and the connection is already open.

open

public static I2cBusConnection open(int busId,
                                    int baudrate)
                             throws IOException

Open a new instance of a logical connection to an I2C bus.

An I2C bus is accessed using an explicit bus identifier and baud rate.

Only one application may be connected to a particular I2C bus at a given time.

Parameters:

busId - The I2C bus identifier.

baudrate - The baud rate of the I2C bus (in kpbs)

Returns:

New I2cBusConnection instance.

Throws:

IOException - A java.io.IOException is thrown, if an attempt is made to open the I2C bus and the connection is already open.

openInputStream

public InputStream openInputStream()
                            throws IOException

Returns an InputStream for this connection.

Closing the InputStream and the OutputStream of a I2cBusConnection allows to close the I2cBusConnection.

Returns:

An InputStream for reading bytes from this I2cBusConnection.

Throws:

IOException -

• An InputStream is already open on the I2cBusConnection.
• The I2cBusConnection where to open the InputStream is closed.

openOutputStream

public OutputStream openOutputStream()
                              throws IOException

Returns an OutputStream for this connection.

Closing the InputStream and the OutputStream of a I2cBusConnection allows to close the I2cBusConnection.

Returns:

An OutputStream for writing bytes to this I2cBusConnection.

Throws:

IOException -

• An OutputStream is already open on the I2cBusConnection.
• The I2cBusConnection where to open the OutputStream is closed.

getBaudRate

public int getBaudRate()

Gets the baudrate for the I2C connection.

Returns:

the baudrate of the connection

getDelayAfterRead

public int getDelayAfterRead()

Gets the given delay after reading for the I2C connection.

Returns:

the delay after reading

getDelayAfterWrite

public int getDelayAfterWrite()

Gets the given delay after writing for the I2C connection.

Returns:

the delay after writing

close

public void close()
           throws IOException

Closes the I2C bus connection.

If the I2cBusConnection has already been closed or a close is pending, this method does nothing. If the I2cBusConnection has underlying open streams, the I2cBusConnection will be closed only when these streams will be closed.

Throws:

IOException - if an I/O error occurs