# Common error messages
fatal: unable to access 'https://github.com/espressif/esp-idf.git/': 
SSL certificate problem: certificate verify failed

# Solution 1: Use mirror source
git config --global http.sslverify false
git clone https://github.com/espressif/esp-idf.git

# Solution 2: Use domestic mirror (China users)
git clone https://gitee.com/EspressifSystems/esp-idf.git

# Error message
ERROR: Could not install packages due to an EnvironmentError

# Solution: Use virtual environment
python -m venv esp-idf-env
source esp-idf-env/bin/activate  # Linux/macOS
# esp-idf-env\Scripts\activate.bat  # Windows
pip install -r requirements.txt

# Error: xtensa-esp32s3-elf-gcc: command not found

# Solution: Re-run install and export
cd esp-idf
./install.sh esp32s3
source export.sh

# Add to ~/.bashrc for permanent setup
echo 'source ~/esp-idf/export.sh' >> ~/.bashrc

// Error: 'class WiFiClass' has no member named 'setSleep'

// Solution: Update ESP32 Arduino Core
// Tools → Board Manager → ESP32 → Update to latest version (>= 2.0.5)

// Alternative: Use correct API
WiFi.setSleep(false);  // Correct for newer versions

# Error message
E (123) flash: Detected size(4MB) doesn't match configured size(16MB)

# Solution 1: Check actual flash size
esptool.py --port /dev/ttyUSB0 flash_id

# Solution 2: Configure correct flash size
idf.py menuconfig
→ Serial flasher config → Flash size → 4MB/8MB/16MB

# Error: PSRAM not found
E (456) spiram: SPI RAM not found

# Solution: Check PSRAM configuration
idf.py menuconfig
→ Component config → ESP32S3-Specific → Support for external SPI RAM
→ Type of SPI RAM chip in use → ESP-PSRAM64

# Error: Partition table length mismatch
E (789) esp_image: Invalid partition table

# Solution: Regenerate partition table
idf.py partition-table
idf.py erase-flash
idf.py flash

// Error: fatal error: 'driver/i2s.h' file not found

// Solution: Add correct include paths
#include "driver/i2s.h"  // ESP-IDF style
// or
#include <driver/i2s.h>  // Alternative style

// Check component dependencies in CMakeLists.txt
REQUIRES driver

// Error: 'i2s_driver_install' was not declared in this scope

// Solution: Include correct headers and link libraries
#include "driver/i2s.h"

// For Arduino IDE, ensure ESP32 core version compatibility
// Some functions changed between ESP-IDF versions

// Error: 'xTaskCreatePinnedToCore' undeclared

// Solution: Include FreeRTOS headers
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

// Check stack size (minimum 2048 bytes recommended)
xTaskCreatePinnedToCore(taskFunction, "TaskName", 4096, NULL, 1, NULL, 1);

# Error: Serial port /dev/ttyUSB0 not found

# Solution 1: Check USB connection and cables
lsusb  # Linux
system_profiler SPUSBDataType  # macOS

# Solution 2: Install drivers
# CP210x: https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers
# CH340: http://www.wch.cn/downloads/

# Error: Permission denied: '/dev/ttyUSB0'

# Solution: Add user to dialout group
sudo usermod -a -G dialout $USER
# Logout and login again, or:
sudo chmod 666 /dev/ttyUSB0

# Error: Device or resource busy

# Solution: Close other programs using the port
sudo lsof | grep ttyUSB
kill -9 <PID>

# Or use different port
ls /dev/tty*  # Find available ports

# Error: Failed to connect to ESP32-S3: Timed out waiting for packet header

# Solution 1: Enter download mode manually
# Hold BOOT button, press and release RESET, then release BOOT

# Solution 2: Check wiring for auto-download circuit
# GPIO0 to BOOT button (pull to GND)
# EN to RESET button

# Error: A fatal error occurred: MD5 of file does not match data in flash

# Solution 1: Erase flash completely
idf.py erase-flash

# Solution 2: Use slower baud rate
idf.py -b 115200 flash  # Instead of default 460800

# Solution 3: Check power supply (ensure stable 3.3V, sufficient current)

# Error: Invalid bootloader

# Solution: Flash bootloader separately
idf.py bootloader-flash
idf.py app-flash

# Error: ***ERROR*** A stack overflow in task TaskName has been detected

