esphome-config-helper

ESPHome 設定ヘルパー

すぐに使えるテンプレート、GPIO リファレンスガイド、検証ユーティリティを備えた、ESPHome 設定の迅速な生成とトラブルシューティングのためのスキルです。

目的

このスキルは、以下を提供して ESPHome デバイスの設定を効率化します。

• 一般的なデバイスタイプ向けのクイックスタートテンプレート
• ピンの競合を防ぐ GPIO ピン配置リファレンス
• 配線図付きの一般的なセンサー設定
• エラーメッセージの検索と解決方法
• 設定の検証ワークフロー

一般的な ESPHome 設定タスクでは、このスキルを使用してください。ESP32-S3-BOX-3 固有の実装には、代わりに esphome-box3-builder スキルを使用してください。

このスキルを使用する場面

以下の場合にこのスキルを使用してください。

• 新しい ESPHome デバイスの設定を開始するとき
• 既存の設定にセンサー、スイッチ、ディスプレイを追加するとき
• コンパイル時または実行時のエラーをトラブルシューティングするとき
• コンポーネントに安全な GPIO ピンを特定するとき
• 書き込み前に設定を検証するとき

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

• 高度な技術的な質問（esphome-core、esphome-components など）
• 複雑なオートメーションロジック（esphome-automations エージェント）
• ネットワークのトラブルシューティング（esphome-networking エージェント）
• ESP32-S3-BOX-3 プロジェクト（esphome-box3 エージェント）

設定テンプレート

利用可能なテンプレート

templates/ ディレクトリにあります。

1. basic-device.yaml - 最小構成の ESP32 スターター

   • WiFi と API を備えた ESP32 プラットフォーム
   • OTA アップデートを有効化
   • ロガーとウェブサーバー
   • カスタムプロジェクトのベースとして使用します

2. sensor-node.yaml - 温度／湿度センサーノード

   • GPIO4 に DHT22 センサーを接続
   • フォールバック AP 付き WiFi
   • Home Assistant との連携
   • 環境モニタリングに使用します

3. relay-switch.yaml - 4 チャンネルリレーコントローラー

   • 4 つのリレーを GPIO で制御（GPIO23、GPIO22、GPIO21、GPIO19）
   • インターロック付き物理ボタン入力
   • Home Assistant 用のスイッチエンティティ
   • ホームオートメーションのスイッチ制御に使用します

4. display-node.yaml - センサー付きディスプレイ

   • SSD1306 OLED ディスプレイ（128x64、I²C）
   • DHT22 温度／湿度センサー
   • センサーの読み取り値を表示するディスプレイラムダ
   • センサー情報の視覚的な表示に使用します

テンプレートの使用方法

テンプレートを使用するには：

1. 適切なテンプレートファイルを読みます
2. デバイス名、WiFi 認証情報、GPIO ピンをカスタマイズします
3. 必要に応じてコンポーネントを追加または削除します
4. 設定を検証します（以下の「検証ワークフロー」を参照）

テンプレートのワークフロー：

# 1. Read template
cat .claude/skills/esphome-config-helper/templates/sensor-node.yaml

# 2. Copy to project
cp .claude/skills/esphome-config-helper/templates/sensor-node.yaml my-device.yaml

# 3. Edit with device-specific values
# - Update device name
# - Set WiFi credentials (use secrets.yaml)
# - Adjust GPIO pins if needed
# - Customize sensor names

# 4. Validate (see Validation Workflow)

GPIO ピンリファレンス

GPIO のクイック検索

GPIO の詳細なピン配置と安全なピンの選択については、以下を参照してください。

• references/gpio-pinouts.md - ESP32 および ESP8266 の GPIO リファレンス
  • 各プラットフォームで安全に使えるピン
  • 避けるべきストラッピングピン
  • I²C／SPI／UART のデフォルトピン
  • 入力専用ピンと出力対応ピン
  • 起動失敗の原因となるピン（GPIO0、GPIO2、GPIO15）

安全に使えるピン：

• ESP32：GPIO4、GPIO5、GPIO12、GPIO13、GPIO14、GPIO16、GPIO17、GPIO18、GPIO19、GPIO21、GPIO22、GPIO23、GPIO25-27、GPIO32、GPIO33
• ESP8266：GPIO4（D2）、GPIO5（D1）、GPIO12（D6）、GPIO13（D7）、GPIO14（D5）

避けるべきピン（ストラッピング／起動用ピン）：

