(Image © Electronic Assembly, lcd-module.de)

The tutorial follows the same path I took whilst developing a simple library for a screen I had bought. I set myself the challenge of doing this from scratch, rather than using code from the internet.

Whilst this post uses a 128×64 screen as an example it is equally applicable to different sizes.

Pros:

• Easy to interface using fewer pins than other graphic LCDs
• Onboard voltage booster for the liquid crystal display
• Software controlled contrast and rotation
• Works at faster clock speeds
• Good selection of backlight colours

Cons:

• 3.3v logic only (not such a problem any more)
• In SPI mode a large buffer is required in local memory

Getting started

The most important thing needed when developing a library is a good datasheet. The information provided by screen manufacturers is often lacking in detail or quality.  The datasheet I used can be found here.

Basic operation (hardware)

The most basic pinout for the ST7565 is shown below.  To drive it from a microcontroller in SPI mode 5 pins are required.  All of these pins are outputs from the microcontroller and inputs to the screen.  Because it is not possible to read from the screen there is no requirement for inputs.

It is necessary to connect RESET to the microcontroller as the initialisation procedure involves toggling this pin.  This pin should not be tied high or low or it may not be possible to reset the screen correctly.

Depending on your GLCD module it may be necessary to connect a number of capacitors, this is discussed in the next section.

Voltage boosting and regulation

The ST7565 has an integrated voltage booster (charge pump) circuit that can provide the high voltages needed by the liquid crystal display. If the circuit only has a single supply such as 3.3v then the charge pump is the easiest way to power the screen. If the circuit contains a voltage source of between 9v and 12v then it is possible to reduce the number of external components needed by using this directly.

The internal booster can provide from 2x to 6x the input voltage depending on how capacitors are connected between the CAPxx terminals. Full details are provided on page 31 to 34 of the datasheet above. The only limitation is that the maximum voltage after boosting must not exceed Vout, which is 13.5v.

Many LCD specific datasheets will provide the exact capacitors required for a particular model. For some display modules these capacitors are included on the circuit board and do not need to be added.  Check the datasheet carefully!  For example, the image below is taken from the datasheet for an inexpensive model available from Mouser, the EA DOGM132-5:

(© Electronic Assembly, lcd-module.de)

In addition to the voltage booster the ST7565 contains an integrated voltage regulator. This has 8 steps and regulates the reference voltage used to drive the liquid crystal display. It is necessary to find a value between 0 and 7 which works well with the specific hardware as this is used with the dynamic contrast feature.  Typically a “middle” value such as 3 will work with any screen.

Basic operation (software)

SPI mode provides an easy mechanism to drive the screen using few pins.  A single bit is written to the data pin and the clock is pulsed high then low.  The implementation of SPI by the ST7565 is fairly standard, more information can be found on the Wikipedia SPI Bus page.

One limitation of using the screen in SPI mode is that it only supports writing commands or data. It is not possible to read from the screen therefore it is necessary to keep a copy of the current screen data in memory on the microcontroller. The size of this software buffer can be calculated easily, there are 128 columns and 64 rows for a total of 8192 bits (1 bit per pixel for black and white). Therefore 1024 bytes in total are required to store a copy of the screen, which can be a large amount on many smaller microcontrollers.

With software (‘bit banged’) SPI it is possible to use the screen at very fast clock speeds. On an PIC 18F I have used my screen with a 64Mhz internal oscillator and it works absolutely fine. It is possible to calculate (or simulate/measure) whether the microcontroller can exceed the ST7565 minimum clock period.

Screen layout

Unlike displays using the KS0108 the ST7565 has a single controller for the whole screen. There is no need to swap between the left and right in order to send commands.

A 128×64 screen is made up of 8 pages, each of which is 8 pixels high and 132 wide. This maps nicely to the software buffer required for caching the screen contents because each page is a byte high.

It is easiest to imagine the top left of the screen as 0,0 and the bottom right as 127,63. This makes some of the maths required in software much easier.  To write data at (0,0) it is necessary to select page 0, column 0 and then set the individual bit.  In contrast the location (32,32) is in page 5.  The simplest method of writing data to the screen is to send a whole page at a time, starting from the left in column 0 and continuining to the right at column 127.

Sending a command to the screen

Issuing a single command to the screen is the most basic building block of the interface code.  The steps required are:

• Set the A0 pin low to indicate that command data is being sent
• Set the chip select (CS) pin low
• Send each bit of the command, starting with the most significant bit and working down to the least significant
• Set the chip select (CS) pin high, to free the bus

