ESPHome 使用チュートリアル

このチュートリアルでは、ESPHome Device Builder を使用して ESPHome の設定を作成し、ファームウェアをコンパイルしてデバイスに書き込む方法を説明します。

1. 準備

環境の準備

1. Home Assistant 公式ドキュメントに従って Home Assistant をインストールし、起動します。
2. ESPHome 公式ドキュメントに従って ESPHome Device Builder をインストールし、起動します。

2. ファームウェアのコンパイルと書き込み

デバイスを作成する

1. Home AssistantのサイドバーからESPHome Builderを開きます。
2. 右下の+ Create deviceをクリックします。初回はページ上のAdd new deviceをクリックしてもかまいません。

3. Create configurationウィンドウでCreate new projectを選択します。

4. ボード一覧から実際に使用するボードを検索して選択します。

• 一覧に正確なモデルがある場合は、そのモデルを選択します。
• ボードが不明な場合は、Connect your boardをクリックして自動検出を試します。
• チップモデルと必要なパラメータを確認した場合に限り、Generic ESP32 Boardなどの汎用ボードを使用します。

5. デバイス名を入力し、Finish setupをクリックします。

設定を編集する

プロジェクトを作成すると、ESPHomeは最小限の設定を生成します。右側のエディタでYAMLを編集します。左側のCore configuration、Components、Automationsから設定項目を確認または追加できます。

デフォルト設定には通常、次の項目が含まれます。

Unit TMOS PIRを例に、まずESPHomeコンポーネントリポジトリを読み込みます。

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: [sths34pf80]
    refresh: 0s

読み込み後、適切なESPHomeプラットフォーム設定でこのコンポーネントを使用します。製品ごとの正確なプラットフォーム名、パラメータ、エンティティ設定は、対応するコンポーネントページを参照してください。

編集が完了したら、右下のSaveをクリックします。エディタに構文またはコンポーネントエラーが表示された場合は、コンパイルを続行する前に修正してください。

ファームウェアをコンパイルする

1. エディタ右下のInstallをクリックします。

インストール方法を選択する際は、次の表を参照してください。

ファームウェアを書き込む

Plug into this computer

初回の書き込みにはこの方法を推奨します。

1. USBデータケーブルでデバイスをパソコンに接続します。デバイスによっては、先にダウンロードモードへ切り替える必要があります。製品固有の説明を参照してください。
2. インストール方法のダイアログでPlug into this computerを選択します。
3. コンパイルが完了するまで待ちます。ログにSuccessfully compiled programと表示されたら、Open USB flasherをクリックします。

4. ブラウザの新しいタブでESPHome Webが開きます。firmware.factory.binが受信されていることを確認し、Connect & installをクリックします。

5. ブラウザに表示されたシリアルポート一覧から対象デバイスを選択し、Connectをクリックします。

一般的なシリアルポート名は次のとおりです。

• macOS：cu.usbmodem... または cu.usbserial...
• Linux：/dev/ttyUSB... または /dev/ttyACM...
• Windows：COM...

6. 画面の指示に従ってインストールを確認し、消去、書き込み、検証が完了するまで待ちます。書き込み中はページを表示したままにし、USBケーブルを外さないでください。
7. 書き込み後にデバイスを再起動します。デバイスはYAMLのWi-Fi 設定でネットワークに接続します。接続に失敗すると、フォールバックアクセスポイントを起動します。

Plug into your Home Assistant server

ブラウザを実行しているパソコンではなく、Home AssistantホストにデバイスをUSB 接続する場合に使用します。

1. デバイスをHome AssistantホストのUSBポートに接続します。
2. Plug into your Home Assistant serverを選択します。
3. シリアルポート一覧から対象デバイス（例：/dev/ttyUSB0または/dev/ttyACM0）を選択します。
4. コンパイルと書き込みが完了するまで待ち、デバイスを再起動します。

対象ポートが表示されない場合は、次を確認してください。

• USBケーブルがデータ転送に対応し、デバイスが正しく給電されていること。
• Home AssistantホストがUSBデバイスを認識していること。
• 仮想マシン、Docker、NAS 環境からHome Assistant/ESPHomeへUSBデバイスが割り当てられていること。
• シリアルポートを他のアドオンやプログラムが使用していないこと。

On the network（OTA）

この方法は、ESPHomeファームウェアがすでに動作し、デバイスがオンラインの場合にのみ使用できます。

1. デバイスとHome Assistantがネットワーク経由で相互に通信できることを確認します。
2. On the networkを選択します。
3. 対象デバイスを選択し、コンパイル、アップロード、再起動が完了するまで待ちます。
4. ログでデバイスが再接続し、起動エラーがないことを確認します。

初回書き込み、オフライン状態、ネットワーク設定変更後に再接続できない場合、またはOTA 設定を削除した場合は、USBで復旧してください。

ファームウェアをダウンロードして手動で書き込む

コンパイル結果ページのDownloadをクリックするとファームウェアを保存できます。初回の完全な書き込みには通常firmware.factory.binを使用します。firmware.ota.binはOTA 更新用であり、初回書き込み用ファイルの代わりには使用しないでください。

手動で書き込む前に、ファイル形式、チップモデル、Flash 設定、書き込みアドレスを確認してください。製品固有の説明がない場合は、可能な限りESPHomeのUSBフラッシャーを使用してください。

書き込み後、ESPHome Webにインストールの進行状況と再起動状態が表示されます。

3. 使用を開始する

Home Assistantに追加する

ファームウェアが起動してネットワークに接続すると、Home Assistantは通常 ESPHomeデバイスを自動検出します。

1. Settings -> Devices & servicesを開きます。

2. Discoveredに表示されたESPHomeデバイスを見つけ、Addをクリックします。

3. 確認ダイアログでデバイス情報を確認し、Submitをクリックします。

4. デバイス名を入力し、対応するAreaを選択してFinishをクリックします。

5. デバイス詳細ページを開き、エンティティの状態とセンサーデータが正常に更新されることを確認します。

Home Assistantがデバイスを自動検出しない場合：

1. Add integrationをクリックし、ESPHomeを検索します。
2. デバイスのホスト名（例：living-room-sensor.local）またはIPアドレスを入力します。
3. 求められた場合は、YAMLのapi.encryption.keyに対応するキーを入力します。