soundshot/flash_tool/BUILD_NOTES.md

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:

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)

python3 build.py

macOS Specific

./build_macos.sh

or

source venv/bin/activate
pyinstaller ESP32_Flasher_macOS.spec

Windows Specific

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

xattr -cr dist/ESP32_Flasher.app

Port permission issues on Linux

sudo usermod -a -G dialout $USER

(Logout/login required)

Build fails on macOS

Make sure virtual environment is active:

source venv/bin/activate