Introduction: MicroPython on an ESP32 Board With Integrated SSD1306 OLED Display (WEMOS/Lolin)

Picture of MicroPython on an ESP32 Board With Integrated SSD1306 OLED Display (WEMOS/Lolin)

There are a number of ESP32 development boards available now that also include a connected SSD1306 OLED display. These can be obtained from a number of places including BangGood and AliExpress.

This is a quick run through of one way of getting one of these boards, including the display, working with MicroPython. I use Python 2.7 and a Windows 10 PC but other routes are available for a number of the steps using other version of Python and OS's. I will give some pointers if I can but you may have to do some independent research.

Step 1: Connect the Board and Determine Port Number

Picture of Connect the Board and Determine Port Number

Connect your board to the PC via a suitable USB to micro USB cable.

On the board you may see some text and images being displayed depending on what comes installed on the ESP32.

Open your device manager (simple search for 'device' in the windows search box). When expanded the ports section should show something like the above. Make a note of the port number, e.g. in my case COM3.

Step 2: Downloading and Installing Required Software.


If you do not have it already installed install Python by downloading from the official site. I use Python 2.7, but 3.x should be fine, though you may need to change some instructions.


Pip is a installer for python modules that both downloads and installs the modules. Latest versions of Python include pip but if you are using an older version you can install it using this guide. To see if you have pip look in the Scripts folder of your Python installation, e.g. if you installed in C:\Python27 then look in C:\Python27\Scripts.


This is the recommended tool for installing the firmware on the chip. You use pip to install it as follows:

pip install esptool

If you have an old version you almost certainly need to upgrade to the latest version as follows:

pip install esptool --upgrade

Note that some old versions were actual Python py files, i.e., on windows but the latest versions are executables, though, I assume to maintain compatibility with previous scripts or instructions they are called


Ampy allows you to interact with the file system created on the chip. I use the adafruit version that can be installed as follows:

pip install adafruit-ampy

For information on installing on other OS's or version of Python look here.

Terminal Program

You will need a terminal program to connect you to the serial port. I use PuTTY which you can download from here.

Step 3: Obtain MicroPython and Install It.

Picture of Obtain MicroPython and Install It.

Get the Bin File

MicroPython for the ESP32 chips can be obtained from here. Note that at the time of writing this port is under development and only daily builds are available.

Download the bin file and make a note of its location.

Get to a command prompt. On Windows simply type CMD in the search box and select 'Command Prompt'.

In the command prompt change directory to the Python scripts directory. So, for example, if you have installed Python in C:\Python27 enter the following:

cd c:\Python27\Scripts

If installed on another disk, e.g. d:\Python27 you will have to change the active disk first.


cd d:\Python27\Scripts

Check Connection

We can now use to initially check the connection to the ESP32. The quickest way to do this is the command: --port COMX flash_id

Where you replace the COMX with your port identifier, e.g. COM3 in my case. This command should produce a log similar to the first above that includes 'Detected Flash Size'. If it does all is going well.

Erase Flash

Before installing the bin file we need to erase the flash on the chip. To do this enter the following command --port COMX erase_flash

Again replacing COMX with your port identifier. You should get a output like the image above containing 'Chip erase completed successfully'.

Program with the MicroPython file.

Enter the following command, replacing COMX with your serial port and X:\somewhere\micropython.bin with the location of the downloaded bin file. --chip esp32 --port COMX write_flash -z 0x1000 X:\somewhere\micropython.bin

This will take a few seconds at the end you should get an output as above containing 'Hash of data verified'.

Check Installation using Terminal program.

Open your terminal program, I use PuTTY and connect to the port via a serial connection at 115200 baud. On connecting you should get something like the PuTTY window shown. Do not worry about the error, we shall fix that shortly. In time honoured tradition enter the following line at the prompt.

print("Hello World")

Step 4: Fixing the Error and Uploading the OLED Library.

Fixing the Error

The error comes from missing a file (see here for report). For now we do as suggest in the report and create a that just acknowledges its own existence.

At the prompt enter the following lines.

f = open("", "w")

f.write("print(\" Hello\")\n")


Next time you reboot the board the error will be replaced by the above printed remark.

Uploading the OLED Library

I used the adafruit MicroPython module that can be found here. Download the ZIP and then just extract the file to a known location on your machine.

To upload this we are going to use ampy but before we can do so we must close the terminal program as only one of the programs can use the connection at a time.

