neopool-modbus 1.0.0

Async Python client for Sugar Valley NeoPool / VistaPool / Hidrolife Modbus pool controllers

neopool-modbus

Async Python client for Sugar Valley NeoPool pool controllers (sold under brands VistaPool, Hidrolife, Aquascenic, Oxilife, Hayward, Brilix, Bayrol) connected via Modbus TCP.

This library is the communication layer extracted from the Home Assistant neopool integration and is suitable for any async Python project — Home Assistant integrations, scripts, dashboards, or custom automation.

Installation

pip install neopool-modbus

Requires Python 3.13+ and pymodbus>=3.10.0 (installed transitively).

Quick start

import asyncio

from neopool_modbus import NeoPoolModbusClient


async def main() -> None:
    client = NeoPoolModbusClient(
        {"host": "192.168.1.42", "port": 502, "slave_id": 1}
    )
    try:
        data = await client.async_read_all()
        # Keys are the upstream Sugar Valley register names from
        # https://github.com/arendst/Tasmota/.../xsns_83_neopool.ino,
        # values are decoded into native Python types.
        print(f"pH:          {data['MBF_MEASURE_PH']}")           # e.g. 7.42
        print(f"Temperature: {data['MBF_MEASURE_TEMPERATURE']} °C")  # e.g. 27.3
        print(f"Hydrolysis:  {data['MBF_HIDRO_CURRENT']}")        # e.g. 6.5
    finally:
        await client.close()


asyncio.run(main())

The client is lazy — it opens the TCP connection on first use and reuses it across calls; close() releases the socket and resets retry/backoff state.

Public API

from neopool_modbus import (
    NeoPoolModbusClient,
    NeoPoolError,
    NeoPoolConnectionError,
    NeoPoolTimeoutError,
)
from neopool_modbus.registers import (
    EXEC_REGISTER,
    EEPROM_SAVE_REGISTER,
    HEATING_SETPOINT_REGISTER,
    INTELLIGENT_SETPOINT_REGISTER,
    MANUAL_FILTRATION_REGISTER,
    TIMER_BLOCKS,
    is_valid_relay_gpio,
)
from neopool_modbus.decoders import (
    parse_timer_block,
    build_timer_block,
    hhmm_to_seconds,
    seconds_to_hhmm,
    get_machine_name,
    is_hydrolysis_in_percent,
    # ... see neopool_modbus.decoders for the full list
)
from neopool_modbus.status_mask import (
    decode_relay_state,
    decode_named_relay_states,
    decode_uv_lamp_state,
    decode_hidro_status_bits,
    decode_ion_status_bits,
    decode_ph_rx_cl_cd_status_bits,
)

The exception hierarchy (NeoPoolError → NeoPoolConnectionError / NeoPoolTimeoutError) is a forward-compatible contract; today the client still raises the underlying pymodbus exceptions directly. Catching Exception is the only safe choice for now.

Features

• Async I/O on top of pymodbus.AsyncModbusTcpClient
• Batched register reads — one round-trip per protocol page, with notification-bit-driven cache invalidation so unchanged pages skip the read
• Exponential connection retry with bounded backoff
• Write-and-verify cycle for configuration registers
• Capability detection (hydrolysis, pH, Redox, chlorine, conductivity, ION)
• Strict type hints (py.typed), 100 % unit-test coverage

Logging

The library uses a single logger named neopool_modbus. Enable it like any other Python logger:

import logging
logging.getLogger("neopool_modbus").setLevel(logging.DEBUG)

Home Assistant users can flip the integration's "Enable debug logging" toggle in the UI; the integration's manifest.json lists neopool_modbus so the toggle covers the library too.

License

Apache 2.0 — see LICENSE.