View source for Beginners guide to SPI on Raspberry Pi

= Introduction =
In this guide, I will show you how to get SPI up and running on a Raspberry Pi, and how to control a SPI_LCD module. We will start from scratch, with a blank SD card.



= Required hardware = 

* Raspberry Pi
* 4GB (or larger) SD card
* Power supply for your Raspberry Pi
* Ethernet cable and/or USB keyboard (network connectivity is required)
* SD-card reader

= Bitwizard hardware = 
either:
* a set of:
** [http://www.bitwizard.nl/catalog/product_info.php?products_id=69 RPi Serial Breakout board]
** [http://www.bitwizard.nl/catalog/product_info.php?products_id=90 SPI cable]
** [http://www.bitwizard.nl/catalog/product_info.php?products_id=89 SPI LCD]
* [http://www.bitwizard.nl/catalog/product_info.php?cPath=34&products_id=115 Raspberry Pi UI 16x2]
* [http://www.bitwizard.nl/catalog/product_info.php?cPath=34&products_id=123 Raspberry Pi UI 20x4]
Not necessary, but useful:
* Monitor with HDMI (or DVI and a HDMI-DVI adapter)
* HDMI cable

= Software we will be using =

* [http://www.raspberrypi.org/downloads/ The latest Raspbian "wheezy"] [http://downloads.raspberrypi.org/raspbian_latest.torrent Direct link]
* If you are using Windows: download putty.exe from [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html here]

Unpack the Raspbian image. I advise on making a separate directory for this project, and put all the files there.

= Preparing the SD card =

== Under Linux ==

First, we will flash the SD card with the Debian image. Plug your SD card in your favorite reader, and into your PC. My SD card became /dev/sdc on my laptop, your mileage may vary.<br>
Copy the image to your SD-card:
 sudo dd if=2014-06-20-wheezy-raspbian.img of=/dev/sdc
This may take some time, depending on the speed of your SD card, and card reader.

==  Under Windows ==

Download and extract [http://sourceforge.net/projects/win32diskimager/ Win32diskimager]. Connect the SD card to your computer and start Win32Diskimager. Select the drive and image and click 'Write'


= Connecting the hardware =

We recommend you have/buy the rpi_serial board. It breaks out the SPI and I2C busses of the Raspberry Pi. This allows you to use a simple straight through 4- (I2C) or 6-pin (SPI) cable to connect the Raspberry Pi to the LCD board. The cables are available from our shop as well. 

Connecting the SPI version of the board to Raspberry Pi without any interface logic is not recommended: The LCD board needs to run at 5V because the HD44780 only works at 5V. The MISO line is then driven by the board at 5V level, which is said to shorten the life of the BCM2735 significantly. 

The I2C version of the board can be wired directly to the rpi with four wires. 

If you're using SPI, please use the spi0 port for now for the purpose of this tutorial. 

For RPi UI users: simply connect the board with the gpio pins.

= First boot =

You might want to hook up your pi to a monitor, but I usually find that to much of a hassle. Hooking up your Pi to your network, however, is necessary.
Mount the RPi-serial board on your Pi, connect the SPI cable to the SPI0 port (mind the polarity!), and connect the other end of the SPI cable to your SPI_LCD module.<br>
Plug your freshly flashed SD card in your Pi, hook up power, and your Pi will boot.


The first time the RPi boots, it will boot into the Raspberry Pi Config Tool. If you have connected a keyboard, you should enable SSH under advanced settings, expand the SD card and reboot. Upon reboot, you should see a message like
 "My network IP address is 192.168.1.116" 
You could connect to the RPi using SSH (see below, recommended) or continue using the keyboard.

= Connecting to the Raspberry Pi Using SSH =
To connect the Raspberry Pi, we first need to know its IP-number. This can be found in a number of ways:
* Check your router for new devices in the network.
* Use a network scanner like Zenmap or Fing (on your smartphone)

If you figured out the IP, you can connect to the RPi:
* On Windows: start putty
* On Linux: ssh pi@IP where IP is the IP-address
The default username/password is pi/raspberry


= Installing the program = 
When connected, everything needs to be setup for interfacing with the board. We use our own bw_upgrade script:
Get the script:
 wget http://www.bitwizard.nl/software/bw_upgrade && chmod a+x bw_upgrade
Run the script (this may/will take some time):
 sudo ./bw_upgrade

And now, it's time to play! Let's try to display our first text:
 sudo bw_tool -a 94  -t 'Hello World!'
In case of I2C (check display when unsure):
 sudo bw_tool -a 94 -I  -t 'Hello World!'
If you did everything right, you now have "Hello world!" displayed on your LCD. Have a look at the [[Bw tool| the wiki page of bw_tool]], or the  [https://github.com/rewolff/bw_rpi_tools/blob/master/bw_tool/bw_tool.c source of bw_tool].

= Next steps =

The bw_lcd program can also be used to control all of our other SPI boards, using the -a, -r, and -v switches.
 sudo bw_tool -a <address of the board> -r <register> -v <value>
Let's try this with a SPI_LCD, by clearing the screen. The display is at address 82, the register is 0x10, and the value doesn't matter. Caveat: The address should be given in hex, but the register and value in decimal.
 sudo bw_tool -a 82 -r 16 -v 0
Now your display should be cleared. <br>
Note: We have written a new program, bw_tool, which is also capable of controlling our SPI boards. However, we still need to write the documentation for it. The program and sources are located in ~/bw_rpi_tools/bw_tool .

= Congratulations! =

If you managed to get everything in this how-to working, you should be able to control the entire range of BitWizard SPI boards. Good luck, and please show us your projects!

= Troubleshooting =

If you have any problems, please let us know, and we will do our best to help you resolve them. You can email us, or post your problem in our forum. We will respond as soon as we can.