hd44780-linux 0.0.1
A library to interface with hd44780 via I2C

# HD44780-linux
This repository is a fork of [Matt Timmons-Brown (Raspberry Pi Guy)](https://github.com/the-raspberry-pi-guy)'s [lcd](https://github.com/the-raspberry-pi-guy/lcd) library and allows interfacing a generic linux device with an **HD44780 liquid-crystal display (LCD)** via I2C.

As with the original library you can drive an LCD via the I2C pins of a Raspberry Pi, but also via the I2C pins of your [VGA port](https://dave.cheney.net/tag/hd44780).

# Table of Contents
1. [Supported devices](#supported-devices)
2. [Installation](#Installation)
3. [Demos](#demos)
   - [Backlight control](#backlight-control)
   - [Custom characters](#custom-characters)
   - [Extended strings](#extended-strings)
   - [Forex](#forex)
   - [IP address](#ip-address)
   - [LCD](#lcd-1)
   - [NetMonitor](#netmonitor)
   - [Progress bar](#progress-bar)
4. [Implementation](#Implementation)
   - [Systemd](#systemd)
5. [Contributions](#contributions)
6. [Thanks](#thanks)

# Supported devices
  This 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), 16x4

  displays 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 supported

  See here for further explanation of lcd memory addressing:
  http://web.alfredstate.edu/weimandn/lcd/lcd_addressing/lcd_addressing_index.html


# Installation
0. Use `raspi-config` to enable the I2C interface (only for Raspberry Pi and similar boards)

1. Enable i2c kernel module
  ```sh
  sudo modprobe i2c-dev
  ```

2. Add your user to i2c group
  ```sh
  sudo usermod -a -G i2c $(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)

3. List all available I2C buses
  ```sh
  ls /dev/i2c-*
  ```

4. Scan for devices on the first bus
  ```sh
  i2cdetect -y 0
  ```

5. Connect your device

6. Scan 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)<br>If you still can't find it try checking the cables and trying again.

7. Installing the library
  ```sh
  python3 -m pip install hd44780-linux
  ```

8. Start trying one of the [**demos**](#demos)

[top :arrow_up:](#)

# Demos
A list of demonstration (demo) files that illustrate how to use the LCD driver. Demos inside `test/` folder are ordered alphabetically.

## Backlight Control
- Author: [@Tomtom0201](https://github.com/Tomtom0201)

This demo showcases the backlight control of the LCD, which is available on some hardware:

<p align="center">
  <img src="imgs/demo_backlight.gif" width="50%">
</p>

## Custom characters
- Author: [@juvus](https://github.com/juvus)

It 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:

  1. `{0x00}`
  2. `{0x01}`
  3. `{0x02}`
  4. `{0x03}`
  5. `{0x04}`
  6. `{0x05}`
  7. `{0x06}`
  8. `{0x07}`

Please, 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.

<p align="center">
  <img src="imgs/demo_custom_characters.jpg" width="50%">
</p>

## Extended strings
- Author: [@juvus](https://github.com/juvus)

This 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:

<p align="center">
  <img src="imgs/characters_table.png" width="50%">
</p>

For 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:

```Python
display.lcd_display_extended_string("{0xEF}", 2)
```

If 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:

```Python
display.lcd_display_extended_string("Symbol:{{0xEF}} data:{0}".format(5), 2)
```

<p align="center">
  <img src="imgs/demo_extended_strings.jpg" width="50%">
</p>

## Forex
- Author: [@bariskisir](https://github.com/bariskisir)
- Additional Python package requirements: `pip`, `requests`, `bs4`

To install the requirements, follow this procedure:
  - Install `pip` and use it to install the remaining packages
    ```sh
    sudo apt install python-pip
    pip install requests bs4
    ```

<p align="center">
  <img src="imgs/demo_forex.gif" width="50%">
</p>

## IP Address
- Author: [@Sierra007117](https://github.com/Sierra007117)

Display your Pi's IP address, which is useful for `SSH` access and more!

<p align="center">
  <img src="imgs/demo_ip.jpg" width="50%">
</p>

## LCD
- Author: [@Tomtom0201](https://github.com/Tomtom0201)

This demo shows how simple strings could be displayed on the LCD.  For extended usage, take a look at [Extended strings](#extended-strings) demo instead.

<p align="center">
  <img src="imgs/demo_simple_strings.jpg" width="50%">
</p>

## NetMonitor
- Author: [@cgomesu](https://github.com/cgomesu)

This 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):

```Python
hosts = {
    'Internet': '8.8.8.8',
    'Firewall': '192.168.1.1',
    'NAS': '192.168.1.2'
}
services = {
    'Cameras': {'ip': '192.168.1.2', 'port': '8000'},
    'Plex': {'ip': '192.168.1.2', 'port': '32400'}
}
```

<p align="center">
  <img src="imgs/demo_netmonitor.gif" width="50%">
</p>

## Progress bar
- Author: [@juvus](https://github.com/juvus)

This 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.

<p align="center">
  <img src="imgs/demo_progress_bar.jpg" width="50%">
</p>

[top :arrow_up:](#)

# Implementation
Once 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:

```sh
sudo chmod +x script.py
```

Similarly, file ownership can be configured via `chown`.  For example, to set the user `<YOUR-USERNAME>` as owner of the file `script.py`, run the following:

```sh
sudo chown <YOUR-USERNAME> script.py
```

## Systemd
Use the following procedure to run any LCD Python script as a (systemd) service:

1. Create a new unit file in `/lib/systemd/system/` called `hd44780-lcd.service`:
   ```sh
   sudo nano /lib/systemd/system/hd44780-lcd.service
   ```

2. Copy and paste the following in the new unit file:
   ```sh
   [Unit]
   Description=Python script for an hd44780 LCD

   [Service]
   Type=simple
   ## Edit the following according to the script permissions
   User=<YOUR-USERNAME>
   #Group=users

   ## Edit the following with the full path to your script
   ExecStart=/usr/bin/python /path/to/script.py

   Restart=always
   RestartSec=5

   KillMode=process
   KillSignal=SIGINT

   [Install]
   WantedBy=multi-user.target
   ```

3. Enable the service and start it:
   ```sh
   sudo systemctl enable hd44780-lcd.service
   sudo systemctl start hd44780-lcd.service
   ```

4. Check that the LCD is displaying the correct information; otherwise, check the service status:
   ```sh
   systemctl status hd44780-lcd.service
   ```

[top :arrow_up:](#)

# Contributions
Thank 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.

In addition, if you've never contributed to an open source project before, please take a look at the following resources:
- [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)
- [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)

[top :arrow_up:](#)

# Thanks
Special thanks go the [original creator](https://github.com/the-raspberry-pi-guy) of the library and his awesome work.