MicroPython 學習筆記 : 關於 SSD1306 OLED 驅動程式

前年 (2022) 年底曾經用 Wemos D1 Mini (ESP8266) 做過 SSD1306 顯示器實驗, 參考 :

# MicroPython 學習筆記 : SSD1306 OLED 顯示器測試 (一)

# MicroPython 學習筆記 : SSD1306 OLED 顯示器測試 (二)

那時因手上沒有多餘的 ESP32 開發板, 就沒有在 ESP32 上測試, 以為所用的驅動程式 ssd1306.py 在 ESP32 板上應該沒問題. 我依據之前的筆記去 MicroPython 官網下載驅動程式, 發現它居然已經被移除了 : 

# https://github.com/micropython/micropython/blob/master/drivers/display/ssd1306.py

我在趙英傑老師的 "超圖解 Python 物聯網實作入門" 這本書的第 12 章讀到 "MicroPython 內建控制 OLED 螢幕的 ssd1306 程式庫", 且書中範例都是直接 import ssd1306, 沒有談到如何上傳 ssd1306.py, 所以我認為可能有一段時間 MicroPython 韌體有把 ssd1306 納入內建函式庫, 但最新的 v1.23 版已經拿掉了 : 

MicroPython v1.23.0 on 2024-06-02; Generic ESP32 module with ESP32

Type "help()" for more information.

>>> import ssd1306   

Traceback (most recent call last):

  File "<stdin>", line 1, in <module>

ImportError: no module named 'ssd1306'

所以我只好從以前放在 GitHub 的測試資料中下載當時用在 ESP8266 的 ssd1306.py 上傳到 LOLIN D32 的 ESP32 開發板 (韌體是 v1.23 版) 重做實驗, 結果出現 "I2C operation not supported"  錯誤 : 

MicroPython v1.23.0 on 2024-06-02; Generic ESP32 module with ESP32

Type "help()" for more information.

>>> from machine import I2C, Pin  

import ssd1306

# LOLIN D32 的硬體 I2C 為 GPIO22 (SCL) 與 21 (SDA)

i2c=I2C(0, scl=Pin(22), sda=Pin(21))     

oled=ssd1306.SSD1306_I2C(128, 64, i2c)    # 0.96 吋解析度 128*64 

oled.fill(1)      # 將 1 填滿顯示緩衝器 (點亮畫素)

oled.show()    

Traceback (most recent call last):

  File "<stdin>", line 6, in <module>

  File "ssd1306.py", line 109, in __init__

  File "ssd1306.py", line 37, in __init__

  File "ssd1306.py", line 64, in init_display

  File "ssd1306.py", line 89, in show

  File "ssd1306.py", line 119, in write_data

OSError: I2C operation not supported    

但回到 ESP8266 開發板 (MicroPython v1.19.1) 測試又正常, 我原先以為是韌體版本的關係, 於是把一顆 LOLIN D32 燒回 v1.19.1 版重試還是出現相同錯誤, 可見與韌體版本無關, 兩年前若有在 ESP32 開發板上做實驗結果應該一樣. 這樣看來是驅動程式 ssd1306.py 的問題了, 它可能一開始就是為 ESP8266 寫的. 

於是我將上面錯誤訊息與兩年前用的 ssd1306.py 原始碼貼給 ChatGPT 分析錯誤原因, 詢問如何改成 ESP32 開發板可用之驅動程式, 經過來回修正得到下面的 ssd1306_esp32.py : 

# ssd1306_esp32.py

# MicroPython SSD1306 OLED driver, I2C and SPI interfaces

from micropython import const

import time

import framebuf

# register definitions

SET_CONTRAST        = const(0x81)

SET_ENTIRE_ON       = const(0xa4)

SET_NORM_INV        = const(0xa6)

SET_DISP            = const(0xae)

SET_MEM_ADDR        = const(0x20)

SET_COL_ADDR        = const(0x21)

SET_PAGE_ADDR       = const(0x22)

SET_DISP_START_LINE = const(0x40)

SET_SEG_REMAP       = const(0xa0)

SET_MUX_RATIO       = const(0xa8)

SET_COM_OUT_DIR     = const(0xc0)

SET_DISP_OFFSET     = const(0xd3)

SET_COM_PIN_CFG     = const(0xda)

