Shortly after I got the SPIDriver, I obtained the similar I2CDriver through CrowdSupply.  It’s made by the same folks, and has a very similar interface.  The software provided is different though.  Anyways…  I managed to figure out the ‘C’ programming language interface, added a missing “i2c_stop” prototype to the header file, and get it working in test.

I purchased a TC2004A LCD display from Amazon, here is the datasheet:  TC2004A-01 .

The I2C Interface

I2C means Inter-IC-Communication, with the “2” originally meant to be superscripted, as in “I squared C”.  It was developed by Phillips Semiconductor in the 1980s.  It’s a relatively slow, but pin-efficient interface… not as efficient as Dallas Semiconductor’s “1-wire” interface, but more ubiquitous – available everywhere, and adapted for many uses.

The I2C Display

Anyways, modern LCD displays all seem to have a built-in I2C interface. It’s slow, but it works.  More on the speed, and tricks to get around this, later.

I2C Conversion Chip

The old parallel interface appears to still be there, but there’s almost always a daughterboard attached containing a PCF8574 I2C-to-parallel conversion chip.  Here’s the datasheet for the conversion chip : PCF8574 .

Display Controller

The original Hitachi HD44780 controller chip is still there, here is datasheet: HD44780 .  There appears to be a second source now, the Sitronix ST7066U, here is datasheet: ST7066U_v2.4 .

The HD44780 and friends, always did have a 4/8 bit bus, based on the Motorola MC6800 bus interface – probably because Hitachi second-sourced a bunch of Motorola MC68xx parts in the 1980s.  But I digress :-)

Anyway, this bus had two control lines:

• RW – read/write.  This is actually “read/not write” but many source code languages don’t like the embedded use of slashes in symbol names, and  it’s difficult to do an above bar in most simple word processors.  Anyways, this is high for read and low for write.  Its state is latched on the rising edge of E and must be stable through the end of E high.
• E – enable.  This is an active-high strobe.

The HD44780 has one address pin called RS for register select.  Like RW, this is latched on the rising edge of E and must be stable through the end of E high.  When RS is low, the command/status register is accessed.  When RS is high, data memory is accessed.

There are eight data lines, D0 through D7.  Generally, outgoing data must be valid before the rising edge through the falling edge of E.  Most devices latch the data in on the falling edge of E, although this is not always the case.

Connections from I2C Conversion Chip to Display Controller

With only 8 bits total output from the I2C conversion chip, the display only implements the 4 bit interface.  The 4 bit interface is made up of only the top 4 data lines, D4 through D7.

To control the HD44780, the bus interface has to be emulated by bit-banging.  It takes multiple I2C transfers to do a single transaction.

More than Two Lines

The original HD44780 could control one or two line character displays with lines that were up to 64 characters in width.  Today, displays often have more than two lines, but generally not nearly as wide as 64 characters – most often, not even half this…  so they split the lines.

The original internal display ram was 128 bytes of addressable memory.  The top line at addresses 0x00 to 0x00+LINE_LENGTH-1, the lower line at addresses 0x40 to 0x40+LINE_LENGTH-1.  The rest of the memory was present and could be used as scratchpad memory, with no effect on the display.

What modern displays appear to do, is split the display into multiple 2-line parts.  The top two lines work just like the original, using addresses 0x00 to 0x00+LINE_LENGTH-1, and 0x40 to 0x40+LINE_LENGTH-1, as before.  The third line uses addresses 0x00+LINE_LENGTH to 0x00+(2LINE_LENGTH)-1, the fourth line uses 0x40+LINE_LENGTH to 0x40+(2LINE_LENGTH)-1.

So, in my case, for a 4 line by 20 character display, the lines start at 0x00, 0x40, 0x14 (decimal 20) and 0x54 (0x80+decimal 20), respectively.

There are also devices that have larger displays – more rows, or longer lines that don’t allow them to play the “split original 2 lines” trick.  For this, the common approach is to use two HD44780 controllers (or equivalent), and have 2 “E” signals.

Accessing the Display

As with the SPIDriver, there are an assortment of drivers and sample programs provided to play with.  I built the little i2ccl ‘C’ program that was provided, and that showed me the basics of access.  I reviewed the lcd1602.py script.  That gave me everything I needed.  I adapted a very old LCD access library that I wrote many years ago, do use the i2cdriver functions.  I wrote a ‘C’ program called TestLcd which exercised these libraries, and found all kinds of errors (of course).

