com.cinterion.io

Interface SpiConnection

All Superinterfaces:

Connection, InputConnection, OutputConnection, StreamConnection

public interface SpiConnection
extends StreamConnection

This interface defines a logical connection to an SPI device.

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

Only one application may be connected to a particular SPI device at a given time. An java.io.IOException is thrown, if an attempt is made to open the SPI device 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:
SPI:<device identifier>;[<optional parameters>]

The first parameter must be a device identifier, which is a logical device name. These identifiers are device 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 device, the parameter MAY be ignored. The device 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 device, 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.

Optional Parameters

Parameter	Default	Description
baudrate	platform dependent	The speed of the connection
clockMode	0	Mode of the SPI clock.

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

Following parameter types are required:
baudrate: 8 bit decimal value; available rates in kpbs: 100, 250, 500, 1083, 3250, 6500; default: 100
clockMode: 8 bit decimal value; available SPI clock modes: 0, 1 ,2 and 3

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 SPI device 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.

<spi_connection_string>	::= "spi:"<device_id>[<options_list>] ;
<device_id>	::= 0
<options_list>	::= *(<baud_rate_string>| <spi_clock_mode>) ; ; 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
<spi_clock_mode>	::= ";clockMode="<clock_mode>
<clock_mode>	::= string of decimal digits

Selecting SPI Mode

The figure shows the four types of the SPI clock mode selectable by setting the appropriate hexadecimal value within the parameter clockMode.

Transmitting Data

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

ASCII Protocol for SPI 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
aplication -> device	Start Transfer Message	<	0x3C	Special character sent to the SPI device to start sending
aplication -> device	Stop Transfer Message	>	0x3E	Special character sent to the SPI device to stop sending.
device -> aplication	Start Response Message	{	0x7B	Special character sent to the SPI aplication to mark the beginning of a response message
device -> aplication	Stop Response Message	}	0x7D	Special character sent to the SPI aplication to mark the end of a response message
device -> aplication	Protocol error	!	0x21	Reports to the SPI aplication that the transfer frame does not comply with the protocol definition (syntax error).
device -> aplication	Transmission OK	+	0x2B	Notifies the SPI aplication: data were successfully transmitted the SPI slave address was recognized.

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 SPI this applies to the Read Offset Byte and the Read Length and, if available, all 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 SPI 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 SPI device driver), i.e. it is not sent to the SPI 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 SPI 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 SPI Bus:

Frame	Format
Transfer Message	<_ID ReadOffset ReadLength Data > Read Offset = 8 bits Read Length = 16 bitss Max. read length of data is 2048 bytes(2KB)
Response Message Write OK Reading x bytes OK Protocol error in xth byte	{ID +} {ID + _Data} {ID ! _xxxx}

The SPI has two serial data lines, DO (I2CDAT_SPIDO) for sending data from the master to the slave, and DI (SPIDI) for receiving data sent from the slave to the master. Both data lines are controlled by one serial clock line CLK (I2CCLK_SPICLK). The module acts as master providing the clock. Write and read data are handled in the same Transfer Messages and Response Messages. In a Transfer Message, the next two elements after the ID are the Read Offset and the Read Length, both required to enable reading data from the slave. The Read Offset specifies where to start reading, i.e. which byte is the first to start reading from. If the Read Offset is zero then reading starts from the first byte. The Read Length specifies the number of expected bytes. If the Read Offset is zero and the Read Length does not equal zero, the master reads the specified number of bytes, starting from the first byte. If the Read Length is zero, the Read Offset is ignored, meaning that the master will not read data from the slave. To transmit data from the master to the slave all data can be entered after the Read Length.

In a Response Message the ID is followed by a special character to indicate the result of reading. If successful, "+" is given, followed by the read data. If reading fails only "!" is received.

Error Handling on the SPI Bus

Protocol error:
If a protocol error is detected the ASCII value "!" is sent in the driver response. Also, a Stop Condition is sent to the SPI 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 SPI 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 SPI device notifies that it has recognized the SPI address.

Example

The following example shows how a SpiConnection shall be used to access a SPI device.

Open SPI connection and data streams:

 spiConnection cc = (SpiConnection) Connector.open("spi:0;baudrate=100;clockMode=1");

 int baudrate = cc.getBaudRate();
 InputStream inStream  = cc.openInputStream();
 OutputStream outStream = cc.openOutputStream();
 

Write Transfer Frame, where a = message ID followed by the corresponding command of the SPI device:

 String data = "<a...>";
 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();