SET_DISP_CLK_DIV    = const(0xd5)

SET_PRECHARGE       = const(0xd9)

SET_VCOM_DESEL      = const(0xdb)

SET_CHARGE_PUMP     = const(0x8d)

class SSD1306:

    def __init__(self, width, height, external_vcc):

        self.width = width

        self.height = height

        self.external_vcc = external_vcc

        self.pages = self.height // 8

        self.buffer = bytearray(self.pages * self.width)

        self.framebuf = framebuf.FrameBuffer(self.buffer, self.width, self.height, framebuf.MVLSB)

        self.poweron()

        self.init_display()

    def poweron(self):

        # 如果不需要其他行為，可以保持為 pass，或者你可以加入實際的硬體啟動程式碼

        pass

    def init_display(self):

        for cmd in (

            SET_DISP | 0x00, # off

            # address setting

            SET_MEM_ADDR, 0x00, # horizontal

            # resolution and layout

            SET_DISP_START_LINE | 0x00,

            SET_SEG_REMAP | 0x01, # column addr 127 mapped to SEG0

            SET_MUX_RATIO, self.height - 1,

            SET_COM_OUT_DIR | 0x08, # scan from COM[N] to COM0

            SET_DISP_OFFSET, 0x00,

            SET_COM_PIN_CFG, 0x02 if self.height == 32 else 0x12,

            # timing and driving scheme

            SET_DISP_CLK_DIV, 0x80,

            SET_PRECHARGE, 0x22 if self.external_vcc else 0xf1,

            SET_VCOM_DESEL, 0x30, # 0.83*Vcc

            # display

            SET_CONTRAST, 0xff, # maximum

            SET_ENTIRE_ON, # output follows RAM contents

            SET_NORM_INV, # not inverted

            # charge pump

            SET_CHARGE_PUMP, 0x10 if self.external_vcc else 0x14,

            SET_DISP | 0x01): # on

            self.write_cmd(cmd)

        self.fill(0)

        self.show()

    def poweroff(self):

        self.write_cmd(SET_DISP | 0x00)

    def contrast(self, contrast):

        self.write_cmd(SET_CONTRAST)

        self.write_cmd(contrast)

    def invert(self, invert):

        self.write_cmd(SET_NORM_INV | (invert & 1))

    def show(self):

        x0 = 0

        x1 = self.width - 1

        if self.width == 64:

            # displays with width of 64 pixels are shifted by 32

            x0 += 32

            x1 += 32

        self.write_cmd(SET_COL_ADDR)

        self.write_cmd(x0)

        self.write_cmd(x1)

        self.write_cmd(SET_PAGE_ADDR)

        self.write_cmd(0)

        self.write_cmd(self.pages - 1)

        self.write_data(self.buffer)

    def fill(self, col):

        self.framebuf.fill(col)

    def pixel(self, x, y, col):

        self.framebuf.pixel(x, y, col)

    def scroll(self, dx, dy):

        self.framebuf.scroll(dx, dy)

    def text(self, string, x, y, col=1):

        self.framebuf.text(string, x, y, col)

class SSD1306_I2C(SSD1306):

    def __init__(self, width, height, i2c, addr=0x3c, external_vcc=False):

        self.i2c = i2c

        self.addr = addr

        self.temp = bytearray(2)

        super().__init__(width, height, external_vcc)

    def write_cmd(self, cmd):

        self.temp[0] = 0x80 # Co=1, D/C#=0

        self.temp[1] = cmd

        self.i2c.writeto(self.addr, self.temp)

        

    def write_data(self, buf):

        # 使用 writeto 將資料一次性寫入

        self.i2c.writeto(self.addr, b'\x40' + buf)        

class SSD1306_SPI(SSD1306):

    def __init__(self, width, height, spi, dc, res, cs, external_vcc=False):

        self.rate = 10 * 1024 * 1024

        dc.init(dc.OUT, value=0)

        res.init(res.OUT, value=0)

        cs.init(cs.OUT, value=1)

        self.spi = spi

        self.dc = dc

        self.res = res

        self.cs = cs

        super().__init__(width, height, external_vcc)

    def write_cmd(self, cmd):

        self.spi.init(baudrate=self.rate, polarity=0, phase=0)

        self.cs(1)

        self.dc(0)

        self.cs(0)

        self.spi.write(bytearray([cmd]))

        self.cs(1)

    def write_data(self, buf):

        self.spi.init(baudrate=self.rate, polarity=0, phase=0)

        self.cs(1)

        self.dc(1)

        self.cs(0)

        self.spi.write(buf)

        self.cs(1)

    def poweron(self):

        self.res(1)

        time.sleep_ms(1)

        self.res(0)

        time.sleep_ms(10)

        self.res(1)

