
Security News
pnpm 10.12 Introduces Global Virtual Store and Expanded Version Catalogs
pnpm 10.12.1 introduces a global virtual store for faster installs and new options for managing dependencies with version catalogs.
All-in-one utility for flashing and managing MicroPython deployments on ESP32-C3 SuperMini boards.
esp32_micropython
is an all-in-one command-line utility designed to simplify flashing MicroPython firmware and managing file deployments on ESP32-C3 SuperMini boards (and compatible variants) that feature a built-in USB-C connector for direct serial communication.
It leverages esptool
for flashing firmware and mpremote
for file system operations and REPL interaction.
Before you begin, it's crucial to correctly identify your ESP32-C3 board and ensure it can be stably connected to your computer.
ESP32-C3 FH4...
or similar. The general pattern is ESP32-C3 XX Y ZZZZZZ T U? VVVVVVV WWWWWWWWWW
where XX
indicates flash/temperature, Y
is flash size, ZZZZZZ
is a date/lot code, etc.BOOT
(often IO0) and RST
(Reset).For a detailed guide on board identification, pinouts, and establishing a stable USB connection (especially the BOOT button procedure for flashing), please refer to the guide: docs_md/identify_board.md
.
You can install the esp32_micropython
utility and its dependencies (esptool
, mpremote
, pyserial
) using pip:
pip install esp32_micropython
(If installing from local source, you'd typically use pip install .
or python setup.py install
from the project root.)
Ensure that Python and pip are correctly installed and configured in your system's PATH.
The utility is invoked from your terminal or PowerShell:
esp32 [global_options] <command> [<args>...]
Global Options:
--port <PORT_NAME>
or -p <PORT_NAME>
: Temporarily overrides the configured COM port for the current command. For example, esp32 --port COM7 flash
.Before most operations, you need to tell the tool which serial port your ESP32-C3 is connected to.
esp32 devices
Lists all available serial (COM) ports detected on your system. The currently selected/configured port will be marked with an asterisk (*
).
esp32 devices
esp32 device [PORT_NAME] [--force]
Sets or tests the COM port.
esp32 device COM5
: Sets COM5
as the active port for subsequent commands and saves it to .esp32_deploy_config.json
. It will test the port first.esp32 device
: If a port is already configured, it tests the connection to the configured port. If no port is configured, it lists available ports.esp32 device COM5 --force
: Sets COM5
even if the initial connection test fails.Tip for already flashed devices: If your device is already flashed with MicroPython and running, it should respond to the test. If mpremote
can't connect, ensure the device isn't in a tight loop or stuck. For a new or problematic device, you might need to set the port with --force
before flashing.
This command erases the ESP32-C3's flash and installs MicroPython firmware.
esp32 flash [firmware_source] [--baud BAUD_RATE]
firmware_source
(optional):
micropython.org
..bin
file..bin
firmware file.--baud BAUD_RATE
(optional): Sets the baud rate for flashing (default: 460800
).Shorthand Usage:
# Ensure device port is set first (e.g., esp32 device COM5)
esp32 flash
This will use the default firmware URL.
Important:
BOOT
(or IO0) button.BOOT
, plug in the USB-C cable.BOOT
button.esp32 upload <local_source> [remote_destination]
Uploads files or directories from your computer to the ESP32's filesystem.
Understanding local_source
and trailing slashes for directories:
local_source
is a file: It's always uploaded as that single file.local_source
is a directory and ends with a /
(or \
on Windows, e.g., my_dir/
): The contents of my_dir
are uploaded.local_source
is a directory and does not end with a /
(e.g., my_dir
): The directory my_dir
itself (including its contents) is uploaded.Understanding remote_destination
:
/
) of the ESP32's filesystem.Scenarios & Examples:
esp32 upload main.py
# Result on ESP32: /main.py
esp32 upload utils.py lib
# Result on ESP32: /lib/utils.py (lib/ will be created if needed)
# Assuming local_project/ contains file1.py and subdir/file2.py
esp32 upload local_project/
# Result on ESP32: /file1.py, /subdir/file2.py
esp32 upload local_project/ remote_app
# Result on ESP32: /remote_app/file1.py, /remote_app/subdir/file2.py
esp32 upload my_library
# Result on ESP32: /my_library/... (contains contents of local my_library)
esp32 upload my_library existing_remote_lib_folder
# Result on ESP32: /existing_remote_lib_folder/my_library/...
esp32 upload_all_cwd
A basic command that attempts to upload all eligible files and directories from your current working directory (CWD) on your computer to the root of the ESP32. It excludes common non-project files like .git
, __pycache__
, etc.
# From your project's directory
esp32 upload_all_cwd
esp32 download <remote_source_path> [local_target_path]
Downloads files or directories from the ESP32 to your computer. This command behaves similarly to upload
but in reverse.
Understanding remote_source_path
and trailing slashes for directories:
remote_source_path
points to a file on the ESP32 (e.g., /data/log.txt
): The file is downloaded.remote_source_path
points to a directory on the ESP32 and ends with a /
(e.g., /logs/
): The contents of that remote directory are downloaded into the specified local_target_path
.
//
(e.g., esp32 download // local_root_backup
).remote_source_path
points to a directory on the ESP32 and does not end with a /
(e.g., /config
): The directory config
itself (including its contents) is downloaded and created within the local_target_path
.Understanding local_target_path
:
.
) on your computer.Scenarios & Examples:
esp32 download /boot.py
# Result: ./boot.py locally
esp32 download /lib/utils.py my_local_lib
# Result: ./my_local_lib/utils.py locally (my_local_lib/ created if needed)
cp :remote_file local_file_path
)
esp32 download /data/sensor.dat backup/latest_sensor.dat
# Result: ./backup/latest_sensor.dat locally
logs
) and its contents into the current local directory:
esp32 download /logs
# Result: ./logs/... locally (creates a 'logs' folder in CWD)
data
) and its contents into a specified local directory (backup_data
):
esp32 download /data backup_data
# Result: ./backup_data/data/... locally
/app/
) into the current local directory:
esp32 download /app/ .
# Result: Files and subdirectories from /app/ on device are copied into ./ locally
# Example: if /app/main.py and /app/gfx/img.png exist,
# they become ./main.py and ./gfx/img.png
/lib/
) into a specified local directory (local_libs_backup
):
esp32 download /lib/ local_libs_backup
# Result: Contents of /lib/ on device are copied into ./local_libs_backup/ locally
# Example: if /lib/tool.py exists, it becomes ./local_libs_backup/tool.py
full_backup
:
esp32 download // full_backup
# Result: All files and folders from device root copied into ./full_backup/
esp32 list [remote_directory]
or esp32 ls [remote_directory]
Lists files and directories on the ESP32. The listing is recursive from the given path.
remote_directory
(optional): The directory to list (e.g., /lib
). Defaults to the root (/
), listing top-level items.Shorthand Usage:
esp32 list
esp32 list lib
esp32 tree [remote_directory]
Displays a tree-like view of files and subdirectories within the specified remote directory.
remote_directory
(optional): Defaults to root (/
).Shorthand Usage:
esp32 tree
esp32 tree lib
esp32 delete [remote_path_to_delete]
Deletes a file or directory (recursively) on the ESP32.
remote_path_to_delete
(optional): The file or directory to delete (e.g., old_main.py
, temp_files/
)./
, the command will prompt for confirmation to delete all contents of the root directory. Use with extreme caution!Shorthand Usage:
esp32 delete old_script.py
esp32 delete my_module/
esp32 delete # Prompts to wipe root
esp32 delete / # Also prompts to wipe root
esp32 run [script_name]
Executes a MicroPython script that exists on the ESP32's filesystem.
script_name
(optional): The path to the script on the device (e.g., app.py
, tests/run_tests.py
). Defaults to main.py
. Path is relative to the device root.
The script's output (and any errors) will be displayed in your terminal.Shorthand Usage:
esp32 run
# Executes /main.py on device
esp32 run services/scanner.py
# Executes /services/scanner.py on device
Connection Issues / Device Not Detected:
esp32 devices
, esp32 device <PORT>
).docs_md/identify_board.md
.esptool
or mpremote
command not found:
esptool
and mpremote
are installed: pip install esptool mpremote pyserial
.Firmware Flashed, but Device Unresponsive or test_device
Fails:
.bin
file for ESP32-C3 from micropython.org/download/esp32c3/ that matches your board's specifications (e.g., flash size, specific features if known).flash
command with the path to your downloaded file:
esp32 flash path/to/your_downloaded_firmware.bin
Upload/Download/List commands fail with "No response or mpremote error":
esp32 device
to test basic connectivity.This utility aims to streamline your ESP32-C3 MicroPython development workflow. Happy coding!
FAQs
All-in-one utility for flashing and managing MicroPython deployments on ESP32-C3 SuperMini boards.
We found that esp32-micropython demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 10.12.1 introduces a global virtual store for faster installs and new options for managing dependencies with version catalogs.
Security News
Amaro 1.0 lays the groundwork for stable TypeScript support in Node.js, bringing official .ts loading closer to reality.
Research
A deceptive PyPI package posing as an Instagram growth tool collects user credentials and sends them to third-party bot services.