If you want to program your ESP32 and ESP8266 with MicroPython firmware, it’s very handy to use an IDE. In this guide, we’ll introduce you to Thonny IDE. After completing this guide, you’ll have your first LED blinking using MicroPython and Thonny IDE.

We’ve experimented with several IDEs to program the ESP32 and ESP8266 boards using MicroPython, and Thonny IDE is our preference.

It allows you to program your ESP32, ESP8266, Raspberry Pi Pico, and other boards with MicroPython. It is compatible with Windows, Mac OS X, and Linux. It comes installed by default on the Raspberry Pi OS. Additionally, it’s easy to install, so you shouldn’t have problems with the installation process.

Alternatively, you may want to check the following compilation of MicroPython-compatible IDEs:

• MicroPython IDEs for ESP32 and ESP8266

What is MicroPython?

MicroPython is a Python 3 programming language re-implementation targeted for microcontrollers and embedded systems. MicroPython is very similar to regular Python. Apart from a few exceptions, the language features of Python are also available in MicroPython. The most significant difference between Python and MicroPython is that MicroPython was designed to work under constrained conditions.

Because of that, MicroPython does not come with the entire pack of standard libraries. It only includes a small subset of the Python standard libraries, but it includes modules to easily control and interact with the GPIOs, use Wi-Fi, and other communication protocols.

Installing Thonny IDE

In this guide, we provide instructions to install Thonny IDE in different operating systems. Follow the section for the operating system you’re using.

• A) Installing Thonny IDE – Windows PC
• B) Installing Thonny IDE – Mac OS X
• C) Installing Thonny IDE – Linux

Tip: Thonny IDE comes installed by default on the Raspberry Pi OS that is used with the Raspberry Pi board.

A) Installing Thonny IDE – Windows PC

To install Thonny on your Windows PC, follow the next instructions:

1. Go to https://thonny.org

2. Download the Installer for Windows and wait a few seconds while it downloads.

3. Run the .exe file.

4. Follow the installation wizard to complete the installation process. You just need to click “Next”.

5. After completing the installation, open Thonny IDE. A window, as shown in the following figur,e should open.

B) Installing Thonny IDE – Mac OS X

Since Thonny IDE is open source and downloaded from the Internet, it’s not a verified app in the App Store. For security reasons, Mac OS X blocks unknown apps to run on your computer. Follow these next instructions to enable any downloaded software to run in your Mac.

1. Open the “System Preferences...” menu.

2. Open the “Security & Privacy” menu.

3. At the bottom left corner, click the lock icon to modify your “Security & Privacy” settings:

4. Type your username/password and click the “Unlock” button.

5. Finally, select the option “Allow apps downloaded from: Anywhere“.

That’s it, you can close that window.

To install Thonny on Mac OS X, follow the next instructions:

1. Go to https://thonny.org

2. Download the version for Mac OS X and wait a few seconds while it downloads.

3. Open the .dmg file.

4. Drag the “Thonny” application to your Desktop:

5. Thonny IDE is now installed and you can double-click to open it:

6. After the installation is completed, open Thonny IDE. A window as shown in the following figure should open.

C) Installing Thonny IDE – Linux

To install Thonny on your Linux computer, it depends on your Linux distribution and version, follow the next instructions for your system. First, we recommend installing these dependencies: python3, python3-pip, and python3-tk

If you’re in Ubuntu, you can install the Python dependencies like this:

sudo apt install python3 python3-pip python3-tk

After having Python3, pip3, and Python3 Tkinter, you can install Thonny IDE.

• Ubuntu (after running that command, you’ll need to press Enter again to install the software):

bash <(wget -O - https://thonny.org/installer-for-linux)

• Or you can install Thonny IDE with pip3:

sudo pip3 install thonny

• Fedora since 27:

sudo dnf install thonny

• Raspbian since Stretch (installed by default):

sudo apt install python3-thonny

After installing Thonny IDE and depending on your installation method, to open Thonny IDE:

• You either need go to the search bar and type “Thonny” to find it
• Or if you installed Thonny IDE using pip3, you can type in your terminal window:

thonny

Then, it should open Thonny IDE:

Flashing MicroPython Software

MicroPython isn’t flashed onto the ESP32 or ESP8266 boards by default. The first thing you need to do to start programming your boards with MicroPython is flash/upload/burn the firmware.

There are different ways in which you can do that. Thonny IDE comes with a tool that allows you to quickly install MicroPython firmware on your board. That’s the method we’ll use in this tutorial.

Note: flashing your boards with MicroPython is reversible. This means that after you flash the ESP32/ESP8266 with MicroPython, you can still use Arduino IDE in the future. You just need to upload a code using the Arduino IDE to your board.

Flashing MicroPython Firmware using Thonny IDE

In this section, you’ll learn how to flash MicroPython firmware on your boards using Thonny IDE. Follow the next steps:

1) Connect your ESP32 or ESP8266 board to your computer.

