com.cinterion.io

Interface I2cBusConnection

All Superinterfaces:

Connection, InputConnection, OutputConnection, StreamConnection

public interface I2cBusConnection
extends StreamConnection

This interface defines a logical connection to an I2C bus.

A I2C bus is accessed using a Generic Connection Framework string with an explicit bus identifier and embedded configuration parameters, each separated with a semi-colon (;).

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 Connector.open() and the connection is already open.

A URI with the type and parameters is used to open the connection. The scheme must be:
i2c:<bus identifier>[<optional parameters>]

The first parameter must be a bus identifier, which is a logical bus name. These identifiers are bus specific.

Any additional parameters must be separated by a semi-colon (;) and spaces are not allowed in the string. If a particular optional parameter is not applicable to a particular port, the parameter MAY be ignored. The port identifier MUST NOT contain a semi-colon (;).

Legal parameters are defined by the definition of the parameters below. Illegal or unrecognized parameters cause an IllegalArgumentException. If the value of a parameter is supported by the bus, it must be honored. If the value of a parameter is not supported the system MAY substitute a valid value, which can be discovered using the corresponding get method.

Note : Now the 'delay after read' and 'delay after write' are not suppoted currently. Please don't use 'writeDelay' and 'readDelay' parameters in 'Connector.open()' function!
eg:
Don't use "Connector.open" like this :
connection = (I2cBusConnection) Connector.open("i2c:0;baudrate=" + baudrate + ";writeDelay=" + delay_write + ";readDelay=" + delay_read);
you should use it like this :
connection = (I2cBusConnection) Connector.open("i2c:0;baudrate=" + baudrate);

Optional Parameters

Parameter	Default	Description
baudrate	platform dependent	The speed of the connection
writeDelay	0	Delay after each written byte.
readDelay	0	Delay after each read byte.

[Cinterion WM ]
The current platform supports only one I2C connection, therefore the default bus identifier "'0" has to be used.

Following parameter types are required:
baudrate: 8 bit decimal value; available rates in kpbs: 100, 400; default: 400
delayWrite: 16 bit hexadecimal value
delayRead: 16 bit hexadecimal value

The OutputStream objects block the thread until all bytes have been written. The InputStream objects block 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.

BNF Format for Connector.open() string

The URI must conform to the BNF syntax specified below. If the URI does not conform to this syntax, an IllegalArgumentException is thrown.Now the 'delay after read' and 'delay after write' are not suppoted currently. Please don't use 'writeDelay' and 'readDelay' parameters in 'Connector.open()' function!

<i2c_connection_string>	::= "i2c:"<bus_id>[<options_list>] ;
<bus_id>	::= 0
<options_list>	::= *(<baud_rate_string>| <delay_after_writing>| <delay_after_reading>) ; ; if an option duplicates a previous option in the ; option list, that option overrides the previous ; one
<baud_rate_string>	::= ";baudrate="<baud_rate>
<baud_rate>	::= string of decimal digits
<delay_after_writing>	::= ";writeDelay="<delay_write> (Delay after write not supported currently)
<delay_write>	::= string of hexadecimal digits without "0x"
<delay_after_reading>	::= ";readDelay="<delay_read> (Delay after read not supported currently)
<delay_read>	::= string of hexadecimal digits without "0x"

Specifying Delay Time for I2C

The following figures are provided to assist you in specifying appropriate values for the parameters and . 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 µs at 100 kbps 2.0 µs at 400 kbps
Delay_min for Read	9.9 µs at 100 kbps 2.6 µs 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:

 i2cConnection cc = (I2cBusConnection) Connector.open("i2c:0;baudrate=100");

 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();