LCD 16x2 simulator

README.md

@@ -17,6 +17,7 @@ You can buy one of these great little I2C LCD on eBay or somewhere like [the Pi
    - [Backlight control](#backlight-control)
    - [Custom characters](#custom-characters)
    - [Extended strings](#extended-strings)
+   - [Emulator](#emulator)
    - [Forex](#forex)
    - [Home automation](#home-automation)
    - [IP address](#ip-address)
@@ -119,6 +120,78 @@ Please, see the comments and implementation in the [`demo_lcd_custom_characters.
   <img src="imgs/demo_custom_characters.jpg" width="50%">
 </p>
 
+### Emulator
+
+- Author: [@Jumitti](https://github.com/Jumitti)
+- ``Tkinter`` Python package: standard library (on **WINDOWS**).
+  - If there is an error, how to install on **Debian/Ubuntu**:
+    ```bash
+    sudo apt update
+    sudo apt install python3-tk
+    ```
+    On **macOS**:
+    ```bash
+    brew install python-tk
+    ```
+
+Just a 16x2 LCD screen simulator using Tkinter, allowing for easy testing and visualization of LCD displays without physical hardware. This simulator helps in developing and debugging LCD-based projects directly from a computer.
+Especially if you don't have your Raspberry and LCD with you.
+
+Some nice features are in addition. You can change the title and size of the Tkinter window, change the font and the 
+font size, the color of the background and the text (the [Backlight control](#backlight-control) is reverse colors).
+
+The font size and [Custom characters](#custom-characters) adapt to the size of the Tkinter window.
+And because it is an emulator, if you wanted to add or remove columns and lines you can do it
+
+
+**How to use:**
+- ``import drivers`` => ``import emulators``
+- ``Lcd()`` => ``LcdEmulator()``
+- ``CustomCharacters`` => ``CustomCharactersEmulator()``
+
+Suggested beginning program:
+
+```Python
+import emulators
+
+display = emulators.LcdEmulator()
+cc = emulators.CustomCharactersEmulator(display)
+
+# Then the rest of your finest feats
+```
+
+All other functions are the same. **Please refer to [demo_emulator.py](demo_emulator.py)**
+
+**Personalization of your Tkinter window**
+
+- **Parameters for `LcdEmulator()`**
+```Python
+import emulators
+
+display = emulators.LcdEmulator(TITTLE_WINDOWS="Hello World",
+                                LCD_BACKGROUND="pale turquoise", LCD_FOREGROUND="orange",
+                                SESSION_STATE_BACKLIGHT=1,
+                                FONT="Arial", FONT_SIZE=50,
+                                COLUMNS=16, ROWS=2, CHAR_WIDTH=50)
+```
+
+| Parameter               | Type              | Default Value  | Description                                                                                                                                |
+|-------------------------|-------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| `TITTLE_WINDOWS`        | `Union[str, int]` | `LCD 16x2 Emulator` | Renames the Tkinter window.                                                                                                                |
+| `LCD_BACKGROUND`        | `str`             | `green`        | Background color (supports HEX values, e.g., `#55A8DB`). [List of supported colors](https://www.tcl-lang.org/man/tcl8.4/TkCmd/colors.htm). |
+| `LCD_FOREGROUND`        | `str`             | `black`        | Foreground color (supports HEX values, e.g., `#55A8DB`). [List of supported colors](https://www.tcl-lang.org/man/tcl8.4/TkCmd/colors.htm). |
+| `SESSION_STATE_BACKLIGHT` | `int`             | `1`            | Controls the backlight. Set `1` for ON and `0` for OFF.                                                                                    |
+| `FONT`                  | `str`             | `Courier`      | Font family. [List of available fonts](https://stackoverflow.com/a/64301819).                                                              |
+| `FONT_SIZE`             | `int > 0`         | `75`           | The font size. The font size adapts to the window size to prevent overflow.                                                                |
+| `COLUMNS`               | `int > 0`         | `16`           | Number of columns (you can customize it beyond the standard 16x2 LCD screen configuration).                                                |
+| `ROWS`                  | `int > 0`         | `2`            | Number of rows (you can customize it beyond the standard 16x2 LCD screen configuration).                                                   |
+| `CHAR_WIDTH`            | `int > 0`         | `75`           | Resizes the Tkinter window accordingly.                                                                                                    |
+
+
+<p align="center">
+  <img src="imgs/demo_simulator.gif" width="50%">
+</p>
+
 ### Extended strings
 
 - Author: [@juvus](https://github.com/juvus)

demo_emulator.py

@@ -0,0 +1,63 @@
+#! /usr/bin/env python
+
+# Just a 16x2 LCD screen simulator using Tkinter, allowing for easy testing and
+# visualization of LCD displays without physical hardware. This simulator helps
+# in developing and debugging LCD-based projects directly from a computer.
+
+# Import necessary libraries for communication and display use
+import emulators
+from time import sleep
+from datetime import datetime
+
+
+# Load the driver and set it to "display"
+# If you use something from the driver library use the "display." prefix first
+display = emulators.LcdEmulator()
+
+# Create object with custom characters data
+cc = emulators.CustomCharactersEmulator(display)
+
+# Redefine the default characters:
+# Custom caracter #1. Code {0x00}.
+cc.char_1_data = ["01010", "11111", "10001", "10101", "10001", "11111", "01010", "00000"]
+
+# Load custom characters data to CG RAM:
+cc.load_custom_characters_data()
+
+# Main body for code
+try:
+    i = 0
+    while True:
+        display.lcd_clear()
+
+        display.lcd_display_string(' Hello, World !', line=1)
+        if i < 1:
+            display.lcd_backlight(1)
+            text = "This is a simulation of a 16x2 LCD"
+            for j in range(len(text) - 14):
+                text2 = "{0x00}" + text[j:j + 15]
+                display.lcd_display_extended_string(text2, 2)
+                sleep(0.15)
+            i += 1
+
+        elif 1 <= i <= 10:
+            display.lcd_backlight(0)
+            display.lcd_display_string(str(datetime.now().time()), 2)
+            i += 1
+
+        elif 11 <= i <= 20:
+            display.lcd_display_string("    ENJOY :)    ", line=2)
+            i += 1
+
+        if i > 20:
+            i = 0
+
+        sleep(0.5)
+
+except KeyboardInterrupt:
+    # If there is a KeyboardInterrupt (when you press ctrl+c), exit the program and cleanup
+    print("Cleaning up!")
+    display.lcd_clear()
+
+
+

emulators/__init__.py

@@ -0,0 +1 @@
+from .emulator import LcdEmulator, CustomCharactersEmulator