esphome-box3-builder

ESP32-S3-BOX-3 构建技能

面向 ESP32-S3-BOX-3 硬件的专业技能，为复杂的音频／显示／触摸项目提供完整的配置模板、显示 lambda 速查手册、触摸交互模式和语音助手集成方案。

用途

此技能通过提供以下内容，加快 ESP32-S3-BOX-3 项目的开发：

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

ESP32-S3-BOX-3 专属项目请使用此技能。对于通用 ESPHome 配置，请改用 esphome-config-helper 技能。

何时使用此技能

以下情况请使用此技能：

• 从头配置 ESP32-S3-BOX-3 硬件
• 实现显示 lambda 渲染（ILI9xxx）
• 设置 I²S 音频管线（ES7210、ES8311）
• 配置 GT911 触摸交互
• 构建带唤醒词检测的语音助手
• 创建多页面触摸屏 UI
• 排查 BOX-3 专属问题

以下任务请委派给专业的 ESPHome Agent：

• 深入的技术说明（esphome-box3 agent）
• 通用 ESPHome 概念（esphome-core agent）
• 网络配置（esphome-networking agent）

硬件概述

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 IMU

关键要求：

• 必须显式配置 PSRAM（2025.2+ 重大变更）
• 推荐使用 ESP-IDF 框架（对音频／显示支持更佳）
• 麦克风和扬声器共用 I²S 总线
• 显示屏和触摸屏共用复位引脚 GPIO48

完整硬件规格请参阅：

• references/box3-pinout.md - 完整 GPIO 引脚分配、组件地址和已知问题

配置模板

可用模板

位于 templates/ 目录：

1. box3-base.yaml - 硬件初始化基础模板

   • 使用八线模式的 PSRAM 配置 ESP-IDF 框架
   • I²S 音频总线配置
   • ES7210 ADC 和 ES8311 DAC 设置
   • ILI9xxx 显示屏基础配置
   • GT911 触摸初始化
   • 用作所有 BOX-3 项目的基础

2. box3-voice.yaml - 完整语音助手

   • 使用 okay_nabu 的 micro_wake_word
   • 语音助手管线（唤醒词 → HA Assist → TTS）
   • 使用 Nabu 媒体播放器进行音频闪避
   • 语音交互状态管理
   • 用于语音控制的 BOX-3 项目

3. box3-display-ui.yaml - 多页面触摸屏 UI

   • 3 页导航系统
   • 触摸区域二进制传感器
   • 使用 Material Design 的显示 lambda
   • 使用全局变量进行页面状态管理
   • 用于交互式触摸屏项目

4. box3-audio-player.yaml - 音乐／媒体播放器

   • 媒体播放器实体
   • 使用触摸按钮进行音量控制
   • 显示屏显示播放状态
   • 播放／暂停／跳过控制
   • 用于音频播放项目

使用模板

使用模板的步骤：

1. 阅读相应的模板文件
2. 自定义设备名称和 WiFi 凭据
3. 根据需要调整 UI 元素、颜色和字体
4. 使用 BOX-3 专属脚本刷写（参见“脚本”部分）

模板工作流：

# 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 渲染

Lambda 渲染手册

完整的显示 lambda 示例和模式，请参阅：

• references/display-lambdas.md - 显示 lambda 手册
  • 文本渲染（字体、对齐、换行）
  • 形状（矩形、圆形、直线）
  • 图标（Material Design Icons 集成）
  • 图像和精灵图
  • 动画模式
  • 多页面导航
  • 坐标系和定位

快速显示模式

基本文本显示：

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

填充矩形（卡片背景）：

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

多行文本：

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

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

Material Design UI 组件

Material Design 配色方案、排版和布局，请参阅：

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

字体集成

所需字体位于 assets/fonts/：

• Roboto-Regular.ttf - Material Design 排版
• materialdesignicons-webfont.ttf - MDI 图标字体

字体配置：

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
    ]

图标码点参考：assets/fonts/mdi-codepoints.txt

触摸交互模式

触摸配置

完整的触摸模式和手势检测，请参阅：

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

快速触摸模式

触摸按钮区域：

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"

页面导航：

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 音频设置

共享 I²S 总线（LRCLK=GPIO45、BCLK=GPIO17、MCLK=GPIO2）：

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

ES7210 麦克风 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 扬声器 DAC（48kHz、GPIO15，需要 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

语音助手集成

唤醒词配置

micro_wake_word（设备端检测）：

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

语音助手管线：

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"

音频闪避

Nabu Media Player（语音期间降低 30dB）：

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

脚本和实用工具

BOX-3 刷写脚本

验证和刷写实用工具提供了 BOX-3 专用工作流：

脚本：scripts/flash-box3.sh

用法：

# 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

BOX-3 问题排查

常见 BOX-3 错误

I²S DMA 缓冲区错误：

• 解决方案：在扬声器配置中将 buffer_duration 增大到 100ms

触摸无响应：

• 解决方案：检查 GPIO48 复位引脚（反转：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 Agent（深入的技术问题）
• references/box3-pinout.md（硬件专属已知问题章节）

配置最佳实践

PSRAM 配置（关键）

始终显式配置 PSRAM（2025.2+ 要求）：

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

ESP-IDF 框架（推荐）

BOX-3 使用 ESP-IDF 而非 Arduino：

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

显示配置

16 位颜色需要 PSRAM：

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

触摸配置

与显示屏共用复位引脚：

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

与其他技能和 Agent 集成

何时使用其他资源

• 常规 ESPHome 配置：使用 esphome-config-helper skill

  • 基本设备设置
  • WiFi 配置
  • 常见传感器（非 BOX-3 专用）

• 深入的 BOX-3 技术问题：委派给 esphome-box3 agent

  • 音频管线架构
  • 深入了解显示 lambda API
  • 语音助手调优
  • 硬件专属优化

• ESPHome 核心概念：委派给 esphome-core agent

  • YAML 结构与组织
  • 替换项与机密信息
  • 包管理

附加资源

参考文件

如需详细了解 BOX-3，请参阅：

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

模板文件

templates/ 中提供了完整可用的 BOX-3 配置：

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

资源文件

assets/ 中的 Material Design 资源：

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

实用脚本

scripts/ 中的验证和刷写工具：

• flash-box3.sh - BOX-3 专用的验证和刷写工作流

快速入门工作流

对于新的 ESP32-S3-BOX-3 项目：

1. 选择模板，依据项目类型（base、voice、display-ui、audio-player）
2. 复制模板到项目目录
3. 自定义配置：
   • 更新设备名称和 WiFi 凭据
   • 调整显示文本、颜色和布局
   • 修改触摸区域以适配自定义 UI
   • 如果使用语音功能，则配置唤醒词模型
4. 添加自定义功能，使用参考文档（display-lambdas.md、touch-patterns.md）
5. 验证并刷写，使用 scripts/flash-box3.sh
6. 监控日志，并在需要时使用参考指南排查问题

向现有 BOX-3 配置中添加内容：

1. 查阅参考文档，了解特定功能（显示、触摸、音频）
2. 从模板中复制相关代码
3. 集成到现有配置中
4. 逐步测试（每次添加一个功能）
5. 在最终刷写前进行验证

此技能可加速复杂音频/显示/触摸项目的 BOX-3 开发。对于常规 ESPHome 配置或深入的技术问题，请使用 esphome-config-helper skill，或委派给 ESPHome 专家 Agent。