squeezelite-esp32-gronod/WINDOWS_BUILD_GUIDE.md

# Windows Build Guide for Guition JC4827W543C

This guide explains how to build squeezelite-esp32 for the Guition board on Windows.

## Prerequisites

1. **ESP-IDF for Windows**
   - Download and install ESP-IDF from: https://dl.espressif.com/dl/esp-idf/
   - Run the installer and follow the setup instructions
   - Make sure to install the required tools (Git, Python, CMake)

2. **Visual Studio Build Tools** (if not already installed by ESP-IDF)
   - Install from Visual Studio Installer
   - Select "C++ build tools"

3. **Hardware**
   - Guition JC4827W543C board
   - USB cable for power and programming
   - External I2S audio DAC (required)

## Setup Instructions

### 1. Install ESP-IDF
```cmd
# Run the ESP-IDF installer
# Launch ESP-IDF Command Prompt from Start Menu
```

### 2. Initialize ESP-IDF Environment
```cmd
# In ESP-IDF Command Prompt
cd C:\Espressif\esp-idf
export.bat
```

### 3. Clone and Setup Project
```cmd
# Navigate to your workspace
cd C:\Users\YourName\Projects

# Clone the repository (if not already done)
git clone <repository-url> squeezelite-esp32-gronod
cd squeezelite-esp32-gronod
```

### 4. Set Environment for Project
```cmd
# Set ESP-IDF environment for this project
C:\Espressif\esp-idf\export.bat
```

## Build Methods

### Method 1: PowerShell Script (Recommended)
```powershell
# Open PowerShell as Administrator
# Navigate to project directory
cd C:\Users\YourName\Projects\squeezelite-esp32-gronod

# Run the build script
.\build-guition.ps1

# For clean build
.\build-guition.ps1 -Clean
```

**Note:** If you get execution policy errors, run:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### Method 2: Batch File (Simple)
```cmd
# Open Command Prompt
# Navigate to project directory
cd C:\Users\YourName\Projects\squeezelite-esp32-gronod

# Run the build script
build-guition.bat

# For clean build
build-guition.bat clean
```

### Method 3: Manual Commands
```cmd
# Set ESP-IDF environment
C:\Espressif\esp-idf\export.bat

# Set target
set IDF_TARGET=esp32s3

# Copy Guition config
copy /Y squeezelite-esp32-Guition-sdkconfig.defaults sdkconfig.defaults

# Configure (opens menu interface)
idf.py menuconfig

# Build
idf.py build
```

## Menuconfig Configuration

When `idf.py menuconfig` runs:

1. **Select Target Hardware**:
   - Navigate to: `Squeezelite-ESP32` → `Guition JC4827W543C`

2. **Configure Audio** (if needed):
   - Navigate to: `Audio settings` → `DAC settings`
   - Set I2S GPIO pins for your external DAC
   - Default: BCK=15, WS=16, DO=17

3. **Save and Exit**:
   - Press `S` to save
   - Press `Q` to exit

## Flashing the Firmware

### Find Your COM Port
```cmd
# List all COM ports
mode

# Or check Device Manager under "Ports (COM & LPT)"
```

### Flash and Monitor
```cmd
# Flash firmware
idf.py -p COM3 flash

# Flash and monitor (recommended)
idf.py -p COM3 flash monitor

# Just monitor (if already flashed)
idf.py -p COM3 monitor
```

### Using the Scripts
Both PowerShell and batch scripts will ask if you want to flash after building.

## Troubleshooting

### Common Issues

1. **"ESP-IDF environment not found"**
   - Make sure you're running from ESP-IDF Command Prompt
   - Or run `C:\Espressif\esp-idf\export.bat` first

2. **"Python not found"**
   - ESP-IDF installer should include Python
   - Check that Python is in your PATH

3. **"Build tools not found"**
   - Install Visual Studio Build Tools
   - Make sure C++ tools are selected

4. **"Permission denied" (PowerShell)**
   - Run PowerShell as Administrator
   - Or set execution policy: `Set-ExecutionPolicy RemoteSigned`

5. **"COM port not found"**
   - Check device connections
   - Install USB drivers if needed (CH340/CP210x)
   - Check Device Manager

### Clean Build
If you encounter build issues:
```cmd
# Using batch file
build-guition.bat clean

# Or manually
idf.py fullclean
idf.py build
```

### Verifying Installation
```cmd
# Check ESP-IDF version
idf.py --version

# Check target
echo %IDF_TARGET%

# List available targets
idf.py --help | findstr target
```

## Development Workflow

1. **Initial Setup**: Run the build script once to configure
2. **Code Changes**: Make your modifications
3. **Build**: Run `.\build-guition.ps1` or `build-guition.bat`
4. **Flash**: Let the script flash automatically, or use `idf.py -p COMX flash`
5. **Monitor**: Use `idf.py -p COMX monitor` to view logs

## Performance Tips

- **SSD Storage**: Build on SSD for much faster compilation
- **RAM**: 8GB+ recommended for large projects
- **CPU**: Multi-core CPU helps with parallel compilation
- **Antivirus**: Exclude project directory from real-time scanning

## Next Steps

After successful build and flash:

1. Connect to WiFi AP created by device
2. Configure your network settings
3. Set up audio DAC configuration
4. Connect to your Logitech Media Server

For more detailed configuration, see `GUITION_SETUP.md`.