ST7735 128 x 160 Graphic LCD library

Using the Positron8 ST7735 128x160 Colour Graphic LCD library with an 18F PIC microcontroller.

Graphic LCDs have always been fascinating to me, and colour LCDs hold a magic that is just waiting for code to be written for them, so they can be seen working. The Positron compilers are ideal for writing a library for display units of all kinds because they produce tight and fast assember code, so even complex parts of code operate much faster than other compilers can do. Both the Positron8's and Positron16's language is also simple to understand, so it is an easy excercise to alter code to add extra bits and pieces to the library.

The ST7735 128x160 colour graphic LCD is extremely inexpensive for what you get, and their size is small enough to fit in a casing, but still large enough to read easily with the correct font used. I will present here a library for the Positron8 compiler that is easy to use, but flexible and robust enough to use in commercial products.

Connections from the PIC microcontroller to the ST7735 display.
The inexpensive ST7735 modules available are interfaced with using an SPI protocol (Serial Peripheral Interface), so they only require a few pins to be used on the microcontroller, but still offer speed and reliability and a choice of 65 thousand colours on the screen, all at once if required! A typical ST7735 128x160 LCD module is shown below, but there are quite a few to choose from. A datasheet for the ST7735 chip can be found here: ST7735.pdf.

The ST7735 LCD PCB has the pins:

VCC, is the 3.3 Volts or 5 Volts power to it. This is sometimes named as VDD.
GND, is connected to common ground used by the microcontroller.
SCK, is the Clock line used for the SPI interface. This is sometimes printed on the PCB as CLK or SCL or SCK.
SDA, is the Data line used for the SPI interface.
CS, is the pin used by the SPI interface for it to start listening when the pin is brought low, and finish listening when it is brought high.
RES, is the Reset pin for the ST7735 device. This pin is active low, so a low to high toggle on this pin with reset the ST7735.
DC, is the data or command selection when communicating with the ST7735 device. A low on this pin will enable command mode, while a high will enable data mode. This is sometimes printed on the PCB as A0.
BL, is not always on the modules you can purchase, or sometimes named LED. If the PCB has the text BL, then a low on this pin will normally disable the LCD's LED backlight. If this is printed as LED, it requires +3.3 Volts attached to it to illuminate the LCD's backlight LED. I have found with a few PCB modules with the BL text, that leaving this pin disconnected enables the backlight, so it may not need to be used by the microcontroller, unless a low power sleep mode is to be implemented in your circuit.

Within your Positron8 program, the pins used by the ST7735 PCB must be declared, otherwise, the library will use default pins and give you a few warning messages that is has done so. Setting the pins to use is easily done by adding the header code below:

Device = 18F25K20 ' Choose an 18F device
Declare Xtal = 20 ' Set the compiler to create code for 20MHz operation (Can be changed to higher or lower frequencies)
'
' Setup the pins to use for the ST7735 interface
'
$define ST7735_SCL_Pin PORTB.4 ' Connects to the LCD's SCL or SCK pin
$define ST7735_SDA_Pin PORTB.3 ' Connects to the LCD's SDA or DAT pin
$define ST7735_RES_Pin PORTB.2 ' Connects to the LCD's RES or RST pin
$define ST7735_DC_Pin PORTB.1 ' Connects to the LCD's DC pin, or A0 pin
$define ST7735_CS_Pin PORTB.0 ' Connects to the LCD's CS pin

Include "ST7735.inc" ' Load the ST7735 library into the program

Make sure the $defines for the pins used are placed before the library file is included in the program's listing, so the library's code can see them.

The library has several procedures to display text with different fonts and of many sizes, as well as draw lines and circles and plot pixels. It can also clear the display with any suitable background colour, and rotate the display. The library's firmware uses a software based SPI interface, so any valid I/O pin can be used for any of the above lines.

A list of the ST7735 library's procedures are shown below:

SST735_Init
Initialise the ST7735 LCD device.