藍色粗體部分就是增加或改寫的程式碼, 其一是在 SSD1306 類別中新增一個 dummy 的 power_on() 方法, 其二是在 SSD1306_I2C 類別中的 write_data() 方法改寫為只用 writeto() 一次寫入. 此驅動程式經測試在 ESP8266 與 ESP32 上均可順利執行. 我將此驅動程式放在 GitHub : 

# https://github.com/tony1966/tony1966.github.io/blob/master/test/MicroPython/lib/ssd1306_esp32.py 

既然此驅動程式用在 ESP8266/ESP32 都可以, 其實可以去掉後面的 "_esp32". 

完成驅動程式改寫後卻發現 Random Nerd 的網站也有提供 ssd1306.py :

# MicroPython: OLED Display with ESP32 and ESP8266

我將它的 Adafruit 版本驅動程式分別在 ESP8266 與 ESP32 上測試均可正常執行, 複製如下 :

# ssd1306.py 

# MicroPython SSD1306 OLED driver, I2C and SPI interfaces created by Adafruit

import time

import framebuf

# register definitions

SET_CONTRAST        = const(0x81)

SET_ENTIRE_ON       = const(0xa4)

SET_NORM_INV        = const(0xa6)

SET_DISP            = const(0xae)

SET_MEM_ADDR        = const(0x20)

SET_COL_ADDR        = const(0x21)

SET_PAGE_ADDR       = const(0x22)

SET_DISP_START_LINE = const(0x40)

SET_SEG_REMAP       = const(0xa0)

SET_MUX_RATIO       = const(0xa8)

SET_COM_OUT_DIR     = const(0xc0)

SET_DISP_OFFSET     = const(0xd3)

SET_COM_PIN_CFG     = const(0xda)

SET_DISP_CLK_DIV    = const(0xd5)

SET_PRECHARGE       = const(0xd9)

SET_VCOM_DESEL      = const(0xdb)

SET_CHARGE_PUMP     = const(0x8d)

class SSD1306:

    def __init__(self, width, height, external_vcc):

        self.width = width

        self.height = height

        self.external_vcc = external_vcc

        self.pages = self.height // 8

        # Note the subclass must initialize self.framebuf to a framebuffer.

        # This is necessary because the underlying data buffer is different

        # between I2C and SPI implementations (I2C needs an extra byte).

        self.poweron()

        self.init_display()

    def init_display(self):

        for cmd in (

            SET_DISP | 0x00, # off

            # address setting

            SET_MEM_ADDR, 0x00, # horizontal

            # resolution and layout

            SET_DISP_START_LINE | 0x00,

            SET_SEG_REMAP | 0x01, # column addr 127 mapped to SEG0

            SET_MUX_RATIO, self.height - 1,

            SET_COM_OUT_DIR | 0x08, # scan from COM[N] to COM0

            SET_DISP_OFFSET, 0x00,

            SET_COM_PIN_CFG, 0x02 if self.height == 32 else 0x12,

            # timing and driving scheme

            SET_DISP_CLK_DIV, 0x80,

            SET_PRECHARGE, 0x22 if self.external_vcc else 0xf1,

            SET_VCOM_DESEL, 0x30, # 0.83*Vcc

            # display

            SET_CONTRAST, 0xff, # maximum

            SET_ENTIRE_ON, # output follows RAM contents

            SET_NORM_INV, # not inverted

            # charge pump

            SET_CHARGE_PUMP, 0x10 if self.external_vcc else 0x14,

            SET_DISP | 0x01): # on

            self.write_cmd(cmd)

        self.fill(0)

        self.show()

    def poweroff(self):

        self.write_cmd(SET_DISP | 0x00)

    def contrast(self, contrast):

        self.write_cmd(SET_CONTRAST)

        self.write_cmd(contrast)

    def invert(self, invert):

        self.write_cmd(SET_NORM_INV | (invert & 1))

    def show(self):

        x0 = 0

        x1 = self.width - 1

        if self.width == 64:

            # displays with width of 64 pixels are shifted by 32

            x0 += 32

            x1 += 32

        self.write_cmd(SET_COL_ADDR)

        self.write_cmd(x0)

        self.write_cmd(x1)

        self.write_cmd(SET_PAGE_ADDR)

        self.write_cmd(0)

        self.write_cmd(self.pages - 1)

        self.write_framebuf()

    def fill(self, col):

        self.framebuf.fill(col)

    def pixel(self, x, y, col):

        self.framebuf.pixel(x, y, col)

    def scroll(self, dx, dy):

        self.framebuf.scroll(dx, dy)

    def text(self, string, x, y, col=1):

        self.framebuf.text(string, x, y, col)