Once it has been closed enter the following on the command prompt, still in the Scripts directory.

ampy --port COMX --baud 115200 put x:\location\

Where you replace COMX with the port you are using and x:\location\ where you downloaded the python file.

Open the terminal program again, you may need to press enter once connected to get the >>> prompt. Check the existence of the new file by entering:

import os


The result of which should be:

 ['', '', '']

Step 5: Displaying Some Text.

Picture of Displaying Some Text.


These commands are all done when connected to the board via the terminal server.

First import the libraries we need

import machine, ssd1306

Now we create the I2C connector object and use that to create the screen object

i2c = machine.I2C(scl=machine.Pin(4), sda=machine.Pin(5))

oled = ssd1306.SSD1306_I2C(128, 64, i2c)

Note that unlike the adafruit example for connecting micropython to an ssd1306 here the pin numbers are the otherway round.

Finally we can output to the screen, first by clearing to black, then adding some text and finally showing it on the screen.

oled.text('MicroPython on', 0, 0)
oled.text('an ESP32 with an', 0, 10)
oled.text('attached SSD1306', 0, 20)
oled.text('OLED display', 0, 30)

After which the text, as the image above, should be displayed on the screen.

Other tutorial are available for other elements of using MicroPython but hopefully this will be of use for this particular situation.


AlbertoM140 (author)2017-11-01

Hi thank for your guide, unfortunately I've a problem with the OLED (I put micropython on Hemlet WiFi KIT32 ) the problem is:

>>> import machine, ssd1306

>>> i2c = machine.I2C(scl=machine.Pin(15), sda=machine.Pin(4))

>>> oled = ssd1306.SSD1306_I2C(128, 64, i2c)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

File "", line 117, in __init__

File "", line 37, in __init__

File "", line 62, in init_display

File "", line 122, in write_cmd

AlbertoM140 (author)AlbertoM1402017-11-01

.... sorry was missing the final part of the error:
OSError: [Errno 19] ENODEV


PaulE127 (author)AlbertoM1402017-11-01

Looking at the code it is failing at:

self.i2c.writeto(self.addr, self.buffer)

If you are not using the same set up as in the photo it's quite possible that the pins for I2C are different. I would try the command


after create the i2c object. If that fails it's likely that you need to used different pin numbers. I would check first reversing the numbers as see what happens.

AlbertoM140 made it! (author)PaulE1272017-11-02

Thank you for your reply and your help!.
The pins were right for the HelTec WiFiKIT32 board. The embedded display is mounted on SCL(15) SDA(4), but thanks to you, I remembered that another pin must be connected, in fact the pin 16 is the OLED_RST . The OLED_RST must be high during normal operations (now I putted a LED on pin, to don't forghet it anymore!).
With this code everythings works fine!

import machine
pin16 = machine.Pin(16, machine.Pin.OUT)
import machine, ssd1306
i2c = machine.I2C(scl=machine.Pin(15), sda=machine.Pin(4))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)


tumidinoda (author)2017-11-01

Many thanks, worked perfectly.
Vielen Dank

MicheleH14 made it! (author)2017-10-18

Fast and easy i love it... any idea how we change the fonts ?

PaulE127 (author)MicheleH142017-10-22

Not sure how to change the fonts. Given you can use the SSD2306 library to access individual pixels you should be able to use the adafruit font library found here: but I have not had time to play with it yet.

MicheleH14 (author)PaulE1272017-10-22

Thanks i looked there but it just shows a bin file they seem to be converting not how to create or get additional font bins.

PaulE127 (author)MicheleH142017-10-23

That probably was not the best link. I think its covered here: though not looked in depth but need to soon as trying to write text to an epaper display and at the moment I can only get it to write text in portrait mode.

DarrenD33 (author)2017-10-21

Worked perfectly! Thank you.

Edinho1 (author)2017-09-16

Muito bom o tutorial, funcionou corretamente...

SlayerBill (author)2017-09-04

I had a problem uploading the .bin file as listed but got it working using the following: --chip esp32 --port COMX write_flash -z 0x1000 firmware_filename_here.bin

PaulE127 (author)SlayerBill2017-09-05

Thanks. I will edit it accordingly.

DIY Hacks and How Tos (author)2017-07-09

Great first Instructable. Thanks for sharing with the community.

About This Instructable




More by PaulE127:MicroPython on an ESP32 Board With Integrated SSD1306 OLED Display (WEMOS/Lolin)
Add instructable to: