LCD Display Library for Tiva and Stellaris Launchpads

Liquid Crystal Displays (LCDs) are great for creating impressive (and sometimes, useful!) microcontroller projects. The 16 characters / 2 lines display is very cheap and directly supported by the arduino LiquidCrystal library (also works in  MSP430 with Energia).

In this post we implement similar functionality for the Tiva C series and  Stellaris launchpads. This version of the library works in CCS and can be used with Stellaris LM4F120, TivaC TM4C123G and Tiva C Connected TM4C1294 launchpads with minimal changes.

LCD library in action. Also current state of Greek economy :)

You may download the complete project from my github page.

The HD44780 specification

LCDs that use the HD44780 drivers are commonly called COGs (Chip on Glass) as they contain all the necessary circuits to drive the LCD segments and communication with the host processor is generally limited to the following pins:

• DB0 to DB7 Data bus. The bus is used to communicate commands or characters to be written to the screen, one byte at a time. To save MCU pins, the interface can be configured for 4 bit operation, where only the DB4 to DB7 lines are used.
• An RS (Register Select) pin. Specifies whether the data bus is carrying a command to be executed or a character to be displayed. When RS is low,  data on the bus represents a command, otherwise it represents a character.
• An EN pin. This is a strobe pin, It has to be pulsed Low-High-Low for the LCD to accept the data in the bus.

When using 4 bit mode, the above connections require 6 pins of your MCU.

The LCD display will also require additional pins to be connected to Vcc or GND, including:

• Power and ground for the LCD and HD44780 ICs.
• Power and ground for the LCD backlight (if applicable)
• Ground connection of the R/W pin (to enable writing to the LCD).
• A potentiometer between Vcc and GND to pin 5 for adjusting display contrast. 

Here is the pinout used in my version of the LCD library for the TivaC launchpad. Pin assignment can be easily reconfigured using the appropriate #define statements in display.h file:

LCD pin       TivaC

-------------------

DB4           PD0

DB5           PD1

DB6           PD2

DB7           PD3

RS            PE4

EN            PE5

The Code

Let's have a look at how the library works. It is based on the HD44780 spec and heavily influenced by a similar work for the MSP430 published in the Co-Random Thoughts blog. The display.h file defines some useful macros to represent the pins and ports we use:

#define RS GPIO_PIN_4 // Energia Pin 5

#define EN GPIO_PIN_5 // Energia Pin 6

#define D4 GPIO_PIN_0 // Energia Pin 23

#define D5 GPIO_PIN_1 // Energia Pin 24

#define D6 GPIO_PIN_2 // Energia Pin 25

#define D7 GPIO_PIN_3 // Energia Pin 26

#define ALLDATAPINS  D7 | D6 | D5 | D4

#define ALLCONTROLPINS RS | EN

#define DATA_PORT_BASE GPIO_PORTD_BASE

#define CMD_PORT_BASE GPIO_PORTE_BASE

#define DATA_PERIPH SYSCTL_PERIPH_GPIOD

#define CMD_PERIPH SYSCTL_PERIPH_GPIOE

The DATA_PORT_BASE points to Port D which is configured for the data bus. CMD_PORT_BASE points to Port E, configured for the RS and EN signals.

To start up the LCD in 4 bit data mode, we have to send the following command to the D4-D7 pins twice:

D7 D6 D5 D4

 0  0  1  0

For this, we need to pull RS low, send the command, strobe the LCD via the EN pin, wait a bit and repeat. After this step the LCD is switched to 4 bit mode. All subsequent 8bit commands / characters are sent as  a pair of nibbles.

Here is the relevant code in initLCD:

void initLCD(void)
{
SysCtlPeripheralEnable(DATA_PERIPH);
SysCtlPeripheralEnable(CMD_PERIPH);
GPIOPinTypeGPIOOutput(DATA_PORT_BASE,  ALLDATAPINS);
GPIOPinTypeGPIOOutput(CMD_PORT_BASE, ALLCONTROLPINS);
GPIOPinWrite(DATA_PORT_BASE, ALLDATAPINS ,0);
GPIOPinWrite(CMD_PORT_BASE, ALLCONTROLPINS ,0);

SysCtlDelay(10000);

setCmd();
SysCtlDelay(15000);
GPIOPinWrite(DATA_PORT_BASE, ALLDATAPINS, 0b0010);
pulseLCD();
GPIOPinWrite(DATA_PORT_BASE, ALLDATAPINS, 0b0010);
pulseLCD();

PulseLCD is a simple function that pulses EN to Low-High-Low states:

void pulseLCD()
{
// Go Low -> High -> Low
GPIOPinWrite(CMD_PORT_BASE, EN, 0);
GPIOPinWrite(CMD_PORT_BASE, EN, EN);
GPIOPinWrite(CMD_PORT_BASE, EN, 0);
}

Similarly the setCmd() and setData() functions switch the RS pin to low / high respectively.

After successfully initializing the LCD to 4bit mode, we sent a few more commands:

sendByte(0x28,FALSE);  // Set two lines
cursorOffLCD();       // Cursor invisible
sendByte(0x06, FALSE); // Set insert mode

After setting insert mode, the LCD is ready to accept characters for printing. The sendByte function sends a byte as a pair of nibbles:

void sendByte(char byteToSend, int isData)
{
if (isData)
setData();
else
setCmd();
SysCtlDelay(400);
GPIOPinWrite(DATA_PORT_BASE, ALLDATAPINS, byteToSend >>4);
pulseLCD();
GPIOPinWrite(DATA_PORT_BASE, ALLDATAPINS, byteToSend);
pulseLCD();
}

The high nibble is set first followed by the low nibble. The display is strobed to accept each nibble. RS is set accordingly for data (high) or command (low).
Timing is important: with the delays currently in the program, the LCD works fine when running at 25MHz frequency. If you need to run at the full 80MHz of the TivaC (or more for the TivaC Connected) you will need to introduce more SysCtlDelay statements  or the display will fail to catch and garbled text will be shown!

Printing to the LCD is  very simple: Just send the characters of your string one by one to the sendByte function:

void printLCD(char *text)
{
char *c;
c = text;

while ((c != 0) && (*c != 0))
{
sendByte(*c, TRUE);
c++;
}
}

The library implements a few more command of the HD44780 protocol. Here are a few interesting hex codes to try:

Function Definition    Hex Code
Set 4 bit mode         0x0
Scroll one char right  0x1E
Scroll one char left   0x18
Goto Home position     0x02
Go one char left       0x10
Go one char right      0x14
Underline cursor on    0x0E
Blinking cursor        0x0F
Invisible cursor       0x0C
Blank display          0x08
Clear display          0x01
Set next position      0x80+Address

More details are available in the HD44780 datasheet.

Happy coding!

MSP430/ARM Development on Linux: Installing CCS 6.0

Code Composer Studio (or CCS as it is widely known), is Texas Instruments' own development tool for their series of MCUs like the well known MSP430 and the Stellaris/Tiva (ARM based) series. Texas Instruments also provides a number of inexpensive development / demo boards known as launchpads. I am the happy owner of two of them: the MSP430 one (F5529) and the ARM based Stellaris launchpad (LM4F120).

Texas Instruments provides some instructions on installing CCS 6.0 on Linux. We will provide additional instructions for installing Tivaware (or stellarisware).

Basic Install

Install your favorite *buntu variant. I've chosen Xubuntu 14.04 since it is lightweight enough and the speed is tolerable on my tiny 2009 Acer Netbook. (While I have beefier machines for development, the netbook is very convenient as it fits perfectly on my rather small electronics workbench).

Make sure to install the updates, either during installation or immediately afterwards by running:

sudo apt-get update; sudo apt-get upgrade

Downloading CCS6.0

Download CCS6.0 for Linux from this page:

CCS6.0 for Linux

It is preferable to download the full version rather than the web based installer.

Installing Dependencies

Before running the installation program, some dependencies need to be installed. In general the instructions in TI's wiki apply:

sudo apt-get install libc6:i386 libx11-6:i386 libasound2:i386 libatk1.0-0:i386 libcairo2:i386 libcups2:i386 libdbus-glib-1-2:i386 libgconf-2-4:i386 libgdk-pixbuf2.0-0:i386 libgtk-3-0:i386 libice6:i386 libncurses5:i386 libsm6:i386 liborbit2:i386 libudev1:i386 libusb-0.1-4:i386 libstdc++6:i386 libxt6:i386 libxtst6:i386 libgnomeui-0:i386 libusb-1.0-0-dev:i386 libcanberra-gtk-module:i386

Some of these are already installed, apt-get will inform you about this.

Note the wiki refers to the 64bit version, but CCS runs without any problem in Ubuntu 32bit too (as you may have noticed, all the above dependencies are 32bits anyway). Create the required symbolic link:

sudo ln -s /lib/i386-linux-gnu/libudev.so.1 /lib/libudev.so.0

Running the Installation

Change to your Download folder (or wherever you placed the downloaded CCS6.0 archive):

cd ~/Downloads

Extract the files:

tar xvzf CCS6.0.1.00040_linux.tar.gz

(replace with actual filename of downloaded file, may differ if a new CCS version is released)

Change to the folder of the extracted files and run the installer:

cd CCS6.0.1.00040_linux

./ccs_setup_6.0.1.00040.bin

There is no need to run the installer as root (with sudo), unless you wish to install it for multiple users. Otherwise, just run it as a standard user and install CCS in a subdirectory of your home directory. After accepting the license, you will be prompted to select an installation directory. Assuming your username is 'user', install CCS to /home/user/ti (the location is automatically suggested by the installer).

You will then be greeted by the processor support dialog:

It is wise to select all the MCUs that you intend developing for. For this example we selected MSP and Tiva/Stellaris development:

 

You won't have to change the default emulators selected in the next dialog. In the App Center dialog, select at least the MSP430Ware:

Installing the Drivers

After the CCS installation is complete and before plugging in your USB launchpad, install the necessary drivers:

cd ~/ti/ccsv6/install_scripts

sudo ./install_drivers.sh

Running CCS for the First Time

The first time you run CCS, you will be asked to select a workspace (and maybe set it as default). We have chosen /home/user/tidev here but you are welcome to choose your own or accept the default. Make a note of this as you will need it later.

On the first run the App Center will automatically download any options you selected during install (like the MSP430ware) and will also update other components. If you only intend to develop for MSP430, your setup is now complete. For Stellaris/Tiva, read on.

Installing Tivaware (Stellarisware)

Developing for tiva or stellaris requires the Tivaware library and some additional settings in CCS. Note that you can use Tivaware to develop for stellaris (LM4F devices) and there is no need to install stellarisware:

Download Tivaware from TI:

Tivaware download page

If for some reason you prefer stellarisware (for example, developing for LM3S devices):

Stellarisware download page

Tivaware is provided as an EXE file, but is actually a self extracting ZIP. Unzip to a subdirectory of your CCS6.0 install path:

cd ~/ti
mkdir tivaware
cd tivaware
unzip ~/Downloads/SW-TM4C-2.1.0.12573.exe

(the actual filename may vary)

There are several ways to include tivaware in your projects. In order to minimize required settings on each project, create a vars.ini file in your workspace. Remember this is /home/user/tidev in our example:

cd ~/tidev
vi vars.ini

(obviously, use your favorite editor instead of vi to create this file)

A single line is needed:

TIVAWARE_INSTALL=/home/user/ti/tivaware

 

Configuring Your Project for Tivaware

The vars.ini file creates an environment variable for the /home/user/tidev workspace (where the file is saved). To configure your project to use tivaware successfully:

• Import the vars.ini file as source for CCS Build variables
• Add an "include files" path to the compiler using the TIVAWARE_INSTALL variable
• Add the driverlib.lib file to the project.

Go ahead and create a new project (File => New => CCS Project). Use the following screenshot as a guide:

When finished, select File => Import => Code Composer Studio => Build Variables:

Select the vars.ini file previously created:

Next, right click on your project name in the project explorer. Select properties, ARM Compiler, Include Options and add the following directory path:

Finally, add (actually, link) driverlib.lib to your project. Right click on your project name in the project explorer and select add files:

The full path for driverlib.lib as shown: /usr/ti/tivaware/driverlib/ccs/Debug. On the next dialog, select link to file:

 

We are done! Here is our BlinkTheLed project (from the Tiva Workshop workbook), successfully built:

 

Since the drivers for the in-circuit debug interface are installed as well, you can actually connect your launchpad and run a debug session on the device.
And now you can continue running your development environment on your lean and mean Linux machine. Happy coding!