esphome-box3-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ESP32-S3-BOX-3 Builder Skill

ESP32-S3-BOX-3 构建工具技能

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.

专为ESP32-S3-BOX-3硬件打造的专业技能，为复杂的音频/显示/触摸项目提供完整的配置模板、Display Lambda渲染指南、触摸交互模式以及语音助手集成方案。

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.

本技能通过提供以下内容加速ESP32-S3-BOX-3的开发：

完整的硬件初始化模板
Display Lambda渲染指南（文本、图形、图标、多页面UI）
音频流水线配置方案（I²S、ES7210 ADC、ES8311 DAC）
触摸交互模式（按钮、滑动、手势）
语音助手集成（唤醒词、音频闪避、Home Assistant Assist）
Material Design UI组件
硬件专属故障排查与解决方法

仅在ESP32-S3-BOX-3专属项目中使用本技能。通用ESPHome配置请使用esphome-config-helper技能。

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)

在以下场景使用本技能：

从零开始配置ESP32-S3-BOX-3硬件
实现Display Lambda渲染（ILI9xxx）
搭建I²S音频流水线（ES7210、ES8311）
配置GT911触摸交互
构建带唤醒词检测的语音助手
创建多页面触摸屏UI
排查Box-3专属问题

以下场景请委托给专业ESPHome代理：

深度技术讲解（esphome-box3代理）
通用ESPHome概念（esphome-core代理）
网络配置（esphome-networking代理）

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

ESP32-S3-BOX-3是一套完整的开发套件，包含：

模块：ESP32-S3-WROOM-1（16MB Flash、16MB Octal PSRAM）
显示屏：ILI9342C（320x240、SPI、16位色需PSRAM支持）
触摸：GT911电容式触摸（I²C、多点触摸）
麦克风：ES7210 4通道ADC（I²S、16kHz）
扬声器：ES8311单声道DAC（I²S、48kHz、需MCLK）
传感器：BME688环境传感器、ICM-42607-P惯性测量单元

关键要求：

必须显式配置PSRAM（2025.2版本后为强制要求）
推荐使用ESP-IDF框架（对音频/显示屏支持更好）
麦克风与扬声器共享I²S总线
显示屏与触摸共享复位引脚GPIO48

完整硬件规格请参考：

references/box3-pinout.md
- 完整GPIO引脚定义、组件地址、已知问题

Configuration Templates

配置模板

Available Templates

可用模板

Located in

templates/

directory:

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

模板位于

templates/

目录下：

box3-base.yaml
- 硬件初始化基础模板
- 启用PSRAM八进制模式的ESP-IDF框架
- I²S音频总线配置
- ES7210 ADC与ES8311 DAC设置
- ILI9xxx显示屏基础配置
- GT911触摸初始化
- 作为所有Box-3项目的基础模板
box3-voice.yaml
- 完整语音助手模板
- 搭配okay_nabu的micro_wake_word
- 语音助手流水线（唤醒词 → HA Assist → TTS）
- 基于Nabu媒体播放器的音频闪避
- 语音交互状态管理
- 用于语音控制类Box-3项目
box3-display-ui.yaml
- 多页面触摸屏UI模板
- 3页面导航系统
- 触摸区域二进制传感器
- 带Material Design的Display Lambda
- 基于全局变量的页面状态管理
- 用于交互式触摸屏项目
box3-audio-player.yaml
- 音乐/媒体播放器模板
- 媒体播放器实体
- 触摸按钮音量控制
- 显示播放状态的显示屏
- 播放/暂停/切歌控制
- 用于音频播放类项目

Using Templates

模板使用方法

To use a template:

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

Template Workflow:

yaml

undefined

使用模板步骤：

阅读对应模板文件
自定义设备名称、WiFi凭据
根据需要调整UI元素、颜色、字体
使用Box-3专属脚本烧录（见脚本章节）

模板工作流：

yaml

undefined

1. Read template

1. 查看模板

cat .claude/skills/esphome-box3-builder/templates/box3-voice.yaml

2. Copy to project

2. 复制到项目目录

cp .claude/skills/esphome-box3-builder/templates/box3-voice.yaml my-box3.yaml

3. Edit device-specific values

3. 编辑设备专属配置

- Update device name

- 更新设备名称

- Set WiFi credentials (use secrets.yaml)

设置WiFi凭据（使用secrets.yaml）

- Customize wake word model if desired

- 按需自定义唤醒词模型

- Adjust display text and layout

- 调整显示屏文本与布局

4. Flash with BOX-3 script

4. 使用Box-3脚本烧录

./.claude/skills/esphome-box3-builder/scripts/flash-box3.sh my-box3.yaml

undefined

./.claude/skills/esphome-box3-builder/scripts/flash-box3.sh my-box3.yaml

