readme.txt

LCD using AVR controller

This file is part of a ZIP archive that was downloaded from
<http://www.idleloop.com/robotics/ColorLCD/>

The code provided here comes with no warranty or support.
It is distributed under the GNU General Public License.
See GNU-GPL.txt or http://www.gnu.org/copyleft/gpl.html for details.

This sample code is designed to work on Spark Fun's Nokia-like graphic
color LCD.

=== wiring ===

I had the best results when using a 3.3V supply for VCC-Digital and VCC-Display,
with a separate (6-7V) supply and current-limiting resistor for LED V+ (I used
a 5-pack of NiMH with a 68 Ohm resistor for LED V+ and a voltage regulator for
the 3.3V supply). I also used a 33kOhm pull-up resistor on the CS (chip select)
line to ensure that it would be disabled during AVR programming.

For control lines, the important thing is that SDATA and SCLK are connected to
the MOSI and SCK outputs (from SPI). Other lines can be changed (but do of course
require a corresponding code change).

Wiring for the control lines is as follows:

 LCD           ATmega16/32/644   ATmega128
 -----------   ---------------   ------------
 CS            PC0               PC0
 RESET (RST)   PA7               PA7
 SDATA         PB5 (MOSI)        PB2 (MOSI) *
 SCLK          PB7 (SCK)         PB1 (SCK) *

 (pushbutton)  PB3               PB3         optional; connect between pin and GND

 * Note: if using pins other than in the mega16/32/644 column, you'll need to
   update the code as well! (See the "globals" section at the top of main.cpp.)

=== LCD calibration ===

The LCD has an LED backlight with a brightness controlled in software.
In main.cpp, the function VolumeExperiment is designed to help you determine
the best setting for your system (based on voltage applied to LED V+ and
variation between LCDs). See the comment by the function (and sample call
from main) for details.

=== building ===

This code was compiled with WinAVR-20060421 (which uses avr-gcc), and was
tested on an ATmega644. It should also work on the ATmega16, ATmega32,
and ATmega128.

If you are using something other than an ATmega644, make the following changes
in "makefile"
  - set MCU_TARGET (list options with: avr-gcc --target-help)
  - set AVRDUDE_PART (list options with: avrdude -c avrisp)
  - update the "setfuse" rule

Typing "make" with no arguments will build the program.
There are a couple useful arguments you can specify:
  - make setfuse -- this will program the fuse bits; be sure to update the
      setfuse rule in the makefile to use appropriate values for your controller!
  - make program -- this will download your program using AVRDUDE; see the
      comment at the top of makefile for details

=== code ===

The code is in the AVRcode folder. Highlights...

* main.cpp -- contains declarations of variables corresponding to wiring,
  and contains main() function. The default program will cycle through
  several screens. There is also code to help pick a value for screen
  "volume" (brightness).
* Config.h -- this file contains defined values to control what features
  are included by various .cpp files.
* Bitmaps.cpp/h -- these files contain the information for the bitmaps
  shown in the sample code. (See the "utilities" section below for details
  on how to generate this info for your images!)

The "library" code is generally unchanged for different applications, so
these files are in a separate "lib" folder. The most interesting ones for
this project are:

* lib/LCD-color.h -- look at the functions (and corresponding comments)
  to see what the LCD can do! (Examples of using these functions are
  in main.cpp.)
* lib/Fonts.h -- the header comment lists the fonts available; add
  #define values in Config.h to include fonts in your program. (See the
  "utilities" section below for details on creating your own fonts!)

=== utilities ===

There are two programs in the "util" folder:
* lcdphoto   -- generates a byte array from a picture
* fontmunger -- generates code for a font drawn in a bitmap
They are designed to be run from the command line. Run with no
arguments to see the usage information. These programs are described
below.

To create a picture for the LCD:
  + In Abode Photoshop:
    - Set the Image Mode to (8-bit) RGB.
    - Crop and resize as necessary so picture is a maximum of 130 pixels
      in either dimension.
    - File/Save As, Format = Photoshop Raw, interleaved (header 0 bytes).
    - Remember the number of pixels for width and height.
  + Run lcdphoto (in the util folder); usage:
       lcdphoto (width) (height) (filename)
    The output will go to the command window. It's convenient to redirect
    it to a file. Example:
       lcdphoto 50 76 giraffe.raw > giraffe.txt
    This specifies that giraffe.raw contains the image data for a picture
    that is 50 pixels wide by 76 pixels high, and redirects the output to
    a file called giraffe.txt.
  + Copy the output from lcdphoto into Bitmaps.cpp (use the existing code
    as an example).
  + Add a declaration in Bitmaps.h (using existing code as an example).

To create a new font for the LCD:
  + In Abode Photoshop:
    - Set the Image Mode to Indexed Color. Indices are used as follows:
      ~ 0: background (e.g. white)
      ~ 1: font pixels (e.g. black)
      ~ 2: gridlines (e.g. red)
      ~ 3: baseline (e.g. blue)
    - Use the PSD files in the util/fontmunger/fonts folder as examples
      (e.g. FontGrid-5x9.psd).
    - Draw gridlines to create "cells" for the characters. All characters
      must be the same height; they can be different widths.
    - Draw characters in the cells.
    - The first cell is assumed to correspond to space (ASCII 0x20)
      ~ The cell height determines the height used for all characters.
      ~ A horizontal blue line specifies the baseline (lowest pixel
        for capital letters), which determines the ascent and descent
        for the font.
    - Each subsequent cell corresponds to the next ASCII value. Leave cells
      blank for characters that aren't defined. You can stop when there are
      no more characters (there's no assumption about the last character
      defined).
    - For monospace fonts, the width of the space defines the width of
      all characters; they must match or will be truncated.
    - For proportional fonts, the width of the "0" (zero) character cell
      defines the width for all numbers.
    - For proportional fonts, whitespace will be trimmed on BOTH sides,
      except for space and numbers.
    - The right edges of the last character in each row must line up. So,
      make the last character wider as necessary (it will be trimmed as
      appropriate). (See FontGrid-3x5.psd for an example.)
    - File/Save As, Format = Photoshop Raw, interleaved (header 0 bytes).
  + Run fontmunger (in the util folder); usage:
       fontmunger <file> [mono]
    The text "mono" is optional and specifies to create a monospace font;
    if omitted, a proportional font is created. The output will go to the
    command window. It's convenient to redirect it to a file. Examples:
       fontmunger 5x9.raw > 5x9.txt
       fontmunger 5x9.raw mono > 5x9Mono.txt
    The first example specifies that 5x9.raw should be used to generate
    a proportional font set, and saves the generated code to 5x9.txt.
    The second example uses the same file, but interprets it for a
    monospace font set.
  + Copy the generated file (e.g. 5x9.txt) to the lib folder (in AVRcode).
  + Add code for your new font to the end of Fonts.cpp (using the existing
    code as an example).
  + Add a declaration at the end of Fonts.h (using existing code as an example).