Tutorial Display

Control the OLED Display on the ESP32

In this part of the tutorial, we explain how to control the display that is included on the ESP32 web kit module. The display is connected over I2C and we use the microPython module ssd1306.py as library.

Success criteria

• you can write a string to the display
• you can converts numbers to strings and write them to the display
• you can clear the display or fill it
• you can position text at different positions on the display

Required Module and Files

• 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)

• This is a basic display test example for how to use this module
• This is a code example that reads analog in and prints on the display
• you can download all the file in a ZIP: https://www.sketching-with-hardware.org/files/display.zip
• this is based on https://github.com/micropython/micropython/blob/master/drivers/display/ssd1306.py
• and extended by setting the reset pin
  • pin16 = Pin(16, Pin.OUT)
  • pin16.value(1)

Related Components

The components are related to the LMUBox. For more components, see the Hardware List. Many of the pages on actuators and sensor include additional examples.

Microcontroller

• ESP32 Web Kit with integrated OLED Display from Heltec
• ESP8266 ESP-12F OLED NodeMCU Module with integrated 0.91" OLED Display from AZDelivery

Actuators

• OLED LCD Display

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

Using the uPyCraft IDE to upload files

In this video on youtube (6:48), we show how to upload an run Python files with the uPyCraft IDE: https://youtu.be/MXfj_gWf0z4

Reading analog inputs

In this video on youtube (46:23 ) we show how to read an analog input and how to configure the ADC (there is also information on how to connect a resistor and about voltage dividers): https://youtu.be/gjj5KyK2qGI

Code Examples

Code Example: displaytest.py

from machine import I2C, Pin 
import ssd1306

# ESP32 reset pin for display must be 1 - this is pin16 
# should be done in ssd1306.py - if not uncommend the next 2 lines
#pin16 = Pin(16, Pin.OUT)
#pin16.value(1)


# Pins according the schematic https://heltec.org/project/wifi-kit-32/
i2c = I2C(-1, scl=Pin(15), sda=Pin(4))

#display size
oled_width = 128
oled_height = 64
oled = ssd1306.SSD1306_I2C(oled_width, oled_height, i2c)

#test text
oled.text('Hello, World', 0, 0)
oled.text('some more text!?', 0, 10)
oled.text('...even more :-)', 0, 20)

#show is required - otherwise you will not see it
oled.show()

Code Example: adc2disp.py

# test program to read in a analog value on Pin 32 on the ESP32 board
# and display it on the 0.96" OLED Display (Heltec ESP32 Web Kit)

from machine import ADC
from time import sleep
from machine import I2C, Pin 
import ssd1306

# ESP32 reset pin for display must be 1 - this is pin16 
# should be done in ssd1306.py - if not uncommend the next 2 lines
#pin16 = Pin(16, Pin.OUT)
#pin16.value(1)

# this is for ESP32
# Pins according the schematic https://heltec.org/project/wifi-kit-32/
i2c = I2C(-1, scl=Pin(15), sda=Pin(4))

# for ESP8266 it should be:
# i2c = I2C(-1, scl=Pin(5), sda=Pin(4))
 

#display size
oled_width = 128
oled_height = 64
oled = ssd1306.SSD1306_I2C(oled_width, oled_height, i2c)

# for ESP32 setup the ADC on Pin GPIO32
adc = ADC(Pin(32)) 
adc.atten(ADC.ATTN_11DB)    # set 11dB input attenuation (voltage range roughly 0.0v - 3.6v)

# for ESP8266 setup the ADC(0)
#adc = ADC(0) 

while True:
  # read in analog value in v
  v = adc.read()
  # print to serial line
  print(v)
  # empty display
  oled.fill(0)
  oled.show()
  # write v converted to a string onto the display at (0,0)
  oled.text(str(v), 0, 0)
  oled.show()
  sleep(1)