Raspberry Pi: Driving the TextStar Display with Python

As you may have seen in my previous Raspberry Pi post, I have a TextStar serial LCD display to show basic info without the need of a monitor or TV. I have written a python module which makes using the display and its various functions easier without knowing to much about the lower level serial stuff.

The module was built using python 3.2. So far I haven't tested if it runs with prior versions. If you get it to run with another version feel free to tell me in the comments so I can add it here. Apart from a standard python install this module also needs the pyserial package to access the serial port.

For the hardware side I'd like to refer to Jeremy's Blog, he has instructions and pictures on how to connect the display to the Pi.

You also should take a look into the datasheet and set the display to 3.3V levels before starting.

As usual with my projects, all the latest code can be found on GitHub. You will need the TextStar.py module in your python search path or in the same directory as your program. The basic usage would be something like this:

#!/usr/bin/env python
 
from TextStar import * # Import everything from the TextStar Module
 
display = TextStar('/dev/ttyAMA0')          # Setup the display using the RasPi's serial port
display.sendCmd('Hello World!')             # Show the text 'Hello World!' on the display
display.setCurPos(2)                        # Position the cursor on the second line
display.drawGraph(TS_BSTYLE_CAPPED, 16, 80) # Draw a Bargraph using the full line of 16 characters and fill to 80 %

I tried to document all the external functions of the class with pydoc, so the command pydoc TextStar should show a help text. For the reference I will also copy it here:

Help on module TextStar:

NAME
    TextStar - Module for driving a TextStar Serial 16x2 Module

DESCRIPTION
    (C) Stefan Brand 2012
    This code is released unter the GPL v3 or later.

CLASSES
    builtins.object
        TextStar
    
    class TextStar(builtins.object)
     |  Class to drive a TextStar Serial 16x2 Display (Module No CW-LCD-02)
     |  For in-depth information about the display see the datasheet at http://cats-whisker.com/resources/documents/cw-lcd-02_datasheet.pdf
     |  
     |  Methods defined here:
     |  
     |  __init__(self, port, baud=9600, debug=False)
     |      Constructor, initializes a new instance of the display class. Takes the following Arguments:
     |      
     |      port:
     |              Serial Port to use. On linux this can be '/dev/ttyS0' or '/dev/ttyUSB0' for example
     |      
     |      baud: [optional]
     |              baudrate to use. Defaults to 9600 Baud, should match the rate set in the display
     |      
     |      debug: [optional]
     |              If set to True debugging / errormessages are print to STDERR. Default value is False.
     |      
     |      Example:
     |      
     |      from TextStar import *
     |      display = TextStar('/dev/ttyAMA0', debug=True)
     |      
     |      Import the module and initialize a new instance using the RaspberryPi Serial port. Debugging output to STDERR is enabled.
     |  
     |  drawGraph(self, style, length, percent)
     |      Draws a bar graph using the displays bar graph feature. Takes the following arguments:
     |      
     |      style:
     |              The style of the bar graph, the following styles are supported:
     |                      TS_BSTYLE_CAPPED   - Capped (terminated) bar graph
     |                      TS_BSTYLE_UNCAPPED - Uncapped (unterminated) bar graph
     |      
     |      length:
     |              Length of the whole graph in characters. Can range from 1 to 16.
     |      
     |      percent:
     |              Percentage of the graph that will be filled.
     |      
     |      Example:
     |              TextStar.drawGraph(TS_BSTYLE_CAPPED, 8, 65)
     |      
     |              Draw a terminated graph using 8 characters and filled to 65 %
     |  
     |  getKey(self)
     |      Query for the displays Keys. Takes no Arguments.
     |      The method will wait 0.1 seconds for a keypress and return None if no key was pressed.
     |      The Keys can be configured in the display. Standard keys are A, B, C and D.
     |      For every key the uppercase letter is returned on key down and the lowercase letter is returned on key release
     |  
     |  sendCmd(self, command)
     |      Send text or commands to the display 
     |      
     |      Example:
     |              TextStar.sendCmd(TS_CLEAR)
     |              TextStar.sendCmd('Hello World!')
     |      
     |              Clear the display and show the Text 'Hello World!'
     |  
     |  setCurPos(self, line, column=None)
     |      Position the cursor at the specified Position. Uses the Following Arguments:
     |      
     |      line:
     |              line number to set the Cursor. The display has 16 virtual lines, so this value can range from 1 to 16.
     |              Only 2 lines are shown at any time (which lines depends on the position of the Window.
     |      
     |      column: [Optional]
     |              Column number to position the Cursor at. If this argument is omitted the column 1 is assumed.
     |              The values can range from 1 to 16.
     |      
     |      Example:
     |              TextStar.setCurPos(2, 4)
     |      
     |              Position the curor at line 2, column 4
     |  
     |  setCurStyle(self, style)
     |      Sets the Cursor Style. The following Styles are supported:
     |              TS_CSTYLE_NONE      - No Cursor
     |              TS_CSTYLE_BLOCK     - Solid Block Cursor
     |              TS_CSTYLE_BLFLASH   - Flashing Block Cursor
     |              TS_CSTYLE_UNDERLINE - Solid Underline Cursor
     |              TS_CSTYLE_UNDFLASH  - Flashing Underline Cursor
     |      
     |      Example:
     |              TextStar.setCursorStyle(TS_CSTYLE_BLOCK) 
     |      
     |              Set the Cursor to a solid Block
     |  
     |  winScroll(self, updown)
     |      Move the window up or down 1 line. Takes the following Arguments:
     |      
     |      updown:
     |              Determines in which direction to move the window.
     |              0 - Move down one line
     |              1 - move up one line
     |  
     |  ----------------------------------------------------------------------
     
DATA
    TS_BSTYLE_CAPPED = 'b'
    TS_BSTYLE_UNCAPPED = 'B'
    TS_CLEAR = '\x0c'
    TS_CMD = 'þ'
    TS_CR = '\r'
    TS_CSTYLE_BLFLASH = 2
    TS_CSTYLE_BLOCK = 1
    TS_CSTYLE_NONE = 0
    TS_CSTYLE_UNDERLINE = 3
    TS_CSTYLE_UNDFLASH = 4
    TS_CUR_BACK = '\x08'
    TS_CUR_DOWN = '\n'

Also the datasheet has in depth information about the display and how to access its various functions if you need more than what the class provides.

If you have questions regarding the usage of this class or the display feel free to ask in the comments. I will show the usage of this class for my temperature logging programm in a followup post, so stay tuned.