Skip to main content

Section 1 Set Up Development Environment

This tutorial will introduce MicroPython and guide you through configuring the MicroPython development environment for ESP32.

Important: About board compatibility

The core logic of this tutorial applies to all ESP32 boards, but all the operation steps are explained using the example of the Waveshare ESP32-S3-Zero mini development board. If you are using a development board of another model, please modify the corresponding settings according to the actual situation.

1. What is MicroPython?​

MicroPython is a lean and efficient implementation of the Python 3 programming language, specifically optimized to run on microcontrollers and other resource-constrained environments.

MicroPython supports various microcontroller platforms. It can run on devices with as little as 256KB of flash memory and 16KB of RAM. However, you will get the most complete and smoothest experience on hardware like ESP32, which has more than 512KB of flash and 128KB of RAM.

In simple terms, MicroPython is a "miniature version" of Python that runs on microcontrollers. It allows developers to control hardware using Python syntax, lowering the barrier to entry for embedded development.

1.1 How It Works​

MicroPython's operation primarily relies on firmware (Firmware) flashed into the device.

  1. Interactive Interpreter (REPL): When the MicroPython firmware starts, it runs a miniature Python interpreter and enters a standby state. At this point, via a serial connection, the user can access the REPL (Read-Eval-Print Loop) environment. Python commands sent in this environment are executed immediately, and results are returned. This immediate feedback mechanism significantly improves debugging efficiency.
  2. File Execution Mechanism: In addition to interactive input, MicroPython also supports running code saved in the file system. When the device boots, it will sequentially try to run boot.py (the system boot script) and main.py (the user's main program). Saving code as main.py enables the program to run automatically on device power-up.

MicroPython Architecture

1.2 Differences from Standard Python​

  • Independent Implementation: MicroPython is not a modified version of standard Python (CPython) source code. It is written from scratch for embedded environments. It strictly adheres to Python 3 syntax, but its internal implementation differs.
  • Feature Subset: Due to the very limited memory (RAM) and flash memory (Flash) on microcontrollers, MicroPython includes only a subset of standard Python's core libraries. Some large or inapplicable libraries (like the full versions of numpy or requests) are removed or replaced with more streamlined modules.
  • Hardware Support: MicroPython's biggest feature is the addition of modules for hardware control, such as the machine module (for GPIO, I2C, SPI, etc.) and the network module (for Wi-Fi, Bluetooth).
  • Cross-Platform: Besides ESP32, MicroPython supports many other development boards, such as the STM32 series, ESP8266, Raspberry Pi Pico (RP2040), and more.

1.3 Comparison with Other ESP32 Development Methods​

FeatureMicroPythonArduinoESP-IDF
Learning DifficultyLowMediumHigh
Development EfficiencyHighMediumLow
PerformanceMediumHighHighest
Memory FootprintRelatively HighMediumControllable

2. Setting up the Development Environment​

Thonny is a beginner-friendly Python Integrated Development Environment (IDE). It has built-in, comprehensive support for MicroPython, allowing you to easily perform all operations such as firmware flashing, file management, and code debugging.

note

The following content in this tutorial will be demonstrated using the Thonny IDE.

2.1 Installing Thonny​

Go to the Thonny website to download and install Thonny.

DownloadArduinoIDE

2.2 Flashing MicroPython Firmware​

MicroPython needs to run on its specific firmware, so you must flash the corresponding firmware before first use. Here are two methods to flash the firmware.

note

This method is simple to operate and suitable for most scenarios. Thonny will automatically download the firmware.

  1. Connect the development board: Connect the ESP32 development board to your computer using a USB cable.

    info

    If you encounter connection timeouts or flashing failures in subsequent steps, try manually entering download mode: Hold down the BOOT button on the board, then plug in the USB cable, and finally release the BOOT button.

  2. Configure the interpreter: Open Thonny, click the interpreter status box in the bottom right corner (initially it may show 'Local Python'), then select Configure interpreter.

    Install Firmware via Thonny Step 1

  3. Open the firmware flashing tool: In the pop-up window, select the MicroPython(ESP32) interpreter and the corresponding port for your development board. Then, click the Install or update MicroPython(esptool) link in the bottom right.

    Install Firmware via Thonny Step 2

  4. Select firmware: Configure the following parameters in the Install MicroPython(esptool) window:

    info

    If the interface options are greyed out, wait for Thonny to update the firmware list via the internet. If the firmware list cannot be refreshed, please use the Via Thonny (Custom Firmware) installation method.

    Install Firmware via Thonny Step 3
    • Target port: Select the port corresponding to your ESP32 device (if unsure, unplug and replug the device to see which port disappears and reappears).
    • MicroPython family: Choose the chip model according to your actual hardware.
    • variant: Choose the generic Espressif xxx.
    • version: It is recommended to select the latest stable version.

  5. Start flashing: Click Install. Thonny will automatically erase the flash memory and flash the new MicroPython firmware. Wait for the progress bar to complete until you see the Done! prompt.

    Install Firmware via Thonny Step 4

2.3 Verifying the Development Environment​

After flashing, the next step is to verify if the environment configuration is successful.

  1. Reconnect the device: Disconnect the ESP32 from your computer, then reconnect it. Ensure the interpreter in the bottom right corner of Thonny is set to MicroPython (ESP32) and the correct port.

    Port Changes

    After flashing the MicroPython firmware, the corresponding COM port number for the device might change (especially when using native USB interfaces like those on ESP32-S3/C3). If the connection fails, click the bottom right corner to reselect the correct port.

  2. Restart the interpreter: If the Shell window at the bottom is unresponsive, you can click the red Stop button on the toolbar to restart the onboard interpreter.

  3. Check the prompt: Upon successful connection, the Shell window should display the MicroPython version information, development board info, and the >>> prompt. This indicates you have successfully entered the MicroPython REPL environment on the ESP32.

  4. Run test code: At the >>> prompt, enter your first line of MicroPython code and press Enter:

    print('Hello, ESP32!')

    You should immediately see the ESP32 return the message Hello, ESP32!.

At this point, the ESP32 MicroPython development environment has been successfully set up, and you have run your first line of code.