i2c4lcd - Controller for HD44780 Compatible LCDs

i2c4lcd allows you to easily control HD44780 compatible LCDs via port expander modules with the PCF8574 IC. This is primarily designed for Raspberry Pi. You will need to have installed python-smbus and i2c-tools.

Getting Started

Pi Setup

Using this for the Pi, you will need to enable automatic loading of I2C Kernal module. There are plenty of tutorials out there on how to do this.

Make the following connections from the Pi your port expander module:

• GND -- GND
  
• 5V -- VCC
  
• GPIO2 -- SDA
  
• GPIO3 -- SCL

Edit the Pi's /etc/modules file with:

sudo nano /etc/modules

and add the following lines, if they've not already been added (this will enable these modules at boot):

i2c-bcm2708
i2c-dev

Instsallation

As mentioned you will need to install smbus and i2c-tools:

sudo apt-get install python-smbus
sudo apt-get install i2c-tools

Clone the repository:

git clone https://github.com/nichnet/i2c4lcd.git

Usage

python i2c4lcd.py -m <message> -l <line number> -a <text align (l|c|r)> -c <clear current display> -f <flash backlight>

Simple Single String

python i2c4lcd.py -m "Hello World" -l 2 -a c

The display will be appended to without using the clear argument by default. This can be overwritten by setting the default in the user settings field:

CLEAR_DISPLAY_DEFAULT = True

python i2c4lcd.py -m '"Hello World!" -l 3 -a c

Text Alignment

The text alignment can be set. If no argument is provided, the text will be left aligned by default. You can set the alignment to "l" for left, "c" for center, and "r" for right alignment.

Below is an example calling the script with center alignment:

python i2c4lcd.py -m "Hello World" -l 2 -a c

Multi-line Input

python i2c4lcd.py -m '["Hello World!", "How are you?"]' -c

Display Flashing

When writing to the display, the display can be instructed to flash to prompt/notify the user. Flash speed and count can be overwritten in the user settings field:

BACKLIGHT_FLASH_COUNT = 3
BACKLIGHT_FLASH_SPEED = 0.25 # 25ms

python i2c4lcd.py -m "Hello World!" -l 2 -a c -f

You can also override whether the backlight should be on or off by default in the user settings field. This is enabled by default:

BACKLIGHT_DEFAULT_STATE = True

Issues You May Face

You may run into a runtime error, this could be due to a memory address mismatch. Ensure your connection is proper and if the issue persists, run the following command to probe for devices:

sudo i2cdetect 0

or

sudo i2cdetect 1

depending on your Pi version.

Running this will immediately scan i2c bus 0 or 1 and return which memory address the device is located at. Update the user settings field as follows:

I2C_ADDRESS = 0x27 # i2c device address (other typical address would be 0x3f)

Extras

To interface with node.js, click here

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

GNU General Public License v3.0