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

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

Documentation

Changelog

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