pyintellicenter

Python library for communicating with Pentair IntelliCenter pool control systems over a local network.

What It Does

pyintellicenter is an async Python library for communicating directly with Pentair IntelliCenter pool control systems (i5P, i8P, i10P, and similar) over your local network. It supports both TCP and WebSocket transports, provides real-time push-based equipment state updates, and is the underlying library powering the Pentair IntelliCenter Home Assistant integration.

Features

• Dual Transport Support: TCP (port 6681) and WebSocket (port 6680) connections
• Local Communication: Direct connection to IntelliCenter — no cloud required
• Real-time Updates: Push-based notifications via the NotifyList protocol
• Per-object Subscriptions: subscribe(objnam, callback) on the model controller (and forwarded by the connection handler) registers any number of per-object or all-object listeners with an unsubscribe remover — see docs/API.md
• mDNS Discovery: Automatically find IntelliCenter units on your network
• Async/Await: Built on Python asyncio for efficient I/O
• Type Annotations: Full type hints for IDE support and static analysis
• Robust Connection Handling: Automatic reconnection with exponential backoff
• Circuit Breaker Pattern: Prevents connection storms during outages
• Home Assistant Ready: Convenience helpers for integration development, including read-only accessors for temperature, chemistry, sensors, heaters, and schedules

Installation

See INSTALL.md for the complete guide.

pip install pyintellicenter
# or
uv add pyintellicenter

Requires Python 3.13+.

Quick Start

Basic Connection (TCP)

import asyncio
from pyintellicenter import ICModelController, PoolModel, ICConnectionHandler


async def main():
    model = PoolModel()
    controller = ICModelController("192.168.1.100", model)
    handler = ICConnectionHandler(controller)
    await handler.start()

    print(f"Connected to: {controller.system_info.prop_name}")
    print(f"Software version: {controller.system_info.sw_version}")

    for obj in model:
        print(f"{obj.sname} ({obj.objtype}): {obj.status}")

    await controller.set_circuit_state("POOL", True)
    await handler.astop()


asyncio.run(main())

await handler.astop() waits for the connection teardown to complete. The synchronous handler.stop() is the best-effort form: it schedules the teardown in the background and is safe to call from callbacks.

WebSocket Connection

from pyintellicenter import ICConnection


async def main():
    async with ICConnection("192.168.1.100", transport="websocket") as conn:
        response = await conn.send_request(
            "GetParamList", condition="", objectList=[{"objnam": "INCR", "keys": ["VER", "SNAME"]}]
        )
        print(response)

Auto-Discovery

from pyintellicenter import discover_intellicenter_units


async def main():
    units = await discover_intellicenter_units(discovery_timeout=5.0)
    for unit in units:
        print(f"Found: {unit.name} at {unit.host}:{unit.port}")
        print(f"  Model: {unit.model}")
        print(f"  WebSocket port: {unit.ws_port}")

Usage

See docs/USAGE.md for full usage patterns. The sections below cover the main concepts.

Connection Behavior

Connection Flow:

1. Connect — establishes TCP or WebSocket connection
2. Initialize — fetches system info and all equipment objects
3. Monitor — receives real-time NotifyList push updates
4. Keepalive — sends queries every 90 seconds (configurable)

Reconnection Strategy:

1. Debounce: 15-second grace period before marking disconnected
2. Exponential Backoff: starts at 30 s, increases 1.5x each attempt (max 10 min)
3. Circuit Breaker: after 5 consecutive failures, pauses for 5 minutes
4. Reset: successful connection resets failure counters
5. Reconcile: every (re)connect prunes equipment deleted at the panel from the model and reports the removals through the update callback as {objnam: None} entries

Handler Lifecycle:

• await handler.start() — connect and wait for the first successful attempt; reconnection then continues in the background
• handler.connected — True while the handler considers the connection established (debounced view)
• handler.stop() — synchronous best-effort stop (teardown runs in the background; safe from callbacks)
• await handler.astop() — stop and wait for the full connection teardown

Notification Processing:

• Push notifications are queued (default: 100 items max)
• Queue prevents slow callbacks from blocking I/O
• When full, oldest notifications are dropped (prefers fresh state)
• Both sync and async callbacks are supported

Error Handling

from pyintellicenter import (
    ICError,  # Base exception
    ICConnectionError,  # Connection failures
    ICResponseError,  # Bad response from IntelliCenter
    ICCommandError,  # Command execution error
    ICTimeoutError,  # Request timeout
)

try:
    await controller.start()
except ICConnectionError as e:
    print(f"Connection failed: {e}")
except ICTimeoutError as e:
    print(f"Request timed out: {e}")

Equipment Types

Heater Modes

from pyintellicenter import HeaterType

HeaterType.OFF  # Heater off
HeaterType.HEATER  # Gas/electric heater only
HeaterType.SOLAR_PREFERRED  # Solar preferred, heater backup
HeaterType.SOLAR_ONLY  # Solar only
HeaterType.ULTRA_TEMP  # UltraTemp heat pump only
HeaterType.ULTRA_TEMP_PREFERRED  # UltraTemp preferred
HeaterType.HYBRID_GAS  # Hybrid heater, gas mode
HeaterType.HYBRID_ULTRA_TEMP  # Hybrid heater, heat pump mode
HeaterType.HYBRID_HYBRID  # Hybrid heater, hybrid mode
HeaterType.HYBRID_DUAL  # Hybrid heater, dual mode
# ... and more

Light Effects

from pyintellicenter import LIGHT_EFFECTS

# Available effects for IntelliBrite/MagicStream lights
# PARTY, ROMAN, CARIB, AMERCA, SSET, ROYAL, BLUER, GREENR, REDR, WHITER, MAGNTAR

await controller.set_light_effect("C0003", "PARTY")

API Reference

Full API reference lives in docs/. Key entry points:

See docs/API.md for the detailed per-class reference.

Architecture

+----------------------------------------------------------+
|                    ICConnectionHandler                    |
|              (Auto-reconnection, callbacks)               |
+----------------------------------------------------------+
|                    ICModelController                      |
|           (State management, helper methods)              |
+----------------------------------------------------------+
|                     ICBaseController                      |
|              (Command handling, metrics)                  |
+----------------------------------------------------------+
|                      ICConnection                         |
|               (Transport selection, flow control)         |
+----------------------+-----------------------------------+
|      ICProtocol      |       ICWebSocketTransport        |
|    (TCP transport)   |      (WebSocket transport)        |
+----------------------+-----------------------------------+

Development

See docs/DEVELOPMENT.md. In short:

git clone https://github.com/joyfulhouse/pyintellicenter.git
cd pyintellicenter
uv sync --extra dev
uv run pytest
uv run ruff check
uv run mypy src/pyintellicenter

Support

• Join the JoyfulHouse Discord for support and discussion across all JoyfulHouse Home Assistant integrations and libraries.
• Issues: https://github.com/joyfulhouse/pyintellicenter/issues
• PyPI: https://pypi.org/project/pyintellicenter/

Support Development

This library powers the Pentair IntelliCenter Home Assistant integration and is maintained in spare time with real hardware and tooling costs behind every release. If it is useful to you, please consider supporting its development:

• GitHub Sponsors
• Ko-fi

License

This project is licensed under the MIT License — see LICENSE for details.

Related Projects

• Pentair IntelliCenter — the Home Assistant integration built on this library.
• node-intellicenter — Node.js library (protocol reference).