Embrace…   CG Characters

One of the cool features of the HD44780 type displays is their ability to display compose characters, or CG characters.  You can compose up to 8 arbitrary different 5×7 patterns, store the patterns in RAM, and access them just like regular characters.  This is helpful, because, well, the character set is a little weird – having some kind of foreign symbol where backslash should be, value 0x5C – see below.

It can also be cool for creating industry-specific compose characters too.  For instance, my first exposure to the HD44780 was in the late ’80s, where we designed it into the Kodiak Scoretec scoreboard system (I developed the electronics for the remote keyboard assembly, eventually became responsible for support of the entire system).  It had little numbers for periods, number of fouls, a little football for possession, special characters for bonus etc.

Extend…   CG Palette

The LCD library has the concept of a CG palette.  There are far more than 8 compose characters defined, but only 8 can be used at any given time.  When this library tries to display a CG character, it checks to see if it’s already in the palette.  If it is, it uses it.  If it is not, it finds an available CG location, loads it with the desired CG character, and uses it.  If there are no CG locations available, it displays a question mark ‘?’.

I added a function to this, so that if no CG locations are available, every present CG character is cross checked to every character in the display RAM, to see if that CG character is presently in use.  The first CG location that’s not in use, is removed to make room for the new CG character.  At the end, if there just aren’t enough CG locations, again a question mark ‘?’ is displayed.

Extinguish…   Backlight and Display Clear

I changed the clear() function to use the direct clear command, instead of writing spaces out to the screen.  Much faster!

I also added a function to control the backlight, seeing as it can be turned on and off using I2C.

Speed, Speed…   Always Need More Speed!

It turns out that accessing the display through I2C is quite slow.  Now, I found a few easy things to speed things up… and there may be places where I can save time, but are more complex.  However, those may be for a later time.

I modified the library to check whether a character is already in the display, before writing it out.  If it is already there, it skips the write, saving precious I/O time.

Compared to the I/O time, the processor time is nothing, so this speeds things up considerably, especially if very little changes from second to second…  like maybe, in an IRIG-B decoder display, hmmmmmm?

I bought a cool device called SPIDriver through CrowdSupply.  Actually, I bought two – and got them each with a neat little SPI based 132 x 162 colour LCD display.

It’s a very neat device, appearing as a USB serial port to your system.  On my LINUX system, it appears as /dev/ttyUSBn.  There are several sample programs and libraries available to drive SPIDriver, including for the display.

The display operates with a Sitronix ST7735 controller – here are a couple of different version datasheets: ST7735 ST7735S_v1.1 .

Anyway, I hacked the included Python program st7735s.py to do my own bidding.   irig_to_st7735.py takes STDIN text, uses the PIL library to rasterize it into graphics, and paints it into the little display.

Unfortunately, it takes about 1-1/2 seconds to get it transferred onto the display – it is a full graphics display, and it is a SPI interface, after all.  I added an option to read_irig to put out 8 lines of text every 2 seconds, which I then piped into the Python program.  It worked fine.  Not terribly useful, but fine :-)

#!/usr/bin/env python3
# coding=utf-8

#***************
# Import functions.
#---------------
import array
import getopt
import struct
import sys
import time

from PIL import Image, ImageDraw, ImageFont
from spidriver import SPIDriver

#***************
# Constants.
#---------------
Version         = 0
Issue           = 3
IssueDate       = "2019-05-06"
DefaultDevice   = "/dev/ttyUSB0"

LightBlue   = (102, 255, 255)
PaleBlue    = (102, 204, 255)
Red         = (255,   0,   0)
Yellow      = (255, 255,   0)
Lime        = (  0, 255,   0)
White       = (255, 255, 255)

NOP = 0x00
SWRESET = 0x01
RDDID = 0x04
RDDST = 0x09

SLPIN = 0x10
SLPOUT = 0x11
PTLON = 0x12
NORON = 0x13

INVOFF = 0x20
INVON = 0x21
DISPOFF = 0x28
DISPON = 0x29
CASET = 0x2A
RASET = 0x2B
RAMWR = 0x2C
RAMRD = 0x2E

PTLAR = 0x30
COLMOD = 0x3A
MADCTL = 0x36

