Introduction: 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
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.
Python
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
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.
Esptool
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. esptool.py, on windows but the latest versions are executables, though, I assume to maintain compatibility with previous scripts or instructions they are called esptool.py.exe.
Ampy
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.
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.
d: cd d:\Python27\Scripts
Check Connection
We can now use esptool.py to initially check the connection to the ESP32. The quickest way to do this is the command:
esptool.py --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
esptool.py --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.
esptool.py --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 main.py file (see here for report). For now we do as suggest in the report and create a main.py that just acknowledges its own existence.
At the prompt enter the following lines.
f = open("main.py", "w")
f.write("print(\"main.py: Hello\")\n")
f.close()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 ssd1306.py module that can be found here. Download the ZIP and then just extract the ssd1306.py 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\ssd1306.py
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 os.listdir()
The result of which should be:
['boot.py', 'main.py', 'ssd1306.py']
Step 5: Displaying Some Text.
Finally...
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.fill(0)
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)oled.show()
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.
