Getting Started with MicroPython on ESP32 and ESP8266

Get started with MicroPython firmware for the ESP32 and ESP8266. We'll introduce you to MicroPython, show you the differences between it and regular Python, and show you how to program your ESP-based boards using MicroPython using the uPyCraft IDE. You will have your first LED flashing using MicroPython after following this instruction.

What is MicroPython?

MicroPython is a Python 3 reimplementation targeted at embedded devices and microcontrollers. MicroPython and regular Python are extremely similar. So, if you know how to program in Python, you can also program in MicroPython.

What is MicroPython

Python vs MicroPython

With a few exceptions, the Python language features are likewise available in MicroPython. The most significant difference between Python and MicroPython is that MicroPython was designed to work in constrained environments.

python VS micropython

As a result, MicroPython does not include the whole standard library. It only provides a small subset of the standard Python library. It does, however, contain modules for accessing low-level hardware, which means there are libraries for readily accessing and interacting with the GPIOs.

Devices having Wi-Fi capabilities, like the ESP8266 and ESP32, also include modules to support network work connections.

Why MicroPython?

Python is a programming language that is widely used, simple, and easy to learn. As a result, the introduction of MicroPython makes it exceedingly simple and easy to program digital electronics. MicroPython is an excellent starting point if you've never programmed digital electronics before.

The goal of MicroPython is to make programming digital electronics as simple as possible so that it may be used by everyone. MicroPython is being used by hobbyists, researchers, teachers, and even in commercial applications. The code for flashing an LED on an ESP32 or ESP8266 is as simple as the following:

# Complete project details at

from machine import Pin
from time import sleep

led = Pin(2, Pin.OUT)

while True:
  led.value(not led.value())

MicroPython has an interactive REPL (Read-Evaluate-Print Loop), which is a great feature. The REPL enables you to connect to a board and quickly run code without the need to compile or upload code.

MicroPython – Boards support

MicroPython runs on many different devices and boards, such as:

MicroPython on ESP32 and ESP8266: boards supported
  • ESP32
  • ESP8266
  • PyBoard
  • Micro: Bit
  • Teensy 3.X
  • WiPy – Pycom
  • Adafruit Circuit Playground Express
  • Other ESP32/ESP8266 based boards

Take a look at the following links for more information on other boards that support MicroPython:

MicroPython and the ESP32 and ESP8266 boards will be used in our projects.

The ESP32 is the ESP8266's successor. So, for the time being, not all features of the ESP32 are available in MicroPython to get the most out of it; it is still an ongoing project. However, it is quite useful and may be used to create a variety of projects.

The ESP32 and ESP8266 boards are quite similar, and there won't be much of a difference when you program them using MicroPython. This means that whatever you write for the ESP8266 should also run on the ESP32 with no or minimal changes (mostly updating the pin assignment).

Installing uPyCraft IDE

Install uPyCraft IDE on your PC before continuing with this tutorial. To install uPyCraft IDE, follow one of the following tutorials:

Flashing MicroPython Firmware to ESP32/ESP8266

Unlike other boards, MicroPython is not pre-flashed on the ESP32 or ESP8266. Flashing or uploading the board is the initial step in using MicroPython to program your boards. To flash MicroPython firmware on your board, follow the next tutorial:

esp8266 firmware flashing message

Getting Started with uPyCraft IDE

To help you get started programming the ESP32 and ESP8266 using MicroPython, we'll give you an overview of the uPyCraft IDE software in this part.

The IDE is a piece of software that offers tools to help with the development, debugging, and uploading of code. With MicroPython, there are several ways to program your ESP board. We picked the uPyCraft IDE because it is simple and intuitive to use and works great with the ESP board.

At this point, we assumed that you had:

  • uPyCraft IDE installed on your computer
  • ESP32/ESP8266 flashed with MicroPython firmware

uPyCraft IDE Overview

Open the uPyCraft IDE; a new window opens as follows:

7 uPyCraft IDE Windows PC

Let’s take a closer look at each section of uPyCraft IDE:

uPycraft ide getting started
  1. Folder and files
  2. Editor
  3. MicroPython Shell/Terminal
  4. Tools

1. Folder and files