FRMCTR1 = 0xB1
FRMCTR2 = 0xB2
FRMCTR3 = 0xB3
INVCTR = 0xB4
DISSET5 = 0xB6

PWCTR1 = 0xC0
PWCTR2 = 0xC1
PWCTR3 = 0xC2
PWCTR4 = 0xC3
PWCTR5 = 0xC4
VMCTR1 = 0xC5

RDID1 = 0xDA
RDID2 = 0xDB
RDID3 = 0xDC
RDID4 = 0xDD

PWCTR6 = 0xFC

GMCTRP1 = 0xE0
GMCTRN1 = 0xE1

DELAY = 0x80

#***************
# Pure Python rgb to 565 encoder for portablity
#---------------
def as565(ProcessedImage):
    #print ("ProcessedImage:", ProcessedImage)

    OriginalRed, OriginalGreen, OriginalBlue = [list(c.getdata()) for c in ProcessedImage.convert("RGB").split()]

    def MultiplyAndShift(ColourValue, ShiftBy):
        return ColourValue * (2 ** ShiftBy - 1) // 255

    d565 = [(MultiplyAndShift(BlueValue, 5) << 11) | (MultiplyAndShift(GreenValue, 6) << 5) | MultiplyAndShift(RedValue, 5) for (RedValue, GreenValue, BlueValue) in zip(OriginalRed, OriginalGreen, OriginalBlue)]

    d565h = array.array('H', d565)
    #print ("d565h:", d565h)
    d565h.byteswap()
    d565s = d565h.tostring()
    #print ("d565s:", d565s);
    return array.array('B', d565s)

