{"id":13613195,"url":"https://github.com/dhylands/python_lcd","last_synced_at":"2025-04-05T16:09:14.437Z","repository":{"id":12509755,"uuid":"15179441","full_name":"dhylands/python_lcd","owner":"dhylands","description":"Python based library for talking to character based LCDs.","archived":false,"fork":false,"pushed_at":"2023-02-17T04:50:13.000Z","size":92,"stargazers_count":319,"open_issues_count":18,"forks_count":116,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-29T15:09:04.135Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhylands.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2013-12-14T03:35:12.000Z","updated_at":"2025-03-16T03:28:16.000Z","dependencies_parsed_at":"2024-01-29T19:30:24.651Z","dependency_job_id":null,"html_url":"https://github.com/dhylands/python_lcd","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhylands%2Fpython_lcd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhylands%2Fpython_lcd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhylands%2Fpython_lcd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhylands%2Fpython_lcd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhylands","download_url":"https://codeload.github.com/dhylands/python_lcd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361691,"owners_count":20926643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T20:00:41.357Z","updated_at":"2025-04-05T16:09:14.412Z","avatar_url":"https://github.com/dhylands.png","language":"Python","readme":"lcd_api and i2c_lcd\n===============\n\nPython code for talking to HD44780 compatible character based dot matrix LCDs.\n\n## Other ports\n\nThis code is synchronous. Peter Hinch put together an async driver for\nthe HD77480 over [here](https://github.com/peterhinch/micropython-async/tree/master/v3/as_drivers/hd44780).\n\nThis library is based off of a C version that I wrote, which can be found\n[here](https://github.com/dhylands/projects/blob/master/common/lcd-api.c)\n(also look for files in the same directory which start with lcd).\n\nNic created a C# port of this library which can be found [here](https://github.com/OfItselfSo/CS_LCD).\n\n## Communicating with the LCD\n\nYou can communicate with the LCDs using either 4 or 8 GPIO pins.\n\nAlternatively, the I2C classes implement 8-bit GPIO expander boards\n[PCF8574](http://www.ti.com/lit/ds/symlink/pcf8574.pdf) and\n[MCP23008](http://www.microchip.com/wwwproducts/en/MCP23008)\nwhich reduces the number of required GPIO pins to two (SCL, SDA).\nThe boards usually mount behind the LCDs and are commonly called \"backpacks\".\n\nThe most commonly used display is a \"1602\" or \"16x2\", which features 16 columns\nand 2 rows of characters. There are also other LCDs using the same HD44780\ncontroller. eg. 8x2, 16x1, 16x4, 20x2, 20x4, 40x1, 40x2. Each come in various\nbacklight and pixel colours.\n\nThere are also variants of the code for [MicroPython](http://micropython.org/).\nAll of the files which start with **pyb_** were tested on the\n[pyboard](https://store.micropython.org/store/#/products/PYBv1_1).\nFiles starting with **esp8266_** were tested on a\n[WeMos D1 Mini](https://www.wemos.cc/product/d1-mini.html).\nFiles starting with **nodemcu_** were tested on a\n[NodeMCU development board](https://en.wikipedia.org/wiki/NodeMCU).\nThe files containing **adafruit_lcd** were tested on an Adafruit\n[I2C / SPI character LCD backpack](https://www.adafruit.com/product/292)\n\n## Installing CPython\n\n### Cpython 3.x\n\n    # python smbus needs dev headers\n    sudo apt update\n    sudo apt install python3-dev\n    python -m pip install smbus  # optional, good test before installing library\n    python -m pip install -e .\n\n\n### Cpython 2.7\n\n    # python smbus needs dev headers\n    sudo apt update\n    sudo apt install python2-dev\n    python -m pip install smbus  # optional, good test before installing library\n    python -m pip install -e .\n\n\n## Tutorial\n\nGiuseppe Cassibba wrote up a [tutorial](https://peppe8o.com/using-i2c-lcd-display-with-raspberry-pi-pico-and-micropython) which demonstrates connecting an I2C LCD to a Raspberry Pi Pico.\n\n## Files\n\n| File                          | Description                               |\n| -----                         | -----------                               |\n| circuitpython_i2c_lcd.py      | CircuitPython PCF8574 I2C backpack        |\n| circuitpython_i2c_lcd_test.py | CircuitPython test using PCF8574 backpack |\n| esp32_gpio_lcd.py             | ESP32 GPIO HAL                            |\n| esp32_gpio_lcd_test.py        | ESP32 test using 4-bit GPIO               |\n| esp8266_i2c_lcd.py            | ESP8266 PCF8574 I2C HAL                   |\n| esp8266_i2c_lcd_test.py       | ESP8266 test using PCF8574 backpack       |\n| i2c_lcd.py                    | Linux PCF8574 I2C HAL                     |\n| i2c_lcd_test.py               | Linux test using PCF8574 backpack         |\n| lcd_api.py                    | Core logic                                |\n| machine_i2c_lcd.py            | Pyboard machine.I2C PCF8574 backpack      |\n| machine_i2c_lcd_test.py       | Test for machine.I2C PCF8574 backpack     |\n| nodemcu_gpio_lcd.py           | NodeMCU GPIO HAL                          |\n| nodemcu_gpio_lcd_test.py      | NodeMCU test using 4-bit GPIO             |\n| onion_lcd_gpio.py             | Onion GPIO HAL                            |\n| onion_lcd_gpio.py             | Ontion test using 4 bit GPIO              |\n| pyb_gpio_lcd.py               | Pyboard GPIO HAL                          |\n| pyb_gpio_lcd_test8.py         | Pyboard test using 8-bit GPIO             |\n| pyb_gpio_lcd_test.py          | Pyboard test using 4-bit GPIO             |\n| pyb_i2c_adafruit_lcd.py       | Pyboard MCP23008 I2C HAL                  |\n| pyb_i2c_adafruit_lcd_test.py  | Pyboard test using Adafruit backpack      |\n| pyb_i2c_grove_rgb_lcd.py      | Pyboard Grove I2C RGB LCD HAL             |\n| pyb_i2c_grove_rgb_lcd_test.py | Pyboard test using Grove I2C RGB LCD      |\n| pyb_i2c_lcd.py                | Pyboard PCF8574 I2C HAL                   |\n| pyb_i2c_lcd_test.py           | Pyboard test using PCF8574 backpack       |\n\n\nThe files which end in **_test.py** are examples which show how the corresponding\nfile is used.\n\n**i2c_lcd.py** was tested on a [BeagleBone Black](https://beagleboard.org/black) using a 2 x 16 LCD with an I2C\nmodule similar to [this one](http://arduino-info.wikispaces.com/LCD-Blue-I2C).\n\nTo install on your BBB:\n```bash\ngit clone https://github.com/dhylands/python_lcd.git\ncd python_lcd\nsudo pip install -e .\n```\n\nAnd to test:\n```bash\nsudo lcd/i2c_lcd_test.py\n```\n\nSince my LCD was a 5v device, I used a level converter to convert from BBB's\n3.3v to the LCD's 5v.\n\nI put together some\n[photos here] (https://picasaweb.google.com/115853040635737241756/PythonI2CLCD?authkey=Gv1sRgCLyZoJ3_uPjiXA)\n\nComing from the BeagleBone Black the wire colors are:\n\n| Color  | Pin   | Name   |\n| ------ | ----- | ------ |\n| Black  | P9-1  | GND    |\n| Red    | P9-3  | 3.3v   |\n| Orange | P9-7  | SYS_5V |\n| Yellow | P9-19 | SCL    |\n| White  | P9-20 | SDA    |\n\nThe photo shows Orange connected to P9-5. I discovered that P9-7 is controlled\nby the onboard voltage regulators, so when you do a \"sudo poweroff\" then\nSYS_5V drops to 0v when the BBB is powered off. P9-5 (VDD_5V) remains at\n5v after the BBB is powered off.\n\nAnd the colors going to the LCD are:\n\n| Color  | Name |\n| ------ | ---- |\n| Black  | GND  |\n| Red    | 5v   |\n| White  | SDA  |\n| Yellow | SCL  |\n\nI used a [SparkFun level shifter](https://www.sparkfun.com/products/8745)\n(this particular model is no longer available).\n\nSome examples of other level shifters which could be used:\n* [Logic Level Converter](https://www.sparkfun.com/products/11978)\n* [Logic Level Converter Bi-Directional](https://www.sparkfun.com/products/12009)\n* [Voltage-Level Translator - TXB0104 Breakout](https://www.sparkfun.com/products/11771)\n* [PCA9306 Level Translator Breakout](https://www.sparkfun.com/products/11955)\n* [4-channel I2C-safe Bi-directional Logic Level Converter - BSS138](http://www.adafruit.com/products/757)\n* [8-channel Bi-directional Logic Level Converter - TXB0108](http://www.adafruit.com/products/395)\n\nI found a circuit mentioned in [this Google+ post](https://plus.google.com/101619328411109842819/posts/5dPjmvRwhXH)\nand thought I would include it here, since it's related to the LCDs these drivers interface with.\n![LCD Schematic](/simplest-lcd-supply.png)\n\nThe circuit allows for digitally controlling the contrast via PWM and also controlling\nthe backlight brightness via PWM.\n\n## Custom characters\n\nThe HD44780 displays come with 3 possible CGROM font sets. Japanese, European and Custom.\nTest which you have using:\n\n```\nlcd.putchar(chr(247))\n```\n\nIf you see Pi (π), you have a Japanese A00 ROM.\nIf you see a division sign (÷), you have a European A02 ROM.\n\nCharacters match ASCII characters in range 32-127 (0x20-0x7F) with a few exceptions:\n\n* 0x5C is a Yen symbol instead of backslash\n* 0x7E is a right arrow instead of tilde\n* 0x7F is a left arrow instead of delete\n\nOnly the ASCII characters are common between the two ROMs 32-125 (0x20-0x7D)\nRefer to the HD44780 datasheet for the table of characters.\n\nThe first 8 characters are CGRAM or character-generator RAM.\nYou can specify any pattern for these characters.\n\nTo design a custom character, start by drawing a 5x8 grid.\nI use dots and hashes as it's a lot easier to read than 1s and 0s.\nDraw pixels by replacing dots with hashes.\nWhere possible, leave the bottom row unpopulated as it may be occupied by the underline cursor.\n\n```\nHappy Face (where .=0, #=1)\n.....\n.#.#.\n.....\n..#..\n.....\n#...#\n.###.\n.....\n```\n\nTo convert this into a bytearray for the custom_char() method, you need to add each row of 5 pixels to least significant bits of a byte (the right side).\n\n```\nHappy Face (where .=0, #=1)\n..... == 0b00000 == 0x00\n.#.#. == 0b01010 == 0x0A\n..... == 0b00000 == 0x00\n..#.. == 0b00100 == 0x04\n..... == 0b00000 == 0x00\n#...# == 0b10001 == 0x11\n.###. == 0b01110 == 0x0E\n..... == 0b00000 == 0x00\n```\n\nNext, add each byte from top to bottom to a new byte array and pass to custom_char() with location 0-7.\n\n```\nhappy_face = bytearray([0x00,0x0A,0x00,0x04,0x00,0x11,0x0E,0x00])\nlcd.custom_char(0, happy_face)\n```\n\n`custom_char()` does not print anything to the display. It only updates the CGRAM.\nTo display the custom characters, use putchar() with chr(0) through chr(7).\n\n```\nlcd.putchar(chr(0))\nlcd.putchar(b'\\x00')\n```\n\nCharacters are displayed by reference.\nOnce you have printed a custom character to the lcd, you can overwrite the custom character and all visible instances will also update.\nThis is useful for drawing animations and graphs, as you only need to print the characters once and then can simply modify the custom characters in CGRAM.\n\nExamples:\n\n```\n# smiley faces\nhappy = bytearray([0x00,0x0A,0x00,0x04,0x00,0x11,0x0E,0x00])\nsad = bytearray([0x00,0x0A,0x00,0x04,0x00,0x0E,0x11,0x00])\ngrin = bytearray([0x00,0x00,0x0A,0x00,0x1F,0x11,0x0E,0x00])\nshock = bytearray([0x0A,0x00,0x04,0x00,0x0E,0x11,0x11,0x0E])\nmeh = bytearray([0x00,0x0A,0x00,0x04,0x00,0x1F,0x00,0x00])\nangry = bytearray([0x11,0x0A,0x11,0x04,0x00,0x0E,0x11,0x00])\ntongue = bytearray([0x00,0x0A,0x00,0x04,0x00,0x1F,0x05,0x02])\n\n# icons\nbell = bytearray([0x04,0x0e,0x0e,0x0e,0x1f,0x00,0x04,0x00])\nnote = bytearray([0x02,0x03,0x02,0x0e,0x1e,0x0c,0x00,0x00])\nclock = bytearray([0x00,0x0e,0x15,0x17,0x11,0x0e,0x00,0x00])\nheart = bytearray([0x00,0x0a,0x1f,0x1f,0x0e,0x04,0x00,0x00])\nduck = bytearray([0x00,0x0c,0x1d,0x0f,0x0f,0x06,0x00,0x00])\ncheck = bytearray([0x00,0x01,0x03,0x16,0x1c,0x08,0x00,0x00])\ncross = bytearray([0x00,0x1b,0x0e,0x04,0x0e,0x1b,0x00,0x00])\nretarrow = bytearray([0x01,0x01,0x05,0x09,0x1f,0x08,0x04,0x00])\n\n# battery icons\nbattery0 = bytearray([0x0E,0x1B,0x11,0x11,0x11,0x11,0x11,0x1F])  # 0% Empty\nbattery1 = bytearray([0x0E,0x1B,0x11,0x11,0x11,0x11,0x1F,0x1F])  # 16%\nbattery2 = bytearray([0x0E,0x1B,0x11,0x11,0x11,0x1F,0x1F,0x1F])  # 33%\nbattery3 = bytearray([0x0E,0x1B,0x11,0x11,0x1F,0x1F,0x1F,0x1F])  # 50%\nbattery4 = bytearray([0x0E,0x1B,0x11,0x1F,0x1F,0x1F,0x1F,0x1F])  # 66%\nbattery5 = bytearray([0x0E,0x1B,0x1F,0x1F,0x1F,0x1F,0x1F,0x1F])  # 83%\nbattery6 = bytearray([0x0E,0x1F,0x1F,0x1F,0x1F,0x1F,0x1F,0x1F])  # 100% Full\nbattery7 = bytearray([0x0E,0x1F,0x1B,0x1B,0x1B,0x1F,0x1B,0x1F])  # ! Error\n```\n\nAn online editor for creating customer characters is available online at https://clach04.github.io/lcdchargen/ (source code available from https://github.com/clach04/lcdchargen/tree/python)\n","funding_links":[],"categories":["Libraries","精选驱动库"],"sub_categories":["Display","显示类"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhylands%2Fpython_lcd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhylands%2Fpython_lcd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhylands%2Fpython_lcd/lists"}