Skip to content

Implement 2nd generation Power Hub features and documentation updates - #978

Open
du5 wants to merge 21 commits into
tolwi:mainfrom
du5:claude/magical-hawking-fxebly
Open

du5 wants to merge 21 commits into
tolwi:mainfrom
du5:claude/magical-hawking-fxebly

Conversation

@du5

@du5 du5 commented Nov 14, 2026

Copy link
Copy Markdown

This pull request introduces comprehensive support for EcoFlow Power Kits (particularly the 2nd generation Power Hub) and improves handling of multi-module device discovery and configuration. It updates documentation, enhances the configuration flow to robustly discover and manage sub-devices (modules), and adds support for new Home Assistant entity types. The changes also ensure that missing parent devices do not block configuration loading, and that ignored modules are tracked.

Power Kits support and module discovery:

  • Added detailed documentation and entity lists for Power Kits, including instructions for 1st and 2nd generation Power Hub integration and a new reference to docs/power_kits_2nd_gen.md in README.md. [1] [2]
  • Implemented robust sub-device (module) discovery for Power Kits, including a new method to fetch latestQuotas via a short-lived MQTT session for module enumeration in private_api.py.

Configuration flow and device management:

  • Enhanced the configuration flow to support module discovery from both public and private API responses, including a new utility to parse module information from quota responses and track added device serials. [1] [2] [3]
  • Added CONF_IGNORED_MODULES to track modules removed via the remove-device flow, ensuring ignored modules are not rediscovered. [1] [2]

Device loading and error handling:

  • Improved device loading in extract_devices to gracefully handle sub-devices whose parent is missing, logging a warning and skipping them instead of failing the entire entry.

Home Assistant integration:

  • Registered the Platform.TEXT entity type for Home Assistant, enabling support for text entities (such as naming circuits).

Internal and dependency updates:

  • Added necessary imports and refactoring in private_api.py to support threading, asyncio, and MQTT for module discovery. [1] [2]

These changes collectively enable robust, user-friendly integration of EcoFlow Power Kits and their modules into Home Assistant, with improved error handling and configuration flexibility.

claude added 21 commits October 31, 2026 07:20
The 2nd generation 5 kVA Power Hub is listed by the developer platform
without a product name and every data request for it fails with error
1006, while the app's MQTT stream carries all of its modules (bbcin,
bbcout, iclow, bp5000, kitscc, lddc, ichigh, ldac, wireless) as JSON
wrapped twice. Add a POWER_KITS device type for private_api that reuses
the public Power Kits entities, routes each module's heartbeat and the
latestQuotas reply to its own sub device, and keeps the main battery's
totals and the wireless module on the hub device.

The config flow now discovers sub devices in the reconfigure flow too,
and asks a private-API hub for latestQuotas over a short MQTT session
to find its modules. quota_all sends one latestQuotas per topic instead
of one per sub device.

Commands reuse the 1st generation payloads and are untested on a 2nd
generation hub.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
…power unit

Built from a 5 kVA Power Hub's full latestQuotas reply and a minute of
heartbeats:

- The 2nd generation AC/DC panel (EF-PK-005-2) reports its AC board as
  ldac and its DC board as lddc under one serial; sub devices are listed
  by serial, so one board was dropped. Modules sharing a serial now get
  "<serial>#<type>" list keys while data routing, naming and commands
  keep using the real serial.
- The hub device takes the system totals from the flat bmsTotal quota
  entry and from mainBP heartbeats: total current (signed 16-bit in
  0.1 A), remaining time, charge and discharge limits, generator start
  and stop levels, plus the gps module.
- New entities for what the 2nd generation reports: battery health and
  cumulative energy, inverter apparent power, charge power and effective
  settings (appCfg), DC circuits 13 to 16 and the L1/L2 AC buses.
- Switches whose state is reported by another module than the one that
  takes the command (AC Output, AC Charging, charge current, Main DC
  Output) now live on the reporting module and address the sibling in
  the command; the DC panel has 12 relay switches.
