Initial commit: Paperwall, a standalone e-ink dashboard

Navidrome now-playing, clock, and weather for a Waveshare epd4in0e panel,
with a local web UI and install/uninstall scripts for the Pi.

display/__init__.py

@@ -0,0 +1,28 @@
+"""Display driver interface.
+
+A driver only needs to do three things: get ready, put an image on the panel,
+and go to sleep to save power. `EPD4in0eDisplay` talks to the real Waveshare
+hardware; `MockDisplay` is a drop-in stand-in for developing off the Pi.
+"""
+
+from abc import ABC, abstractmethod
+
+from PIL import Image
+
+
+class Display(ABC):
+    resolution: tuple[int, int]
+
+    @abstractmethod
+    def init(self) -> None:
+        """Prepare the panel for writing (called once at startup, and again
+        after every sleep since most EPDs need re-initializing)."""
+
+    @abstractmethod
+    def show(self, image: Image.Image) -> None:
+        """Push a full-resolution image to the panel. This is always a full
+        refresh on this hardware -- there is no partial-refresh path."""
+
+    @abstractmethod
+    def sleep(self) -> None:
+        """Put the panel into low-power mode between updates."""

display/epd4in0e_driver.py

@@ -0,0 +1,54 @@
+"""Driver for the Waveshare epd4in0e (4", 6-color Spectra) panel.
+
+Thin wrapper around the vendored `waveshare_epd.epd4in0e` module -- the exact
+driver already proven working under the InkyPi install on this Pi. That
+driver only exposes `Clear()` and `display()`, both of which do a full
+`TurnOnDisplay()` flash cycle; there is no partial-refresh path for this
+panel at the hardware/SDK level, confirmed by reading the driver itself.
+"""
+
+import logging
+
+from display import Display
+
+logger = logging.getLogger(__name__)
+
+RESOLUTION = (400, 600)
+
+
+class EPD4in0eDisplay(Display):
+    def __init__(self):
+        self.resolution = RESOLUTION
+        self._epd = None
+
+    def init(self) -> None:
+        from waveshare_epd import epd4in0e
+
+        self._epd = epd4in0e.EPD()
+        self._epd.init()
+        logger.info("epd4in0e initialized")
+
+    def show(self, image) -> None:
+        if self._epd is None:
+            self.init()
+
+        width, height = self.resolution
+        if image.size != (width, height):
+            raise ValueError(
+                f"Image size {image.size} does not match panel resolution {self.resolution}"
+            )
+
+        # Re-init: the panel goes to sleep after every show(), and needs a
+        # fresh init() before it will accept commands again.
+        self._epd.init()
+
+        # Clear first to avoid ghosting from the previous image -- also a
+        # full flash, there's no way around it on this panel.
+        self._epd.Clear()
+
+        self._epd.display(self._epd.getbuffer(image.convert("RGB")))
+
+    def sleep(self) -> None:
+        if self._epd is not None:
+            self._epd.sleep()
+        logger.info("epd4in0e put to sleep")

display/mock_driver.py

@@ -0,0 +1,35 @@
+"""Development stand-in for the real panel: saves each frame as a PNG instead
+of writing to hardware, so the scheduler/rendering logic can be exercised off
+the Pi.
+"""
+
+import logging
+from pathlib import Path
+
+from PIL import Image
+
+from display import Display
+
+logger = logging.getLogger(__name__)
+
+
+class MockDisplay(Display):
+    def __init__(self, resolution: tuple[int, int], out_dir: str = "./mock_output"):
+        self.resolution = resolution
+        self.out_dir = Path(out_dir)
+        self.out_dir.mkdir(parents=True, exist_ok=True)
+        self._frame_count = 0
+
+    def init(self) -> None:
+        logger.info("MockDisplay initialized (resolution=%s)", self.resolution)
+
+    def show(self, image: Image.Image) -> None:
+        self._frame_count += 1
+        path = self.out_dir / "current.png"
+        image.save(path)
+        history_path = self.out_dir / f"frame_{self._frame_count:04d}.png"
+        image.save(history_path)
+        logger.info("MockDisplay: wrote frame to %s", path)
+
+    def sleep(self) -> None:
+        logger.info("MockDisplay: sleep")

display/waveshare_epd/epd4in0e.py

@@ -0,0 +1,232 @@
+# *****************************************************************************
+# * | File        :	  epd7in3f.py
+# * | Author      :   Waveshare team
+# * | Function    :   Electronic paper driver
+# * | Info        :
+# *----------------
+# * | This version:   V1.0
+# * | Date        :   2022-10-20
+# # | Info        :   python demo
+# -----------------------------------------------------------------------------
+# ******************************************************************************/
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documnetation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to  whom the Software is
+# furished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS OR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+import logging
+from . import epdconfig
+
+import PIL
+from PIL import Image
+import io
+
+# Display resolution
+EPD_WIDTH       = 400
+EPD_HEIGHT      = 600
+
+logger = logging.getLogger(__name__)
+
+class EPD:
+    def __init__(self):
+        self.reset_pin = epdconfig.RST_PIN
+        self.dc_pin = epdconfig.DC_PIN
+        self.busy_pin = epdconfig.BUSY_PIN
+        self.cs_pin = epdconfig.CS_PIN
+        self.width = EPD_WIDTH
+        self.height = EPD_HEIGHT
+        self.BLACK  = 0x000000   #   0000  BGR
+        self.WHITE  = 0xffffff   #   0001
+        self.YELLOW = 0x00ffff   #   0010
+        self.RED    = 0x0000ff   #   0011
+        self.BLUE   = 0xff0000   #   0101
+        self.GREEN  = 0x00ff00   #   0110
+        
+
+    # Hardware reset
+    def reset(self):
+        epdconfig.digital_write(self.reset_pin, 1)
+        epdconfig.delay_ms(20) 
+        epdconfig.digital_write(self.reset_pin, 0)         # module reset
+        epdconfig.delay_ms(2)
+        epdconfig.digital_write(self.reset_pin, 1)
+        epdconfig.delay_ms(20)   
+
+    def send_command(self, command):
+        epdconfig.digital_write(self.dc_pin, 0)
+        epdconfig.digital_write(self.cs_pin, 0)
+        epdconfig.spi_writebyte([command])
+        epdconfig.digital_write(self.cs_pin, 1)
+
+    def send_data(self, data):
+        epdconfig.digital_write(self.dc_pin, 1)
+        epdconfig.digital_write(self.cs_pin, 0)
+        epdconfig.spi_writebyte([data])
+        epdconfig.digital_write(self.cs_pin, 1)
+        
+    # send a lot of data   
+    def send_data2(self, data):
+        epdconfig.digital_write(self.dc_pin, 1)
+        epdconfig.digital_write(self.cs_pin, 0)
+        epdconfig.spi_writebyte2(data)
+        epdconfig.digital_write(self.cs_pin, 1)
+        
+    def ReadBusyH(self):
+        logger.debug("e-Paper busy H")
+        while(epdconfig.digital_read(self.busy_pin) == 0):      # 0: busy, 1: idle
+            epdconfig.delay_ms(5)
+        epdconfig.delay_ms(200)
+        logger.debug("e-Paper busy H release")
+
+    def TurnOnDisplay(self):
+        self.send_command(0x04) # POWER_ON
+        self.ReadBusyH()
+
+        self.send_command(0x06)
+        self.send_data(0x6F)
+        self.send_data(0x1F)
+        self.send_data(0x17)
+        self.send_data(0x27)
+        epdconfig.delay_ms(200)
+
+        self.send_command(0x12) # DISPLAY_REFRESH
+        self.send_data(0X00)
+        self.ReadBusyH()
+        
+        self.send_command(0x02) # POWER_OFF
+        self.send_data(0X00)
+        self.ReadBusyH()
+        
+    def init(self):
+        if (epdconfig.module_init() != 0):
+            return -1
+        # EPD hardware init start
+        self.reset()
+        self.ReadBusyH()
+        epdconfig.delay_ms(30)
+
+        self.send_command(0xAA)   
+        self.send_data(0x49)
+        self.send_data(0x55)
+        self.send_data(0x20)
+        self.send_data(0x08)
+        self.send_data(0x09)
+        self.send_data(0x18)
+
+        self.send_command(0x01)
+        self.send_data(0x3F)
+
+        self.send_command(0x00)  
+        self.send_data(0x5F)
+        self.send_data(0x69)
+
+        self.send_command(0x05)
+        self.send_data(0x40)
+        self.send_data(0x1F)
+        self.send_data(0x1F)
+        self.send_data(0x2C)
+
+        self.send_command(0x08)
+        self.send_data(0x6F)
+        self.send_data(0x1F)
+        self.send_data(0x1F)
+        self.send_data(0x22)
+
+        self.send_command(0x06)
+        self.send_data(0x6F)
+        self.send_data(0x1F)
+        self.send_data(0x17)
+        self.send_data(0x17)
+
+        self.send_command(0x03)
+        self.send_data(0x00)
+        self.send_data(0x54)
+        self.send_data(0x00)
+        self.send_data(0x44) 
+
+        self.send_command(0x60)
+        self.send_data(0x02)
+        self.send_data(0x00)
+
+        self.send_command(0x30)
+        self.send_data(0x08)
+
+        self.send_command(0x50)
+        self.send_data(0x3F)
+
+        self.send_command(0x61)
+        self.send_data(0x01)
+        self.send_data(0x90)
+        self.send_data(0x02) 
+        self.send_data(0x58)
+
+        self.send_command(0xE3)
+        self.send_data(0x2F)
+
+        self.send_command(0x84)
+        self.send_data(0x01)
+        self.ReadBusyH()
+        return 0
+
+    def getbuffer(self, image):
+        # Create a pallette with the 7 colors supported by the panel
+        pal_image = Image.new("P", (1,1))
+        pal_image.putpalette( (0,0,0,  255,255,255,  255,255,0,  255,0,0,  0,0,0,  0,0,255,  0,255,0) + (0,0,0)*249)
+
+        # Check if we need to rotate the image
+        imwidth, imheight = image.size
+        if(imwidth == self.width and imheight == self.height):
+            image_temp = image
+        elif(imwidth == self.height and imheight == self.width):
+            image_temp = image.rotate(90, expand=True)
+        else:
+            logger.warning("Invalid image dimensions: %d x %d, expected %d x %d" % (imwidth, imheight, self.width, self.height))
+
+        # Convert the soruce image to the 7 colors, dithering if needed
+        image_6color = image_temp.convert("RGB").quantize(palette=pal_image)
+        buf_6color = bytearray(image_6color.tobytes('raw'))
+
+        # PIL does not support 4 bit color, so pack the 4 bits of color
+        # into a single byte to transfer to the panel
+        buf = [0x00] * int(self.width * self.height / 2)
+        idx = 0
+        for i in range(0, len(buf_6color), 2):
+            buf[idx] = (buf_6color[i] << 4) + buf_6color[i+1]
+            idx += 1
+            
+        return buf
+
+    def display(self, image):
+        self.send_command(0x10)
+        self.send_data2(image)
+
+        self.TurnOnDisplay()
+        
+    def Clear(self, color=0x11):
+        self.send_command(0x10)
+        self.send_data2([color] * int(self.height) * int(self.width/2))
+
+        self.TurnOnDisplay()
+
+    def sleep(self):
+        self.send_command(0x07) # DEEP_SLEEP
+        self.send_data(0XA5)
+        
+        epdconfig.delay_ms(2000)
+        epdconfig.module_exit()
+### END OF FILE ###
+