undefined

Display Lambda Rendering

Display Lambda渲染

Lambda Rendering Cookbook

Lambda渲染指南

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

完整的Display Lambda示例与模式请参考：

references/display-lambdas.md
- Display Lambda使用指南
- 文本渲染（字体、对齐、换行）
- 图形（矩形、圆形、线条）
- 图标（Material Design Icons集成）
- 图片与精灵
- 动画模式
- 多页面导航
- 坐标系与定位

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

基础文本显示：

cpp

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

填充矩形（卡片背景）：

cpp

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

多行文本：

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

图标渲染（Material Design Icons）：

cpp

// 需在assets/fonts/中放入MDI字体
it.printf(30, 100, id(mdi_icons_24), "\U000F0425");  // 温度计图标

Material Design UI Components

Material Design UI组件

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)

Material Design配色方案、排版与布局请参考：

references/material-design.md
- Material Design UI指南
- 调色板（主色调、强调色、背景色、文本色）
- 排版层级（标题、正文、说明文字）
- 卡片布局与间距
- 图标集成
- 触摸区域尺寸（最小48x48像素）

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

所需字体位于

assets/fonts/

：

Roboto-Regular.ttf - Material Design标准字体
materialdesignicons-webfont.ttf - MDI图标字体

字体配置：

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",  # 温度计
      "\U000F050F",  # 湿度百分比
      "\U000F0493",  # 播放
      "\U000F03E4",  # 暂停
    ]

图标编码参考：

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

完整的触摸模式与手势检测请参考：

references/touch-patterns.md
- 触摸交互模式
- 按钮二进制传感器区域
- 滑动手势检测
- 长按模式
- 多点触摸处理
- 页面导航集成

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

触摸按钮区域：

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"

页面导航：

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

Audio Pipeline Configuration

音频流水线配置

I²S Audio Setup

I²S音频设置

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

共享I²S总线（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麦克风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扬声器DAC（48kHz、GPIO15、需MCLK）：

yaml

audio_dac:
  - platform: es8311
    id: es8311_dac
    bits_per_sample: 16bit
    sample_rate: 48000
    use_mclk: true  # 必须启用
    address: 0x18

speaker:
  - platform: i2s_audio
    dac_type: external
    i2s_dout_pin: GPIO15
    sample_rate: 48000
    buffer_duration: 100ms  # 防止音频爆音

Voice Assistant Integration

语音助手集成

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"

micro_wake_word（本地唤醒词检测）：

yaml

micro_wake_word:
  models:
    - model: okay_nabu  # 可选hey_jarvis、alexa、hey_mycroft

语音助手流水线：

yaml

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

  on_listening:
    - logger.log: "正在监听..."

  on_tts_start:
    - logger.log: "正在播报..."

  on_end:
    - logger.log: "完成"

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

Nabu媒体播放器（语音交互时音量降低30dB）：

yaml

media_player:
  - platform: nabu
    name: "Media Player"
    on_play:
      - media_player.volume_set:
          volume: 70%  # 语音助手激活时音量降至70%

Scripts and Utilities

脚本与工具

BOX-3 Flashing Script

Box-3烧录脚本

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

Script:

scripts/flash-box3.sh

Usage:

bash

undefined

验证与烧录工具提供Box-3专属工作流：

脚本：

scripts/flash-box3.sh

用法：

bash

undefined

Validate, compile, and flash BOX-3

验证、编译并烧录Box-3

./.claude/skills/esphome-box3-builder/scripts/flash-box3.sh my-box3.yaml

The script runs:

脚本执行以下操作：

1. Validates configuration

1. 验证配置

2. Compiles firmware with BOX-3 optimizations

2. 以Box-3优化参数编译固件

3. Flashes via USB (auto-detects /dev/ttyACM0 or /dev/ttyUSB0)

3. 通过USB烧录（自动识别/dev/ttyACM0或/dev/ttyUSB0）

4. Monitors logs after flash

4. 烧录后监控日志

undefined

undefined

Troubleshooting BOX-3 Issues

Box-3故障排查

Common BOX-3 Errors

常见Box-3错误

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)

I²S DMA缓冲区错误：

解决方案：在扬声器配置中增加
```
buffer_duration
```
至100ms

触摸无响应：

解决方案：检查GPIO48复位引脚（需设置inverted: true，与显示屏共享）

屏幕闪烁：

解决方案：确保已启用PSRAM并设置
```
color_palette: NONE
```

音频爆音：

解决方案：验证采样率（麦克风16kHz、扬声器48kHz），增加buffer_duration

未检测到PSRAM：

解决方案：确认配置中包含
```
psram: { mode: octal, speed: 80MHz }
```