Therefore the “display on” command (which is 0xAF or 0b10101111) should be sent as: 1, 0, 1, 0, 1, 1, 1, 1.

As long as the SPI timings are not violated there is no need to introduce any delays as the screen will never be “busy”.

Screen initialisation

Now that we can send a single command to we need to follow a number of steps to setup the screen.

• Strobe the RESET pin low then high, to initiate a hardware reset
• Setup the duty cycle (either 1/7 or 1/9) depending on the physical LCD
• Set the horizontal and vertical orientation to a known state
• Configure the internal resistor divider which is used by the voltage regulator
• Turn on the internal voltage booster to provide power to the LCD glass
• Initialise the dynamic contrast to a default value
• Reset the current display position to the top left

The commands for these are a single byte except the dynamic contrast, which is explained later.  Below is an image captured from a logic analyser while the initialisation code runs.

In this trace the following things can be seen:

• Command 0xA2: set the LCD bias to 1/9th
• Command 0xA0: horizontally “normal” (not flipped)
• Command 0xC8: vertically “flipped” (complements the command above)
• Command 0×23: the internal resistor divider set to 3 (from 0..7)
• Command 0x2F: power control, all internal blocks ON
• Command 0×81: enter dynamic contrast mode
• Data for the dynamic contrast mode, set to 31 (from 0..63)
• Command 0×40: go back to the top left of the display

When power is first applied to the screen it is also important to clear the onboard screen memory. As it is non-volatile RAM it will start in an unknown state.

Sending data to the screen

The only difference between sending a command and data is the A0 pin.  When sending data the A0 pin must be high to differentiate

To start we send a command to reset the position to the top left corner (0,0). After this a quick trick is to write a single byte and see how it is displayed. It is important to know which way round the screen will display the data it receives, whether the “most significant bit” or “least significant bit” is displayed at the top.  The illustration below shows the output if the byte 0×80 is sent four times to the screen:

From this it can be seen that the most significant bit displays at the bottom of the page.  That is the first bit we send is at the bottom, then subsequent bits work upwards toward the top of the page.  This will be important later when we try to set an individual pixel.

Displaying a basic test pattern

The easiest way to test if the driver code is working is to send a very basic test pattern. A quick check is to send constant bytes of 0xFF to fill the screen. If this works then variations can be tried, such as 0xF0 or 0xAA.

At the end of each row, after every 128 bytes, it is necessary to select the next page and move to the start of the row.  The following image is the basic test card I used to demonstrate that my display was wired up correctly.

Writing to specific pixels

Writing specific pixels opens up a whole world of possibilities from lines, circles, 1 bit-per-pixel graphics and variable height fonts. As these graphics functions are not dependant on a specific controller or screen it is best to split them out into a separate library which is portable across any screen.  This is perhaps the most difficult portion whilst developing a library to work with any screen.

In order to set a specific pixel it is necessary to break the process into a number of steps:

•  Find the corresponding byte in the software buffer
• Calculate the bit within this byte
• Use logical XOR (to set the bit) or AND (to clear the bit)

Finding the correct byte is straightforward.  The first position in our array is at the top left of the screen.  The 128th byte in the array (Array[127]) is on the first page at the right hand side of the screen.  The next bit “wraps” to the next page, at page 1 column 1.

To calculate which byte we need to use we need to divide the Y position by 8 and multiple the result by 128.  To this we add the X position, then subtract 1 (as C arrays start from 0).  The equation X + ( ( Y / 8 ) * 128 ) – 1 works well in C.  To verify this is correct:

• (1,1) on the screen would give 1 + ( 1 / 8 ) * 128 – 1 = 0
• (61,52) on the screen would give 61 + ( 52 / 8 ) * 128 – 1 = 828

To calculate the bit inside this byte we must remember that the 8th (most significant) bit appears at the bottom of the page.  So to write to Y location 8 we need to set the 8th bit of a byte on the first page.  To write to Y location 16 we need to write to the 8th bit of the corresponding byte on the second page.  Therefore we need the remainder after the Y position is divided by 8, which can be found using the modulo operator.  This is as simple as Y % 8:

• (1,1) means setting 1 % 8 = the 1st bit
• (61,49) means setting 49 % 8 = the 1st bit
• (61,53) means setting 53 % 8 = the 5th bit

It is now possible to set the correct bit inside the byte, on PIC microcontrollers this can be achieved using very efficient bit operators such as bsf or bcf.