2) Open Thonny IDE. Go to Tools > Options > Interpreter.

3) Select the interpreter you want to use accordingly to the board you’re using and select the COM port your board is connected to. Finally, click on the link Install or update MicroPython.

4) Then, select the port once again, the board you’re using, and the variant. It will automatically pick up the most recent MicroPython firmware version—see the screenshot below. Finally, you can click Install.

After a few seconds, the installation should be completed. If you’re using an ESP32, you may need to press the BOOT button for a few seconds after clicking the Install button.

5) When the installation is completed, you can close the window. You should get the following message on the Shell (see the picture below), and at the bottom right corner, it should have the Interpreter it’s using and the COM port.

Troubleshooting:
If it doesn’t recognize the device, and you have a message saying “no backend” in the bottom-right corner, it may be the case that it is not detecting the COM port automatically. If that’s the case, go to Tools > Options > Interpreter and select the COM port manually. After that, it should recognize the MicroPython device, and you should get the previous message.

The REPL

You should also see the >>> symbol (if you don’t, click on the Stop icon at the top).

This symbol represents the MicroPython REPL (Read-Eval-Print-Loop) prompt. This symbol means you’re interacting with MicroPython (the board with MicroPython firmware installed) in interactive mode in real time. This simply means that you can enter and execute commands directly. Let’s test it in the next section

Testing the Installation

Important: before testing the installation, your ESP32/ESP8266 board needs to be flashed with MicroPython firmware (see the previous step).

Type help() in the Shell after the prompt >>> and see if your device responds.

It should print some useful information about programming your board using MicroPython.
You can test other commands. For, example type the following:

>> print('Hello')

It should print Hello on the Shell right after you enter the command.

You can also run the following commands successively on the Shell after the prompt (>>>) one at a time to turn on the ESP32/ESP8266 built-in LED.

>>> from machine import Pin

>>> led = Pin(2, Pin.OUT)

If you’re using an ESP32, turn the onboard LED as follows:

>>> led.value(1)

If you’re using an ESP8266, the built-in LED works with inverted logic. So, you turn it on as follows:

>>> led.value(0)

The on-board LED should light up.

Now, you can turn off the built-in LED. On the ESP32, run the following command:

>>> led.value(0)

And like this for the ESP8266:

>>> led.value(1)

If everything is working as expected, it means you have successfully installed Thonny IDE, as well as MicroPython firmware on your ESP32 or ESP8266 boards.

Thonny IDE Overview

At this point, you should have:

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

Open Thonny IDE. There are two different sections: the Editor and the MicroPython Shell/Terminal:

• The Editor section is where you write your code and edit your .py files. You can open more than one file, and the Editor will open a new tab for each file.
• In the MicroPython Shell, you can type commands to be executed immediately by your ESP board without the need to upload new files. The terminal also provides information about the state of an executing program, shows errors related to the uploading process, syntax errors, prints messages, etc…

You can also customize Thonny IDE to show other useful tabs. Go to View, and you can select several tabs that provide more information.

Something that could be very useful is the Variables tab. It lists all available variables in your program and their corresponding values.

Running Your First Script – Blinking an LED

To get you familiar with the process of writing a file and executing code on your ESP32/ESP8266 boards, we’ll upload a new script that simply blinks the on-board LED of your ESP32 or ESP8266.

When you open Thonny IDE for the first time, the Editor shows an untitled file. Copy the following script to that file:

from machine import Pin
from time import sleep
led = Pin(2, Pin.OUT)
while True:
  led.value(not led.value())
  sleep(0.5)

Running the Script

To run that script on your board, simply click on the Run icon in Thonny IDE.

The on-board LED will start blinking.

To stop the execution of the program, you can hit the STOP button or simply press CTRL+C.

Running your Code Automatically

Just running the file with Thonny doesn’t copy it permanently to the ESP32 or ESP8266 filesystem. This means that if you unplug it from your computer and apply power to the board, nothing will happen because it doesn’t have any MicroPython file saved on its filesystem.

The Thonny IDE Run function is useful to test the code, but if you want to upload it permanently to your board, you need to create and save a file to the board’s filesystem. Let’s see how to do that.

Uploading Code to the ESP32/ESP8266 Boards

Stop the execution of the previous program by clicking on the Stop button if you haven’t already.

1) With the code copied to the file, click on the Save icon or go to File > Save as…

2) Then, select MicroPython device.

3) Name the file main.py, otherwise, it will not run automatically on the ESP32 or ESP8266.

Notice that the window that pops up shows the files currently saved on the board’s filesystem. There should be a file called boot.py. That file is created by default when you burn MicroPython firmware.

4) Finally, click Ok to proceed.

Important: when you name a file main.py, the ESP will run that file automatically on boot (when it starts). If you call it a different name, it will still be saved on the board filesystem, but it will not run automatically on boot.

5) Now, press the on-board RST/EN button so that the board restarts and starts running the code.

6) Now, your board should be blinking the blue on-board LED every 500 milliseconds.

