Example SPI test

TODO: {{#todo:Review (2.21.14-17:40->BS+);(2.24.14-13:00->MD-)(2.28.14-17:48->BS+)|Brian Serrano|oe 4,md,Review,bs}}

This is a guide to the spi_test example project included in the EMAC OE SDK.

SPI works in a master/slave setup. The master is the one that sends the clock pulses. At each pulse, data will be sent and received.

SPI is a protocol on four signal lines, it only requires three. The fourth line is only required if you have more than one device on the SPI bus; otherwise, you can hard-wire the chip select of the only device on the SPI bus so that it is always selected.

SPI has a slave select pin. Every device will share the "MISO" (Master Input Slave Output), "MOSI" (Master Output Slave Input), and "Clock" pins, but each device will have its own slave select pin (also know as chip select). This means we can have a virtually unlimited number of devices on the same SPI bus. The slave select pin can be active high or active low depending on the device.

This procedure provides an overview of how to compile and run the spi_test C example project. This is an example test interface for sending a transaction to an EMAC SPI device interface. It is only relevant if the EMAC SPI device interface is enabled for an external SPI device that is connected to the bus. It assumes familiarity with the C programming language and is intended to be used by experienced programmers who are looking to learn the EMAC SDK.

For more information about the SPI protocol, see the following page: http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus

The spi_test project builds one executable: spi_test.

Opening, Building, and Uploading the Project Files

For information on opening the project from within Eclipse, please see, Importing the EMAC OE SDK Projects with Eclipse. Then, follow Using the EMAC OE SDK Projects with Eclipse for information on how to build, upload, and execute the example.

The example is located in the path below:

developer@ldc:~$ path/to/EMAC/SDK/projects/spi

Alternatively, the Makefile can be used with the make command from the command-line to build and upload the example. For more information on this method, please see, Using EMAC OE SDK Example Projects.

Usage and Behavior

Hardware Requirements

The spi_test C example project will run on any EMAC carrier board which has an SPI interface (see also the EMAC SPI Programming page).

Using spi_test

The spi_test program is executed from the console. It takes three parameters.

root@emac-oe~:$ ./spi_test device length mosi

• device: Name of the spi device node.
• length: Length of spi transactions in bytes.
• mosi: Hex value to be transmitted in hexadecimal.

This example command was run on an EMAC SoM-150ES carrier board. Test results will be displayed in the terminal.

root@emac-oe~:$ ./spi_test /dev/mcp3208 3 CDEF
MOSI  MISO
 CD  : 00
 EF  : 01
 FF  : 04

During the SPI clock cycle, the master sends a bit on the MOSI line; the slave then reads it from that line. Next, the slave sends a bit on the MISO line; the master then reads it from that same line.

As for this example, we are using a mcp3208 device with a length of 3, and a hex value of CDEF.

root@emac-oe~:$ ./spi_test /dev/mcp3208 4 CCDD
MOSI  MISO
 CD  : 00
 EF  : 01
 FF  : AC
 FF  : 00

When using the same device but different length, and hex value, the results differ.

root@emac-oe~:$ ./spi_test /dev/mcp3208 5 EEFF
MOSI  MISO
 EE  : 00
 FF  : 00
 FF  : F8
 FF  : 00
 FF  : 00

In this third example the results change again because of the different length and hex value.

NOTE: A better description of the output is needed, along with more examples of using it. There should be at least 3-5 examples. As an example, you can see the way I demonstrated usage of the MySQL commandline on our Liferay site.

Summary

The spi_test C example project demonstrates how to use the SPI device. SPI is simply a way to send data from device to device in a serial fashion (bit by bit). SPI provide good support for communication with slow peripheral devices that are accessed intermittently. This protocol is used for things like SD memory cards, MP3 decoders, memory devices, and other high speed applications.

SPI can operate at extremely high speeds (million of bytes per second), which may be too fast for some devices. It can also achieve significantly higher data rates than I²C device or SMBus. SPI is better suited than I²C for applications that are naturally thought of as data streams (as opposed to reading and writing addressed locations in a slave device).