Skip to main content

python-senz-wifi-module

Python library for interacting with the SenzWifi (Pentair Thermal WiFi) API to control thermostats.

Features

  • Async-first — built on httpx for efficient async operations
  • Authentication & session management — automatic retry on session expiry
  • Thermostat control — list, read, and update thermostat settings
  • Convenience methods — set temperature, turn off, boost mode
  • Real-time notifications — long-polling for thermostat state changes
  • CLI tool — built-in command-line interface for quick operations
  • Fully typed — type hints throughout with py.typed marker

Installation

pip install senzwifi

Or install from source:

git clone https://github.com/sockless-coding/python-senz-wifi-module.git
cd python-senz-wifi-module
pip install -e .

Quick Start

Using the Library

import asyncio
from senzwifi import AsyncSenzWifi, RegulationMode

async def main():
    # Create client with credentials
    async with AsyncSenzWifi("your@email.com", "your-password") as client:
        # Authenticate
        await client.authenticate()

        # List all thermostats
        response = await client.get_thermostats()
        for group in response.groups:
            print(f"Group: {group.group_name}")
            for t in group.thermostats:
                print(f"  {t.room}: {t.temperature_celsius:.1f}°C (mode: {RegulationMode(t.regulation_mode).name})")

        # Set a thermostat to 21°C manually
        await client.set_manual_temperature("SN123456789", 21.0)

        # Turn off a thermostat
        await client.turn_off("SN123456789")

        # Start boost mode (3 hours by default)
        await client.start_boost("SN123456789")

asyncio.run(main())

Using the CLI

# List all thermostats
senzwifi --username "your@email.com" --password "your-password" list

# Get a specific thermostat
senzwifi --username "your@email.com" --password "your-password" get SN123456789

# Set temperature to 21°C
senzwifi --username "your@email.com" --password "your-password" set SN123456789 21.0

# Turn off a thermostat
senzwifi --username "your@email.com" --password "your-password" off SN123456789

# Start boost mode
senzwifi --username "your@email.com" --password "your-password" boost SN123456789

API Reference

AsyncSenzWifi

The main client class. Supports use as an async context manager.

async with AsyncSenzWifi(email, password) as client:
    await client.authenticate()
    # ... use the client

Constructor

Parameter Type Default Description
email str — Account email address
password str — Account password
max_retries int 3 Maximum retry attempts for failed requests
timeout float 30.0 Request timeout in seconds

Methods

authenticate() -> AuthResponse

Authenticate and obtain a session ID.

auth = await client.authenticate()
if auth.is_success:
    print(f"Logged in as {auth.email}")
get_thermostats() -> ThermostatsResponse

Fetch all thermostats grouped by their group.

response = await client.get_thermostats()
for group in response.groups:
    print(f"{group.group_name}: {len(group.thermostats)} devices")

# Get all thermostats flat
all_thermostats = response.get_all_thermostats()

# Find a specific thermostat
t = response.get_thermostat("SN123456789")
get_thermostat(serial_number: str) -> Thermostat

Get a specific thermostat by serial number.

t = await client.get_thermostat("SN123456789")
print(f"{t.room}: {t.temperature_celsius:.1f}°C")
set_manual_temperature(serial_number: str, temperature_celsius: float) -> UpdateThermostatResponse

Set a thermostat to a specific temperature in manual mode.

result = await client.set_manual_temperature("SN123456789", 21.5)
print(f"Success: {result.success}")
turn_off(serial_number: str) -> UpdateThermostatResponse

Turn off a thermostat.

result = await client.turn_off("SN123456789")
start_boost(serial_number: str, end_time: datetime | None = None) -> UpdateThermostatResponse

Start boost (comfort) mode. Defaults to 3 hours from now if no end time is specified.

from datetime import datetime, timedelta, timezone

# Boost for 3 hours (default)
await client.start_boost("SN123456789")

# Boost until a specific time
end = datetime.now(timezone.utc) + timedelta(hours=1)
await client.start_boost("SN123456789", end_time=end)
update_thermostat(serial_number: str, thermostat: Thermostat) -> UpdateThermostatResponse

Update a thermostat with custom settings.

