soundshot/flash_tool

ESP32 Firmware Flasher GUI

A cross-platform GUI tool for flashing ESP32 firmware packages.

Features

• Simple, user-friendly graphical interface
• Cross-platform support (Windows, macOS, Linux)
• Automatic serial port detection
• Firmware package validation (.zip files)
• Real-time flashing progress output
• Configurable flash parameters

Building Executables

Universal Build (Recommended)

The easiest way to build for your current platform:

python build.py

This script will:

1. Detect your platform automatically
2. Install required dependencies
3. Build the appropriate executable

Platform-Specific Builds

macOS

./build_macos.sh

This creates an application bundle at dist/ESP32_Flasher.app

To run:

open dist/ESP32_Flasher.app

Windows

build_from_spec.bat

This creates an executable at dist\ESP32_Flasher.exe

Linux

python build.py

Creates an executable at dist/ESP32_Flasher

Running Without Building

You can run the GUI directly with Python:

python gui_flasher.py

Requirements

pip install -r requirements.txt

Firmware Package Format

The flasher expects a .zip file containing these files:

• bootloader.bin - ESP32 bootloader
• partition-table.bin - Partition table
• ota_data_initial.bin - OTA data
• soundshot.bin - Main application firmware

Usage

1. Launch the ESP32_Flasher application
2. Select your ESP32's serial port (or click Refresh)
3. Browse and select your firmware .zip package
4. (Optional) Adjust flash settings if needed
5. Click "Flash Firmware"
6. Wait for the process to complete

Flash Settings

Default settings work for most ESP32 boards:

• Chip: esp32
• Baud Rate: 460800 (faster) or 115200 (more reliable)
• Flash Mode: dio
• Flash Freq: 40m
• Flash Size: 2MB (adjust based on your board)

Troubleshooting

Port Not Detected

• Ensure ESP32 is connected via USB
• Install CH340/CP2102 drivers if needed (Windows/macOS)
• On Linux, add user to dialout group: sudo usermod -a -G dialout $USER

Flash Failed

• Try lower baud rate (115200)
• Press and hold BOOT button during flash
• Check USB cable quality
• Verify firmware package integrity

macOS: "App is damaged"

Run this command to allow the app:

xattr -cr dist/ESP32_Flasher.app

Development

Project Structure

flash_tool/
├── gui_flasher.py              # Main GUI application
├── ESP32_Flasher_macOS.spec    # PyInstaller spec for macOS
├── ESP32_Flasher_Windows.spec  # PyInstaller spec for Windows
├── build.py                    # Universal build script
├── build_macos.sh              # macOS build script
├── build_from_spec.bat         # Windows build script
├── requirements.txt            # Python dependencies
└── README.md                   # This file

Dependencies

• tkinter: GUI framework (included with Python)
• pyserial: Serial port communication
• esptool: ESP32 flashing utility
• pyinstaller: Executable builder

License

[Your license here]

Support

For issues and questions, please contact [your contact info].