Editing OLED LCD Display

= Description =
See also '''[https://www.sketching-with-hardware.org/wiki/Tutorial_Display Tutorial Display]'''

* We use '''[https://www.sketching-with-hardware.org/files/ssd1306.py ssd1306.py]''' (for the [[ESP32 Web Kit]] version 1 and 2)
* We use '''[https://www.sketching-with-hardware.org/files/ssd1306v03.py 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 =
<syntaxhighlight lang="python" line='line'>
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()
</syntaxhighlight>


[[File:DisplayPixel.PNG|600px]]
[[File:DisplayLinePos.PNG|600px]]

= A small Program in MicroPython (for ESP32-S3, Heltec WIFI-Kit version 3) =
<syntaxhighlight lang="python" line='line'>
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()
</syntaxhighlight>

= How to control it in MicroPython (ESP32, Version 1, 2) =
<syntaxhighlight lang="python" line='line'>
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()
</syntaxhighlight>


[[File:DisplayPixel.PNG|600px]]
[[File:DisplayLinePos.PNG|600px]]

= A small Program in MicroPython =
<syntaxhighlight lang="python" line='line'>
# todo 
# code goes here
</syntaxhighlight>


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

<youtube>UbxwePvgX-U</youtube>

== 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/

<youtube>lnxWP7jBnkE</youtube>


= Background =
text

image(s)