# Solution 1: Increase task stack size
xTaskCreatePinnedToCore(task, "TaskName", 8192, NULL, 1, NULL, 1);
//                                        ^^^^^ Increase from 4096

# Solution 2: Check recursive functions and large local variables
// Move large arrays to heap
int* large_array = (int*)malloc(1000 * sizeof(int));

# Error: E (123) heap: alloc failed, heap is corrupt

# Solution 1: Monitor heap usage
size_t free_heap = esp_get_free_heap_size();
Serial.printf("Free heap: %u bytes\n", free_heap);

# Solution 2: Use PSRAM for large allocations
void* ptr = ps_malloc(large_size);  // Allocate in PSRAM

// Solution: Use memory pools or reduce allocation frequency
#include "esp_heap_caps.h"

// Check heap integrity
bool heap_ok = heap_caps_check_integrity_all(true);
if (!heap_ok) {
    Serial.println("Heap corruption detected!");
}

// Check I2S configuration
i2s_config_t i2s_config = {
    .mode = (i2s_mode_t)(I2S_MODE_MASTER | I2S_MODE_TX),
    .sample_rate = 16000,
    .bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT,  // Check this
    .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,   // Check this
    .communication_format = I2S_COMM_FORMAT_STAND_I2S,
    .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
    .dma_buf_count = 4,                             // Try 8
    .dma_buf_len = 1024,                            // Try 512
    .use_apll = false
};

// Verify pin connections
// BCLK, LRC, DIN pins must match hardware

// Solution 1: Check sample rate matching
// Ensure source sample rate matches I2S configuration

// Solution 2: Add delay in audio loop
void audioTask(void* param) {
    while(1) {
        // Process audio
        vTaskDelay(pdMS_TO_TICKS(10));  // Add small delay
    }
}

// Solution 3: Use higher priority for audio tasks
xTaskCreatePinnedToCore(audioTask, "Audio", 4096, NULL, 5, NULL, 1);
//                                                       ^ High priority

// Debug Wi-Fi connection
WiFi.onEvent([](WiFiEvent_t event, WiFiEventInfo_t info) {
    switch(event) {
        case ARDUINO_EVENT_WIFI_STA_START:
            Serial.println("WiFi Started");
            break;
        case ARDUINO_EVENT_WIFI_STA_CONNECTED:
            Serial.println("WiFi Connected");
            break;
        case ARDUINO_EVENT_WIFI_STA_GOT_IP:
            Serial.printf("WiFi Got IP: %s\n", WiFi.localIP().toString().c_str());
            break;
        case ARDUINO_EVENT_WIFI_STA_DISCONNECTED:
            Serial.printf("WiFi Disconnected. Reason: %d\n", info.wifi_sta_disconnected.reason);
            break;
    }
});

// Common disconnect reasons:
// 2: Auth expired
// 3: Auth leave  
// 4: Assoc expired
// 8: Assoc leave
// 15: 4-way handshake timeout

// Solution: Adjust power management
WiFi.setSleep(false);  // Disable power save mode

// Check signal strength
int32_t rssi = WiFi.RSSI();
Serial.printf("Signal strength: %d dBm\n", rssi);
// Good: > -50 dBm, Fair: -50 to -70 dBm, Poor: < -70 dBm

// Use external antenna if available

// Check pin configuration
pinMode(pin, OUTPUT);
digitalWrite(pin, HIGH);

// Verify pin is not used by other functions
// ESP32-S3 pins 19-20 are used for USB-JTAG
// Pins 26-32 may not exist on some modules

// Use multimeter to verify voltage levels
// 3.3V = HIGH, 0V = LOW

// Internal pull-up/down may be weak (45kΩ)
pinMode(pin, INPUT_PULLUP);   // 45kΩ pull-up
pinMode(pin, INPUT_PULLDOWN); // 45kΩ pull-down

// For critical signals, use external resistors (10kΩ)

// I2C Scanner code
#include <Wire.h>

void scanI2C() {
    Serial.println("Scanning I2C devices...");
    for (byte address = 1; address < 127; address++) {
        Wire.beginTransmission(address);
        if (Wire.endTransmission() == 0) {
            Serial.printf("Device found at 0x%02X\n", address);
        }
    }
}

// Check wiring:
// SDA, SCL pins
// Pull-up resistors (4.7kΩ recommended)
// Power supply (3.3V)

// Add error checking
Wire.beginTransmission(device_address);
Wire.write(register_address);
Wire.write(data);
byte error = Wire.endTransmission();