Syntax: ST7735_Init()

The ST7735 chip needs to be configured before it can be used, so the ST7735_Init() procedure loads its registers with values that suit the display type on the PCB. It must be issued at the start of the program before any of the library's procedures can be used.

ST7735_Rotate
Rotate the direction of the display on the LCD.

Syntax: ST7735_Rotate(pDirection)

Parameter:
pDirection: Holds which direction the display will scan. It can contain values 1 to 4, for each rotation direction.

Example:
Include "ST7735.inc" ' Load the ST7735 graphic LCD library into the program
Include "Tahoma_Bold_16.inc" ' Load the Tahoma 16 flash memory font table into the program

ST7735_Init() ' Initialise the ST7735 display before we start using it
ST7735_Rotate(1) ' Set the rotation that the display will use
ST7735_Cls(clBlack) ' Clear the LCD’s screen with the colour black
ST7735_SetFont(TahomaBold_16) ' Choose the font to use for the text (must be loaded before it can be used)

ST7735_PaperColour(clBlack) ' Set the font's background colour to black
ST7735_PenColour(clWhite) ' Set the font to be coloured white
Print At 0, 0, "Hello World" ' Print on the display

ST7735_Cls
Clear the display with a colour.

Syntax: ST7735_Cls(pColour)

Parameter:
pColour: Holds the 16-bit RGB565 format value that the LCD uses for its colours.

Example:
Include "ST7735.inc" ' Load the ST7735 graphic LCD library into the program
ST7735_Init() ' Initialise the ST7735 display before we start using it
Do ' Create a loop to change the colour every iteration
ST7735_Cls(Random) ' Clear the display with a random colour
Loop ' Do it forever

Note.
The colour value can be any of 65536 values. i.e. 16-bit colour. Its arrangement is known as RGB565, where each colour element is signified by a group of bits. See en.wikipedia.org/wiki/RGB_color_model.

ST7735_Plot
Alter a pixel on the graphic LCD.

Syntax: ST7735_Plot(pXpos, pYpos, pColour)

Parameters:
pXpos: X position of the pixel (0 to 159)
pYpos: Y position of the pixel (0 to 127)
pColour: Colour of the pixel to plot on the display (0 to 65535 RGB565 format)

Example.
Include "ST7735.inc" ' Load the ST7735 graphic LCD library into the program
Dim bXpos as Byte ' Create a byte sized variable for the X position
Dim bYpos as Byte ' Create a byte sized variable for the Y position

ST7735_Init() ' Initialise the ST7735 display before we start using it
ST7735_Cls(clWhite) ' Clear the LCD's screen with the colour white
For bYpos = 0 To 127 ' Create a loop for the Y position
For bXpos = 0 To 159 ' Create a loop for the X position
ST7735_Plot(bXpos, bYpos, clRed) ' Set a red pixel at the Xpos and Ypos
DelayMs 5 ' Slow things down so we can see the pixel being drawn
Next ' Close the X position loop
Next ' Close the Y position loop

ST7735_Line
Draw a line on the LCD’s display.

Syntax: ST7735_Line(pStartXpos, pStartYpos, pEndXpos, pEndYpos, pColour)

Parameters:
pStartXpos: Starting X position of the line (0 to 159)
pStartYpos: Starting Y position of the line (0 to 127)
pEndXpos: Ending X position of the line (0 to 159)
pEndYpos: Ending Y position of the line (0 to 127)
pColour: Colour of the line to draw on the display (0 to 65535 RGB565 format)

Example.
Include "ST7735.inc" ' Load the ST7735 graphic LCD library into the program
Dim bEndYpos as Byte ' Create a byte sized variable for the ending Y position

ST7735_Init() ' Initialise the ST7735 display before we start using it
ST7735_Cls(clBlack) ' Clear the LCD's screen with the colour black
For bEndYpos = 0 To 127 ' Create a loop for the ending Y position
ST7735_Line(10, 0, 10, bEndYpos, clWhite) ' Draw a white line
Next ' Close the ending Y position loop

