【ITニュース解説】How I Log ESPHome Device Data to CSV with Python (and Why You Should Too)

ホームオートメーションの世界では、スマートデバイスが私たちの生活を便利にしてくれる。中でも、ESP32のような安価でパワフルなボードにESPHomeというソフトウェアを組み合わせたデバイスは、DIYで様々な自動化プロジェクトを実現するのに非常に人気がある。しかし、これらのデバイスから得られるデータを、より信頼性の高い形で長期的に記録し、分析したいと考えた時、標準的なツールだけでは不十分な場合がある。この記事では、ESPHomeデバイスのデータをPythonを使って直接取得し、CSVファイルに記録する方法について解説する。

多くの人がESPHomeデバイスを「Home Assistant」というスマートホームプラットフォームと連携させて利用している。Home Assistantはデバイスの状態を管理したり、自動化ルールを設定したり、ダッシュボードで現状を視覚化したりするのに非常に優れている。また、デバイスの履歴データをデータベースに保存する機能も備わっている。しかし、Home Assistantの履歴機能にはいくつかの限界がある。まず、そのデータベースは主にダッシュボードでの表示に最適化されており、詳細な生データ分析には向いていない。古いデータは整理されたり、すべての状態変化が細かく記録されないことがある。例えば、センサーがまれにしかデータを送信しない場合、Home Assistantの履歴だけでは、センサーがデータを送らなかったのか、それともHome Assistantがその更新を捉え損ねたのかを判別するのが難しい。さらに、Home AssistantからCSV形式でデータをエクスポートしようとすると、手順が複雑で手間がかかる場合が多い。特に、ディープスリープモードを使ってバッテリーを節約しているESPHomeデバイスの場合、デバイスが目覚めてデータを送信し、すぐにスリープに戻るというサイクルの中で、Home Assistantのデータベースだけでは正確な更新時刻やデータ欠損の有無を完全に把握することは困難になる。こうした理由から、Home Assistantに依存せず、デバイスから直接、一切加工されていない生のデータを時系列で確実に記録できる「ブラックボックスレコーダー」のような仕組みが必要だと感じられた。

この課題を解決するために目を向けたのが、ESPHomeが提供するネイティブAPIだ。これは、Home Assistantが内部でESPHomeデバイスと通信する際に使っているのと同じ仕組みで、TCPプロトコル（デフォルトではポート6053）を通じてデバイスと直接対話できる。Pythonにはaioesphomeapiという優れたライブラリがあり、これを利用すれば、認証、デバイスの発見、そしてリアルタイムでのデータストリーミングといった複雑な処理を簡単に行うことができる。このAPIを使うことで、Home Assistantがデータをどう処理・保存するかに関わらず、センサーの生データ、スイッチの状態、バイナリセンサーのオンオフといったあらゆる更新情報を、発生した瞬間に直接受け取ることが可能になる。

まず、PythonからESPHomeデバイスと通信する基本的なスクリプトを作成する。aioesphomeapiライブラリを使ってデバイスのIPアドレスやパスワードを指定し、接続を確立する。接続後、デバイスから送られてくるすべての状態更新（センサーの値、スイッチの状態など）を受け取るためのコールバック関数を登録する。このコールバック関数は、デバイスから新しいデータが送られてくるたびに自動的に実行される仕組みだ。スクリプトを実行すると、例えば30秒ごとに温度センサーが報告する値や、バイナリセンサーがON/OFFを切り替える瞬間、さらにはディープスリープから一時的に復帰してデータを送信し、再びスリープするデバイスの更新まで、すべての情報がリアルタイムでコンソールに表示される。このデータストリームは完全に「生」であり、平均化されたり、古いデータが削られたりすることはなく、デバイスが実際に何を送っているかの真実を教えてくれる。これがトラブルシューティングや長期的なログ記録にとって非常に価値のある情報となる。

