Software we will be using

Unpack the Raspbian image, and download the script. I advise on making a seperate 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 favourite reader, and into your PC. My SD card became /dev/sdc on my laptop, your mileage may vary.
Copy the image to your SD-card:

sudo dd if=debian6-19-04-2012.img of=/dev/sdc

This may take some time, depending on the speed of your SD card, and card reader.

Next, we need to move the modified kernel image and modules to the freshly flashed SD card. For this, you need to mount the partitions on your SD card. Im lazy, and just unplug my card reader, and plug it back in. Ubuntu then automagically mounts the two relevant partitions.
You will see a small (56MB) partition (mounted as /media/1AF7-904A on my system), which is the /boot partition/directory. You will also see a larger (approx 1.7GB) partition, containing all other data (mounted as /media/8fe3c9ad-c8f5-4b39-aec2-f6e8dba743e0 on my system). You may need to change the target directory in the following commands.

Under Windows

Will be written ASAP.

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.

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.
Plug your freshly flashed SD card in your Pi, hook up power, and your Pi will boot.

Playing time

SSH into your Pi. If you have a monitor attached, your Pi will tell you it's IP address: "My network IP address is 192.168.1.116" (or an other IP of course). If you don't have a monitor attached, you need to check your routers logs to find out which IP your Pi has.
SSH into your pi:

ssh 192.168.1.116 -l pi

The default password is "raspberry"

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_rpi_tools/bw_spi/bw_lcd -T 0,0 'Hello World!'

If you did everything right, you now have "Hello world!" displayed on your LCD. Have a look at the source of bw_lcd, or its Raspberry_Pi_LCD_program manual for other options.

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_lcd -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_lcd -a 82 -r 16 -v 0

Now your display should be cleared.
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 howto 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.