Package: liquidcrystal-i2c-linux
LiquidCrystal_I2C-linuxThis repository is a python port of the ArduinoLiquidCrystal_I2Clibrary.With this library you can connect your I2C lcd to your linux box (using available GPIOs, but also via the I2C pins of yourVGA port) and control it like you did with the C++ library.Table of ContentsSupported devicesInstallationImplementationGetting StartedBasic commandsOther commandsSystemdContributionsThanksSupported devicesThis library by default will handle most common type of character lcds based on the Hitachi HD44780 with PCF8574 I2C backpack:40x2, 20x4, 20x2, 16x2, 16x1 (type 2), 16x4displays not supported by this:16x1 (type 1), This uses a discontigous memory for the single line
(It's not particularly difficult to make it work, but you have to use it as an 8x2 display)40x4 is dual 40x2 displays using dual E signals which is not supportedSee here for further explanation of lcd memory addressing:http://web.alfredstate.edu/weimandn/lcd/lcd_addressing/lcd_addressing_index.htmlInstallationUseraspi-configto enable the I2C interface (only for Raspberry Pi and similar boards)Enable i2c kernel modulesudomodprobei2c-devAdd your user to i2c groupsudousermod-a-Gi2c$(whoami)To apply group change, depending on the case, you may need to:Close and reopen your terminal window (if you are in a desktop environment)Log-out and log-in again in your tty session (if you use a computer without a desktop environment)Restart your ssh session (if you are connected to a remote device, maybe a Raspberry)List all available I2C busesls/dev/i2c-*Scan for devices on the first busi2cdetect-y0Connect your deviceScan again the same bus and look for new devices. If you see a new device you're done, otherwise repeat from step 4, scanning the other available buses until you find your device. (each bus corresponds to a physical connection so, if you change the device, you don't need to scan all the buses)If you still can't find it try checking the cables and trying again.Installing the librarypython3-mpipinstallliquidcrystal_i2c-linuxImplementationGetting StartedBasic commands:Initializationfromliquidcrystal_i2cimportLCDInitialize the lcd using bus and address you found before.If cols and rows are not specified, library assumes 16x2.lcd=LCD(bus=1,addr=0x3e,cols=16,rows=2)At this point the lcd is already cleared and the cursor set to home, so we don't need to call lcd.clear() and lcd.home() again.However when you need to clear all and place the cursor at 0,0 use:lcd.clear()lcd.home()PrintingPlace the cursor where you want to print (remember numbers start from zero so 0 will be the first column/row).lcd.setCursor(3,1)lcd.print("Hello, world!")Printing special charactersThanks toThe Raspberry Pi guy'slibrarywe have two methods to print special characters:classic LiquidCrystal_I2C waylcd.setCursor(2,1)lcd.write(0xF7)#prints π symbolnew The Raspberry Pi guy's waylcd.setCursor(2,1)lcd.printExt("Hello{0xF7}")Warning: if you use this method with stringformatyou need to escape the placeholder using double curly brackets.lcd.setCursor(2,1)lcd.printExt("Hello {{0xF7}} ={0}".format(3.14))Printing custom charactersThe HD44780 allows to define 8 custom characters that you can load in CGRAM and call like any other special character.
The 8 character slots are numbered from 0 to 7, their placeholders are obviously{0x00},{0x01},{0x02},{0x03},{0x04},{0x05},{0x06},{0x07}.# define custom character bitmap# you can design the character using https://maxpromer.github.io/LCD-Character-Creator/ but keep in mind that byte definitions are different between C++ and Pythoncustom_char_cpu=[0b01010,0b11111,0b10001,0b10101,0b10001,0b11111,0b01010,0b00000]# now it's time to load the character# we will use slot 3lcd.createChar(3,custom_char_cpu)# print the character as all special characterslcd.setCursor(0,0)lcd.printExt("This is a CPU:{0x03}")Other commands:Turn backlight on/offlcd.backlight()lcd.noBacklight()Show/hide cursorlcd.cursor()lcd.noCursor()Turn cursor blinking on/off (needs cursor to be enabled)lcd.blink()lcd.noBlink()Show hide all textlcd.display()lcd.noDisplay()Scroll the entire display by one place left/right without resending stringslcd.scrollDisplayLeft()lcd.scrollDisplayRight()Set autoscroll on/offlcd.autoscroll()lcd.noAutoscroll()Set writing directionlcd.leftToRight()lcd.rightToLeft()SystemdUse the following procedure to run any LCD Python script as a (systemd) service:Create a new unit file in/lib/systemd/system/calledi2c-lcd.service:sudonano/lib/systemd/system/i2c-lcd.serviceCopy and paste the following in the new unit file:[Unit]Description=Pythonscriptforanhd44780LCD[Service]Type=simple## Edit the following according to the script permissionsUser=<YOUR-USERNAME>#Group=users## Edit the following with the full path to your scriptExecStart=/usr/bin/python3/path/to/script.pyRestart=alwaysRestartSec=5KillMode=processKillSignal=SIGINT[Install]WantedBy=multi-user.targetEnable the service and start it:sudosystemctlenablei2c-lcd.service
sudosystemctlstarti2c-lcd.serviceCheck that the LCD is displaying the correct information; otherwise, check the service status:systemctlstatusi2c-lcd.serviceThanksI'd like to thank the creators of the C++ library for their awesome work, andThe Raspberry Pi guyfor theprintExtfunction, derived from hislcd_display_extended_string.