t = await client.get_thermostat("SN123456789")
t.regulation_mode = RegulationMode.SCHEDULE
t.manual_temperature = 2000  # 20.0°C in raw format
result = await client.update_thermostat("SN123456789", t)
wait_for_notification(timeout: float = 300.0) -> Notification | None

Long-poll for thermostat state change notifications.

notification = await client.wait_for_notification(timeout=60.0)
if notification:
    print(f"Change detected: {notification.action} on {notification.thermostat.room}")

Models

RegulationMode

RegulationMode.SCHEDULE   # 1 — Use the configured schedule
RegulationMode.BOOST      # 2 — Boost / comfort temp mode
RegulationMode.MANUAL     # 3 — Constant temp mode
RegulationMode.OFF        # 5 — Off

Thermostat

Key properties (all temperatures available in both raw and Celsius):

Property Type Description
serial_number str Device serial number
room str Room name
group_name str Group name
temperature_celsius float Current temperature
regulation_mode int Current regulation mode
online bool Whether the device is online
heating bool Whether heating is active
manual_temperature_celsius float Manual setpoint temperature
comfort_temperature_celsius float Comfort/boost temperature
min_temp_celsius float Minimum temperature
max_temp_celsius float Maximum temperature
schedules list[Schedule] Available schedules

Temperature Conversion Utilities

from senzwifi import temp_to_celsius, celsius_to_temp

# Raw API value (1/100 °C) → Celsius
temp_to_celsius(2100)  # 21.0

# Celsius → raw API value
celsius_to_temp(21.0)  # 2100

Exceptions

Exception Description
SenzWifiError Base exception for all errors
AuthenticationError Authentication failed
SessionExpiredError Session has expired
DeviceNotFoundError Thermostat not found
APIError API request failed

Example: Monitoring Thermostats

See examples/monitor.py for a complete example that monitors thermostat changes in real time.

import asyncio
from senzwifi import AsyncSenzWifi, RegulationMode

async def monitor():
    async with AsyncSenzWifi("your@email.com", "your-password") as client:
        await client.authenticate()

        # Show initial state
        response = await client.get_thermostats()
        for t in response.get_all_thermostats():
            mode = RegulationMode(t.regulation_mode).name
            print(f"[INIT] {t.room}: {t.temperature_celsius:.1f}°C ({mode})")

        # Watch for changes
        while True:
            notification = await client.wait_for_notification()
            if notification:
                t = notification.thermostat
                mode = RegulationMode(t.regulation_mode).name
                print(f"[CHANGE] {t.room}: {t.temperature_celsius:.1f}°C ({mode})")

asyncio.run(monitor())

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Run type checker
mypy senzwifi

License

MIT

Metadata

Release files for senzwifi 2026.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for senzwifi 2026.6.2
File Size Uploaded Provenance Actions
senzwifi-2026.6.2.tar.gz 24.6 kB With provenance Details for senzwifi-2026.6.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for senzwifi 2026.6.2
File Interpreter ABI Platform Actions
senzwifi-2026.6.2-py3-none-any.whl Python 3 none any Details for senzwifi-2026.6.2-py3-none-any.whl

Total release size: 41.9 kB

Release files / senzwifi-2026.6.2.tar.gz

Download URL senzwifi-2026.6.2.tar.gz
Size 24.6 kB
Tags Source
SHA-256 checksum
How to use checksums
219007308c7ade41567c3bd742d4ac20e4f822ab821a9aaa239f880608006715
BLAKE2b-256 checksum
How to use checksums
d9182c2e7807fc131d7212f4ae2f091779819eb1a564d26ec6be6c1a35948804
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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 Jun 21, 2026.

Transparency log

Release files / senzwifi-2026.6.2-py3-none-any.whl

Download URL senzwifi-2026.6.2-py3-none-any.whl
Size 17.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b6f768a79301605e472e66d4be38107093921bb9b2fe4962aeac47d1b0ff0338
BLAKE2b-256 checksum
How to use checksums
c58772b433a09dfead98d7087fabe56b252ead09fb705e7d3d46701befb24161
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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 Jun 21, 2026.

Transparency log

Security for senzwifi 2026.6.2

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for senzwifi-2026.6.2.tar.gz

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 Jun 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page