The following figure shows the ESP32 on-board LED light up.

And the following figure shows the ESP8266.

After saving the file, you can remove and apply power again to the board, or you can even power it using a different power supply that is not your computer.

Notice that the board will automatically start blinking the LED when you apply power to it. This means the main.py file was successfully uploaded to the board and that it is running that file automatically.

Congratulations! You’ve just written and uploaded your first MicroPython script to your ESP32/ESP8266 board

Troubleshooting Tips for Thonny IDE

We’ve discovered some common problems and error messages that occur with Thonny IDE. Usually restarting your ESP with the on-board EN/RST button fixes your problem. Or press the Thonny IDE “Stop/Restart backend” button and repeat your desired action. In case it doesn’t work for you, read these next common errors and discover how to solve them.

Error #1: You get one of the following messages:

========================= RESTART =========================
Unable to connect to COM4
Error: could not open port 'COM4': FileNotFoundError(2, 'The system cannot find the file specified.', None, 2)

Check the configuration, select Run → Stop/Restart or press Ctrl+F2 to try again. (On some occasions it helps to wait before trying again.)

Or:

========================= RESTART =========================
Could not connect to REPL.
Make sure your device has suitable firmware and is not in bootloader mode!
Disconnecting.

Or:

========================= RESTART =========================
Lost connection to the device (EOF).

Unplug and plug back your ESP board. Then, double-check that you’ve selected the right serial port in the Tools > Options > Interpreter > Port. Then, click the “Stop/Restart backend” button to establish a serial communication. You should now be able to upload a new script or re-run new code.

These errors might also mean that you have your serial port being used by another program (like a serial terminal or in the Arduino IDE). Double-check that you’ve closed all the programs that might be establishing a serial communication with your ESP board. Then, unplug and plug back your ESP board. Finally, restart Thonny IDE.

Error #2: Thonny IDE fails to respond or gives an Internal Error:

When this happens, you can usually close that window, and it will continue to work. If it keeps crashing, we recommend restarting the Thonny IDE software.

Error #3: Thonny IDE hangs when pressing “Stop/Restart backend” button:

When you press the “Stop/Restart backend” button, you need to wait a few seconds. The ESP needs time to restart and establish the serial communication with Thonny IDE. If you press the “Stop” button multiple times or if you press the button very quickly, the ESP will not have enough time to restart properly, and it’s very likely to crash Thonny IDE.

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

Brownout detector was triggered

Or if the ESP keeps restarting and printing the ESP boot information:

ets Jun 8 2016 00:22:57 

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) 
configsip: 0, SPIWP:0xee 
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 
mode:DIO, clock div:2 
load:0x3fff0018,len:4 
load:0x3fff001c,len:4732 
load:0x40078000,len:7496 
load:0x40080400,len:5512

The “Brownout detector was triggered” error message or constant reboots means that there’s some sort of hardware problem. It’s often related to one of the following issues:

• Poor quality USB cable;
• USB cable is too long;
• Board with some defect (bad solder joints);
• Bad computer USB port;
• Or not enough power provided by the computer USB port.

Solution: try a different shorter USB cable (with data wires), try a different computer USB port or use a USB hub with an external power supply.

Important: if you keep having constant problems or weird error messages, we recommend re-flashing your ESP board with the latest version of MicroPython firmware.

Error #5: When I try to establish a serial communication with the ESP32/ESP8266 in Thonny IDE, I can’t get it to connect.

We think this is what’s happening: when you’re running a script on your board, sometimes it’s busy running that script and performing the tasks.

So, you need to try starting the connection by pressing “Stop/Restart backend” button multiple times or restarting the ESP to make it available to establish the serial communication.

Warning: don’t press the “Stop/Restart backend” button multiple times very quickly. After pressing that button, you need to be patient and wait a few seconds for the command to run.

If you’re running a script that uses Wi-Fi, deep sleep, or it’s doing multiple tasks, I recommend trying 3 or 4 times to establish the communication. If you can’t, I recommend re-flash the ESP with MicroPython firmware.

Error #6: debug tools are grayed out:

Thonny IDE debug tools aren’t available for MicroPython. The debug tools are only available for the Python Interpreter, so being grayed out is the expected behavior.

Wrapping Up

Thonny IDE is a great IDE to program the ESP32 and ESP8266 boards using MicroPython. It is compatible with Windows, Mac OS X, and Linux, and it is easy to install.

We have an article with a compilation of several MicroPython IDEs compatible with the ESP32 and ESP8266 boards that you can check below:

• MicroPython IDEs for ESP32 and ESP8266

More tutorials about MicroPython with ESP32 and ESP8266:

• MicroPython Programming Basics with ESP32 and ESP8266
• MicroPython with ESP32 and ESP8266: Interacting with GPIOs
• ESP32/ESP8266 MicroPython Web Server

Learn more about MicroPython with our eBook:

• MicroPython Programming with ESP32 and ESP8266 eBook

Thanks for reading.