001package com.pi4j.wiringpi; 002 003/* 004 * #%L 005 * ********************************************************************** 006 * ORGANIZATION : Pi4J 007 * PROJECT : Pi4J :: Java Library (Core) 008 * FILENAME : Lcd.java 009 * 010 * This file is part of the Pi4J project. More information about 011 * this project can be found here: http://www.pi4j.com/ 012 * ********************************************************************** 013 * %% 014 * Copyright (C) 2012 - 2013 Pi4J 015 * %% 016 * Licensed under the Apache License, Version 2.0 (the "License"); 017 * you may not use this file except in compliance with the License. 018 * You may obtain a copy of the License at 019 * 020 * http://www.apache.org/licenses/LICENSE-2.0 021 * 022 * Unless required by applicable law or agreed to in writing, software 023 * distributed under the License is distributed on an "AS IS" BASIS, 024 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 025 * See the License for the specific language governing permissions and 026 * limitations under the License. 027 * #L% 028 */ 029 030 031import com.pi4j.util.NativeLibraryLoader; 032 033/** 034 * <p> 035 * Part of wiringPi is a library to allow access to parallel interface LCD displays (Those that use 036 * the popular Hitachi HD44780U or compatible controllers) 037 * </p> 038 * 039 * <p> 040 * The library is simple to use in your own programs, however wiring the displays up may be 041 * challenging, so do take care. It is possible to wire up more than one display! In 8-bit mode, the 042 * first display needs 10 GPIO pins and each additional display needs just one more pin, so with a 043 * maximum of 17 GPIO pins, that's 8 displays. If you move to using a 4-bit interface (trivial in 044 * the code), then it's 4 more displays and 12 LCDs! However I suspect the rest of the wiring might be 045 * somewhat challenging. Wiring is described at the end of the this page. 046 * </p> 047 * 048 * <p> 049 * The LCD display can be either a 5V display or a 3,3v display, however if we are using a 5V 050 * display then we must make absolutely sure the display can never write data back to the Raspberry 051 * Pi, otherwise it will present 5V on the Pi's GPIO pins which will not be good. At best you'll 052 * destroy the pin drivers, at worst you'll destroy your Pi. 053 * </p> 054 * 055 * <p> 056 * So make sure you always connect the R/W pin on the display to ground to force the display to be 057 * read-only to the host. 058 * </p> 059 * 060 * <p> 061 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to 062 * the following system libraries: 063 * <ul> 064 * <li>pi4j</li> 065 * <li>wiringPi</li> 066 * </ul> 067 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by 068 * Gordon Henderson @ <a href="https://projects.drogon.net/">https://projects.drogon.net/</a>) 069 * </blockquote> 070 * </p> 071 * 072 * @see <a href="http://www.pi4j.com/">http://www.pi4j.com/</a> 073 * @see <a 074 * href="https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/">https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/</a> 075 * @author Robert Savage (<a 076 * href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>) 077 */ 078public class Lcd { 079 080 // private constructor 081 private Lcd() { 082 // forbid object construction 083 } 084 085 static { 086 // Load the platform library 087 NativeLibraryLoader.load("pi4j", "libpi4j.so"); 088 } 089 090 /** 091 * <p> 092 * First, you need to initialize wiringPi in the way you want to. The LCD library will call 093 * pinMode functions, but these are ignored if you have already set the modes using the gpio 094 * program and want to use the wiringPiSetupSys() mechanism. 095 * </p> 096 * 097 * <pre> 098 * int lcdInit(int rows, int cols, int bits, int rs, int strb, int d0, int d1, int d2, int d3, int d4, 099 * int d5, int d6, int d7); 100 * </pre> 101 * 102 * <p> 103 * This is the main initialization function and must be called before you use any other LCD 104 * functions. 105 * </p> 106 * 107 * <p> 108 * Rows and cols are the rows and columns on the display (e.g. 2, 16 or 4,20). Bits is the 109 * number of bits wide on the interface (4 or 8). The rs and strb represent the pin numbers of 110 * the displays RS pin and Strobe (E) pin. The parameters d0 through d7 are the pin numbers of 111 * the 8 data pins connected from the Pi to the display. Only the first 4 are used if you are 112 * running the display in 4-bit mode. 113 * </p> 114 * 115 * <p> 116 * The pin numbers will be either wiringPi pin numbers of GPIO pin numbers depending on which 117 * wiringPiSetup function you used. 118 * </p> 119 * 120 * <p> 121 * The return value is the handle to be used for all subsequent calls to the lcd library when 122 * dealing with that LCD, or -1 to indicate a fault. (Usually incorrect parameters) 123 * </p> 124 * 125 * @see <a 126 * href="https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/">https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/</a> 127 * 128 * @param rows 129 * @param cols 130 * @param bits 131 * @param rs 132 * @param strb 133 * @param d0 134 * @param d1 135 * @param d2 136 * @param d3 137 * @param d4 138 * @param d5 139 * @param d6 140 * @param d7 141 * @return return value 142 */ 143 public static native int lcdInit(int rows, int cols, int bits, int rs, int strb, int d0, 144 int d1, int d2, int d3, int d4, int d5, int d6, int d7); 145 146 /** 147 * <p> 148 * Set the cursor to the home position. 149 * </p> 150 * 151 * @see <a 152 * href="https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/">https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/</a> 153 * @param handle 154 */ 155 public static native void lcdHome(int handle); 156 157 /** 158 * <p> 159 * Clears the LCD screen. 160 * </p> 161 * 162 * @see <a 163 * href="https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/">https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/</a> 164 * @param handle 165 */ 166 public static native void lcdClear(int handle); 167 168 /** 169 * <p> 170 * Set the position of the cursor for subsequent text entry. 171 * </p> 172 * 173 * @see <a 174 * href="https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/">https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/</a> 175 * @param handle 176 * @param x 177 * @param y 178 */ 179 public static native void lcdPosition(int handle, int x, int y); 180 181 /** 182 * <p> 183 * Write a single character of data to the LCD display. 184 * </p> 185 * 186 * @see <a 187 * href="https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/">https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/</a> 188 * @param handle 189 * @param data 190 */ 191 public static native void lcdPutchar(int handle, byte data); 192 193 /** 194 * <p>Write string of data to the LCD display.</p> 195 * 196 * <p>(ATTENTION: the 'data' argument can only be a maximum of 512 characters.)</p> 197 * 198 * @see <a 199 * href="https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/">https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/</a> 200 * @param handle 201 * @param data 202 */ 203 public static native void lcdPuts(int handle, String data); 204 205 /** 206 * <p>Write formatted string of data to the LCD display.</p> 207 * 208 * <p>(ATTENTION: the 'data' argument can only be a maximum of 512 characters.)</p> 209 * 210 * @see <a 211 * href="https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/">https://projects.drogon.net/raspberry-pi/wiringpi/lcd-library/</a> 212 * @param handle 213 * @param data 214 * @param args 215 */ 216 public static void lcdPuts(int handle, String data, String... args) { 217 lcdPuts(handle, String.format(data, (Object[]) args)); 218 } 219}