LCD Library

Part of wiringPi is a library to allow access to parallel interface LCD displays (Those that use the popular Hitachi HD44780U or compatible controllers)

Two LCD displays connected to a Raspberry Pi

Two LCD displays connected to a Raspberry Pi

LCD Connected to Pi in 4-bit mode

LCD Connected to Pi in 4-bit mode

LCD connected to Pi in 8-bit mode

LCD connected to Pi in 8-bit mode

The library is simple to use in your own programs, however wiring the displays up may be challenging, so do take care. It is possible to wire up more than one display! In 8-bit mode, the first display needs 10 GPIO pins and each additional display needs just one more pin, so with a maximum of 17 GPIO pins, that’s 8 displays. If you move to using a 4-bit interface (trivial in the code), then it’s 4 more displays – 12 LCDs! However I suspect the rest of the wiring might be somewhat challenging… Wiring is described at the end of the this page.

The LCD display can be either a 5V display or a 3,3v display, however if we are using a 5V display then we must make absolutely sure the display can never write data back to the Raspberry Pi, otherwise it will present 5V on the Pi’s GPIO pins which will not be good. At best you’ll destroy the pin drivers, at worst you’ll destroy your Pi.

So make sure you always connect the R/W pin on the display to ground to force the display to be read-only to the host.

To use the LCD library, you’ll need this at the start of your program:

#include <wiringPi.h>
#include <lcd.h>

First, you need to initialise wiringPi in the way you want to. The LCD library will call pinMode functions, but these are ignored if you have already set the modes using the gpio program and want to use the wiringPiSetupSys() mechanism.

  • int  lcdInit (int rows, int cols, int bits, int rs, int strb,
            int d0, int d1, int d2, int d3, int d4, int d5, int d6, int d7) ;

This is the main initialisation function and must be called before you use any other LCD functions.

Rows and cols are the rows and columns on the display (e.g. 2, 16 or 4,20). Bits is the number of bits wide on the interface (4 or 8). The rs and strb represent the pin numbers of the displays RS pin and Strobe (E) pin. The parameters d0 through d7 are the pin numbers of the 8 data pins connected from the Pi to the display. Only the first 4 are used if you are running the display in 4-bit mode.

The pin numbers will be either wiringPi pin numbersof GPIO pin numbers depending on which wiringPiSetup function you used.

The return value is the ‘handle’ to be used for all subsequent calls to the lcd library when dealing with that LCD, or -1 to indicate a fault. (Usually incorrect parameters)

In the above Fritzing diagrams, the 4-bit one would be initialised by:

fd = lcdInit (2, 16, 4,  11,10 , 0,1,2,3,0,0,0,0) ;

and the 8-bit one by:

fd = lcdInit (2, 16, 8,  11,10 , 0,1,2,3,4,5,6,7) ;
  • lcdHome (int handle)
  • lcdClear (int handle)

These home the cursor and clear the screen respectively.

  • lcdPosition (int handle, int x, int y)

Set the position of the cursor for subsequent text entry.

  • lcdPutchar (int handle, uint8_t data)
  • lcdPuts (int handle, char *string)
  • lcdPrintf (int handle, char *message, …)

These output a single ASCII character, a string or a formatted string using the usual printf formatting commands.

At the moment, there is no input cursor control and no clever scrolling or wrapping of data sent to the display. It is up to your program to manage the display as it needs to.

Do see an example program in the examples directory inside the wiringPi software distribution.

Connecting them up:

Connecting up displays is relatively straight forward. You pick 4 or 8 GPIO pins for the data bus, then 2 more pins for the control. The LCDs have 2 control wires labeled RS and E. the E pin is what we refer to as the strobe pin above.

The R/W pin on the LCD must be connected to 0V/Ground and this is vitally important if you are using a 5V display.

You refer to the diagram of the edge connector on the LCD and use that to hook up the pins on the GPIO connector. Use the diagram here to help you keep track of the GPIO pins you are using.

Note the pin numbers on the GPIO connecting (using either wiringPi pin numbering or GPIO pin numbering) and enter those into the lcdInit() function call and you must call wiringPiSetup() or wiringPiSetupGpio() before you use this library.

For a 2nd (or 3rd, etc.) display, you wire the displays in parallel, connecting up all the same pins with the exception of the E pin. Each display needs its own unique E pin connected back to a different GPIO pin.


