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, 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 according to your system to download and install it directly.

Operating System Download Link / Method
Windows: Click to download the Windows installer
MAC OS: Click to download the Mac installer
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 Thonny software on Windows:

A. The downloaded Thonny icon looks like this.

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 create a shortcut on your desktop, making it convenient for you to open the Thonny software later.

F. Click "Install" to install the software.

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

H. Once you see the following interface, it means the Thonny software has been installed successfully. Just click "Finish".

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

2. Basic Configuration of Thonny Software

A. Double-click the Thonny desktop icon and you will see the following interface. You can also choose the language (select Simplified Chinese here) and perform initial settings. After setting, 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 is already installed

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

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

  1. Click "Device Manager". If the CP2102 driver is already installed on your computer, 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 display as follows.

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

  1. Click "Browse my computer for drivers(R)".

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

  1. Wait for the CP2102 driver installation to finish. When the interface displays as follows, it means the CP2102 driver has been installed. You can close this interface.

  1. When the ESP32 is connected to the computer, the interface displays as follows.

MAC System


For the method 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 Python programs on the ESP32 board, we first need to flash the firmware onto the ESP32 board.

We provide this firmware in our folder. Click to download: Python Materials.

Flash the MicroPython Firmware

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

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

Note: Different computers may have different COM ports, 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)", and then click "Install or update MicroPython".

  1. The following dialog box will pop up. Please install it as shown below. Note: If the firmware installation fails, click "Install" again, then hold down the Boot button on the ESP32 board, and release the Boot button only after the upload progress percentage appears.)

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

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

  1. So far, all the preparatory work is 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.

Run Online

When the ESP32 is connected to the 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 of the ESP32, the user's code will not be executed again.

6. Common Operations in Thonny

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

You can move the code anywhere. For example, we save the code in the D drive, with the path D:\2. 项目教程.

Upload Code to the ESP32

For convenience, we take "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 in 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.