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/BUILD_NOTES.md
+++ b/flash_tool/BUILD_NOTES.md
@@ -0,0 +1,110 @@
+# Build Notes
+
+## Build Status
+
+✅ **macOS Build: SUCCESS**
+- Built on: macOS 15.6 (arm64)
+- Python Version: 3.9.6 (Xcode system Python with tkinter support)
+- Output: `dist/ESP32_Flasher.app`
+- Size: ~7.0 MB
+- Tested: ✅ Application launches and runs successfully
+
+## Prerequisites
+
+### macOS
+**Important:** Homebrew's Python 3.13 does NOT include tkinter support by default.
+
+**Solution:** Install python-tk package:
+```bash
+brew install python-tk@3.13
+```
+
+However, the build system will automatically use the system Python (3.9.6 from Xcode) which has tkinter built-in. This is the recommended approach.
+
+## Known Issues
+
+### ~~macOS tkinter Warning~~ - RESOLVED
+**Previous Issue:** Homebrew Python 3.13 doesn't include tkinter
+**Solution:** Build system now uses Xcode's Python 3.9.6 which has native tkinter support
+**Status:** ✅ Fixed - no warnings, app works perfectly
+
+### Virtual Environment Required (macOS)
+Due to PEP 668 (externally-managed environments), macOS requires using a virtual environment for pip installations. The build scripts automatically handle this.
+
+## Build Commands
+
+### Quick Build (Any Platform)
+```bash
+python3 build.py
+```
+
+### macOS Specific
+```bash
+./build_macos.sh
+```
+or
+```bash
+source venv/bin/activate
+pyinstaller ESP32_Flasher_macOS.spec
+```
+
+### Windows Specific
+```batch
+build_from_spec.bat
+```
+
+## Distribution
+
+### macOS
+- Distribute the entire `ESP32_Flasher.app` folder (it's a bundle)
+- Users may need to run: `xattr -cr ESP32_Flasher.app` if macOS blocks it
+- Consider creating a DMG for easier distribution
+
+### Windows
+- Distribute the single `ESP32_Flasher.exe` file
+- No installation required
+- May trigger Windows SmartScreen (normal for unsigned apps)
+
+## File Structure
+
+```
+flash_tool/
+├── dist/                          # Build output
+│   ├── ESP32_Flasher.app         # macOS bundle
+│   └── ESP32_Flasher             # Standalone binary
+├── build/                         # Build artifacts
+├── venv/                          # Python virtual environment (macOS)
+├── gui_flasher.py                # Source code
+├── ESP32_Flasher_macOS.spec      # macOS build config
+├── ESP32_Flasher_Windows.spec    # Windows build config
+├── build.py                      # Universal build script
+├── build_macos.sh                # macOS build script
+└── build_from_spec.bat           # Windows build script
+```
+
+## Next Steps
+
+1. **Testing**: Test the app with actual ESP32 hardware and firmware
+2. **Icons**: Add custom icons (.icns for macOS, .ico for Windows)
+3. **Code Signing**: Sign the executables for production distribution
+4. **DMG Creation**: Package macOS app in a DMG for easier distribution
+5. **Windows Installer**: Consider creating an NSIS or WiX installer
+
+## Troubleshooting
+
+### "App is damaged" on macOS
+```bash
+xattr -cr dist/ESP32_Flasher.app
+```
+
+### Port permission issues on Linux
+```bash
+sudo usermod -a -G dialout $USER
+```
+(Logout/login required)
+
+### Build fails on macOS
+Make sure virtual environment is active:
+```bash
+source venv/bin/activate
+```