This section shows numerous folders and files. The device folder shows the files that are currently stored on your ESP board. When you open the device folder after connecting your ESP32 or ESP8266 via serial to the uPyCraft IDE, all files stored there should load. You should only have a file by default. It is advised that you construct a file to run your main function.

  • runs when the device starts and sets up several configuration options;
  • This is the main script that contains your code. It is executed immediately after

The SD folder is meant to access files stored on SD cards; this works only with boards like the PyBoard that include an SD card port.

The uPy_lib shows the built-in IDE library files.

Finally, the workspace is a directory where your files are saved. On your PC, these files are stored in a directory that you have defined. This is especially useful for keeping track of all your files.

To select your working directory while using uPycraft for the first time, click the workspace folder. A new window appears, allowing you to choose your workspace directory. As your working directory, create a new folder or select an existing one.

Then, go to File > Reflush Directory to update the directory.

reflush directory

Note: To change your user directory, simply go to Tools >InitConfig and click the user space directory folder to choose a new path.

choose another directory

2. Editor

The Editor section is where you write code and edit .py files. You may open many files at once, and the editor will open a new tab for each one.

3. MicroPython Shell/terminal

You may type commands into the MicroPython Shell that will be performed instantly by your ESP board without the need to upload new files. The terminal additionally displays information about a running program's state, shows errors relating to upload and print syntax, prints messages, and so on.

4. Tools

The task icons on the rightmost side enable you to perform things quickly. In the figure below, each button is labeled:

uPycraft ide tools
  • New file: creates a new file in the Editor.
  • Open file: open a file from your computer.
  • Save file: saves a file.
  • Download and run: Upload the code to your board and execute the code.
  • Stop: stop the execution of the code. It’s the same as entering CRTL+C on the shell to stop all scripts from running.
  • Connect/Disconnect: connect or disconnect from your board via Serial. You must select the serial port first in Tools > Serial.
  • Undo: undo the last change in the code Editor.
  • Redo: redo the last change in the code Editor.
  • Syntax check: check the syntax of your code.
  • Clear: clear the Shell/terminal window messages.

Running Your First Script

We'll upload a new script that simply blinks the onboard LED of your ESP32 or ESP8266 to familiarise you with the process of writing a file and running code on your ESP32 or ESP8266 boards.

Establishing communication with the board

The following steps should be taken once the MicroPython firmware has been installed on your board and the board has been connected to your computer via a USB cable:

1. Go to Tools > Board and select the board you’re using.

2. Go to Tools > Port and select the com port your ESP is connected to.

3. Press the Connect button to establish serial communication with your board.

uPycraft ide tools menu connect or disconnect

4. Following a successful connection with your board, the >>> should display in the Shell window. To test whether it's working, type the print command:

>>> print('Hello')

The message “Hello” should be printed. You can only proceed with this tutorial if you see that message. Otherwise, ensure that you have established serial connectivity with your board or that the MicroPython firmware on your board has been successfully flashed.

print hello

Creating the file on your board

1. Press the “New file” button to create a new file.

uPycraft ide tools menu new file

2. Press the “Save file” button to save the file on your PC.

uPycraft ide tools menu save file

3. A new window opens; name your file and save it on your PC.

new file created uPyCraft IDE

4. After that, you should see the following in your uPyCraft IDE (the file on your device and a new tab with the file):

main py file created

5. Click the “Download and run” button to upload the file to your ESP board:

uPycraft ide tools menu download and run

6. The device directory should now load the file. Your ESP has the file stored.

upload file to esp32

Uploading the blink LED script

1. Copy the following code to the Editor on the file:

# Complete project details at

from machine import Pin
from time import sleep

led = Pin(2, Pin.OUT)

while True:
  led.value(not led.value())

2. Press the “Stop” button to stop any script from running on your board:

uPycraft ide tools menu stop

3. Click the “Download and Run button” to upload the script to the ESP32 or ESP8266:

uPycraft ide tools menu download and run

4. You should see a message saying “download ok” in the Shell window.

download ok

Testing the script

To run the script that was just uploaded to your board, you need to follow these steps:

1. Press the “Stop” button.

uPycraft ide tools menu stop

2. To restart your board and run the script from the beginning, press the on-board ESP32/ESP8266 EN (ENABLE) or RST (RESET) button:

