149 lines
3.3 KiB
Markdown
149 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
python build.py
|
|
```
|
|
|
|
This script will:
|
|
1. Detect your platform automatically
|
|
2. Install required dependencies
|
|
3. Build the appropriate executable
|
|
|
|
### Platform-Specific Builds
|
|
|
|
#### macOS
|
|
|
|
```bash
|
|
./build_macos.sh
|
|
```
|
|
|
|
This creates an application bundle at `dist/ESP32_Flasher.app`
|
|
|
|
To run:
|
|
```bash
|
|
open dist/ESP32_Flasher.app
|
|
```
|
|
|
|
#### Windows
|
|
|
|
```batch
|
|
build_from_spec.bat
|
|
```
|
|
|
|
This creates an executable at `dist\ESP32_Flasher.exe`
|
|
|
|
#### Linux
|
|
|
|
```bash
|
|
python build.py
|
|
```
|
|
|
|
Creates an executable at `dist/ESP32_Flasher`
|
|
|
|
## Running Without Building
|
|
|
|
You can run the GUI directly with Python:
|
|
|
|
```bash
|
|
python gui_flasher.py
|
|
```
|
|
|
|
### Requirements
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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].
|