语音助手崩溃：

解决方案：完全禁用Bluetooth/BLE（ESP32-S3上会导致崩溃）

OTA时UI冻结：

解决方案：在esp32.framework.advanced中添加
```
execute_from_psram: true
```

完整Box-3故障排查请参考：

esphome-box3代理（深度技术问题）
```
references/box3-pinout.md
```
（硬件专属已知问题章节）

Configuration Best Practices

配置最佳实践

PSRAM Configuration (Critical)

PSRAM配置（关键）

Always include explicit PSRAM config (2025.2+ requirement):

yaml

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

必须显式配置PSRAM（2025.2版本后强制要求）：

yaml

psram:
  mode: octal  # Box-3配备16MB Octal PSRAM
  speed: 80MHz

ESP-IDF Framework (Recommended)

ESP-IDF框架（推荐）

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

Box-3项目优先使用ESP-IDF而非Arduino：

yaml

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf
    advanced:
      execute_from_psram: true  # 防止OTA时UI冻结

Display Configuration

显示屏配置

16-bit color requires PSRAM:

yaml

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

16位色需PSRAM支持：

yaml

display:
  - platform: ili9xxx
    model: S3BOX
    color_palette: NONE  # 2025.2版本后需PSRAM
    # ...

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

与显示屏共享复位引脚：

yaml

touchscreen:
  - platform: gt911
    reset_pin:
      number: GPIO48
      inverted: true  # 与显示屏复位引脚共享
    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

通用ESPHome配置：使用esphome-config-helper技能
- 基础设备设置
- WiFi配置
- 通用传感器（非Box-3专属）
Box-3深度技术问题：委托给esphome-box3代理
- 音频流水线架构
- Display Lambda API深度解析
- 语音助手调优
- 硬件专属优化
ESPHome核心概念：委托给esphome-core代理
- YAML结构与组织
- 替换与密钥管理
- 包管理

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

Box-3详细信息请参考：

references/box3-pinout.md
- ESP32-S3-BOX-3完整硬件参考，包含GPIO引脚定义、I²C地址、组件规格与已知问题
references/display-lambdas.md
- 全面的Display Lambda指南，包含文本渲染、图形、图标、图片、动画与多页面导航模式
references/touch-patterns.md
- 触摸交互模式，包含按钮区域、滑动手势、长按检测与页面导航集成
references/material-design.md
- Material Design UI指南，包含调色板、排版层级、卡片布局、图标使用与触摸区域尺寸规范

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

templates/

目录下的完整可运行Box-3配置：

box3-base.yaml
- 硬件初始化基础模板
box3-voice.yaml
- 带唤醒词的语音助手模板
box3-display-ui.yaml
- 多页面触摸屏UI模板
box3-audio-player.yaml
- 音乐/媒体播放器模板

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

assets/

目录下的Material Design资源：

fonts/Roboto-Regular.ttf
- Material Design标准字体
fonts/materialdesignicons-webfont.ttf
- MDI图标字体
fonts/mdi-codepoints.txt
- 图标编码参考

Utility Scripts

工具脚本

Validation and flashing tools in

scripts/

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

scripts/

目录下的验证与烧录工具：

flash-box3.sh
- Box-3专属验证与烧录工作流

Quick Start Workflow

快速开始工作流

For new ESP32-S3-BOX-3 project:

Select template based on project type (base, voice, display-ui, audio-player)
Copy template to project directory
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
Add custom features using references (display-lambdas.md, touch-patterns.md)
Validate and flash using
```
scripts/flash-box3.sh
```
Monitor logs and troubleshoot if needed using reference guides

For adding to existing BOX-3 config:

Consult references for specific feature (display, touch, audio)
Copy relevant code from templates
Integrate with existing config
Test incrementally (add one feature at a time)
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.

新建ESP32-S3-BOX-3项目：

选择模板 根据项目类型选择（基础、语音、显示UI、音频播放器）
复制模板 到项目目录
自定义配置：
- 更新设备名称与WiFi凭据
- 调整显示屏文本、颜色、布局
- 为自定义UI修改触摸区域
- 使用语音功能时配置唤醒词模型
添加自定义功能 参考相关文档（display-lambdas.md、touch-patterns.md）
验证并烧录 使用
```
scripts/flash-box3.sh
```
监控日志 如需排查问题请参考指南

为现有Box-3配置添加功能：

参考文档 查找对应功能（显示、触摸、音频）
复制相关代码 从模板中提取
集成到现有配置
增量测试 每次添加一个功能
验证最终烧录前进行验证

本技能为复杂音频/显示/触摸项目提供快速Box-3开发能力。通用ESPHome配置或深度技术问题请使用esphome-config-helper技能或委托给ESPHome专业代理。