How cjaliaga/home-assistant-aquarea works
Project type and purpose
• This is a Home Assistant custom integration (“aquarea”) that plugs into Home Assistant Core.
• It provides an interface to Panasonic Aquarea Smart Cloud devices using the third-party Python library aioaquarea.
• The goal is to surface heat pump zones, sensors, switches, and climate controls as Home Assistant entities.
File structure
• Top-level folders:
• .github for CI/workflow definitions (HACS, hassfest, releases).
• custom_components/aquarea which contains the integration code.
• Within custom_components/aquarea:
• manifest.json and config_flow.py define metadata and the setup UI flow.
• coordinator.py implements Home Assistant’s DataUpdateCoordinator pattern.
• Multiple platform modules (climate.py, sensor.py, switch.py, binary_sensor.py, button.py, select.py, water_heater.py) each exposing one or more Entity classes.
• const.py for common constants, strings.json and translations/*.json for i18n.
• hacs.json indicates HACS compatibility.
README for additional insights
• Confirms the use of aioaquarea to perform HTTP-based cloud API calls.
• Describes supported entities: climate, water heater, sensors, energy, mode selectors, diagnostic sensors, etc.
• Explains the authentication flow and single-connection limitation of the Panasonic cloud.
Main components
a. Home Assistant Core
b. Aquarea Integration (custom_components/aquarea)
• Config Flow (user authentication setup)
• DataUpdateCoordinator (central polling/refresh mechanism)
• Entity platforms (climate, sensor, switch, etc.)
c. aioaquarea API client library
d. Panasonic Aquarea Smart Cloud (external service)
e. Home Assistant UI / State Machine (where entities appear)
Relationships and data flows
• User interacts with the Home Assistant UI to configure the integration (Config Flow → Home Assistant Core → Integration).
• Config Flow hands credentials to the API client and instantiates the DataUpdateCoordinator.
• The Coordinator schedules periodic fetches via aioaquarea to the Panasonic cloud.
• The API client makes HTTP(S) calls, returns JSON data.
• Coordinator parses the data, notifies all registered Entity instances.
• Each Entity (climate, sensor, etc.) updates its state in Home Assistant’s state machine and renders in the UI.
• When the user sends a command (e.g., set temperature), the Entity calls the Coordinator/API client, which issues a write call to the cloud.
Architectural patterns and design principles
• Layered architecture:
• Presentation/UI layer (Home Assistant frontend)
• Integration layer (Config Flow + Coordinator + Platforms)
• API client layer (aioaquarea)
• External system (Panasonic cloud)
• Observer pattern via DataUpdateCoordinator: Entities subscribe to data updates.
• Single source of truth: Coordinator centralizes polling and caching.
• Separation of concerns: each platform file only implements a specific entity type.
Technologies, frameworks, libraries
• Python 3.x, Home Assistant Integration API
• aioaquarea (async HTTP client for Panasonic cloud)
• Home Assistant DataUpdateCoordinator
• JSON for configuration and translations
• HACS for distribution
Final advice
• Every key part: Config Flow, Coordinator, Platforms, API client, cloud service.
• DataUpdateCoordinator pattern, since it’s central to how data moves.
• Use annotation or footnotes to note the single-connection limitation and retry logic.
• Review the manifest.json for any additional dependencies you might want to call out.