ESP32-S3-BOX-3 Builder Skill

Specialist skill for ESP32-S3-BOX-3 hardware providing complete configuration templates, display lambda cookbook, touch interaction patterns, and voice assistant integration for complex audio/display/touch projects.

Purpose

This skill accelerates ESP32-S3-BOX-3 development by providing:

• Complete hardware initialization templates
• Display lambda rendering cookbook (text, shapes, icons, multi-page UI)
• Audio pipeline recipes (I²S, ES7210 ADC, ES8311 DAC)
• Touch interaction patterns (buttons, swipes, gestures)
• Voice assistant integration (wake word, ducking, Home Assistant Assist)
• Material Design UI components
• Hardware-specific troubleshooting and workarounds

Use this skill for ESP32-S3-BOX-3 specific projects. For general ESPHome configuration, use the esphome-config-helper skill instead.

When to Use This Skill

Use this skill when:

• Configuring ESP32-S3-BOX-3 hardware from scratch
• Implementing display lambda rendering (ILI9xxx)
• Setting up I²S audio pipeline (ES7210, ES8311)
• Configuring GT911 touch interaction
• Building voice assistant with wake word detection
• Creating multi-page touchscreen UI
• Troubleshooting BOX-3 specific issues

Delegate to specialized ESPHome agents for:

• Deep technical explanations (esphome-box3 agent)
• General ESPHome concepts (esphome-core agent)
• Network configuration (esphome-networking agent)

Hardware Overview

The ESP32-S3-BOX-3 is a complete development kit with:

• Module: ESP32-S3-WROOM-1 (16MB Flash, 16MB Octal PSRAM)
• Display: ILI9342C (320x240, SPI, PSRAM required for 16-bit color)
• Touch: GT911 capacitive (I²C, multi-touch)
• Microphone: ES7210 4-channel ADC (I²S, 16kHz)
• Speaker: ES8311 mono DAC (I²S, 48kHz, requires MCLK)
• Sensors: BME688 environmental, ICM-42607-P IMU

Critical Requirements:

• PSRAM must be explicitly configured (2025.2+ breaking change)
• ESP-IDF framework recommended (better audio/display support)
• Shared I²S bus for microphone and speaker
• Reset pin GPIO48 shared between display and touch

For complete hardware specifications, consult:

• references/box3-pinout.md - Complete GPIO pinout, component addresses, known issues

Configuration Templates

Available Templates

Located in templates/ directory:

1. box3-base.yaml - Hardware initialization foundation
   • ESP-IDF framework with PSRAM octal mode
   • I²S audio bus configuration
   • ES7210 ADC and ES8311 DAC setup
   • ILI9xxx display basic config
   • GT911 touch initialization
   • Use as foundation for all BOX-3 projects
2. box3-voice.yaml - Complete voice assistant
   • micro_wake_word with okay_nabu
   • Voice assistant pipeline (wake word → HA Assist → TTS)
   • Audio ducking with Nabu media player
   • State management for voice interaction
   • Use for voice-controlled BOX-3 projects
3. box3-display-ui.yaml - Multi-page touchscreen UI
   • 3-page navigation system
   • Touch zone binary sensors
   • Display lambda with Material Design
   • Page state management with globals
   • Use for interactive touchscreen projects
4. box3-audio-player.yaml - Music/media player
   • Media player entity
   • Volume control with touch buttons
   • Display showing playback status
   • Play/pause/skip controls
   • Use for audio playback projects

Using Templates

To use a template:

1. Read the appropriate template file
2. Customize device name, WiFi credentials
3. Adjust UI elements, colors, fonts as needed
4. Flash using BOX-3 specific script (see Scripts section)

Template Workflow:

# 1. Read template
cat .claude/skills/esphome-box3-builder/templates/box3-voice.yaml

# 2. Copy to project
cp .claude/skills/esphome-box3-builder/templates/box3-voice.yaml my-box3.yaml

# 3. Edit device-specific values
# - Update device name
# - Set WiFi credentials (use secrets.yaml)
# - Customize wake word model if desired
# - Adjust display text and layout

# 4. Flash with BOX-3 script
./.claude/skills/esphome-box3-builder/scripts/flash-box3.sh my-box3.yaml

Display Lambda Rendering

Lambda Rendering Cookbook

For complete display lambda examples and patterns, consult:

• references/display-lambdas.md - Display lambda cookbook
  • Text rendering (fonts, alignment, wrapping)
  • Shapes (rectangles, circles, lines)
  • Icons (Material Design Icons integration)
  • Images and sprites
  • Animation patterns
  • Multi-page navigation
  • Coordinate system and positioning

Quick Display Patterns

Basic Text Display:

it.printf(160, 10, id(roboto_16), TextAlign::TOP_CENTER, "ESP32-S3-BOX-3");

Filled Rectangle (Card Background):