MicroPython on ESP32 and ESP8266: esp32 EN enable button

If you're using an ESP32, your Terminal messages should look like this following an EN/RST button press:

uploading new script

The on-board LED on your ESP32 or ESP8266 should be blinking every 500 milliseconds. The ESP32's on-board LED is located as follows:

MicroPython on ESP32 and ESP8266: ESP32 on-board LED

Here’s the ESP8266 on-board LED:

MicroPython on ESP32 and ESP8266: ESP8266 on-board LED

Troubleshooting Tips

We've noticed several common uPyCraft IDE problems and error messages. Restarting your ESP using the on-board EN/RST button often fixes the issue. Alternatively, you may do your desired action by hitting the uPyCraft IDE “Stop” button and repeating it. In case it doesn't work for you, go on to learn how to solve the next common error.

Error #1: You get the following message:

Select Serial Port could not open port 'COM4': FileNotFoundError(2, 'The system cannot find the file specified.', None, 2)

Or an equivalent message:

could not open port 'COM4': PermissionError(13, 'A device attached to the system is not functioning.', None, 31)

Unplug and replug your ESP board. Then, under the Tools > Serial menu, double-check that you've selected the right serial port. Then, to initiate serial communication, click the “Connect/disconnect” button. You should be able to upload a new script or re-run a new code at this point.

This error might indicate that another program is using your serial port (like the Arduino IDE or a serial terminal). Check that you have closed any tabs that may be in serial connection with your ESP board. Then, unplug and replug your ESP board. Finally, restart the uPyCraft IDE and try selecting a serial port from the Tools > Serial menu.

Error #2: Trouble uploading a new script.

already in download model,please wait.

Make sure any running code is terminated by using the “Stop” button in the uPyCraft IDE (1 or 2 times). Then, press the “Download and run” button to upload the new script to your ESP board.

Error #3: After uploading a new script, if you see the following message:

Ready to download this file,please wait!
download ok
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'os' isn't defined

Or this message:

Ready to download this file,please wait!
download ok
OSError: [Errno 98]

It means the new file was successfully uploaded to your board. It printed the “download ok” message, as you can see. To restart your board and re-run the newly uploaded script from the beginning, press the ESP on-board “EN/RST” button.

Error #4: Problem restarting your ESP board, running a new script, or opening the serial port:

Brownout detector was triggered

The “Brownout detector was triggered” error message means there is a hardware malfunction of some sort. It is often associated with one of the following issues:

  • Poor-quality USB cable.
  • The USB cable is too long.
  • Board with some defects (bad solder joints).
  • Bad computer USB port.
  • Or not enough power provided by the computer's USB port.

Solution: Try using a USB hub with an external power source, a shorter USB cable (with data wires), or another computer USB port.

Important: If you keep getting weird error messages or problems, we recommend flashing your ESP board with the most recent version of MicroPython firmware: Flash/Upload MicroPython Firmware to ESP32 and ESP8266

Error #5: When I try to open serial communication with the ESP32/ESP8266 in uPyCraft IDE, sometimes it prompts the “Burn Firmware” window, asking to re-flash the MicroPython firmware.

We think this is what's going on: when you run a script on your board, it's occasionally busy running the script and completing the duties. As a result, you need to open the COM tab numerous times or restart the ESP to make it available for serial connection with the uPyCraft IDE.

If you're running a script that uses Wi-Fi, deep sleep, or multiple processes, I recommend trying 3 or 4 times to establish contact. If this is not possible, I recommend re-flashing the ESP with MicroPython firmware.


We hope you liked learning how to program MicroPython on ESP32 and ESP8266. Take a look at our eBook, MicroPython Programming with ESP32 and ESP8266, if you want to learn more about MicroPython.

If you like ESP8266, you may also like:

We hope you find this tutorial useful. Thanks for reading.

Oh hi there It’s nice to meet you.

Sign up to receive awesome content in your inbox, every month.

We don’t spam! Read our privacy policy for more info.

Leave a Reply

Your email address will not be published. Required fields are marked *

Developing IoT Projects with ESP32

Automate your home or business with inexpensive Wi-Fi devices

ESP8266 Home Automation Projects

Leverage the power of this tiny WiFi chip to build exciting smart home projects