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

 1 from machine import Pin, I2C, SoftI2C
 2 from time import sleep
 3 
 4 #comment/uncomment the one for you version or change the pins if you use a different setup
 5 
 6 ##for ESP32 - version 1,2 (WIFI KIT, Heltech)
 7 #from ssd1306 import SSD1306_I2C
 8 #i2c = I2C(scl=Pin(15), sda=Pin(4))
 9 #pin16 = Pin(16, Pin.OUT)
10 #pin16.on()
11 
12 #for ESP32-S3 - version 3 (WIFI KIT, Heltech)
13 from ssd1306v03 import SSD1306_I2C
14 i2c = SoftI2C(scl=Pin(18), sda=Pin(17))
15 
16 oled_width = 128
17 oled_height = 64
18 oled = SSD1306_I2C(oled_width,oled_height,i2c)
19 
20 # switch the display off, but it's still active
21 oled.poweroff()
22 
23 # switch the display on again
24 oled.poweron()
25 
26 # contrast in range 0-255 (0=darker)
27 oled.contrast(contrast)
28 
29 # invert in True/False
30 oled.invert(invert)
31 
32 # content will be shown, has to be called when something changes
33 oled.show()
34 
35 
36 # Graphics
37 # fill the screen in color c (0=dark, 1=bright)
38 oled.fill(c)
39 
40 # set pixel at position x,y to color c
41 oled.pixel(x,y,c)
42 
43 # returns color of pixel x,y
44 oled.pixel(x,y)
45 
46 # draws a horizontal line from x,y, length=w in color c
47 oled.hline(x,y,w,c)
48 
49 # draws a vertical line from x,y, length=w in color c
50 oled.vline(x,y,w,c)
51 
52 # draws a line from x1,y1 to x2,y2 in color c
53 oled.line(x1,y1,x2,y2,c)
54 
55 # draws a rectangle at position x,y with width=w and height=h in color c
56 oled.rect(x,y,w,h,c)
57 
58 # draws a filled rectangle at position x,y with width=w and height=h in color c
59 oled.fill_rect(x,y,w,h,c)
60 
61 
62 # Text
63 # set text s at pixel x,y
64 oled.text(s,x,y,c)
65 
66 # line = line number (0-5)
67 # pos = horizontal position (0-15)
68 def text_line(text, line, pos=0):
69   x = 10*pos
70   y = line*11
71   oled.text(text,x,y)
72   oled.show()
73 
74 # don't forget to show!
75 oled.show()

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

 1 from machine import Pin, SoftI2C
 2 from ssd1306v03 import SSD1306_I2C
 3 from time import sleep
 4 
 5 i2c = SoftI2C(scl=Pin(18), sda=Pin(17))
 6 
 7 oled_width = 128
 8 oled_height = 64
 9 oled = SSD1306_I2C(oled_width,oled_height,i2c)
10 
11 # line = line number (0-5)
12 # pos = horizontal position (0-15)
13 def text_line(text, line, pos=0):
14   x = 10*pos
15   y = line*11
16   oled.text(text,x,y)
17   oled.show()
18   
19 # set text
20 oled.text("Hello",0,0)
21 # horizontal line from x=10, y=50, length=70, color bright
22 oled.hline(10,50,70,1)
23 # display it
24 oled.show()
25 sleep(3)
26 
27 # delete all/ set all to dark
28 oled.fill(0)
29 # don't forget to show/display changes
30 oled.show()
31 sleep(1)
32 
33 # set new text
34 oled.text("Hi",0,0)
35 # filled rectangle at x=50, y=20, width=20, height=20, color bright
36 oled.fill_rect(50,20,20,20,1)
37 # inverts colors of display
38 oled.invert(True)
39 oled.show()

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

 1 from machine import Pin, I2C
 2 from ssd1306 import SSD1306_I2C
 3 
 4 i2c = I2C(scl=Pin(15), sda=Pin(4))
 5 pin16 = Pin(16, Pin.OUT)
 6 pin16.on()
 7 
 8 oled_width = 128
 9 oled_height = 64
10 oled = SSD1306_I2C(oled_width,oled_height,i2c)
11 
12 # switch the display off, but it's still active
13 oled.poweroff()
14 
15 # switch the display on again
16 oled.poweron()
17 
18 # contrast in range 0-255 (0=darker)
19 oled.contrast(contrast)
20 
21 # invert in True/False
22 oled.invert(invert)
23 
24 # content will be shown, has to be called when something changes
25 oled.show()
26 
27 
28 # Graphics
29 # fill the screen in color c (0=dark, 1=bright)
30 oled.fill(c)
31 
32 # set pixel at position x,y to color c
33 oled.pixel(x,y,c)
34 
35 # returns color of pixel x,y
36 oled.pixel(x,y)
37 
38 # draws a horizontal line from x,y, length=w in color c
39 oled.hline(x,y,w,c)
40 
41 # draws a vertical line from x,y, length=w in color c
42 oled.vline(x,y,w,c)
43 
44 # draws a line from x1,y1 to x2,y2 in color c
45 oled.line(x1,y1,x2,y2,c)
46 
47 # draws a rectangle at position x,y with width=w and height=h in color c
48 oled.rect(x,y,w,h,c)
49 
50 # draws a filled rectangle at position x,y with width=w and height=h in color c
51 oled.fill_rect(x,y,w,h,c)
52 
53 
54 # Text
55 # set text s at pixel x,y
56 oled.text(s,x,y,c)
57 
58 # line = line number (0-5)
59 # pos = horizontal position (0-15)
60 def text_line(text, line, pos=0):
61   x = 10*pos
62   y = line*11
63   oled.text(text,x,y)
64   oled.show()
65 
66 # don't forget to show!
67 oled.show()

A small Program in MicroPython

 1 from machine import Pin, I2C
 2 from ssd1306 import SSD1306_I2C
 3 
 4 i2c = I2C(scl=Pin(15), sda=Pin(4))
 5 pin16 = Pin(16, Pin.OUT)
 6 pin16.on()
 7 
 8 oled_width = 128
 9 oled_height = 64
10 oled = SSD1306_I2C(oled_width,oled_height,i2c)
11 
12 # line = line number (0-5)
13 # pos = horizontal position (0-15)
14 def text_line(text, line, pos=0):
15   x = 10*pos
16   y = line*11
17   oled.text(text,x,y)
18   oled.show()
19   
20 # set text
21 oled.text("Hello",0,0)
22 # horizontal line from x=10, y=50, length=70, color bright
23 oled.hline(10,50,70,1)
24 # display it
25 oled.show()
26 sleep(3)
27 
28 # delete all/ set all to dark
29 oled.fill(0)
30 # don't forget to show/display changes
31 oled.show()
32 sleep(1)
33 
34 # set new text
35 oled.text("Hi",0,0)
36 # filled rectangle at x=50, y=20, width=20, height=20, color bright
37 oled.fill_rect(50,20,20,20,1)
38 # inverts colors of display
39 oled.invert(True)
40 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/