enecoQ Data Fetcher

enecoQ から電力使用量、電力使用料金、CO2 排出量を取得する CLI ツールです。enecoQ は株式会社ファミリーネットジャパンが提供する CYBERHOME サービス内の電力データ管理 Web サービスで、公開 API がないため、このツールは Playwright でブラウザを操作してデータを取得します。今日または今月のデータを JSON かコンソール表示で出力します。

必要要件

• CYBERHOME（enecoQ）のアカウント
• Python 3.10 以上

インストール

どの方法でも、初回に Playwright のブラウザ（Chromium）のインストールが必要です。

uvx

インストールせずに直接実行できます。

uvx --from enecoq-data-fetcher playwright install chromium
uvx enecoq-data-fetcher --email your@email.com --password yourpassword

uv tool

uv tool install --with-executables-from playwright enecoq-data-fetcher
playwright install chromium

--with-executables-from playwright を付けると、依存パッケージの playwright コマンドも PATH に入ります。

pipx

pipx install --include-deps enecoq-data-fetcher
playwright install chromium

pip

仮想環境を有効にした状態で実行してください。

pip install enecoq-data-fetcher
playwright install chromium

使用方法

enecoq-data-fetcher --email your@email.com --password yourpassword

uvx の場合は先頭を uvx enecoq-data-fetcher に置き換えてください。

# 今日のデータをコンソールに表示
enecoq-data-fetcher --email your@email.com --password yourpassword --period today --format console

# 今月のデータを JSON ファイルに保存
enecoq-data-fetcher --email your@email.com --password yourpassword --output data/power_data.json

環境変数で認証情報を渡す

--email と --password の代わりに、環境変数 ENECOQ_EMAIL と ENECOQ_PASSWORD でも認証情報を渡せます。両方を指定した場合はコマンドライン引数が優先されます。

--password に書いたパスワードは、同じマシンの他のユーザーがプロセス一覧（ps や /proc/<pid>/cmdline）から読めます。共有マシンや cron で使うときは、自分だけが読める（モード 0600 の）ファイルに環境変数を書き、そこから読み込んでください。

mkdir -p -m 700 ~/.config/enecoq
install -m 600 /dev/null ~/.config/enecoq/env

作成した ~/.config/enecoq/env をエディターで開き、次の 2 行を書きます。

export ENECOQ_EMAIL='your@email.com'
export ENECOQ_PASSWORD='yourpassword'

. ~/.config/enecoq/env && enecoq-data-fetcher --period today --format console

出力形式

JSON

{
  "period": "month",
  "timestamp": "2024-01-15T10:30:00.123456+09:00",
  "usage": 250.5,
  "cost": 7515.0,
  "co2": 125.25
}

JSON には単位が含まれません。usage は kWh、cost は円（JPY）、co2 は kg です。値は期間の開始からの累計です。timestamp は取得した時刻で、実行環境のタイムゾーンのオフセットが付きます。

コンソール

==============================
enecoQ Data
==============================

Period: month
Timestamp: 2024-01-15 10:30:00

Power Usage: 250.5 kWh
Power Cost: 7515.0 JPY
CO2 Emission: 125.25 kg

==============================

ログ

ログは標準ではコンソールにだけ出力されます。--log-file を指定すると、DEBUG レベル以上のログがそのファイルにも記録されます。認証情報はどちらにも記録されません。

enecoq-data-fetcher --email your@email.com --password yourpassword --log-file logs/enecoq.log

設定ファイル

カレントディレクトリの config.yaml（または --config で指定したファイル）でデフォルト設定を変更できます。項目は config.yaml.example を参照してください。

log_level: INFO
log_file: logs/enecoq.log
timeout: 30
max_retries: 3

max_retries は、取得に失敗したときに最初の試行に追加でやり直す回数です（0 でやり直しなし）。--config で指定したファイルが存在しない場合や、値の型が正しくない場合、知らない項目がある場合はエラーになります。

コマンドライン引数と設定ファイルの両方で指定した場合は、コマンドライン引数が優先されます。

他システムとの連携例

cron での定期実行

毎時 42 分にデータを取得してファイルに保存する例です。多くの人が同じ時刻にアクセスすると enecoQ のサーバーに負荷がかかるので、42 は 1〜59 の好きな数字に変えてください。さらに 0〜59 秒のランダムな待機を入れています。$RANDOM は bash の機能なので、SHELL=/bin/bash を指定しています。認証情報は crontab に書かず、環境変数で認証情報を渡すで作成したモード 0600 のファイルから読み込みます。

crontab -e

SHELL=/bin/bash
42 * * * * . "$HOME/.config/enecoq/env" && sleep $((RANDOM \% 60)) && enecoq-data-fetcher --output /path/to/enecoq_data.json

Home Assistant

cron で保存した JSON ファイルを command_line センサーで読み込みます。スクレイピングは cron の 1 回だけで済み、3 つのセンサーは同じファイルを読みます。

# configuration.yaml
command_line:
  - sensor:
      name: "enecoQ Power Usage"
      command: "cat /config/data/enecoq_data.json"
      value_template: "{{ value_json.usage }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing
      icon: mdi:lightning-bolt
      scan_interval: 300
  - sensor:
      name: "enecoQ Power Cost"
      command: "cat /config/data/enecoq_data.json"
      value_template: "{{ value_json.cost }}"
      unit_of_measurement: "JPY"
      device_class: monetary
      state_class: total
      icon: mdi:cash
      scan_interval: 300
  - sensor:
      name: "enecoQ CO2 Emission"
      command: "cat /config/data/enecoq_data.json"
      value_template: "{{ value_json.co2 }}"
      unit_of_measurement: "kg"
      state_class: total_increasing
      icon: mdi:molecule-co2
      scan_interval: 300

monetary の device class には total しか使えないため、料金センサーだけ state_class が異なります。

Utility Meter で期間ごとの値を出す

このツールの値は累計なので、1 時間ごとや 1 日ごとの値は Utility Meter で計算します。次の例は 1 時間ごとの電力使用量、料金、CO2 排出量のセンサー（sensor.enecoq_power_usage_hourly など）を作ります。

# configuration.yaml
utility_meter:
  enecoq_power_usage_hourly:
    source: sensor.enecoq_power_usage
    cycle: hourly
  enecoq_power_cost_hourly:
    source: sensor.enecoq_power_cost
    cycle: hourly
  enecoq_co2_emission_hourly:
    source: sensor.enecoq_co2_emission
    cycle: hourly

日ごとの値が欲しい場合は、--period month で取得したデータを使い、cycle: daily にします。

開発

uv sync
uv run playwright install chromium
./tests/run_tests.sh
uv build

1 つのテストファイルだけを実行するときは PYTHONPATH=src uv run python tests/test_exporter.py のように実行します。テストの詳細は tests/README.md、コーディング規約やリリース手順は AGENTS.md にあります。

トラブルシューティング

Playwright のブラウザが見つからない

次のようなエラーが出たら、インストールの手順で Chromium をインストールしてください。

Executable doesn't exist at /root/.cache/ms-playwright/chromium_headless_shell-1194/chrome-linux/headless_shell

認証エラーが出る

メールアドレスとパスワードが正しいか、ブラウザから enecoQ に直接ログインできるかを確認してください。

データが取得できない

--log-level DEBUG を付けて実行し、詳細なログを確認してください。--log-file を指定すればログをファイルに残せます。enecoQ 自体が停止していないかも確認してください。