proconip 2.2.1__tar.gz → 2.3.1__tar.gz

{proconip-2.2.1 → proconip-2.3.1}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.3.1](https://github.com/ylabonte/proconip-pypi/compare/v2.3.0...v2.3.1) (2026-10-12)
+
+
+### Documentation
+
+* confirm electrolysis bit polarity and document manual-dosage units/limits ([#102](https://github.com/ylabonte/proconip-pypi/issues/102)) ([cb44a11](https://github.com/ylabonte/proconip-pypi/commit/cb44a11336fc73bc9715f9ec12ecffeec8b8d16f))
+
+## [2.3.0](https://github.com/ylabonte/proconip-pypi/compare/v2.2.1...v2.3.0) (2026-10-12)
+
+
+### Features
+
+* flag the chlorine canister columns as cell data under electrolysis ([#100](https://github.com/ylabonte/proconip-pypi/issues/100)) ([27ca22a](https://github.com/ylabonte/proconip-pypi/commit/27ca22acb2e42e47647318713670ddd9f3938daf))
+
 ## [2.2.1](https://github.com/ylabonte/proconip-pypi/compare/v2.2.0...v2.2.1) (2026-10-08)
 
 

{proconip-2.2.1 → proconip-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proconip
-Version: 2.2.1
+Version: 2.3.1
 Summary: Async Python library for interacting with the ProCon.IP pool controller.
 Project-URL: Homepage, https://github.com/ylabonte/proconip-pypi
 Project-URL: Documentation, https://ylabonte.github.io/proconip-pypi/
@@ -165,6 +165,10 @@ asyncio.run(relay_switching_example())
 
 Manual dosage depends on the same factors as if started from the web interface
 of the pool control itself.
+Durations are always in seconds. The controller's web interface allows up to
+59:59 (3599 s) for liquid dosing and up to 23:59 hours (86340 s, whole minutes)
+for chlorine when a salt electrolysis cell is configured; the library passes
+the value through unchecked.
 
 ```python
 import asyncio
@@ -176,7 +180,7 @@ async def manual_dosage_example():
     client_session = aiohttp.ClientSession()
     config = ConfigObject("http://192.168.2.3", "admin", "admin")
     dosage_control = DosageControl(client_session, config)
-    await dosage_control.async_chlorine_dosage(3600)  # start for 1 hour
+    await dosage_control.async_chlorine_dosage(600)  # start for 10 minutes
     await dosage_control.async_ph_minus_dosage(60)  # start for 1 minute
     await client_session.close()
 

{proconip-2.2.1 → proconip-2.3.1}/README.md

@@ -137,6 +137,10 @@ asyncio.run(relay_switching_example())
 
 Manual dosage depends on the same factors as if started from the web interface
 of the pool control itself.
+Durations are always in seconds. The controller's web interface allows up to
+59:59 (3599 s) for liquid dosing and up to 23:59 hours (86340 s, whole minutes)
+for chlorine when a salt electrolysis cell is configured; the library passes
+the value through unchecked.
 
 ```python
 import asyncio
@@ -148,7 +152,7 @@ async def manual_dosage_example():
     client_session = aiohttp.ClientSession()
     config = ConfigObject("http://192.168.2.3", "admin", "admin")
     dosage_control = DosageControl(client_session, config)
-    await dosage_control.async_chlorine_dosage(3600)  # start for 1 hour
+    await dosage_control.async_chlorine_dosage(600)  # start for 10 minutes
     await dosage_control.async_ph_minus_dosage(60)  # start for 1 minute
     await client_session.close()
 

{proconip-2.2.1 → proconip-2.3.1}/src/proconip/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.1'
-__version_tuple__ = version_tuple = (2, 2, 1)
+__version__ = version = '2.3.1'
+__version_tuple__ = version_tuple = (2, 3, 1)
 
 __commit_id__ = commit_id = None

{proconip-2.2.1 → proconip-2.3.1}/src/proconip/api.py

@@ -595,18 +595,37 @@ async def async_start_dosage(
     """Trigger a manual, time-limited dosage on the controller.
 
     Manual dosage is the safe alternative to switching a dosage relay on
-    directly: the controller still applies the same interlocks it uses for the
-    web UI (canister level, dosage enabled in config, redox/pH thresholds, …).
-    If those checks fail, the controller silently no-ops while still returning
-    HTTP 200 — there is no "dosage refused" error in the protocol.
+    directly: it goes through the controller's own dosage logic, which the
+    TRM ties to preconditions such as the dosage channel being enabled and
+    the assigned filter pump running (a running dosage also stops when the
+    filter pump switches off). The TRM's daily maximum dosing amount may also
+    stop it: once the channel's daily amount is reached, the controller does
+    not dose any further. The protocol has no "dosage refused" response,
+    so a successful HTTP exchange does not prove that dosing started; check
+    the dosage relay state in `/GetState.csv` if you need to know.
+
+    The duration is always sent in seconds, as the controller's web UI does
+    (``/Command.htm?MAN_DOSAGE=<target>,<seconds>``). That UI limits the
+    input to ``mm:ss`` up to 59:59 (3599 s) for liquid dosing (chlorine,
+    pH-, pH+) and to ``hh:mm`` up to 23:59 (86340 s, whole minutes) for
+    chlorine when a salt electrolysis cell is configured (see
+    `GetStateData.is_electrolysis_enabled`). This function passes the value
+    through unchecked; how the controller treats values outside those
+    limits is not documented.
+
+    The web UI also stores the duration as the channel's default before it
+    sends the command: it rewrites ``MDOSTIME`` in the channel's ``.ini``
+    (``usr/rdxcntrl.ini``, ``usr/phcntrl.ini`` or ``usr/phpcntrl.ini``) via
+    ``/usrcfg.cgi`` and pre-fills that value next time. This function sends
+    only the command and leaves that default untouched.
 
     Args:
         client_session: An open `aiohttp.ClientSession`.
         config: Controller configuration.
         dosage_target: Which dosing pump to engage (chlorine, pH-, or pH+).
-        dosage_duration: Run time in **seconds**. Allowed range depends on the
-            controller's own dosage configuration; values that exceed the
-            configured maximum are typically clamped silently by the device.
+        dosage_duration: Run time in **seconds**, in both liquid and
+            electrolysis mode. The web UI allows 0–3599 s for liquid dosing
+            and 0–86340 s (whole minutes) for chlorine electrolysis.
         timeout: Per-request timeout in seconds.
 
     Returns:
@@ -662,10 +681,12 @@ class DosageControl:
     async def async_chlorine_dosage(
         self, dosage_duration: int, timeout: float | None = None
     ) -> str:
-        """Run the chlorine dosage pump for ``dosage_duration`` seconds.
+        """Run the chlorine dosage pump (or electrolysis cell) for ``dosage_duration`` seconds.
 
         Args:
-            dosage_duration: Run time in seconds.
+            dosage_duration: Run time in seconds. The controller's web UI
+                allows up to 3599 s for liquid chlorine and up to 86340 s
+                (whole minutes) for a salt electrolysis cell.
             timeout: Override for this call only. If ``None``, the timeout
                 bound in `__init__` is used.
 
@@ -687,7 +708,8 @@ class DosageControl:
         """Run the pH- dosage pump for ``dosage_duration`` seconds.
 
         Args:
-            dosage_duration: Run time in seconds.
+            dosage_duration: Run time in seconds. The controller's web UI
+                allows up to 3599 s (59:59).
             timeout: Override for this call only. If ``None``, the timeout
                 bound in `__init__` is used.
 
@@ -707,7 +729,8 @@ class DosageControl:
         """Run the pH+ dosage pump for ``dosage_duration`` seconds.
 
         Args:
-            dosage_duration: Run time in seconds.
+            dosage_duration: Run time in seconds. The controller's web UI
+                allows up to 3599 s (59:59).
             timeout: Override for this call only. If ``None``, the timeout
                 bound in `__init__` is used.
 

{proconip-2.2.1 → proconip-2.3.1}/src/proconip/definitions.py

@@ -187,7 +187,10 @@ class DataObject:
                 temperature, ``16–23`` → relay, ``24–27`` → digital input,
                 ``28–35`` → external relay, ``36–38`` → canister, ``39–41`` →
                 consumption. Anything outside this range falls into a sentinel
-                "uncategorized" bucket.
+                "uncategorized" bucket. The category is purely positional: with
+                a salt-electrolysis cell, columns 36 and 39 still land in the
+                canister/consumption categories although they describe the
+                cell (see `GetStateData.is_electrolysis_object`).
             name: Sensor name as reported by the controller (e.g. ``"Redox"``).
             unit: Unit string (``"mV"``, ``"°C"``, ``"%"``, ``"--"``, …).
             offset: Calibration offset applied to ``value``.
@@ -620,7 +623,23 @@ class GetStateData:
         return self._dosage_control & 1 == 1
 
     def is_electrolysis_enabled(self) -> bool:
-        """True if electrolysis (saltwater) chlorination is enabled (bit 4)."""
+        """True if the chlorine supply is a salt-electrolysis cell (bit 4).
+
+        When set, the chlorine channel is not fed from a canister: the
+        chlorine "canister" reading (column 36) is the cell's remaining
+        lifetime / maintenance interval in percent, and the chlorine
+        "consumption" reading (column 39) is today's *calculated* chlorine
+        production. Use `is_electrolysis_object` to tell those two objects
+        apart from real canister readings.
+
+        Polarity: the TRM labels bit 4 "Cl liquid || Elektrolysis" without
+        saying which value is which. The controller's own web UI settles it
+        (``topleft.htm``, firmware 1.7.6): it decodes
+        ``rdx_canister_salt = (dos_cntr >> 4) & 0x01`` and shows
+        ``"Flüssig NaClO"`` for 0 and ``"Salz Elektrolyse"`` for 1. A live
+        liquid-chlorine controller (``rdxcntrl.ini`` ``DTYPE=0``) reports
+        DOSAGE_CNTRL 257 with bit 4 clear, consistent with that.
+        """
         return self._dosage_control & 16 == 16
 
     def is_ph_minus_dosage_enabled(self) -> bool:
@@ -651,6 +670,33 @@ class GetStateData:
             return self.is_ph_plus_dosage_enabled()
         return False
 
+    def is_electrolysis_object(self, data_entity: DataObject) -> bool:
+        """Does this canister/consumption object describe a salt-electrolysis cell?
+
+        The controller reuses the chlorine canister columns for a salt
+        electrolysis setup instead of adding new ones. With electrolysis
+        enabled (see `is_electrolysis_enabled`):
+
+        - column 36 (`chlorine_canister`) is the cell's **remaining lifetime**
+          (or maintenance interval) in percent — the share of the configured
+          operating hours that is left, not a canister fill level;
+        - column 39 (`chlorine_consumption`) is **today's chlorine production**
+          calculated from the configured production rate, not a liquid
+          volume drawn from a canister.
+
+        Callers should label and present these objects accordingly (e.g. no
+        canister/volume wording). The pH- and pH+ columns are always real
+        canisters.
+
+        Args:
+            data_entity: Any `DataObject` from this state.
+
+        Returns:
+            True only for the chlorine canister (column 36) or chlorine
+            consumption (column 39) object while electrolysis is enabled.
+        """
+        return data_entity.column in (36, 39) and self.is_electrolysis_enabled()
+
     def get_dosage_relay(self, data_entity: DataObject) -> int | None:
         """Aggregated relay ID that handles the dosing for this canister/consumption entity.
 
@@ -912,20 +958,28 @@ class GetStateData:
 
     @property
     def canister_objects(self) -> list[DataObject]:
-        """The three canister fill-level readings (columns 36–38).
+        """The three canister remaining-content readings (columns 36–38), in percent.
 
         Order: chlorine, pH-, pH+. Convenience properties `chlorine_canister`,
         `ph_minus_canister`, and `ph_plus_canister` return individual entries.
+        The values are estimates the controller derives from pump runtime and
+        configured delivery rate. With a salt-electrolysis cell the chlorine
+        entry is the cell's remaining lifetime instead — check
+        `is_electrolysis_object`.
         """
         return self._canister_objects
 
     @property
     def consumption_objects(self) -> list[DataObject]:
-        """The three dosage consumption counters (columns 39–41).
+        """The three daily dosage amounts (columns 39–41).
 
         Order: chlorine, pH-, pH+. Convenience properties
         `chlorine_consumption`, `ph_minus_consumption`, and
-        `ph_plus_consumption` return individual entries.
+        `ph_plus_consumption` return individual entries. Each is the amount
+        dosed *today* (the controller resets it daily), in the unit the
+        controller reports (``ml``; the chlorine column may report ``g``). With a
+        salt-electrolysis cell the chlorine entry is today's calculated
+        chlorine production — check `is_electrolysis_object`.
         """
         return self._consumption_objects
 
@@ -941,32 +995,41 @@ class GetStateData:
 
     @property
     def chlorine_canister(self) -> DataObject:
-        """Chlorine canister fill level (column 36)."""
+        """Chlorine canister remaining content in percent (column 36).
+
+        With a salt-electrolysis cell (`is_electrolysis_enabled`) this is the
+        cell's remaining lifetime / maintenance interval in percent instead.
+        """
         return self._canister_objects[0]
 
     @property
     def ph_minus_canister(self) -> DataObject:
-        """pH- canister fill level (column 37)."""
+        """pH- canister remaining content in percent (column 37)."""
         return self._canister_objects[1]
 
     @property
     def ph_plus_canister(self) -> DataObject:
-        """pH+ canister fill level (column 38)."""
+        """pH+ canister remaining content in percent (column 38)."""
         return self._canister_objects[2]
 
     @property
     def chlorine_consumption(self) -> DataObject:
-        """Cumulative chlorine consumption counter (column 39)."""
+        """Chlorine dosed today (column 39), in ``ml`` or ``g``.
+
+        With a salt-electrolysis cell (`is_electrolysis_enabled`) this is
+        today's chlorine production calculated from the configured
+        production rate instead.
+        """
         return self._consumption_objects[0]
 
     @property
     def ph_minus_consumption(self) -> DataObject:
-        """Cumulative pH- consumption counter (column 40)."""
+        """pH- dosed today (column 40), in ``ml``."""
         return self._consumption_objects[1]
 
     @property
     def ph_plus_consumption(self) -> DataObject:
-        """Cumulative pH+ consumption counter (column 41)."""
+        """pH+ dosed today (column 41), in ``ml``."""
         return self._consumption_objects[2]
 
     @property

{proconip-2.2.1 → proconip-2.3.1}/tests/conftest.py

@@ -36,3 +36,20 @@ def get_state_data(get_state_csv: str) -> GetStateData:
 @pytest.fixture
 def get_dmx_data(get_dmx_csv: str) -> GetDmxData:
     return GetDmxData(get_dmx_csv)
+
+
+@pytest.fixture
+def get_state_electrolysis_csv() -> str:
+    """`get_state.csv` reconfigured for a salt-electrolysis chlorine supply.
+
+    Derived from the real capture: DOSAGE_CNTRL 273 (Cl enabled + bit 4
+    electrolysis + pH- enabled), chlorine daily amount in ``g``, and non-zero
+    values in the chlorine "canister" (cell lifetime %) and "consumption"
+    (calculated production) columns, per the vendor's TRM column table.
+    """
+    return (FIXTURES_DIR / "get_state_electrolysis.csv").read_text()
+
+
+@pytest.fixture
+def get_state_electrolysis_data(get_state_electrolysis_csv: str) -> GetStateData:
+    return GetStateData(get_state_electrolysis_csv)

proconip-2.3.1/tests/fixtures/get_state_electrolysis.csv

@@ -0,0 +1,6 @@
+SYSINFO,1.7.3,9559698,1,3,0,273,4,4,5
+Time,n.a.,n.a.,n.a.,n.a.,CPU Temp,Redox,pH,Pumpe,n.a.,n.a.,n.a.,n.a.,n.a.,n.a.,n.a.,Terassenlicht,n.a.,n.a.,Gartenlicht,pH minus,Chlor,Bachlauf,Poolpumpe,TASTER1,TASTER2,TASTER3,TASTER4,n.a.,n.a.,n.a.,n.a.,n.a.,n.a.,n.a.,n.a.,Cl Rest,pH- Rest,pH+ Rest,Cl consumption,pH- consumption,pH+ consumption
+h,mV,mV,Bar,ppm,C,mV,pH,C,C,C,C,C,C,C,C,--,--,--,--,--,--,--,--,cm/s,--,--,--,--,--,--,--,--,--,--,--,%,%,%,g,ml,ml
+0,0,0,-0.400,6.00000,147.5,0.0,0.0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+1,0.0625,0.0625,0.0000125,0.000156,-0.00468750,0.0625,0.0078125,0.0625,0.0625,0.0625,0.0625,0.0625,0.0625,0.0625,0.0625,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,0.1,0.1,0.1,1,1,1
+529,-44,-44,-44,-44,24878,14000,932,111,0,0,0,0,0,0,0,2,0,0,2,2,2,2,2,0,0,0,0,0,0,0,0,0,0,0,0,873,615,1000,412,0,0

{proconip-2.2.1 → proconip-2.3.1}/tests/test_definitions.py

@@ -266,6 +266,51 @@ def test_get_dosage_relay(get_state_data: GetStateData) -> None:
     assert get_state_data.get_dosage_relay(get_state_data.analog_objects[0]) is None
 
 
+def test_is_electrolysis_object_false_for_liquid_chlorine(get_state_data: GetStateData) -> None:
+    assert not get_state_data.is_electrolysis_enabled()
+    for obj in get_state_data.canister_objects + get_state_data.consumption_objects:
+        assert not get_state_data.is_electrolysis_object(obj)
+
+
+def test_is_electrolysis_object_marks_chlorine_columns_only(
+    get_state_electrolysis_data: GetStateData,
+) -> None:
+    state = get_state_electrolysis_data
+    assert state.is_electrolysis_enabled()
+    assert state.is_chlorine_dosage_enabled()
+    assert state.is_electrolysis_object(state.chlorine_canister)
+    assert state.is_electrolysis_object(state.chlorine_consumption)
+    # pH canisters stay real canisters
+    for obj in (
+        state.ph_minus_canister,
+        state.ph_plus_canister,
+        state.ph_minus_consumption,
+        state.ph_plus_consumption,
+    ):
+        assert not state.is_electrolysis_object(obj)
+    # unrelated columns never qualify
+    assert not state.is_electrolysis_object(state.redox_electrode)
+    assert not state.is_electrolysis_object(state.analog_objects[0])
+
+
+def test_electrolysis_keeps_chlorine_columns_positional(
+    get_state_electrolysis_data: GetStateData,
+) -> None:
+    """Under electrolysis, columns 36/39 stay in the canister/consumption categories.
+
+    The ``%``/``g`` units and values below come from the synthesised
+    electrolysis fixture, not from observed controller output; the category
+    asserts are what this test pins.
+    """
+    state = get_state_electrolysis_data
+    assert state.chlorine_canister.unit == "%"
+    assert state.chlorine_canister.value == pytest.approx(87.3)
+    assert state.chlorine_canister.category == CATEGORY_CANISTER
+    assert state.chlorine_consumption.unit == "g"
+    assert state.chlorine_consumption.value == pytest.approx(412)
+    assert state.chlorine_consumption.category == CATEGORY_CONSUMPTION
+
+
 def test_is_dosage_relay_by_relay_object(get_state_data: GetStateData) -> None:
     dosage_relay = get_state_data.get_relay(5)  # chlorine dosage relay_id
     assert get_state_data.is_dosage_relay(relay_object=dosage_relay)