search

duinoWitchery / hd44780

Extensible hd44780 LCD library
GNU General Public License v3.0
241 stars 58 forks source link

readme

hd44780 Extensible hd44780 LCD library hd44780Version

Licensing

GPLv3Logo

hd44780 is an open source project for open source projects. Those wishing to create closed projects should seek an alternate solution. hd44780 is licensed under the terms of the GNU General Public License v3.0 as opposed to the more liberal licensing terms of the GNU Lesser General Public License (LGPL), MIT, modified BSD, Apache, etc..

GPL licensing information can found here: https://www.gnu.org/licenses/

For full details on the licensing of the hd44780 library and its components, see the included licensing file.

Library Overview

hd44780 is an extensible Arduino LCD library for hd44780 based LCD displays. The library consists of a hd44780 base class combined with one or more i/o subclasses to perform the i/o communication between the host and the hd44780 display interface.

While the library is API compatible with the Arduino IDE bundled LiquidCrystal library, hd44780 is not a direct drop in replacement for the LiquidCrystal library.

The API functionality provided by the hd44780 base class, when combined with an hd44780 library i/o subclass, is compatible with most of the API functionality of the Arduino LiquidCrystal library as well as with most of the LCD API 1.0 Specification (some of which is nearly obsolete).

The hd44780 API also provides some addtional extensions and all the API functions provided by hd44780 are common across all i/o subclasses. The most most significant extensions being:

S/W requirements

H/W support

Library should work on all Arduino boards including boards with AVR, pic32, arm, and ESP8266 processors.

WARNING
Use caution when using 3v only processors like arm and ESP8266 processors when interfacing with 5v modules as not doing proper level shifting or incorrectly hooking things up can damage the processor.

The library currenly comes with the following i/o subclasses:

Installation

For generic information about Arduino libraries and how to install them consult the Arduino Libraries page: https://www.arduino.cc/en/Guide/Libraries

For ease of proper installation, the preferred method of installing the library is to use the library manager. The use of importing a .zip file is highly discouraged unless using IDE versions prior to version 1.6.2

Installation using Library manager (IDE 1.6.2 and later)

In the IDE, Simply click on:
[Sketch]->Include Library->Manage Libraries...
or
[Tools]->Manage Libraries...
Then search for "Extensible hd44780" to locate the library and install it.
There is no need to uninstall or modify any other LCD libary that may have already been installed.

Installation using zip file w/o library manager (IDE 1.6.1 and earlier)

Installation requires downloading a zip image and then, depending on the version of the IDE you can either install it from the IDE or install it manually by unziping the file into your sketchbook libraries.

NOTE: due to the way github creates its zip files, there is a manual step that must be done to rename the library directory created in your sketchbook libraries area.

First, dowload a library zip image from the github repository releases area:
https://github.com/duinoWitchery/hd44780/releases
Download the image by clicking the zip icon for the desired release.

Installation of zip file library on IDE 1.0.6 to 1.6.1

The library can be installed from the zip image using the IDE. Install it by clicking on: [Sketch]->Include Library->Add .ZIP library... then, simply select the hd44780.zip image you downloaded.

The hd44780 sketchbook library must now be renamed. (see below)

Installation of zip file library on IDE 1.0 to 1.0.5

On these versions of the IDE, the install must be done manually. To install the library simply extract it into your sketchbook/libraries directory. If you don't know where you sketchbook/libraries directory is simply click on: [File]->Preferences or from the keyboard type: <ctrl>comma (hold ctrl and press comma) The location of your sketchbook directory will be in the text box. The zip image must be installed in a directory called "libraries" under that directory.

After the zip file has been extracted and the hd44780 sketchbook library has been created, the library must now be renamed. (see below)

Renaming hd44780 libary directory name after manual installation w/o library manager

When not using the library manager, the hd44780 library directory created in your sketchbook libary area will not be the correct name. This is due to the way github creates its zip files and the way the IDE library manager works. The downloaded zip file and internal directory will have a name like hd44780-X.Y.Z which causes the sketchbook library name to also be hd44780-X.Y.Z While the IDE will usually allow this to work, the proper name should be simply "hd44780" and not using its real name can cause issues in the future.
To rename the library directory, simply go to the sketchbook library location and rename it. If you don't know where you sketchbook/libraries directory is simply click on: [File]->Preferences or from the keyboard type: <ctrl>comma (hold ctrl and press comma) The location of your sketchbook directory will be in the text box.
Use your favorite tool to rename it.

API Summary

The table below is a summary of all the available API functions in the hd44780 library.

Additional information about the API functions and how to use them can be found in the examples.