- pv1InWatts/pv2InWatts are reported in W, not 0.1 W (upstream issue
  tolwi#911); this also applies to the public
  Power Kits device.

Commands remain unverified on 2nd generation hardware.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
…ion notes

Home Assistant devices of the private-API Power Kits now carry EcoFlow's
product names as their model (智控五合一充逆一体机 / Power Hub and its five
functions, 磷酸铁锂电池 / LFP Battery with its capacity, the two boards of
the 交直流智能配电盘 / AC/DC Smart Distribution Panel) and show the printed
serial even when the sub device key carries a "#<type>" suffix. A device
can set model_name; the entity base class falls back to the device type.

docs/power_kits_2nd_gen.md collects the components, specifications,
module to device map, serial prefixes, units and known limits of the
2nd generation 5 kVA kit, with the source of each figure.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
bp5000 is the 磷酸铁锂电池5度电 (LFP Battery 5kWh, 51.2 V / 100 Ah) and
bp2000 the 磷酸铁锂电池2度电 (LFP Battery 2kWh, 51.2 V / 40 Ah), the only
two packs offered for the Power Kits; any other bp type keeps a generic
name. The 2nd generation notes get both packs' specifications.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
… remove

Review follow-ups on the Power Kits sub devices:

- Removing a hub takes its modules with it (entry data, options and the
  registry entries). A module whose parent is gone no longer raises in
  extract_devices and keeps the whole entry from loading; it is skipped
  with a warning instead.
- The remove-device step no longer runs module discovery, which added
  the module just removed straight back. A removed module is recorded
  on its parent (ignored_modules) and left out of later discoveries.
- Discovery now runs for every multi-module device on add and finish,
  merging modules that are not configured yet, so a battery or panel
  that was offline when the hub was added appears on the next
  reconfiguration. Configured sub devices keep their names and options.
- A module missing from a latestQuotas reply no longer counts as fresh
  data: its status and readings are left alone instead of being marked
  online with empty params.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
…eration hub

Captured from the app's set topic while switching things on a 5 kVA hub:

- Main DC output goes to bbcout with module type 15363 (dischgParaSet,
  swSta), not to bbcin with 15362 as documented for the 1st generation.
  A Beeper switch uses the same message (beepEn).
- DC input charging (alternator / generator) toggles chgPause through
  chgParaSet on bbcin.
- The two solar ports toggle mpptt1 / mpptt2 through pvSwitch on kitscc.
- Discharge lower and charge upper limits are socLowerLimit and
  socUpperLimit without a module serial; sliders on the hub device.
- The DC panel's chSwitch uses module type 15368, and all 16 circuits
  answer to it; switches 13 to 16 read dcChRelayV2 and address channels
  12 to 15 (BitMaskEnableEntity gains a command_index).
- AC charging (acChgDisa through dischgIcParaSet on iclow) matches the
  1st generation documentation.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
The hub's ALT IN n / PV IN n ports (port 1 on bbcin, ports 2 and 3 on
kitscc) can be set to auto, alternator or solar. The app sends
setPortType through chgParaSet for port 1 and setPort1Type /
setPort2Type through pvSwitch for ports 2 and 3, with 0 auto, 1
alternator, 2 solar. Port 1 also takes the alternator type
(chgDsgAltmodeSet, alternatorMode 0 generic, 1 48 V excited; a 48 V
excited alternator disables reverse discharge on that port). All four
become select entities, and the charging switches of the three ports
are named by port number like the app.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
…s them

The app sends acCurrMaxSet (charging) and passByMaxCurr (input) together
in one dischgIcParaSet to iclow, 2 to 20 A and 2 to 50 A on a 230 V hub,
and never lets the charging current exceed the input current. The ichigh
device gets both sliders; each sends the other value from the current
appCfg and caps the charging current at the input limit. The two
diagnostic sensors for these values are replaced by the sliders.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
…per confirmed

Captured from the app: grid priority (passByModeEn 1 grid, 2 battery)
is set through dsgIcParaSet on iclow with invNoLoadPwr and setInvTag
left unchanged, not on ichigh as the 1st generation code does; the
switch stays on the ichigh device that reports the state. The beeper
toggles beepEn exactly as implemented. The main DC output voltage is
volTag (0/1, read back as cfgVolTag); it becomes a select that is
disabled by default because 24 V can damage 12 V loads.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
Model EF-PK-O05-3, port ratings, supported devices, the one-dock-per-hub-port
topology (docks cannot be chained), firmware and app notes; confirms the hub
model EF-PK-H05-1 and lists the battery models EFM100-BP / EFM100-BPB.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
… Insight 2

The owner confirmed the console is the bundled display; Power Insight 2 was
taken from a retailer page and is not part of this system. Its official
Chinese name and specs are left to be filled in from the manual.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
Read the hub, console, panel, Power Dock, Power Link and battery manuals the
owner provided. The hub spec table now comes from the hub manual (48 V output
55 A / 3168 W, 12/24 V output 1360 / 1584 W, 15.7 kg, battery port limits,
EF BUS, total 8752 W) with a section on charge priority, bypass, grid
priority, X-Fusion and idle charging. The console is the 智触监控屏 EFM100-MT
(7-inch, EF BUS powered); the Power Link is the 信息集成盒 EF-PK-O05-1; the
panel model is EF-PK-O05-2. Battery specs come from the official battery
manual. The unknown-modules note and known limits are updated accordingly.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
The 2nd generation hub documents no X-Boost mode (only X-Fusion and the
10000 VA peak that the Chinese product page files under 升维驱动); the
5200 W X-Boost figure belongs to the 1st generation hub. A DELTA 2 Max joins
the system only through its smart extra battery on the Power Dock's
MULTI CONNECTION port with the Smart Generator Adapter.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
volTag 0 is 12 V and 1 is 24 V, captured while switching the main DC output
in the app; the 48 V option of the app is noted as not captured yet.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
… voltage option

