proconip 2.1.2__tar.gz → 2.2.0__tar.gz

{proconip-2.1.2 → proconip-2.2.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2.2.0](https://github.com/ylabonte/proconip-pypi/compare/v2.1.2...v2.2.0) (2026-06-14)
+
+
+### Features
+
+* add digital input triggering via WEBIO ([#93](https://github.com/ylabonte/proconip-pypi/issues/93)) ([8c35420](https://github.com/ylabonte/proconip-pypi/commit/8c354202ded3bbe389d6a53c0059b78d14337b97))
+
 ## [2.1.2](https://github.com/ylabonte/proconip-pypi/compare/v2.1.1...v2.1.2) (2026-06-14)
 
 

{proconip-2.1.2 → proconip-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proconip
-Version: 2.1.2
+Version: 2.2.0
 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/

{proconip-2.1.2 → proconip-2.2.0}/src/proconip/__init__.py

@@ -11,8 +11,10 @@ except ImportError:  # pragma: no cover
         __version__ = "0.0.0.dev0"
 
 from .api import (
+    DIGITAL_INPUT_COUNT,
     BadCredentialsException,
     BadStatusCodeException,
+    DigitalInputControl,
     DmxControl,
     DosageControl,
     GetState,
@@ -30,6 +32,7 @@ from .api import (
     async_start_dosage,
     async_switch_off,
     async_switch_on,
+    async_trigger_digital_input,
 )
 from .definitions import (
     CATEGORY_ANALOG,
@@ -45,6 +48,7 @@ from .definitions import (
     BadRelayException,
     ConfigObject,
     DataObject,
+    DigitalInput,
     DmxChannelData,
     DosageTarget,
     GetDmxData,
@@ -67,12 +71,14 @@ __all__ = [
     # data classes
     "DataObject",
     "Relay",
+    "DigitalInput",
     "GetStateData",
     "DmxChannelData",
     "GetDmxData",
     # enums
     "DosageTarget",
     # constants
+    "DIGITAL_INPUT_COUNT",
     "EXTERNAL_RELAY_ID_OFFSET",
     "CATEGORY_TIME",
     "CATEGORY_ANALOG",
@@ -88,6 +94,7 @@ __all__ = [
     "RelaySwitch",
     "DosageControl",
     "DmxControl",
+    "DigitalInputControl",
     # free async functions
     "async_get_raw_data",
     "async_get_raw_state",
@@ -100,4 +107,5 @@ __all__ = [
     "async_get_raw_dmx",
     "async_get_dmx",
     "async_set_dmx",
+    "async_trigger_digital_input",
 ]

{proconip-2.1.2 → proconip-2.2.0}/src/proconip/_version.py

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

{proconip-2.1.2 → proconip-2.2.0}/src/proconip/api.py

@@ -26,6 +26,7 @@ subclasses so callers can handle them uniformly.
 """
 
 import asyncio
+import contextlib
 import socket
 
 from aiohttp import (
@@ -894,3 +895,148 @@ class DmxControl:
             dmx_states=data,
             timeout=self.timeout if timeout is None else timeout,
         )
+
+
+DIGITAL_INPUT_COUNT = 4
+DIGITAL_INPUT_PULSE_SECONDS = 0.6
+
+
+async def async_trigger_digital_input(
+    client_session: ClientSession,
+    config: ConfigObject,
+    digital_input_id: int,
+    timeout: float = 10.0,
+    hold_seconds: float = DIGITAL_INPUT_PULSE_SECONDS,
+) -> str:
+    """Trigger (momentarily pulse) a digital input via the WEBIO ``IO`` field.
+
+    The controller's web UI exposes each digital input as a push button: it
+    sets the input's bit, waits, then clears it. This sends the same two
+    `/usrcfg.cgi` writes — ``IO=<mask>&WEBIO=1`` (press) then, after
+    ``hold_seconds``, ``IO=0&WEBIO=1`` (release) — where
+    ``mask = 1 << digital_input_id``. The hold mirrors the web UI (~600ms) so
+    the controller reliably registers the pulse.
+
+    Unlike relay switching, no `GetStateData` snapshot is needed: the ``IO``
+    field is written directly rather than read-modify-written.
+
+    Because the pulse is two separate writes, the release is not fully
+    guaranteed. If the hold is **cancelled** (e.g. the caller's task is shut
+    down), a best-effort release is attempted before the cancellation
+    propagates. If the **release POST itself fails** (timeout / network blip),
+    that error propagates and the input is left asserted HIGH until the next
+    write.
+
+    Args:
+        client_session: An open `aiohttp.ClientSession`.
+        config: Controller configuration including base URL and credentials.
+        digital_input_id: Zero-based digital input index (0–3).
+        timeout: Per-request timeout in seconds, applied to each of the two
+            POSTs.
+        hold_seconds: Seconds to hold the input HIGH between the press and
+            release POSTs. Defaults to the web UI's ~600ms.
+
+    Returns:
+        The raw response body returned by the release POST.
+
+    Raises:
+        ValueError: If ``digital_input_id`` is not in 0–3.
+        BadCredentialsException: On HTTP 401 or 403.
+        BadStatusCodeException: On any other 4xx or 5xx response.
+        TimeoutException: If an exchange exceeds ``timeout`` seconds.
+        ProconipApiException: For network-level errors.
+    """
+    if not 0 <= digital_input_id < DIGITAL_INPUT_COUNT:
+        raise ValueError(
+            f"digital_input_id must be in 0..{DIGITAL_INPUT_COUNT - 1}, got {digital_input_id}"
+        )
+    mask = 1 << digital_input_id
+    await async_post_usrcfg_cgi(
+        client_session=client_session,
+        config=config,
+        payload=f"IO={mask}&WEBIO=1",
+        timeout=timeout,
+    )
+    try:
+        await asyncio.sleep(hold_seconds)
+    except asyncio.CancelledError:
+        # Best-effort release so a cancelled hold doesn't leave the input
+        # asserted HIGH. Networking inside a cancellation is awkward, so this
+        # is a best effort, not a guarantee.
+        with contextlib.suppress(Exception):
+            await async_post_usrcfg_cgi(
+                client_session=client_session,
+                config=config,
+                payload="IO=0&WEBIO=1",
+                timeout=timeout,
+            )
+        raise
+    return await async_post_usrcfg_cgi(
+        client_session=client_session,
+        config=config,
+        payload="IO=0&WEBIO=1",
+        timeout=timeout,
+    )
+
+
+class DigitalInputControl:
+    """Convenience wrapper that binds a session and config for triggering inputs.
+
+    Construct once with your `aiohttp.ClientSession` and `ConfigObject`, then
+    pulse digital inputs by zero-based id (0–3) without repeating those
+    arguments each time.
+
+    The constructor also binds a default `timeout` for every call made via this
+    wrapper. Each method then accepts an optional per-call `timeout` that
+    overrides the bound default when supplied.
+
+    Example:
+        ```python
+        dic = DigitalInputControl(session, config)
+        await dic.async_trigger(0)  # pulse the first digital input
+        ```
+    """
+
+    def __init__(
+        self,
+        client_session: ClientSession,
+        config: ConfigObject,
+        timeout: float = 10.0,
+    ):
+        """Bind the session, config, and default per-request timeout.
+
+        Args:
+            client_session: An open `aiohttp.ClientSession`.
+            config: Controller configuration.
+            timeout: Default per-request timeout in seconds, used when a method
+                is called without its own ``timeout`` argument.
+        """
+        self.client_session = client_session
+        self.config = config
+        self.timeout = timeout
+
+    async def async_trigger(
+        self,
+        digital_input_id: int,
+        timeout: float | None = None,
+        hold_seconds: float = DIGITAL_INPUT_PULSE_SECONDS,
+    ) -> str:
+        """Trigger the digital input identified by ``digital_input_id``.
+
+        Args:
+            digital_input_id: Zero-based digital input index (0–3).
+            timeout: Override for this call only. If ``None``, the timeout
+                bound in `__init__` is used.
+            hold_seconds: Seconds to hold the input HIGH between press and
+                release. Defaults to the web UI's ~600ms.
+
+        See `async_trigger_digital_input` (the free function) for the full
+        description of behavior and raised exceptions.
+        """
+        return await async_trigger_digital_input(
+            client_session=self.client_session,
+            config=self.config,
+            digital_input_id=digital_input_id,
+            timeout=self.timeout if timeout is None else timeout,
+            hold_seconds=hold_seconds,
+        )

{proconip-2.1.2 → proconip-2.2.0}/src/proconip/definitions.py

@@ -409,6 +409,48 @@ class Relay(DataObject):
         return 1 << self._category_id
 
 
+class DigitalInput(DataObject):
+    """Typed view of a single digital input (CSV columns 24–27).
+
+    Construct one by passing the `DataObject` you got from
+    `GetStateData.digital_input_objects`; the column, name, calibration, and
+    raw value are copied across so the physical value is computed exactly once.
+    ``GetStateData.digital_inputs()`` is a shorthand that does this for you.
+
+    The wrapper exists so digital inputs can be *triggered* (not just read):
+    `get_bit_mask` yields the bit used in the controller's WEBIO ``IO`` field.
+    """
+
+    def __init__(self, data_object: DataObject):
+        """Wrap an existing digital-input `DataObject`.
+
+        Args:
+            data_object: A `DataObject` produced by parsing a `/GetState.csv`
+                response. It should be in the digital_input category, but no
+                check is enforced — passing another object yields a
+                `DigitalInput` whose `get_bit_mask` is meaningless.
+        """
+        super().__init__(
+            data_object.column,
+            data_object.name,
+            data_object.unit,
+            data_object.offset,
+            data_object.gain,
+            data_object.raw_value,  # pass raw value so offset+gain are applied exactly once
+        )
+
+    def get_bit_mask(self) -> int:
+        """Bit for this input in the WEBIO ``IO`` field (``1 << category_id``).
+
+        The four digital inputs occupy bits 0–3, so this returns 1, 2, 4, or 8.
+        To *trigger* an input, pass its ``category_id`` to
+        `async_trigger_digital_input` (which derives the same mask itself); use
+        this method when assembling an ``IO`` payload for a manual
+        `async_post_usrcfg_cgi` write.
+        """
+        return 1 << self._category_id
+
+
 class GetStateData:
     """Parsed representation of a single `/GetState.csv` response.
 
@@ -822,6 +864,14 @@ class GetStateData:
         """The four digital inputs (columns 24–27), in column order."""
         return self._digital_input_objects
 
+    def digital_inputs(self) -> list[DigitalInput]:
+        """The four digital inputs as `DigitalInput` instances.
+
+        Equivalent to wrapping each entry in `digital_input_objects` with
+        `DigitalInput(...)`. Use these to get `get_bit_mask()` for triggering.
+        """
+        return [DigitalInput(obj) for obj in self._digital_input_objects]
+
     @property
     def external_relay_objects(self) -> list[DataObject]:
         """The eight external relays (columns 28–35), in column order.

{proconip-2.1.2 → proconip-2.2.0}/tests/test_api.py

@@ -1,5 +1,8 @@
 """Tests for the API module — HTTP layer, error mapping, and class wrappers."""
 
+import asyncio
+from unittest.mock import patch
+
 import aiohttp
 import pytest
 from aioresponses import aioresponses
@@ -7,6 +10,7 @@ from aioresponses import aioresponses
 from proconip.api import (
     BadCredentialsException,
     BadStatusCodeException,
+    DigitalInputControl,
     DmxControl,
     DosageControl,
     GetState,
@@ -22,6 +26,7 @@ from proconip.api import (
     async_start_dosage,
     async_switch_off,
     async_switch_on,
+    async_trigger_digital_input,
 )
 from proconip.definitions import ConfigObject, DosageTarget, GetDmxData, GetStateData
 
@@ -228,6 +233,115 @@ async def test_set_dmx_sends_post(config: ConfigObject, get_dmx_csv: str) -> Non
     assert result == "ok"
 
 
+# ---------------------------------------------------------------------------
+# async_trigger_digital_input
+# ---------------------------------------------------------------------------
+
+
+def _usrcfg_posts(m: aioresponses) -> list:
+    """Return the recorded POST calls to /usrcfg.cgi, in order."""
+    return [
+        call
+        for (method, url), calls in m.requests.items()
+        for call in calls
+        if method == "POST" and "usrcfg.cgi" in str(url)
+    ]
+
+
+@pytest.mark.parametrize(
+    ("digital_input_id", "expected_mask"),
+    [(0, 1), (1, 2), (2, 4), (3, 8)],
+)
+async def test_trigger_digital_input_sends_posts(
+    config: ConfigObject, digital_input_id: int, expected_mask: int
+) -> None:
+    with aioresponses() as m:
+        m.post(USRCFG_URL, body="press-ok", status=200)
+        m.post(USRCFG_URL, body="release-ok", status=200)
+        async with aiohttp.ClientSession() as session:
+            result = await async_trigger_digital_input(
+                session, config, digital_input_id, hold_seconds=0
+            )
+    posts = _usrcfg_posts(m)
+    assert len(posts) == 2
+    assert posts[0].kwargs["data"] == f"IO={expected_mask}&WEBIO=1"
+    assert posts[1].kwargs["data"] == "IO=0&WEBIO=1"
+    # The function returns the *release* response body.
+    assert result == "release-ok"
+
+
+@pytest.mark.parametrize("digital_input_id", [-1, 4, 99])
+async def test_trigger_digital_input_invalid_id_raises(
+    config: ConfigObject, digital_input_id: int
+) -> None:
+    with aioresponses() as m:
+        async with aiohttp.ClientSession() as session:
+            with pytest.raises(ValueError):
+                await async_trigger_digital_input(session, config, digital_input_id)
+    assert _usrcfg_posts(m) == []
+
+
+async def test_trigger_digital_input_401_raises_bad_credentials(config: ConfigObject) -> None:
+    with aioresponses() as m:
+        m.post(USRCFG_URL, status=401)
+        async with aiohttp.ClientSession() as session:
+            with pytest.raises(BadCredentialsException):
+                await async_trigger_digital_input(session, config, 0)
+
+
+async def test_trigger_digital_input_holds_high_between_posts(config: ConfigObject) -> None:
+    """By default the input is held HIGH ~600ms between press and release.
+
+    Mirrors the controller's web UI, which waits before clearing the bit.
+    asyncio.sleep is patched so the test stays fast while proving the hold
+    happens *between* the two POSTs (one POST recorded when sleep fires).
+    """
+    posts_at_sleep: list[int] = []
+
+    async def record_sleep(delay: float) -> None:
+        posts_at_sleep.append(len(_usrcfg_posts(m)))
+        assert delay == 0.6
+
+    with aioresponses() as m:
+        m.post(USRCFG_URL, body="press-ok", status=200)
+        m.post(USRCFG_URL, body="release-ok", status=200)
+        with patch("proconip.api.asyncio.sleep", side_effect=record_sleep):
+            async with aiohttp.ClientSession() as session:
+                result = await async_trigger_digital_input(session, config, 0)
+
+    assert result == "release-ok"
+    assert len(_usrcfg_posts(m)) == 2
+    # sleep fired exactly once, after the press POST and before the release.
+    assert posts_at_sleep == [1]
+
+
+async def test_trigger_digital_input_releases_on_cancel(config: ConfigObject) -> None:
+    """A cancelled hold still attempts a best-effort release, then re-raises.
+
+    Otherwise a press would set the bit and the cancellation would leave the
+    input asserted HIGH with no release.
+    """
+
+    async def cancel_during_hold(delay: float) -> None:
+        raise asyncio.CancelledError
+
+    with aioresponses() as m:
+        m.post(USRCFG_URL, body="press-ok", status=200)
+        m.post(USRCFG_URL, body="release-ok", status=200)
+        with patch("proconip.api.asyncio.sleep", side_effect=cancel_during_hold):
+            async with aiohttp.ClientSession() as session:
+                with pytest.raises(asyncio.CancelledError):
+                    await async_trigger_digital_input(session, config, 0)
+    posts = _usrcfg_posts(m)
+    assert [p.kwargs["data"] for p in posts] == ["IO=1&WEBIO=1", "IO=0&WEBIO=1"]
+
+
+def test_digital_input_count_is_exported_from_package() -> None:
+    from proconip import DIGITAL_INPUT_COUNT
+
+    assert DIGITAL_INPUT_COUNT == 4
+
+
 # ---------------------------------------------------------------------------
 # OO class wrappers
 # ---------------------------------------------------------------------------
@@ -294,6 +408,18 @@ async def test_dmx_control_class(config: ConfigObject, get_dmx_csv: str) -> None
     assert isinstance(parsed, GetDmxData)
 
 
+async def test_digital_input_control_class(config: ConfigObject) -> None:
+    with aioresponses() as m:
+        m.post(USRCFG_URL, body="press-ok", status=200)
+        m.post(USRCFG_URL, body="release-ok", status=200)
+        async with aiohttp.ClientSession() as session:
+            dic = DigitalInputControl(session, config)
+            result = await dic.async_trigger(2, hold_seconds=0)
+    posts = _usrcfg_posts(m)
+    assert [p.kwargs["data"] for p in posts] == ["IO=4&WEBIO=1", "IO=0&WEBIO=1"]
+    assert result == "release-ok"
+
+
 # ---------------------------------------------------------------------------
 # Exception hierarchy
 # ---------------------------------------------------------------------------

{proconip-2.1.2 → proconip-2.2.0}/tests/test_definitions.py

@@ -16,6 +16,7 @@ from proconip.definitions import (
     BadRelayException,
     ConfigObject,
     DataObject,
+    DigitalInput,
     DmxChannelData,
     GetDmxData,
     GetStateData,
@@ -199,6 +200,16 @@ def test_digital_input_objects(get_state_data: GetStateData) -> None:
         assert obj.column == idx + 24
 
 
+def test_digital_inputs(get_state_data: GetStateData) -> None:
+    inputs = get_state_data.digital_inputs()
+    assert len(inputs) == 4
+    for idx, digital_input in enumerate(inputs):
+        assert isinstance(digital_input, DigitalInput)
+        assert digital_input.category == CATEGORY_DIGITAL_INPUT
+        assert digital_input.category_id == idx
+        assert digital_input.column == idx + 24
+
+
 def test_external_relay_objects(get_state_data: GetStateData) -> None:
     objs = get_state_data.external_relay_objects
     assert len(objs) == 8
@@ -327,6 +338,38 @@ def test_relay_str(get_state_data: GetStateData) -> None:
     assert "Terassenlicht" in str(relay)
 
 
+# ---------------------------------------------------------------------------
+# DigitalInput
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("digital_input_id", "expected_mask"),
+    [(0, 1), (1, 2), (2, 4), (3, 8)],
+)
+def test_digital_input_get_bit_mask(
+    get_state_data: GetStateData, digital_input_id: int, expected_mask: int
+) -> None:
+    digital_input = get_state_data.digital_inputs()[digital_input_id]
+    assert digital_input.get_bit_mask() == expected_mask
+
+
+def test_digital_input_value_not_double_applied() -> None:
+    """DigitalInput must apply offset+gain exactly once, like Relay.
+
+    Mirrors `test_relay_value_not_double_applied`: a non-trivial offset would
+    expose a double-application bug. column 24 is the first digital input.
+    """
+    obj = DataObject(column=24, name="test", unit="--", offset=1.0, gain=1.0, value=1.0)
+    assert obj.value == pytest.approx(2.0)
+
+    digital_input = DigitalInput(obj)
+    assert digital_input.value == pytest.approx(2.0)
+    assert digital_input.raw_value == pytest.approx(1.0)
+    assert digital_input.category == CATEGORY_DIGITAL_INPUT
+    assert digital_input.category_id == 0
+
+
 # ---------------------------------------------------------------------------
 # DmxChannelData
 # ---------------------------------------------------------------------------