DELTA Pro 3 API 実装メモ｜Developer API × MQTT ブリッジ構成

Gaming-Hub の EcoFlow ダッシュボードは、自宅の DELTA Pro 3 と DELTA 3 1500 からライブ計測・発電ログ・充電計画を出しています。製品レビューではなく、API と実装のメモです。同じことをやりたいエンジニア向けに、うちの構成とハマりどころを書きます。

前提: 公式モバイル SDK は使っていません。Pro 3 は EcoFlow Developer API (REST)、1500 系は App Login + MQTT です。機種ごとに経路が違うので、最初から一本化しない方が楽でした。

全体像

スタックは WordPress (PHP) + Docker 上の Node ブリッジ + 共有キャッシュディレクトリです。

• WordPress — ダッシュボード UI、REST、WP-Cron、発電ログの積算
• Developer API クライアント — inc/ecoflow-api.php の Gaming_Hub_Ecoflow_Api
• ecoflow-bridge コンテナ — scripts/ecoflow-bridge-daemon.mjs が MQTT を張り続ける
• wp-content/ecoflow-cache/ — PHP と Node の IPC 用（git には入れない）

Browser → WordPress (PHP)
              ├─ GET  /iot-open/sign/device/quota/all   … Pro 3 ライブ
              ├─ PUT  /iot-open/sign/device/quota       … Pro 3 充電制御
              └─ read/write ecoflow-cache/*.json

ecoflow-bridge (Node) → App Login → MQTT over TLS
              └─ write {SN}.json, bridge-status.json
              └─ read  bridge-command.json（1500 への SET）

PHP と Node は HTTP では話しません。ファイルと Docker volume で繋いでいます。小規模ならこれで十分です。

Pro 3 — Developer API

Pro 3 は EcoFlow 開発者ポータルで発行した Access Key / Secret Key とデバイス SN で動きます。Customizer か .env に入れます。

• ECOFLOW_ACCESS_KEY / ECOFLOW_SECRET_KEY
• ECOFLOW_DEVICE_SN — Pro 3 のシリアル
• ECOFLOW_API_REGION — 日本アカウントは Asia (a → api-a.ecoflow.com)

読み取りの中心は GET /iot-open/sign/device/quota/all?sn=… です。返るのはフラットな quota マップで、キー名が機種・FW で微妙に違います。うちでは gaming_hub_ecoflow_quota_value() が複数キーをフォールバックで試します。

ダッシュボード表示で特に使っているのは次のあたりです。

• powInSumW / powOutSumW — 合計入出力 [W]
• bmsChgDsgState — 0=待機, 1=放電, 2=充電（Pro 3 の状態判定の軸）
• ハイボルト系 — mppt.inWatts など PV 入力
• AC 入出力 — plugInInfoAcInWatts / AC out 系

状態ラベルはワット数だけに頼らず、bmsChgDsgState を優先しています。待機中でも数十 W 動くので、閾値だけだと「充電中／放電中」がブレます。

書き込み（充電制御）

Pro 3 への制御は Developer API の PUT /iot-open/sign/device/quota です。AI PLAN を承認すると、WP-Cron が 10 分ごとに計画を見直し、充電コマンドが変わったときだけ API を叩きます。

主に触っているパラメータ:

• cfgPlugInInfoAcInChgPowMax — グリッド AC 充電上限 [W]（うちは 0 または 1,000 W）
• Energy Backup 予備 SOC — 充電枠の前後で reserve を切り替え

実装は inc/ecoflow-schedule.php → Gaming_Hub_Ecoflow_Api::set_ac_charge_power() です。毎秒 PUT しないのがポイント。EcoFlow 側も、こちらも、どちらも余計なコマンドは嫌がります。

Delta 3 1500 — App Login + MQTT

1500（シリアル D361 / D362 / D381 系）は Developer API の quota が空 です。公式の Developer ドキュメント上も、Delta 3 ラインは App 経由が前提です。

なので Node ブリッジを別コンテナで常駐させています。

docker compose up -d ecoflow-bridge

必要なのは App Login 用メール／パスワード（ECOFLOW_APP_EMAIL, ECOFLOW_APP_PASSWORD）と 1500 の SN（ECOFLOW_DEVICE_SN_2）です。WordPress は Customizer 保存時に bridge-config.json を同期します。

MQTT ブリッジの流れ

1. ecoflow-app-client.mjs が App Login API でトークン取得
2. certification レスポンスから MQTT ブローカー (mqtts://) に接続
3. quota トピックを subscribe し、{SN}.json に最新 quota を書く
4. bridge-status.json に接続状態・エラーを書く（TTL 90 秒で「ライブ」判定）

Client ID はユーザー ID から SHA-256 で安定生成しています。毎回ランダムにすると、EcoFlow 側の 1 日 10 client ID 制限 にすぐ当たります（ログに server is too busy が出たらまず疑う）。

1500 への書き込み

1500 の AC 充電 SET は MQTT 経由です。PHP は bridge-command.json にコマンドを書き、デーモンが拾って publish します。結果は bridge-command-result.json。REST で Node を呼ばないので、デーモンが落ちても WordPress は生き残ります。

PHP 側の quota 正規化

gaming_hub_fetch_ecoflow_device_status() の優先順位はこうです。

1. MQTT ブリッジキャッシュ（1500 / app-only 機種）
2. Developer API quota/all（Pro 3）
3. 1500 で API が空 → ブリッジ待ちメッセージ

正規化後の共通フィールド（gaming_hub_parse_ecoflow_quota()）:

• battery — SOC [%]
• input / output — 合計 W
• solar — HV + LV の合算（機種で内訳キーが違う）
• charge_state — 表示用ラベル（グリッド充電中 / 放電中 / ソーラー充電中 …）

ステータスは transient で 5 秒キャッシュ。ページ表示のたびに quota/all を叩かないようにしています。

発電ログ（energy）との接続

ライブ quota とは別に、inc/ecoflow-energy.php が時間別・日別 kWh を積算します。入力は Pro + 1500 の合算、節約額は「その時間に AC 出力していた分 × LOOOP 単価 − グリッド買電」を日次で出しています。API 実装の話としては、MQTT が落ちている時間帯は 1500 側の入力が欠ける ので、ログ品質もブリッジ死活に依存します。

グラフは /tag/ecoflow/#energy。実運用の数字は 実測レビュー記事 よりログ優先で見てください。

ハマったところ（再現用メモ）

• API Region — 日本は a。US デフォルトのままだと MQTT 認証で not authorized になりがち
• Google ログインのみ — MQTT は Google OAuth そのものは使えない。アプリ内で「ログインパスワード」を別途設定する必要あり
• Delta 3 は Developer API 非対応 — Pro 3 だけ Developer API 、1500 は MQTT、と割り切る
• quota キーのブレ — pdStatus.foo と pd.foo 等。正規化レイヤを挟まないと UI が壊れる
• bridge-status.json は secret 扱い — userId 等が入る。gitignore 済み
• 制御は diff だけ送る — 計画ウィンドウが変わったときだけ PUT / MQTT publish

ディレクトリ早見表

wp-content/themes/gaming-hub/
  inc/ecoflow-api.php      … Developer API クライアント
  inc/ecoflow-app.php        … ブリッジキャッシュ読み書き
  inc/ecoflow-schedule.php   … 充電計画の承認・適用
  inc/ecoflow-energy.php     … 発電ログ積算
  scripts/ecoflow-app-client.mjs
  scripts/ecoflow-bridge-daemon.mjs

wp-content/ecoflow-cache/    … 実行時生成（volume マウント）
  bridge-config.json
  bridge-status.json
  bridge-command.json
  {DEVICE_SN}.json

まとめ

うちの構成は Pro 3 = Developer API で読む・書く、1500 = MQTT ブリッジで読む・ファイル IPC で書く の二系統です。無理に一つの SDK に寄せず、quota 正規化とキャッシュ TTL で UI を安定させています。

ライブ状態は EcoFlow ダッシュボード、実装の参照はテーマ inc/ecoflow*.php と scripts/ecoflow-*.mjs を見てください。製品選びや節約額の話は DELTA Pro 3 実測レビュー の方が向いています。

同種の実装をご依頼の方

関連リンク

• EcoFlow ダッシュボード
• 発電ログ
• DELTA Pro 3 実測レビュー
• ランサーズ（Web/API 実装）