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

text

image(s)

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/

Background

text

image(s)