LCD Library — 135 Comments

  1. I was wondering if it would be possible to connect a display like this one to the raspberry pi:

    Someone wrote a library for Arduino to control these displays in c code:

    Maybe this library can be ported to the raspberry pi? It would be quite handy to be able to write code for these displays?

    • Those are nice displays – I did look at the little Nokia ones recently which are relatively cheap too. One more thing to add to my to-do list 😉

      They seem to msotly have a serial interface, so should be relatively straightforwards to use though.




    This guy was working on this display as well and created a display driver for it (for a Carambola-board). So maybe that is another good option instead of porting UTFT. He though had to create a work around for the lack of GPIO pins, something that i believe the raspberry pi hasn’t. And the good thing is that raspberry pi can deliver 5v instead of only 3.3v. So for what i understand, this display could be working fairly straight out of the box for raspberry pi by just rerouting the gpio’s in the display driver.

    • There is a 5v supply pin on the Pi, but while the Pi can talk to 5V logic, it can only do so writing to the 5v device! If a 5v device tries to write data back to the Pi, then you run a real risk of damaging the Pi )-:


  3. Hi,

    I have a 4×20 Display ( it works – partially with the example code supplied (I see the messages, mentioned in the code – but after a few seconds i’m getting some freaky signs and the display is gone).

    Wiring should be ok, I just added a resistor – instead of a potentiometer.
    Wiring-Map: )

    So far I’m not very skilled in writing code (did a few arduino projects -> but, I’ve tried to “create” a simple Hello World programm:

    (added all includes etc. from the example)
    int main (void){
    int disp1;

    printf (“Hello World\n”);
    disp1 = lcdInit (4,20,4,8,9,4,5,6,7,0,0,0,0) ;

    sleep (1) ;

    lcdPosition (disp1, 0, 0) ;
    lcdPuts (disp1, ” Hello World”) ;

    lcdPosition (disp1, 0, 1) ;
    lcdPuts (disp1, ” ————–“) ;

    return 0 ;

    I’ve compiled it with the following command – without mistakes:
    gcc -o lcd-test lcd.c -L/usr/local/lib -lwiringPi -I/usr/local/include -Wall

    When I start the programm (as root):
    Hello World
    Segmentation fault

    What am I doing wrong???

    Thanks for any help…

    • There may be an issue with the timings of the strobe pulses in the lcd library – I wrote it then modified the behaviour of the delayMicroseconds call subsequently.

      Try editing the lcd.c code in the wiringPi directory – search for a function called strobe() – and increase the numbers in the call to delayMicroseconds() – change the 1 into 100 and the 50 into 150, then see if it works.

      sudo make install

      then re-link your own program with the updated library.

      I don’t have time right now to build one up and test, but I’m fairly sure that’s where the issue is.


  4. Hello!
    I have program with lcdInit(…), lcdHome() and lcdClear() functions.
    If I save the program as .c and compile it with “gcc -o … -lwiringPi”, it’s working OK, but if I save it as .cpp and compile it with “g++ -o .. -lwiringPi” I get error that none of the LCD function except lcdInit(…) exists – something like source can’t be found :S

    It’s possible to make all other function C++ compatible, too?

    • Ahh… Apologies. I’ve obviousy put the c++ wrappers in the wrong place in the .h file. If you move them in your version of lcd.h then they’ll work fine. I’ve updated it, so wil lbe reflected the next time I do a push to the main GIT site.


      • So lcd.h file should look like this ?:

        #define MAX_LCDS 8

        #ifdef __cplusplus
        extern “C” {

        extern int lcdInit (int rows, int cols, int bits, int rs, int strb,
        int d0, int d1, int d2, int d3, int d4, int d5, int d6, int d7) ;

        extern void lcdHome (int fd) ;
        extern void lcdClear (int fd) ;
        extern void lcdPosition (int fd, int x, int y) ;
        extern void lcdPutchar (int fd, uint8_t data) ;
        extern void lcdPuts (int fd, char *string) ;
        extern void lcdPrintf (int fd, char *message, …) ;

        #ifdef __cplusplus

        • Yes! I’ve updated my version and it looks exactly like that. Essentially you “wrap” the function declarations inside a construct that allows c++ programs to call them.

          I simply had the extern “C” part in the wrong place in my original release.


  5. Hi Gordon,

    This library is exactly what I need for my project. Thanks for making it available.

    One quick question around the LCD library. 8bit mode works fine, but when I switch to 4 bit mode I cant get any proper characters on the screen.

    Is there something extra I need to do to get ascii characters to display on the screen in 4 bit mode?

    • there shouldn’t be – but I’ve just been made aware of some timing issues to do with the latest versions of delayMicroseconds () being more accurate, so I’m about to re-create it and do some more tests myself… (complete with beter Fritzing diagrams!)


    • It uses the same controller as I’m using, so it should be OK. It’s even 3.3v too, but still tie the R/W line to ground.


  6. I’ve connected a 4×16 lcd to the raspberry pi. When I try to write some characters to row 3 or row 4, position 0 they are actually written to row 3 position 4.

    A little bug in the wiringpi library?

    • It’s not impossible.. Although are you sure you’ve initialised the software for a 4-line display? and 4×16? The only 4-line ones I’ve seen have been 4 x 20 …


      • This is the code I use:
        The stars on line 1 and 2 are printed as the first 4 characters on line 3 and 4, followed by the hyphens.

        lcd = lcdInit (4, 20, 4, 22, 21, 17,23,24,25,0,0,0,0) ;

        lcdPosition (lcd, 0, 0) ; lcdPuts (lcd, “martijn steegman****”) ;
        lcdPosition (lcd, 0, 1) ; lcdPuts (lcd, “—————-****”);
        lcdPosition (lcd, 0, 2) ; lcdPuts (lcd, “—————-“) ;
        lcdPosition (lcd, 0, 3) ; lcdPuts (lcd, “—————-“) ;

        • Since I have one setup, I’ve run your code: (minor change, I’m using native wirinPi pin numbers)

          lcd = lcdInit (4, 20, 4, 11,10 , 0,1,2,3,0,0,0,0) ;

          sleep (1) ;

          lcdPosition (lcd, 0, 0) ; lcdPuts (lcd, "martijn steegman****") ;
          lcdPosition (lcd, 0, 1) ; lcdPuts (lcd, "1------------------1") ;
          lcdPosition (lcd, 0, 2) ; lcdPuts (lcd, "2------------------2") ;
          lcdPosition (lcd, 0, 3) ; lcdPuts (lcd, "3------------------3") ;

          And what I got:


          I’ve tried it with a smaller number of dashes too, and it seems to print that it is supposed to print..


      • I too am using a 4 x16 LCD,

        in a 4×16 LCD the 2nd and 3rd row starts at 0x10 and 0x50 respectively.

        i.e., add the columns to the 1st & 2nd Row addresses to get the 3rd & 4th row addresses.

      • There seems to be many variants of these displays, depending on the size, model, and phase of the moon – some experimentation is required!


  7. Is it possible to control the LCD using your code & I2C?
    The LCD takes a lot of GPIO’s, adding a PCD8574 solves this 🙂

  8. Would love to see a step-by-step guide for newbies (both in terms of electronics and programming). I think I’ve got it wired up and such, but I don’t know how to get the program to compile, keep getting various errors.

    • Email me the errors and I’ll have a look and see if we can work out what’s going wrong.

      But yes, more demos, more videos, etc. just need more time!!! 🙂


      • It’s a compiling error with g++. Something like
        /usr/local/include/lcd.h:36:34: error: unint8_t has not been declared
        lcdtest.cpp: In function int main():
        lcdtest.cpp:9:10: error: sleep was not declared in this scope
        lcdtest.cpp:12:37: warning: deprecated conversion from string constant to char* [-Wwrite-strings]

        I can write out my simple code, but basically I just copied what Bjoern did.

        • Ok well somewhat fixed it by include everything from the lcd.c example as far as the #include’s go.

          Now I’m getting an error that it cannot find -lwiringPi

          • Bah, sorry… I’m a newb ><
            I found a fix you suggested on the RPi forums so I rebuilt the wiringPi library. Looks like I didn't sudo it the first time.

            Now that's fixed.

            I still get a deprecated conversion from string constant to char* error when compiling, but it does compile.

            Running the code does nothing, though. I'll double check my wiring. Is the LCD supposed to light up as soon as RPi is powered? Mine's not.

          • Can you email me the error message, so I know the line number to look for. I don’t see that warninng on my Pi’s (which all run Raspbian – let me know what you’re running)

            The backlight of the LCD should light up, and the display might be full of black squares, depending on the setting of the contrast pot.

            It won’t do anything else until you intialise it via the code.


  9. Hey There!
    I am really really exited to try this project, I have myself a “SPLC780/HD44780 Character LCD 16×2 BLUE Backlight” I got off ebay for a quid, Before I ask my questions, Im a complete newbie to electronics im more of a software guy! One of the main reasons for getting the pi, to learn!

    1) How do you connect your display to the breadboard? Have you just got Wire soldered in going straight down into the board? Or have you used some form of pins?

    2) I presume that’s a dummer switch for the display brightness? I don’t have one, What would I search for to buy one/Any common electronics that I could take out of of? Also, Will the display only light up with a Dimmer switch?

    • Hi!

      The LCD displays have a row of pins soldered to them. This row then plugs into the breadboard.

      So… It might be time to start to learn to solder 😉

      It may be possible to fashion a solution using jumper wires and some mechanical means to hold them in the holes in the PCB on the LCD display, but really, it would be easier, and probably safer to solder a row of pins in.

      There is a little 10KΩ potentiometer on the display – that controls the contrast of the LCD. It’s pretty close to max to make the display work, so possibly using something the junction of a 1KΩ resistor to +3.3v and a 10KΩ resistor to 0v would give you something visible…

      Buying individual components can be fiddly – especially when you add on postage, so often an idea to bulk buy at times, but something like this:

      is what’s needed. You can also get the breadboards and jumper wires from there too, but I fear you’ll end up paying more for the stuff to connect it all together than the actual display at the end of to day, however things like the breadboard and so-on are re-usable for many other projects.


      • Awesome! Thank’s for the reply, I can already solder which should be one less thing to learn, When you say pins are these buyable items or have you made them from stripped thick wire? That’s what I was planning to do as some wire came with the breadboard starter kit I got from ebay!

        My Cheapo display is also a 5V, you have made it clear that I definitively need to attach the R/W to ground, Which I will do, are there any other techniques to protect the Pi from damage? Since Im completely new to electronics I don’t want to fry my little pi!

        I was thinking about getting a few part’s anyway, since my starter pack didn’t include any input methods like buttons, The plan is to house my Pi in a 1989 gameboy and have an LED display replacing the original screen, but I need to play around with this small one first!


        • the pins are standard pin-strips – like these ones:

          they’re 0.1″ pitch which fit into breadboards (with a bit of a push) and into most edge connectors on LCDs and so on.

          A little tip – if you’re buying a breakout board with 2 rows of these – plug them into a breadboard first, then put the breakout board on-top, then solder it up – that way it’ll always fit into the breadboard!

          I’ve not had any issues myself with those display on the Pi – just make surethe R/W line is tied to ground and you should be OK… At least I’m getting away with it so-far!

          Good luck with the Gameboy project!


          • Hello Gordon! Right, following all your steps, im all setup wiring wise, the display glows blue & depending on the potentiometer displays squares on the top row.
            Im having trouble trying to find an example to start with, is it included with wiringPi? Where/How Do I run a test? and where could I see an example of code to run the library? Is there a documentation page?
            I don’t know either C or Python, But I do know PHP so I should be able to understand snippets, alas Im a “noob” where it comes to compiling, as I don’t have the slightest!

            Thank’s again Gordon!

          • You want to adjust the pot. until you can just see the squares and no more (then you can adjust it back when you have some characters on it)

            If you look in the examples directory, you’ll find a program: lcd.c – compile it with

            make lcd

            then run it with

            sudo ./lcd

            and it should put up some text – although do check the program to make sure it’s using the right pin assignments.


  10. Hi,
    I have managed to get the adafruit LCD backpack and a 2×16 Character display working using python.
    Any pointers on how I can get this to work in C?


    • The Adafruit backpack uses either I2C or a modified SPI (really just feeing a shift register) to control the display. You can use the shiftOut () code in wiring Pi to send data to the shift register, but you’ll then need to send the right codes to it to clear the display, write text and so on. It shouldn’t be too hard to copy th ecodes used in thy Python code, or copy the codes used in my LCD driver in wiringPi.


      • Steve/Gordon,

        are either of you guys aware whether anyone has gotten the Adafruit I2C LCD backpack (16×2 blue/white LCD) to work with WiringPi? There is an Adafruit C++ library, but this is for the Arduino and for an I2C 2×16 LCD backback that has an RGB backlight. I can deal with cleaning out the RGB references but i’m not sure how to make the code work with the Pi – there are a bunch of includes like:

        #if ARDUINO >= 100
        #include “Arduino.h”
        #include “WProgram.h”


        • Sorry, not sure how to post code here – the top two includes got mangled – they are for Wire.h and avr/pgmspace.h

        • I do have an I2C library in wiringPi now, but it seems that some people are having issues compiling it (basically anything other than Raspbian)

          But from what I gather, once you have the Pi ‘seeing’ the display via I2C, you send the same commands to it as you could over the parallel interfacee via I2C. I’ve not done it though.


  11. Hello Gordon,

    I am a new bi to electronic and programming.
    I have a raspberry pi and 2×16 lcd.
    I have wired up using your 4 bit mode diagram. Except with that knob like thing. I could not understand what that is.
    After wiring up when I turn on my pi, I see green back light in the display.
    Now could you provide the program or command required to display text on it?

    Simon Mandy

    • The “knob like thing” is a variable resistor/potentiometer. It’s controlling the contrast of the display. Without it, you’ll get a blank display. You can probably get something out of it by connecting it to the +5v line via a 1K resistor.

      The program can be found in the wiringPi examples directory – lcd.c – but do check it first – that one was setup to drive 2 displays…


      • I wired up again, this time including the variable resistor.
        created a folder named lcd under /home/pi downloaded and extracted Makefile and lcd.c to /home/pi/lcd .
        I tried to do ./Makefile got below errors,

        pi@raspiabita ~/lcdnew $ pwd
        pi@raspiabita ~/lcdnew $ ls
        lcd.c Makefile
        pi@raspiabita ~/lcdnew $ ./Makefile
        ./Makefile: line 27: DEBUG: command not found
        ./Makefile: line 28: CC: command not found
        ./Makefile: line 29: INCLUDE: command not found
        ./Makefile: line 30: DEBUG: command not found
        ./Makefile: line 30: INCLUDE: command not found
        ./Makefile: line 30: CFLAGS: command not found
        ./Makefile: line 32: LDFLAGS: command not found
        ./Makefile: line 33: LIBS: command not found
        ./Makefile: line 38: SRC: command not found
        ./Makefile: line 40: OBJ: command not found
        ./Makefile: line 42: all:: command not found
        ./Makefile: line 44: lcd:: command not found
        ./Makefile: line 45: @echo: command not found
        ./Makefile: line 46: CC: command not found
        ./Makefile: line 46: LDFLAGS: command not found
        ./Makefile: line 46: LIBS: command not found
        ./Makefile: line 46: -o: command not found
        ./Makefile: line 48: .c.o:: command not found
        ./Makefile: line 49: syntax error near unexpected token `newline’
        ./Makefile: line 49: ` @echo [CC] $<'

        Can you assist?

        • the Makefile isn’t a script or program, it’s a set of instructions to the make program. Just type

          make lcd

          on its own to build the project.


          • I got it. So i ran made lcd and that kind of build using lcd.c and generated two files in the directory. lcd.o and lcd.
            So I ran sudo ./lcd nothing is displayed on the LCD. But on the putty terminal I saw “Raspberry Pi LCD test program” as output.

            pi@raspiabita ~/lcdnew $ sudo ./lcd
            Raspberry Pi LCD test program

            what i am doing wrong?

          • It’s hard to tell, really. I’ve made sure you can get someting on the display using the potentiometer though – fully one way will be blank, fully the other will show fully black segments.


  12. Hello Gordon! First of all a quick thanks for your tutorial & help! I wouldnt have got this far without it!

    I have my LCD connected to my PI’s GPIO in 8-bit mode, I want to start playing with buttons while my LCD is still connected, in this 8-bit setup are all GPIO simple pins in use? The only free pins are SPIO? Can I not use those for simple button presses?

    I also came across the adafruit tutorial recently to connecting the same LCD, their hardware method uses a lot less pins? is this the LCD in 4-bit mode? or do they use a different method?×2-lcd-directly-with-a-raspberry-pi/wiring

    Thanks again Gordon.

    • Excellent!

      As for pins – you can use the 5 SPI pins as normal GPIO pins – just make sure you don’t have the SPI drivers loaded, however the 2 I2C pins can also be used (again make sure no I2C kernel module loaded). The I2C pins have the advantage on on-board 1.8K pull-up resistors, so just need a button connecting them to ground – they’ll read ‘1’ when not pushed and ‘0’ when pushed though.

      The Adafruit one does indeed use 4-bit mode – and you can do that with your display too – just remove the bottom 4 bits, and call the setup code in 4-bit mode. (Try it without removing the wires first)


  13. Hi, i finally managed to get my HD44780U 4×20 to work properly.

    Is it possible to make the LCD show stored characters?
    I am using the same code you had in the lcd.c for playing around with and i would need åäö to work. Been reading some about storing custom characters. Is this possible with wiringPi or is it limited to C and stuff.

    Not a very good coder here, just playing around

    • You’ll need to write some move bits in C to send character definitions to the display – it’s not that hard though, and I may expand the library soon though. You may want to look at some of the other libraries (e.g. arduino) to see how they do it, and adapt it to suit.

      However for some of those characters you want, they may already be on the rom on the chip… Try sending character number 230 for å…


  14. Hi,

    thanks for this library. It works fine.
    Now, I want to scroll, add new characters, etc. Is it possible to add a function like “void lcdSendCommand (int fd, uint8_t cmd) ;” in your library?

    So, we’ll can make all what we want with the display.


    • Add this into the lcd.c file:

      void lcdSendCommand (int fd, uint8_t command)
      struct lcdDataStruct *lcd = lcds [fd] ;
      putCommand (lcd, command) ;

      and this into lcd.h:

      extern void lcdSendCommand (int fd, uint8_t command) ;

      and off you go! (make ; sudo make install)

      (I’ll add this into the next release of wiringPi)


  15. Thanks for your work on the WiringPi Library. I was trying to get a 2*40 LCD running and tracked down the initialization problems after digging into the sources. The current cols limit is set to 20, which does not apply to my LCD. Since it took me a while to figure out what the issue was, maybe a bit more verbose error reporting is something to be considered?

    if (! ((bits == 4) || (bits == 8)))
    fprintf(stderr,”bus bits must be either 8 or 4: %d\n”,bits);
    return -1 ;

    if ((rows 20))
    fprintf(stderr,”rows must be between 0 and 20: %d\n”,rows);
    return -1 ;

    if ((cols 40))
    fprintf(stderr,”cols must be between 0 and 20: %d\n”,cols);
    return -1 ;

  16. hi gordon thanks for your work,

    i have an euror like this :

    /usr/local/include/lcd.h : error: unknown type name uint8_t.

    how can in resolv

    • Hm. Thought I’d resolved all those – are you using the latest wiringPi?

      however put

      #include <stdint.h>

      in your program abive the include for lcd.h


  17. ” – are you using the latest wiringPi?”

    I think because i’m doing :
    git clone git://

    Now i have an euror like this :

    Segmentation Fault

    • you’ll need to give me more details I’m afraid. What is it that you’re tryin to compile? What command lin options, etc.


  18. first : (file.c contain a programm to write hello world in a lcd)

    gcc file.c -lwiringPi

    after :

    eurror : Segmentation Fault

    • Well – maybe not quite enough information … You’ll now need to start to debug your program. However one thing – you need to be root to access the GPIO pins, so maybe sudo ./a.out

      If that fails, then email me the code and I’ll have a look if I have time.


  19. file.c:

    #include lcd.h>

    int main(){
    int fd;
    fd = lcdInit(2, 16, 4, 11,10 , 0,1,2,3,0,0,0,0);
    lcdPuts(fd, hello world);
    return 0;

    • You missed that word: email

      However, you need to run this as root and you need to call wiringPiSetup() first.

      Check the example lcd.c program for more details.


  20. Hello, Gordon.

    Thank you for the wiringPi. I´ve been porting for the Raspberry Pi a few of my Arduino examples.

    But now about LCD´s: I used the lcdHome() function in a program here, with a 16×2 LCD, and that result in garbage in the LCD.

    From a HITACHI datasheet for the HD44780U, I had the information that the “Return Home” instruction takes 1.52ms for execution. I put, then, a instruction

    delay (2);

    as the last instruction of the function lcdHome() of your library. In fact, I also did that to the lcdClear() function. It seams like it worked, in my case.

    If you´ve read until this point, I´ll finish asking you: excuse me for my poor english skills…

    .. and again, thank you very much for the wiringPi.

    Best regards,

    • Hi,

      Yes, I think there are several implementations of the HD447800 and several versions of the manual, so erring on the side of caution with the delays seems prudent. I’ll update my library.


  21. Howdy Gordon, thanks for all your hard work on wiring pi. I have to say I’m looking forward to trying it… 🙂 I recently purchased a 40×4 lcd display. Pretty much acts like 2 20×4 it has an E and an E1 pin, and the data pins I suspect are already internally wired in parallel… I think your lcd library will work great with it, once I get a chance to try it…

    I have some experience with arduino, so that will help… Just wanted to say I was thrilled when I came across your post for multiple displays connected to wiringpi… I actually have 2 of these 4×40 displays which would be great to be able to use them, and not just keep them in my neatly organized pile of electronic parts…

    thanks again 🙂

    cheers and thanks again 🙂

  22. Hi!

    Why does my display crashes after few minutes of working?
    It looks like:

    I display time and date in PI_THREAD(myThread)
    In main i check if PI_THREAD is using diplay at the moment or not.
    If not i try to clear it. After fem minutes it crashes….:(

    • It could be a timing issue. Try increasing some of the timing values in the driver code (ie. my lcd.c in wiringPi)


    • @simon I am also facing the same problem….
      does introducing delay solved your problem???
      I have more doubts:
      1. Insufficient power supply could also be the reason.
      2. Is it possible that this may be arising because of electromagnetic interference.
      please mail me if you got the solution.

  23. Hi Gordon,

    First of all, thanks for this, I have the wiringPi library working fine when it comes to simply turning on and off pins and I am happily switching a relay with it. my problem comes as soon as I try to use the LCD functions.

    the error I am getting when compiling is:

    “Undefined reference to ‘lcdInit'” and exactly the same for lcdClear().

    I am including -lwiringPi as a command line switch for the g++ compiler and have the lines #include and #include in my very simple test program.

    I have also tried to re-install the library but am at a loss now as to why it isn’t working.

    Sorry if I am doing something stupid here, I’m a bit of a newbie with Linux C++ development. I can include the full code if it would help.

    Thanks again,


    • ah, it seems to have mistaken the include lines for html tags, I have included lcd.h and wiringPi.h.

      Thanks again

      • That’s amazing, thanks Gordon,

        sorry to be a pain, but now it is printing to the screen but each time it is initialised, it seems to move the cursor four places to the right and flash. running lcdHome(handle) or Clear does not reset it.

        eg, after running twice on a 16×2 LCD in 4 bit mode, it will have moved the cursor off the screen and only rebooting the pi seems to fix it.

        Again, sorry if I am doing something drastically wrong here, I imagine it may be something to do with how i have used lcdInit, I have followed your wiring diagram precisely and used the same parameters you give for the 4 bit setup.

        Thanks once again, and thanks for the quick reply!


        • Have yo got the latest version of wiringPi? Type gpio -v – if you get version 2.03 then you’ve got the latest. If not, then

          cd ~/wiringPi ; git pull ; ./build

          to get it.

          In the examples directory, there is a test program – lcd.c – make it with

          make lcd

          and run it – you’ll need to give it parameters – ie.

          sudo ./lcd 4 16 2

          and see if it runs. Have a look at the source to see how it compares to yours. My guess is that there is possibly a wiring issue, or you’re using the wrong pins in the lcdSetup() code, but it’s hard to know where.


          • Hi again Gordon and thanks again!

            After quite a frustrating day of re-soldering all connections, replacing the lcd, associated ribbon cable and playing with other pieces of sample code to see if it was a hardware or software issue, I finally got it working!

            I suspect it was a wiring issue all along, but I am now successfully running it with the same setup of this Python example. (×2-lcd-module-control-using-python/) so wiringPi pins 6, 5, 4 and 1. It probably would work again reverting back to your original set up but I am hesitant to touch it now!

            Genuinely, your help is much appreciated and thanks again for this library.


          • Glad its working now!

            I’m just in the process of putting something together with the Adafruit LCD display too (the “plate” with buttons). wiringPi v2 drives it without any mucking bout with mcp23017 registers, etc.


  24. Hi Gordon! i’m trying to compile te lcd library and i’m getting always the same error aven including stdint.h:
    gcc -o lcd_test lcd_test.c -lwiringPi
    In file included from lcd_test.c:2:0:
    /usr/local/include/lcd.h:35:37: error: unknown type name ‘uint8_t’
    /usr/local/include/lcd.h:37:37: error: unknown type name ‘uint8_t’
    How can i resolve?
    Thank you so much

    • Do you have the latest wiringPi (ie. version 2?) If you don’t want to get it, then put:

      #include <stdint.h>

      at the start of your lcd_test.c file (or before the include for lcd.h)


  25. Hi Gordon,

    thanks for adding the adafruit LCD support. one question, though – I’m using wiringPi for other GPIO functionality, and have been using wiringPiSetupGpio() rather than wiringPiSetupSys(). I assume that the same program should not call both :-). Will the adafruit LCD functionality work if I initialize with wiringPiSetupGpio()? When I added the wiringPiSetupSys() call, my other GPIO functions stopped physically working…


    • No problems calling wiringPiSetupGpio() with the Adafruit RGB LCD plate. (Or at least there shouldn’t be!)

      Just call one of the setup routines once.


      • Thanks – works like a charm :-).

        My next task is to figure out how to extend the i2c bus so that I can move the Adafruit LCD display about 4 or 5 feet from the Pi, e.g. using a 4-wire telephone cable and RJ11 connectors. Any experience with this, or recommendations?


        • I’ve not tried but you should be of for short distances. Remember to take power and ground too. Might be worth while working out if the display uses 5v or 3.3v (I’d hope it uses 5v to power the backlight at least)


  26. Hi Gordon

    Would there be any reason the lcd example code wouldn’t work out of the box? Using a 4×20 screen, the screen just stays with two strips of boxes. The python code from×2-lcd-directly-with-a-raspberry-pi/ works so I’m sure the wiring is ok.

    The only thing changed in lcd.c was the init line for 4bit operation for what pins were being used:

    lcdHandle = lcdInit (rows, cols, 4, 22,18, 16,11,13,15,0,0,0,0) ;



    • It should work, and I have tested it with a 4,20 display too. Make sure your row & cols in the init function are 4,20 although that should still produce something if it’s wrong.

      Also – those pin numbers – What are they? The do not correspond to any wiringPi nor BCM_GPIO pin numbers. Are they physical pin numbers on the P1 connector? If so, are you using wiringPiSetupPhys() to initalise wiringPi ?


      • Yep, I was using the physical pin numbers, didn’t realize I needed to change the setup call. Thanks for that!

        Also, great library, fantastically useful.

  27. Hi,
    First, a great compliment for your wiringPi Project. But I have a question.
    How much Ohm must the resistor have that we use? (I use a resistor not a Potentiometer)
    I have a 5V LCD.

    Thank you Max

  28. Good morning everyone. Gordon or someone could tell me what’s wrong with these 3 lines of code? What am I doing wrong that shows nothing on the display?

    char heart[8] = {0x0, 0xa, 0x1f, 0x1f, 0xe, 0x4, 0x0, 0x0};
    lcdPosition(fd_display, 0, 0);
    lcdSendCommand(fd_display, (uint8_t*)heart);


  29. Hi Gordon,
    This article includes comments I read three times, but I still prompt an error, I am linux newbie, do not know how the library into the lcd compiler inside.
    sorry,my English is not very good.

    pi@raspberrypi ~/Desktop/workspace $ gcc -o lcdDemo lcdDemo.c -L/usr/local/lib -lwiringPi

    /tmp/ccbDwmjB.o: In function `main’:
    lcdDemo.c:(.text+0x68): undefined reference to `lcdInit’
    lcdDemo.c:(.text+0x84): undefined reference to `lcdPosition’
    lcdDemo.c:(.text+0x90): undefined reference to `lcdPuts’
    collect2: ld returned 1 exit status

      • how did you solve your problem ?
        I’m facing the same issue, having same error messages when I try to compile my c code
        thanks in advance for your replay

  30. I’ve been trying to use this with the Adafruit LCD Char Plate, as used

    However, although I can manually control the backlight, I don’t seem to be able to get any messages written to the display (does not initialise).

    I’m trying to achieve this with Python3. The same circuit seems to be wired correctly (it works with the Adafruit example code with Python2.7) and I’ve checked the pin mapping matches your Af_values.

    Anyone able to confirm it works with Python? Thanks in advance.

  31. hi gordon,
    i have problem while running the program,please help me to solve the problem and error is,
    “undefined reference to lcdInit,lcdPostion,lcdPuts,,,,, ” and i initalise the header file #include,#include

  32. Hi!
    I have more than 8 custom characters that i want to display.
    How is it possible for this to be done?
    Whenever i do “lcdCharDef” it replaces the previous characters that are displayed “on the fly”.
    Thank you

    • Also,
      How i put the characters that are stored in the default “Character Codes”?
      I cannot understand the way.

    • You can only have 8 user-defined characters – that’s a limitation of the displays – these devices have an internal memory capacity counted in dozens of bytes.


  33. Hi Gordon.

    First of all i like to thank You – You make rPi very easy 🙂

    I have problem with LCD.

    gcc -o lcd lcd.c -L/usr/local/lib -lwiringPiDev

    /usr/local/lib/ undefined reference to `digitalRead’
    /usr/local/lib/ undefined reference to `digitalWrite’
    /usr/local/lib/ undefined reference to `sn3218Setup’
    /usr/local/lib/ undefined reference to `delayMicroseconds’
    /usr/local/lib/ undefined reference to `delay’
    /usr/local/lib/ undefined reference to `analogWrite’
    /usr/local/lib/ undefined reference to `digitalWriteByte’
    /usr/local/lib/ undefined reference to `wiringPiSPIDataRW’
    /usr/local/lib/ undefined reference to `pinMode’
    /usr/local/lib/ undefined reference to `wiringPiSPISetup’
    /usr/local/lib/ undefined reference to `pullUpDnControl’
    /usr/local/lib/ undefined reference to `millis’
    /usr/local/lib/ undefined reference to `wiringPiNewNode’
    /usr/local/lib/ undefined reference to `mcp23s17Setup’
    collect2: ld returned 1 exit status

    I dont know what I’m doing wrong.
    It seems that loewe got solution for this, but he didnt share with it 🙂

    I’m waiting unpatient for Your answer.

    All the best


  34. Thank You very much Mister – it worked 😀

    Btw, You are amazing – making libs like this and answer a stranger like me in 11 minutes 😀

  35. Great library, Thx
    I use 7″ wires right now, thinking to move LCD 3′ away
    Is there max distance between PI and LCD ?

    • Not really – but the longer the wires, the longer the signals will take to propogate and stabilise. For more than about half a meter you might need to slow down the strobe signal by adding more delay to it in the code.


  36. Hello
    I got another version of HD44780U display with PCF8574T I2C expander.
    I simply added line pcf8574Setup (100 , 0x27) after wiringPiSetup(), before lcdInit(). I used code that worked with regular LCD with 4bit connection. My display came assembled with I2C expander so I am not 100% sure about pinout, but after couple of hours searching web my lcdInit look like this:
    I use lcdPosition and lcdPuts to display strings on first and second line, but lcd just blinks couple of times, no string output.
    Any suggestion?

  37. hi i have a problem.
    i have a 4X20 lcd with a KS0066 Controller but a can`t get it initialised

    please can somebody help me

    sorry for me bad english 🙂

  38. Hi,
    Thank you very much for the code. Makes life much easier to not have to work out all the control parameters from the data sheet myself!

    One thing that might be worth a change:
    I have an LCD with 40 columns. The Init call fails because you don’t allow displays greater than 20 chars.
    I’ve edited lcd.c and re-compiled and all OK.

    Just thought you might want to change the code in your distribution to support 40 char displays.


  39. Hi Gordon,

    I’ve also made another change to the lcd.c code.

    I’ve added a delay of 1uS in the strobe routie before the strobe is triggered. This is to overcome an occasional character corruption problem that I was seeing on my display when using a longish ribbon cable(about 35cm – old floppy disk cable). It allows the lines to stabilise before committing the data. I now have a clean display.