Refactoring: remove all dependencies to CONFIG/THEME from LcdComm classes, so they can be used in standalone.

Adding simple-program.py (inspired by old main.py from 1.2.0) to show how to include LcdComm in external projects

Author: mathoudebine

README.md

@@ -1,6 +1,11 @@
 # turing-smart-screen-python
 
+| Check out new version with system monitoring features!                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Are you using your Turing Smart Screen for system monitoring?  <br>If so, check out the new [**pre-release 2.0.0 beta 1 - 📊 System Monitor**](https://github.com/mathoudebine/turing-smart-screen-python/releases/tag/2.0.0-beta.1) or the `feature/system-monitoring` branch!  <br><img src="res/pics/Theme3.5Inch.jpg" height="600" />  <img src="res/pics/ThemeTerminal.jpg" height="600" />  <br>It contains embedded hardware monitoring functions, theme creation from configuration files, serial port auto-detection...  <br>See Release Notes to learn more about features and current limitations <br>_Python knowledges recommended._  |
+
 ---
+
 ### ⚠️ DISCLAIMER - PLEASE READ ⚠️
 
 This project is **not affiliated, associated, authorized, endorsed by, or in any way officially connected with Turing brand**, or any of its subsidiaries, affiliates, manufacturers or sellers of the Turing products. All product and company names are the registered trademarks of their original owners.
@@ -10,40 +15,41 @@ This project is an open-source alternative software, not the USBMonitor.exe orig
 ---
 
 A simple Python manager for "Turing Smart Screen" 3.5" IPS USB-C (UART) display, also known as :
-- Turing USB35INCHIPS / USB35INCHIPSV2
-- 3.5 Inch Mini Screen
-- [3.5 Inch 320*480 Mini Capacitive Touch Screen IPS Module](https://www.aliexpress.com/item/1005002505149293.html)
+- Turing USB35INCHIPS / USB35INCHIPSV2 (revision A)
+- XuanFang display (revision B & flagship)
+- [3.5 Inch 320*480 Mini Capacitive Touch Screen IPS Module](https://www.aliexpress.com/item/1005003723773653.html)
 
-Operating systems supported : macOS, Windows, Linux (incl. Raspberry Pi) and all OS that support Python3
-  
-<img src="res/smart-screen-3.webp" width="500"/>
+## Hardware
+<img src="res/pics/smart-screen-3.webp" width="500"/>
 
-This is a 3.5" USB-C display that shows as a serial port once connected.
-It cannot be seen by the operating system as a monitor but picture can be displayed on it.
+The Turing Smart Screen is a 3.5" USB-C display that shows as a serial port once connected.
+It cannot be seen by the operating system as a monitor but pictures can be displayed on it.
 
-A Windows-only software is [available in Chinese](https://lgb123-1253504678.cos.ap-beijing.myqcloud.com/35inch.rar) or [in English](https://lgb123-1253504678.cos.ap-beijing.myqcloud.com/35inchENG.rar) to manage this display.
+There is 3 hardware revisions of the screen: [how to identify my version?](https://github.com/mathoudebine/turing-smart-screen-python/wiki/Hardware-revisions) Version B and "flagship" use the same protocol.  
+A [Windows-only software is available](https://github.com/mathoudebine/turing-smart-screen-python/wiki/Vendor-apps) is provided by the vendor to manage this display.
 This software allows creating themes to display your computer sensors on the screen, but does not offer a simple way to display custom pictures or text.
 
 ## Features
 This Python script can do some simple operations on the Turing display like :
 - **Display custom picture**
 - **Display text**
 - **Display progress bar**
-- Clear the screen (blank)
-- Turn the screen on/off
-- Display soft reset
+- **Screen rotation**
+- Clear the screen (blank) - HW version A only
+- Turn the screen on/off - HW version A only
+- Display soft reset - HW version A only
 - Set brightness
 
-Not yet implemented:
-- Screen rotation
+Operating systems supported : macOS, Windows, Linux (incl. Raspberry Pi) and all OS that support Python3.7
 
 ## Getting started
 _Python knowledges recommended._  
-Download the `main.py` file from this project  
-Download and install latest Python 3.x for your OS: https://www.python.org/downloads/  
+Download this project by cloning it or using the [Releases sections](https://github.com/mathoudebine/turing-smart-screen-python/releases)   
+Download and install the latest Python 3.x (min. 3.7) for your OS: https://www.python.org/downloads/  
 Plug your Turing display to your computer (install the drivers if on Windows)  
-Open the `main.py` file and edit the [`COM_PORT`](https://github.com/mathoudebine/turing-smart-screen-python/blob/deb0a60b772f2c5acef377f13b959632ca649f9f/main.py#L15)  variable to the port used by the display  
+[Identify your hardware revision (version A or version B/flagship)](https://github.com/mathoudebine/turing-smart-screen-python/wiki/Hardware-revisions)  
+Open the `config.yaml` file and change display settings if needed. 
 Open a terminal and run `python3 main.py` or `py -3 main.py` depending on your OS  
 You should see animated content on your Turing display!  
 
-You can then edit the `main.py` file to change the content displayed, or use this file as a Python module for your personal Python project
+For a simple program to control display (e.g. from your personal Python project), you can look at `simple-program.py`

config.yaml

@@ -19,6 +19,7 @@ display:
 
   # Display Brightness
   # Set this as the desired %, 0 being completely dark and 100 being max brightness
+  # Warning: screen can get very hot at high brightness!
   BRIGHTNESS: 20
 
   # Display revision: A or B (for "flagship" version, use B)

library/config.py

@@ -1,7 +1,6 @@
 import os
 import queue
 import sys
-import threading
 
 import yaml
 
@@ -31,7 +30,3 @@ def load_yaml(configfile):
 
 # Queue containing the serial requests to send to the screen
 update_queue = queue.Queue()
-
-# Mutex to protect the queue in case a thread want to add multiple requests (e.g. image data) that should not be
-# mixed with other requests in-between
-update_queue_mutex = threading.Lock()

library/display.py

@@ -1,4 +1,5 @@
 from library import config
+from library.lcd_comm import Orientation
 from library.lcd_comm_rev_a import LcdCommRevA
 from library.lcd_comm_rev_b import LcdCommRevB
 from library.log import logger
@@ -7,20 +8,40 @@
 CONFIG_DATA = config.CONFIG_DATA
 
 
-def get_full_path(path, name):
+def _get_full_path(path, name):
     if name:
         return path + name
     else:
         return None
 
 
+def _get_theme_orientation() -> Orientation:
+    if THEME_DATA["display"]["DISPLAY_ORIENTATION"] == 'portrait':
+        return Orientation.PORTRAIT
+    elif THEME_DATA["display"]["DISPLAY_ORIENTATION"] == 'landscape':
+        return Orientation.LANDSCAPE
+    elif THEME_DATA["display"]["DISPLAY_ORIENTATION"] == 'reverse_portrait':
+        return Orientation.REVERSE_PORTRAIT
+    elif THEME_DATA["display"]["DISPLAY_ORIENTATION"] == 'reverse_landscape':
+        return Orientation.REVERSE_LANDSCAPE
+    else:
+        logger.warning("Orientation '", THEME_DATA["display"]["DISPLAY_ORIENTATION"], "' unknown, using portrait")
+        return Orientation.PORTRAIT
+
+
 class Display:
     def __init__(self):
         self.lcd = None
         if CONFIG_DATA["display"]["REVISION"] == "A":
-            self.lcd = LcdCommRevA()
+            self.lcd = LcdCommRevA(com_port=CONFIG_DATA['config']['COM_PORT'],
+                                   display_width=CONFIG_DATA["display"]["DISPLAY_WIDTH"],
+                                   display_height=CONFIG_DATA["display"]["DISPLAY_HEIGHT"],
+                                   update_queue=config.update_queue)
         elif CONFIG_DATA["display"]["REVISION"] == "B":
-            self.lcd = LcdCommRevB()
+            self.lcd = LcdCommRevB(com_port=CONFIG_DATA['config']['COM_PORT'],
+                                   display_width=CONFIG_DATA["display"]["DISPLAY_WIDTH"],
+                                   display_height=CONFIG_DATA["display"]["DISPLAY_HEIGHT"],
+                                   update_queue=config.update_queue)
         else:
             logger.error("Unknown display revision '", CONFIG_DATA["display"]["REVISION"], "'")
 
@@ -32,13 +53,13 @@ def initialize_display(self):
         self.lcd.InitializeComm()
 
         # Set brightness
-        self.lcd.SetBrightness()
+        self.lcd.SetBrightness(CONFIG_DATA["display"]["BRIGHTNESS"])
 
         # Set backplate RGB LED color (for supported HW only)
-        self.lcd.SetBackplateLedColor()
+        self.lcd.SetBackplateLedColor(THEME_DATA['display']["DISPLAY_RGB_LED"])
 
         # Set orientation
-        self.lcd.SetOrientation()
+        self.lcd.SetOrientation(_get_theme_orientation())
 
     def display_static_images(self):
         if THEME_DATA['static_images']:
@@ -64,8 +85,8 @@ def display_static_text(self):
                     font_size=THEME_DATA['static_text'][text].get("FONT_SIZE", 10),
                     font_color=THEME_DATA['static_text'][text].get("FONT_COLOR", (0, 0, 0)),
                     background_color=THEME_DATA['static_text'][text].get("BACKGROUND_COLOR", (255, 255, 255)),
-                    background_image=get_full_path(THEME_DATA['PATH'],
-                                                   THEME_DATA['static_text'][text].get("BACKGROUND_IMAGE", None))
+                    background_image=_get_full_path(THEME_DATA['PATH'],
+                                                    THEME_DATA['static_text'][text].get("BACKGROUND_IMAGE", None))
                 )
 
 

library/lcd_comm.py

@@ -1,15 +1,13 @@
+import queue
+import threading
 from abc import ABC, abstractmethod
 from enum import IntEnum
 
 import serial
 from PIL import Image, ImageDraw, ImageFont
 
-from library import config
 from library.log import logger
 
-CONFIG_DATA = config.CONFIG_DATA
-THEME_DATA = config.THEME_DATA
-
 
 class Orientation(IntEnum):
     PORTRAIT = 0
@@ -18,45 +16,79 @@ class Orientation(IntEnum):
     REVERSE_LANDSCAPE = 3
 
 
-def get_theme_orientation() -> Orientation:
-    if THEME_DATA["display"]["DISPLAY_ORIENTATION"] == 'portrait':
-        return Orientation.PORTRAIT
-    elif THEME_DATA["display"]["DISPLAY_ORIENTATION"] == 'landscape':
-        return Orientation.LANDSCAPE
-    elif THEME_DATA["display"]["DISPLAY_ORIENTATION"] == 'reverse_portrait':
-        return Orientation.REVERSE_PORTRAIT
-    elif THEME_DATA["display"]["DISPLAY_ORIENTATION"] == 'reverse_landscape':
-        return Orientation.REVERSE_LANDSCAPE
-    else:
-        logger.warning("Orientation '", THEME_DATA["display"]["DISPLAY_ORIENTATION"], "' unknown, using portrait")
-        return Orientation.PORTRAIT
-
-
-def get_width() -> int:
-    if get_theme_orientation() == Orientation.PORTRAIT or get_theme_orientation() == Orientation.REVERSE_PORTRAIT:
-        return CONFIG_DATA["display"]["DISPLAY_WIDTH"]
-    else:
-        return CONFIG_DATA["display"]["DISPLAY_HEIGHT"]
-
-
-def get_height() -> int:
-    if get_theme_orientation() == Orientation.PORTRAIT or get_theme_orientation() == Orientation.REVERSE_PORTRAIT:
-        return CONFIG_DATA["display"]["DISPLAY_HEIGHT"]
-    else:
-        return CONFIG_DATA["display"]["DISPLAY_WIDTH"]
+class LcdComm(ABC):
+    def __init__(self, com_port: str = "AUTO", display_width: int = 320, display_height: int = 480,
+                 update_queue: queue.Queue = None):
+        self.lcd_serial = None
+
+        # String containing absolute path to serial port e.g. "COM3", "/dev/ttyACM1" or "AUTO" for auto-discovery
+        self.com_port = com_port
+
+        # Display always start in portrait orientation by default
+        self.orientation = Orientation.PORTRAIT
+        # Display width in default orientation (portrait)
+        self.display_width = display_width
+        # Display height in default orientation (portrait)
+        self.display_height = display_height
+
+        # Queue containing the serial requests to send to the screen. An external thread should run to process requests
+        # on the queue. If you want serial requests to be done in sequence, set it to None
+        self.update_queue = update_queue
+
+        # Mutex to protect the queue in case a thread want to add multiple requests (e.g. image data) that should not be
+        # mixed with other requests in-between
+        self.update_queue_mutex = threading.Lock()
+
+    def get_width(self) -> int:
+        if self.orientation == Orientation.PORTRAIT or self.orientation == Orientation.REVERSE_PORTRAIT:
+            return self.display_width
+        else:
+            return self.display_height
 
+    def get_height(self) -> int:
+        if self.orientation == Orientation.PORTRAIT or self.orientation == Orientation.REVERSE_PORTRAIT:
+            return self.display_height
+        else:
+            return self.display_width
 
-class LcdComm(ABC):
     def openSerial(self):
-        if CONFIG_DATA['config']['COM_PORT'] == 'AUTO':
+        if self.com_port == 'AUTO':
             lcd_com_port = self.auto_detect_com_port()
             self.lcd_serial = serial.Serial(lcd_com_port, 115200, timeout=1, rtscts=1)
-            logger.debug(f"Auto detected comm port: {lcd_com_port}")
+            logger.debug(f"Auto detected COM port: {lcd_com_port}")
         else:
-            lcd_com_port = CONFIG_DATA["config"]["COM_PORT"]
-            logger.debug(f"Static comm port: {lcd_com_port}")
+            lcd_com_port = self.com_port
+            logger.debug(f"Static COM port: {lcd_com_port}")
             self.lcd_serial = serial.Serial(lcd_com_port, 115200, timeout=1, rtscts=1)
 
+    def closeSerial(self):
+        try:
+            self.lcd_serial.close()
+        except:
+            pass
+
+    def WriteData(self, byteBuffer: bytearray):
+        try:
+            self.lcd_serial.write(bytes(byteBuffer))
+        except serial.serialutil.SerialTimeoutException:
+            # We timed-out trying to write to our device, slow things down.
+            logger.warning("(Write data) Too fast! Slow down!")
+
+    def SendLine(self, line: bytes):
+        if self.update_queue:
+            # Queue the request. Mutex is locked by caller to queue multiple lines
+            self.update_queue.put((self.WriteLine, [line]))
+        else:
+            # If no queue for async requests: do request now
+            self.WriteLine(line)
+
+    def WriteLine(self, line: bytes):
+        try:
+            self.lcd_serial.write(line)
+        except serial.serialutil.SerialTimeoutException:
+            # We timed-out trying to write to our device, slow things down.
+            logger.warning("(Write line) Too fast! Slow down!")
+
     @staticmethod
     @abstractmethod
     def auto_detect_com_port():
@@ -128,16 +160,16 @@ def DisplayText(
         if isinstance(background_color, str):
             background_color = tuple(map(int, background_color.split(', ')))
 
-        assert x <= get_width(), 'Text X coordinate must be <= display width'
-        assert y <= get_height(), 'Text Y coordinate must be <= display height'
+        assert x <= self.get_width(), 'Text X coordinate must be <= display width'
+        assert y <= self.get_height(), 'Text Y coordinate must be <= display height'
         assert len(text) > 0, 'Text must not be empty'
         assert font_size > 0, "Font size must be > 0"
 
         if background_image is None:
             # A text bitmap is created with max width/height by default : text with solid background
             text_image = Image.new(
                 'RGB',
-                (get_width(), get_height()),
+                (self.get_width(), self.get_height()),
                 background_color
             )
         else:
@@ -153,8 +185,8 @@ def DisplayText(
         left, top, text_width, text_height = d.textbbox((0, 0), text, font=font)
         text_image = text_image.crop(box=(
             x, y,
-            min(x + text_width, get_width()),
-            min(y + text_height, get_height())
+            min(x + text_width, self.get_width()),
+            min(y + text_height, self.get_height())
         ))
 
         self.DisplayPILImage(text_image, x, y)
@@ -174,10 +206,10 @@ def DisplayProgressBar(self, x: int, y: int, width: int, height: int, min_value:
         if isinstance(background_color, str):
             background_color = tuple(map(int, background_color.split(', ')))
 
-        assert x <= get_width(), 'Progress bar X coordinate must be <= display width'
-        assert y <= get_height(), 'Progress bar Y coordinate must be <= display height'
-        assert x + width <= get_width(), 'Progress bar width exceeds display width'
-        assert y + height <= get_height(), 'Progress bar height exceeds display height'
+        assert x <= self.get_width(), 'Progress bar X coordinate must be <= display width'
+        assert y <= self.get_height(), 'Progress bar Y coordinate must be <= display height'
+        assert x + width <= self.get_width(), 'Progress bar width exceeds display width'
+        assert y + height <= self.get_height(), 'Progress bar height exceeds display height'
 
         # Don't let the set value exceed our min or max value, this is bad :)
         if value < min_value: