Sterowanie wyświetlaczami ePaper (7.5" trójkolorowe WaveShare 13505 i 14229) z poziomu MicroPythona i Raspberry Pico

[Pyth0n]

Dziś pierwszy mój samodzielny wpis: jak wysterować trójkolorowy wyświetlacz ePaper z Raspberry Pico. Przykłady są przeprowadzane na czarno-biało-czerwonej matrycy GDEW075Z09 (zestaw WaveShare 13505, matryca z płytką kontrolera SPI w formie shielda na Raspberry Pi), ale tak samo programuje się czarno-biało-żółtą matrycę GDEW075C21 (zestaw WaveShare 14229).

Teoria

Wyświetlacze typu e-papier w najczęstszej formie nazywają się wyświetlaczami elekroforetycznymi i działają tak:

• Wyświetlacz zawiera miliony miniaturowych, przezroczystych kapsułek zawierających dwa lub trzy pigmenty zawieszone w oleju. Cząsteczki pigmentów są naładowane elektrycznie (w wyświetlaczach dwukolorowych - dodatnio i ujemnie, w trójkolorowych słabo i silnie dodatnio i ujemnie)
• Kapsułki są umieszczone pomiędzy przezroczystą elektrodą wspólną u góry a matrycą elektrod indywidualnych na dole. Jeden piksel składa się z wielu kapsułek (są one dużo mniejsze od jednej elektrody) i widać to pod dużym powiększeniem.
• Zmieniając napięcie na elektrodach indywidualnych można wypychać pożądane pigmenty w kierunku górnej części wyświetlacza, wtedy piksel zmienia kolor. W 3-kolorowych jest trudnej, bo dwa pigmenty poruszają się razem (czarny i kolorowy), ale z różnymi prędkościami i trzeba sztuczek, żeby te kolory finalnie rozdzielić - więcej w tym artykule.
• Napięcia sterujące są dość wysokie (jak na współczesną elektronikę), rzędu ±7-15V i wyświetlacz pozostawiony "pod napięciem" przez dłuższy czas może ulec uszkodzeniu (jak burn-in w OLED czy plaźmie). Pamiętaj, żeby po każdym odświeżeniu przełączyć kontroler w stan power-down.

Kontroler

Matryce można kupić w formie zestawu z shieldem dla Raspberry Pi (testowałem z Pi0W i Pi3). Płytka shielda ma pod spodem styki do standardowego łącza GPIO-40, ale ma też osobne gniazdo SPI do używania z innymi komputerami nadzorczymi. I właśnie to gniazdo zostało wykorzystane do podpięcia się do Raspberry Pico. W zestawie z shieldem jest nawet odpowiedni kabel z żeńskimi końcówkami do podpięcia pod szpilki. Shield jest uniwersalny (do wszystkich "gołych" matryc ePaper sprzedawanych przez WaveShare), należy tylko odpowiednio na nim ustawić mikroswitche.

Interfejs elektryczny

Shield jest wyposażony w standardowy, jednokierunkowy port SPI (matryca ma co prawda łącze dwukierunkowe, ale część odbiorcza nie jest "przepuszczana" przez shield), kilka sygnałów sterujących (CS, CD, RST) oraz jeden monitorujący (BUSY). Zasilany jest jednym napięciem 3.3V.

Przykładowy kod zakłada następujące połączenia (kolorowe kable na dole powyższego zdjęcia, licząc od lewej):

• BUSY -> GP6 (pin 9 Pico)
• RST <- GP1 (pin 2 Pico)
• DC <- GP0 (pin 1 Pico)
• CS <- GP5/SPI0)CSn (pin 7 Pico)
• CLK <- GP2/SPI0_SCK (pin 4 Pico)
• DIN <- GP3/SPI0_TX (pin 5 Pico)
• GND -- GND (pin 38 Pico)
• VCC -- 3V3_OUT (pin 36 Pico)

Protokół

Do wyświetlacza możemy przesyłać ciągi komend opcjonalnie uzupełnionych o dane. O tym, co jest transmitowane, decyduje stan linii DC.  Sekwencja wysłania komendy wygląda tak:

• Wysterować linię DC na stan niski (komenda),
• Wysterować linię CS na stan niski,
• Przesłać bajt komendy
• Wysterować linię CS na stan wysoki,

Jeżeli komenda wymaga danych, to później następuje taka sekwencja:

• Wysterować linię DC na stan wysoki (dane),
• Wysterować linię CS na stan niski,
• Przesłać bajty danych
• Wysterować linię CS na stan wysoki,

Na końcu trzeba próbkować linię BUSY, stan wysoki sygnalizuje zakończenie operacji.

Dokumentacja jawnie wskazuje, że należy "zdjąć" na chwilę CS po komendzie, jednak zaobserwowałem, że nie ma to wpływu na działanie wyświetlacza. Program przykładowy skonstruowany jest zgodnie z dokumentacją.

Inicjalizacja

Proces inicjalizacji wyświetlacza zawiera dużo czarnej magii: poszczególne rejestry dla poszczególnych matryc muszą być ustawione konkretnie, bo producent tak mówi - bez głębszego wyjaśniania. Dotyczy to szczególnie zależności czasowych i konfiguracji układu konwersji napięcia. Ma być tak, bo inaczej zepsujesz matrycę.

Sekwencja komend konfiguracyjnych w przykładowym programie jest dostosowana do konkretnych dwóch matryc - parametry dla innych należy ściągnąć z przykładowych programów na wiki WaveShare'a.

Aktualizacja

Matryca ma wbudowaną pamięć obrazu i jeżeli chcemy zmienić jej zawartość, musimy przesłać cały nowy obraz. Po przesłaniu nowej ramki wydaje się polecenie odświeżenia, które pierw czyści cały ekran, a następnie na podstawie zawartości pamięci "pompuje" odpowiednie piksele. W przypadku opisywanych matryc cały cykl trwa bolesne 15 sekund. Matryce dwukolorowe mają możliwość częściowego odświeżenia prostokątnego okienka - trwa to około 1/3s. Niestety, żadna matryca trójkolorowa nie ma takiej funkcjonalności.

Zasilanie

Aby uniknąć uszkodzenia materiały matrycy, należy bezwzględnie wydawać polecenie wyłączenia zasilania po każdym odświeżeniu.

Program

"""
Driver do wyświetlaczy GDEW075Z09 (czarno-biało-czerwony) i GDEW075C21
(czarno-biało-żółty), występujących odpowiednio w zestawach WaveShare
13505 i 14229

Copyright (c) 2021 Paweł Kraszewski

Bazuje na pracy:
  Copyright (c) 2017 Waveshare
  Copyright (c) 2018 Mike Causer

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation 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
furnished 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 FOR 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.
"""