Function Description
LiquidCrystal API https://www.arduino.cc/en/Reference/LiquidCrystal
init(...) not supported
begin(cols, rows) initialize communication interface and LCD
backlight is turned on if supported
hd44780 extension: returns zero on success
clear() clear the display and home the cursor
hd44780 extension: returns zero on success
home() home the cursor
hd44780 extension: returns zero on success
setCursor(col, row) set cursor position
hd44780 extension: returns zero on success
write(data) send data byte to the display
returns 1 on success
write(*str) send C string to the display
returns characters written
write(*buffer, size) send size bytes to the display
returns characters written
returns size on success
print(...) print formatted data on the display
(from Print class)
returns characters output
println(...) not supported (from Print class)
cursor() turn on underline cursor
hd44780 extension: returns zero on success
noCursor() turn off/hide cursor
hd44780 extension: returns zero on success
blink() enable blinking at cursor position
hd44780 extension: returns zero on success
noBlink() disable blinking at cursor position
hd44780 extension: returns zero on success
display() enable pixels on display
hd44780 extension: returns zero on success
noDisplay() disable/hide pixels on display
hd44780 extension: returns zero on success
scrollDisplayLeft() shift display contents left
hd44780 extension: returns zero on success
scrollDisplayRight() shift display contents right
hd44780 extension: returns zero on success
autoscroll() enable left/right autoshifting for new characters
hd44780 extension: returns zero on success
noAutoscroll() disable left/right autoshifting
hd44780 extension: returns zero on success
leftToRight() write left to right, set autoshift to left
hd44780 extension: returns zero on success
rightToLeft() write right to left, set autoshift to right
hd44780 extension: returns zero on success
createChar(charval, charmap[]) create a custom character
hd44780 extension: returns zero on success
setRowOffsets(row0) set address for start of line
hd44780 extension: returns zero on success
setRowOffsets(row0, row1) set address for start of each line
hd44780 extension: returns zero on success
setRowOffsets(row0, row1, row2, row3) set address for start of each line
hd44780 extension: returns zero on success
command(cmd) send raw 8bit hd44780 command to LCD
hd44780 extension: returns zero on success
hd44780 extensions
Included in hd44780 but not part of LiquidCrytal or LCD 1.0 API
createChar(charval, charmap[]) create a custom character
(supports charmap in AVR PROGMEM)
returns zero on success
backlight() turn on backlight (max brightness)
returns zero on success
noBacklight() turn off backlight
returns zero on success
lineWrap() turn on automatic line wrapping
(wraps lines but does not scroll display)
returns zero on success
noLineWrap() turn off automatic line wrapping
returns zero on success
moveCursorLeft() move cursor one space to right
returns zero on success
moveCursorRight() move cursor one space to left
returns zero on success
read() read data byte from LCD
(requires r/w signal control)
returns negative value on failure
setExecTimes(chUs, insUs) configure clear/home and instruction/data times
LCD API 1.0 Functions http://playground.arduino.cc/Code/LCDAPI
setBacklight(dimvalue) set backlight brightness (0-255)
hd44780 extension: returns zero on success
setContrast(contvalue) set contrast (0-255)
hd44780 extension: returns zero on success
on() turn on LCD pixels and backlight
hd44780 extension: returns zero on success
off() turn off LCD pixels and backlight
hd44780 extension: returns zero on success
status() read hd44780 status byte (busy flag & address)
(requires r/w signal control)
returns negative value on failure
Deprecated LCD API 1.0 Functions
These exist in hd44780 but are deprecated
cmdDelay(CmdDelay, CharDelay) use setExecTimes() instead
cursor_on() use cursor() instead
hd44780 extension: returns zero on success
cursor_off() use noCursor() instead
hd44780 extension: returns zero on success
blink_on() use blink() instead
hd44780 extension: returns zero on success
blink_off() use noBlink() instead
hd44780 extension: returns zero on success
load_custom_character(char_num, Rows[]) use createChar() instead
hd44780 extension: returns zero on success
BROKEN LCD API 1.0 Functions
setCursor(row, col) row,col is backwards from Liquidcrystal;
therefore cannot be supported

Examples

Examples for the included hd44780 i/o classes are provided to demonstrate how to use LCDs with various h/w interfaces.
Each i/o class included in the hd44780 library package has its own examples.
You can access i/o class examples from the IDE from [File]->Examples->hd44780->ioClass and then choose the desired i/o class.
hd44780 also includes some examples that use other 3rd party LCD libraries rather than hd44780 which can be found under otherLibraries.
The sketches in the hd44780examples area are special purpose sketches that are used as include files for the i/o class examples. They should not be looked at as examples for how to use the library. While the hd44780examples sketches can be modified to work standalone with any LiquidCrystal API compatible library, their primary purpose, as shipped in the hd44780 library package, is to act as an include file for the i/o class wrapper sketches and are not intended to be used directly.
See the ioClass specific subdirectories for the examples for each ioClass.

See hd44780examples sketch along with the readme files under the examples directory and the wiki for additional information about the examples.
If browsing on the hd44780 github repository, you can click on the examples directory and its subdirectories to see each readme file.

Additional Information & Documentation

You can find additional information by using the included Documentation sketch.
Once the hd44780 library package is installed. It can be found in the IDE from [File]->Examples->Documentation
It provides hd44780 library information as well as links to further information including

CHANGELOG

[1.3.2] - 2020-11-15

[1.3.1] - 2020-08-10

[1.3.0] - 2020-07-01

[1.2.0] - 2020-06-03

[1.1.1] - 2020-03-28

[1.1.0] - 2019-08-12

[1.0.2] - 2019-05-21

[1.0.1] - 2018-08-06

[1.0.0] - 2018-06-24

[0.9.4] - 2018-06-12

[0.9.3] - 2018-02-11

[0.9.2] - 2018-02-04

[0.9.1] - 2018-01-06

[0.9.0] - 2017-05-12

[0.8.6] - 2017-05-11

[0.8.5] - 2017-04-29

[0.8.4] - 2017-03-05

[0.8.3] - 2017-01-08

[0.8.2] - 2016-12-26

[0.8.1] - 2016-11-12

[0.8.0] - 2016-11-01

[0.7.3] - 2016-10-23

[0.7.2] - 2016-09-21

[0.7.1] - 2016-08-20

[0.6.0] - 2016-08-08

[0.5.0-a] - 2016-07-30