How tolwi/hassio-ecoflow-cloud works
Project Type and Purpose
• This is a Home Assistant custom integration (Python package under custom_components/ecoflow_cloud) that connects Home Assistant to the EcoFlow Cloud via MQTT and HTTP APIs.
• Purpose: monitor and control EcoFlow devices (Delta, River, Glacier, PowerStream, etc.) by subscribing to an MQTT broker and/or calling public/private REST APIs, then expose device attributes as HA entities (sensors, switches, numbers, selects, buttons).
File Structure
Top-level directories of interest:
• .devcontainer, .github – dev/test tooling, CI.
• custom_components/ecoflow_cloud – the core integration:
– api/ (ecoflow_mqtt.py, private_api.py, public_api.py, message.py)
– devices/internal (Protobuf definitions, device‐specific parsers)
– devices/public (device classes for public API responses)
– registry.py & data_holder.py – in-memory device/state registry
– config_flow.py – user-facing setup
– sensor.py, switch.py, number.py, select.py, button.py – HA platform entry points
– diagnostics.py, recorder.py – HA diagnostics & data persistence
– manifest.json, translations/ – metadata
• docs/ – human-readable documentation (integration.md, device docs)
README for Additional Insights
• Integration uses MQTT broker mqtt.ecoflow.com to receive device telemetry.
• Falls back (or parallely uses) REST-based private_api & public_api for control & state retrieval.
• Supports dozens of device models, each with its own sensor/switch definitions.
Main Components & Their Relationships
[ Home Assistant Core ]
↓ loads
[ ecoflow_cloud Integration ]
• config_flow.py
• manifest.json / translations
• startup orchestration
↓
┌────────────────────────────────────────────┐
│ API Layer │
│ ┌───────────────┐ ┌───────────────┐ │
│ │ MQTT Client │◀─┤ecoflow_mqtt.py│ │
│ └───────────────┘ └───────────────┘ │
│ │ ▲ │
│ │ subscribe │ publish / subscribe│
│ ▼ │ │
│ ┌───────────────────────────────────────┐ │
│ │ Private API (HTTP/REST) │ │
│ │ public_api.py & private_api.py │ │
│ └───────────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ [ EcoFlow Cloud Services ] │
│ – mqtt.ecoflow.com (Broker) │
│ – ecoflow.com REST endpoints │
└────────────────────────────────────────────┘
↓ decode messages via Protobuf │
[ Domain / Device Layer ] │
• data_holder.py (state aggregation) │
• devices/internal/*.py (Protobuf parsers)│
• devices/public/*.py (API wrappers) │
• registry.py (map device → HA entities) │
↓
[ HA Platforms (entity factories) ]
• sensor.py → SensorEntity
• switch.py → SwitchEntity
• number.py → NumberEntity
• select.py → SelectEntity
• button.py → ButtonEntity
• recorder.py / diagnostics.py
↓
[ Home Assistant UI / State Machine ]
Architectural Patterns & Principles
• Layered architecture:
– API Layer (MQTT + HTTP)
– Domain / Model Layer (device classes, data holder, registry)
– Platform Layer (HA entity adapters)
• Observer/Event pattern: MQTT messages or API callbacks trigger state updates.
• Protobuf code generation (proto files → _pb2.py) to decode binary messages.