Raspberry Pi, TextStar LCD, and Python

I have my raspberry pi and have been trying to get it to talk to a serial LCD via the uart ports on the gpio header. This post aims to demonstrate simple comms with bash (the command line) and then with programmatically using python. You can download this code if it’s of any use.


I purchased a serial LCD from Coolcomponents called the TextStar from Cat’s Whiskers Technologies (their product page). It’s a tiny display but incredibly easy to use. It even has four buttons on the sides to use as inputs to your project.

Raspberry Pi setup

I installed the latest Debian based image on my pi and control it over SSH (not entirely necessary although I found the GUI a little too slow to be productive). Follow Raspberry Pi Beginners video tutorials on YouTube  on setting up if you’re a complete novice.

Python is installed by default on all distributions I’ve come across and just typing “Python” into the command line will get you into a basic command by command python interpreter. It’s better practise, however, to write your script in a file “example.py” and running “python example.py” to run the entire thing.

What Python doesn’t normally have straight out of the box is the serial control module it requires to use the UART pins on the RPi’s GPIO header. For that I found an excellent how to here. The commands below are distilled from that post:

wget http://pypi.python.org/packages/source/p/pyserial/pyserial-2.6.tar.gz
gunzip pyserial-2.6.tar.gz
tar -xvf pyserial-2.6.tar
cd pyserial-2.6
sudo python setup.py install
cd ..

Now at the start of a python script you may write “import serial” to have access to the hardware serial ports (including over USB).

Getting it working
So hardware linkup was easy. Do this with the power off just in case! Connect the power pins on the LCD, marked as “+” and “-” to the “5V” and “GND” pins on the RPi’s header. Then boot up. I seem to recall that the baud rate and everything was already configured to match the RPi. So much so that when booting the RPi debug messages would scroll through on the screen and you’d be left with “raspberrypi login:”!

Hello World on LCD

Using bash via SSH to get text on a serial LCD

On the command line you can send an output elsewhere using the “>” symbol. So instead of sending an echo command to the standard output (the terminal) you can redirect it to the serial port. This is a good test for starters. I found “/dev/ttyAMA0” to be the symbolic representation of the GPIO UART. Therefore the following command should send “Hello World” to the screen:

echo "Hello World!" > /dev/ttyAMA0

Using Python

In your python script you need to import the serial module and initialise the port including a handle to access it later. Use the following lines as an example:

import serial
serBaud = 115200
serPort = '/dev/ttyAMA0'
ser=serial.Serial(serPort, serBaud)

Then when you want to write to it use the following:

ser.write("Hello World!")

The datasheet has some important commands to allow clearing, cursor movement, progress bars, and special symbols. One example is sending the hex character 0x0C to clear the screen. In python that is achieved with the following:


I wrote a small class in python which I would like to share here. It is by no means a complete set of commands but it allows simple writing to a specific line and access to the bar graph function.

import time, serial
serBaud = 115200
serPort = '/dev/ttyAMA0'
ser=serial.Serial(serPort, serBaud)
class LiquidC:
 'A class to abstract away serial LCD commands originally by David Taylor of dmt195.wordpress.com'
 def __init__(self):
 #initalise the serial port and clear the screen
 print "\n\nInitialising LCD...\n"
 def clear(self):
 def selftest(self):
 print "Writing test to screen"
 ser.write("Hello World")
 def gotoline(self, line):
 def write(self, line, text):
 def bargraph(self, line, percent):
 def help(self):
 print '''TextStar simple Python library
 Clears the screen.
 Writes "Hello World" to the first line and
 a bar graph to the second.
 write(line number, text string)
 Writes a text string to the specified line.
 bargraph(line number, percentage)
 Draws a bargraph spanning the width of the
 line specified with the percentage complete.
 Prints this help information.'''

# Main program below...
tLCD = LiquidC() #initialises a new object, tLCD
tLCD.write(1,"A progress bar!")
for i in range(0,101):
tLCD.write(1,"Line 1 test")
tLCD.write(2, "Line 2 test")

I offer this as completely public domain so feel free to use and hack it all you like. If you do use it though please let me know, and if you improve on it and want to share back please get in touch!

One thing I did notice is that I have to run the scripts as root, ie “sudo python example.py” for anything that uses the serial module. If anyone has any guidance on this please comment below! Thanks.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: