LCD Library for PIC – Setup on MPLAB X IDE

This article describes the setup and use of the C library for hd44780 based alphanumeric lcd modules. This library is also available for the AVR family of microcontrollers. This part is focused on its usage with PIC16F series of MCUs from Microchip. Here we describe how to setup a MPLAB X project with support for lcd related functions. The library is designed for compilation and use with Microchip’s XC8 C Compiler.

PIC16F877A LCD Library Demo

Fig. LCD Demo


Creating a New Project in MPLAB X

You can create a new project using the MPLAB’s Start page as shown below.

MPLAB X Start Page

Fig. MPLAB X Start Page

Alternatively you can use File->New Project

mplab x file->new project

Fig. Select New Project from File Menu

And for those who love the Keyboard over mouse can hit <Ctrl>+<Shift>+<N>

Any of the three method will launch the New Project Wizard as shown below.

The first step is the selection of project type.

From the Categories list select Microchip Embedded and from Projects select Standalone Project.

mplab project type

Fig. Project Type Selection

Second step is the selection of device for which the project is targeted. Select Mid Range 8-bit MCUs (PIC12/16/MCP) in Family and PIC16F877A in Device.

MPLAB X Device Selection

Fig. Device Selection

Third step is the selection of debug tool. For that select Simulator.

MPLAB X Tool Selection

Fig. Tool Selection

Microchip MPLAB lets you install more that one compiler. It also lets you install more that one version of the same compiler. So their is a step to select a compiler for use with your project.

In the image below you can see the compiler XC8 in the list of available compilers, under it is listed all different versions of the XC8 versions available. Since I had only version 1.12, it is the only available option under XC8.

MPLAB X Compiler Selection

Fig. Compiler Selection

Project name and location

Finally enter the name of project and choose a location on your computer where you wish to save the project and all related files.

MPLAB X Enter Project Name and Location

Fig. Enter Project Name and Location

Click Finish.

Configuring the new MPLAB Project

A small configuration that is needed on all MPLAB project is the definition of a global C preprocessor symbol (consider it as a project level global constant). This symbol is named _XTAL_FREQ and it holds a value equal to the frequency at which the PIC MCU will be running. Note the definition of this symbol is very important ! other wise the codes will not be able to generate accurate timing and the code will fail at runtime!

On MPLAB Window, right click over the project’s name in the Project window.

MPLAB X Project Context Menu

Fig. Project Context Menu

This will bring up a context menu as shown above. From the menu select Properties. It is the last item in the long menu. The Project Properties window will open up as shown below.

MPLAB X Project Properties

Fig. Project Properties.

In the left hand pane labeled Categories select XC8 Compiler. It will open up options for the compiler which is displayed on the right hand side of the window. In Option Categories select Preprocessing and messages.

And then click on the button as shown in the image above to open up the Define Macro window.

In this window add a macro name _XTAL_FREQ=20000000(two followed by seven zeros, i.e. 20 MHz).

MPLAB X Define XTAL Frequency

Fig. Define Macros.

Adding LCD Library Support Files

The library to drive hd44780 based alphanumeric LCD modules comes as a set of following files.

  • lcd_hd44780_pic16.c
  • lcd_hd44780_pic16.h
  • custom_char.h
  • myutils.h

You can download the package from the link given below.

Unzip all the files from the package and then copy them to your MPLAB X (LCDTest.X in this case) project folder using Windows file manager.

Files Belonging to the LCD Library

Fig. Paste the LCD Lib files to project folder.

Now when the files have been copied to the project folder. Its time to add the files to the project.

Adding the source files.

Please refer to the image given below to add existing source files in MPLAB X.

MPLAB X Add Existing Source Files

Fig. Adding existing source files.

It will open up the standard file select dialog which lets you select files to add to the project. Select lcd_hd44780_pic16 and it will get added to the project.

Select lcd source files

Fig. Select lcd_hd44780_pic16.c

Adding the header files.

As you must have seen that the lcd library has three header files.

  • lcd_hd44780_pic16.h
  • custom_char.h
  • myutils.h

All the three header files must be added to the header files section of the project. The steps are same as described above for source files.

MPLAB X Add Existing Header Files

Fig. Adding existing header files


select lcd header files

Fig. Selecting LCD header files.

Now the project is ready and has support of using lcd related functions.

Writing a "Hello World" Application

We will write a small program that will initialize the LCD module and write a string Hello World on it.

Adding a new source file to project

You will need to add a new source file to the project, this file will hold our main application code. For this

  1. Right click on the Source Files Section of Project in the Projects window.
  2. Select New > C Source File …
MPLAB X New Source File

Fig. New Source File.

It will open up the New C Source File Dialog.

In this dialog enter the name for this new file. Enter the name "LCDTest" and copy paste the program given below to this file.

MPLAB New C File

Fig. Naming the new file.

Sample Program


 The most basic example program to write a line of text in a hd44780 based
 alphanumeric lcd module using our lcd library for pic16 mcus.

 Compiler: Microchip XC8 v1.12 (
 IDE: Microchip MPLABX

 MCU: PIC16F877A
 Frequency: 20MHz



#include <xc.h>

#include "lcd_hd44780_pic16.h"

#pragma config FOSC = HS        // Oscillator Selection bits (HS oscillator)
#pragma config WDTE = OFF       // Watchdog Timer Enable bit (WDT disabled)
#pragma config PWRTE = OFF      // Power-up Timer Enable bit (PWRT disabled)
#pragma config BOREN = ON       // Brown-out Reset Enable bit (BOR enabled)
#pragma config LVP = ON         // Low-Voltage (Single-Supply) In-Circuit Serial Programming Enable bit (RB3/PGM pin has PGM function; low-voltage programming enabled)
#pragma config CPD = OFF        // Data EEPROM Memory Code Protection bit (Data EEPROM code protection off)
#pragma config WRT = OFF        // Flash Program Memory Write Enable bits (Write protection off; all program memory may be written to by EECON control)
#pragma config CP = OFF         // Flash Program Memory Code Protection bit (Code protection off)

void main (void)
  //Initialize the LCD Module

  //Clear the display

  //Write a string
  LCDWriteString("Hello World !");

     //Do nothing, just loop indefinitely


Now its time to build this project. Building is the process of compiling all files in the project and then linking them to build the final executable image. This executable image is in the form of a hex file. The name of this file is <project name>.X.production.hex

To build the project select Build Project from the Run Menu.

MPLAB X Build Project

Fig. Building the project

If you have did everything precisely as described in this tutorial your project should build without any problem and you should get a BUILD SUCCESSFUL message in the output window of the MPLAB X IDE.

MPLAB X Build Success Message

Fig. Build Success

The hex file which is actually the executable program in machine language, is generated in the folder "\dist\default\production" which is in your project folder.

The name of the file should be LCDTest.X.production.hex

Burning the hex file to MCU

Burning is the process of transferring the data contained in this hex file to appropriate memory locations on the chip so that chip can execute this program. To burn a chip you need a device programmer. A device programmer consists of a hardware and a driving software. You can purchase a device programmer for PIC16F MCUs from our online store. Please note that we ship through out India and to many other countries. International customers can pay safety using Paypal while Indian customer can use Credit Card, Debit Card or Online Banking for purchase.

How to burn the hex file to PIC MCU using this programmer is described in this article.

USB PIC Programmer

Fig. USB Port Based PIC Programmer


eXtreme Burner - PIC16 Software

Fig. Software Interface


Hardware required to run this demo is described separatly in this article.

pic development board and lcd board

LCD Board Connection


PIC16F877A LCD Library Demo

Fig. LCD Demo




By Avinash Gupta

JLCPCB Prototype: $2 for 10 pcs PCBs, 48 Hours Quick Turn

China’s Largest PCB Prototype Enterprise, 300,000+ Customers & 10,000+ Online Orders Per Day

Get quote online easily: quote

Facing problem with your embedded, electronics or robotics project? We are here to help!
Post a help request.


Avinash Gupta is solely focused on free and high quality tutorial to make learning embedded system fun !

More Posts - Website

Follow Me:
FacebookLinkedInGoogle Plus

Industrial Counter
eXtreme Burner PIC

21 thoughts on “LCD Library for PIC – Setup on MPLAB X IDE

  • Pingback: LCD Module Interface with PIC16F877A |eXtreme Electronics

  • By shivdas - Reply

    Thanks for lcd display module information. It is required for me.

  • Pingback: Making A Thermometer with PIC16F877A |eXtreme Electronics

  • By pcb_nl - Reply

    This was very helpful.

    Could you tell me what custom_char.h is for?
    If i use LCDWriteInt() the compiler says there is not enough memory. “could not find space (64 bytes) for variable ___cgram”
    i deleted a few lines of the content of __cgram[] and then it compiled.

    using pic16f1823 and not so many program space
    Program space used 2E7h ( 743) of 800h words ( 36.3%)
    Data space used 3Eh ( 62) of 80h bytes ( 48.4%)
    EEPROM space used 0h ( 0) of 100h bytes ( 0.0%)
    Configuration bits used 2h ( 2) of 2h words (100.0%)
    ID Location space used 0h ( 0) of 4h bytes ( 0.0%)

    • By Avinash - Reply


      __cgram[] is used for storing custom characters face.

  • By R - Reply

    Your libraries hint that thay can only be used for 16F, but XC8 is for all 8-bit MCU’s, 10F-12F-16F-18F . Would this library work with the 18F series as well?

    I hope to use it for 18F4550/4553.

  • By Nitin Joshi - Reply

    Thanks for the reply.
    I want to know is there any HD44780 LCD library files available for PIC33.
    as i am working on dspic33fj16gs504 which is Microchip IC

  • By Gustavo - Reply

    Hello, I followed your tutorial and work fine, but I need to move the LCD’s connections to PORTB and use a 4×16 LCD.
    I changed on lcd_hd44780_pic16.h all references to PORTB. Then I builded the project without erros but the simulation still working on PORTD. To check the build I commented:

    //LCD Data Port
    //Port PD0-PD3 are connected to D4-D7
    // #define LCD_DATA B //Port PD0-PD3 are connected to D4-D7
    // #define LCD_DATA_POS 0

    After that I builded the project again and surprise the project builded without erros. I think the defines of the ports are in other place, because when i commented those lines the compiler should give some errors like symbol undefined.
    Can you help me please?
    Sorry my English, I’m Spanish users from Argentina.

  • By Ray - Reply

    Greetings first.

    Was forced to move away from “Pic BasicPro” and to use a C type compiler. What a great step by step explanation and great introduction to the “X” environment.
    Thank kindly for the great information.

  • By Povorai Gabor - Reply

    Hi! Im having trouble of setting up the external oscillator of a pic18f4520 to 20MHz crystal, i know the #pragma define OSC=HS must be applied but its not working (for the same lcd display) i was able to writhe some text with the internal oscillator though, but with bad display quality.

  • By Cabir Bilirgen - Reply

    Hi Avinash
    I am from Turkey
    This is a very good and best well teaching site that I have ever seen
    How can I get lcd.c and lcd.h for 18f4550 and xc8
    Thanks for everything

  • By Sujit Mishra - Reply

    Hello Sir,
    Thanks for the tutorial. Sir i tried your code with PIC16F877A, my code compiled successfully without any error but sir when I checked it on hardware it displays only black box although the code runs well on proteus. The only change I have in code is that I have commented RW portion because my RW pin is grounded. Sir can u plz guide me what may b the problem.

  • By tiago - Reply

    works in LCD 20×4?

  • By George Searle - Reply

    Using XC8/mplab. Successfully adapted library for 16f877a use PORTE for control and PORTD RD0 to RD3 for data. Trying to change to RD4 to RD7 for data without any luck. Where do I need to make the changes in your library code.

    Many thanks for your tutorials.


    • By Avinash - Reply

      @George Searle,

      Edit the lcd_hd44780_pic16.h file, find #define LCD_DATA_POS 0
      change 0 to 4

  • By An - Reply

    How can i write the custom chars?

  • By Jan - Reply

    The lib works wel with the PIC16F877A but not with PIC16F18877.
    What can be the reason? Is there an update of Do I have to rework the lib myself?
    Please respond

  • By Jan - Reply

    From my previous question I can report that I have solved the situation.
    In the LCD init routine some extra measures are required to set also the LAT registers correct. This could be done very nice using the same macro system as in the original lib. I also included the clearing of the ANSEL registers just to make sure.
    Kind regards

    • By Avinash - Reply


      Thanks for the comment. Nice to know that you have got it working.

  • By marry - Reply

    hi thanks you so much. but can you help me to make lcd display 2 lines

  • By Aju George - Reply

    Hello sir, can u tell me how to print variables

Leave a Reply

Your email address will not be published. Required fields are marked *

2 − = one

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>