コンソールにデータを表示するだけでは、実用的なデータ分析や長期保存には適さない。そこで、取得したデータをCSV（Comma Separated Values）ファイルに記録することにした。CSVは非常にシンプルで汎用的なファイル形式であり、ExcelやGoogle Sheetsのような表計算ソフトで簡単に開いて閲覧できるだけでなく、PythonのPandasライブラリを使えば数行のコードでデータ分析に取り込むことができる。また、プレーンテキスト形式であるため、特別なツールやデータベースがなくても、テキストエディタで内容を確認できるという利点がある。データをすべて一つの巨大なファイルに保存し続けると、時間の経過とともに管理が難しくなるため、ログファイルを毎日自動的に切り替える仕組みも導入した。具体的には、日付ごとに異なるファイル名（例：esphome_2025-09-06.csv）を付けて保存することで、古いデータを簡単にアーカイブしたり、日ごとの傾向を分析したり、必要に応じて古いログだけを圧縮したりすることが可能になる。

この機能を実現するために、「ESPHomeLogger」というPythonのクラスを設計した。このクラスは、ESPHomeのネイティブAPIを使用してデバイスに接続し、すべての更新（センサー、スイッチなど）を購読する。そして、各更新を受け取るたびに、タイムスタンプ（ISO 8601形式）、エンティティID（sensor.living_room_tempのような一意の識別子）、フレンドリー名（「リビングルームの温度」のような分かりやすい名前）、そして生のデータ値を含む一行をCSVファイルに書き込む。また、真夜中になると自動的に新しい日付のCSVファイルを作成し、そのファイルにヘッダー行を書き込む機能も備えている。この仕組みによって、リアルタイムの更新を見るだけでなく、ESPHomeデバイスが報告したすべての値が、整理された日ごとの形式で永続的に記録されるようになる。値がNoneであったり、数値型でNaN（非数）であったりする場合には、ログに含めずにスキップするような堅牢な処理も含まれている。さらに、接続が失われた場合でも、指定された間隔で自動的に再接続を試みるリトライロジックも実装されており、ログ記録の中断を最小限に抑えるよう配慮されている。

一つのデバイスのログを記録できるようになったら、次は複数のデバイスに対応させることを考えるのは自然な流れだ。家にはリビングルームの温度・湿度センサー、キッチンのCO₂センサー、寝室のバッテリー駆動センサーなど、複数のESPHomeデバイスが設置されていることが多い。それぞれのデバイスから独立してログを取得することで、家全体の環境の履歴を総合的に把握できるようになる。Pythonのasyncio（非同期処理）ライブラリを利用すると、複数のESPHomeLoggerインスタンスを同時に実行するのが非常に簡単だ。それぞれのロガーインスタンスは独自のタスクとして動作し、それぞれのデバイスに接続して、それぞれのCSVファイルにデータを書き込む。各デバイスのログは、デバイスごとに異なる専用のフォルダ（例：logs/living_room、logs/bedroom）に保存され、その中に日ごとのCSVファイルが作成される。この構造は非常に整理されており、デバイスごとのログのアーカイブ、特定の部屋のデータ抽出、複数のCSVファイルを読み込んでデバイス間の傾向を比較するといった作業を容易にする。このシステムが稼働することで、Home Assistantだけでは得られなかった、ESPHomeデバイスの透明で信頼性の高い履歴が手に入る。

このプロジェクトを通して、いくつかの重要な教訓が得られた。Home Assistantはスマートホームの中核として非常に強力だが、特にディープスリープを使用するデバイスやバッテリー駆動のデバイスなど、不安定なデバイスのデバッグにおいては、生のデバイスデータが何よりも真実を語る場合があることを理解した。Home Assistantの履歴だけでは、デバイスが実際にデータを送信したのか、あるいは何らかの理由で更新が漏れたのかを判断しきれないことがあったのだ。また、ESPHomeのネイティブAPIがPythonで驚くほど簡単に扱えることも分かった。aioesphomeapiライブラリのおかげで、わずかなコードでESP32デバイスからの更新をリアルタイムでストリーミング監視することが可能になった。日ごとのCSVログの存在は、データ分析において非常に大きな効果をもたらした。ディープスリープデバイスが予定通りに起動しなかった場合の更新の見落としをすぐに特定したり、リビングルームと寝室の夜間の温度差を比較したり、古いデータをHome Assistantのデータベースを肥大化させることなくアーカイブしたり、PandasやGrafanaのようなツールにデータを取り込んで詳細な分析を行ったりと、多くのメリットがあった。最終的に、Home Assistantのような素晴らしいプラットフォームがあっても、すべてのニッチなニーズをカバーできるわけではないということに気付いた。軽量な補助スクリプトを自作することで、以前は得られなかったレベルの透明性と制御を手に入れることができたのである。