AC Heating XCC Heat Pump Controller Integration

Home Assistant integration for AC Heating XCC heat pump controllers with photovoltaic integration. Monitor and control your heat pump system directly from Home Assistant with automatic entity discovery and bilingual support.

Inspired by work in https://github.com/Pdobry/xcc-graph.

🏠 Home Assistant Integration Features

• 🔧 470+ settable fields automatically discovered across 8 configuration pages
• 📊 Live data monitoring with real-time sensor values
• 🌐 Bilingual support (English/Czech with auto-detection)
• 📋 Organized by device (heating, PV, hot water, auxiliary source, etc.)

📦 HACS Installation

1. Add Custom Repository:

   • Open HACS in Home Assistant
   • Click the 3 dots (⋮) → "Custom repositories"
   • Add repository: https://github.com/pvyleta/xcc-integration
   • Category: Integration

2. Install Integration:

   • Go to HACS > Integrations
   • Search for "XCC Heat Pump Controller"
   • Click "Download" and restart Home Assistant

3. Configure Integration:

   • Settings > Devices & Services > "Add Integration"
   • Search for "XCC Heat Pump Controller"
   • Enter your XCC controller details

🔧 Development & Testing

Development Setup

1. Clone the repository:

   git clone https://github.com/pvyleta/xcc-integration
   cd xcc-integration

2. Create virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

Running Tests

The integration includes comprehensive tests to ensure reliability:

# Run all tests
python -m pytest tests/ -v

📚 Configuration Pages

The integration automatically discovers entities from these XCC pages:

Page	Description	Typical Entities
Heating Circuits	Temperature control, schedules. Every circuit the controller reports as enabled is polled; the first keeps bare xcc_to_* names, further circuits are namespaced xcc_okruh<n>_*	Temperature sensors, setpoint controls
Photovoltaics	Battery management, export limits	Power sensors, battery controls
PV Inverter	Inverter configuration and telemetry	String/phase sensors, inverter settings
Hot Water	Sanitization, circulation	Water temperature, heating controls
Auxiliary Source	Backup heating system	Status sensors, operation controls
Spot Pricing	Dynamic pricing optimization	Price sensors, optimization switches
System Status	Overall system information	Status sensors, diagnostic data
Heat Pump Settings	Advanced configuration (discovered dynamically)	Configuration switches, numbers
PV Battery SOC	Monthly battery state-of-charge target curve	12 monthly setpoint numbers (%)

🧰 Standalone Tools

The repo root ships a few helper scripts, separate from the integration in custom_components/xcc/. They do not share code with the integration (auth and page lists are duplicated). Current status:

Tool	Purpose	Status
find_hidden_switches.py	Offline analysis of scraped XML to list hidden _BOOL_i switch fields	✅ Works (needs fresh_tuv_data/ or tests/sample_data/)
xcc_scraper.py	Download all controller pages to disk	⚠️ Partially broken — only the inline fallback client path works; the custom_components/xcc import path is API-incompatible
xcc_cli.py	Interactive CLI to browse/search controller fields	❌ Broken — depends on field_database.json and scripts/analyze_known_pages.py, neither of which exists in the repo

These are kept for reference/backup workflows. See XCC_SCRAPER_README.md for scraper usage and caveats.