The main DC output only offers 12 V and 24 V; the 48V tab shows the hub's
48 V DC OUT port (battery bus voltage for third-party loads) with power and
status only.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
… off by default

The DC and AC boards of the distribution panel answer getDcAllAlias /
getAcAllAlias with the names the owner gave the circuits in the app. The
private client asks once after connecting, the boards' devices also pick up
every later reply, and the circuit sensors and switches rename themselves
(entity ids keep the default titles). The AC output and grid priority
switches are disabled by default: toggling grid priority remotely cut the AC
output and with it the hub's uplink; recovery needed the hub's AC button.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
Documents the alias requests and how entities follow the app's circuit
names, the two switches now disabled by default and why, that the app has
no X-Boost switch, that this system has no Power Link, and that the
alternator current and idle charging settings are not shown by the app on a
home system without an alternator.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
Each circuit of the DC and AC boards gets a text entity holding the name the
app shows; writing it sends setDcChAlias / setAcChAlias (both captured from
the app) with the circuit's icon kept. A rename made in the app is seen on
the set topic and applied at once. Adds the text platform, the docs
generator's text section and the icon numbers to the notes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
The app takes 24 letters or digits, or 8 Chinese characters: 24 bytes of
UTF-8. Longer names are rejected with a service validation error.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSsPaZYtMrC9vzT5hHeSRb
Copilot AI balanced review requested due to automatic review settings November 14, 2026 04:53

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Discovery can overwrite sibling devices or restore ignored boards, while removing iclow can misroute AC control commands to ichigh.

2 open issues
What changed in this PR

This PR adds second-generation Power Hub support to the EcoFlow Home Assistant integration, including module discovery, circuit controls and naming, and supporting documentation.

Changes:

  • Adds private-API Power Kits devices, telemetry, controls, and circuit-name text entities.
  • Extends module discovery and removal handling, including ignored modules and missing-parent recovery.
  • Documents supported hardware, commands, entities, and operational limitations.
File Description
README.md Adds setup guidance and the Power Kits entity summary.
docs/​summary.md Lists Power Kits entities by module.
docs/​power_kits_2nd_gen.md Documents hardware, protocol details, and limitations.
docs/​integration.md Links the new Power Kits documentation.
docs/​gen.py Generates hub/module sections and text-entity documentation.
docs/​devices/​POWER_KITS.md Provides detailed entity and command references.
docs/​device_management.md Explains module removal and rediscovery.
custom_components/​ecoflow_cloud/​text.py Sets up Home Assistant text entities.
custom_components/​ecoflow_cloud/​entities/​__init__.py Displays module models and real serial numbers.
custom_components/​ecoflow_cloud/​devices/​registry.py Registers private-API Power Kits support.
custom_components/​ecoflow_cloud/​devices/​public/​powerkit.py Extends bitmask controls and module serial handling.
custom_components/​ecoflow_cloud/​devices/​internal/​powerkit.py Implements private-API telemetry, controls, and circuit naming.
custom_components/​ecoflow_cloud/​devices/​internal/​powerkit_data.py Parses module payloads and circuit-alias messages.
custom_components/​ecoflow_cloud/​devices/​__init__.py Adds text-entity and startup-command hooks.
custom_components/​ecoflow_cloud/​config_flow.py Extends module discovery and removal tracking.
custom_components/​ecoflow_cloud/​api/​private_api.py Fetches discovery quotas over MQTT and requests startup settings.
custom_components/​ecoflow_cloud/​__init__.py Registers text support and skips orphaned modules.

Review effort: Balanced

Comment on lines +188 to +192
key = sub_device_sn
if serial_count[sub_device_sn] > 1:
key = f"{sub_device_sn}{SN_TYPE_SEPARATOR}{sub_device_type}"
if (sub_device_type, sub_device_sn) in configured or key in ignored or sub_device_sn in ignored:
continue
Comment on lines +505 to +506
_LOGGER.warning("No %s module found for %s; sending the command to %s", module_type, parent.sn, self.module_sn)
return self.module_sn
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants