Up and running on the TouchShield Stealth and Slide in 5 minutes

EDIT: Chris has posted a new version of this article that fixes a lot of the issues that we found... specifically with the AVR compiler that ships with the Arduino IDE. Check it out in the new post here.

------------------

Preamble

Chris and I have been pretty busy the past month or so, and the TouchShield Stealth (128 x 128 pixels) and TouchShield Slide (320 x 240 pixels) are now both ready for a major "firmware" upgrade. Thank you to everyone who sent back code optimizations on the graphics routines (especially Sheldon and Omar, although technically it's not fair - you're actually real game programmers). The old TouchShield ran in the low 10-15 frames per second, but with this core now runs closer to 30-40 frames per second! Also, ever since my little project a few weeks back, I've had a lot of encouraging email support from the Processing community, and with a little bit of help, now both the Stealth and Slide both run SubProcessing (a subset of the Processing language). That means that programs can be written on the Arduino, and you can literally hot swap the Stealth and Slide in real time and the program works simultaneously, and even scales the graphics accordingly... (I'll definitely take some videos later this week).

In the meantime, there are a few things that Chris and I am still working on, namely picture uploading. Although the TouchShield Stealth image uploader still works, the upgraded chip in the TouchShield Slide means that I have to rewrite the application. This time, I'm going to write it in Java so the same program works on Mac, Windows, and Linux! I'm hoping to have that wrapped up before next week. Without further ado, here we go! (and if you set a playlist to William Tell's Overture, you'll definitely be done before it completes...)

This is the new TouchShield Core, version 0.9. You can click here, and download it on the "app store." It's all GNU GPL'd.


Act 1: Overture

The first step, is to make sure you're running the latest version of the Arduino IDE application, which as of December 12th, 2008, is version 0012. You can grab the latest version over at the arduino.cc website, here.

Please install version 0012 or greater (because David and team upgraded the AVR compiler, to a more efficient version, so that now it works a lot better!). Once the file is downloaded, unzip it to a new place on your hard-drive, and proceed to step 2...


Act 2: Legato

The next step is to install the "core" files into the new installation of the Arduino IDE. This means copying the touchStealth and touchSlide folders into the following folder:

arduino-0012/hardware/cores/

After this step, (and on my hard drive), the cores folder includes 5 folders:

touchStealth/
touchSlide/
blank/
atmega8/
arduino/

Now that the folders are installed, you just need to make sure that the Arduino IDE program knows about the folders. To do this, open the following file:

arduino-0012/hardware/boards.txt

This file contains a description of all of the Arduino cores and compilers, that the IDE can recognize. At the end of this file, just add the lines below (or, you can copy over the version of the boards.txt file that I've included). Before you edit the boards.txt file, make sure that all versions of the Arduino IDE are closed, and you don't have any running on your computer. If you do, it might not save the changes to the boards.txt file correct. So just close and exit from any versions of the program you might have running, just to be safe!

##############################################################

stealth.name=TouchShield Stealth

stealth.upload.protocol=butterfly
stealth.upload.maximum_size=57342
stealth.upload.speed=57600

stealth.bootloader.low_fuses=0xFF
stealth.bootloader.high_fuses=0x98
stealth.bootloader.extended_fuses=0xFB
stealth.bootloader.path=TouchShield
stealth.bootloader.file=TouchShield_boot.hex
stealth.bootloader.unlock_bits=0xFF
stealth.bootloader.lock_bits=0xFF

stealth.build.mcu=atmega645
stealth.build.f_cpu=16000000L
stealth.build.core=touchStealth

##############################################################

slide.name=TouchShield Slide

slide.upload.protocol=butterfly
slide.upload.maximum_size=258048
slide.upload.speed=57600

slide.bootloader.low_fuses=0xFF
slide.bootloader.high_fuses=0x98
slide.bootloader.extended_fuses=0xFB
slide.bootloader.path=TouchShield
slide.bootloader.file=TouchShield_boot.hex
slide.bootloader.unlock_bits=0xFF
slide.bootloader.lock_bits=0xFF

slide.build.mcu=atmega2560
slide.build.f_cpu=16000000L
slide.build.core=touchSlide

##############################################################

Now, you're ready to move onto step 3!



Act 3: Autumn

The TouchShield Stealth and TouchShield Slide communicate with the Arduino using pins 2 and 3. That means it uses Software Serial, not the built-in hardware serial. In order to get Software Serial working properly, then, we're going to copy over the AFSoftSerial libraries into the appropriate location (thanks Limor!). While we're at it, we're also going to copy over the library Chris and I've written to display large numbers on the screen, in case you want to play around and make big timers or countdown clocks...

Just go to the folder:

arduino-0012/hardware/libraries

Now copy into this folder the two folders, touchLargeNums and AFSoftSerial.

On my computer, the libraries folder now has 12 folders in it:

Stepper/
Sprite/
SoftwareSerial/
Servo/
Matrix/
LiquidCrystal/
Firmata/
Ethernet/
EEPROM/
AFSoftSerial/
touchLargeNums/
Wire/

Voila!

Now, ready to move onto step 4...


Act 4: Allegro Moderato

You open the door. You walk through the door, you roll a die. A dwarf appears. Press 1 to use your magic wand. Press 2 to cast a spell. Press 3 to.... Ok, now it's time to boot everything up!

Open the newly installed and upgraded version of the Arduino IDE. This is the file in the arduino-0012/ folder called "arduino.exe" or "arduino", depending on what operating system you're using.

Place the TouchShield Stealth or TouchShield Slide on top of the Arduino. If this is the first time you're connecting your Arduino to your computer, you'll want to make sure you also install the FTDI drivers. The guys at arduino.cc have great tutorials for installing the drivers properly, over here:

http://arduino.cc/en/Guide/Windows
http://arduino.cc/en/Guide/MacOSX
http://www.arduino.cc/playground/Learning/Linux

Once the drivers are installed, or if you've already installed them before, connect the Arduino to the computer using a USB cable.

The Arduino IDE will take a few seconds, and then it will recognize the Arduino. The next step is to program the TouchShield and the Arduino with the appropriate programs. The TouchShield will run the SubProcessing library, which is a little version of the Processing Graphics library, written just for the TouchShield. From now on, any program written for the TouchShield Stealth will work on the Slide and vice versa, as well as being cross-compatible with any version of Processing you might have installed on your computer. This means I can prototype graphics on my PC, and then flash it down to the Arduino, and it'll look the same!

So the first step is to program the TouchShield. From December 18th, 2008 and onward, every TouchShield that gets mailed out will come pre-loaded with the latest version of the SubProcessing software as of that date, so if this is the first time you're using it, you can skip this step. Otherwise, continue to update the TouchShield's firmware:

Open up the TouchShield.txt file. It contains a small little program that puts the TouchShield into "canvas" mode. This means it sits there, waiting for display commands from the Arduino. That code looks like this:


void setup(void) {

}

void loop(void) {
beginCanvas();
}


Copy and paste this code into the Arduino IDE main window. Then, select the appropriate Serial port from the Tools->Serial Port menu. On my computer, it's serial port 18. Then, select the right board from the Tools->Board menu (either TouchShield Stealth or TouchShield Slide).

Click the compile (or play) button to compile the code. Now, press the reset button on the TouchShield. On the Stealth and the Slide, it's the button right next to the USB connector on the Arduino. This puts the TouchShield into reset mode, waiting for a program from the Arduino IDE.

Now press the program button, or "upload to I/O board". The LEDs will blink as the program is downloaded to the board, and then it'll finish. Done!

The final step is to load a program onto the Arduino.

Open the Arduino.txt file, and copy and paste this into a new program in the Arduino IDE window. Now, select "Arduino" from the Tools->Boards menu. Press play to compile, and then press the "upload to IO board" button to send the program to the Arduino. Done!

In about a second or two, the Arduino will reset, and will start sending commands to the TouchShield. The program is pretty simple, it just displays a little red square that you can drag around the screen. If you happen to have a Slide and a Stealth, you can hot-swap the two shields one after the other, and they'll both start displaying whatever the Arduino sends to them. In some cases, it might help to cycle the power on the Arduino and TouchShield, by reseting or re-plugging in the USB or Lithium Backpack.

If you have any questions, or want any help writing some code, or if anything at all doesn't work, or if you're just looking for someone to bounce ideas or talk to, just drop me an email!

Matt and Chris
(and Limor and Sheldon and Omar - thanks!)