Using the Adafruit LCD Shield from Java

We’re interrupting the ordinary programming for a series of Raspberry PI related articles. Yep, I finally bought one and started having some fun.

I know I am sooo late to the party. My excuse is that having really young kids translates into a constant time shortage. That said, I bought myself a Raspberry Pi just in time for some vacation. One of the first things I did was to get an LCD shield for the Raspberry PI. I settled on this particular kit:

It’s a really nice little LCD kit which also features a few buttons. The shield uses a port extender (MCP23017) to get another 16 GPIO ports over I²C. This is quite nice, since you probably want to use your GPIO ports for other things. Also, you can hook up several I²C devices on the same bus, so using the I²C pins for the LCD shield doesn’t mean that you’ve used them up.

The LCD shield can be run in various different modes. My little example library uses 16×2 characters by default.

Building the Kit

The instructions for building the kit are excellent, and there are just a few things I’d like to note:

  1. Get a stacking header
    I fortunately came to the conclusion I would need a stacking header before soldering everything together, but unfortunately after I had ordered the LCD shield. I am oh so happy I decided to wait for the header to arrive before finally putting the kit together.
  2. If you want to attach a standard flat 26 pin cable, trim out some space in the LCD PCB for the little orientation peg on the cable header 
    This I did not do – I ended up trimming down the cable header with my Dremel instead, since it’s too hard to access that area after soldering on the LCD.
  3. (Optional) Unused GPIO pins for free!
    E.g. GPA5 appears to not be in use. Feel free to use it for your own purposes. The library initializes it as yet another input pin by default, but that is easily changed.
  4. (Optional) Use interrupts for the buttons
    This will cost you a GPIO pin (and you cannot use one of the unused ones on the LCD shield’s MCP23017), but will allow you to poll the button pins a lot less often without risking missing a button press. You may want to do some additional soldering on pin 20 of the MCP23017 – INTA is not hooked up by default. This also requires you to hack my Java code a little bit to initialize GPINTEN, and to read from INTF and INTCAP,

Testing the Kit

Once you’ve built the kit, follow the instructions here to try out the LCD kit using the demo python code. Once you have your LCD shield up and running you can move on to getting everything to run from Java.

Using the LCD Shield from Java

Once everything is working from python, you are ready to run things from Java. I mostly did a straight port of the Python library.

  1. First download and install Pi4J
    This will be required for most future posts I might put on the blog.
  2. Next download lcd.jar
    The source is available with

Now you can run the included demos by just invoking the jar like this:
sudo java –Xbootclasspath/a:/opt/pi4j/lib/pi4j-core.jar –jar lcd.jar


When running the demos, use the up/down buttons to select a demo, then press select to run a demo. When the demo is done, use up/down to select a new demo.

API Examples

Here is how the API can be used to show some text:

LCD lcd = new LCD();
lcd.setText("Hello World!\n2nd Hello World!");

Here is an example with some buttons:

final LCD lcd = new LCD();
lcd.setText("LCD Test!\nPress a button...");
ButtonPressedObserver observer = new ButtonPressedObserver(lcd);
observer.addButtonListener(new ButtonListener() {
    @Override public void onButtonPressed(Button button) {

For more examples, check out the demos in the se.hirt.pi.adafruitlcd.demo package. I currently have most of the implementation in my python port LCD class. Anything that isn’t purely reading/setting registers, I’ve handled outside of that class (such as the polling of buttons). If I ever find some time I might clean up the API and move away from the current python port.

Tips and Tricks

  • If you want to teach the LCD to do additional tricks, the LCD controller used is the HD44780
    Note that it might be valuable to read the spec if for no other reason than to understand the limits (e.g. quite small DDRAM buffer).
  • MCP23017 is an awesome little thing
    Ever wanted more GPIO ports? Using the MCP23017 is one way to get plenty more. Just remember to provide a unique address by configuring A0-A2 (see page 8 of the spec). Connecting them all to ground will yield 0x20 (which is what the LCD shield uses). Hooking them all up to 5v will yield 0x27.
  • Be careful with how much current you source/sink, both using the MCP23017 (25mA) and the RPi (16mA GPIO, 50mA 3.3v rail, 5V rail pretty much depends on your power supply). If you need to source/sink more than the IO pins can handle, you can use a Darlington Array, for example ULN2803.

15 Responses to "Using the Adafruit LCD Shield from Java"

  1. […] code to detect key pressing (I was using Markus Hilt’s wrapper around Pi4J, available here:, but I found some opportunities to improve performance, considering we are in an embedded […]

  2. Marcus says:

    Updated the code with better debouncing algorithm.

  3. Todd Leonhardt says:

    I tried downloading and executing your lcd.jar with the instructions above:
    “sudo java –Xbootclasspath/a:/opt/pi4j/lib/pi4j-core.jar –jar lcd.jar”
    and it complains about not being able to find or execute a Main inside that jar.

    Do you have any advice on required versions of the JRE and/or Pi4J or was I doing something wrong?

  4. Marcus says:

    Nah, bad manifest in the jar. It should be fixed now. Sorry about that. 😉

  5. Mike says:

    Tried running the lcd.jar file and it generates this error:

    Exception in thread “main” Cannot open file handle for /dev/i2c-1 got -1 back.

    Mine is located at i2c-0, how can i change this?

  6. Marcus says:

    Change line 58 in the demo to:
    final ILCD lcd = new RealLCD(I2CBus.BUS_0, 0x20);

  7. roman says:

    Error: Could not find or load main class –Xbootclasspath.a:.opt.pi4j.lib.pi4j-core.jar
    Pi4J is installed.

  8. Marcus says:

    You seem to have some syntactic problem on your command-line. The JVM seems to think –Xbootclasspath.a:.opt.pi4j.lib.pi4j-core.jar is your main class.

  9. Marcus says:

    For example, you have a dot instead of a forward slash after bootclasspath.

  10. […] More Raspberry Pi fun with Java! For an Adafruit LCD Shield library, check out my previous blog. […]

  11. Paulo Lima says:

    Just a tipp: please make sure to get your i2c enabled, device tree disabled, and the blacklist file properly configured.

  12. Hello, I am using your project details as a building off of point for a project in college. I want to make a “smart dorm” system that can display information on the screen. The project must be in Java and you seem to be one of the only people on the internet who have gotten this to work.
    However, when I run the command:
    sudo java –Xbootclasspath/a:/opt/pi4j/lib/pi4j-core.jar –jar lcd.jar
    I get the output:
    Error: Could not find or load main class –Xbootclasspath.a:.opt.pi4j.lib.pi4j-core.jar
    I installed pi4j with their bash script installer and I have the file pi4j-core.jar in my /opt/pi4j/lib/ directory.
    If you have any insight as to how I could make this project work that would be greatly appreciated.
    Thank you,

  13. Marcus says:

    I think the minus sign before the Xbootclasspath might have been copied as a hyphen. Try typing the line yourself instead of copying it.

  14. gainestr says:

    I appreciate the work you’ve done on this. Have you played around with node-red at all? I’m trying to find a way to use the LCD Shield with node-red. Any advice on this?

  15. Marcus says:

    Hi there!

    Nope, not played around with node-red. That said, I’ve started pushing all of this into Robo4J. Maybe Robo4J may help?


Leave a Reply

Your email address will not be published.