def debug565(OriginalColour):
    print ("OriginalColour:", OriginalColour)

    OriginalRed, OriginalGreen, OriginalBlue = OriginalColour

    def MultiplyAndShift(ColourValue, ShiftBy):
        return ColourValue * (2 ** ShiftBy - 1) // 255

    d565 = [(MultiplyAndShift(OriginalBlue, 5) << 11) | (MultiplyAndShift(OriginalGreen, 6) <HH", x0, x1))
        self.writeCommand(RASET)  # Row addr set
        self.writeData(struct.pack(">HH", y0, y1))
        self.writeCommand(RAMWR)  # write to RAM

    def rect(self, x, y, w, h, color):
        self.setAddrWindow(x, y, x + w - 1, y + h - 1)
        self.writeData(w * h * struct.pack(">H", color))

    def start(self):
        self.sd.setb(0)
        time.sleep(.001)
        self.sd.setb(1)
        time.sleep(.001)

        self.cmd(SWRESET)   # Software reset, 0 args, w/delay
        time.sleep(.180)
        self.cmd(SLPOUT)    # Out of sleep mode, 0 args, w/delay
        time.sleep(.180)

        commands = [
            (FRMCTR1, (     # Frame rate ctrl - normal mode
                0x01, 0x2C, 0x2D)),  # Rate = fosc/(1x2+40) * (LINE+2C+2D)
            (FRMCTR2, (     # Frame rate control - idle mode
                0x01, 0x2C, 0x2D)),  # Rate = fosc/(1x2+40) * (LINE+2C+2D)
            (FRMCTR3, (     # Frame rate ctrl - partial mode
                0x01, 0x2C, 0x2D,  # Dot inversion mode
                0x01, 0x2C, 0x2D)),  # Line inversion mode
            (PWCTR1, (      # Power control
                0xA2,
                0x02,       # -4.6V
                0x84)),     # AUTO mode
            (PWCTR2, (      # Power control
                0xC5,)),    # VGH25 = 2.4C VGSEL = -10 VGH = 3 * AVDD
            (PWCTR3, (      # Power control
                0x0A,       # Opamp current small
                0x00)),     # Boost frequency
            (PWCTR4, (      # Power control
                0x8A,       # BCLK/2, Opamp current small & Medium low
                0x2A)),
            (PWCTR5, (      # Power control
                0x8A, 0xEE)),
            (VMCTR1, (      # VCOM control
                0x0E,)),
            (MADCTL, (      # Memory access control (directions)
                0xC8,)),    # row addr/col addr, bottom to top refresh
            (COLMOD, (      # set color mode
                0x05,)),    # 16-bit color
            (GMCTRP1, (     # Gamma + polarity Correction Characterstics
                0x02, 0x1c, 0x07, 0x12,
                0x37, 0x32, 0x29, 0x2d,
                0x29, 0x25, 0x2B, 0x39,
                0x00, 0x01, 0x03, 0x10)),
            (GMCTRN1, (     # Gamma - polarity Correction Characterstics
                0x03, 0x1d, 0x07, 0x06,
                0x2E, 0x2C, 0x29, 0x2D,
                0x2E, 0x2E, 0x37, 0x3F,
                0x00, 0x00, 0x02, 0x10)),
            (NORON, ()),    # Normal display on
            (DISPON, ()),   # Main screen turn on
        ]
        for c, args in commands:
            self.cmd(c, args)

    def clear(self):
        self.rect(0, 0, 128, 160, 0x0000)

    def writestrings(self, ListOfLineStrings):
        #print ("On entry into writestrings(), ListOfLineStrings: ", ListOfLineStrings)

        #print ("Starting writestrings")
        BaseWidth  = 160
        BaseHeight = 128

        # make a blank image for the text, initialized to transparent text color
        TextImage = Image.new('RGB', (BaseWidth, BaseHeight), ( 16,  16,  16))

        TextSize = int(BaseHeight/ 8)
        LineColours = (White, Lime, Lime, PaleBlue, LightBlue, LightBlue, Yellow, Red)
        #print ("Length of list of LineColours: " + "{0:d}".format(len(LineColours)))
        StartColumnOffset = 0

        # get a font
        #FontToWrite = ImageFont.truetype('Pillow/Tests/fonts/FreeMono.ttf', int(TextSize))
        FontToWrite = ImageFont.truetype('Courier_New.ttf', int(TextSize))
        # get a drawing context
        DrawContext = ImageDraw.Draw(TextImage)

        # draw text, full opacity
        LineNumber = 1
        for LineString in ListOfLineStrings:
            #print ("LineString: " + LineString)
            if  (LineNumber > len(LineColours)):
                print ("Past end of colour list, LineNumber = " + "{0:d}".format(LineNumber) + " and length of LineColours list = " + "{0:d}".format(len(LineColours)))
                print ("Length of ListOfLineStrings = " + "{0:d}".format(len(ListOfLineStrings)))
                print ("ListOfLineStrings: ", ListOfLineStrings )
                print ()
                LocalColour = White
            else:
                LocalColour = LineColours[LineNumber-1]

            DrawContext.text((StartColumnOffset, (LineNumber-1)*TextSize), LineString, font=FontToWrite, fill=LocalColour)
            LineNumber += 1

        FinalImage = TextImage

        # debug by saving images to disk
        #print ("Output 01txt.jpg")
        #SaveImage = TextImage.convert('RGB')
        #SaveImage.save("01text.jpg")

        #print ("Ouput 02base.jpg")
        #SaveImage = BaseImage.convert('RGB')
        #SaveImage.save("02base.jpg")

        #print ("Ouput 03final.jpg")
        #SaveImage = FinalImage.convert('RGB')
        #SaveImage.save("03final.jpg")

        #print ("FinalImage.size")
        #print (FinalImage.size)

        if FinalImage.size[0] > FinalImage.size[1]:
            #print ("Rotating 90 degrees")
            FinalImage = FinalImage.transpose(Image.ROTATE_90)
        #w = 160 * FinalImage.size[0] // FinalImage.size[1]
        #FinalImage = FinalImage.resize((w, 160), Image.ANTIALIAS)
        #(w, h) = FinalImage.size
        #if w > 128:
            #FinalImage = FinalImage.crop((w // 2 - 64, 0, w // 2 + 64, 160))
        #elif w < 128:
            #c = Image.new("RGB", (128, 160))
            #c.paste(FinalImage, (64 - w // 2, 0))
            #FinalImage = c
        st.setAddrWindow(0, 0, 127, 159)
        #st.writeData(as565(FinalImage.convert("RGB")))
        st.writeData(as565(FinalImage))

#***************
# Function to provide usage help.
#---------------
def usage():
        print ("nTake in read_irig LCD output and display to ST7735 display attached to SPIDriver, v"+"%1d" % (Version)+"."+"%1d" % (Issue)+" "+IssueDate+" dmw")
        print ("nTypical usage: "+sys.argv[0]+" [option]* ")
        print ("n      Options: ")
        print   ("               -o            Output device for SPIDriver (default " + DefaultDevice + ")")
        print   ("               -v                    More verbose")

        print ("n      RCS Info:")
        print   ("               $Header: /home/dmw/src/ntp/refclock_irig/RCS/irig_to_st7735.py,v 1.4 2019/05/17 03:37:27 dmw Exp $")

        print ("n")

#***************
# Main function.  
#---------------
if __name__ == '__main__':
    #***************
    # Get command line options.  Error results in help text dump and exit.
    #---------------
    try:
        opts, args = getopt.getopt(sys.argv[1:], "o:v")
    except getopt.GetoptError as Error:
        # print help information and exit:
        print ("n")
        print (Error) # will print something like "option -a not recognized"
        print ("n------------------------------")
        usage()
        sys.exit(2)

    #***************
    # Set defaults.
    #---------------
    UseDevice   = DefaultDevice
    Verbose     = False

    #print ("Checking options now")

    #***************
    # Parse values from command line options.  Error results in message and exit.
    #---------------
    for Option, Argument in opts:
        #print ("Checking option: " + Option + ", with argument: " + Argument)
        if   Option in ("-o"):              # Output file name.
            UseDevice = Argument
            #print ("nUsing device: " + UseDevice)
        elif Option in ("-v"):              # Turn on verbosity.
            Verbose = True
        else:
            print ("nUnknown option "" + Option + " " + Argument + "", aborting...")
            print ("n------------------------------")
            usage()
            sys.exit(2)

    if  (Verbose):
        print("nLightBlue")
        debug565(LightBlue)

        print("nPaleBlue")
        debug565(PaleBlue)

        print("nRed")
        debug565(Red)

        print("nYellow")
        debug565(Yellow)

        print("nLime")
        debug565(Lime)

        print ("nWhite")
        debug565(White)

        print ()
        print ("nUsing device: " + UseDevice)

        print ()

    #exit(0)

    #***************
    # Open ST7735 display through SPIDriver, initialize and clear.
    #---------------
    st = ST7735(SPIDriver(UseDevice))
    st.start()
    st.clear()

    #***************
    # Initial message.
    #---------------
    LineList = [
        #         1111111
        #1234567890123456
        "  IRIG Decoder", 
        "v"+"%1d" % (Version)+"."+"%1d" % (Issue)+" "+IssueDate,
        "    (c) 2019", 
        "  Dean Weiten",
        "  Winnipeg, MB",
        " (204)-888-1334",
        " dmw@weiten.com"]
    st.writestrings( LineList )

    #***************
    # Loop on input.
    # Expecting up to 8 lines per frame,
    # up to 16 characters per line.
    # Colours are fixed sequence.
    # An exception (often a ctrl-C break)
    # results in clearing and exit message display.
    #---------------
    try:
        LineIndex = 0
        LineList = []
        for line in sys.stdin:
            FindFF = line.find('f')
            if  (FindFF>=0):
                if  (Verbose):
                    print ("Got FF at " + "{0:d}".format(FindFF))
                    print( "The line up to the FF is "" + line[:FindFF] + ""." )

                LineToAppend = line[:FindFF].rstrip("rnf")
                if  (len(LineToAppend) > 0):
                    LineList.append(LineToAppend)
                st.writestrings( LineList )
                LineList = []
                LineToAppend = line[FindFF+1:].rstrip("rnf")
                if  (len(LineToAppend) > 0):
                    #print ("First line "" + LineToAppend + "" has length " + "{0:d}".format(len(LineToAppend)) + ", so will be appended, list is at present: "", LineList, "".")
                    LineList.append(LineToAppend)
            else:
                LineToAppend = line.rstrip("rnf")
                if  (len(LineToAppend) > 0):
                    #print ("Line "" + LineToAppend + "" has length " + "{0:d}".format(len(LineToAppend)) + ", so will be appended.")
                    LineList.append(LineToAppend)
                    #print ("Length of LineList after append is " + "{0:d}".format(len(LineList)) + ".")

            if  (Verbose):
                print( "The line list is:" )
                print(LineList)
            #st.writestrings(LoopNumber)
            #LoopNumber += 1

    finally:
        st.clear()

        #time.sleep(3)

        LineList = [
            #         1111111
            #1234567890123456
            "  IRIG Decoder", 
            "v"+"%1d" % (Version)+"."+"%1d" % (Issue)+" "+IssueDate,
            "",
            "    Exiting"]
        st.writestrings( LineList )

        time.sleep(4)

        st.clear()