# 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].