python-pooldose 0.9.6

Unoffical async Python client for SEKO PoolDose devices

python-pooldose

Unofficial async Python client for SEKO Pooldosing systems. SEKO is a manufacturer of various monitoring and control devices for pools and spas. Some devices from VÁGNER POOL and BWT are compatible as well.

This client uses an undocumented local HTTP API. It provides live readings for pool sensors such as temperature, pH, ORP/Redox, as well as status information and control over the dosing logic.

Disclaimer: Use at your own risk. No liability for damages or malfunctions.

Features

• Async/await support for non-blocking operations
• Dynamic sensor discovery based on device model and firmware
• Dictionary-style access to instant values
• Structured data API with type-based organization
• Device analyzer for discovering unsupported device capabilities
• PEP-561 compliant with full type hints for Home Assistant integrations
• Command-line interface for direct device interaction and testing
• Secure by default - WiFi passwords excluded unless explicitly requested
• Comprehensive error handling with detailed logging
• Cloud connection status
• WiFi RSSI signal

Each method queries the device live and returns the current value.

• SSL/HTTPS support for secure communication

Prerequisites

1. Install and set-up the PoolDose devices according to the user manual.
   1. In particular, connect the device to your WiFi network.
   2. Identify the IP address or hostname of the device.
2. Browse to the IP address or hostname (default port: 80).
   1. Try to log in to the web interface with the default password (0000).
   2. Check availability of data in the web interface.
3. Optionally: Block the device from internet access to ensure cloudless-only operation.

Installation

(i) Release Version (PyPI)

Install the latest stable release from PyPI:

pip install python-pooldose

(ii) Development Version (GitHub)

Install the latest development state directly from the main branch:

pip install "git+https://github.com/lmaertin/python-pooldose.git@main"

If you want to work on the code locally (editable install):

git clone https://github.com/lmaertin/python-pooldose.git
cd python-pooldose
pip install -e .

macOS/Linux Quick Installer

For convenience, the repository also provides a bootstrap script that downloads the latest source archive from GitHub, installs it into a local virtual environment, and creates a launcher on the Desktop.

curl -fsSLO https://raw.githubusercontent.com/lmaertin/python-pooldose/main/install-unix.sh
bash install-unix.sh

The installer creates:

• macOS: ~/Library/Application Support/python-pooldose and ~/Desktop/PoolDose.command
• Linux: ~/.local/share/python-pooldose and ~/Desktop/PoolDose.sh

Network access hint:

• macOS: If prompted, allow Local Network access for Terminal/iTerm/Python.
• Linux: If a firewall is enabled, allow local network access for Terminal/Python.

Run the same installer again later to update to the latest source from GitHub. The generated launcher can also forward normal CLI arguments:

~/Desktop/PoolDose.command --host 192.168.1.100
~/Desktop/PoolDose.command --help

On Linux, use ~/Desktop/PoolDose.sh instead of ~/Desktop/PoolDose.command.

Windows Quick Installer

Use the PowerShell installer to download and install the latest source into a local virtual environment and create a Desktop launcher.

Invoke-WebRequest https://raw.githubusercontent.com/lmaertin/python-pooldose/main/install-windows.ps1 -OutFile install-windows.ps1
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1

The installer creates:

• %LOCALAPPDATA%\python-pooldose for source and virtual environment
• %USERPROFILE%\Desktop\PoolDose.cmd as a launcher

If Python is not installed yet, the script stops and shows instructions to install Python first (python.org installer or winget).

Network access hint:

• If Windows Firewall prompts for Python/Terminal network access, click Allow.

Quick Start

import asyncio
from pooldose.client import PooldoseClient
from pooldose.request_status import RequestStatus

async def main():
    client = PooldoseClient(host="192.168.1.100")
    status = await client.connect()
    if status != RequestStatus.SUCCESS:
        print(f"Connection failed: {status}")
        return

    # Dictionary-style access
    status, values = await client.instant_values()
    if status == RequestStatus.SUCCESS and values:
        print(f"Temperature: {values['temperature']}")
        print(f"pH: {values.get('ph', 'N/A')}")

    # Structured data (grouped by type)
    status, data = await client.instant_values_structured()
    if status == RequestStatus.SUCCESS:
        for sensor, info in data.get("sensor", {}).items():
            print(f"{sensor}: {info['value']} {info.get('unit', '')}")

asyncio.run(main())

Command Line Usage

# Connect to device
pooldose --host 192.168.1.100

# With HTTPS
pooldose --host 192.168.1.100 --ssl

# Analyze device capabilities
pooldose --host 192.168.1.100 --analyze

# Mock mode (testing without hardware)
pooldose --mock path/to/data.json

# Show help / version
pooldose --help
pooldose --version

See docs/cli.md for full CLI documentation and device analysis details.

Supported Devices

Device	PRODUCT_CODE	FW Code	Notes
SEKO PoolDose Double	PDPR1H1HAW100	539187
SEKO PoolDose Double Spa	PDPR1H04AW100	539292
SEKO POOLDOSE pH+ORP CF Group Wi-Fi	PDPR1H1HAW102	539187	Alias for PDPR1H1HAW100 mapping
SEKO PoolDose pH	PDPH1H1HAW100	539176	pH-only device
BWT MEDO CONNECT Wi-Fi	PDPH1H1HAW1B0	539494	Based on SEKO PoolDose pH mapping
VÁGNER POOL VA DOS BASIC	PDHC1H1HAR1V0	539224
VÁGNER POOL VA DOS EXACT	PDHC1H1HAR1V1	539224	Alias for PDPR1H1HAR1V0 mapping

Other models may work but are untested. See docs/device-support.md for how to request support for new devices.

Documentation

Topic	Description
API Reference	Constructor, methods, properties, data formats
CLI & Device Analysis	Command line usage and device analyzer
Examples	Basic and advanced usage examples
Mock Client	Testing without hardware using JSON files
SSL/HTTPS	SSL configuration and migration guide
Security	Data classification and sensitive data handling
Type Hints & HA	PEP-561 compliance and Home Assistant integration

Changelog

For detailed release notes and version history, please see CHANGELOG.md.