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 - 2015 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="http://www.pi4j.com/">http://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}