Add Home Assistant HACS integration for MPWiK Wrocław water consumption monitoring

[Copilot]

Creates a complete HACS integration to monitor water consumption from MPWiK Wrocław e-BOK system in Home Assistant, while preserving standalone CLI functionality.

Integration Structure

• Config Flow: UI-based setup with credential validation via remote Selenium
• Coordinator: 12h polling interval + random 0-30min jitter to distribute load
• Sensors: Daily/hourly consumption (measurement), total meter reading (total_increasing), last reading timestamp
• Translations: Full PL/EN support (Polish primary market)

Architecture

Home Assistant → custom_components/mpwik_wroclaw → Selenium Chrome Add-on → MPWiK API

Reuses existing mpwik_selenium.py via dynamic import, connects to external Selenium WebDriver (not bundled).

Key Files

custom_components/mpwik_wroclaw/
├── __init__.py          # Entry point, platform forwarding
├── manifest.json        # Domain metadata, selenium==4.15.2 requirement
├── config_flow.py       # UI config with remote WebDriver validation
├── coordinator.py       # DataUpdateCoordinator with random interval offset
├── sensor.py            # 4 sensor entities (CoordinatorEntity pattern)
├── const.py             # Constants, 12h base interval
└── translations/        # PL/EN strings for config flow

Configuration Example

# Via UI only - no YAML config
# Required: login, password, selenium_host, punkt_sieci
# Default selenium_host: 5f203b37-selenium-standalone-chrome

Changes to Existing Code

• README.md: Added HACS section with architecture diagram, preserved standalone usage
• .gitignore: Allowed custom_components/**/*.json and hacs.json

Standalone script behavior unchanged. Integration follows HA 2024.1+ patterns with async/await throughout.

Original prompt

Create a Home Assistant HACS integration for MPWiK Wrocław water consumption monitoring.

Requirements:

1. Create HACS Integration Structure

Create the following directory structure:

custom_components/mpwik_wroclaw/
├── __init__.py
├── manifest.json
├── config_flow.py
├── const.py
├── coordinator.py
├── sensor.py
├── strings.json
└── translations/
    └── en.json

2. Integration Features:

• Config flow with UI configuration for:
  • Login (podmiot ID)
  • Password
  • Selenium host (default: "5f203b37-selenium-standalone-chrome")
  • Punkt Sieci (network point ID)
• Use the existing mpwik_selenium.py module from the repository
• Connect to remote Selenium WebDriver (not bundled)
• Create sensors for:
  • Daily water consumption
  • Hourly water consumption (latest reading)
  • Total consumption
• Update data every 12 hours (MPWiK updates daily)
• Support for multiple meters (punkty sieci)

3. Files to Create:

manifest.json:

{
  "domain": "mpwik_wroclaw",
  "name": "MPWiK Wrocław",
  "version": "0.1.0",
  "codeowners": ["@neutrinus"],
  "config_flow": true,
  "documentation": "https://github.com/neutrinus/mpwik-wroclaw-client",
  "issue_tracker": "https://github.com/neutrinus/mpwik-wroclaw-client/issues",
  "iot_class": "cloud_polling",
  "requirements": ["selenium==4.15.2"],
  "dependencies": []
}

const.py:
Define constants:

• DOMAIN = "mpwik_wroclaw"
• CONF_SELENIUM_HOST = "selenium_host"
• CONF_PUNKT_SIECI = "punkt_sieci"
• DEFAULT_SELENIUM_HOST = "5f203b37-selenium-standalone-chrome"
• DEFAULT_SCAN_INTERVAL = timedelta(hours=12)

config_flow.py:

• Implement ConfigFlow with async_step_user
• Validate login by connecting to Selenium and testing MPWiK login
• Handle errors: cannot_connect, invalid_auth
• Schema with login, password, selenium_host (with default), punkt_sieci
• Use existing mpwik_selenium.py for validation

coordinator.py:

• DataUpdateCoordinator that fetches data every 12 hours
• Use mpwik_selenium.py with remote Selenium WebDriver
• Handle authentication and data fetching
• Parse response and return structured data

sensor.py:

• Create sensors for:
  • Daily consumption (state_class: measurement, device_class: water)
  • Total consumption (state_class: total_increasing, device_class: water)
  • Last reading timestamp
• Use coordinator for data updates

init.py:

• Setup integration
• Create coordinator
• Forward setup to sensor platform
• Handle unload

strings.json and translations/en.json:

• UI strings for config flow
• Error messages
• Sensor names

4. Create hacs.json:

{
  "name": "MPWiK Wrocław",
  "render_readme": true,
  "domains": ["sensor"]
}

5. Update README.md:

Add a new section "Home Assistant Integration (HACS)" with:

• ASCII art diagram showing the architecture (Selenium Add-on + HACS Integration)
• Installation instructions:
  1. Install Selenium Standalone Chrome add-on
  2. Install via HACS
  3. Configure through UI
• Link to Selenium add-on: https://github.com/jaredhobbs/ha-addons
• Configuration example
• Sensor descriptions

6. Technical Requirements:

• Use async/await patterns
• Import mpwik_selenium module from the existing codebase
• Connect to Selenium using webdriver.Remote with selenium_host
• Handle ConfigEntryAuthFailed for auth errors
• Proper error handling and logging
• Follow Home Assistant integration best practices
• Code should be compatible with Home Assistant 2024.1+

7. Integration Architecture:

[HA Core] 
   ↓
[HACS Integration custom_components/mpwik_wroclaw/] 
   ↓ (selenium==4.15.2, connects via HTTP)
[Selenium Standalone Chrome Add-on]
   ↓ (runs Chrome browser)
[MPWiK Website]

The integration should reuse as much as possible from the existing mpwik_selenium.py file, adapting it to work with async Home Assistant patterns and remote WebDriver connection.

Create all necessary files for a complete, working HACS integration following the Rocky Mountain Power pattern found at jaredhobbs/rocky-mountain-power.

This pull request was created as a result of the following prompt from Copilot chat.

Create a Home Assistant HACS integration for MPWiK Wrocław water consumption monitoring.

Requirements:

1. Create HACS Integration Structure

Create the following directory structure:

custom_components/mpwik_wroclaw/
├── __init__.py
├── manifest.json
├── config_flow.py
├── const.py
├── coordinator.py
├── sensor.py
├── strings.json
└── translations/
    └── en.json

2. Integration Features:

• Config flow with UI configuration for:
  • Login (podmiot ID)
  • Password
  • Selenium host (default: "5f203b37-selenium-standalone-chrome")
  • Punkt Sieci (network point ID)
• Use the existing mpwik_selenium.py module from the repository
• Connect to remote Selenium WebDriver (not bundled)
• Create sensors for:
  • Daily water consumption
  • Hourly water consumption (latest reading)
  • Total consumption
• Update data every 12 hours (MPWiK updates daily)
• Support for multiple meters (punkty sieci)

3. Files to Create:

manifest.json:

{
  "domain": "mpwik_wroclaw",
  "name": "MPWiK Wrocław",
  "version": "0.1.0",
  "codeowners": ["@neutrinus"],
  "config_flow": true,
  "documentation": "https://github.com/neutrinus/mpwik-wroclaw-client",
  "issue_tracker": "https://github.com/neutrinus/mpwik-wroclaw-client/issues",
  "iot_class": "cloud_polling",
  "requirements": ["selenium==4.15.2"],
  "dependencies": []
}

const.py:
Define constants:

• DOMAIN = "mpwik_wroclaw"
• CONF_SELENIUM_HOST = "selenium_host"
• CONF_PUNKT_SIECI = "punkt_sieci"
• DEFAULT_SELENIUM_HOST = "5f203b37-selenium-standalone-chrome"
• DEFAULT_SCAN_INTERVAL = timedelta(hours=12)

config_flow.py:

• Implement ConfigFlow with async_step_user
• Validate login by connecting to Selenium and testing MPWiK login
• Handle errors: cannot_connect, invalid_auth
• Schema with login, password, selenium_host (with default), punkt_sieci
• Use existing mpwik_selenium.py for validation

coordinator.py:

• DataUpdateCoordinator that fetches data every 12 hours
• Use mpwik_selenium.py with remote Selenium WebDriver
• Handle authentication and data fetching
• Parse response and return structured data

sensor.py:

• Create sensors for:
  • Daily consumption (state_class: measurement, device_class: water)
  • Total consumption (state_class: total_increasing, device_class: water)
  • Last reading timestamp
• Use coordinator for data updates

init.py:

• Setup integration
• Create coordinator
• Forward setup to sensor platform
• Handle unload

strings.json and translations/en.json:

• UI strings for config flow
• Error messages
• Sensor names

4. Create hacs.json:

{
  "name": "MPWiK Wrocław",
  "render_readme": true,
  "domains": ["sensor"]
}

5. Update README.md:

Add a new section "Home Assistant Integration (HACS)" with:

• ASCII art diagram showing the architecture (Selenium Add-on + HACS Integration)
• Installation instructions:
  1. Install Selenium Standalone Chrome add-on
  2. Install via HACS
  3. Configure through UI
• Link to Selenium add-on: https://github.com/jaredhobbs/ha-addons
• Configuration example
• Sensor descriptions

6. Technical Requirements:

• Use async/await patterns
• Import mpwik_selenium module from the existing codebase
• Connect to Selenium using webdriver.Remote with selenium_host
• Handle ConfigEntryAuthFailed for auth errors
• Proper error handling and logging
• Follow Home Assistant integration best practices
• Code should be compatible with Home Assistant 2024.1+

7. Integration Architecture:

[HA Core] 
   ↓
[HACS Integration custom_components/mpwik_wroclaw/] 
   ↓ (selenium==4.15.2, connects via HTTP)
[Selenium Standalone Chrome Add-on]
   ↓ (runs Chrome browser)
[MPWiK Website]

The integration should reuse as much as possible from the existing mpwik_selenium.py file, adapting it to work with async Home Assistant patterns and remote WebDriver connection.

Create all necessary files for a complete, working HACS integration following the Rocky Mountain Power pattern found at jaredhobbs/rocky-mountain-power.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.