class EPaper_GDEW075Z09:
    from micropython import const
    
    EPD_WIDTH = const(640)
    EPD_HEIGHT = const(384)
    COMMAND = const(0)
    DATA = const(1)
    
    def __init__(self, spi, cs, dc, rst, busy):
        """
        Inicjalizacja wyświetlacza
        :param spi: Skonfigurowany interfejs SPI
        :param cs: Pin do sygnału wyjściowego ~CS (chip select)
        :param dc: Pin do sygnału wyjściowego DC (data/command)
        :param rst: Pin do sygnału wyjściowego ~RST (reset)
        :param busy: Pin do sygnału wejściowego ~BUSY (gotowość wyświetlacz)
        """
        import framebuf
        
        self.spi = spi
        self.cs = cs
        self.dc = dc
        self.rst = rst
        self.busy = busy
        self.cs.init(self.cs.OUT, value=1)
        self.dc.init(self.dc.OUT, value=0)
        self.rst.init(self.rst.OUT, value=0)
        self.busy.init(self.busy.IN)
        self._setup_pixel_lut()
        
        # Format framebuf.GS2_HMSB to grafika w 4 odcieniach szarości. Tablica
        # LUT przetwarza kolory 0, 1, 2 i 3 odpowiednio na biały,
        # czerwony/żółty, czarny, czarny (tak, dwa czarne)
        # Bajt tablicy obrazu to spakowane 4 piksle, dlatego wymaga 1/4 bajtów
        
        # Bufor pamięciowy
        self.buf = bytearray(self.EPD_WIDTH * self.EPD_HEIGHT // 4)
        
        # Framebuffer (operacje graficzne, itd)
        self.fb = framebuf.FrameBuffer(
                self.buf,
                self.EPD_WIDTH, self.EPD_HEIGHT,
                framebuf.GS2_HMSB
        )
    
    def _wait_for_ready(self):
        from time import sleep_ms
        while self.busy.value() == 0:
            sleep_ms(100)
    
    def _setup_pixel_lut(self):
        """
        Funkcja wypełnia tablice do szybkiej transformacji
        obrazu w formacie 2:2:2:2 (bajt zawiera cztery pikele po
        dwa bity każdy) na dwa bajty w formacie 4:4 4:4 (piksele po
        cztery bity, ale tylko 3 kombinacje dają sensowny wynik,
        kolory czarny, biały i czerwony/żółty)
        """
        LUT = [3, 4, 0, 0]
        self.lut_high = bytearray(256)
        self.lut_low = bytearray(256)
        for i in range(0, 256):
            p1 = LUT[(i >> 6) & 3]
            p2 = LUT[(i >> 4) & 3]
            p3 = LUT[(i >> 2) & 3]
            p4 = LUT[(i >> 0) & 3]
            self.lut_high[i] = (p2 << 4) | p1
            self.lut_low[i] = (p4 << 4) | p3
    
    def _send_command(self, command, data=None):
        """
        Funkcja wysyła komendę (z linią DC=0) za którą występują
        opcjonalne dane (z linią DC=1)
        :param command: komenda wyświetlacz
        :param data: opcjonalne dane dla komendy
        """
        self.dc(self.COMMAND)
        self.cs(0)
        self.spi.write(bytearray([command]))
        self.cs(1)
        if data is not None:
            self.dc(self.DATA)
            self._send_raw_data(data)
        
    
    def _send_raw_data(self, data):
        """
        Komenda wysyła surowe dane
        :param data: dane
        """
        self.dc(self.DATA)
        self.cs(0)
        self.spi.write(data)
        self.cs(1)
    
    def _send_pixel_data(self, data):
        """
        Komenda wysyła bufor wyświetlacza w formacie 2:2:2:2 przeliczając
        kolory według prekalkulowanych tablic LUT
        :param data: framebuffer
        """
        self.dc(self.DATA)
        self.cs(0)
        for quad_pixel in data:
            self.spi.write(bytearray([
                self.lut_low[quad_pixel],
                self.lut_high[quad_pixel]
            ]))
        self.cs(1)
    
    def setup(self):
        """
        Inicjalizacja wyświetlacza.
        Poprawne dla modułów GDEW075Z09 (czarno-biało-czerwony) i GDEW075C21
        (czarno-biało-żółty), występujących odpowiednio w zestawach WaveShare
        13505 i 14229
        """
        import ustruct
        
        self.hard_reset()
        # Power setting
        self._send_command(0x01, b'\x37\x00')
        # Panel setting
        self._send_command(0x00, b'\xCF\x08')
        # PLL Control
        self._send_command(0x30, b'\x3A')
        # VCM DC Setting
        self._send_command(0x82, b'\x28')
        # Booster soft start
        self._send_command(0x06, b'\xC7\xCC\x15')
        # VCOM and data interval setting
        self._send_command(0x50, b'\x77')
        # TCON setting
        self._send_command(0x60, b'\x22')
        # SPI flash control
        self._send_command(0x65, b'\x00')
        # TCON resolution
        self._send_command(0x61, ustruct.pack(">HH", self.EPD_WIDTH, self.EPD_HEIGHT))
        # FLASH mode
        self._send_command(0xE5, b'\x03')
        # Temp calibration
        self._send_command(0x41, b'\x00')
        # Power on
        self._send_command(0x04)
        self._wait_for_ready()
    
    def hard_reset(self):
        """
        Twardy reset wyświetlacza (zeruje wszystkie rejestry), impuls niski
        sygnału ~RST przez 200ms i dodatkowe 200ms czekania
        """
        from time import sleep_ms
        
        self.rst(0)
        sleep_ms(200)
        self.rst(1)
        sleep_ms(200)
    
    def update(self):
        """
        Aktualizuje zawartość wyświetlacza na podstawie bieżącej zawartości
        framebuffera. Dla opisywanych wyświetlaczy trwa to ~10s :(
        """
        
        # Start pixel transmission
        self._send_command(0x10)
        
        # Pixels
        self._send_pixel_data(self.buf)
        
        # Stop pixel transmission
        self._send_command(0x11)
        
        # Display refresh
        self._send_command(0x12)
        
        self._wait_for_ready()
    
    def power_down(self):
        """
        Wyłączenie zasilania wyświetlacza (zawartość oczywiście pozostaje na
        ekranie)
        """
        # Power off
        self._send_command(0x02)
        
        self._wait_for_ready()
        
        # Deep sleep
        self._send_command(0x07, b'\xA5')
    
    def get_framebuffer(self):
        """
        Zwraca klasę framebuf.FrameBuffer() do rysowania na buforze
        :return: framebuf.FrameBuffer()
        """
        return self.fb
    
    def get_size(self):
        """
        Zwraca rozmiar wyświetlacza w pikselach
        :return: (width,height)
        """
        return self.EPD_WIDTH, self.EPD_HEIGHT


def demo():
    from machine import Pin, SPI
    
    # Konfiguracja pinów zgodnie z artykułem
    sck = Pin(2)
    miso = Pin(4)
    mosi = Pin(3)
    dc = Pin(0)
    cs = Pin(5)
    rst = Pin(1)
    busy = Pin(6)
    spi = SPI(0, baudrate=20000000, polarity=0, phase=0, sck=sck, miso=miso, mosi=mosi)
    
    # Podpięcie pod wyświetlacz
    e = EPaper_GDEW075Z09(spi, cs, dc, rst, busy)
    
    # Inicjalizacja
    e.setup()
    
    # Pobranie  rozmiaru wyświetalcza w pikselach
    w, h = e.get_size()
    
    # Pobranie instancji klasy FrameBuffer do rysowania
    fb = e.get_framebuffer()
    
    # Przypisanie kolorów
    black = 2
    red = 1
    white = 0
    
    # Wypełnienie białym kolorem
    fb.fill(white)
    
    # Ramki
    for i in range(0, 40, 4):
        fb.rect(i, i, w - 1 - 2 * i, h - 1 - 2 * i, black)
        fb.rect(i + 2, i + 2, w - 1 - 4 - 2 * i, h - 1 - 4 - 2 * i, red)
    
    # "Szachownica"
    for x in range(12):
        for y in range(12):
            c = (red, black, white)[(x + y) % 3]
            fb.fill_rect(50 + x * 20, 50 + y * 20, 19, 19, c)
            
    # Tekst
    fb.text('RED', w // 2, h // 2, red)
    fb.text('BLACK', w // 2, h // 2 + 16, black)
    
    # Wysłanie bufora do matrycy i polecenie odświeżenia
    e.update()
    
    # Bardzo, BARDZO ważne! Wyłączenie zasilania
    e.power_down()


if __name__ == "__main__":
    demo()

Miłej zabawy! A, skryptu można używać jako biblioteki w swoich programach. Jak zapiszecie na Malince jako "epaper.py" to z własnego skryptu użyjecie tego przez "from epaper import EPaper_GDEW075Z09"

PS.

Niebawem to samo, tylko w C++. A potem inne peryferia: OLED monochromatyczny, OLED kolorowy i LCD kolorowy, w wersjach pierw Python, potem C++.

[Gieneq]

@Pyth0n Ciekawy projekt 🙂 

Przy okazji podpytam jak oceniasz micro Pythona na mikrokontrolerach? Ma to sens, jest przyszłościowe? Czy jest duża strata w mocy obliczeniowej w porównaniu z językiem w pełni kompilowanym?

Tak ostatnio zastanawiam się nad tym, bo patrząc że w programowaniu na PC optymalizacja pod względem szybkości wykonania w wielu przypadkach została przysłonięta łatwością utrzymania i rozwijania kodu - języki obiektowe wysokiego poziomu, to czy coś podobnego nie pojawi się w mikrokontrolerach. Jeżeli pojawiają się już lepsze układy to czy nabudowanie warstwy abstrakcji, żeby jednak oddalić się od sprzętu, kosztem wydajności nie jest tą samą drogą co w programowaniu PC? 

Edytowano Luty 20, 2021 przez Gieneq