proconip 2.3.0__tar.gz → 2.3.1__tar.gz

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

@@ -1,5 +1,12 @@
 # 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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proconip
-Version: 2.3.0
+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.3.0 → 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.3.0 → 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.3.0'
-__version_tuple__ = version_tuple = (2, 3, 0)
+__version__ = version = '2.3.1'
+__version_tuple__ = version_tuple = (2, 3, 1)
 
 __commit_id__ = commit_id = None

{proconip-2.3.0 → 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.3.0 → proconip-2.3.1}/src/proconip/definitions.py

@@ -632,14 +632,13 @@ class GetStateData:
         production. Use `is_electrolysis_object` to tell those two objects
         apart from real canister readings.
 
-        Polarity evidence: the TRM labels bit 4 "Cl liquid || Elektrolysis",
-        naming both options without saying which value is which. A live
-        firmware 1.7.6 controller configured for liquid chlorine
-        (``rdxcntrl.ini`` ``DTYPE=0``, chlorine dosing on) reports
-        DOSAGE_CNTRL 257 (bits 0 and 8, bit 4 clear), as does the real capture
-        in the test fixtures. So bit 4 is the chlorine device-type selector,
-        and set = electrolysis is inferred, not observed; a real electrolysis
-        capture is still pending.
+        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