Example SPI test

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

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

SPI (Serial Peripheral Interface) is a synchronous full duplex serial data communication standard used to interface many types of memory and I/O devices. SPI requires four lines per slave device connection, three of which are shared across the SPI bus. MISO, MOSI and SCLK are the three shared bus lines and chip selects (CSn) are used to determine which device is the target for communication.

NOTE: This isn't exactly true. SPI only requires 3 lines, not 4. The 4th line is only required if you have more than one device on the SPI bus; otherwise, you can hard-wire the CS of the only device on the SPI bus so that it is always selected. Additionally, it's not 4 per device from the host processor, because people typically use tricks to reduce the number of lines from the host processor required for the CSn lines. For example, a 1:2 multiplexer can be used to select device A when the input line is low or device B when the input line is high. Similarly, a 2:4 multiplexer can be used to select among 4 devices. With more than 4 devices, an I²C device can often be used which will supply (typically) 8-16 GPIO lines which can be used to feed the chip select lines of the SPI devices while only requiring 2 lines from the host processor. This means that it's usually possible to get away with using no more than 5 lines in total from the host processor. Since the number of lines required from the host processor is generally what people are most concerned about, because these are the most difficult to come by, the above paragraph should be reworded to clarify this. The SPI Programming page has been marked for revision due to this issue as well.

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.

NOTE: It would be a good idea to point them to the directory which contains this example project in addition to referring them to these generic pages.

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.

NOTE: In cases like above, be sure to put argument names inside code tags. I added them in this bullet list for you. Generally, if a word is typed on the command line or a keyword in output, put it inside code tags to indicate that the exact word, as shown, is important.

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 1 12

MOSI  MISO
 12  : 00

After running the ./spi_test /devmcp3208 1 12 command, the program displays MOSI in hexadecimal and then outputs MISO.

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 enables the serial exchange of data between two devices, one called a master and the other called a slave. It operates in full duplex mode.

NOTE: There can be more than one slave per master, so the second sentence needs rewording. Common uses would be good to include here. Speeds would be good to note, as well as benefits of SPI over I²C/SMBus.