ST7735_Circle
Draw a circle on the LCD’s screen.

Syntax: ST7735_Circle(pXpos, pYpos, pRadius, pColour)

Parameters:
pXpos: Centre X position of the circle (0 to 159)
pYpos: Centre Y position of the circle (0 to 127)
pRadius: Radius of the circle in pixels (1 to 159)
pColour: Colour of the circle to draw on the display (0 to 65535 RGB565 format)

Example.
Include "ST7735.inc" ' Load the ST7735 graphic LCD library into the program
Dim bRadius as Byte ' Create a byte sized variable for radius of the circle

ST7735_Init() ' Initialise the ST7735 display before we start using it
ST7735_Cls(clWhite) ' Clear the LCD’s screen with the colour white
For bRadius = 1 to 127 Step 4 ' Create a loop for the radius of the circle
ST7735_Circle(80, 63, bRadius, clBlue) ' Draw a blue circle
DelayMs 100 ' Slow things down so we can see the circles being drawn
Next ' Close the radius loop

ST7735_PenColour
Set the colour of the text.

Syntax: ST7735_PenColour(pColour)

Parameter:
pColour: Colour of the character printed on the display (0 to 65535 RGB565 format)

Example:
Include "ST7735.inc" ' Load the ST7735 graphic LCD library into the program
Include "Tahoma_Bold_16.inc" ' Load the Tahoma 16 flash memory font table into the program

ST7735_Init() ' Initialise the ST7735 display before we start using it

ST7735_Cls(clWhite) ' Clear the LCD’s screen with the colour white
ST7735_SetFont(TahomaBold_16) ' Choose the font to use for the text (must be loaded before it can be used)

ST7735_PaperColour(clWhite) ' Set the font's background colour to white
ST7735_PenColour(clBlack) ' Set the font to be coloured black
Print At 0, 0, "Hello" ' Print text on the display
ST7735_PenColour(clBrightRed) ' Set the font to be coloured bright red
Print At 0, 22, "World" ' Print text on the display

Note.
The colour value can be any of 65536 values. i.e. 16-bit colour. Its arrangement is known as RGB565, where each colour element is signified by a group of bits. See en.wikipedia.org/wiki/RGB_color_model.

ST7735_PaperColour
Set the background colour of the text.

Syntax: ST7735_PaperColour(pColour)

Parameter:
pColour: Colour of the background around the character printed on the display (0 to 65535 RGB565 format)

Example:
Include "ST7735.inc" ' Load the ST7735 graphic LCD library into the program
Include "Tahoma_Bold_16.inc" ' Load the Tahoma 16 flash memory font table into the program

ST7735_Init() ' Initialise the ST7735 display before we start using it

ST7735_Cls(clWhite) ' Clear the LCD’s screen with the colour white
ST7735_SetFont(TahomaBold_16) ' Choose the font to use for the text (must be loaded before it can be used)

ST7735_PaperColour(clYellow) ' Set the font's background colour to yellow
ST7735_PenColour(clBlack) ' Set the font to be coloured black
Print At 0, 0, "Hello" ' Print text on the display
ST7735_PaperColour(clCyan) ' Set the font's background colour to cyan
ST7735_PenColour(clBrightRed) ' Set the font to be coloured bright red
Print At 0, 22, "World" ' Print text on the display

Note.
The colour value can be any of 65536 values. i.e. 16-bit colour. Its arrangement is known as RGB565, where each colour element is signified by a group of bits. See en.wikipedia.org/wiki/RGB_color_model.

Print
Print text on the display.

Syntax: The Syntax is exactly the same as the compiler's Print command, and the library has taken over the compiler's library subroutines, so it calls the ST7735 Print routine instead. That means all the modifiers that are available for the compiler's Print command are also available for use on the ST7735 display.

