pybls21 5.0.0__tar.gz → 5.1.0__tar.gz

{pybls21-5.0.0/pybls21.egg-info → pybls21-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybls21
-Version: 5.0.0
+Version: 5.1.0
 Summary: Async Modbus TCP client for Blauberg S21 ventilation devices
 Author-email: Julius Vitkauskas <zadintuvas@gmail.com>
 License-Expression: MIT
@@ -94,9 +94,55 @@ identity, exceptions, and Home Assistant component migration.
 
 Booleans are not accepted as numeric control values. Bad arguments raise
 `ValueError` before network I/O. `S21Error` is the base for
-`UnsupportedDeviceException` and `ModbusCommunicationException`; the latter
+`UnsupportedDeviceException`, `DiscoveryError`, and `ModbusCommunicationException`; the latter
 includes transport errors and timeouts, retaining the original cause.
 
+## Discovering devices
+
+```python
+from pybls21 import discover, S21Client
+
+# Broadcast one read-only UDP request and collect replies for three seconds.
+devices = await discover()
+for device in devices:
+    print(device.device_id, device.host)
+    snapshot = await S21Client(device.host).poll()
+
+# Optional: target a subnet, choose a local interface, or query a known host.
+devices = await discover(address="192.168.1.255", local_address="192.168.1.10")
+devices = await discover(address="192.168.1.149", timeout=1.0)
+```
+
+`discover()` returns a tuple of immutable `DiscoveredDevice` objects with `host`
+and `device_id`. It collects replies for the whole timeout, deduplicates by
+controller ID (keeping the first address received), and sorts results by ID.
+No replies means an empty tuple. Invalid arguments raise `ValueError`; socket
+failures raise `DiscoveryError`, a subclass of `S21Error`, retaining the cause.
+Cancellation propagates and closes the socket. No background tasks are left running.
+
+Discovery uses IPv4 UDP port **4000**, independently of Modbus TCP port **502**.
+It sends a parameter-read request for controller ID and device type using an
+empty password. Replies must have a valid checksum, matching controller IDs,
+and S21 device type 1. This was verified by unicast and broadcast against an S21
+running firmware `0.36 (2019-05-08)`; availability on other firmware is not yet
+verified. The packet format follows the manufacturer's
+[UDP protocol documentation](https://device.report/m/4ad7c8426973ad1157494cc5715f286e69d244ea3fa438d4b66851938bebf485);
+the [S21 manual](https://blaubergdata.de/Daten/Manual_S21.pdf) describes the app's
+network-search feature.
+
+The default broadcast address is `255.255.255.255`; it normally reaches only the
+local subnet. On a host with multiple network interfaces, call discovery for
+each desired interface using `local_address` and, if necessary, its subnet's
+broadcast address. Arguments accept IPv4 addresses, not hostnames or IPv6.
+Firewalls and network isolation can prevent replies; manual host configuration
+remains supported. Discovery does not automatically run when creating a client.
+
+The controller ID is a device-provided identifier that applications can use
+across IP changes. It is separate from `ClimateDevice` and does not change
+existing polling or entity IDs. UDP replies are not authenticated; validate a
+candidate with `S21Client.poll()` before setting up the device. No device settings
+are written and no password is needed for discovery on the tested unit.
+
 ## Additional readings
 
 `await client.poll()` also returns extract and exhaust air temperatures

{pybls21-5.0.0 → pybls21-5.1.0}/README.md

@@ -70,9 +70,55 @@ identity, exceptions, and Home Assistant component migration.
 
 Booleans are not accepted as numeric control values. Bad arguments raise
 `ValueError` before network I/O. `S21Error` is the base for
-`UnsupportedDeviceException` and `ModbusCommunicationException`; the latter
+`UnsupportedDeviceException`, `DiscoveryError`, and `ModbusCommunicationException`; the latter
 includes transport errors and timeouts, retaining the original cause.
 
+## Discovering devices
+
+```python
+from pybls21 import discover, S21Client
+
+# Broadcast one read-only UDP request and collect replies for three seconds.
+devices = await discover()
+for device in devices:
+    print(device.device_id, device.host)
+    snapshot = await S21Client(device.host).poll()
+
+# Optional: target a subnet, choose a local interface, or query a known host.
+devices = await discover(address="192.168.1.255", local_address="192.168.1.10")
+devices = await discover(address="192.168.1.149", timeout=1.0)
+```
+
+`discover()` returns a tuple of immutable `DiscoveredDevice` objects with `host`
+and `device_id`. It collects replies for the whole timeout, deduplicates by
+controller ID (keeping the first address received), and sorts results by ID.
+No replies means an empty tuple. Invalid arguments raise `ValueError`; socket
+failures raise `DiscoveryError`, a subclass of `S21Error`, retaining the cause.
+Cancellation propagates and closes the socket. No background tasks are left running.
+
+Discovery uses IPv4 UDP port **4000**, independently of Modbus TCP port **502**.
+It sends a parameter-read request for controller ID and device type using an
+empty password. Replies must have a valid checksum, matching controller IDs,
+and S21 device type 1. This was verified by unicast and broadcast against an S21
+running firmware `0.36 (2019-05-08)`; availability on other firmware is not yet
+verified. The packet format follows the manufacturer's
+[UDP protocol documentation](https://device.report/m/4ad7c8426973ad1157494cc5715f286e69d244ea3fa438d4b66851938bebf485);
+the [S21 manual](https://blaubergdata.de/Daten/Manual_S21.pdf) describes the app's
+network-search feature.
+
+The default broadcast address is `255.255.255.255`; it normally reaches only the
+local subnet. On a host with multiple network interfaces, call discovery for
+each desired interface using `local_address` and, if necessary, its subnet's
+broadcast address. Arguments accept IPv4 addresses, not hostnames or IPv6.
+Firewalls and network isolation can prevent replies; manual host configuration
+remains supported. Discovery does not automatically run when creating a client.
+
+The controller ID is a device-provided identifier that applications can use
+across IP changes. It is separate from `ClimateDevice` and does not change
+existing polling or entity IDs. UDP replies are not authenticated; validate a
+candidate with `S21Client.poll()` before setting up the device. No device settings
+are written and no password is needed for discovery on the tested unit.
+
 ## Additional readings
 
 `await client.poll()` also returns extract and exhaust air temperatures

{pybls21-5.0.0 → pybls21-5.1.0}/pybls21/__init__.py

@@ -1,7 +1,9 @@
 """Public API for the asynchronous Blauberg S21 client."""
 
 from .client import S21Client
+from .discovery import DiscoveredDevice, discover
 from .exceptions import (
+    DiscoveryError,
     ModbusCommunicationException,
     S21Error,
     UnsupportedDeviceException,
@@ -10,6 +12,9 @@ from .models import BypassMode, BypassType, ClimateDevice, HVACAction, HVACMode
 
 __all__ = [
     "S21Client",
+    "discover",
+    "DiscoveredDevice",
+    "DiscoveryError",
     "S21Error",
     "ModbusCommunicationException",
     "UnsupportedDeviceException",

pybls21-5.1.0/pybls21/discovery.py

@@ -0,0 +1,133 @@
+"""Read-only IPv4 discovery using the controller's UDP protocol."""
+
+import asyncio
+import math
+import socket
+from dataclasses import dataclass, field
+from ipaddress import IPv4Address
+
+from .exceptions import DiscoveryError
+
+_DISCOVERY_PORT = 4000
+_MAX_PACKET_SIZE = 256
+# Read device ID (0x007c) and device type (0x00b9), with an empty password.
+_BODY = b"\x02\x10DEFAULT_DEVICEID\x00\x01\x7c\xb9"
+_REQUEST = b"\xfd\xfd" + _BODY + sum(_BODY).to_bytes(2, "little")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DiscoveredDevice:
+    """An S21 discovery reply; use host with S21Client's Modbus TCP port."""
+
+    host: str = field(doc="IPv4 address from which the reply was received.")
+    device_id: str = field(doc="16-character controller ID, independent of its IP.")
+
+
+def _parse_response(data: bytes, host: str) -> DiscoveredDevice | None:
+    """Ignore malformed packets and other products sharing the UDP protocol."""
+    if (
+        not 25 <= len(data) <= _MAX_PACKET_SIZE
+        or data[:4] != b"\xfd\xfd\x02\x10"
+        or sum(data[2:-2]) != int.from_bytes(data[-2:], "little")
+    ):
+        return None
+    identity = data[4:20]
+    if not identity.isalnum():
+        return None
+    password_size = data[20]
+    position = 21 + password_size
+    end = len(data) - 2
+    if password_size > 8 or position >= end or data[position] != 6:
+        return None
+    position += 1
+    parameters: dict[int, bytes] = {}
+    high_byte = 0
+    while position < end:
+        parameter = data[position]
+        position += 1
+        size = 1
+        if parameter == 0xFF:  # Change the high byte of subsequent parameter IDs.
+            if position >= end:
+                return None
+            high_byte = data[position] << 8
+            position += 1
+            continue
+        if parameter == 0xFE:  # Explicit length for the following parameter.
+            if position + 2 > end:
+                return None
+            size, parameter = data[position : position + 2]
+            position += 2
+        if parameter >= 0xFC or size == 0 or position + size > end:
+            return None
+        key = high_byte | parameter
+        if key in parameters:
+            return None
+        parameters[key] = data[position : position + size]
+        position += size
+    # S21 is type 1. Do not mistake VENTO and related products for an S21.
+    if parameters.get(0xB9) != b"\x01\x00" or parameters.get(0x7C) != identity:
+        return None
+    return DiscoveredDevice(host=host, device_id=identity.decode("ascii"))
+
+
+async def discover(
+    *,
+    timeout: float = 3.0,
+    address: str = "255.255.255.255",
+    local_address: str = "0.0.0.0",
+) -> tuple[DiscoveredDevice, ...]:
+    """Find S21 controllers without changing device settings.
+
+    Send one UDP broadcast and collect replies for ``timeout`` seconds. ``address``
+    may be a subnet broadcast or a known device's IPv4 address for unicast lookup.
+    Bind ``local_address`` to a local IPv4 address to select a network interface.
+    Hostnames and IPv6 are not supported. Broadcasts normally stay on the local
+    subnet; call separately for each desired interface on a multihomed host.
+
+    Return devices sorted by ID, retaining the first address seen for each ID.
+    Silence returns an empty tuple. Invalid arguments raise ValueError; socket
+    failures raise DiscoveryError. Cancellation propagates and closes the socket.
+    The timeout bounds sending and receiving, not just the first reply.
+    """
+    if (
+        isinstance(timeout, bool)
+        or not isinstance(timeout, (int, float))
+        or not math.isfinite(timeout)
+        or timeout <= 0
+    ):
+        raise ValueError("timeout must be a finite positive number")
+    if not isinstance(address, str) or not isinstance(local_address, str):
+        raise ValueError("address and local_address must be IPv4 address strings")
+    destination = str(IPv4Address(address))
+    interface = str(IPv4Address(local_address))
+    loop = asyncio.get_running_loop()
+    devices: dict[str, DiscoveredDevice] = {}
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+            sock.setblocking(False)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+            sock.bind((interface, 0))
+            deadline = asyncio.timeout(timeout)
+            try:
+                async with deadline:
+                    await loop.sock_sendto(
+                        sock, _REQUEST, (destination, _DISCOVERY_PORT)
+                    )
+                    while True:
+                        data, source = await loop.sock_recvfrom(
+                            sock, _MAX_PACKET_SIZE + 1
+                        )
+                        # Yield even if a busy socket has another packet ready,
+                        # so deadlines and cancellation cannot be starved.
+                        await asyncio.sleep(0)
+                        if source[1] != _DISCOVERY_PORT:
+                            continue
+                        device = _parse_response(data, source[0])
+                        if device is not None:
+                            devices.setdefault(device.device_id, device)
+            except TimeoutError:
+                if not deadline.expired():
+                    raise
+    except OSError as error:
+        raise DiscoveryError("UDP discovery failed") from error
+    return tuple(devices[key] for key in sorted(devices))

{pybls21-5.0.0 → pybls21-5.1.0}/pybls21/exceptions.py

@@ -14,3 +14,7 @@ class ModbusCommunicationException(S21Error):
 
     Transport exceptions are retained as ``__cause__`` when wrapped.
     """
+
+
+class DiscoveryError(S21Error):
+    """UDP discovery failed due to a socket error; the cause is retained."""

{pybls21-5.0.0 → pybls21-5.1.0/pybls21.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybls21
-Version: 5.0.0
+Version: 5.1.0
 Summary: Async Modbus TCP client for Blauberg S21 ventilation devices
 Author-email: Julius Vitkauskas <zadintuvas@gmail.com>
 License-Expression: MIT
@@ -94,9 +94,55 @@ identity, exceptions, and Home Assistant component migration.
 
 Booleans are not accepted as numeric control values. Bad arguments raise
 `ValueError` before network I/O. `S21Error` is the base for
-`UnsupportedDeviceException` and `ModbusCommunicationException`; the latter
+`UnsupportedDeviceException`, `DiscoveryError`, and `ModbusCommunicationException`; the latter
 includes transport errors and timeouts, retaining the original cause.
 
+## Discovering devices
+
+```python
+from pybls21 import discover, S21Client
+
+# Broadcast one read-only UDP request and collect replies for three seconds.
+devices = await discover()
+for device in devices:
+    print(device.device_id, device.host)
+    snapshot = await S21Client(device.host).poll()
+
+# Optional: target a subnet, choose a local interface, or query a known host.
+devices = await discover(address="192.168.1.255", local_address="192.168.1.10")
+devices = await discover(address="192.168.1.149", timeout=1.0)
+```
+
+`discover()` returns a tuple of immutable `DiscoveredDevice` objects with `host`
+and `device_id`. It collects replies for the whole timeout, deduplicates by
+controller ID (keeping the first address received), and sorts results by ID.
+No replies means an empty tuple. Invalid arguments raise `ValueError`; socket
+failures raise `DiscoveryError`, a subclass of `S21Error`, retaining the cause.
+Cancellation propagates and closes the socket. No background tasks are left running.
+
+Discovery uses IPv4 UDP port **4000**, independently of Modbus TCP port **502**.
+It sends a parameter-read request for controller ID and device type using an
+empty password. Replies must have a valid checksum, matching controller IDs,
+and S21 device type 1. This was verified by unicast and broadcast against an S21
+running firmware `0.36 (2019-05-08)`; availability on other firmware is not yet
+verified. The packet format follows the manufacturer's
+[UDP protocol documentation](https://device.report/m/4ad7c8426973ad1157494cc5715f286e69d244ea3fa438d4b66851938bebf485);
+the [S21 manual](https://blaubergdata.de/Daten/Manual_S21.pdf) describes the app's
+network-search feature.
+
+The default broadcast address is `255.255.255.255`; it normally reaches only the
+local subnet. On a host with multiple network interfaces, call discovery for
+each desired interface using `local_address` and, if necessary, its subnet's
+broadcast address. Arguments accept IPv4 addresses, not hostnames or IPv6.
+Firewalls and network isolation can prevent replies; manual host configuration
+remains supported. Discovery does not automatically run when creating a client.
+
+The controller ID is a device-provided identifier that applications can use
+across IP changes. It is separate from `ClimateDevice` and does not change
+existing polling or entity IDs. UDP replies are not authenticated; validate a
+candidate with `S21Client.poll()` before setting up the device. No device settings
+are written and no password is needed for discovery on the tested unit.
+
 ## Additional readings
 
 `await client.poll()` also returns extract and exhaust air temperatures

{pybls21-5.0.0 → pybls21-5.1.0}/pybls21.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ pybls21/__init__.py
 pybls21/_decoder.py
 pybls21/client.py
 pybls21/constants.py
+pybls21/discovery.py
 pybls21/exceptions.py
 pybls21/models.py
 pybls21/py.typed
@@ -18,5 +19,6 @@ pybls21.egg-info/requires.txt
 pybls21.egg-info/top_level.txt
 tests/test_client.py
 tests/test_decoder.py
+tests/test_discovery.py
 tests/test_lifecycle.py
 tests/test_models.py

{pybls21-5.0.0 → pybls21-5.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pybls21"
-version = "5.0.0"
+version = "5.1.0"
 description = "Async Modbus TCP client for Blauberg S21 ventilation devices"
 readme = "README.md"
 requires-python = ">=3.14.2"

pybls21-5.1.0/tests/test_discovery.py

@@ -0,0 +1,233 @@
+"""UDP discovery framing, real loopback I/O, and resource lifecycle tests."""
+
+import asyncio
+import socket
+import unittest
+from dataclasses import FrozenInstanceError
+from unittest.mock import AsyncMock, Mock, patch
+
+from pybls21 import DiscoveredDevice, DiscoveryError, S21Error, discover
+from pybls21.discovery import _parse_response
+
+# Captured from the physical S21, firmware 0.36 (2019-05-08).
+CAPTURED = bytes.fromhex(
+    "fdfd0210303032343030353433333337353130370006"
+    "fe02b90100fe107c30303234303035343333333735313037b409"
+)
+IDENTITY = b"0024005433375107"
+
+
+def frame(body):
+    return b"\xfd\xfd" + body + sum(body).to_bytes(2, "little")
+
+
+def response(parameters=None, identity=IDENTITY, password=b"", function=6):
+    if parameters is None:
+        parameters = b"\xfe\x02\xb9\x01\x00\xfe\x10\x7c" + identity
+    return frame(
+        b"\x02\x10"
+        + identity
+        + bytes([len(password)])
+        + password
+        + bytes([function])
+        + parameters
+    )
+
+
+class TestDiscoveryParser(unittest.TestCase):
+    def test_hardware_capture(self):
+        self.assertEqual(response(), CAPTURED)
+        device = _parse_response(CAPTURED, "192.168.1.149")
+        self.assertEqual(
+            device,
+            DiscoveredDevice(host="192.168.1.149", device_id=IDENTITY.decode()),
+        )
+        with self.assertRaises(FrozenInstanceError):
+            device.host = "192.168.1.1"
+
+    def test_parameter_order_lengths_and_unknown_parameters(self):
+        parameters = (
+            b"\xfe\x10\x7c"
+            + IDENTITY
+            + b"\x42\x09"  # Unknown, default one-byte value.
+            + b"\xff\x01\xb9\x42"  # Different page, not device type.
+            + b"\xff\x00\xfe\x02\xb9\x01\x00"
+        )
+        self.assertIsNotNone(
+            _parse_response(response(parameters, password=b"1111"), "127.0.0.1")
+        )
+
+    def test_rejects_bad_header_checksum_identity_and_other_devices(self):
+        good_params = b"\xfe\x02\xb9\x01\x00\xfe\x10\x7c" + IDENTITY
+        bad_packets = [
+            b"",
+            CAPTURED[:-1],
+            CAPTURED + b"\x00",
+            b"\x00" * 257,
+            frame(b"\x03" + CAPTURED[3:-2]),
+            frame(b"\x02\x0f" + CAPTURED[4:-2]),
+            response(identity=b"DEFAULT_DEVICEID"),
+            response(identity=b"\xff" * 16),
+            response(password=b"123456789"),
+            frame(b"\x02\x10" + IDENTITY + b"\x08\x00\x00"),
+            response(function=1),
+            response(b"\xfe\x10\x7c" + IDENTITY),
+            response(b"\xfe\x02\xb9\x03\x00\xfe\x10\x7c" + IDENTITY),
+            response(b"\xb9\x01\xfe\x10\x7c" + IDENTITY),
+            response(good_params[:-1] + b"8"),
+            response(good_params + b"\xfe\x02\xb9\x01\x00"),
+        ]
+        for packet in bad_packets:
+            with self.subTest(packet=packet):
+                self.assertIsNone(_parse_response(packet, "127.0.0.1"))
+
+    def test_rejects_truncated_or_invalid_parameter_blocks(self):
+        for suffix in (
+            b"\xff",
+            b"\xfe",
+            b"\xfe\x10",
+            b"\xfe\x10\x7cshort",
+            b"\xfe\x00\x01",
+            b"\xfc",
+            b"\xfd\x7c",
+            b"\xfe\x01\xff\x00",
+        ):
+            with self.subTest(suffix=suffix):
+                self.assertIsNone(_parse_response(response(suffix), "127.0.0.1"))
+
+
+class TestDiscovery(unittest.IsolatedAsyncioTestCase):
+    async def asyncSetUp(self):
+        self.server = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.server.setblocking(False)
+        self.server.bind(("127.0.0.1", 0))
+        self.addCleanup(self.server.close)
+        patcher = patch(
+            "pybls21.discovery._DISCOVERY_PORT", self.server.getsockname()[1]
+        )
+        patcher.start()
+        self.addCleanup(patcher.stop)
+        self.loop = asyncio.get_running_loop()
+
+    async def test_collects_multiple_devices_deduplicates_and_ignores_noise(self):
+        async def answer():
+            request, sender = await self.loop.sock_recvfrom(self.server, 1024)
+            # Exact wire contract: read only, empty password, ID and type queries.
+            self.assertEqual(
+                request,
+                bytes.fromhex("fdfd021044454641554c545f444556494345494400017cb9e905"),
+            )
+            for packet in (
+                b"garbage",
+                response(identity=b"0024005433379999"),
+                CAPTURED,
+                CAPTURED,
+            ):
+                await self.loop.sock_sendto(self.server, packet, sender)
+            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as wrong_port:
+                wrong_port.sendto(response(identity=b"0024005433370000"), sender)
+
+        responder = asyncio.create_task(answer())
+        try:
+            devices = await discover(
+                address="127.0.0.1", local_address="127.0.0.1", timeout=0.1
+            )
+            await asyncio.wait_for(responder, 1)
+        finally:
+            responder.cancel()
+            await asyncio.gather(responder, return_exceptions=True)
+        self.assertEqual(
+            [d.device_id for d in devices], [IDENTITY.decode(), "0024005433379999"]
+        )
+        self.assertTrue(all(d.host == "127.0.0.1" for d in devices))
+
+    async def test_silence_returns_empty_tuple(self):
+        self.assertEqual(await discover(address="127.0.0.1", timeout=0.02), ())
+
+    async def test_cancellation_closes_socket(self):
+        original = socket.socket
+        sockets = []
+
+        def factory(*args, **kwargs):
+            sock = original(*args, **kwargs)
+            sockets.append(sock)
+            return sock
+
+        with patch("pybls21.discovery.socket.socket", side_effect=factory):
+            task = asyncio.create_task(discover(address="127.0.0.1", timeout=30))
+            try:
+                await asyncio.wait_for(self.loop.sock_recvfrom(self.server, 1024), 1)
+            finally:
+                task.cancel()
+                with self.assertRaises(asyncio.CancelledError):
+                    await task
+        self.assertEqual(sockets[0].fileno(), -1)
+
+    async def test_invalid_arguments_do_not_open_socket(self):
+        for kwargs in (
+            *(
+                {"timeout": value}
+                for value in (0, -1, True, float("nan"), float("inf"), "3", None)
+            ),
+            {"address": "example.org"},
+            {"address": "::1"},
+            {"local_address": "not-an-ip"},
+            {"address": 123},
+            {"local_address": None},
+        ):
+            with (
+                self.subTest(kwargs=kwargs),
+                patch("pybls21.discovery.socket.socket") as factory,
+            ):
+                with self.assertRaises(ValueError):
+                    await discover(**kwargs)
+                factory.assert_not_called()
+
+    async def test_socket_errors_are_wrapped_and_close_socket(self):
+        for stage in ("create", "bind", "send", "receive", "socket_timeout"):
+            error = (
+                TimeoutError("socket timeout")
+                if stage == "socket_timeout"
+                else OSError("network unavailable")
+            )
+            sock = Mock()
+            sock.__enter__ = Mock(return_value=sock)
+            sock.__exit__ = Mock(return_value=False)
+            factory = Mock(return_value=sock)
+            send = AsyncMock()
+            receive = AsyncMock()
+            if stage == "create":
+                factory.side_effect = error
+            elif stage == "bind":
+                sock.bind.side_effect = error
+            elif stage == "send":
+                send.side_effect = error
+            else:
+                receive.side_effect = error
+            with (
+                self.subTest(stage=stage),
+                patch("pybls21.discovery.socket.socket", factory),
+                patch.object(self.loop, "sock_sendto", send),
+                patch.object(self.loop, "sock_recvfrom", receive),
+            ):
+                with self.assertRaises(DiscoveryError) as caught:
+                    await discover()
+                self.assertIsInstance(caught.exception, S21Error)
+                self.assertIs(caught.exception.__cause__, error)
+                if stage != "create":
+                    sock.__exit__.assert_called_once()
+
+    async def test_deadline_includes_send_and_closes_socket(self):
+        sock = Mock()
+        sock.__enter__ = Mock(return_value=sock)
+        sock.__exit__ = Mock(return_value=False)
+
+        async def blocked_send(*args):
+            await asyncio.Event().wait()
+
+        with (
+            patch("pybls21.discovery.socket.socket", return_value=sock),
+            patch.object(self.loop, "sock_sendto", side_effect=blocked_send),
+        ):
+            self.assertEqual(await discover(timeout=0.01), ())
+        sock.__exit__.assert_called_once()