it.filled_rectangle(10, 30, 300, 80, COLOR_PRIMARY);

Multi-Line Text:

it.printf(20, 40, id(roboto_12), "Temperature: %.1f°C", id(temp_sensor).state);
it.printf(20, 60, id(roboto_12), "Humidity: %.1f%%", id(humidity_sensor).state);

Icon Rendering (Material Design Icons):

// Requires MDI font in assets/fonts/
it.printf(30, 100, id(mdi_icons_24), "\U000F0425");  // thermometer icon

Material Design UI Components

For Material Design color schemes, typography, and layouts, consult:

• references/material-design.md - Material Design UI guide
  • Color palette (primary, accent, background, text)
  • Typography hierarchy (headlines, body, captions)
  • Card layouts and spacing
  • Icon integration
  • Touch zone sizing (minimum 48x48 pixels)

Font Integration

Required fonts are in assets/fonts/:

• Roboto-Regular.ttf - Material Design typography
• materialdesignicons-webfont.ttf - MDI icon font

Font Configuration:

font:
  - file: .claude/skills/esphome-box3-builder/assets/fonts/Roboto-Regular.ttf
    id: roboto_16
    size: 16

  - file: .claude/skills/esphome-box3-builder/assets/fonts/materialdesignicons-webfont.ttf
    id: mdi_icons_24
    size: 24
    glyphs: [
      "\U000F0425",  # thermometer
      "\U000F050F",  # water-percent
      "\U000F0493",  # play
      "\U000F03E4",  # pause
    ]

Icon codepoints reference: assets/fonts/mdi-codepoints.txt

Touch Interaction Patterns

Touch Configuration

For complete touch patterns and gesture detection, consult:

• references/touch-patterns.md - Touch interaction patterns
  • Binary sensor zones for buttons
  • Swipe gesture detection
  • Long press patterns
  • Multi-touch handling
  • Page navigation integration

Quick Touch Patterns

Touch Button Zone:

binary_sensor:
  - platform: touchscreen
    name: "Button 1"
    x_min: 10
    x_max: 150
    y_min: 200
    y_max: 230
    on_press:
      - logger.log: "Button 1 pressed"

Page Navigation:

binary_sensor:
  - platform: touchscreen
    name: "Next Page"
    x_min: 240
    x_max: 310
    y_min: 200
    y_max: 230
    on_press:
      - lambda: |-
          id(current_page) = (id(current_page) + 1) % 3;
          id(box3_display).show_page(id(current_page));

Audio Pipeline Configuration

I²S Audio Setup

Shared I²S Bus (LRCLK=GPIO45, BCLK=GPIO17, MCLK=GPIO2):

i2s_audio:
  - id: i2s_shared
    i2s_lrclk_pin: GPIO45
    i2s_bclk_pin: GPIO17
    i2s_mclk_pin: GPIO2

ES7210 Microphone ADC (16kHz, GPIO16):

audio_adc:
  - platform: es7210
    id: es7210_adc
    bits_per_sample: 16bit
    sample_rate: 16000
    mic_gain: 24DB
    address: 0x40

microphone:
  - platform: i2s_audio
    adc_type: external
    i2s_din_pin: GPIO16
    sample_rate: 16000

ES8311 Speaker DAC (48kHz, GPIO15, requires MCLK):

audio_dac:
  - platform: es8311
    id: es8311_dac
    bits_per_sample: 16bit
    sample_rate: 48000
    use_mclk: true  # Required
    address: 0x18

speaker:
  - platform: i2s_audio
    dac_type: external
    i2s_dout_pin: GPIO15
    sample_rate: 48000
    buffer_duration: 100ms  # Prevents audio popping

Voice Assistant Integration

Wake Word Configuration

micro_wake_word (on-device detection):

micro_wake_word:
  models:
    - model: okay_nabu  # or hey_jarvis, alexa, hey_mycroft

Voice Assistant Pipeline:

voice_assistant:
  microphone: box_mic
  speaker: box_speaker
  noise_suppression_level: 1
  auto_gain: 31dBFS
  volume_multiplier: 2.0

  on_listening:
    - logger.log: "Listening..."

  on_tts_start:
    - logger.log: "Speaking..."

  on_end:
    - logger.log: "Done"

Audio Ducking

Nabu Media Player (30dB reduction during voice):

media_player:
  - platform: nabu
    name: "Media Player"
    on_play:
      - media_player.volume_set:
          volume: 70%  # Reduce to 70% when voice assistant active

Scripts and Utilities

BOX-3 Flashing Script

The validation and flashing utility provides BOX-3 specific workflow:

Script: scripts/flash-box3.sh

Usage:

# Validate, compile, and flash BOX-3
./.claude/skills/esphome-box3-builder/scripts/flash-box3.sh my-box3.yaml