Print At
Print text on the display at a certain pixel position.

Syntax: Again, the ST7735 library takes control of the compiler's Print At command that it uses for graphic LCDs, and will start the text at the X and Y positions. This makes the ST7735 library extremely easy to use for the user who is already familiar with the Positron language, and makes the displaying of text on the ST7735 extremely flexible and friendly.

ST7735__SetFont
Choose the font to use for the displaying of text.

Syntax: ST7735_SetFont(pFontName)

Parameter:
pFontName: is the name of the flash memory font table that is included in the BASIC code. The fonts can be created using a Windows application named FontConverter.exe, and can be downloaded from the link provided over its name. The FontConverter.exe program creates a flash memory data table, and when finished converting, stores the font's information in the clipboard, so create a new page in the compiler's IDE and paste the code into it, then save it with a relevant .inc name in the directory of your choice. The name of the font is the name used for the Flash memory table within the font file For example, the "Tahoma_Bold_16.inc" file used in the demos on this page, has a flash memory table named: TahomaBold_16, so that is the name to use in the ST7735_SetFont procedure.

Example:
Include "ST7735.inc" ' Load the ST7735 graphic LCD library into the program
Include "Tahoma_Bold_16.inc" ' Load the Tahoma 16 flash memory font table into the program

ST7735_Init() ' Initialise the ST7735 display before we start using it

ST7735_Cls(clWhite) ' Clear the LCD’s screen with the colour white
ST7735_SetFont(TahomaBold_16) ' Choose the font to use for the text (must be loaded before it can be used)

ST7735_PaperColour(clWhite) ' Set the font's background colour to white
ST7735_PenColour(clBlack) ' Set the font to be coloured black
Print At 0, 0, "Hello" ' Print text on the display
ST7735_PenColour(clBrightRed) ' Set the font to be coloured bright red
Print At 0, 22, "World" ' Print text on the display

Notea.
The font used for the text, when created by FontConverter.exe must be set to Y axis before creating the font.

The colour value can be any of 65536 values. i.e. 16-bit colour. Its arrangement is known as RGB565, where each colour element is signified by a group of bits. See en.wikipedia.org/wiki/RGB_color_model.

Notes.
You may have noticed the use of colour names in the above examples, such as clBlack, clWhite, clBrightRed etc... These are constant values that represent a selection of RGB565 colours, so that writing the final Positron code is easier because the calculations for creating a colour are not required for common colours.

They are located at the top of the "ST7735.inc" library file and are a collection of $defines.

For example:
'
' Set some RGB565 colours
' RRRRRGGGGGGBBBBB
$define clBlack %0000000000000000
$define clBrightBlue %0000000000011111
$define clBrightGreen %0000011111100000
$define clBrightCyan %0000011111111111
$define clBrightRed %1111100000000000
$define clBrightMagenta %1111100000011111
$define clBrightYellow %1111111111100000
$define clBlue %0000000000010000
$define clGreen %0000010000000000
$define clCyan %0000010000010000
$define clRed %1000000000000000
$define clMagenta %1000000000010000
$define clBrown %1111110000000000
$define clLightGray %1000010000010000
$define clDarkGray %0100001000001000
$define clLightBlue %1000010000011111
$define clLightGreen %1000011111110000
$define clLightCyan %1000011111111111
$define clLightRed %1111110000010000
$define clLightMagenta %1111110000011111
$define clYellow %1111111111110000
$define clWhite %1111111111111111

$define clGray0 %1110011100011100
$define clGray1 %1100011000011000
$define clGray2 %1010010100010100
$define clGray3 %1000010000010000
$define clGray4 %0110001100001100
$define clGray5 %0100001000001000
$define clGray6 %0010000100000100

The Positron8 compiler ST7735 library for 18F devices can be downloaded from here: Positron8_ST7735_Library.zip. It also contains some demos to show it working with a PIC18F25K20 device, but any 18F device can be used if it has enough Flash and RAM space.