Displaying text

Like many other graphic LCDs the ST7565 has no built-in font.  The quickest & easiest way of displaying text on this screen is to define an 8 pixel high font. This maps directly to one page (or ‘line’) of the display and therefore we can use very fast instructions to copy the data from a predefined font to the right area of the screen.

However this limits us to a fixed height and only 8 lines of the screen. Now that we know how to set individual pixels there are much nicer ways of displaying text. Consider the following image:

Larger fonts take up more room but can be used to provide a much nicer looking user interface for a project.  With the knowledge that we can set a specific pixel it is easy to make advanced graphics functions.  However these are separate to the ST7565 screen itself, so I will cover them in a future blog post.  Impatient readers can check my graphics library (Doxygen documentation can be found here).

Using advanced features

So far all of the features are common to all standard graphic LCDs. However there are a number of additional tricks that ST7565 based displays can offer.

Inverting the screen

With a single command the ST7565 can be instructed to invert the display.  This can be useful for emphasis or to make the screen easier to read in certain situations.  The command “display normal or reverse” is 0b1010011X, where X is 1 for reversed or 0 for normal.

The picture below shows the same font demonstration as above, but with the inverse feature turned on.

Blacking the screen

The ST7565 is capable of setting all points on the display to black without affecting the screen RAM.  Whilst it is hard to think of a situation where this might be useful the command “display all points” is a single byte and can be used to turn the display black if required.

Dynamic contrast control

Unlike other common graphic LCDs the contrast for the ST7565 is set by an internal resistor divider. This means that it can be set in software and altered dynamically. To change the contrast we need to send two commands. The first enters “volume mode set” and the second sets the contrast from 0..63.

The number of useful steps may be less than 64, on my test screen the visible steps are from 12 (very light) to 40 (very dark). Lower values are not visible as the voltage is too low, higher values make the screen completely black as there is no distinction between pixels which are off or on.

This feature could be used with a light sensor to dim the screen depending on ambient conditions. It can also be used to fade the screen in or out.

Screen rotation and mirroring

In the same way that the screen can be inverted without affecting the display data it is possible to flip the screen in either the horizontal or vertical direction.  This means that the screen can be used either way up with no changes required to the software except sending extra two commands to the screen.

Flipping the screen horizontally (from left to right) is achieved with the confusingly named “ADC Select” command.  Flipping the screen vertically (from top to bottom) is possible with the “COM Output Mode Select” command.  Unless you want to view the screen in a mirror it is necessary to use both commands at once!

As mentioned earlier the memory on the screen is actually 132 columns wide, to support a maximum screen size of 132×64.  On 128 pixel wide models there is an important consideration if rotating the display.  If the screen is not rotated as the extra 4 rows are on the right hand side and not visible, as illustrated below:

When the screen is rotated the controller outputs these columns in the opposite order, starting with the last column.  Therefore the unused 4 columns from the screen memory are output first, leaving an empty space on the left hand side.

In order fix this it is necessary to keep track in software of whether the screen is rotated or not.  When it is rotated the column address should be incremented by 4 each time a new line is sent to the screen, skipping the extra columns which would otherwise be displayed.

Improving efficiency

Refreshing the screen involves sending the entire local buffer to the screen RAM. If only a few changes have been made then this is a very inefficient way to update the screen.

It would be possible to send each individual write to the screen, simply by copying the single byte that has changed each time a pixel is written. However this is inefficient if more than a single bit (or pixel) is set in the same byte in subsequent operations. Changes to the screen would also be very visible at slower speeds.

As the screen has 8 pages the most efficient method on a small microcontroller is to send only the pages which have changed. Each time a pixel is set or cleared the corresponding page in the local buffer is marked as ‘dirty’. When it comes to refreshing the screen only the dirty pages are transferred.

In the example above only pages 2 and 5 have had changes made.  Therefore these will be sent to the screen, which takes 1/4 of the time as sending all 8 pages.

The screen could be subdivided into even smaller regions, for example 16 half pages. The trade-off of extra code each time a pixel is set and the reduced bus time sending data should be considered carefully.

Verifying speeds

Above I commented that it was possible to run a PIC at 64Mhz and not violate the SPI timings.  The important values are shown in Table 28 of the datasheet:

We are interested in Tscyc, Tshw and Tslw.  These relate to the total clock cycle, the HIGH portion of the cycle and the LOW portion respectively.  The overall clock pulse must be at least 50ns and the high and low portions must be at least 25ns each.