class SSD1306_I2C(SSD1306):

    def __init__(self, width, height, i2c, addr=0x3c, external_vcc=False):

        self.i2c = i2c

        self.addr = addr

        self.temp = bytearray(2)

        # Add an extra byte to the data buffer to hold an I2C data/command byte

        # to use hardware-compatible I2C transactions.  A memoryview of the

        # buffer is used to mask this byte from the framebuffer operations

        # (without a major memory hit as memoryview doesn't copy to a separate

        # buffer).

        self.buffer = bytearray(((height // 8) * width) + 1)

        self.buffer[0] = 0x40  # Set first byte of data buffer to Co=0, D/C=1

        self.framebuf = framebuf.FrameBuffer1(memoryview(self.buffer)[1:], width, height)

        super().__init__(width, height, external_vcc)

    def write_cmd(self, cmd):

        self.temp[0] = 0x80 # Co=1, D/C#=0

        self.temp[1] = cmd

        self.i2c.writeto(self.addr, self.temp)

    def write_framebuf(self):

        # Blast out the frame buffer using a single I2C transaction to support

        # hardware I2C interfaces.

        self.i2c.writeto(self.addr, self.buffer)

    def poweron(self):

        pass

class SSD1306_SPI(SSD1306):

    def __init__(self, width, height, spi, dc, res, cs, external_vcc=False):

        self.rate = 10 * 1024 * 1024

        dc.init(dc.OUT, value=0)

        res.init(res.OUT, value=0)

        cs.init(cs.OUT, value=1)

        self.spi = spi

        self.dc = dc

        self.res = res

        self.cs = cs

        self.buffer = bytearray((height // 8) * width)

        self.framebuf = framebuf.FrameBuffer1(self.buffer, width, height)

        super().__init__(width, height, external_vcc)

    def write_cmd(self, cmd):

        self.spi.init(baudrate=self.rate, polarity=0, phase=0)

        self.cs.high()

        self.dc.low()

        self.cs.low()

        self.spi.write(bytearray([cmd]))

        self.cs.high()

    def write_framebuf(self):

        self.spi.init(baudrate=self.rate, polarity=0, phase=0)

        self.cs.high()

        self.dc.high()

        self.cs.low()

        self.spi.write(self.buffer)

        self.cs.high()

    def poweron(self):

        self.res.high()

        time.sleep_ms(1)

        self.res.low()

        time.sleep_ms(10)

        self.res.high()

我將這兩個程式碼貼給 ChatGPT 比較後得到下面評語 :

• Adafruit 版本 : 對 I2C 實現做了更專門的優化, 使用硬體兼容的緩衝區和 FrameBuffer1, 可以更高效地管理顯示更新.
• 建議版本 : 是比較通用的 MicroPython 驅動實現, 使用標準 framebuf, 適合不依賴特定硬體兼容性的場景. 

兩者在功能上都是完整的 SSD1306 驅動, 只是在硬體兼容和效率優化上略有不同. 

總之, Adafruit 的版本優點是效能優化; 而 ChatGPT 建議的版本則是硬體相容性較好, 可擇一使用取代原本只能用在 ESP8266 那個舊版本. 

此 Adafruit 的 SSD1306 驅動程式也也複製一份放在 GitHub : 

# https://github.com/adafruit/Adafruit_CircuitPython_GFX/blob/main/adafruit_gfx/gfx.py