enecoq-data-fetcher 1.0.0

enecoQ power data fetcher - Fetch power usage, cost, and CO2 emission data from enecoQ web service

enecoQ Data Fetcher

enecoQ Web Service から電力使用量、電力使用料金、CO2排出量を取得するCLIツールです。

概要

enecoQは株式会社ファミリーネットジャパンが提供するCYBERHOMEサービス内の電力データ管理Webサービスです。このツールは、enecoQから電力データをプログラマティックに取得し、JSON形式やコンソール表示で出力します。

主な機能

• 電力使用量データの取得
• 電力使用料金データの取得
• CO2排出量データの取得
• 今日または今月のデータ取得
• JSON形式またはコンソール表示での出力

必要要件

• CYBERHOME（enecoQ）のアカウント
• Python 3.9以上
• uv（Pythonパッケージマネージャー）
• Playwright（ブラウザ自動化）

インストール

1. uvのインストール（初回のみ）

uvがインストールされていない場合は、以下のコマンドでインストールしてください：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# または Homebrew (macOS/Linux)
brew install uv

2. パッケージのインストール（初回のみ）

# リポジトリをクローン
git clone <repository-url>
cd enecoq-data-fetcher

# 仮想環境の作成と依存関係のインストール
uv sync

# Playwrightブラウザのインストール
uv run playwright install

使用方法

基本的な使い方

uv run enecoq-fetch --email [e-mail] --password yourpassword

コマンドライン引数

引数	説明	デフォルト値	必須
--email	CYBERHOME (enecoQ) のメールアドレス	-	✓
--password	CYBERHOME (enecoQ) のパスワード	-	✓
--period	データ取得期間（today または month）	month
--format	出力形式（json または console）	json
--output	JSON出力先ファイルパス	-
--log-level	ログレベル（DEBUG, INFO, WARNING, ERROR）	INFO

使用例

今月のデータをJSON形式で取得

uv run enecoq-fetch --email [e-mail] --password yourpassword --period month --format json

今日のデータをコンソールに表示

uv run enecoq-fetch --email [e-mail] --password yourpassword --period today --format console

JSON出力をファイルに保存

uv run enecoq-fetch --email [e-mail] --password yourpassword --output data/power_data.json

デバッグモードで実行

uv run enecoq-fetch --email [e-mail] --password yourpassword --log-level DEBUG

出力形式

JSON形式

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

注: JSON出力では単位情報は含まれません。単位は以下の通りです：

• usage: kWh（キロワット時）
• cost: JPY（日本円）
• co2: kg（キログラム）

コンソール形式

==============================
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

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

ログ

ログは以下の場所に出力されます：

• コンソール: INFOレベル以上
• ファイル: logs/enecoq.log（DEBUGレベル以上）

ログファイルには認証情報は記録されません。

高度な設定（オプション）

config.yaml ファイルを作成することで、デフォルト設定をカスタマイズできます：

log_level: INFO
log_file: logs/enecoq.log
timeout: 30
max_retries: 3
user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"

設定ファイルを使用する場合：

uv run enecoq-fetch --email [e-mail] --password yourpassword --config config.yaml

他システムとの連携例

cronでの定期実行

毎時42分にデータを取得してファイルに保存する例（負荷分散のため0〜60秒のランダム待機）：

# crontabを編集
crontab -e

# 以下を追加（プロジェクトディレクトリのパスを指定）
42 * * * * cd /path/to/enecoq-data-fetcher && sleep $((RANDOM \% 60)) && /path/to/uv run enecoq-fetch --email [e-mail] --password yourpassword --output /path/to/enecoq_data.json

注: 負荷分散のため、42を別の数字（59以下の任意の値）に変更することを推奨します。多くのユーザーが同じ時刻にアクセスするとサーバーに負荷がかかるため、0以外のランダムな時刻を選択してください。

Home Assistantとの連携

cronで定期的に保存したJSONファイルを読み込む方法：

# 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  # 5分ごとに更新
  - 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_increasing
      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

注: cronがデータを取得して /config/data/ に保存し、複数のセンサーがそのファイルを読むことで、スクレイピングの回数を1回で済ませます。

Utility Meter で差分を取得

このツールが返す値は累計値です。差分が必要な場合は、Utility Meter を使用してください。

累計値から時間ごとの使用量を計算する例：

# 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

これにより、以下のセンサーが作成されます：

• sensor.enecoq_power_usage_hourly: 1時間あたりの電力使用量（kWh）
• sensor.enecoq_power_cost_hourly: 1時間あたりの電力使用料金（JPY）
• sensor.enecoq_co2_emission_hourly: 1時間あたりのCO2排出量（kg）

同様の方法で --period month で取得したデータから日次センサーを作ることもできます。

累計値から日付ごとの使用量を計算する例：

# configuration.yaml
utility_meter:
  enecoq_power_usage_daily:
    source: sensor.enecoq_power_usage
    cycle: daily
  enecoq_power_cost_daily:
    source: sensor.enecoq_power_cost
    cycle: daily
  enecoq_co2_emission_daily:
    source: sensor.enecoq_co2_emission
    cycle: daily

これにより、以下のセンサーが作成されます：

• sensor.enecoq_power_usage_daily: 1日あたりの電力使用量（kWh）
• sensor.enecoq_power_cost_daily: 1日あたりの電力使用料金（JPY）
• sensor.enecoq_co2_emission_daily: 1日あたりのCO2排出量（kg）

開発

テストの実行

全テストの実行

# テストスクリプトを使用（推奨）
./tests/run_tests.sh

個別テストの実行

# PYTHONPATHを設定して実行
PYTHONPATH=src uv run python tests/test_exporter.py

詳細なテスト情報は tests/README.md を参照してください。

パッケージのビルド

uv build

トラブルシューティング

認証エラーが発生する

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

データが取得できない

• --log-level DEBUG オプションを使用して詳細なログを確認してください
• enecoQ Web Service が利用可能か確認してください