esphome-box3-builder

ESP32-S3-BOX-3 ビルダースキル

ESP32-S3-BOX-3 ハードウェア向けの専門スキルです。複雑なオーディオ／ディスプレイ／タッチ操作プロジェクトに役立つ、完全な設定テンプレート、ディスプレイラムダのクックブック、タッチ操作パターン、音声アシスタント統合を提供します。

目的

このスキルは、次の機能を提供して ESP32-S3-BOX-3 の開発を加速します。

• ハードウェア初期化の完全なテンプレート
• ディスプレイラムダ描画のクックブック（テキスト、図形、アイコン、複数ページ 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 ハードウェアを一から設定する
• ディスプレイラムダ描画（ILI9xxx）を実装する
• I²S オーディオパイプライン（ES7210、ES8311）を設定する
• GT911 タッチ操作を設定する
• ウェイクワード検出機能付きの音声アシスタントを構築する
• 複数ページのタッチスクリーン UI を作成する
• BOX-3 固有の問題をトラブルシューティングする

次の作業は、専門の ESPHome エージェントに委任してください。

• 詳細な技術解説（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 を使用したディスプレイラムダ
   • globals を使用したページ状態管理
   • インタラクティブなタッチスクリーンプロジェクトで使用

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 の完全な例とパターンについては、以下を参照してください。

• 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、ディスプレイと共用）

ディスプレイのちらつき：

• 解決策：color_palette: NONE を指定して PSRAM が有効になっていることを確認します

オーディオのポッピングノイズ：

• 解決策：サンプルレート（マイク 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（ハードウェア固有の既知の問題のセクション）

設定のベストプラクティス

PSRAM の設定（重要）

PSRAM の設定を必ず明示してください（2025.2 以降の要件）：

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

ESP-IDF フレームワーク（推奨）

BOX-3 では Arduino ではなく ESP-IDF を使用します。

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

他のスキルやエージェントとの統合

その他のリソースを使用する場合

• 一般的な ESPHome 設定：esphome-config-helper スキルを使用します

  • 基本的なデバイス設定
  • WiFi 設定
  • 一般的なセンサー（BOX-3 固有ではないもの）

• BOX-3 に関する詳細な技術的な質問：esphome-box3 エージェントに委任します

  • オーディオパイプラインのアーキテクチャ
  • ディスプレイ lambda API の詳細
  • 音声アシスタントのチューニング
  • ハードウェア固有の最適化

• ESPHome のコアコンセプト：esphome-core エージェントに委任します

  • YAML の構造と整理
  • 置換とシークレット
  • パッケージ管理

追加リソース

リファレンスファイル

BOX-3 の詳細情報については、以下を参照してください。

• references/box3-pinout.md - GPIO ピン配置、I²C アドレス、コンポーネント仕様、既知の問題を含む ESP32-S3-BOX-3 の完全なハードウェアリファレンス
• 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 - アイコンのコードポイントリファレンス

ユーティリティスクリプト

sc‌ripts/ にある検証および書き込みツール：

• 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 スキルを使用するか、ESPHome の専門エージェントに委任してください。