Python OmniLogic Local
A modern Python library for local control of Hayward OmniLogic and OmniHub pool controllers
Features • Installation • Quick Start • Documentation • CLI Tool
Overview
Python OmniLogic Local provides complete local control over Hayward OmniLogic and OmniHub pool automation systems using their UDP-based XML protocol. Built with modern Python 3.14+, comprehensive type hints, and Pydantic validation, this library offers a async, type-safe interface for pool automation.
Features
Equipment Control
- Heaters: Temperature control, mode selection (heat/auto/off), solar support
- Pumps & Filters: Variable speed control, on/off operation, diagnostic information
- ColorLogic Lights: Multiple models supported (2.5, 4.0, UCL, SAM), brightness, speed, show selection
- Relays: Control auxiliary equipment like fountains, deck jets, blowers
- Chlorinators: Timed percent control, enable/disable operation
- Groups: Coordinated equipment control (turn multiple devices on/off together)
- Schedules: Enable/disable automated schedules
Monitoring & State Management
- Real-time Telemetry: Water temperature, chemical readings, equipment state
- Configuration Discovery: Automatic detection of all equipment and capabilities
- Sensor Data: pH, ORP, TDS, salt levels, flow sensors
- Filter Diagnostics: Last speed, valve positions, priming states
- Equipment Hierarchy: Automatic parent-child relationship tracking
Developer-Friendly Design
- Type Safety: Comprehensive type hints with strict mypy validation
- Async/Await: Non-blocking asyncio-based API
- Pydantic Models: Automatic validation and serialization
- Smart State Management: Automatic dirty tracking and efficient refreshing
- Equipment Collections: Dict-like and attribute access patterns
- Generic Architecture: Type-safe equipment hierarchy with generics
Installation
Requirements: Python 3.14 or higher
pip install python-omnilogic-local
With CLI tools (includes packet capture utilities):
pip install python-omnilogic-local[cli]
Quick Start
Basic Usage
import asyncio
from pyomnilogic_local import OmniLogic, OmniLogicConfig
async def main():
# Connect to your OmniLogic controller
config = OmniLogicConfig(
host="192.168.1.100"
)
omni = OmniLogic(config)
# Initial refresh to load configuration and state
await omni.refresh()
# Access equipment by name
pool = omni.backyard.bow["Pool"]
# Control heater
heater = pool.heater
print(f"Current temperature: {heater.current_temperature}°F")
print(f"Target temperature: {heater.current_set_point}°F")
await heater.set_temperature(85)
await heater.turn_on()
# Refresh to get updated state
await omni.refresh()
# Control lights
from pyomnilogic_local.omnitypes import ColorLogicBrightness, ColorLogicSpeed
light = pool.lights["Pool Light"]
await light.turn_on()
await light.set_show(
show=light.effects.TWILIGHT,
brightness=ColorLogicBrightness.ONE_HUNDRED_PERCENT,
speed=ColorLogicSpeed.ONE_TIMES
)
# Control pump speed
pump = pool.pumps["Pool Pump"]
await pump.set_speed(75) # Set to 75%
asyncio.run(main())
Monitoring Equipment State
async def monitor_pool():
config = OmniLogicConfig(
host="192.168.1.100"
)
omni = OmniLogic(config)
await omni.refresh()
pool = omni.backyard.bow["Pool"]
# Check multiple equipment states
print(f"Water temperature: {pool.heater.current_temperature}°F")
print(f"Heater is {'on' if pool.heater.is_on else 'off'}")
print(f"Pump speed: {pool.pumps['Main Pump'].current_speed}%")
# Check all lights
for name, light in pool.lights.items():
if light.is_on:
print(f"{name}: {light.show.name} @ {light.brightness.name}")
else:
print(f"{name}: OFF")
# Access chemical sensors
if pool.sensors:
for name, sensor in pool.sensors.items():
print(f"{name}: {sensor.current_reading}")
asyncio.run(monitor_pool())
Efficient State Updates
The library includes intelligent state management to minimize unnecessary API calls:
# Force immediate refresh of Telemetry
await omni.refresh(force_telemetry=True)
# Force immediate refresh of MSP Config
await omni.refresh(force_mspconfig=True)
# Refresh only if data is older than 30 seconds
await omni.refresh(if_older_than=30.0)
# Refresh only if equipment state changed (default after control commands)
await omni.refresh(if_dirty=True)
Documentation
Equipment Hierarchy
OmniLogic
├── Backyard
│ ├── Bodies of Water (BOW)
│ │ ├── Heater (single virtual heater)
│ │ ├── Pumps
│ │ ├── Filters
│ │ ├── Chlorinator
│ │ ├── Lights (ColorLogic)
│ │ ├── Relays
│ │ ├── Sensors
│ │ └── CSAD (Chemical Sensing & Dispensing)
│ ├── Lights (ColorLogic)
│ ├── Relays
│ └── Sensors
├── Groups
└── Schedules
Accessing Equipment
Equipment can be accessed using dictionary-style or attribute-style syntax:
# Dictionary access (by name)
pool = omni.backyard.bow["Pool"]
# Heater is a single object (not a collection)
heater = pool.heater
# Most equipment are collections
for pump_name, pump in pool.pumps.items():
print(f"Pump: {pump_name} - Speed: {pump.current_speed}%")
# Lights, relays, and sensors can be on both BOW and backyard levels
for light_name, light in pool.lights.items():
print(f"BOW Light: {light_name}")
for light_name, light in omni.backyard.lights.items():
print(f"Backyard Light: {light_name}")
# Groups and schedules are at the OmniLogic level
for group_name, group in omni.groups.items():
print(f"Group: {group_name}")
Equipment Properties
All equipment exposes standard properties:
equipment.name # Equipment name
equipment.system_id # Unique system identifier
equipment.bow_id # Body of water ID (if applicable)
equipment.is_ready # Whether equipment can accept commands
equipment.mspconfig # Configuration data
equipment.telemetry # Real-time state data
Control Methods
Control methods are async and automatically handle readiness checks:
from pyomnilogic_local.omnitypes import ColorLogicBrightness, ColorLogicSpeed
# All control methods are async
await heater.turn_on()
await heater.turn_off()
await heater.set_temperature(85)
# Light show control - brightness and speed are parameters to set_show()
await light.set_show(
show=light.effects.CARIBBEAN,
brightness=ColorLogicBrightness.EIGHTY_PERCENT,
speed=ColorLogicSpeed.TWO_TIMES
)
# Pump speed control
await pump.set_speed(75)
# State is automatically marked dirty after control commands
# Refresh to get updated telemetry
await omni.refresh()
Exception Handling
The library provides specific exception types:
from pyomnilogic_local import (
OmniLogicLocalError, # Base exception
OmniEquipmentNotReadyError, # Equipment in transitional state
OmniEquipmentNotInitializedError, # Missing required attributes
OmniConnectionError, # Network/communication errors
)
try:
await heater.set_temperature(120) # Too high
except OmniValidationException as e:
print(f"Invalid temperature: {e}")
try:
await light.turn_on()
except OmniEquipmentNotReadyError as e:
print(f"Light not ready: {e}")
CLI Tool
The library includes a command-line tool for monitoring and debugging:
# Get telemetry data
omnilogic --host 192.168.1.100 debug get-telemetry
# List all equipment
omnilogic get lights
omnilogic get pumps
omnilogic get heaters
# Get raw XML responses
omnilogic debug --raw get-mspconfig
# View filter diagnostics
omnilogic debug get-filter-diagnostics
Installation with CLI tools:
pip install python-omnilogic-local[cli]
Supported Equipment
Fully Supported
- Pool/Spa Heaters (gas, heat pump, solar, hybrid)
- Variable Speed Pumps & Filters
- ColorLogic Lights (2.5, 4.0, UCL, SAM models)
- Relays (water features, auxiliary equipment)
- Chlorinators (timed percent control)
- Sensors (temperature, pH, ORP, TDS, salt, flow)
- Groups (coordinated equipment control)
- Schedules (enable/disable)
- CSAD (Chemical Sensing & Dispensing) - monitoring
Partial Support
- CSAD equipment control (monitoring only currently)
- Some advanced heater configurations
[!NOTE] If your controller has equipment not listed here, please open an issue with details about your configuration.
Development
This project uses modern Python tooling:
- Python: 3.14+ with type hints
- Type Checking: mypy strict mode
- Validation: Pydantic v2
- Testing: pytest with async support
- Code Quality: black, isort, pylint, ruff
- Package Management: uv (optional) or pip
Running Tests
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=pyomnilogic_local --cov-report=html
# Type checking
mypy pyomnilogic_local
# Linting
pylint pyomnilogic_local
Credits
This library was made possible by the pioneering work of:
- djtimca - Original protocol research and implementation
- John Sutherland - Protocol documentation and testing
Related Projects
- Home Assistant Integration - Use this library with Home Assistant
Disclaimer
This is an unofficial library and is not affiliated with, endorsed by, or connected to Hayward Industries, Inc. Use at your own risk. The developers are not responsible for any damage to equipment or property resulting from the use of this software.
1 maintainer
Metadata
1 maintainer
Release files for python-omnilogic-local 5.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| python_omnilogic_local-5.0.1.tar.gz | 86.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| python_omnilogic_local-5.0.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 206.9 kB
Release files / python_omnilogic_local-5.0.1.tar.gz
| Download URL | python_omnilogic_local-5.0.1.tar.gz |
|---|---|
| Size | 86.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
48b638fabfa0482934d8ce92cd9e20a6fcb93ece5f14ce6b1c30bb9777a82bac
|
|
BLAKE2b-256 checksum How to use checksums |
e93841becfdd2e00676b08a5198318476557f160ef724712587eafa1e9839139
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / python_omnilogic_local-5.0.1-py3-none-any.whl
| Download URL | python_omnilogic_local-5.0.1-py3-none-any.whl |
|---|---|
| Size | 120.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2d03dcc506426ca72096a08660964bae16056ec5e9367b1db8fbefde6f5f8b74
|
|
BLAKE2b-256 checksum How to use checksums |
7464e8fb15d3259ff0013fb0c9b36e8e99505f690da7e201786279924dc070bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency log