display/waveshare_epd/epdconfig.py

@@ -0,0 +1,322 @@
+# /*****************************************************************************
+# * | File        :	  epdconfig.py
+# * | Author      :   Waveshare team
+# * | Function    :   Hardware underlying interface
+# * | Info        :
+# *----------------
+# * | This version:   V1.2
+# * | Date        :   2022-10-29
+# * | Info        :   
+# ******************************************************************************
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documnetation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to  whom the Software is
+# furished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS OR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+import os
+import logging
+import sys
+import time
+import subprocess
+
+from ctypes import *
+
+logger = logging.getLogger(__name__)
+
+
+class RaspberryPi:
+    # Pin definition
+    RST_PIN  = 17
+    DC_PIN   = 25
+    CS_PIN   = 8
+    BUSY_PIN = 24
+    PWR_PIN  = 18
+    MOSI_PIN = 10
+    SCLK_PIN = 11
+
+    def __init__(self):
+        import spidev
+        import gpiozero
+        
+        self.SPI = spidev.SpiDev()
+        self.GPIO_RST_PIN    = gpiozero.LED(self.RST_PIN)
+        self.GPIO_DC_PIN     = gpiozero.LED(self.DC_PIN)
+        # self.GPIO_CS_PIN     = gpiozero.LED(self.CS_PIN)
+        self.GPIO_PWR_PIN    = gpiozero.LED(self.PWR_PIN)
+        self.GPIO_BUSY_PIN   = gpiozero.Button(self.BUSY_PIN, pull_up = False)
+
+        
+
+    def digital_write(self, pin, value):
+        if pin == self.RST_PIN:
+            if value:
+                self.GPIO_RST_PIN.on()
+            else:
+                self.GPIO_RST_PIN.off()
+        elif pin == self.DC_PIN:
+            if value:
+                self.GPIO_DC_PIN.on()
+            else:
+                self.GPIO_DC_PIN.off()
+        # elif pin == self.CS_PIN:
+        #     if value:
+        #         self.GPIO_CS_PIN.on()
+        #     else:
+        #         self.GPIO_CS_PIN.off()
+        elif pin == self.PWR_PIN:
+            if value:
+                self.GPIO_PWR_PIN.on()
+            else:
+                self.GPIO_PWR_PIN.off()
+
+    def digital_read(self, pin):
+        if pin == self.BUSY_PIN:
+            return self.GPIO_BUSY_PIN.value
+        elif pin == self.RST_PIN:
+            return self.RST_PIN.value
+        elif pin == self.DC_PIN:
+            return self.DC_PIN.value
+        # elif pin == self.CS_PIN:
+        #     return self.CS_PIN.value
+        elif pin == self.PWR_PIN:
+            return self.PWR_PIN.value
+
+    def delay_ms(self, delaytime):
+        time.sleep(delaytime / 1000.0)
+
+    def spi_writebyte(self, data):
+        self.SPI.writebytes(data)
+
+    def spi_writebyte2(self, data):
+        self.SPI.writebytes2(data)
+
+    def DEV_SPI_write(self, data):
+        self.DEV_SPI.DEV_SPI_SendData(data)
+
+    def DEV_SPI_nwrite(self, data):
+        self.DEV_SPI.DEV_SPI_SendnData(data)
+
+    def DEV_SPI_read(self):
+        return self.DEV_SPI.DEV_SPI_ReadData()
+
+    def module_init(self, cleanup=False):
+        self.GPIO_PWR_PIN.on()
+        
+        if cleanup:
+            find_dirs = [
+                os.path.dirname(os.path.realpath(__file__)),
+                '/usr/local/lib',
+                '/usr/lib',
+            ]
+            self.DEV_SPI = None
+            for find_dir in find_dirs:
+                val = int(os.popen('getconf LONG_BIT').read())
+                logging.debug("System is %d bit"%val)
+                if val == 64:
+                    so_filename = os.path.join(find_dir, 'DEV_Config_64.so')
+                else:
+                    so_filename = os.path.join(find_dir, 'DEV_Config_32.so')
+                if os.path.exists(so_filename):
+                    self.DEV_SPI = CDLL(so_filename)
+                    break
+            if self.DEV_SPI is None:
+                RuntimeError('Cannot find DEV_Config.so')
+
+            self.DEV_SPI.DEV_Module_Init()
+
+        else:
+            # SPI device, bus = 0, device = 0
+            self.SPI.open(0, 0)
+            self.SPI.max_speed_hz = 4000000
+            self.SPI.mode = 0b00
+        return 0
+
+    def module_exit(self, cleanup=False):
+        logger.debug("spi end")
+        self.SPI.close()
+
+        self.GPIO_RST_PIN.off()
+        self.GPIO_DC_PIN.off()
+        self.GPIO_PWR_PIN.off()
+        logger.debug("close 5V, Module enters 0 power consumption ...")
+        
+        if cleanup:
+            self.GPIO_RST_PIN.close()
+            self.GPIO_DC_PIN.close()
+            # self.GPIO_CS_PIN.close()
+            self.GPIO_PWR_PIN.close()
+            self.GPIO_BUSY_PIN.close()
+
+        
+
+
+
+class JetsonNano:
+    # Pin definition
+    RST_PIN  = 17
+    DC_PIN   = 25
+    CS_PIN   = 8
+    BUSY_PIN = 24
+    PWR_PIN  = 18
+
+    def __init__(self):
+        import ctypes
+        find_dirs = [
+            os.path.dirname(os.path.realpath(__file__)),
+            '/usr/local/lib',
+            '/usr/lib',
+        ]
+        self.SPI = None
+        for find_dir in find_dirs:
+            so_filename = os.path.join(find_dir, 'sysfs_software_spi.so')
+            if os.path.exists(so_filename):
+                self.SPI = ctypes.cdll.LoadLibrary(so_filename)
+                break
+        if self.SPI is None:
+            raise RuntimeError('Cannot find sysfs_software_spi.so')
+
+        import Jetson.GPIO
+        self.GPIO = Jetson.GPIO
+
+    def digital_write(self, pin, value):
+        self.GPIO.output(pin, value)
+
+    def digital_read(self, pin):
+        return self.GPIO.input(self.BUSY_PIN)
+
+    def delay_ms(self, delaytime):
+        time.sleep(delaytime / 1000.0)
+
+    def spi_writebyte(self, data):
+        self.SPI.SYSFS_software_spi_transfer(data[0])
+
+    def spi_writebyte2(self, data):
+        for i in range(len(data)):
+            self.SPI.SYSFS_software_spi_transfer(data[i])
+
+    def module_init(self):
+        self.GPIO.setmode(self.GPIO.BCM)
+        self.GPIO.setwarnings(False)
+        self.GPIO.setup(self.RST_PIN, self.GPIO.OUT)
+        self.GPIO.setup(self.DC_PIN, self.GPIO.OUT)
+        self.GPIO.setup(self.CS_PIN, self.GPIO.OUT)
+        self.GPIO.setup(self.PWR_PIN, self.GPIO.OUT)
+        self.GPIO.setup(self.BUSY_PIN, self.GPIO.IN)
+        
+        self.GPIO.output(self.PWR_PIN, 1)
+        
+        self.SPI.SYSFS_software_spi_begin()
+        return 0
+
+    def module_exit(self):
+        logger.debug("spi end")
+        self.SPI.SYSFS_software_spi_end()
+
+        logger.debug("close 5V, Module enters 0 power consumption ...")
+        self.GPIO.output(self.RST_PIN, 0)
+        self.GPIO.output(self.DC_PIN, 0)
+        self.GPIO.output(self.PWR_PIN, 0)
+
+        self.GPIO.cleanup([self.RST_PIN, self.DC_PIN, self.CS_PIN, self.BUSY_PIN, self.PWR_PIN])
+
+
+class SunriseX3:
+    # Pin definition
+    RST_PIN  = 17
+    DC_PIN   = 25
+    CS_PIN   = 8
+    BUSY_PIN = 24
+    PWR_PIN  = 18
+    Flag     = 0
+
+    def __init__(self):
+        import spidev
+        import Hobot.GPIO
+
+        self.GPIO = Hobot.GPIO
+        self.SPI = spidev.SpiDev()
+
+    def digital_write(self, pin, value):
+        self.GPIO.output(pin, value)
+
+    def digital_read(self, pin):
+        return self.GPIO.input(pin)
+
+    def delay_ms(self, delaytime):
+        time.sleep(delaytime / 1000.0)
+
+    def spi_writebyte(self, data):
+        self.SPI.writebytes(data)
+
+    def spi_writebyte2(self, data):
+        # for i in range(len(data)):
+        #     self.SPI.writebytes([data[i]])
+        self.SPI.xfer3(data)
+
+    def module_init(self):
+        if self.Flag == 0:
+            self.Flag = 1
+            self.GPIO.setmode(self.GPIO.BCM)
+            self.GPIO.setwarnings(False)
+            self.GPIO.setup(self.RST_PIN, self.GPIO.OUT)
+            self.GPIO.setup(self.DC_PIN, self.GPIO.OUT)
+            self.GPIO.setup(self.CS_PIN, self.GPIO.OUT)
+            self.GPIO.setup(self.PWR_PIN, self.GPIO.OUT)
+            self.GPIO.setup(self.BUSY_PIN, self.GPIO.IN)
+
+            self.GPIO.output(self.PWR_PIN, 1)
+        
+            # SPI device, bus = 0, device = 0
+            self.SPI.open(2, 0)
+            self.SPI.max_speed_hz = 4000000
+            self.SPI.mode = 0b00
+            return 0
+        else:
+            return 0
+
+    def module_exit(self):
+        logger.debug("spi end")
+        self.SPI.close()
+
+        logger.debug("close 5V, Module enters 0 power consumption ...")
+        self.Flag = 0
+        self.GPIO.output(self.RST_PIN, 0)
+        self.GPIO.output(self.DC_PIN, 0)
+        self.GPIO.output(self.PWR_PIN, 0)
+
+        self.GPIO.cleanup([self.RST_PIN, self.DC_PIN, self.CS_PIN, self.BUSY_PIN], self.PWR_PIN)
+
+
+if sys.version_info[0] == 2:
+    process = subprocess.Popen("cat /proc/cpuinfo | grep Raspberry", shell=True, stdout=subprocess.PIPE)
+else:
+    process = subprocess.Popen("cat /proc/cpuinfo | grep Raspberry", shell=True, stdout=subprocess.PIPE, text=True)
+output, _ = process.communicate()
+if sys.version_info[0] == 2:
+    output = output.decode(sys.stdout.encoding)
+
+if "Raspberry" in output:
+    implementation = RaspberryPi()
+elif os.path.exists('/sys/bus/platform/drivers/gpio-x3'):
+    implementation = SunriseX3()
+else:
+    implementation = JetsonNano()
+
+for func in [x for x in dir(implementation) if not x.startswith('_')]:
+    setattr(sys.modules[__name__], func, getattr(implementation, func))
+
+### END OF FILE ###