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: https://www.pi4j.com/ 012 * ********************************************************************** 013 * %% 014 * Copyright (C) 2012 - 2019 Pi4J 015 * %% 016 * This program is free software: you can redistribute it and/or modify 017 * it under the terms of the GNU Lesser General Public License as 018 * published by the Free Software Foundation, either version 3 of the 019 * License, or (at your option) any later version. 020 * 021 * This program is distributed in the hope that it will be useful, 022 * but WITHOUT ANY WARRANTY; without even the implied warranty of 023 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 024 * GNU General Lesser Public License for more details. 025 * 026 * You should have received a copy of the GNU General Lesser Public 027 * License along with this program. If not, see 028 * <http://www.gnu.org/licenses/lgpl-3.0.html>. 029 * #L% 030 */ 031 032 033import com.pi4j.util.NativeLibraryLoader; 034 035/** 036 * <p> 037 * Part of wiringPi is a library to allow access to parallel interface LCD displays (Those that use 038 * the popular Hitachi HD44780U or compatible controllers) 039 * </p> 040 * 041 * <p> 042 * The library is simple to use in your own programs, however wiring the displays up may be 043 * challenging, so do take care. It is possible to wire up more than one display! In 8-bit mode, the 044 * first display needs 10 GPIO pins and each additional display needs just one more pin, so with a 045 * maximum of 17 GPIO pins, that's 8 displays. If you move to using a 4-bit interface (trivial in 046 * the code), then it's 4 more displays and 12 LCDs! However I suspect the rest of the wiring might be 047 * somewhat challenging. Wiring is described at the end of the this page. 048 * </p> 049 * 050 * <p> 051 * The LCD display can be either a 5V display or a 3,3v display, however if we are using a 5V 052 * display then we must make absolutely sure the display can never write data back to the Raspberry 053 * Pi, otherwise it will present 5V on the Pi's GPIO pins which will not be good. At best you'll 054 * destroy the pin drivers, at worst you'll destroy your Pi. 055 * </p> 056 * 057 * <p> 058 * So make sure you always connect the R/W pin on the display to ground to force the display to be 059 * read-only to the host. 060 * </p> 061 * 062 * <p> 063 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to 064 * the following system libraries: 065 * <ul> 066 * <li>pi4j</li> 067 * <li>wiringPi</li> 068 * </ul> 069 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by 070 * Gordon Henderson @ <a href="http://wiringpi.com/">http://wiringpi.com/</a>) 071 * </blockquote> 072 * </p> 073 * 074 * @see <a href="https://www.pi4j.com/">https://www.pi4j.com/</a> 075 * @see <a 076 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 077 * @author Robert Savage (<a 078 * href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>) 079 */ 080public class Lcd { 081 082 // private constructor 083 private Lcd() { 084 // forbid object construction 085 } 086 087 static { 088 // Load the platform library 089 NativeLibraryLoader.load("libpi4j.so"); 090 } 091 092 /** 093 * <p> 094 * First, you need to initialize wiringPi in the way you want to. The LCD library will call 095 * pinMode functions, but these are ignored if you have already set the modes using the gpio 096 * program and want to use the wiringPiSetupSys() mechanism. 097 * </p> 098 * 099 * <pre> 100 * int lcdInit(int rows, int cols, int bits, int rs, int strb, int d0, int d1, int d2, int d3, int d4, 101 * int d5, int d6, int d7); 102 * </pre> 103 * 104 * <p> 105 * This is the main initialization function and must be called before you use any other LCD 106 * functions. 107 * </p> 108 * 109 * <p> 110 * Rows and cols are the rows and columns on the display (e.g. 2, 16 or 4,20). Bits is the 111 * number of bits wide on the interface (4 or 8). The rs and strb represent the pin numbers of 112 * the displays RS pin and Strobe (E) pin. The parameters d0 through d7 are the pin numbers of 113 * the 8 data pins connected from the Pi to the display. Only the first 4 are used if you are 114 * running the display in 4-bit mode. 115 * </p> 116 * 117 * <p> 118 * The pin numbers will be either wiringPi pin numbers of GPIO pin numbers depending on which 119 * wiringPiSetup function you used. 120 * </p> 121 * 122 * <p> 123 * The return value is the handle to be used for all subsequent calls to the lcd library when 124 * dealing with that LCD, or -1 to indicate a fault. (Usually incorrect parameters) 125 * </p> 126 * 127 * @see <a 128 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library</a> 129 * 130 * @param rows number of rows 131 * @param cols number of columns 132 * @param bits number of bits wide on the interface (4 or 8) 133 * @param rs pin number of the RS pin 134 * @param strb pin number of the strobe (E) pin 135 * @param d0 pin number for driving bit 1 136 * @param d1 pin number for driving bit 2 137 * @param d2 pin number for driving bit 3 138 * @param d3 pin number for driving bit 4 139 * @param d4 pin number for driving bit 5 (only used in 8-bit mode) 140 * @param d5 pin number for driving bit 6 (only used in 8-bit mode) 141 * @param d6 pin number for driving bit 7 (only used in 8-bit mode) 142 * @param d7 pin number for driving bit 8 (only used in 8-bit mode) 143 * @return 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) 144 */ 145 public static native int lcdInit(int rows, int cols, int bits, int rs, int strb, int d0, 146 int d1, int d2, int d3, int d4, int d5, int d6, int d7); 147 148 /** 149 * <p> 150 * Set the cursor to the home position. 151 * </p> 152 * 153 * @see <a 154 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 155 * @param handle file handle 156 */ 157 public static native void lcdHome(int handle); 158 159 /** 160 * <p> 161 * Clears the LCD screen. 162 * </p> 163 * 164 * @see <a 165 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 166 * @param handle file handle 167 */ 168 public static native void lcdClear(int handle); 169 170 /** 171 * <p> 172 * Turns the LCD display ON (1) / OFF (0) 173 * </p> 174 * 175 * @see <a 176 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 177 * @param handle file handle 178 */ 179 public static native void lcdDisplay(int handle, int state); 180 181 /** 182 * <p> 183 * Turns the LCD cursor ON (1) / OFF (0) 184 * </p> 185 * 186 * @see <a 187 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 188 * @param handle file handle 189 */ 190 public static native void lcdCursor(int handle, int state); 191 192 193 /** 194 * <p> 195 * Turns the LCD cursor blinking behavior ON (1) / OFF (0) 196 * </p> 197 * 198 * @see <a 199 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 200 * @param handle file handle 201 */ 202 public static native void lcdCursorBlink(int handle, int state); 203 204 205 /** 206 * <p> 207 * Set the position of the cursor for subsequent text entry. 208 * </p> 209 * 210 * @see <a 211 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 212 * @param handle file handle 213 * @param x column position staring at 0 (left) 214 * @param y row position starting at 0 (top) 215 */ 216 public static native void lcdPosition(int handle, int x, int y); 217 218 /** 219 * <p> 220 * This allows you to re-define one of the 8 user-definable chanracters in the display. The data array is 8 bytes 221 * which represent the character from the top-line to the bottom line. Note that the characters are actually 5×8, 222 * so only the lower 5 bits are used. The index is from 0 to 7 and you can subsequently print the character defined 223 * using the lcdPutchar() call. 224 * </p> 225 * 226 * @see <a 227 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 228 * @param handle file handle 229 * @param index index value from 0 to 7 230 * @param data 8 bytes which represent the character from the top-line to the bottom line 231 */ 232 public static native void lcdCharDef(int handle, int index, byte data[]); 233 234 /** 235 * <p> 236 * Write a single character of data to the LCD display. 237 * </p> 238 * 239 * @see <a 240 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 241 * @param handle file handle 242 * @param data character data to write 243 */ 244 public static native void lcdPutchar(int handle, byte data); 245 246 /** 247 * <p>Write string of data to the LCD display.</p> 248 * 249 * <p>(ATTENTION: the 'data' argument can only be a maximum of 512 characters.)</p> 250 * 251 * @see <a 252 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 253 * @param handle file handle 254 * @param data string data to write 255 */ 256 public static native void lcdPuts(int handle, String data); 257 258 /** 259 * <p>Write formatted string of data to the LCD display.</p> 260 * 261 * <p>(ATTENTION: the 'data' argument can only be a maximum of 512 characters.)</p> 262 * 263 * @see <a 264 * href="http://wiringpi.com/dev-lib/lcd-library/">http://wiringpi.com/dev-lib/lcd-library/</a> 265 * @param handle file handle 266 * @param data format string to write 267 * @param args string arguments to use in formatted string 268 */ 269 public static void lcdPuts(int handle, String data, String... args) { 270 lcdPuts(handle, String.format(data, (Object[]) args)); 271 } 272}