ESP32 MicroPython-T
ESP32 MicroPython-T is a Visual Studio Code extension for managing ESP32 and ESP8266 boards running MicroPython. It combines serial-port detection, firmware installation, upload and run commands, file backup, board information, monitoring, stoppable operations, settings, and automatic port cleanup in one ESP sidebar.
What is new in v1.1.0
- Added a Stop button directly inside the message shown while an ESP action is running.
- Added the
ESP: Stop Running Command Palette command.
- Tracks the currently running
mpremote or esptool child process so it can be terminated immediately.
- On Windows, stops the full process tree using
taskkill /T /F.
- Ends extension-owned tasks, closes VS Code terminals, removes stale
mpremote and esptool processes, and frees the selected COM port.
- Shows animated stopping feedback while cleanup is in progress.
- Gradually hides the action message when an operation completes.
- Preserves the serialized-action, backup, firmware, board-detection, and fast disconnect-recovery features from earlier releases.
Supported boards
The built-in online firmware installer includes:
- ESP32 Generic
- ESP32-S2 Generic
- ESP32-S3 Generic
- ESP32-C3 Generic
- ESP8266 Generic
The embedded online firmware links point to MicroPython v1.23.0 images dated 2024-06-02. A compatible local .bin firmware image can also be selected.
Main features
- Detect serial devices using
mpremote devs.
- Validate MicroPython through
mpremote, with esptool chip detection as a fallback.
- Unlock all board tools when MicroPython responds.
- Enable install-only mode when an ESP chip is detected without a responsive MicroPython runtime.
- Download and install online firmware or flash a local
.bin image.
- Upload the active Python file permanently, normally as
main.py.
- Run the active Python file temporarily with
mpremote run.
- Stop a running monitor or board operation and free the COM port.
- Reset the board and list files in its root filesystem.
- Recursively back up board files to the active workspace.
- Delete the configured permanent file after confirmation and reset the board.
- Stream MicroPython monitor output to the extension output channel.
- Read board, system, MicroPython, CPU-frequency, unique-ID, and MAC information.
- Open dedicated Board Info and Settings windows.
- Prevent overlapping ESP actions.
- Close terminals and release stale serial processes before board operations.
- Detect USB disconnection, clear the selected port, and lock tools automatically.
- Check for
mpremote, esptool, and pyserial at startup and offer to install missing packages.
Requirements
- Visual Studio Code 1.75.0 or later
- Python 3 available through the configured Python command
- A supported ESP32 or ESP8266 board
- A data-capable USB cable
- The correct USB-to-serial driver
Install the required Python packages:
python -m pip install --upgrade mpremote esptool pyserial
When Python is started with python3 or py, change esp32.pythonCommand in the extension settings.
Install from VSIX
- Download
esp32-micropython-t-1.1.0.vsix.
- Open Visual Studio Code.
- Open the Extensions view.
- Select the
... menu.
- Select Install from VSIX....
- Choose the downloaded file.
- Reload Visual Studio Code when requested.
First-use workflow
- Connect the board through USB.
- Open the ESP activity-bar view.
- Refresh the available ports.
- Select the correct port.
- Wait for board validation.
- When MicroPython responds, all tools become available.
- When only an ESP chip is detected, firmware installation remains available in install-only mode.
Commands
| Command |
Purpose |
ESP: Check Ports |
Lists detected serial ports. |
ESP: Select Port |
Selects and validates a serial device. |
ESP: Install MicroPython |
Erases flash and installs online or local firmware. |
ESP: Upload Permanent |
Copies the active saved .py file to the configured permanent filename. |
ESP: Run Temporary |
Runs the active saved .py file without permanent copying. |
ESP: Reset |
Executes machine.reset() on the selected board. |
ESP: List Files |
Lists files in the board root directory. |
ESP: Backup Files |
Recursively downloads board files into a timestamped workspace backup. |
ESP: Stop Permanent |
Deletes the configured permanent file after confirmation and resets the board. |
ESP: Monitor |
Starts MicroPython monitor output. |
ESP: Stop Running |
Force-stops the tracked ESP process and frees the serial port. |
ESP: Close ESP Terminals |
Closes terminals and releases ESP serial processes. |
ESP: Open Board Info Window |
Opens detailed board information. |
ESP: Open Settings Window |
Opens the extension settings window. |
Keyboard shortcuts
| Shortcut |
Command |
Ctrl+Alt+P |
Select port |
Ctrl+Alt+I |
Install MicroPython |
Ctrl+Alt+U |
Upload permanent |
Ctrl+Alt+R |
Run temporary |
Ctrl+Alt+E |
Reset board |
Ctrl+Alt+M |
Start monitor |
Ctrl+Alt+S |
Close terminals and free the port |
The Stop Running and Backup Files commands are available from the sidebar and Command Palette. Custom shortcuts can be assigned from Visual Studio Code's Keyboard Shortcuts page.
Extension settings
| Setting |
Default |
Description |
esp32.pythonCommand |
python |
Python executable used for mpremote, esptool, dependency installation, and pyserial checks. |
esp32.port |
auto |
Selected serial port. A disconnected port is cleared automatically. |
esp32.permanentFileName |
main.py |
Destination used by permanent upload and permanent-code removal. |
esp32.autoResetAfterUpload |
true |
Resets the board after permanent upload. |
esp32.chip |
esp32 |
Firmware target: esp32, esp32s2, esp32s3, esp32c3, or esp8266. |
esp32.flashBaud |
460800 |
Baud rate used when writing firmware. |
Stop a running ESP action
While an operation is active, the sidebar displays a running-action overlay with a Stop button. Selecting it:
- marks the current operation as cancelled;
- terminates the tracked child process or process tree;
- terminates tasks started by the extension;
- closes open VS Code terminals;
- on Windows, terminates stale Python processes whose command line contains
mpremote or esptool;
- waits briefly for serial cleanup;
- removes the busy/stopping state and returns the extension to ready status.
This is intended for a stuck monitor, temporary run, backup, firmware operation, or another command holding the COM port. Because terminal cleanup closes every VS Code terminal, save terminal work before using it.
Backup ESP files
An open workspace folder is required. Backups are stored under:
<workspace>/esp-backups/backup-<port>-<YYYYMMDD-HHMMSS>/
The extension recursively discovers board directories, copies each file through mpremote fs cp, writes backup-manifest.json, restores the selected-port state, and offers to open the completed folder. Failed items are recorded in the manifest.
Serial-port preparation
Before a board action starts, the extension blocks overlapping operations, displays a busy state, terminates its tracked tasks, closes open VS Code terminals, kills stale mpremote or esptool processes on Windows, waits for the serial port to be released, and then starts the requested command.
Firmware installation
Firmware installation erases the board before writing the selected image. Existing programs and filesystem data are removed, so use Backup ESP Files first when MicroPython is still responsive.
Online firmware is downloaded into .esp-micropython-firmware in the active workspace, or into extension storage when no workspace is open. Offline installation accepts a compatible .bin file. Erase and write steps run sequentially and their exit codes are checked.
Connection and disconnection handling
The selected port is checked through pyserial every 250 ms. When it remains absent for approximately 0.5 seconds, the extension closes terminals, clears the selected port, changes esp32.port to auto, clears board information, locks board tools, and refreshes the port list.
Troubleshooting
Required Python package is missing
python -m pip install --upgrade mpremote esptool pyserial
Use the same Python executable configured in esp32.pythonCommand.
Port is busy
Close Thonny, Arduino IDE, PuTTY, and other serial programs. Use Stop ESP Running when an extension operation is stuck. The extension also performs serial cleanup before actions.
Wait briefly after stopping. Some USB drivers need a moment to release the handle. Reconnect the cable when another external program still owns the port.
Port appears but tools remain locked
Check the USB cable, driver, power, selected port, and board mode. When esptool detects the chip but MicroPython does not respond, install-only mode should enable firmware installation.
Upload or run is rejected
The active editor must contain a saved .py file.
Monitor output is streamed to the extension output channel. The output channel does not provide terminal-style standard input, so use another serial terminal for interactive REPL input.
Implementation notes
- Built-in firmware URLs are fixed in
extension.js; they do not automatically follow the newest MicroPython release.
Stop Running terminates the extension's tracked host process and cleans the serial port; it is not a general remote debugger for arbitrary detached firmware execution.Stop Permanent deletes the configured permanent file; it is different from Stop Running.- Pre-action and stop cleanup close every VS Code terminal, including terminals not created by this extension.
- Stale Python-process termination is Windows-specific.
- Flashing firmware erases board data.
- Backup files are stored in the workspace and are excluded from the rebuilt release VSIX.
Extension identity
- Publisher:
Mech-EAD
- Extension name:
esp32-micropython-t
- Display name:
ESP32 MicroPython-T
- Version:
1.1.0
- Visual Studio Code engine:
^1.75.0
- License: MIT
License
Released under the MIT License. See license or LICENSE.txt for the complete terms.