Crunching the numbers

Assume that the SPI code turns ON the clock pin and then OFF again immediately in 2 instructions.  The pin will be HIGH at the end of the first instruction and LOW again after the second, therefore it is only HIGH for the period of 1 instruction.

On the PIC 12/16/18 family of microcontrollers each instruction takes 4 cycles.  At 64Mhz this means that each instruction takes 1/(64000000/4) seconds, or 62.5ns.  From this we can expect that the HIGH period of the clock pulse should be about 62.5ns, easily within the required timings.

Checking with a logic analyser

It is also possible to measure and see how long the pulse lasts on real hardware.  The screenshot below shows the HIGH portion of the clock pulse being measured, this is the shortest part of the cycle.  The PIC being used is an 18F25K22 running at 64Mhz.  The code toggles the pin ON and OFF in two instructions.

Remember that it must be at least 25ns long in order to be acceptable.  The measurement shows 41.7ns, which is shorter than calculated but still acceptable.  A number of reasons could produce the difference between our calculation and the physical measurement:

• The resolution of the logic analyser (24Mhz in this example) might not be sufficient for the measurement.
• Setting or clearing bits in hardware might not take the entire 4 cycles.
• The PIC might not be running at exactly 64Mhz due to instability of the oscillator or PLL.

See also

If you are interested in using a ST7565 based screen in an Arduino project then you should check out Ladyada’s tutorial on Adafruit.  My C library is available which was designed for PIC 18F parts with HiTech C.  It would be trivial to change for another compiler or chip.

Below is a ZIP file containing the case drawn in Eagle to measurements from the datasheet. A dimension layer is included that makes the most of the internal space.

Download the Eagle board file – free for any use (but credit is nice)

I emailed a few weeks ago and have received no reply, so all I have to go on is a few posts on their forums which confirm I’m not the only one experiencing the issue.

So BatchPCB, unless you can get this fixed I’m afraid I’ll be seeking an alternative. Comments suggesting other cheap PCB fabrication houses welcome, I’ll probably try DorkbotPDX first.

• Freescale “Compact Integrated Antennas“

• Kent Smith “Antennas for low power applications“

• Ingecom “V / UHF Antenna Design“

I will update the blog once the circuit board is designed and I have managed to test range and effectiveness.

The first is an 8×8 LED matrix, with code for some whizzy effects. More information and downloads on this page.

If anybody wants to see the code, I could tidy it up a bit and post with some explanation.

Copper layers

Silkscreen

This board uses 0803 SMD parts, but boy are they tiny.  These are some of the larger surface mount components, I definitely would not try the smaller ones.  After applying paste by hand to the board (I used this stuff) I carefully placed the components using a pair of tweezers I bought specially.

Most board houses will apply a solder mask to manufactured PCBs, this is a special layer on top of the board that covers up everything except the pads.  This means a thin line of paste can be run along all the pins of the chip, there is no need to try and put an individual dot on every pad!  As the paste heats up and turns into solder the flux will evaporate and surface tension pulls the solder paste back onto each pad.

The original board, paste and tweezers can be seen in the image below.

SMD board tools

After assembly came the fun bit, cooking time!  I kept an old frying pan specially for this, into which I placed the board.  Cooking time was no more than a few minutes, it is very visible when the paste starts to reflow and turn into molten solder.  As soon as that happened I turned off the gas hob and left it to cool.

Cooking an SMD PCB!

Note that the oven thermometer really doesn’t work, it had barely reached 50°C by the time the board was finished.  A non contact IR thermometer apparently works much better and should be considered if you want to roughly follow a specific reflow profile.

The final result is shown below, after the header pins were hand soldered.

The finished SMD PCB

Did it work first time?  Well, mostly.  The PIC powered up, the LED blinked on and it talked to PICKit2 on the PC.  After a little examination I found that two of the pads on the chip were not properly soldered, which played havoc with some code I was writing.

Next time I think I would use more paste, I was quite frugal with the syringe and had to fix the two bad joints by hand.  I also probably wouldn’t design all future PCBs as SMD, populating and reflowing the board is easy but the parts are fairly expensive compared to standard “through hole” alternatives.

One more picture now of it in use.  This little thing really speeds up prototyping time, no need to connect a pull-up resistor, power and ICSP lines manually.  If only writing code was so easy..

SMD breakout in use with a graphic LCD