• ESP32：GPIO0、GPIO2、GPIO5、GPIO12、GPIO15（使用には注意が必要です）
• ESP8266：GPIO0、GPIO2、GPIO15

一般的なセンサー設定

センサー選択ガイド

配線図付きの詳細なセンサー設定については、以下を参照してください。

• references/common-sensors.md - 主な 20 種類のセンサー設定
  • 温度／湿度センサー（DHT22、BME280、SHT3x）
  • モーションセンサー（PIR、mmWave）
  • 光センサー（BH1750、TSL2561）
  • 距離センサー（HC-SR04、VL53L0X）
  • ガスセンサー（MQ シリーズ、SGP30）
  • 完全な配線図とプラットフォームの選択

センサーのおすすめ：

• 温度／湿度：BME280（I²C、DHT22 より信頼性が高い）
• モーション：HC-SR501 PIR（GPIO バイナリセンサー）
• 光：BH1750（I²C、正確な照度測定）
• 距離：HC-SR04（超音波式、測定範囲 2～400cm）
• 空気質：BME680（I²C、温度／湿度／気圧／ガス）

基本的なセンサーパターン

I²C センサー（BME280 の例）：

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true

sensor:
  - platform: bme280
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    pressure:
      name: "Pressure"
    address: 0x76
    update_interval: 60s

GPIO センサー（DHT22 の例）：

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    update_interval: 60s

バイナリセンサー（PIR モーション）：

binary_sensor:
  - platform: gpio
    pin: GPIO14
    name: "Motion Sensor"
    device_class: motion

トラブルシューティングガイド

エラー検索

エラーメッセージの完全な検索テーブルと解決策については、以下を参照してください。

• references/troubleshooting.md - エラーメッセージの包括的なリファレンス
  • コンパイルエラー（不明なプラットフォーム、GPIO の競合、依存関係の問題）
  • 実行時エラー（WiFi の失敗、センサーのタイムアウト、OTA の問題）
  • 設定エラー（YAML 構文、無効なピン、コンポーネントの不足）
  • ハードウェアの問題（センサーが検出されない、リレーが切り替わらない）

よくあるエラーのクイックリファレンス：

エラーメッセージ	クイック修正
"Unknown platform"	コンポーネント名のスペルを確認し、プラットフォームがサポートされていることを確認します
"GPIO already in use"	GPIO ピンの割り当てを確認し、重複を避けます
"Could not compile"	YAML 構文を確認し、インデント（2 スペース）を確認します
"WiFi connection failed"	SSID／パスワードを確認し、信号強度を確認して、静的 IP を使用します
"Sensor not found"	I²C アドレスを確認し（scan: true を使用）、配線を確認します
"OTA upload failed"	デバイスに到達可能か確認し、OTA パスワードを確認して、デバイスを再起動します

トラブルシューティングのワークフロー

エラーが発生した場合：

1. YAML 構文を確認する：インデント（2 スペース、タブなし）を確認します
2. GPIO ピンを検証する：競合がないことを確認し、安全なピンを使用します
3. コンポーネントのプラットフォームを確認する：プラットフォーム名と設定を確認します
4. ログを確認する：esphome logs device.yaml を使用して、実行時エラーを確認します
5. リファレンスを参照する：具体的なエラーについては references/troubleshooting.md を確認します
6. 設定を検証する：検証ワークフローを実行します（以下を参照）

検証ワークフロー

検証スクリプトの使用

検証ユーティリティを使用すると、設定をすばやく確認できます。

スクリプト：scripts/validate-config.sh

使用方法：

# Validate configuration
./.claude/skills/esphome-config-helper/scripts/validate-config.sh my-device.yaml

# The script runs:
# 1. esphome config my-device.yaml  (syntax check)
# 2. esphome compile my-device.yaml (compilation test)

検証手順：

1. 構文検証：esphome config my-device.yaml

   • YAML 構文を確認します
   • コンポーネントの設定を検証します
   • 不足している要件を報告します
   • 最終的な設定を表示します

2. コンパイルテスト：esphome compile my-device.yaml

   • 必要なライブラリをダウンロードします
   • ファームウェアをコンパイルします
   • エラーと警告を報告します
   • 設定が機能することを確認します

3. エラーを修正する：検証に失敗した場合：

   • エラーメッセージを確認します
   • GPIO の競合を確認します
   • コンポーネントのプラットフォームを確認します
   • references/troubleshooting.md を参照します
   • 修正後に再検証します

書き込み前のチェックリスト

デバイスに書き込む前に：