# The script runs:
# 1. Validates configuration
# 2. Compiles firmware with BOX-3 optimizations
# 3. Flashes via USB (auto-detects /dev/ttyACM0 or /dev/ttyUSB0)
# 4. Monitors logs after flash

Troubleshooting BOX-3 Issues

Common BOX-3 Errors

I²S DMA Buffer Error:

• Solution: Increase buffer_duration to 100ms in speaker config

Touch Not Responding:

• Solution: Check GPIO48 reset pin (inverted: true, shared with display)

Display Flicker:

• Solution: Ensure PSRAM enabled with color_palette: NONE

Audio Popping:

• Solution: Verify sample rates (16kHz mic, 48kHz speaker), increase buffer_duration

PSRAM Not Detected:

• Solution: Confirm psram: { mode: octal, speed: 80MHz } in config

Voice Assistant Crashes:

• Solution: Disable Bluetooth/BLE completely (causes crashes on ESP32-S3)

UI Freezing During OTA:

• Solution: Add execute_from_psram: true in esp32.framework.advanced

For complete BOX-3 troubleshooting, consult:

• esphome-box3 agent (deep technical issues)
• references/box3-pinout.md (hardware-specific known issues section)

Configuration Best Practices

PSRAM Configuration (Critical)

Always include explicit PSRAM config (2025.2+ requirement):

psram:
  mode: octal  # BOX-3 has 16MB Octal PSRAM
  speed: 80MHz

ESP-IDF Framework (Recommended)

Use ESP-IDF over Arduino for BOX-3:

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf
    advanced:
      execute_from_psram: true  # Prevents UI freezing during OTA

Display Configuration

16-bit color requires PSRAM:

display:
  - platform: ili9xxx
    model: S3BOX
    color_palette: NONE  # Requires PSRAM (2025.2+)
    # ...

Touch Configuration

Shared reset pin with display:

touchscreen:
  - platform: gt911
    reset_pin:
      number: GPIO48
      inverted: true  # Shared with display reset
    interrupt_pin:
      number: GPIO3
      ignore_strapping_warning: true

Integration with Other Skills and Agents

When to Use Other Resources

• General ESPHome config: Use esphome-config-helper skill
  • Basic device setup
  • WiFi configuration
  • Common sensors (not BOX-3 specific)
• Deep BOX-3 technical questions: Delegate to esphome-box3 agent
  • Audio pipeline architecture
  • Display lambda API deep dive
  • Voice assistant tuning
  • Hardware-specific optimizations
• ESPHome core concepts: Delegate to esphome-core agent
  • YAML structure and organization
  • Substitutions and secrets
  • Package management

Additional Resources

Reference Files

For detailed BOX-3 information, consult:

• references/box3-pinout.md - Complete ESP32-S3-BOX-3 hardware reference with GPIO pinout, I²C addresses, component specifications, and known issues
• references/display-lambdas.md - Comprehensive display lambda cookbook with text rendering, shapes, icons, images, animation, and multi-page navigation patterns
• references/touch-patterns.md - Touch interaction patterns including button zones, swipe gestures, long press detection, and page navigation integration
• references/material-design.md - Material Design UI guide with color palette, typography hierarchy, card layouts, icon usage, and touch zone sizing guidelines

Template Files

Complete working BOX-3 configurations in templates/:

• box3-base.yaml - Hardware initialization foundation
• box3-voice.yaml - Voice assistant with wake word
• box3-display-ui.yaml - Multi-page touchscreen UI
• box3-audio-player.yaml - Music/media player

Asset Files

Material Design resources in assets/:

• fonts/Roboto-Regular.ttf - Material Design typography
• fonts/materialdesignicons-webfont.ttf - MDI icon font
• fonts/mdi-codepoints.txt - Icon codepoint reference

Utility Scripts

Validation and flashing tools in scripts/:

• flash-box3.sh - BOX-3 specific validation and flashing workflow

Quick Start Workflow

For new ESP32-S3-BOX-3 project:

1. Select template based on project type (base, voice, display-ui, audio-player)
2. Copy template to project directory
3. Customize configuration:
   • Update device name and WiFi credentials
   • Adjust display text, colors, layout
   • Modify touch zones for custom UI
   • Configure wake word model if using voice
4. Add custom features using references (display-lambdas.md, touch-patterns.md)
5. Validate and flash using scripts/flash-box3.sh
6. Monitor logs and troubleshoot if needed using reference guides

For adding to existing BOX-3 config:

1. Consult references for specific feature (display, touch, audio)
2. Copy relevant code from templates
3. Integrate with existing config
4. Test incrementally (add one feature at a time)
5. Validate before final flash

This skill provides rapid BOX-3 development for complex audio/display/touch projects. For general ESPHome configuration or deep technical questions, use the esphome-config-helper skill or delegate to ESPHome specialist agents.