lutron-integration 0.0.0a1__tar.gz

lutron_integration-0.0.0a1/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: lutron-integration
+Version: 0.0.0a1
+Summary: Lutron Integration Protocol client, focused on QS Standalone
+Keywords: QSE-CI-NWK-E,Lutron,QS Standalone,Grafik Eye
+Author: Andy Lutomirski
+Author-email: Andy Lutomirski <luto@kernel.org>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Maintainer: Andy Lutomirski
+Maintainer-email: Andy Lutomirski <luto@kernel.org>
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/amluto/lutron-integration
+Description-Content-Type: text/markdown
+
+# What is this? #
+
+lutron_integration is a a client library for the Lutron Integration Protocol.
+This is a protocol used by a number of different Lutron products, documented here:
+
+https://assets.lutron.com/a/documents/040249.pdf
+
+lutron_integration is intended to be able to support all dialects of the protocol,
+but it is currently primarily targetted at the "QS Standalone" dialect.  Other dialects
+are barely, if at all, implemented.
+
+If you want to set up a QS Standalone system, you need a Lutron [QSE-CI-NWK-E](https://assets.lutron.com/a/documents/369373_qse-ci-nwk-e_eng.pdf),
+at least one other Lutron device (both to make it useful and to provide power), and some appropriate wire.
+Lutron's devices are generally intended for professional installation, and they provide extensive
+documentation on their website.
+
+Programming your QSE-CI-NWK-E is outside the scope of this library, but it's fairly
+easy to do over Telnet.  (In general, a skilled Lutron installer will install a QS
+system and will install the QSE-CI-NWK-E as well if requested to do so.  They will program
+the rest of the system (which requires no proprietary software for a standalone
+system and can be done by following instructions in the manual), and they may or
+may not program the QSE-CI-NWK-E.)  Integrating some other system, e,g, whatever
+system uses this library, is the job of whoever sets up that system, i.e. you!
+
+To set it up, you will need a computer that allows you to control its IP and subnet
+settings and to set up an IP on the subnet 192.168.250.0/24, and you'll need to connect
+to 192.168.250.1/24.  You can often fudge this by connecting to the same L2 network
+that the QSE-CI-NWK-E is on, even via wifi, and adding a secondary address.
+
+- On a Mac, the command resembles `sudo ifconfig en0 alias 192.168.250.2 255.255.255.0`
+- On Linux, the command resembles `sudo ip addr add 192.168.250.2/24 dev eth0`
+- On Windows, you can use the GUI, painfully.  I'm sure there is some way to do it via Powershell or ipconfig
+
+Then you can telnet to 192.168.250.1 and configure a real IP address with
+commands like `#ETHERNET,0,[IP address]` and `#ETHERNET,1,[subnet mask]` --
+see [page 19][lip].  The QSE-CI-NWK-E does not appear to support DHCP at all,
+and Lutron recommends using static addresses even for other dialects.  Or you can
+use RS232.
+
+lutron_integration presently has no dependencies at all outside the standard library,
+and I would like to keep it that way unless there is a fairly compelling reason
+to add a dependency.
+
+# Usage #
+
+Users of this library are responsible for connecting to the integration access point
+on their own, which generally involves figuring out what IP address and TCP port
+(hint: 23) to connect to and using `await asyncio.open_connection(address, port)`
+or doing whatever incantation is appropriate on your platform to connect to a
+serial port.
+
+(Lots more to write here)
+
+lutron_integration is fully async and very strongly respects the idea of
+structured concurrency: it does not create tasks at all.  If you want the
+library do so something, you call it.  If you are not actively calling it,
+it does nothing!
+
+
+[lip]: https://assets.lutron.com/a/documents/040249.pdf

lutron_integration-0.0.0a1/README.md

@@ -0,0 +1,60 @@
+# What is this? #
+
+lutron_integration is a a client library for the Lutron Integration Protocol.
+This is a protocol used by a number of different Lutron products, documented here:
+
+https://assets.lutron.com/a/documents/040249.pdf
+
+lutron_integration is intended to be able to support all dialects of the protocol,
+but it is currently primarily targetted at the "QS Standalone" dialect.  Other dialects
+are barely, if at all, implemented.
+
+If you want to set up a QS Standalone system, you need a Lutron [QSE-CI-NWK-E](https://assets.lutron.com/a/documents/369373_qse-ci-nwk-e_eng.pdf),
+at least one other Lutron device (both to make it useful and to provide power), and some appropriate wire.
+Lutron's devices are generally intended for professional installation, and they provide extensive
+documentation on their website.
+
+Programming your QSE-CI-NWK-E is outside the scope of this library, but it's fairly
+easy to do over Telnet.  (In general, a skilled Lutron installer will install a QS
+system and will install the QSE-CI-NWK-E as well if requested to do so.  They will program
+the rest of the system (which requires no proprietary software for a standalone
+system and can be done by following instructions in the manual), and they may or
+may not program the QSE-CI-NWK-E.)  Integrating some other system, e,g, whatever
+system uses this library, is the job of whoever sets up that system, i.e. you!
+
+To set it up, you will need a computer that allows you to control its IP and subnet
+settings and to set up an IP on the subnet 192.168.250.0/24, and you'll need to connect
+to 192.168.250.1/24.  You can often fudge this by connecting to the same L2 network
+that the QSE-CI-NWK-E is on, even via wifi, and adding a secondary address.
+
+- On a Mac, the command resembles `sudo ifconfig en0 alias 192.168.250.2 255.255.255.0`
+- On Linux, the command resembles `sudo ip addr add 192.168.250.2/24 dev eth0`
+- On Windows, you can use the GUI, painfully.  I'm sure there is some way to do it via Powershell or ipconfig
+
+Then you can telnet to 192.168.250.1 and configure a real IP address with
+commands like `#ETHERNET,0,[IP address]` and `#ETHERNET,1,[subnet mask]` --
+see [page 19][lip].  The QSE-CI-NWK-E does not appear to support DHCP at all,
+and Lutron recommends using static addresses even for other dialects.  Or you can
+use RS232.
+
+lutron_integration presently has no dependencies at all outside the standard library,
+and I would like to keep it that way unless there is a fairly compelling reason
+to add a dependency.
+
+# Usage #
+
+Users of this library are responsible for connecting to the integration access point
+on their own, which generally involves figuring out what IP address and TCP port
+(hint: 23) to connect to and using `await asyncio.open_connection(address, port)`
+or doing whatever incantation is appropriate on your platform to connect to a
+serial port.
+
+(Lots more to write here)
+
+lutron_integration is fully async and very strongly respects the idea of
+structured concurrency: it does not create tasks at all.  If you want the
+library do so something, you call it.  If you are not actively calling it,
+it does nothing!
+
+
+[lip]: https://assets.lutron.com/a/documents/040249.pdf

lutron_integration-0.0.0a1/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "lutron-integration"
+version = "0.0.0a1"
+description = "Lutron Integration Protocol client, focused on QS Standalone"
+authors = [
+  {name = "Andy Lutomirski", email = "luto@kernel.org"}
+]
+maintainers = [
+  {name = "Andy Lutomirski", email = "luto@kernel.org"}
+]
+license = "MIT"
+keywords = ["QSE-CI-NWK-E", "Lutron", "QS Standalone", "Grafik Eye"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/amluto/lutron-integration"
+
+[build-system]
+requires = ["uv_build >= 0.9.8, <0.10.0"]
+build-backend = "uv_build"

lutron_integration-0.0.0a1/src/lutron_integration/connection.py

@@ -0,0 +1,457 @@
+import asyncio
+from dataclasses import dataclass
+import re
+import collections
+from collections.abc import Callable, Iterable
+import logging
+from . import types
+
+_LOGGER = logging.getLogger(__name__)
+
+# A message we received that, when converted to uppercase,
+# starts with one of these prefixes, is considered to be a synchronous
+# reply to a query.  Additionally, the empty string is a synchronous
+# reply.  We consider a query to be answered when we receive a synchronous
+# reply followed by a prompt.
+#
+# This appears to be completely reliably on QSE-CI-NWK-E with one
+# exception: #OUTPUT and ?OUTPUT commands, at least on verrsion
+# 8.60, produce no output per se.  The NWK sends a ~OUTPUT, but
+# that's entirely indistinguishable from an *unsolicited* message.
+#
+# The best solution found so far is to avoid ever sending #OUTPUT
+# or ?OUTPUT, which, conveniently, is never necessary on QS
+# standalone, as #DEVICE and ?DEVICE handle all cases and more.
+_REPLY_PREFIXES = [
+    b"~DETAILS",
+    b"~ERROR",
+    b"~INTEGRATIONID",
+    b"~PROGRAMMING",
+    b"~ETHERNET",
+    b"~MONITORING",
+]
+
+
+class LoginError(Exception):
+    """Exception raised when login fails."""
+
+    message: bytes
+
+    def __init__(self, message: bytes) -> None:
+        self.message = message
+        super().__init__(message.decode("utf-8", errors="replace"))
+
+
+class ProtocolError(Exception):
+    """Exception raised when the protocol doesn't parse correctly."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(str)
+
+
+class DisconnectedError(Exception):
+    """Exception raised when we aren't connected."""
+
+    def __init__(self) -> None:
+        super().__init__("Disconnected")
+
+
+@dataclass
+class _Conn:
+    r: asyncio.StreamReader
+    w: asyncio.StreamWriter
+
+
+@dataclass
+class _CurrentQuery:
+    reply: None | bytes
+    unsolicited_messages: None | list[bytes]
+
+
+# Monitoring messages may be arbitrarily interspersed with actual replies, and
+# there is no mechanism in the protocol to tell which messages are part of a reply vs.
+# which are asynchronously received monitoring messages.
+#
+# On the bright side, once we enable prompts, we at least know that all direct
+# replies to queries (critically, ?DETAILS) will be received before the QSE>
+# prompt.  However, we do not know *which* QSE> prompt they preceed because
+# unsolicited messages end with '\r\nQSE>'.  Thanks, Lutron.
+#
+# We manage to parse the protocol by observing that the incoming stream is a
+# stream of messages where each message either ends with b'\r\nQSE>' or
+# is just b'QSE>' (no newline).  We further observe that no actual logical
+# line of the protocol can start with a Q (everything starts with ~), so
+# we can't get confused by a stray Q at the start of a line.
+#
+# This does not handle the #PASSWD flow.
+
+
+class LutronConnection:
+    """Represents an established Lutron connection."""
+
+    __lock: asyncio.Lock
+    __cond: asyncio.Condition
+
+    __conn: _Conn | None  # TODO: There is no value to ever nulling this out
+    __prompt_prefix: bytes
+
+    # Unsolicited messages that we have read are enqueued at the
+    # end of __unsolicited_queue and are popped from the front.
+    #
+    # Protected by __lock
+    __unsolicited_queue: collections.deque[bytes]
+
+    # While running a query, this is not None and it contains the
+    # collected results
+    #
+    # Protected by __lock
+    __current_query: _CurrentQuery | None
+
+    # Are we currently reading?  The login code does not count.
+    #
+    # Protected by __lock
+    __currently_reading: bool
+
+    # Only used by __read_one_message(), which is never called
+    # concurrently with itself.
+    __buffered_byte: bytes
+
+    # This lock serves (solely) to prevent raw_query() from being called
+    # concurrently with itself.
+    __query_lock: asyncio.Lock
+
+    # TODO: We should possibly track when we are in a bad state and quickly fail future operations
+
+    def __init__(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        self.__conn = _Conn(reader, writer)
+        self.__lock = asyncio.Lock()
+        self.__cond = asyncio.Condition(self.__lock)
+        self.__unsolicited_queue = collections.deque()
+        self.__buffered_byte = b""
+        self.__query_lock = asyncio.Lock()
+
+    @classmethod
+    async def create_from_connnection(
+        cls, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> "LutronConnection":
+        self = LutronConnection(reader, writer)
+        assert self.__conn is not None
+
+        # When we first connect, the MONITORING state is uknown, which is rather annoying.
+        # To function sensibly, we need:
+        #
+        # Diagnostic Monitoring (1): otherwise errors will be ignored and we won't find out about them
+        # Reply State (11): Queries will never be answered if this is off
+        # Prompt State (12): The prompt is how we tell that the system has finished processing a request
+        #
+        # And, awkwardly, until we set these, we might be in a state where the system
+        # is entirely silent, and we don't really know what replies to expect.
+
+        # Send the commands to enable the above monitoring modes
+        self.__conn.w.write(
+            b"".join(b"#MONITORING,%d,1\r\n" % mode for mode in (1, 11, 12))
+        )
+
+        # In response, we really have no idea what to expect, except that there really ought
+        # be at least one prompt.  So we'll do an outrageous cheat and send a command with
+        # a known reply that we wouldn't otherwise see so we can wait for it.
+        self.__conn.w.write(b"?MONITORING,2\r\n")
+
+        await self.__conn.r.readuntil(b"~MONITORING,2,")
+        data = await self.__conn.r.readuntil(b">")
+
+        m = re.fullmatch(b"\\d\r\n([A-Za-z0-9]+)>", data)
+        if not m:
+            raise ProtocolError(
+                f"Could not parse {(b'~MONITORING,2,' + data + b'>')!r} as a monitoring ping reply"
+            )
+        self.__prompt_prefix = m[1]
+
+        self.__currently_reading = False
+        self.__current_query = None
+
+        return self
+
+    # This returns the protocol name as inferred from the prompt.
+    # For example, QS Standalong is b'QSE'.
+    @property
+    def protocol_name(self) -> bytes:
+        return self.__prompt_prefix
+
+    # This is the meat of the reader.  This function is the only thing that reads from
+    # the underlying StreamReader, and it is never called concurrently.
+    #
+    # We don't use cancellation ourselves, but we want to recover cleanly from
+    # a client cancelling a call, which means that we can never await something
+    # that might result in a cancellation while we are storing data that
+    # we've read in a local variable.
+    async def __read_one_message(self) -> bytes:
+        assert self.__currently_reading
+        # This needs to be cancelable and then runnable again without losing data
+        assert self.__conn is not None
+        if not self.__buffered_byte:
+            self.__buffered_byte = await self.__conn.r.read(1)
+
+            if not self.__buffered_byte:
+                # We got EOF.
+                raise DisconnectedError()
+
+        if self.__buffered_byte == self.__prompt_prefix[0:1]:
+            # We got Q and expect SE>
+            expected = self.__prompt_prefix[1:] + b">"
+            data = await self.__conn.r.readexactly(len(expected))
+            if data != expected:
+                raise ProtocolError(f"Expected {expected!r} but received {data!r}")
+            self.__buffered_byte = b""
+            return b""
+        else:
+            # We got the first byte of a message and expect the rest of it
+            # followed by b'\r\nQSE>'
+            data = await self.__conn.r.readuntil(b"\r\n" + self.__prompt_prefix + b">")
+            result = (
+                self.__buffered_byte + data[: -(len(self.__prompt_prefix) + 1)]
+            )  # strip the QSE>
+            self.__buffered_byte = b""
+            return result
+
+    def __is_message_a_reply(self, message: bytes) -> bool:
+        # If it's blank (i.e. they send b'QSE>'), then it's a reply.
+        if not message:
+            return True
+
+        # Is it in our list of reply prefixes?
+        upper = message.upper()
+        for prefix in _REPLY_PREFIXES:
+            if upper.startswith(prefix):
+                return True
+
+        # Otherwise it's not a reply.  (Note that messages like ~DEVICE
+        # may well be sent as a result of a query, but they are not sent
+        # as a reply to the query -- they're sent as though they're
+        # unsolicited.)
+
+        # Sanity check: we expect exactly one b'\r\n', and it will be at the
+        # end.
+        assert message.endswith(b"\r\n")
+        assert b"\r\n" not in message[:-2], (
+            f"Unsolicited message {message!r} has too many lines"
+        )
+        return False
+
+    # Reads one message and stores the result in the appropriate member variables(s)
+    #
+    # Caller must hold self.__cond
+    async def __read_and_dispatch(self):
+        # TODO: I'm not thrilled with this unlock-and-relock sequence.
+        # Getting rid of it would require refactoring the callers.
+        self.__cond.release()
+        try:
+            data = await self.__read_one_message()
+        finally:
+            await self.__cond.acquire()
+
+        if not self.__is_message_a_reply(data):
+            self.__unsolicited_queue.append(data)
+
+            if (
+                self.__current_query
+                and self.__current_query.unsolicited_messages is not None
+            ):
+                self.__current_query.unsolicited_messages.append(data)
+                _LOGGER.debug("Received semi-solicited message: %s", repr(data))
+            else:
+                _LOGGER.debug("Received unsolicited message: %s", repr(data))
+
+            self.__cond.notify_all()
+        else:
+            if self.__current_query is None:
+                _LOGGER.error("Received unexpected syncronous message %s", repr(data))
+                return  # No need to notify_all()
+
+            if self.__current_query.reply is not None:
+                _LOGGER.error(
+                    "Received syncronous message %s before handling prior sync message %s",
+                    (repr(data), repr(self.__current_query.reply)),
+                )
+                return  # No need to notify_all()
+
+            _LOGGER.debug("Received synchronous message: %s", repr(data))
+            self.__current_query.reply = data
+            self.__cond.notify_all()
+
+    # Reads until predicate returns true.  May be called concurrently.
+    # Needs to tolerate cancellation.
+    #
+    # Caller must hold self.__cond
+    async def __wait_for_data(self, predicate: Callable[[], bool]):
+        assert self.__cond.locked()
+
+        while True:
+            if predicate():
+                return
+
+            if self.__currently_reading:
+                await self.__cond.wait()
+                continue
+
+            try:
+                self.__currently_reading = True
+                await self.__read_and_dispatch()
+            finally:
+                self.__currently_reading = False
+
+    async def __raw_query(
+        self, command: bytes, unsolicited_out: None | list[bytes] = None
+    ) -> bytes:
+        assert self.__conn is not None
+
+        async with self.__query_lock:
+            async with self.__cond:
+                if self.__current_query:
+                    raise ProtocolError(
+                        "raw_query called while a query in in progress (did you cancel and try again)"
+                    )
+                self.__current_query = _CurrentQuery(
+                    reply=None, unsolicited_messages=unsolicited_out
+                )
+
+            assert b"\r\n" not in command
+
+            self.__conn.w.write(command + b"\r\n")
+            await self.__conn.w.drain()
+
+            async with self.__cond:
+                await self.__wait_for_data(
+                    lambda: self.__current_query is not None
+                    and self.__current_query.reply is not None
+                )
+
+                assert self.__current_query is not None
+                assert self.__current_query.reply is not None
+                reply = self.__current_query.reply
+                self.__current_query = None
+                return reply
+
+    # Issues a command and returns the synchronous reply.
+    async def raw_query(self, command: bytes) -> bytes:
+        return await self.__raw_query(command, None)
+
+    # Issues a command and returns the synchronous reply and
+    # a copy of all unsolicited messages received starting just before
+    # sending the command and receiving the synchronous reply.
+    # This is inherently racy and may return earlier unsolicited messages
+    # as well.  It will not prevent read_unsolicited() from receiving the
+    # same messages.
+    #
+    # This is useful for probing devices or outputs without interfering
+    # with whatever other code might be using read_unsolicited()
+    async def raw_query_collect(self, command: bytes) -> tuple[bytes, list[bytes]]:
+        unsolicited_out: list[bytes] = []
+        reply = await self.__raw_query(command, unsolicited_out)
+        return (reply, unsolicited_out)
+
+    # Helper to ping the other end
+    async def ping(self) -> None:
+        await self.raw_query(b"")
+
+    async def send_device_command(
+        self,
+        dev: types.SerialNumber | bytes,
+        component: int,
+        action: types.DeviceAction,
+        params: Iterable[bytes],
+    ) -> None:
+        if isinstance(dev, types.SerialNumber):
+            sn = dev.sn
+        else:
+            sn = dev
+        command = b"#DEVICE,%s,%d,%d,%s" % (
+            sn,
+            component,
+            action.value,
+            b",".join(params),
+        )
+        await self.raw_query(command)
+
+    # Reads one single unsolicited message
+    async def read_unsolicited(self) -> bytes:
+        async with self.__cond:
+            await self.__wait_for_data(lambda: len(self.__unsolicited_queue) >= 1)
+
+            result = self.__unsolicited_queue.popleft()
+            return result
+
+    # Higher-level queries
+
+    # Gets the most recent for all components that respond to probes.
+    async def probe_device(
+        self, dev_id: types.SerialNumber | bytes
+    ) -> tuple[bytes, list[bytes]]:
+        if isinstance(dev_id, bytes):
+            target = dev_id
+        else:
+            assert isinstance(dev_id, types.SerialNumber)
+            target = dev_id.sn
+        return await self.raw_query_collect(b"?DEVICE,%s,0,0" % target)
+
+    async def disconnect(self) -> None:
+        if self.__conn is None:
+            return None
+        self.__conn.w.close()
+        await self.__conn.w.wait_closed()
+        self._conn = None
+        return None
+
+
+async def login(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    username: bytes,
+    password: None | bytes,
+) -> LutronConnection:
+    """
+    Authenticate with a Lutron device over an asyncio stream.
+
+    Waits for the login prompt, sends the username, and validates the response.
+
+    Args:
+        reader: The asyncio StreamReader for receiving data
+        writer: The asyncio StreamWriter for sending data
+        username: The username as bytes
+        password: The password as bytes, or None if no password is required
+
+    Returns:
+        LutronConnection object representing the established connection
+
+    Raises:
+        LoginError: If the login fails, containing the error message from the server
+    """
+    # Wait for the login prompt
+    await reader.readuntil(b"login: ")
+
+    # Send the username (line-oriented protocol requires newline)
+    writer.write(username + b"\r\n")
+    await writer.drain()
+
+    # Read the server's response
+    response = await reader.readline()
+    response = response.strip()
+
+    # Check if login was successful
+    if response == b"connection established":
+        return await LutronConnection.create_from_connnection(reader, writer)
+    else:
+        raise LoginError(response)
+
+
+async def dump_replies(conn: LutronConnection):
+    try:
+        async with asyncio.timeout(0.25):
+            while True:
+                # It would be nice to just do this until it would block, but StreamReader doesn't
+                # have a nonblocking read operation
+                print(repr(await conn.read_unsolicited()))
+    except TimeoutError:
+        pass

lutron_integration-0.0.0a1/src/lutron_integration/devices.py

@@ -0,0 +1,365 @@
+from dataclasses import dataclass
+import re
+from . import types, connection
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ArraySpec:
+    count: int
+    base: int  # First component number
+    stride: int = 1  # Spacing between component numbers
+
+
+@dataclass(frozen=True)
+class ComponentGroup:
+    name: str  # Programmer-friendly name, like "ZONE"
+    desc: str  # Base description without number, like "Zone Controller"
+    array_spec: ArraySpec | None = None  # Array specification (for array mode)
+    numbers: tuple[int, ...] | None = (
+        None  # Explicit list of component numbers (for arbitrary mode)
+    )
+
+    @property
+    def count(self) -> int:
+        if self.array_spec is not None:
+            return self.array_spec.count
+        else:
+            assert self.numbers is not None
+            return len(self.numbers)
+
+    def __post_init__(self):
+        # Validate that exactly one mode is specified
+        if (self.array_spec is None) == (self.numbers is None):
+            raise ValueError("Must specify either array_spec or numbers but not both")
+
+        if self.numbers is not None and not self.numbers:
+            raise ValueError("numbers cannot be an empty list")
+
+        # Initialize per-group cache
+        object.__setattr__(self, "_cache", {})
+
+    def lookup_component(self, number: int) -> int | None:
+        """Check if this group contains a component number.
+
+        Returns the 1-based index if found, None otherwise.
+        """
+        if self.numbers is not None:
+            # Arbitrary mode
+            try:
+                return self.numbers.index(number) + 1
+            except ValueError:
+                return None
+        else:
+            # Array mode
+            assert self.array_spec is not None
+            if number >= self.array_spec.base:
+                offset = number - self.array_spec.base
+                if offset % self.array_spec.stride == 0:
+                    index = offset // self.array_spec.stride + 1
+                    if 1 <= index <= self.array_spec.count:
+                        return index
+            return None
+
+    def component_number(self, index: int) -> int | None:
+        """Get the component number for a 1-based index.
+
+        Args:
+            index: 1-based index into this component group
+
+        Returns:
+            Component number if index is valid, None otherwise.
+        """
+        if index < 1 or index > self.count:
+            return None
+
+        if self.numbers is not None:
+            # Arbitrary mode
+            return self.numbers[index - 1]
+        else:
+            # Array mode
+            assert self.array_spec is not None
+            return self.array_spec.base + (index - 1) * self.array_spec.stride
+
+
+class DeviceClass:
+    """Represents a device type with its component groups and individual components."""
+
+    groups: dict[str, ComponentGroup]
+
+    def __init__(self, groups: list[ComponentGroup]):
+        """Initialize a device class with component groups and individual components.
+
+        Args:
+            groups: List of ComponentGroup instances
+            components: Dictionary mapping component names to ComponentGroup instances
+        """
+        self.groups = {g.name: g for g in groups}
+
+    def lookup_component(self, number: int) -> tuple[ComponentGroup, int] | None:
+        """Resolves a component number to a ComponentGroup and index within the group"""
+
+        # TODO: Consider adding a cache
+
+        # Search through component groups to find a match
+        for group in self.groups.values():
+            index = group.lookup_component(number)
+            if index is not None:
+                return (group, index)
+
+        return None
+
+
+FAMILY_TO_CLASS: dict[bytes, DeviceClass] = {}
+
+# Grafik Eye QS Device Definition
+GrafikEyeQS = DeviceClass(
+    groups=[
+        ComponentGroup(
+            name="ZONE", desc="Zone Controller", array_spec=ArraySpec(count=24, base=1)
+        ),
+        ComponentGroup(
+            name="SHADE_OPEN", desc="Shade Column Open", numbers=(38, 44, 50)
+        ),
+        ComponentGroup(
+            name="SHADE_PRESET", desc="Shade Column Preset", numbers=(39, 45, 51)
+        ),
+        ComponentGroup(
+            name="SHADE_CLOSE", desc="Shade Column Close", numbers=(40, 46, 56)
+        ),
+        ComponentGroup(
+            name="SHADE_LOWER", desc="Shade Column Lower", numbers=(41, 52, 57)
+        ),
+        ComponentGroup(
+            name="SHADE_RAISE", desc="Shade Column Raise", numbers=(47, 53, 58)
+        ),
+        ComponentGroup(
+            name="SCENE_BUTTON", desc="Scene Button", numbers=(70, 71, 76, 77)
+        ),
+        ComponentGroup(name="SCENE_OFF_BUTTON", desc="Scene Off Button", numbers=(83,)),
+        ComponentGroup(
+            name="SCENE_CONTROLLER", desc="Scene Controller", numbers=(141,)
+        ),
+        ComponentGroup(name="LOCAL_CCI", desc="Local CCI", numbers=(163,)),
+        ComponentGroup(
+            name="TIMECLOCK_CONTROLLER", desc="Timeclock Controller", numbers=(166,)
+        ),
+        # The LEDs are not available in QS Standalone
+        ComponentGroup(
+            name="SCENE_LED",
+            desc="Scene LED",
+            array_spec=ArraySpec(count=4, base=201, stride=9),
+        ),
+        ComponentGroup(name="SCENE_OFF_LED", desc="Scene Off LED", numbers=(237,)),
+        ComponentGroup(
+            name="SHADE_OPEN_LED",
+            desc="Shade Column Open LED",
+            array_spec=ArraySpec(count=3, base=174, stride=9),
+        ),
+        ComponentGroup(
+            name="SHADE_PRESET_LED",
+            desc="Shade Column Preset LED",
+            array_spec=ArraySpec(count=3, base=175, stride=9),
+        ),
+        ComponentGroup(
+            name="SHADE_CLOSE_LED",
+            desc="Shade Column Close LED",
+            array_spec=ArraySpec(count=3, base=211, stride=9),
+        ),
+        ComponentGroup(
+            name="WIRELESS_OCC_SENSOR",
+            desc="Wireless Occupancy Sensor",
+            array_spec=ArraySpec(count=30, base=500),
+        ),
+        ComponentGroup(
+            name="ECOSYSTEM_OCC_SENSOR",
+            desc="EcoSystem Ballast Occupancy Sensor",
+            array_spec=ArraySpec(count=64, base=700),
+        ),
+        # These components are not documented.
+        # TODO: Confirm the behavior of the zone buttons on a 16-zone unit
+        ComponentGroup(name="MASTER_RAISE", desc="Master Raise Button", numbers=(74,)),
+        ComponentGroup(name="MASTER_LOWER", desc="Master Lower Button", numbers=(75,)),
+        ComponentGroup(
+            name="ZONE_RAISE",
+            desc="Zone Raise Button",
+            array_spec=ArraySpec(count=8, base=36, stride=6),
+        ),
+        ComponentGroup(
+            name="ZONE_LOWER",
+            desc="Zone Lower Button",
+            array_spec=ArraySpec(count=8, base=37, stride=6),
+        ),
+        ComponentGroup(name="TIMECLOCK_BUTTON", desc="Timeclock Button", numbers=(68,)),
+        ComponentGroup(name="OK_BUTTON", desc="OK Button", numbers=(69,)),
+        ComponentGroup(
+            name="SWITCH_GROUP_BUTTON", desc="Swich Group Button", numbers=(80,)
+        ),
+    ]
+)
+
+Shade = DeviceClass(
+    groups=[
+        # Yes, Lutron really did not document any components!
+        # Shades accept a target position as "light level" (action 14)
+        # on component 0 and report their position via this action as well.
+        ComponentGroup(
+            name="SHADE",
+            desc="Shade Position",
+            numbers=(0,),
+        ),
+    ]
+)
+
+Keypad = DeviceClass(
+    groups=[
+        # Buttons 1-7: most keypads have these, even if they claim to have fewer
+        # buttons.  They might be hiding under the cover plate.
+        ComponentGroup(
+            name="BUTTON", desc="Button", array_spec=ArraySpec(count=7, base=1)
+        ),
+        # The top raise/lower buttons only sometimes exist.  The bottom raise/lower
+        # buttons are very common.  It's a bit unclear what happens if they are
+        # physically absent (e.g. on a "7-button" Architrave keypad, not all
+        # programming features are present because the bottom raise/lower buttons
+        # don't exist.)
+        ComponentGroup(name="BUTTON_TOP_LOWER", desc="Button Top Lower", numbers=(16,)),
+        ComponentGroup(name="BUTTON_TOP_RAISE", desc="Button Top Raise", numbers=(17,)),
+        ComponentGroup(
+            name="BUTTON_BOTTOM_LOWER", desc="Button Top Lower", numbers=(18,)
+        ),
+        ComponentGroup(
+            name="BUTTON_BOTTOM_RAISE", desc="Button Top Raise", numbers=(19,)
+        ),
+    ]
+)
+
+# TODO: This isn't great: a shade power supply is 'SHADES(3)' but is not a shade
+FAMILY_TO_CLASS[b"KEYPAD(1)"] = Keypad
+FAMILY_TO_CLASS[b"GRAFIK_EYE(2)"] = GrafikEyeQS
+FAMILY_TO_CLASS[b"SHADES(3)"] = Shade
+
+
+def action_to_friendly_str(action: int):
+    try:
+        return types.DeviceAction(action).name
+    except ValueError:
+        return str(action)
+
+
+@dataclass
+class DeviceUpdateValues:
+    component: int
+    action: types.DeviceAction
+    params: tuple[bytes]
+
+
+@dataclass
+class DeviceUpdate:
+    """Represents a parsed device update message."""
+
+    serial_number: types.SerialNumber
+    component: int
+    action: types.DeviceAction
+    value: tuple[bytes, ...]
+
+
+_DEVICE_UPDATE_RE = re.compile(rb"~DEVICE,([^,]+),(\d+),(\d+)(?:,([^\r]*))?\r\n", re.S)
+
+
+def decode_device_update(
+    message: bytes, iidmap: types.IntegrationIDMap
+) -> DeviceUpdate | None:
+    """Parse a ~DEVICE message into a DeviceUpdate.
+
+    Args:
+        message: Raw ~DEVICE message bytes
+        universe: LutronUniverse for resolving device identifiers
+
+    Returns:
+        DeviceUpdate if message was parsed successfully, None otherwise
+    """
+
+    # ~DEVICE,<identifier>,<component>,<action>[,<params>]\r\n
+    match = _DEVICE_UPDATE_RE.fullmatch(message)
+    if not match:
+        _LOGGER.debug(f"Failed to parse device message: {message!r}")
+        return None
+
+    device_identifier = match[1]
+    component = int(match[2])
+    action_int = int(match[3])
+    value = tuple(match[4].split(b",")) if match[4] else ()
+
+    # Resolve device identifier to serial number
+    try:
+        sn = types.SerialNumber(device_identifier)
+    except ValueError:
+        # Not a serial number, try integration ID
+        if device_identifier in iidmap.device_ids:
+            sn = iidmap.device_ids[device_identifier]
+        else:
+            _LOGGER.debug("Unknown device identifier: %s", device_identifier)
+            return None
+
+    try:
+        action = types.DeviceAction(action_int)
+    except ValueError:
+        _LOGGER.debug(f"Unknown action {action_int} in update {message!r}")
+        return None
+
+    return DeviceUpdate(
+        serial_number=sn, component=component, action=action, value=value
+    )
+
+
+async def probe_device(
+    conn: connection.LutronConnection,
+    iidmap: types.IntegrationIDMap,
+    dev_id: types.SerialNumber | bytes,
+) -> list[DeviceUpdate]:
+    result: list[DeviceUpdate] = []
+    _, updates = await conn.probe_device(dev_id)
+
+    for update in updates:
+        decoded = decode_device_update(update, iidmap)
+        if decoded is not None:
+            result.append(decoded)
+
+    return result
+
+
+_IIDLINE_RE = re.compile(
+    b"~INTEGRATIONID,([^,]+),(DEVICE|OUTPUT),([0-9A-Fa-fx]+)(?:,([0-9]+))?", re.S
+)
+
+
+async def enumerate_iids(conn: connection.LutronConnection) -> types.IntegrationIDMap:
+    iidmap = types.IntegrationIDMap()
+
+    integration_ids = await conn.raw_query(b"?INTEGRATIONID,3")
+    iidlines = integration_ids.split(b"\r\n")
+
+    if not iidlines or iidlines[-1] != b"":
+        raise types.ParseError("~INTEGRATIONIDS,3 list does not split correctly")
+    iidlines = iidlines[:-1]
+
+    for line in iidlines:
+        m = _IIDLINE_RE.fullmatch(line)
+        if not m:
+            raise types.ParseError(f"Integration id line {line!r} does not parse")
+        name = m[1]
+        if name == b"(Not Set)":
+            # If we ever support a dialect that does not support ?DETAILS, then we could
+            # use the (Not Set) lines as a way to discover devices without integration IDs.
+            # This is not necessary for QS Standalone.
+            continue
+        sn = types.SerialNumber(m[3])
+        if m[2] == b"DEVICE":
+            iidmap.device_ids[name] = sn
+        else:
+            iidmap.output_ids[name] = (sn, int(m[4]))
+
+    return iidmap

lutron_integration-0.0.0a1/src/lutron_integration/qse.py

@@ -0,0 +1,141 @@
+from dataclasses import dataclass, field
+from . import connection, types, devices
+from .types import SerialNumber
+
+# Notes:
+#
+# Integration ids for devices appear to be stored on the devices (or at least if you
+# wipe the flash on the NWK via #RESET,2 then they are not cleared).  You cannot
+# set an integration id for a nonexistent device.  Setting an integration id for
+# a device that does exist is quite slow.
+#
+# Integration ids for *outputs* seem to be rather different.  They can be set quite
+# quickly, but only for devices that actually exist, but you can integration ids
+# for absurdly large output numbers that do not actually exist.  Additionally,
+# #RESET,2 seems to erase all the output integration ids.
+#
+# My hypotheses is that output integration IDs are translated in the NWK
+# to/from device commands and states.  For example, Grafik Eye has documented
+# DEVICE component numbers for up to 24 zone controllers.  Monitoring shows
+# ~DEVICE if no integrationid is assigned and ~OUTPUT if an integration id
+# is assigned.  This mapping might not even care about the device type --
+# it might be the case that action 14 (light level) always maps to OUTPUT
+# action 1 (light level), and that the component number maps straight through.
+
+# The integrationid system tries to be well behaved.  It tries to reject
+# duplicates.  You can set any number of device integration ids to
+# b"(Not Set)", in which case they appear to be not set.  But it does
+# not prevent you from setting an integration id that looks like a
+# serial number, and you can cause #INTEGRATIONID to go into an
+# infinite loop by first setting a device's integration id to its own
+# serial number and then trying to change it.  (This appears to be
+# recoverable by rebooting the NWK.)
+
+
+@dataclass
+class DeviceDetails:
+    sn: SerialNumber
+    integration_id: bytes
+    family: bytes
+    product: bytes
+
+    # raw_attrs likely contains at least b'CODE', b'BOOT', and b'HW',
+    # and it also contins b'SN', b'INTEGRATIONID', etc.
+    raw_attrs: dict[bytes, bytes]
+
+
+_DETAILS_KEYS = {
+    "SN": "sn",
+    "INTEGRATIONID": "integration_id",
+    "FAMILY": "family",
+    "PRODUCT": "product",
+}
+
+
+def parse_details(data: bytes) -> list[DeviceDetails]:
+    """
+    Parse a reply to ?DETAILS into a list of dictionaries, one per device
+
+    Each line is formatted as
+    ~DETAILS,KEY1:VALUE1,KEY2:VALUE2,...
+
+    Args:
+        data: Raw bytes containing multiple ~DETAILS lines separated by \r\n
+
+    Returns:
+        List of dictionaries, where each dict represents one device with
+        keys and values as bytes
+    """
+    result: list[DeviceDetails] = []
+
+    # Split into lines
+    lines = data.split(b"\r\n")
+
+    if not lines or lines[-1] != b"":
+        raise types.ParseError("~DETAILS list does not split correctly")
+    lines = lines[:-1]
+
+    for line in lines:
+        # Check if line starts with ~DETAILS,
+        if not line.startswith(b"~DETAILS,"):
+            raise types.ParseError(f"Unexpected details line: {line!r}")
+
+        # Remove the ~DETAILS, prefix
+        details_str = line[9:]  # len(b'~DETAILS,') == 9
+
+        # Split by comma to get key-value pairs
+        pairs = details_str.split(b",")
+
+        attrs: dict[bytes, bytes] = {}
+        for pair in pairs:
+            # Split by first colon only (values might contain colons)
+            if b":" in pair:
+                key, value = pair.split(b":", 1)
+                attrs[key] = value
+            else:
+                raise types.ParseError("Details entry {pair!r} has no comma")
+
+        device = DeviceDetails(
+            sn=SerialNumber(attrs[b"SN"]),
+            integration_id=attrs[b"INTEGRATIONID"],
+            family=attrs[b"FAMILY"],
+            product=attrs[b"PRODUCT"],
+            raw_attrs=attrs,
+        )
+
+        result.append(device)
+
+    return result
+
+
+# TODO: This isn't just QSE.  Homeworks QS, Quantum, and myRoom Plus support this.
+@dataclass
+class IntegrationIDRecord:
+    iid: bytes
+    style: bytes  # either b'DEVICE' or b'OUTPUT'
+    sn: SerialNumber
+
+
+@dataclass
+class LutronUniverse:
+    devices_by_sn: dict[SerialNumber, DeviceDetails] = field(default_factory=dict)
+    iidmap: types.IntegrationIDMap = field(default_factory=types.IntegrationIDMap)
+
+    # NB: It's possible for devices_by_sn and iidmap to be out of sync
+    # with each other if configuration changes between when we read
+    # ?DETAILS and ?INTEGRATIONID.
+
+
+async def enumerate_universe(conn: connection.LutronConnection) -> LutronUniverse:
+    all_devices = parse_details(await conn.raw_query(b"?DETAILS,ALL_DEVICES"))
+
+    universe = LutronUniverse()
+    universe.devices_by_sn = {d.sn: d for d in all_devices}
+
+    # We could map iids to devices like this:
+    # {d.integration_id: d for d in all_devices if d.integration_id != b'(Not Set)'}
+    # but it's redundant with iidmap.
+
+    universe.iidmap = await devices.enumerate_iids(conn)
+
+    return universe

lutron_integration-0.0.0a1/src/lutron_integration/types.py

@@ -0,0 +1,105 @@
+from dataclasses import dataclass, field
+import re
+from enum import Enum, unique
+
+_SN_RE = re.compile(b"(?:0x)?([0-9A-Fa-f]{0,8})", re.S)
+
+
+# A serial number as reported by the integration access point
+# is an optional 0x followed by
+# 8 hexadecimal digits, with inconsistent case.  The NWK accepts a serial
+# number with up to two 0x prefixes followed by any number (maybe up to
+# some limit) of zeros followed by case-insensitive hex digits.
+#
+# Some but not all commands will accept an integration id in place of
+# a serial number.  The NWK can get extremely confused if there is an
+# integration id that is also a well-formed serial number.
+#
+# (All of this comes from testing a QSE-CI-NWK-E, but I expect
+#  it to be compatible with other integration access points
+#  as well.)
+#
+# This class represents a canonicalized serial number.  It's hashable.
+@dataclass(order=False, eq=True, frozen=True)
+class SerialNumber:
+    sn: bytes
+
+    def __init__(self, sn: bytes):
+        m = _SN_RE.fullmatch(sn)
+        if not m:
+            raise ValueError(f"Malformed serial number {sn!r}")
+        sn = m[1]
+        object.__setattr__(self, "sn", b"0" * (8 - len(sn)) + sn.upper())
+
+    def __repr__(self):
+        return f"SerialNumber({self.sn!r})"
+
+    def __str__(self):
+        return self.sn.decode()
+
+
+# These are DEVICE actions.  OUTPUT actions are different.
+@unique
+class DeviceAction(Enum):
+    ENABLE = 1
+    DISABLE = 2
+    PRESS_CLOSE_UNOCC = 3  # Press button or close shades or room unoccupied
+    RELEASE_OPEN_OCC = 4  # Release button or open shades or room occupied
+    HOLD = 5
+    DOUBLE_TAP = 6
+    CURRENT_SCENE = 7
+    LED_STATE = 9
+    SCENE_SAVE = 12
+    LIGHT_LEVEL = 14
+    ZONE_LOCK = 15
+    SCENE_LOCK = 16
+    SEQUENCE_STATE = 17
+    START_RAISING = 18
+    START_LOWERING = 19
+    STOP_RAISING_LOWERING = 20
+    HOLD_RELEASE = 32  # for keypads -- I have no idea what it does
+    TIMECLOCK_STATE = 34  # 0 = disabled, 1 = enabled
+
+    # 21 is a mysterious property of the SHADE component of shades.
+    # It seems to have the value 0 most of the time but has other values when the shade
+    # is moving.
+    MOTOR_MYSTERY = 21
+
+
+@unique
+class OutputAction(Enum):
+    LIGHT_LEVEL = 1
+    START_RAISING = 2
+    START_LOWERING = 3
+    STOP_RAISING_LOWERING = 4
+    START_FLASHING = 5
+    PULSE_TIME = 6
+    TILT_LEVEL = 9
+    LIFT_TILT_LEVEL = 10
+    START_RAISING_TILT = 11
+    START_LOWERING_TILT = 12
+    STOP_RAISING_LOWERING_TILT = 13
+    START_RAISING_LIFT = 14
+    START_LOWERING_LIFT = 15
+    STOP_RAISING_LOWERING_LIFT = 16
+    DMX_COLOR_LEVEL = 17
+
+
+@dataclass
+class IntegrationIDMap:
+    # Maps output integration ids to the device sn and output/zone number
+    output_ids: dict[bytes, tuple[SerialNumber, int]] = field(default_factory=dict)
+
+    # Maps device integration ids to the device sn
+    device_ids: dict[bytes, SerialNumber] = field(default_factory=dict)
+
+    # We don't bother storing the reverse mapping anywhere -- we need
+    # to be able to control outputs that don't have integration IDs,
+    # and there appears to be no benefit to ever sending an #OUTPUT command.
+
+
+class ParseError(Exception):
+    """Exception raised when a message doesn't parse correctly."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(str)