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.
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.
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 https://RandomNerdTutorials.com
from machine import Pin
from time import sleep
led = Pin(2, Pin.OUT)
while True:
led.value(not led.value())
sleep(0.5)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:
- 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.
![Arduino UNO R4 WiFi [ABX00087] - Renesas RA4M1 / ESP32-S3 - Wi-Fi, Bluetooth, USB-C, CAN, DAC, OP AMP, Qwiic Connector, 12x8 LED Matrix](https://m.media-amazon.com/images/I/416S910MpBL.jpg)
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:
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:
![Official Arduino Starter Kit [K000007] (English Projects Book) - 12 DIY Projects with All Necessary Electronic Components and Instructions - origianl kit by Arduino from Italy](https://m.media-amazon.com/images/I/51fPv6DsjQL.jpg)
- 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:
Let’s take a closer look at each section of uPyCraft IDE:
- Folder and files
- Editor
- MicroPython Shell/Terminal
- 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 boot.py file by default. It is advised that you construct a main.py file to run your main function.
- boot.py: runs when the device starts and sets up several configuration options;
- main.py: This is the main script that contains your code. It is executed immediately after boot.py.
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.
Note: To change your user directory, simply go to Tools >InitConfig and click the user space directory folder to choose a new path.
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:
- 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.
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')
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.
Creating the main.py file on your board
1. Press the “New file” button to create a new file.
2. Press the “Save file” button to save the file on your PC.
3. A new window opens; name your file main.py and save it on your PC.
4. After that, you should see the following in your uPyCraft IDE (the boot.py file on your device and a new tab with the main.py file):
5. Click the “Download and run” button to upload the file to your ESP board:
6. The device directory should now load the main.py file. Your ESP has the file main.py stored.
Uploading the blink LED script
1. Copy the following code to the Editor on the main.py file:
# Complete project details at https://RandomNerdTutorials.com
from machine import Pin
from time import sleep
led = Pin(2, Pin.OUT)
while True:
led.value(not led.value())
sleep(0.5)2. Press the “Stop” button to stop any script from running on your board:
3. Click the “Download and Run button” to upload the script to the ESP32 or ESP8266:
4. You should see a message saying “download ok” in the Shell window.
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.
2. To restart your board and run the script from the beginning, press the on-board ESP32/ESP8266 EN (ENABLE) or RST (RESET) button:
If you're using an ESP32, your Terminal messages should look like this following an EN/RST button press:
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:
Here’s the 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
os.listdir('.')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'os' isn't definedOr this message:
>>>
Ready to download this file,please wait!
...
download ok
os.listdir('.')
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 triggeredThe “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.
Conclusion
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:
- ESP8266 NodeMCU Deep Sleep with Arduino IDE
- Build a Water Level Control System Using ESP8266 NodeMCU
- Getting Started with ESP8266 NodeMCU Board | Complete Guide
- How to Post on Twitter using an ESP8266
We hope you find this tutorial useful. Thanks for reading.
