python-broadlink 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

broadlink/__init__.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
 """The python-broadlink library."""
+
+import contextlib
 from collections.abc import AsyncIterator
-from typing import List, Optional, Tuple, Union
+from typing import Optional, Union
 
 from . import exceptions as e
 from .alarm import S1C
@@ -223,8 +225,8 @@ SUPPORTED_TYPES = {
 
 def gendevice(
     dev_type: int,
-    host: Tuple[str, int],
-    mac: Union[bytes, str],
+    host: tuple[str, int],
+    mac: bytes | str,
     name: str = "",
     is_locked: bool = False,
 ) -> Device:
@@ -258,12 +260,15 @@ async def hello(
 
     Useful if the device is locked.
     """
-    async for device in xdiscover(
-        timeout=timeout,
-        discover_ip_address=ip_address,
-        discover_ip_port=port,
-    ):
-        return device
+    async with contextlib.aclosing(
+        xdiscover(
+            timeout=timeout,
+            discover_ip_address=ip_address,
+            discover_ip_port=port,
+        )
+    ) as devices:
+        async for device in devices:
+            return device
     raise e.NetworkTimeoutError(
         -4000,
         "Network timeout",
@@ -273,10 +278,10 @@ async def hello(
 
 async def discover(
     timeout: float = DEFAULT_TIMEOUT,
-    local_ip_address: Optional[str] = None,
+    local_ip_address: str | None = None,
     discover_ip_address: str = DEFAULT_BCAST_ADDR,
     discover_ip_port: int = DEFAULT_PORT,
-) -> List[Device]:
+) -> list[Device]:
     """Discover devices connected to the local network."""
     return [
         device
@@ -288,7 +293,7 @@ async def discover(
 
 async def xdiscover(
     timeout: float = DEFAULT_TIMEOUT,
-    local_ip_address: Optional[str] = None,
+    local_ip_address: str | None = None,
     discover_ip_address: str = DEFAULT_BCAST_ADDR,
     discover_ip_port: int = DEFAULT_PORT,
 ) -> AsyncIterator[Device]:

broadlink/alarm.py

@@ -1,4 +1,5 @@
 """Support for alarm kits."""
+
 from . import exceptions as e
 from .device import Device
 

broadlink/climate.py

@@ -1,7 +1,8 @@
 """Support for climate control."""
+
 import enum
 import struct
-from typing import List, Sequence
+from collections.abc import Sequence
 
 from . import exceptions as e
 from .device import Device
@@ -33,7 +34,7 @@ class hysen(Device):
         payload = self.decrypt(response[0x38:])
 
         p_len = int.from_bytes(payload[:0x02], "little")
-        nom_crc = int.from_bytes(payload[p_len:p_len+2], "little")
+        nom_crc = int.from_bytes(payload[p_len : p_len + 2], "little")
         real_crc = CRC16.calculate(payload[0x02:p_len])
 
         if nom_crc != real_crc:
@@ -83,9 +84,7 @@ class hysen(Device):
         data["dif"] = payload[10]
         data["svh"] = payload[11]
         data["svl"] = payload[12]
-        data["room_temp_adj"] = (
-            int.from_bytes(payload[13:15], "big", signed=True) / 10.0
-        )
+        data["room_temp_adj"] = int.from_bytes(payload[13:15], "big", signed=True) / 10.0
         data["fre"] = payload[15]
         data["poweron"] = payload[16]
         data["unknown"] = payload[17]
@@ -127,9 +126,7 @@ class hysen(Device):
     # E.g. loop_mode = 0 ("12345,67") means Saturday and Sunday (weekend schedule)
     # loop_mode = 2 ("1234567") means every day, including Saturday and Sunday (weekday schedule)
     # The sensor command is currently experimental
-    async def set_mode(
-        self, auto_mode: int, loop_mode: int, sensor: int = 0
-    ) -> None:
+    async def set_mode(self, auto_mode: int, loop_mode: int, sensor: int = 0) -> None:
         """Set the mode of the device."""
         mode_byte = ((loop_mode + 1) << 4) + auto_mode
         await self.send_request([0x01, 0x06, 0x00, 0x02, mode_byte, sensor])
@@ -210,19 +207,7 @@ class hysen(Device):
     async def set_time(self, hour: int, minute: int, second: int, day: int) -> None:
         """Set the time."""
         await self.send_request(
-            [
-                0x01,
-                0x10,
-                0x00,
-                0x08,
-                0x00,
-                0x02,
-                0x04,
-                hour,
-                minute,
-                second,
-                day
-            ]
+            [0x01, 0x10, 0x00, 0x08, 0x00, 0x02, 0x04, hour, minute, second, day]
         )
 
     # Set timer schedule
@@ -231,7 +216,7 @@ class hysen(Device):
     # {'start_hour':17, 'start_minute':30, 'temp': 22 }
     # Each one specifies the thermostat temp that will become effective at start_hour:start_minute
     # weekend is similar but only has 2 (e.g. switch on in morning and off in afternoon)
-    async def set_schedule(self, weekday: List[dict], weekend: List[dict]) -> None:
+    async def set_schedule(self, weekday: list[dict], weekend: list[dict]) -> None:
         """Set timer schedule."""
         request = [0x01, 0x10, 0x00, 0x0A, 0x00, 0x0C, 0x18]
 
@@ -317,9 +302,7 @@ class hvac(Device):
         """Encode data for transport."""
         packet = bytearray(10)
         p_len = 10 + len(data)
-        struct.pack_into(
-            "<HHHHH", packet, 0, p_len, 0x00BB, 0x8006, 0, len(data)
-        )
+        struct.pack_into("<HHHHH", packet, 0, p_len, 0x00BB, 0x8006, 0, len(data))
         packet += data
         crc = CRC16.calculate(packet[0x02:], polynomial=0x9BE4)
         packet += crc.to_bytes(2, "little")
@@ -330,7 +313,7 @@ class hvac(Device):
         # payload[0x2:0x8] == bytes([0xbb, 0x00, 0x07, 0x00, 0x00, 0x00])
         payload = self.decrypt(response[0x38:])
         p_len = int.from_bytes(payload[:0x02], "little")
-        nom_crc = int.from_bytes(payload[p_len:p_len+2], "little")
+        nom_crc = int.from_bytes(payload[p_len : p_len + 2], "little")
         real_crc = CRC16.calculate(payload[0x02:p_len], polynomial=0x9BE4)
 
         if nom_crc != real_crc:
@@ -341,7 +324,7 @@ class hvac(Device):
             )
 
         d_len = int.from_bytes(payload[0x08:0x0A], "little")
-        return payload[0x0A:0x0A+d_len]
+        return payload[0x0A : 0x0A + d_len]
 
     async def _send(self, command: int, data: bytes = b"") -> bytes:
         """Send a command to the unit."""

broadlink/const.py

@@ -1,4 +1,5 @@
 """Constants."""
+
 DEFAULT_BCAST_ADDR = "255.255.255.255"
 DEFAULT_PORT = 80
 DEFAULT_RETRY_INTVL = 1

broadlink/cover.py

@@ -1,6 +1,7 @@
 """Support for covers."""
+
 import asyncio
-from typing import Sequence
+from collections.abc import Sequence
 
 from . import exceptions as e
 from .device import Device

broadlink/device.py

@@ -10,10 +10,12 @@ speaks unprompted, so each device keeps a single datagram endpoint and an
 from __future__ import annotations
 
 import asyncio
+import collections
+import contextlib
+import logging
 import random
 import socket
 from collections.abc import AsyncIterator
-from typing import Optional, Tuple, Union
 
 from cryptography.hazmat.backends import default_backend
 from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
@@ -27,11 +29,24 @@ from .const import (
 )
 from .protocol import Datetime
 
-HelloResponse = Tuple[int, Tuple[str, int], bytes, str, bool]
+_LOGGER = logging.getLogger(__name__)
+
+HelloResponse = tuple[int, tuple[str, int], bytes, str, bool]
 
 # Device error codes that mean the session key is no longer accepted and a
-# fresh auth() will fix it. -7: control key expired; -4012: control id error.
-_REAUTH_CODES = {-7, -4012}
+# fresh auth() will fix it. -2: logged out; -7: control key expired;
+# -4012: control id error.
+_REAUTH_CODES = {-2, -7, -4012}
+
+# How many recently used request counters to remember. A reply carrying one
+# of them (other than the current request's) is a late or duplicate answer
+# to an earlier request and is dropped rather than taken as the answer to
+# the current one. 64 covers a burst of resends comfortably and ages out
+# long before the 16-bit counter wraps.
+_RECENT_MAX = 64
+
+_CLOSED = (None, None)
+"""Sentinel put on the receive queue when the endpoint is closed."""
 
 
 class _Protocol(asyncio.DatagramProtocol):
@@ -39,8 +54,7 @@ class _Protocol(asyncio.DatagramProtocol):
 
     def __init__(self) -> None:
         self.queue: asyncio.Queue[tuple[bytes, tuple[str, int]]] = asyncio.Queue()
-        self.transport: Optional[asyncio.DatagramTransport] = None
-        self.closed = asyncio.get_running_loop().create_future()
+        self.transport: asyncio.DatagramTransport | None = None
 
     def connection_made(self, transport) -> None:  # type: ignore[override]
         self.transport = transport
@@ -53,9 +67,8 @@ class _Protocol(asyncio.DatagramProtocol):
         # the retry loop will time out and raise NetworkTimeoutError.
         pass
 
-    def connection_lost(self, exc: Optional[Exception]) -> None:
-        if not self.closed.done():
-            self.closed.set_result(None)
+    def connection_lost(self, exc: Exception | None) -> None:
+        pass
 
     def drain(self) -> None:
         """Drop anything that arrived before the current request."""
@@ -64,8 +77,8 @@ class _Protocol(asyncio.DatagramProtocol):
 
 
 async def _open_endpoint(
-    local_addr: Optional[tuple[str, int]] = None,
-    remote_addr: Optional[tuple[str, int]] = None,
+    local_addr: tuple[str, int] | None = None,
+    remote_addr: tuple[str, int] | None = None,
     broadcast: bool = False,
 ) -> tuple[asyncio.DatagramTransport, _Protocol]:
     """Create a UDP endpoint. Tests replace this to fake the network."""
@@ -101,7 +114,7 @@ def _parse_hello(resp: bytes, host: tuple[str, int]) -> HelloResponse:
 
 async def scan(
     timeout: float = DEFAULT_TIMEOUT,
-    local_ip_address: Optional[str] = None,
+    local_ip_address: str | None = None,
     discover_ip_address: str = DEFAULT_BCAST_ADDR,
     discover_ip_port: int = DEFAULT_PORT,
 ) -> AsyncIterator[HelloResponse]:
@@ -134,7 +147,7 @@ async def scan(
                     break
                 try:
                     resp, host = await asyncio.wait_for(protocol.queue.get(), remaining)
-                except asyncio.TimeoutError:
+                except TimeoutError:
                     break
                 if len(resp) < 0x80:
                     continue
@@ -174,8 +187,8 @@ class Device:
 
     def __init__(
         self,
-        host: Tuple[str, int],
-        mac: Union[bytes, str],
+        host: tuple[str, int],
+        mac: bytes | str,
         devtype: int,
         timeout: float = DEFAULT_TIMEOUT,
         name: str = "",
@@ -200,39 +213,32 @@ class Device:
         self.aes = None
         self.update_aes(bytes.fromhex(self.__INIT_KEY))
 
-        self._lock: Optional[asyncio.Lock] = None
-        self._transport: Optional[asyncio.DatagramTransport] = None
-        self._protocol: Optional[_Protocol] = None
-        self._reauth_ok = True
+        self._lock: asyncio.Lock | None = None
+        self._transport: asyncio.DatagramTransport | None = None
+        self._protocol: _Protocol | None = None
+        self._endpoint_addr: tuple[str, int] | None = None
+        self._recent: collections.deque[int] = collections.deque(maxlen=_RECENT_MAX)
+        self._reauth_lock: asyncio.Lock | None = None
+        self._auth_generation = 0
 
     def __repr__(self) -> str:
         """Return a formal representation of the device."""
         return (
-            "%s.%s(%s, mac=%r, devtype=%r, timeout=%r, name=%r, "
-            "model=%r, manufacturer=%r, is_locked=%r)"
-        ) % (
-            self.__class__.__module__,
-            self.__class__.__qualname__,
-            self.host,
-            self.mac,
-            self.devtype,
-            self.timeout,
-            self.name,
-            self.model,
-            self.manufacturer,
-            self.is_locked,
+            f"{self.__class__.__module__}.{self.__class__.__qualname__}("
+            f"{self.host}, mac={self.mac!r}, devtype={self.devtype!r}, "
+            f"timeout={self.timeout!r}, name={self.name!r}, "
+            f"model={self.model!r}, manufacturer={self.manufacturer!r}, "
+            f"is_locked={self.is_locked!r})"
         )
 
     def __str__(self) -> str:
         """Return a readable representation of the device."""
-        return "%s (%s / %s:%s / %s)" % (
-            self.name or "Unknown",
-            " ".join(filter(None, [self.manufacturer, self.model, hex(self.devtype)])),
-            *self.host,
-            ":".join(format(x, "02X") for x in self.mac),
-        )
+        ident = " ".join(filter(None, [self.manufacturer, self.model, hex(self.devtype)]))
+        mac = ":".join(format(x, "02X") for x in self.mac)
+        name = self.name or "Unknown"
+        return f"{name} ({ident} / {self.host[0]}:{self.host[1]} / {mac})"
 
-    async def __aenter__(self) -> "Device":
+    async def __aenter__(self) -> Device:
         return self
 
     async def __aexit__(self, *exc) -> None:
@@ -259,22 +265,31 @@ class Device:
     # ---------------------------------------------------------- session
 
     async def auth(self) -> bool:
-        """Authenticate to the device."""
-        self.id = 0
-        self.update_aes(bytes.fromhex(self.__INIT_KEY))
+        """Authenticate to the device.
 
+        The session reset, the exchange and the install of the new key all
+        happen while holding the request lock, so a request queued behind
+        the lock is never framed with the initial key or device id 0.
+        """
         packet = bytearray(0x50)
         packet[0x04:0x14] = [0x31] * 16
         packet[0x1E] = 0x01
         packet[0x2D] = 0x01
-        packet[0x30:0x36] = "Test 1".encode()
-
-        response = await self.send_packet(0x65, packet, _reauth=False)
-        e.check_error(response[0x22:0x24])
-        payload = self.decrypt(response[0x38:])
+        packet[0x30:0x36] = b"Test 1"
 
-        self.id = int.from_bytes(payload[:0x4], "little")
-        self.update_aes(payload[0x04:0x14])
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+            self._reauth_lock = asyncio.Lock()
+        async with self._lock:
+            self.id = 0
+            self.update_aes(bytes.fromhex(self.__INIT_KEY))
+            response = await self._exchange(self._frame(0x65, bytes(packet)))
+            e.check_error(response[0x22:0x24])
+            payload = self.decrypt(response[0x38:])
+            self.id = int.from_bytes(payload[:0x4], "little")
+            self.update_aes(payload[0x04:0x14])
+            self._auth_generation += 1
+        _LOGGER.debug("%s: authenticated, session id %d", self.host[0], self.id)
         return True
 
     async def hello(self, local_ip_address=None) -> bool:
@@ -282,15 +297,17 @@ class Device:
 
         Device information is checked before updating name and lock status.
         """
-        responses = scan(
-            timeout=self.timeout,
-            local_ip_address=local_ip_address,
-            discover_ip_address=self.host[0],
-            discover_ip_port=self.host[1],
-        )
         entry = None
-        async for entry in responses:
-            break
+        async with contextlib.aclosing(
+            scan(
+                timeout=self.timeout,
+                local_ip_address=local_ip_address,
+                discover_ip_address=self.host[0],
+                discover_ip_port=self.host[1],
+            )
+        ) as responses:
+            async for entry in responses:  # noqa: B007 - first reply only
+                break
         if entry is None:
             raise e.NetworkTimeoutError(
                 -4000,
@@ -363,17 +380,30 @@ class Device:
     # -------------------------------------------------------- transport
 
     async def aclose(self) -> None:
-        """Close the device's endpoint. It is reopened on the next call."""
-        if self._transport is not None:
-            self._transport.close()
-            self._transport = None
-            self._protocol = None
+        """Close the device's endpoint. It is reopened on the next call.
+
+        A request in flight fails at once with ``ConnectionClosedError``
+        rather than waiting out its timeout.
+        """
+        transport, protocol = self._transport, self._protocol
+        self._transport = None
+        self._protocol = None
+        self._endpoint_addr = None
+        if transport is not None:
+            transport.close()
+            _LOGGER.debug("%s: endpoint closed", self.host[0])
+        if protocol is not None:
+            protocol.queue.put_nowait(_CLOSED)  # type: ignore[arg-type]
 
     async def _endpoint(self) -> tuple[asyncio.DatagramTransport, _Protocol]:
+        if self._transport is not None and self._endpoint_addr != self.host:
+            # The caller changed host; the connected socket points at the
+            # old address, so drop it.
+            await self.aclose()
         if self._transport is None or self._transport.is_closing():
-            self._transport, self._protocol = await _open_endpoint(
-                remote_addr=self.host
-            )
+            self._transport, self._protocol = await _open_endpoint(remote_addr=self.host)
+            self._endpoint_addr = self.host
+            _LOGGER.debug("%s: endpoint opened", self.host[0])
         return self._transport, self._protocol  # type: ignore[return-value]
 
     def _frame(self, packet_type: int, payload: bytes) -> bytes:
@@ -419,52 +449,85 @@ class Device:
         return resp
 
     async def _exchange(self, packet: bytes) -> bytes:
-        """Send one frame and wait for one reply, resending on silence."""
+        """Send one frame and wait for its reply, resending on silence.
+
+        Replies carry the request's packet counter (offset 0x28), so a reply
+        is matched to the request by counter. A reply whose counter belongs
+        to any other recent request (a late answer, or the second answer to
+        a request that was resent) is dropped; one with a counter this
+        device has not used recently is accepted, for firmware that may not
+        echo it.
+        """
         transport, protocol = await self._endpoint()
         protocol.drain()
         loop = asyncio.get_running_loop()
         start = loop.time()
         timeout = self.timeout
+        count = int.from_bytes(packet[0x28:0x2A], "little")
+        self._recent.append(count)
+        sends = 0
 
         while True:
             transport.sendto(packet)
-            time_left = timeout - (loop.time() - start)
-            wait = min(DEFAULT_RETRY_INTVL, time_left)
-            try:
-                resp, _ = await asyncio.wait_for(protocol.queue.get(), max(wait, 0))
-            except asyncio.TimeoutError:
-                if (loop.time() - start) >= timeout:
-                    raise e.NetworkTimeoutError(
-                        -4000,
-                        "Network timeout",
-                        f"No response received within {timeout}s",
-                    ) from None
-                continue
-            return self._validate(resp)
-
-    async def send_packet(
-        self, packet_type: int, payload: bytes, *, _reauth: bool = True
-    ) -> bytes:
+            sends += 1
+            if sends > 1:
+                _LOGGER.debug("%s: no reply, resending (%d)", self.host[0], sends)
+            resend_at = loop.time() + DEFAULT_RETRY_INTVL
+            while True:
+                now = loop.time()
+                if now - start >= timeout:
+                    break
+                wait = min(resend_at, start + timeout) - now
+                try:
+                    resp, _ = await asyncio.wait_for(protocol.queue.get(), max(wait, 0))
+                except TimeoutError:
+                    if loop.time() - start >= timeout:
+                        break
+                    if loop.time() >= resend_at:
+                        break  # Resend.
+                    continue
+                if resp is None:
+                    raise e.EndpointClosedError(
+                        -4013, "Endpoint closed", "The device endpoint was closed"
+                    )
+                resp = self._validate(resp)
+                reply_count = int.from_bytes(resp[0x28:0x2A], "little")
+                if reply_count == count or reply_count not in self._recent:
+                    return resp
+                _LOGGER.debug(
+                    "%s: dropped a reply for an earlier request (counter 0x%04x)",
+                    self.host[0],
+                    reply_count,
+                )
+            if loop.time() - start >= timeout:
+                _LOGGER.debug("%s: no reply within %ss", self.host[0], timeout)
+                raise e.NetworkTimeoutError(
+                    -4000,
+                    "Network timeout",
+                    f"No response received within {timeout}s",
+                ) from None
+
+    async def send_packet(self, packet_type: int, payload: bytes) -> bytes:
         """Send a packet to the device and return the raw response frame.
 
         If the device answers that the session key is no longer valid, the
         session is re-authenticated once and the request is sent again.
+        Concurrent callers that hit the same expired key share one
+        re-authentication and each retry once.
         """
         if self._lock is None:
             self._lock = asyncio.Lock()
+            self._reauth_lock = asyncio.Lock()
+        generation = self._auth_generation
         async with self._lock:
             resp = await self._exchange(self._frame(packet_type, bytes(payload)))
 
-        if _reauth and self._reauth_ok:
-            code = int.from_bytes(resp[0x22:0x24], "little", signed=True)
-            if code in _REAUTH_CODES:
-                self._reauth_ok = False
-                try:
+        code = int.from_bytes(resp[0x22:0x24], "little", signed=True)
+        if code in _REAUTH_CODES:
+            _LOGGER.debug("%s: device answered %d, re-authenticating", self.host[0], code)
+            async with self._reauth_lock:  # type: ignore[union-attr]
+                if self._auth_generation == generation:
                     await self.auth()
-                    async with self._lock:
-                        resp = await self._exchange(
-                            self._frame(packet_type, bytes(payload))
-                        )
-                finally:
-                    self._reauth_ok = True
+            async with self._lock:
+                resp = await self._exchange(self._frame(packet_type, bytes(payload)))
         return resp

broadlink/exceptions.py

@@ -1,4 +1,5 @@
 """Exceptions for Broadlink devices."""
+
 import collections
 import struct
 
@@ -22,7 +23,7 @@ class BroadlinkException(Exception):
     def __str__(self):
         """Return str(self)."""
         if self.errno is not None:
-            return "[Errno %s] %s" % (self.errno, self.strerror)
+            return f"[Errno {self.errno}] {self.strerror}"
         return self.strerror
 
     def __eq__(self, other):
@@ -42,13 +43,13 @@ class MultipleErrors(BroadlinkException):
         """Initialize the exception."""
         errors = args[0][:] if args else []
         counter = collections.Counter(errors)
-        strerror = "Multiple errors occurred: %s" % counter
+        strerror = f"Multiple errors occurred: {counter}"
         super().__init__(strerror, **kwargs)
         self.errors = errors
 
     def __repr__(self):
         """Return repr(self)."""
-        return "MultipleErrors(%r)" % self.errors
+        return f"MultipleErrors({self.errors!r})"
 
     def __str__(self):
         """Return str(self)."""
@@ -71,6 +72,16 @@ class ConnectionClosedError(BroadlinkException):
     """Connection closed error."""
 
 
+class EndpointClosedError(ConnectionClosedError):
+    """The library's own endpoint was closed while a request was in flight.
+
+    Raised locally by ``Device.aclose()``, not by the device. It is a
+    subclass of ``ConnectionClosedError`` so existing handlers still catch
+    it, and a distinct class so a caller that closed the device on purpose
+    can tell it apart from the device's "logged out" (-2) answer.
+    """
+
+
 class StructureAbnormalError(BroadlinkException):
     """Structure abnormal error."""
 
@@ -142,6 +153,7 @@ BROADLINK_EXCEPTIONS = {
     -4010: (DataValidationError, "Received encrypted data packet length error"),
     -4011: (DataValidationError, "Received encrypted data packet check error"),
     -4012: (AuthorizationError, "Device control ID error"),
+    -4013: (EndpointClosedError, "Endpoint closed"),
 }
 
 

broadlink/helpers.py

@@ -1,5 +1,6 @@
 """Helper functions and classes."""
-from typing import Dict, List, Sequence
+
+from collections.abc import Sequence
 
 
 class CRC16:
@@ -8,10 +9,10 @@ class CRC16:
     CRC tables are cached for performance.
     """
 
-    _cache: Dict[int, List[int]] = {}
+    _cache: dict[int, list[int]] = {}
 
     @classmethod
-    def get_table(cls, polynomial: int) -> List[int]:
+    def get_table(cls, polynomial: int) -> list[int]:
         """Return the CRC-16 table for a polynomial."""
         try:
             crc_table = cls._cache[polynomial]