Skip to content

Environment Setup

Setting Up the Development Environment

Before you start building projects, you need to make some preparations first. This is very important and you cannot skip it.

1. Install Thonny (Important)

Thonny is a free, open-source software platform with a small footprint, a simple interface, easy operation, and rich features. It is a Python IDE suitable for beginners. In this tutorial, we use this IDE to develop the ESP32 throughout the whole process. Thonny supports multiple operating systems, including Windows, Mac OS, and Linux.

1. Download the Thonny software:

It is recommended to click the link below to download and install directly according to your system.

Operating System Download Link / Method
Windows: Click to download the Windows installer package
MAC OS: Click to download the Mac installer package
Linux: Latest version: (as follows)
Binary bundle for PC (Thonny+Python): 
bash <(wget -O - https://thonny.org/installer-for-linux) 
With pip:
pip3 install thonny
Distro packages (may not be the latest version):
Debian, Rasbian, Ubuntu, Mint and others:
sudo apt install thonny
Fedora:
sudo dnf install thonny
Thonny's open-source code repository: https://github.com/thonny/thonny/releases/

2. Install the Thonny software on Windows:

A. The downloaded Thonny icon is as follows.

B. Double-click "thonny-4.0.2.exe", and the following dialog box will appear. Here I choose "" to proceed. You can also choose "" to proceed.

C. If you are not familiar with installing computer software, you can keep clicking "Next" until the installation is complete.

D. If you need to change the installation path of the Thonny software, you can click "Browse..." to modify it. After selecting the installation path, click "OK".

If you do not want to change the installation path, just click "Next"; then continue clicking "Next".

E. Check "Create desktop icon", and the Thonny software will generate a shortcut on your desktop so that you can open the Thonny software more conveniently later.

F. Click "Install" to install the software.

G. During the installation process, you just need to wait for the installation to complete. Never click "Cancel", otherwise the installation will not succeed.

H. Once you see the following interface, it means the Thonny software has been successfully installed. Click "Finish" and you are done.

I. If you checked "Create desktop icon" during the installation process, you can see the following icon on the desktop.

2. Basic Configuration of the Thonny Software

A. Double-click the desktop icon of the Thonny software, and you can see the following interface. At the same time, you can also select the language (select Simplified Chinese here) and initial settings. After finishing the settings, click "Let's go!".

B. Select "View" → "Files" and "Shell".

3. Install the CP2102 Driver

The ESP32 downloads code through the CP2102 driver. Therefore, before using it, we need to install the CP2102 driver on the computer.

Windows System

Check whether the CP2102 driver has already been installed.

  1. Connect the computer and the ESP32 with a USB cable.

  1. Go to the computer main interface, select "This PC", right-click and select "Manage".

  1. Click "Device Manager". If your computer already has the CP2102 driver installed, you can see "Silicon Labs CP210x USB to UART Bridge(COMx)".

Install the CP2102 Driver

  1. If the CP2102 driver is not installed, the interface will be displayed as follows.

  1. Click "CP2102 USB to UART Bridge Controller", right-click and select "Update Driver Software(P)".

  1. Click "Browse my computer for driver software(R)".

  1. Click "Browse(R)..." and select CP210x_6.7.4 (driver path: ..\additional-resources\CP2102-driver\CP2102-driver-Windows), then click "Next".

  1. Wait for the CP2102 driver installation to complete. When the interface shows the following, it means the CP2102 driver has been installed. You can close this interface.

  1. When the ESP32 is connected to the computer, the interface shows the following.

MAC System


For how to install the CP2102 driver, please refer to the "Arduino C Tutorial Windows System" tutorial in the "Development Environment Setup" section.

4. Flash the MicroPython Firmware (Important)

To run a Python program on the ESP32 board, we first need to flash the firmware onto the ESP32 board.

This firmware is provided in our folder. Left navigation: Resources Download - Other Important Resources.

Flash the MicroPython Firmware

Connect the computer and the ESP32 board with a USB cable.

Make sure the driver has been installed successfully and can correctly identify the COM port. Open the Device Manager and expand "Ports (COM & LPT)".

Note: The COM port may be different on different computers, which is normal.



  1. Open Thonny, click "Run", and select "Configure Interpreter".

  1. Select "MicroPython (ESP32)", select "Silicon Labs CP210x USB to UART Bridge(COM7)", then click "Install or Update MicroPython".

  1. The following dialog box pops up. Please install it as shown in the figure below. Note: If the firmware installation fails, click "Install" again, then press and hold the Boot button on the ESP32 board , and release the Boot button when the upload progress percentage appears.)

  1. Wait for the installation to complete. After the installation is complete, click "Close" first and then "OK".

  1. Close all dialog boxes, go back to the main interface, and click "". As shown in the figure below:

  1. So far, all preparations are ready.

5. Test Code

Test Shell Commands

Enter "print('hello world')" in the "Shell" window and press Enter. If the environment is normal, "hello world" will be printed on the next line.

Online Running

When the ESP32 needs to be connected to a computer, it runs online. Users can use Thonny to write and debug programs.

  1. Open Thonny and click "Open".

  1. In the newly popped-up window, click "This PC".

In the new dialog box, select "Project_01_HelloWorld.py" in the path: "..\program-code\python-code\project-01-Hello World".

Click , and "Hello World" will be printed in the "Shell" window.

Note: When running online, if you press the reset button on the ESP32, the user's code will not run again.

6. Common Operations in Thonny

The code used in this tutorial is saved at (i.e. the path): "..\program-code\python-code".

You can move the code anywhere. For example, we saved the code in Drive D, with the path D:\2. Project Tutorials.

Upload Code to the ESP32

For convenience, we use "Project 16 OLED Display" as an example. In the "Project 16 OLED Display" folder, select "lcd128_32.py", right-click the mouse, and select "Upload to /" to upload the code to the root directory of the ESP32.

Download Code to the Computer

In "MicroPython device", select "boot.py", right-click and select "Download to..." to download the code to your computer.

Delete Files from the ESP32 Root Directory

In "MicroPython device", select "lcd128_32.py", right-click it and select "Delete" to delete "lcd128_32.py" from the root directory of the ESP32.