adding web flasher tool

2025-10-13 18:54:50 -05:00
parent 04d2c71d01
commit 2513a9e7fb
21 changed files with 2071 additions and 177 deletions
--- a/flash_tool/README.md
+++ b/flash_tool/README.md
@@ -0,0 +1,148 @@
+# 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].