• 設定がエラーなしで検証される
• WiFi の認証情報が正しい（secrets.yaml を使用）
• デバイス名がネットワーク上で一意である
• GPIO ピンが安全であることを確認済み
• OTA パスワードが設定されている（今後の更新用）
• API 暗号化キーが設定されている（2026.1.0 以降）

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

YAML 構造

設定を論理的なセクションに整理します。

# 1. Core platform
esphome:
  name: device-name
  friendly_name: Device Name

esp32:
  board: esp32dev
  framework:
    type: arduino

# 2. Network
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    password: !secret ota_password

# 3. Logging
logger:
web_server:

# 4. Components (sensors, switches, etc.)
sensor:
  # ...

binary_sensor:
  # ...

シークレットの管理

機密データには secrets.yaml を使用します。

secrets.yaml:

wifi_ssid: "MyNetwork"
wifi_password: "MyPassword123"
api_encryption_key: "base64-generated-key"
ota_password: "SecureOTAPassword"

設定での参照：

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

命名規則

一貫した命名規則に従います。

• デバイス名：小文字とハイフン（例：bedroom-sensor）
• エンティティ名：各単語の先頭を大文字にし、単語間にスペースを入れる（例："Bedroom Temperature"）
• ID：小文字とアンダースコア（例：temp_sensor）

例：

sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "Living Room Temperature"
      id: living_room_temp
    humidity:
      name: "Living Room Humidity"
      id: living_room_humidity

他のスキルやエージェントとの連携

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

• ESP32-S3-BOX-3 プロジェクト：esphome-box3-builder スキルを使用します

  • オーディオパイプライン（I²S、ES7210、ES8311）
  • ディスプレイのラムダ描画（ILI9xxx）
  • タッチ操作（GT911）
  • 音声アシスタントとの連携

• 高度な技術的な質問：ESPHome エージェントに委任します

  • コアコンセプト → esphome-core エージェント
  • コンポーネントの選定 → esphome-components エージェント
  • オートメーションのロジック → esphome-automations エージェント
  • ネットワークの問題 → esphome-networking エージェント
  • HA との連携 → esphome-homeassistant エージェント

• 複雑なプロジェクト：リソースを組み合わせます

  • テンプレートから開始します（このスキル）
  • エージェントのガイダンスに沿ってカスタマイズします
  • スクリプトで検証します（このスキル）
  • デプロイしてトラブルシューティングを行います（このスキルとエージェント）

追加リソース

参考ファイル

詳しい情報については、以下を参照してください。

• references/gpio-pinouts.md - 安全なピン、ストラッピングピン、ピンの機能を含む、ESP32/ESP8266 の GPIO 完全リファレンス
• references/common-sensors.md - 配線図、プラットフォームの選択、使用例を含む、上位 20 種類のセンサー構成
• references/troubleshooting.md - コンパイル時、実行時、ハードウェアの問題に対する解決策をまとめた、包括的なエラーメッセージ検索表

テンプレートファイル

templates/ にある動作確認済みの設定例：

• basic-device.yaml - 最小構成の ESP32 基盤
• sensor-node.yaml - DHT22 温度・湿度ノード
• relay-switch.yaml - 4 チャンネルリレーコントローラー
• display-node.yaml - センサー付き OLED ディスプレイ

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

/scripts/ にある検証・テストツール：

• validate-config.sh - ESPHome 設定検証用ラッパー

クイックスタートのワークフロー

新しい ESPHome デバイスの場合：

1. デバイスの種類（センサー、スイッチ、ディスプレイ、または基本構成）に応じてテンプレートを選択
2. テンプレートをプロジェクトディレクトリにコピー
3. 設定をカスタマイズ：
   • デバイス名を更新
   • secrets.yaml に WiFi 認証情報を設定
   • references/gpio-pinouts.md を参照して GPIO ピンを調整
   • 必要に応じてコンポーネントを追加・削除
4. scripts/validate-config.sh を使用して設定を検証
5. references/troubleshooting.md を参照してエラーを修正
6. 検証済みの設定でデバイスに書き込む
7. ログを監視し、必要に応じてトラブルシューティング

既存の設定に追加する場合：

1. コンポーネントの設定についてリファレンスを確認
2. references/gpio-pinouts.md でGPIO の空き状況を確認
3. 設定にコンポーネントを追加
4. 書き込む前に検証
5. 更新して監視

このスキルは、一般的な ESPHome のユースケース向けに、設定をすばやく生成します。特殊なハードウェア（ESP32-S3-BOX-3）や高度な技術的な質問には、適切な専門スキルとエージェントを使用してください。