For more information, watch this useful video on Youtube and read the excellent SMD How To from Sparkfun.

By the end of this post there will be a PIC uC talking to Hyperterminal on the PC using less than 50 lines of code.

Pros & cons of using the BoostC library

There main advantage to using this library to implement serial communication is that it sets up all registers and control bits for you (including TRIS for the TX and RX pins). This means limited digging around in the datasheet, you can code without worrying about the underlying hardware.

However it may be a disadvantage too. The limited control over the hardware means that certain things are fixed. For example, 8-bit transmission is the default. It might be possible to change these by modifying the PIC registers directly but I haven’t tried this yet. Leave a comment if you know it works!

Requirements

A few things are necessary to make this work. Firstly a PIC with hardware USART support, in this post I’ll be using the PIC 18F1320 as an example. The hardware USART is listed under “peripherals” in datasheets.

In order to talk to a PC we also need some form of level convertor from logic levels (+5v/0v) to RS-232 (maximum voltage range +12/-12v).  I use a MAX232 breakout board that I built myself, but this board or this board from Sparkfun should work just fine.

Connecting it up

The purpose of this post isn’t to discuss connectivity, but briefly the PIC TX and RX pins need to be connected to the level shifter, as do +5v and GND. The serial pins on the PIC can be found in diagrams in the datasheet. Remember which pins they are as they are needed later.

Find the right values

The BoostC library is incredibly easy to use but there are a three values to work out first. Remember the choices so they can be used in the code later.

bit_time

The first value is bit_time, which is the number of CPU instruction cycles per bit (note that the header file says this is used by the software USART, but code will not compile without it so it is included here for reference).

Take the clock speed in hz, divide by four and then divide by your desired bit rate. I recommend starting slow (e.g. 1200 baud) and trying to faster when it works, so for an 8Mhz clock and 1200 baud we get:

Baud rate generator mode

The second thing to work out is whether we need high or low speed mode and what divisor to use. Fortunately these are fairly simple as they are explained in the datasheet.

If using a slow baud rate with a fast oscillator, the datasheet recommends using the high baud rate generator. The datasheet also suggests that it might help to reduce baud rate error. Enabling this means using a mode of 1. 

For this example I used the 8Mhz internal oscillator (fairly low speed) and did not use the high speed generator, so I set mode to 0.

Baud rate generator divisor

Finding the divisor number is as easy as reading the datasheet to find the “SPBRG value”. There are tables with the combinations of oscillator speed and baud rate showing the correct value. Be careful to use the correct table for whether you plan to work with the high or low speed generator!

For 1200 baud at 8Mhz using the low speed generator, the value is 103.

Using the code

Below is example code which shows how to use the information described above. It was adapted from the file serial_test.c which comes with BoostC.

For some reason the BoostC examples use the hexadecimal locations of the correct registers. It is possible to use their names instead, e.g. TRISB/LATB/PORTB as I have below.

In the code below it is necessary to change 4 things:

• the ports and pin numbers for TX and RX (e.g. if TX is RA6, use 6)
• the bit_time value calculated above
• the call to uart_init, which will need the high/low speed flag and the divisor value
• the clock frequency, if 8Mhz is not used

Code example

Setting up a PC client

As I mentioned above the settings for serial communication are fixed by the library.  You will need to set 1200 bits per second, 8 data bits, no parity, 1 stop bit and Xon/Xoff flow control.  This is often shortened to “1200 8-N-1″.

If you use Hyperterminal, all settings are on the properties page for the relevant serial port.

Conclusion

And finally, some proof that it actually works!  If you find this post useful, or you need further help, please leave a comment below.

Update

Mike (K8LH) has posted a great little utility on the Microchip forums that can help work out the correct values, if you don’t fancy digging through datasheets.

I learned a few things along the way:

• use thin board, this makes a huge difference.  I found 0.0032″ board at Crownhill in the UK, which seems perfect
• let the laminator warm up enough, wait at least 15 minutes after the light comes on
• always leave enough of an edge on the paper and board, excess can always be trimmed off later

Failing to do these wastes time, paper and energy and results in lots of cleaning up to do.

Below is a sample of what the finished PCB looks like.  The slight roughness round the edges is due to cutting it with scissors and the black tint is because I did not have acetone to clean the toner off with.

First PCB made with Pulsar Pro FX

There is an excellent guide to using the paper which includes step-by-step pictures and the finished result.  SMD and double sided boards are perfectly possible, but I haven’t tried yet.