Overview: MicroPython of ESP32 with OLED Display
In this guide, you will learn how to use 0.96″ or 1.3″ OLED Display with ESP32 using MicroPython Code. We will use SSD1306 or SSD1315 I2C OLED Display with ESP32 Module. We will write the Micropython Code in uPyCraft IDE and upload the firmware to ESP32 Board. We will show the messages like “Hello World” or any Simple Text on OLED Screen.
You can check the Getting Started with MicroPython on ESP32 using PyCraft IDE before proceeding for this one.
Bill of Materials
Following are the components required for making this project. All the components can be eaily purchased from Amazon. The components purchase link is given below.
| S.N. | Components Name | Quantity | Purchase Links |
|---|---|---|---|
| 1 | ESP32 Board | 1 | Amazon | AliExpress |
| 2 | 0.96" I2C OLED Display | 1 | Amazon | AliExpress |
| 3 | Connecting Jumper Wires | 5 | Amazon | AliExpress |
| 4 | Breadboard | 1 | Amazon | AliExpress |
Or if you want more cheaper item then you can purchase the MakePython ESP32 Board from Makerfabs as shown in the image below. The board contains combined ESP32 Chip + 1.3″ I2C OLED Display supports MicroPython.
To learn more about this board and purchase it online, you can visit this link: MakePython ESP32 Board.
OLED Display
This SSD1306/SSD1315 is a 0.96/1.3 inch blue OLED display module. The display module can be interfaced with any microcontroller using SPI/IIC protocols. It is having a resolution of 128×64. The package includes display board, display,4 pin male header pre-soldered to board.
OLED (Organic Light-Emitting Diode) is a self-light-emitting technology composed of a thin, multi-layered organic film placed between an anode and cathode. In contrast to LCD technology, OLED does not require a backlight. OLED possesses high application potential for virtually all types of displays and is regarded as the ultimate technology for the next generation of flat-panel displays.
You can check this post where we used OLED Display to display the Temperature: Interfacing DS18B20 Temperature Sensor with ESP32 & OLED
Circuit Diagram/Schematics
If you are using “MakePython ESP32 Board“, there is no connection needed at all. The 1.3″ I2C OLED is connected to GPIO5(SCL) & GPIO4(SDA) of ESP32 Board.
In case if you are using Espressif ESP32 Board and external OLED Display, you need to make connections as shown in the image below. The SDA & SCL pin of OLED display is connected to ESP32 GPIO21 & GPIO22 respectively.
MicroPython Code for Interfacing OLED Display with ESP32
The MicroPython Code for Interfacing OLED Display with ESP32 has two part.
1. SSD1306 Library
2. Main Code
The library to write to the OLED display isn’t part of the standard MicroPython library by default. So, first we need to upload the library to the ESP32 board.
SSD1306/SSD1315 OLED Library
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 |
# MicroPython SSD1306 OLED driver, I2C and SPI interfaces from micropython import const import time import framebuf import sys currentBoard="" if(sys.platform=="esp8266"): currentBoard="esp8266" elif(sys.platform=="esp32"): currentBoard="esp32" elif(sys.platform=="pyboard"): currentBoard="pyboard" import pyb # register definitions SET_CONTRAST = const(0x81) SET_ENTIRE_ON = const(0xa4) SET_NORM_INV = const(0xa6) SET_DISP = const(0xae) SET_MEM_ADDR = const(0x20) SET_COL_ADDR = const(0x21) SET_PAGE_ADDR = const(0x22) SET_DISP_START_LINE = const(0x40) SET_SEG_REMAP = const(0xa0) SET_MUX_RATIO = const(0xa8) SET_COM_OUT_DIR = const(0xc0) SET_DISP_OFFSET = const(0xd3) SET_COM_PIN_CFG = const(0xda) SET_DISP_CLK_DIV = const(0xd5) SET_PRECHARGE = const(0xd9) SET_VCOM_DESEL = const(0xdb) SET_CHARGE_PUMP = const(0x8d) class SSD1306: def __init__(self, width, height, external_vcc): self.width = width self.height = height self.external_vcc = external_vcc self.pages = self.height // 8 self.buffer = bytearray(self.pages * self.width) self.framebuf = framebuf.FrameBuffer(self.buffer, self.width, self.height, framebuf.MVLSB) self.poweron() self.init_display() def init_display(self): for cmd in ( SET_DISP | 0x00, # off # address setting SET_MEM_ADDR, 0x00, # horizontal # resolution and layout SET_DISP_START_LINE | 0x00, SET_SEG_REMAP | 0x01, # column addr 127 mapped to SEG0 SET_MUX_RATIO, self.height - 1, SET_COM_OUT_DIR | 0x08, # scan from COM[N] to COM0 SET_DISP_OFFSET, 0x00, SET_COM_PIN_CFG, 0x02 if self.height == 32 else 0x12, # timing and driving scheme SET_DISP_CLK_DIV, 0x80, SET_PRECHARGE, 0x22 if self.external_vcc else 0xf1, SET_VCOM_DESEL, 0x30, # 0.83*Vcc # display SET_CONTRAST, 0xff, # maximum SET_ENTIRE_ON, # output follows RAM contents SET_NORM_INV, # not inverted # charge pump SET_CHARGE_PUMP, 0x10 if self.external_vcc else 0x14, SET_DISP | 0x01): # on self.write_cmd(cmd) self.fill(0) self.show() def poweroff(self): self.write_cmd(SET_DISP | 0x00) def contrast(self, contrast): self.write_cmd(SET_CONTRAST) self.write_cmd(contrast) def invert(self, invert): self.write_cmd(SET_NORM_INV | (invert & 1)) def show(self): x0 = 0 x1 = self.width - 1 if self.width == 64: # displays with width of 64 pixels are shifted by 32 x0 += 32 x1 += 32 self.write_cmd(SET_COL_ADDR) self.write_cmd(x0) self.write_cmd(x1) self.write_cmd(SET_PAGE_ADDR) self.write_cmd(0) self.write_cmd(self.pages - 1) self.write_data(self.buffer) def fill(self, col): self.framebuf.fill(col) def pixel(self, x, y, col): self.framebuf.pixel(x, y, col) def scroll(self, dx, dy): self.framebuf.scroll(dx, dy) def text(self, string, x, y, col=1): self.framebuf.text(string, x, y, col) def hline(self, x, y, w, col): self.framebuf.hline(x, y, w, col) def vline(self, x, y, h, col): self.framebuf.vline(x, y, h, col) def line(self, x1, y1, x2, y2, col): self.framebuf.line(x1, y1, x2, y2, col) def rect(self, x, y, w, h, col): self.framebuf.rect(x, y, w, h, col) def fill_rect(self, x, y, w, h, col): self.framebuf.fill_rect(x, y, w, h, col) def blit(self, fbuf, x, y): self.framebuf.blit(fbuf, x, y) class SSD1306_I2C(SSD1306): def __init__(self, width, height, i2c, addr=0x3c, external_vcc=False): self.i2c = i2c self.addr = addr self.temp = bytearray(2) super().__init__(width, height, external_vcc) def write_cmd(self, cmd): self.temp[0] = 0x80 # Co=1, D/C#=0 self.temp[1] = cmd #IF SYS : global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.i2c.writeto(self.addr, self.temp) elif currentBoard=="pyboard": self.i2c.send(self.temp,self.addr) #ELSE: def write_data(self, buf): self.temp[0] = self.addr << 1 self.temp[1] = 0x40 # Co=0, D/C#=1 global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.i2c.start() self.i2c.write(self.temp) self.i2c.write(buf) self.i2c.stop() elif currentBoard=="pyboard": #self.i2c.send(self.temp,self.addr) #self.i2c.send(buf,self.addr) self.i2c.mem_write(buf,self.addr,0x40) def poweron(self): pass class SSD1306_SPI(SSD1306): def __init__(self, width, height, spi, dc, res, cs, external_vcc=False): self.rate = 10 * 1024 * 1024 dc.init(dc.OUT, value=0) res.init(res.OUT, value=0) cs.init(cs.OUT, value=1) self.spi = spi self.dc = dc self.res = res self.cs = cs super().__init__(width, height, external_vcc) def write_cmd(self, cmd): global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.spi.init(baudrate=self.rate, polarity=0, phase=0) elif currentBoard=="pyboard": self.spi.init(mode = pyb.SPI.MASTER,baudrate=self.rate, polarity=0, phase=0) self.cs.high() self.dc.low() self.cs.low() global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.spi.write(bytearray([cmd])) elif currentBoard=="pyboard": self.spi.send(bytearray([cmd])) self.cs.high() def write_data(self, buf): global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.spi.init(baudrate=self.rate, polarity=0, phase=0) elif currentBoard=="pyboard": self.spi.init(mode = pyb.SPI.MASTER,baudrate=self.rate, polarity=0, phase=0) self.cs.high() self.dc.high() self.cs.low() global currentBoard if currentBoard=="esp8266" or currentBoard=="esp32": self.spi.write(buf) elif currentBoard=="pyboard": self.spi.send(buf) self.cs.high() def poweron(self): self.res.high() time.sleep_ms(1) self.res.low() time.sleep_ms(10) self.res.high() |
1. Open the uPyCraft IDE and create a new file by clicking on this icon.
2. Copy the above code in the IDE window & save it with the name SSD1306.py.
3. Click the “Download & Run” Icon. This will upload the file to the ESP32 Board.
4. The uPyCraft console window should the following message.
Now you can import the SSD1306 Library and use it on the Code Part.
Main Code
After downloading the SSD1306.py file to the ESP32 Board, you now upload the main code.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
from machine import Pin, I2C import ssd1306 from time import sleep # ESP32 Pin assignment i2c = I2C(-1, scl=Pin(5), sda=Pin(4)) oled_width = 128 oled_height = 64 oled = ssd1306.SSD1306_I2C(oled_width, oled_height, i2c) oled.text('Welcome', 0, 0) oled.text('OLED Display', 0, 10) oled.text('how2electronics', 0, 20) oled.text('Makerfabs', 0, 30) oled.show() |
1. Create a new tab on uPyCraft IDE and save it with the name main.py.
Copy the code from above and then upload to the ESP32 Board by clicking on “Download & Run” Button.
After Console windows show the above message, you can now check the OLED Display screen and see the following message as indicated in the code.
Code Explanation
|
1 |
from machine import Pin, I2C |
This line import the Pin and I2C classes from the machine module so that the data can be sent to OLED Display via I2C Communication
|
1 |
import ssd1306 |
This imports the OLED Library that was uploaded previously to the Board.
|
1 |
i2c = I2C(-1, scl=Pin(5), sda=Pin(4)) |
We are defining the I2C Pins of ESP32 Board here. The ESP32 default I2C pins are GPIO22 (SCL) and GPIO21 (SDA). In case of MakePython ESP32 Board, the GPIO Pins are GPIO5 (SCL) and GPIO4 (SDA)
|
1 2 |
oled_width = 128 oled_height = 64 |
This line defines the OLED height and width
|
1 |
oled = ssd1306.SSD1306_I2C(oled_width, oled_height, i2c) |
Then we create an SSD1306_I2C object called oled. This object accepts the OLED width, height, and the I2C pins defined earlier.
|
1 2 |
oled.text('Welcome', 0, 0) oled.text('OLED Display', 0, 10) |
Using oled we are initializing the OLED display & using the text() function we are write text.
|
1 |
oled.show() |
Using this line we call the show() method to update the OLED.
Video Tutorial & Guide
