Skip Headers
Oracle® Java ME Embedded Device Access API Guide
Release 3.3
E35134-02
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

12 Serial Peripheral Interface Bus

This package provides interfaces and classes for SPI (Serial Peripheral Interface Bus) device access.

The Serial Peripheral Interface (SPI) bus is a synchronous serial data link standard that operates in full duplex mode. Devices communicate in master or slave mode, where the master device initiates the communication data frame. Multiple slave devices are allowed with individual slave select lines.

The functionalities supported by this API are those of an SPI master. In order to communicate with a specific slave, an application should first open and obtain an SPIDevice instance for the SPI slave device the application wants to exchange data with, using its numerical ID, name, type (interface), or properties. The following example demonstrates how to obtain an SPI device using its ID.

 SPIDevice slave = (SPIDevice) PeripheralManager.open(3);
 

This example demonstrates how to access a device using its name and interface.

  SPIDevice slave = (SPIDevice) PeripheralManager.open("RTC1",
      SPIDevice.class, null); 

Once the peripheral opened, the application can exchange data with the SPI slave device using methods of the SPIDevice interface such as the writeAndRead() method.

 slave.writeAndRead(sndBuf, 0, 1, rcvBuf, 0, 1);
 

When the data exchange is over, the application should call the Peripheral.close() method to release the SPI slave device.

 slave.close();
 

Example 12-1 shows how to use the SPI API to communicate with SPI slaves.

Example 12-1 Using the SPI APIs to Communicate with SPI Slaves

import com.oracle.deviceaccess.PeripheralException;
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.spibus.SPIDevice;
import java.io.IOException;
 
public class SPIExample {
 
    SPIDevice slave = null;
 
    public SPIExample() {
        try {
            slave = (SPIDevice) PeripheralManager.open("SPI1",
                SPIDevice.class, (String[]) null);
            byte[] sndBuf1 = {0x01};
            byte[] sndBuf2 = {0x02};
            byte[] rcvBuf = new byte[3];
            slave.writeAndRead(sndBuf1, 0, sndBuf1.length, rcvBuf, 0, 1);
                // received data will be stored in rcvBuf[0]
            slave.writeAndRead(sndBuf2, 0, sndBuf2.length, rcvBuf, 1, 2);
                // received data will be stored in rcvBuf[1] and rcvBuf[2]

        } catch (PeripheralException pe) {
            // Handle exception
        } catch (IOException ioe) {
            // Handle exception
        } finally {
            if (slave != null) {
                try {
                    slave.close();
                } catch (IOException ex) {
                }
            }
        }
    }
}

Information about the SPI-bus specification can be found at http://www.freescale.com/files/microcontrollers/doc/ref_manual/M68HC11RM.pdf.

SPI slave devices are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open() methods. The com.oracle.deviceaccess.spi permission allows access to be granted to SPI slave devices as a whole. This permission must be requested in the JAD file under MIDlet-Permissions or MIDlet-Permissions-Opt, and the application must be digitally signed by a trusted authority to gain access to the APIs. Alternatively, the permission may be allowed for all applications in the untrusted domain of the security policy file (policy.txt).

The SPIDevice Interface

The SPIDevice interface provides methods for transmitting and receiving data to and from an SPI slave device. Each SPI slave device is identified by a numerical ID and by a name.

An SPIDevice instance can be opened by a call to one of the PeripheralManager.open() methods. On an SPI bus, data is transferred between the SPI master device and an SPI slave device in full duplex. That is, data is transmitted by the SPI master to the SPI slave device at the same time data is received from the SPI slave device by the SPI master.

To perform such a bidirectional exchange of data with an SPI slave device, an application may use one of the writeAndRead() methods. When an application only wants to send data to or receive data from an SPI slave device, it may use a write() or read() method, respectively. When writing only, the data received from the SPI slave device will be ignored and discarded. When reading only, dummy data will be sent to the slave.

A data exchange consists of words of a certain length which may vary from one SPI slave device to another. Words in the sending and receiving byte buffers are not packed bit-wise and must be byte-aligned. The most significant bits of a word are stored at the lower index (first). If a word's bit length is not a multiple of eight, then the most significant bits will be undefined when receiving or unused when sending. If the designated portion of a sending or receiving byte buffer cannot contain a positive integral number of words then an InvalidWordLengthException is thrown. For example, if the word length is 16 bits and the designated portion of buffer is only 1-byte long or 3-bytes long, an InvalidWordLengthException is thrown.

Assuming a word length w, the length l of the designated portion of the sending or receiving byte buffer must be such that:

((l % (((w - 1) / 8) + 1)) == 0)

When the data exchange is over, an application should call the SPIDevice.close() method to release the SPI slave device. Any attempt to read or write to an SPI slave device which has been closed will thow a PeripheralNotAvailableException.

The following methods are contained in the SPIDevice interface.

The SPIDeviceConfig Class

The SPIDeviceConfig class encapsulates the configuration parameters of an SPI slave device.

Each SPI slave device has a clock mode. The clock mode is a number from 0 to 3 which represents the combination of the CPOL (SPI Clock Polarity Bit) and CPHA (SPI Clock Phase Bit) signals, where CPOL is the high order bit and CPHA is the low order bit, as shown in Table 12-1.

Table 12-1 Clock Modes in the SPIDeviceConfig Class

Mode CPOL CPHA

0

0 = Active-high clocks selected.

0 = Sampling of data occurs at odd edges of the SCK clock

1

0 = Active-high clocks selected.

1 = Sampling of data occurs at even edges of the SCK clock

2

1 = Active-low clocks selected.

0 = Sampling of data occurs at odd edges of the SCK clock

3

1 = Active-low clocks selected.

1 = Sampling of data occurs at even edges of the SCK clock


An instance of SPIDeviceConfig can be passed to the PeripheralManager.open(PeripheralConfig) method to open the designated SPI slave device with the specified configuration.

The SPIDeviceConfig class consists of one constructor and the following methods

InvalidWordLengthException

The InvalidWordLengthException is thrown by an instance of SPIDevice in case of mismatch between the length of data to be exchanged and the slave's word length as indicated by SPIDevice.getWordLength().