{"id":27771419,"url":"https://github.com/the-raspberry-pi-guy/lcd","last_synced_at":"2025-04-29T22:39:16.844Z","repository":{"id":36596801,"uuid":"40902832","full_name":"the-raspberry-pi-guy/lcd","owner":"the-raspberry-pi-guy","description":"This repository contains all of the code for interfacing with a 16x2 Character I2C LCD Display. This accompanies my YouTube tutorial here: https://www.youtube.com/watch?v=fR5XhHYzUK0","archived":false,"fork":false,"pushed_at":"2024-08-12T15:34:28.000Z","size":23382,"stargazers_count":195,"open_issues_count":4,"forks_count":110,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-29T22:38:57.326Z","etag":null,"topics":["lcd","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/the-raspberry-pi-guy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2015-08-17T14:47:50.000Z","updated_at":"2025-04-18T09:45:14.000Z","dependencies_parsed_at":"2024-06-27T20:14:16.347Z","dependency_job_id":null,"html_url":"https://github.com/the-raspberry-pi-guy/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/the-raspberry-pi-guy%2Flcd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/the-raspberry-pi-guy%2Flcd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/the-raspberry-pi-guy%2Flcd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/the-raspberry-pi-guy%2Flcd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/the-raspberry-pi-guy","download_url":"https://codeload.github.com/the-raspberry-pi-guy/lcd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251596590,"owners_count":21615011,"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":["lcd","raspberry-pi"],"created_at":"2025-04-29T22:39:16.102Z","updated_at":"2025-04-29T22:39:16.817Z","avatar_url":"https://github.com/the-raspberry-pi-guy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LCD\n\nThis repository contains all the code for interfacing with a **16x2 character I2C liquid-crystal display (LCD)**. This accompanies my **Youtube tutorial**: [Raspberry Pi - Mini LCD Display Tutorial](https://www.youtube.com/watch?v=fR5XhHYzUK0).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=fR5XhHYzUK0\"\u003e\n    \u003cimg src=\"imgs/thumb-yt-rpiguy-lcd-tutorial.png\" width=\"80%\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nYou can buy one of these great little I2C LCD on eBay or somewhere like [the Pi Hut](https://thepihut.com/search?type=product\u0026q=lcd).\n\n## Table of Contents\n\n1. [Installation](#installation)\n1. [Demos](#demos)\n   - [Backlight control](#backlight-control)\n   - [Custom characters](#custom-characters)\n   - [Extended strings](#extended-strings)\n   - [Forex](#forex)\n   - [Home automation](#home-automation)\n   - [IP address](#ip-address)\n   - [LCD demo](#lcd-demo)\n   - [NetMonitor](#netmonitor)\n   - [Progress bar](#progress-bar)\n   - [Tiny Dashboard](#tiny-dashboard)\n1. [Implementation](#implementation)\n   - [Systemd](#systemd)\n1. [Contributions](#contributions)\n\n## Installation\n\n- Install git\n\n  ```sh\n  sudo apt install git\n  ```\n\n- Clone the repo in your home directory\n\n  ```sh\n  cd /home/${USER}/\n  git clone https://github.com/the-raspberry-pi-guy/lcd.git\n  cd lcd/\n  ```\n\n- Run the automatic installation script with `sudo` permission\n\n  ```sh\n  sudo ./install.sh\n  ```\n\n- During the installation, pay attention to any messages about `python` and `python3` usage, as they inform which version you should use to interface with the LCD driver.  For example:\n\n  ```txt\n  [LCD] [INFO] You may use either 'python' or 'python3' to interface with the lcd.\n  ```\n\n  or alternatively,\n\n  ```txt\n  [LCD] [INFO] Use 'python3' to interface with the lcd.\n  ```\n\n- At the end of the installation script, you'll be prompted to reboot the RPi to apply the changes made to `/boot/config.txt` and `/etc/modules`.\n\n- After rebooting, try one of the [**demos**](#demos):\n\n  ```sh\n  ./home/${USER}/lcd/demo_clock.py\n  ```\n\n  or\n\n  ```sh\n  python /home/${USER}/lcd/demo_clock.py\n  ```\n\n  or\n\n  ```sh\n  python3 /home/${USER}/lcd/demo_clock.py\n  ```\n\n[top :arrow_up:](#table-of-contents)\n\n## Demos\n\nA list of demonstration (demo) files that illustrate how to use the LCD driver.  Demos are ordered alphabetically.\n\n### Backlight Control\n\n- Author: [@Tomtom0201](https://github.com/Tomtom0201)\n\nThis demo showcases the backlight control of the LCD, which is available on some hardware:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_backlight.gif\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### Custom characters\n\n- Author: [@juvus](https://github.com/juvus)\n\nIt is possible to define in CG RAM memory up to 8 custom characters. These characters can be prompted on LCD the same way as any characters from the [characters table](imgs/characters_table.png). Codes for the custom characters are unique and as follows:\n\n  1. `{0x00}`\n  2. `{0x01}`\n  3. `{0x02}`\n  4. `{0x03}`\n  5. `{0x04}`\n  6. `{0x05}`\n  7. `{0x06}`\n  8. `{0x07}`\n\nPlease, see the comments and implementation in the [`demo_lcd_custom_characters.py`](demo_lcd_custom_characters.py) file for more details on how to use custom characters. Thanks to [@Jumitti](https://github.com/Jumitti), there is also [a web app you can use to generate custom characters](https://custom-characters-for-lcd16x2.streamlit.app/) by drawing them on a matrix.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_custom_characters.jpg\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### Extended strings\n\n- Author: [@juvus](https://github.com/juvus)\n\nThis is demo showcases how extended strings could be used. Extended strings can contain special placeholders of form `{0xFF}`, that is, a hex code of the symbol wrapped within curly brackets. Hex codes of various symbols can be found in the following characters table:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/characters_table.png\" width=\"50%\"\u003e\n\u003c/p\u003e\n\nFor example, the hex code of the symbol `ö` is `0xEF`, and so this symbol could be printed on the second row of the display by using the `{0xEF}` placeholder, as follows:\n\n```Python\ndisplay.lcd_display_extended_string(\"{0xEF}\", 2)\n```\n\nIf you want to combine placeholder to write a symbol `{0xFF}` with the native Python placeholder `{0}` for inserting dome data into text, escape the non-native placeholders. Here is an example:\n\n```Python\ndisplay.lcd_display_extended_string(\"Symbol:{{0xEF}} data:{0}\".format(5), 2)\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_extended_strings.jpg\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### Forex\n\n- Author: [@bariskisir](https://github.com/bariskisir)\n- Additional Python package requirements: `pip`, `requests`, `bs4`\n\nTo install the requirements, follow this procedure:\n\n- Install `pip` and use it to install the remaining packages\n\n    ```sh\n    sudo apt install python-pip\n    pip install requests bs4\n    ```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_forex.gif\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### Home Automation\n\n- Author: [@Jumitti](https://github.com/Jumitti)\n- Repository: [Jumitti/lcd_home_automation](https://github.com/Jumitti/lcd_home_automation)\n\nThis implementation shows how to use the LCD to display messages from temperature sensors and services such as Spotify and Trakt (see below). The implementation also features an integration with Telegram to turn the LCD backlight on/off and send a few other commands to control the host machine (e.g., get the temperature, reboot, shutdown). [@Jumitti](https://github.com/Jumitti) documented the project on its own [Home Automation repository](https://github.com/Jumitti/lcd_home_automation), so make sure to check it out if you want to learn more about it.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_home_automation.gif\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### IP Address\n\n- Author: [@Sierra007117](https://github.com/Sierra007117)\n\nDisplay your Pi's IP address, which is useful for `SSH` access and more!\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_ip.jpg\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### LCD demo\n\n- Author: [@Tomtom0201](https://github.com/Tomtom0201)\n\nThis demo shows how simple strings could be displayed on the LCD.  For extended usage, take a look at [Extended strings](#extended-strings) demo instead.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_simple_strings.jpg\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### NetMonitor\n\n- Author: [@cgomesu](https://github.com/cgomesu)\n\nThis demo uses `ping` and `nc` (netcat) to monitor the network status of hosts and services, respectively. Hosts and services can be modified by editing their respective [dictionaries](https://docs.python.org/3/tutorial/datastructures.html#dictionaries):\n\n```Python\nhosts = {\n    'Internet': '8.8.8.8',\n    'Firewall': '192.168.1.1',\n    'NAS': '192.168.1.2'\n}\nservices = {\n    'Cameras': {'ip': '192.168.1.2', 'port': '8000'},\n    'Plex': {'ip': '192.168.1.2', 'port': '32400'}\n}\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_netmonitor.gif\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### Progress bar\n\n- Author: [@juvus](https://github.com/juvus)\n\nThis is a demo of a graphical progress bar created with [custom characters](#custom-characters). This bar could be used, for example, for showing the current level of battery charge.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_progress_bar.jpg\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### Tiny dashboard\n\n- Author: [@jdarias](https://github.com/jdarias)\n\nThis is a script that shows a famous quote, a currency conversion pair of your choice and the weather of a city. It also shows the last three characters from your ip address, the date in DDMM format and the hour in HH:MM format\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/demo_tiny_dashboard.gif\" width=\"50%\"\u003e\n\u003c/p\u003e\n\nThe script takes info from the following APIs:\n\n- [quotable.io](https://github.com/lukePeavey/quotable): Free public API that provides famous quotes from well known people. It has a public endpoint that doesn't require an API key.\n\n- [exchangerate-api.com](https://exchangerate-api.com) / [free.currencyconverterapi.com](https://free.currencyconverterapi.com): There are a lot of currency apis but these ones offer free currency exchange info. Both are used, one as main, the other as backup. Requires an API key to use.\n\n- [openweathermap.org](https://openweathermap.org): Provides Weather info, forecasts, etc. Requires an API key to use.\n\nIn order to use the script, you need to get **API key tokens for both exchange rate services and the weather api**. Once you've done that, edit the script to put your tokens in the USER VARIABLES section.\n\nAlso set a currency exchange pair. For currency support and the currency codes you need to use, see [exchangerate-api.com/docs/supported-currencies](https://www.exchangerate-api.com/docs/supported-currencies).\n\nA city/country string is also needed to show weather info for such city. Search for your city on [openweathermap.org](https://openweathermap.org) and take note of the `City,country` string and put it in the script.`London,gb` is given as an example.\n\n[top :arrow_up:](#table-of-contents)\n\n## Implementation\n\nOnce you are done editing a `demo_*.py` file or writing your own Python script, follow the instructions on this section to run the script in the background. First, however, ensure that the script (e.g., `script.py`) has at least permission to be executed, as follows:\n\n```sh\nsudo chmod +x script.py\n```\n\nSimilarly, file ownership can be configured via `chown`.  For example, to set the user `${USER}` as owner of the file `script.py`, run the following:\n\n```sh\nsudo chown ${USER} script.py\n```\n\n## Systemd\n\nUse the following procedure to run any LCD Python script as a (systemd) service:\n\n1. Create a new unit file in `/lib/systemd/system/` called `rpi-lcd.service`:\n\n   ```sh\n   sudo nano /lib/systemd/system/rpi-lcd.service\n   ```\n\n2. Copy and paste the following in the new unit file:\n\n   (*If your user is different than `pi`, remember to edit the `User=` entry.*)\n\n   ```sh\n   [Unit]\n   Description=RPi Python script for a 16x2 LCD\n\n   [Service]\n   Type=simple\n   ## Edit the following according to the script permissions\n   User=pi\n   #Group=users\n\n   ## Edit the following with the full path to the compatible Python version and your script\n   ExecStart=/usr/bin/python /path/to/script.py\n\n   Restart=always\n   RestartSec=5\n\n   KillMode=process\n   KillSignal=SIGINT\n\n   [Install]\n   WantedBy=multi-user.target\n   ```\n\n3. Enable the service and start it:\n\n   ```sh\n   sudo systemctl enable rpi-lcd.service\n   sudo systemctl start rpi-lcd.service\n   ```\n\n4. Check that the LCD is displaying the correct information; otherwise, check the service status:\n\n   ```sh\n   systemctl status rpi-lcd.service\n   ```\n\n[top :arrow_up:](#table-of-contents)\n\n## Contributions\n\nThank you for you interest in learning how to contribute to this repository.  We welcome contributions from novices to experts alike, so do not be afraid to give it a try if you are new to `git` and GitHub.  First, however, take a few minutes to read our [CONTRIBUTING.md](CONTRIBUTING.md) guide to learn how to open **Issues** and the various sorts of **Pull Requests (PRs)** that are currently accepted.\n\nIn addition, if you've never contributed to an open source project before, please take a look at the following resources:\n\n- [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github)\n- [Proposing changes to your work with pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests)\n\n[top :arrow_up:](#table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-raspberry-pi-guy%2Flcd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthe-raspberry-pi-guy%2Flcd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-raspberry-pi-guy%2Flcd/lists"}