switch(error) {
    case 0: Serial.println("Success"); break;
    case 1: Serial.println("Data too long"); break;
    case 2: Serial.println("NACK on address"); break;
    case 3: Serial.println("NACK on data"); break;
    case 4: Serial.println("Other error"); break;
}

# Error: Brownout detector was triggered

# Solutions:
# 1. Use adequate power supply (>=500mA for ESP32-S3)
# 2. Add decoupling capacitors (100µF + 10µF near VDD)
# 3. Disable brownout detector (not recommended)
idf.py menuconfig → Component config → ESP32S3-Specific → Brownout voltage

// Measure and optimize power consumption
#include "esp_pm.h"
#include "esp_sleep.h"

// Enable power management
esp_pm_config_esp32s3_t pm_config = {
    .max_freq_mhz = 240,
    .min_freq_mhz = 80,
    .light_sleep_enable = true
};
esp_pm_configure(&pm_config);

// Use light sleep when possible
esp_sleep_enable_timer_wakeup(1000000);  // 1 second
esp_light_sleep_start();

# Error: Task watchdog got triggered

# Solution 1: Reset watchdog in long loops
#include "esp_task_wdt.h"

while (long_operation) {
    // Do work
    esp_task_wdt_reset();  // Reset watchdog
}

# Solution 2: Increase watchdog timeout
idf.py menuconfig → Component config → ESP System Settings → Task Watchdog timeout period

// Optimize task distribution between cores
// Core 0: Protocol stack, WiFi, Bluetooth
// Core 1: Application tasks

// Pin CPU-intensive tasks to Core 1
xTaskCreatePinnedToCore(heavyTask, "Heavy", 4096, NULL, 1, NULL, 1);
//                                                               ^ Core 1

// Pin network tasks to Core 0  
xTaskCreatePinnedToCore(networkTask, "Network", 4096, NULL, 1, NULL, 0);
//                                                                   ^ Core 0

// Use PSRAM for large, infrequently accessed data
uint8_t* large_buffer = (uint8_t*)ps_malloc(1024 * 1024);  // 1MB in PSRAM

// Keep frequently accessed data in internal RAM
uint8_t audio_buffer[4096];  // Small, fast access

// Configure PSRAM speed
idf.py menuconfig → Component config → ESP32S3-Specific → SPI RAM config
→ Set SPI RAM clock to 80MHz

// Multi-level debugging system
#define DEBUG_LEVEL 3  // 0=Error, 1=Warn, 2=Info, 3=Debug

#define DEBUG_PRINT(level, ...) \
    if (level <= DEBUG_LEVEL) { \
        Serial.printf("[%lu] ", millis()); \
        Serial.printf(__VA_ARGS__); \
        Serial.println(); \
    }

// Usage
DEBUG_PRINT(2, "WiFi connecting to %s", ssid);
DEBUG_PRINT(1, "Warning: Low memory %d bytes", esp_get_free_heap_size());
DEBUG_PRINT(0, "Error: I2S init failed");

// Add debug pins for logic analyzer
#define DEBUG_PIN_1  GPIO_NUM_18
#define DEBUG_PIN_2  GPIO_NUM_19

void setup() {
    gpio_set_direction(DEBUG_PIN_1, GPIO_MODE_OUTPUT);
    gpio_set_direction(DEBUG_PIN_2, GPIO_MODE_OUTPUT);
}

void criticalSection() {
    gpio_set_level(DEBUG_PIN_1, 1);  // Mark section start
    // Critical code here
    gpio_set_level(DEBUG_PIN_1, 0);  // Mark section end
}

void printHeapInfo() {
    multi_heap_info_t info;
    heap_caps_get_info(&info, MALLOC_CAP_INTERNAL);
    
    Serial.printf("=== Internal RAM ===\n");
    Serial.printf("Total: %u bytes\n", info.total_free_bytes + info.total_allocated_bytes);
    Serial.printf("Free: %u bytes\n", info.total_free_bytes);
    Serial.printf("Allocated: %u bytes\n", info.total_allocated_bytes);
    Serial.printf("Largest free block: %u bytes\n", info.largest_free_block);
    
    heap_caps_get_info(&info, MALLOC_CAP_SPIRAM);
    Serial.printf("=== PSRAM ===\n");
    Serial.printf("Free: %u bytes\n", info.total_free_bytes);
    Serial.printf("Allocated: %u bytes\n", info.total_allocated_bytes);
}