esphome-box3-builder

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.

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)

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

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

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

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

1. 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:

```yaml

# 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

```

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:

```cpp

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

```

Filled Rectangle (Card Background):

```cpp

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

```

Multi-Line Text:

```cpp

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

```cpp

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

```yaml

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

```yaml

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:

```yaml

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));

```

I²S Audio Setup

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

```yaml

i2s_audio:

- id: i2s_shared

i2s_lrclk_pin: GPIO45

i2s_bclk_pin: GPIO17

i2s_mclk_pin: GPIO2

```

ES7210 Microphone ADC (16kHz, GPIO16):

```yaml

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

```yaml

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

```

Wake Word Configuration

micro_wake_word (on-device detection):

```yaml

micro_wake_word:

models:

- model: okay_nabu # or hey_jarvis, alexa, hey_mycroft

```

Voice Assistant Pipeline:

```yaml

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

```yaml

media_player:

- platform: nabu

name: "Media Player"

on_play:

- media_player.volume_set:

volume: 70% # Reduce to 70% when voice assistant active

```

BOX-3 Flashing Script

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

Script: scripts/flash-box3.sh

Usage:

```bash

# 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

```

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)

PSRAM Configuration (Critical)

Always include explicit PSRAM config (2025.2+ requirement):

```yaml

psram:

mode: octal # BOX-3 has 16MB Octal PSRAM

speed: 80MHz

```

ESP-IDF Framework (Recommended)

Use ESP-IDF over Arduino for BOX-3:

```yaml

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:

```yaml

display:

- platform: ili9xxx

model: S3BOX

color_palette: NONE # Requires PSRAM (2025.2+)

# ...

```

Touch Configuration

Shared reset pin with display:

```yaml

touchscreen:

- platform: gt911

reset_pin:

number: GPIO48

inverted: true # Shared with display reset

interrupt_pin:

number: GPIO3

ignore_strapping_warning: true

```

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

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

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

1. Add custom features using references (display-lambdas.md, touch-patterns.md)
2. Validate and flash using scripts/flash-box3.sh
3. 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.