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

# Run the ESP-IDF installer
# Launch ESP-IDF Command Prompt from Start Menu

2. Initialize ESP-IDF Environment

# In ESP-IDF Command Prompt
cd C:\Espressif\esp-idf
export.bat

3. Clone and Setup Project

# 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

# Set ESP-IDF environment for this project
C:\Espressif\esp-idf\export.bat

Build Methods

Method 1: PowerShell Script (Recommended)

# 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:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Method 2: Batch File (Simple)

# 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

# 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

# List all COM ports
mode

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

Flash and Monitor

# 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:

# Using batch file
build-guition.bat clean

# Or manually
idf.py fullclean
idf.py build

Verifying Installation

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