recsrmesh 0.1.0__tar.gz

recsrmesh-0.1.0/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

recsrmesh-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: recsrmesh
+Version: 0.1.0
+Summary: CSRMesh protocol library
+Author-email: Sean Kinsey <oyvind@kinsey.no>
+License: LGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/oyvindkinsey/recsrmesh
+Project-URL: Repository, https://github.com/oyvindkinsey/recsrmesh
+Project-URL: Issues, https://github.com/oyvindkinsey/recsrmesh/issues
+Keywords: csrmesh,bluetooth,mesh,ble
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.21.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: pycryptodomex>=3.23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Dynamic: license-file

recsrmesh-0.1.0/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recsrmesh"
+version = "0.1.0"
+description = "CSRMesh protocol library"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "LGPL-3.0-or-later"}
+authors = [
+    {name = "Sean Kinsey", email = "oyvind@kinsey.no"}
+]
+keywords = [
+    "csrmesh",
+    "bluetooth",
+    "mesh",
+    "ble",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Home Automation",
+    "Topic :: System :: Hardware",
+]
+
+dependencies = [
+    "bleak>=0.21.0",
+    "cryptography>=41.0.0",
+    "pycryptodomex>=3.23.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+    "pytest-mock>=3.11.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+test = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/oyvindkinsey/recsrmesh"
+Repository = "https://github.com/oyvindkinsey/recsrmesh"
+Issues = "https://github.com/oyvindkinsey/recsrmesh/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["recsrmesh*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--tb=short",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"tests/*" = ["F403", "F405"]

recsrmesh-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

recsrmesh-0.1.0/src/recsrmesh/__init__.py

@@ -0,0 +1,3 @@
+"""CSRMesh protocol library."""
+
+from .mesh import CSRMesh

recsrmesh-0.1.0/src/recsrmesh/_fake_client.py

@@ -0,0 +1,123 @@
+"""Fake BleakClient for replay testing."""
+
+import asyncio
+from collections.abc import Callable
+
+
+class FakeBleakClient:
+    """
+    Device simulator for replay testing.
+
+    Acts like a real BleakClient: accepts writes, verifies against transcript,
+    delivers notifications to handlers.
+    """
+
+    def __init__(self, transcript: dict):
+        self.transcript = transcript
+        self.event_ptr = 0
+        self.notification_handlers: dict[str, Callable] = {}
+        self.connected = True
+
+    async def start_notify(self, char_uuid: str, callback: Callable):
+        """Register notification handler, skip CCCD events."""
+        self.notification_handlers[char_uuid] = callback
+
+        while self.event_ptr < len(self.transcript["events"]):
+            event = self.transcript["events"][self.event_ptr]
+            if event["type"] == "descriptor_write" and \
+               event["details"]["characteristic"] == char_uuid:
+                self.event_ptr += 1
+            else:
+                break
+
+        await self._replay_notifications()
+
+    async def write_gatt_char(
+        self,
+        char_uuid: str,
+        data: bytes,
+        response: bool = True
+    ):
+        """Verify write matches transcript, then replay device response."""
+        if self.event_ptr >= len(self.transcript["events"]):
+            raise RuntimeError(
+                f"State machine wrote beyond transcript end\n"
+                f"  Characteristic: {char_uuid}\n"
+                f"  Data: {data.hex()}"
+            )
+
+        event = self.transcript["events"][self.event_ptr]
+
+        if event["type"] != "gatt_write":
+            raise RuntimeError(
+                f"Protocol violation at event {self.event_ptr}:\n"
+                f"  Expected: {event['type']} (state machine should be waiting)\n"
+                f"  Got: gatt_write to {char_uuid}"
+            )
+
+        expected_char = event["details"]["characteristic"]
+        expected_data = bytes.fromhex(event["details"]["value"].replace(" ", "").replace("\n", ""))
+        expected_type = event["details"]["write_type"]
+        actual_type = "write_without_response" if not response else "write_with_response"
+
+        if char_uuid != expected_char:
+            raise AssertionError(
+                f"Write to wrong characteristic at event {self.event_ptr}:\n"
+                f"  Expected: {expected_char}\n"
+                f"  Got:      {char_uuid}"
+            )
+
+        if data != expected_data:
+            raise AssertionError(
+                f"Write data mismatch at event {self.event_ptr}:\n"
+                f"  Expected: {expected_data.hex()}\n"
+                f"  Got:      {data.hex()}"
+            )
+
+        if actual_type != expected_type:
+            raise AssertionError(
+                f"Write type mismatch at event {self.event_ptr}:\n"
+                f"  Expected: {expected_type}\n"
+                f"  Got:      {actual_type}"
+            )
+
+        self.event_ptr += 1
+        await self._replay_notifications()
+
+    async def _replay_notifications(self):
+        """Deliver consecutive notification events to handlers."""
+        while self.event_ptr < len(self.transcript["events"]):
+            event = self.transcript["events"][self.event_ptr]
+            if event["type"] != "notification":
+                break
+
+            char_uuid = event["details"]["characteristic"]
+            data = bytes.fromhex(event["details"]["value"].replace(" ", "").replace("\n", ""))
+
+            handler = self.notification_handlers.get(char_uuid)
+            if not handler:
+                raise RuntimeError(
+                    f"No handler registered for {char_uuid} at event {self.event_ptr}"
+                )
+
+            handler(None, bytearray(data))
+            self.event_ptr += 1
+            await asyncio.sleep(0.001)
+
+    async def disconnect(self):
+        self.connected = False
+
+    async def stop_notify(self, char_uuid: str):
+        pass
+
+    def verify_complete(self):
+        """Verify all transcript events were consumed."""
+        if self.event_ptr != len(self.transcript["events"]):
+            remaining = len(self.transcript["events"]) - self.event_ptr
+            next_event = self.transcript["events"][self.event_ptr]
+            raise AssertionError(
+                f"Transcript not fully replayed:\n"
+                f"  Consumed: {self.event_ptr}/{len(self.transcript['events'])}\n"
+                f"  Remaining: {remaining} events\n"
+                f"  Next event: {next_event['type']}"
+            )

recsrmesh-0.1.0/src/recsrmesh/ble.py

@@ -0,0 +1,194 @@
+"""BLE state machine for CSRMesh association."""
+
+import asyncio
+import logging
+import time
+from enum import IntEnum, auto
+
+from .crypto import (
+    MASP_XOR_MASK,
+    add_packet_mac,
+    derive_key,
+    uuid_to_hash31,
+    verify_packet_mac,
+    xor_masp_packet,
+)
+from .masp import MaspOpcode
+from .protocol import ProtocolState, ProtocolStateMachine
+
+logger = logging.getLogger(__name__)
+
+# CSRMesh GATT Service
+SERVICE_UUID = "c4edc000-9daf-11e3-8000-00025b000b00"
+
+# MTL Characteristics (legacy)
+CHARACTERISTIC_LOW = "c4edc000-9daf-11e3-8003-00025b000b00"
+CHARACTERISTIC_HIGH = "c4edc000-9daf-11e3-8004-00025b000b00"
+
+# CCCD Descriptor
+CCCD_UUID = "00002902-0000-1000-8000-00805f9b34fb"
+
+
+class AssociationState(IntEnum):
+    """Association session states."""
+    DISCONNECTED = auto()
+    CONNECTING = auto()
+    ASSOCIATING = auto()
+    COMPLETE = auto()
+    FAILED = auto()
+
+
+class AssociationStateMachine:
+    """
+    MASP association protocol runner.
+
+    MTL reassembly and notification management are handled by CSRMesh.
+    Raw reassembled bytes arrive via feed_raw().
+    """
+
+    def __init__(
+        self,
+        client,
+        uuid_hash: int,
+        passphrase: str,
+        device_id: int | None = None,
+    ):
+        self.client = client
+        self.uuid_hash = uuid_hash
+        self.passphrase = passphrase
+
+        if device_id is None:
+            device_id = 33896
+
+        self.protocol = ProtocolStateMachine(uuid_hash, device_id, passphrase)
+
+        self.masp_key = derive_key("", "\x00MASP")
+
+        # State
+        self.state = AssociationState.DISCONNECTED
+        self.error: str | None = None
+        self.pending_response: bytes | None = None
+
+    def feed_raw(self, raw: bytes):
+        """Accept raw reassembled bytes from CSRMesh notification layer."""
+        payload, valid = verify_packet_mac(raw, self.masp_key)
+        if valid:
+            raw = payload
+            logger.debug(f"[MAC valid]   payload {len(raw)}B")
+        else:
+            logger.debug(f"[MAC invalid] passing raw {len(raw)}B")
+        message = xor_masp_packet(raw)
+
+        opcode = message[0]
+        opname = MaspOpcode(opcode).name if opcode in MaspOpcode._value2member_map_ else f"0x{opcode:02x}"
+        logger.debug(f"[message]     opcode={opname} ({len(message)}B)")
+        self.pending_response = message
+
+    async def run(self) -> bool:
+        """Execute full association sequence."""
+        try:
+            self.state = AssociationState.ASSOCIATING
+            await self._run_protocol()
+            return self.state == AssociationState.COMPLETE
+        except Exception as e:
+            self.error = str(e)
+            self.state = AssociationState.FAILED
+            return False
+
+    async def _run_protocol(self, retries: int = 3, timeout: float = 10.0):
+        """Execute MASP protocol state machine with per-message retries."""
+        request = self.protocol.get_initial_request()
+
+        while request is not None:
+            advanced = False
+            for attempt in range(retries + 1):
+                if attempt > 0:
+                    logger.debug(f"[retry]       attempt {attempt + 1}/{retries + 1}"
+                               f" (state={self.protocol.state.name})")
+                assert request is not None
+                await self._send_masp_message(request)
+
+                deadline = time.time() + timeout
+                while True:
+                    remaining = deadline - time.time()
+                    if remaining <= 0:
+                        break
+
+                    response = await self._wait_for_response(timeout=remaining)
+                    if response is None:
+                        break
+
+                    next_request = self.protocol.process(response)
+                    if self.protocol.error:
+                        raise RuntimeError(self.protocol.error)
+                    if next_request is not None or self.protocol.state == ProtocolState.COMPLETE:
+                        request = next_request
+                        advanced = True
+                        break
+
+                if advanced:
+                    break
+            else:
+                raise TimeoutError(
+                    f"No response from device after {retries + 1} attempts "
+                    f"(state={self.protocol.state.name})")
+
+        if self.protocol.state == ProtocolState.COMPLETE:
+            self.state = AssociationState.COMPLETE
+        else:
+            raise RuntimeError(f"Protocol ended in state {self.protocol.state}")
+
+    async def _send_masp_message(self, message_after_xor: bytes):
+        """Send MASP message, fragmenting across characteristics if needed."""
+        # TTL=55 (0x37) matches Android app behavior
+        packet_with_mac = add_packet_mac(message_after_xor, self.masp_key, ttl=55)
+
+        xor_opcode = message_after_xor[0]
+        decoded_opcode = xor_opcode ^ MASP_XOR_MASK[0]
+        opname = MaspOpcode(decoded_opcode).name if decoded_opcode in MaspOpcode._value2member_map_ else f"0x{decoded_opcode:02x}"
+        logger.debug(f"[send]        {opname} ({len(packet_with_mac)}B) wire={packet_with_mac.hex()}")
+
+        # Short packets (<=20B): write to 8004 only
+        # Long packets (>20B): first 20 to 8003, overflow to 8004
+        if len(packet_with_mac) <= 20:
+            await self.client.write_gatt_char(
+                CHARACTERISTIC_HIGH, packet_with_mac, response=False)
+        else:
+            chunk1 = packet_with_mac[:20]
+            chunk2 = packet_with_mac[20:]
+
+            await self.client.write_gatt_char(
+                CHARACTERISTIC_LOW, chunk1, response=False)
+
+            if chunk2:
+                await self.client.write_gatt_char(
+                    CHARACTERISTIC_HIGH, chunk2, response=False)
+
+    async def _wait_for_response(self, timeout: float) -> bytes | None:
+        """Wait for complete response to arrive."""
+        start = time.time()
+        while self.pending_response is None:
+            if time.time() - start > timeout:
+                return None
+            await asyncio.sleep(0.01)
+
+        response = self.pending_response
+        self.pending_response = None
+        return response
+
+
+def _process_discovery_packet(raw: bytes, masp_key: bytes, results: list):
+    """Process a received packet during discovery."""
+    payload, valid = verify_packet_mac(raw, masp_key)
+    if not valid:
+        return
+
+    message = xor_masp_packet(payload)
+    if len(message) < 17 or message[0] != MaspOpcode.UUID_ANNOUNCE:
+        return
+
+    uuid_bytes = message[1:17]
+    uuid_hash = uuid_to_hash31(uuid_bytes)
+    if not any(r['uuid_hash'] == uuid_hash for r in results):
+        results.append({'uuid': uuid_bytes, 'uuid_hash': uuid_hash})
+        logger.debug(f"[discovered]  uuid_hash=0x{uuid_hash:08X} uuid={uuid_bytes.hex()}")