OLED LCD Display

Description

See also Tutorial Display

• We use ssd1306.py (for the ESP32 Web Kit version 1 and 2)
• We use ssd1306v03.py (for the ESP32 Wifi Kit v03 version 3)

How to connect it electrically

The display is connected to the I2C bus. The build in Display on the ESP32 is connected to pin 15 (SCL) and pin 4 (SDA). For another ESP32 we can connect an external display to these pins, too.

For the ESP8266 ESP-12F OLED and other ESP8266 the I2C bus is on GPIO5/Pin24 (SCL) and GPIO4/Pin16 (SDA).

How to control it in MicroPython

from machine import Pin, I2C, SoftI2C
from time import sleep

#comment/uncomment the one for you version or change the pins if you use a different setup

##for ESP32 - version 1,2 (WIFI KIT, Heltech)
#from ssd1306 import SSD1306_I2C
#i2c = I2C(scl=Pin(15), sda=Pin(4))
#pin16 = Pin(16, Pin.OUT)
#pin16.on()

#for ESP32-S3 - version 3 (WIFI KIT, Heltech)
from ssd1306v03 import SSD1306_I2C
i2c = SoftI2C(scl=Pin(18), sda=Pin(17))

oled_width = 128
oled_height = 64
oled = SSD1306_I2C(oled_width,oled_height,i2c)

# switch the display off, but it's still active
oled.poweroff()

# switch the display on again
oled.poweron()

# contrast in range 0-255 (0=darker)
oled.contrast(contrast)

# invert in True/False
oled.invert(invert)

# content will be shown, has to be called when something changes
oled.show()


# Graphics
# fill the screen in color c (0=dark, 1=bright)
oled.fill(c)

# set pixel at position x,y to color c
oled.pixel(x,y,c)

# returns color of pixel x,y
oled.pixel(x,y)

# draws a horizontal line from x,y, length=w in color c
oled.hline(x,y,w,c)

# draws a vertical line from x,y, length=w in color c
oled.vline(x,y,w,c)

# draws a line from x1,y1 to x2,y2 in color c
oled.line(x1,y1,x2,y2,c)

# draws a rectangle at position x,y with width=w and height=h in color c
oled.rect(x,y,w,h,c)

# draws a filled rectangle at position x,y with width=w and height=h in color c
oled.fill_rect(x,y,w,h,c)


# Text
# set text s at pixel x,y
oled.text(s,x,y,c)

# line = line number (0-5)
# pos = horizontal position (0-15)
def text_line(text, line, pos=0):
  x = 10*pos
  y = line*11
  oled.text(text,x,y)
  oled.show()

# don't forget to show!
oled.show()

A small Program in MicroPython (for ESP32-S3, Heltec WIFI-Kit version 3)

from machine import Pin, SoftI2C
from ssd1306v03 import SSD1306_I2C
from time import sleep

i2c = SoftI2C(scl=Pin(18), sda=Pin(17))

oled_width = 128
oled_height = 64
oled = SSD1306_I2C(oled_width,oled_height,i2c)

# line = line number (0-5)
# pos = horizontal position (0-15)
def text_line(text, line, pos=0):
  x = 10*pos
  y = line*11
  oled.text(text,x,y)
  oled.show()
  
# set text
oled.text("Hello",0,0)
# horizontal line from x=10, y=50, length=70, color bright
oled.hline(10,50,70,1)
# display it
oled.show()
sleep(3)

# delete all/ set all to dark
oled.fill(0)
# don't forget to show/display changes
oled.show()
sleep(1)

# set new text
oled.text("Hi",0,0)
# filled rectangle at x=50, y=20, width=20, height=20, color bright
oled.fill_rect(50,20,20,20,1)
# inverts colors of display
oled.invert(True)
oled.show()

How to control it in MicroPython (ESP32, Version 1, 2)

from machine import Pin, I2C
from ssd1306 import SSD1306_I2C

i2c = I2C(scl=Pin(15), sda=Pin(4))
pin16 = Pin(16, Pin.OUT)
pin16.on()

oled_width = 128
oled_height = 64
oled = SSD1306_I2C(oled_width,oled_height,i2c)

# switch the display off, but it's still active
oled.poweroff()

# switch the display on again
oled.poweron()

# contrast in range 0-255 (0=darker)
oled.contrast(contrast)

# invert in True/False
oled.invert(invert)

# content will be shown, has to be called when something changes
oled.show()


# Graphics
# fill the screen in color c (0=dark, 1=bright)
oled.fill(c)

# set pixel at position x,y to color c
oled.pixel(x,y,c)

# returns color of pixel x,y
oled.pixel(x,y)

# draws a horizontal line from x,y, length=w in color c
oled.hline(x,y,w,c)

# draws a vertical line from x,y, length=w in color c
oled.vline(x,y,w,c)

# draws a line from x1,y1 to x2,y2 in color c
oled.line(x1,y1,x2,y2,c)

# draws a rectangle at position x,y with width=w and height=h in color c
oled.rect(x,y,w,h,c)

# draws a filled rectangle at position x,y with width=w and height=h in color c
oled.fill_rect(x,y,w,h,c)


# Text
# set text s at pixel x,y
oled.text(s,x,y,c)

# line = line number (0-5)
# pos = horizontal position (0-15)
def text_line(text, line, pos=0):
  x = 10*pos
  y = line*11
  oled.text(text,x,y)
  oled.show()

# don't forget to show!
oled.show()

A small Program in MicroPython

from machine import Pin, I2C
from ssd1306 import SSD1306_I2C

i2c = I2C(scl=Pin(15), sda=Pin(4))
pin16 = Pin(16, Pin.OUT)
pin16.on()

oled_width = 128
oled_height = 64
oled = SSD1306_I2C(oled_width,oled_height,i2c)

# line = line number (0-5)
# pos = horizontal position (0-15)
def text_line(text, line, pos=0):
  x = 10*pos
  y = line*11
  oled.text(text,x,y)
  oled.show()
  
# set text
oled.text("Hello",0,0)
# horizontal line from x=10, y=50, length=70, color bright
oled.hline(10,50,70,1)
# display it
oled.show()
sleep(3)

# delete all/ set all to dark
oled.fill(0)
# don't forget to show/display changes
oled.show()
sleep(1)

# set new text
oled.text("Hi",0,0)
# filled rectangle at x=50, y=20, width=20, height=20, color bright
oled.fill_rect(50,20,20,20,1)
# inverts colors of display
oled.invert(True)
oled.show()

Related Tutorial Videos

Writing to the OLED Display over I2C

In this video on youtube (22:00) we show how to write text to the OLED Display on the ESP32 module. We then show how to connect a poti to an analog input and display the value in a loop on the display: https://youtu.be/UbxwePvgX-U

Another Tutorial (in German) on writing to the OLED Display with some background

There is a tutorial with several parts at "the Die Hobbyelektroniker - Community" on Micropython with ESP32 https://community.hobbyelektroniker.ch/wbb/index.php?board/51-lektion-5-das-display/