sofapython 0.0.1rc1__tar.gz

sofapython-0.0.1rc1/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.pyc
+*.pyo
+*.bak
+*.log
+*.zip
+*.patch
+.vscode/
+.idea/
+.mypy_cache/
+.pytest_cache/
+.pytest_tmp/
+.pytest_tmp*/
+pytest-cache-files-*/
+.codex-tmp/
+.venv/
+.venv-py313/
+.venv-py313-smoke/
+pytest.ini
+.python-version
+.claude/
+node_modules/
+playwright-report/
+test-results/
+artifacts/
+docs/internal/
+pytest.cmd
+dist/

sofapython-0.0.1rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 m3tac0de
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sofapython-0.0.1rc1/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: sofapython
+Version: 0.0.1rc1
+Summary: Unofficial protocol library and man-in-the-middle proxy for Sofabaton X1 / X1S / X2 universal remote hubs
+Project-URL: Homepage, https://github.com/m3tac0de/home-assistant-sofabaton-x1s
+Project-URL: Issues, https://github.com/m3tac0de/home-assistant-sofabaton-x1s/issues
+Project-URL: Documentation, https://github.com/m3tac0de/home-assistant-sofabaton-x1s/tree/main/docs
+Author: m3tac0de
+License: MIT
+License-File: LICENSE
+Keywords: home-automation,mdns,proxy,sofabaton,universal-remote,x1,x1s,x2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: zeroconf>=0.131
+Description-Content-Type: text/markdown
+
+# sofapython
+
+Unofficial Python library for **Sofabaton X1 / X1S / X2** universal remote
+hubs: a reverse-engineered protocol implementation and a man-in-the-middle
+**proxy** that sits between the hub and the official mobile app.
+
+This is the protocol engine extracted from the
+[Home Assistant Sofabaton X1S integration](https://github.com/m3tac0de/home-assistant-sofabaton-x1s);
+the integration is its reference consumer.
+
+> **Disclaimer:** this project is not affiliated with or endorsed by
+> Sofabaton. The protocol was reverse-engineered from network captures;
+> behavior may break with future hub firmware.
+
+## What it does
+
+- **Proxy** a physical hub: the library advertises itself via mDNS exactly
+  like a real hub, the official app connects to it, and every frame is
+  relayed, decoded and observable. The hub keeps working with the app while
+  your application gets full visibility and control.
+- **Catalogs**: read activities, devices, buttons, commands, macros and
+  favorites from the hub's wire protocol.
+- **Control**: send button/command presses, switch activities, trigger
+  find-my-remote.
+- **Provisioning** (protocol side): create/update/delete devices and
+  activities, including virtual WiFi/IP devices.
+- **Backup / restore**: export and restore hub configuration.
+- **Events**: subscribe to hub/app connection state, activity changes,
+  OTA progress and catalog updates.
+
+Deliberately **out of scope**: executing the HTTP callbacks that virtual
+WiFi/IP devices define (e.g. a Roku-style ECP listener). The library carries
+the protocol artifacts for those features so applications can build them on
+top — the Home Assistant integration does exactly that.
+
+## Install
+
+```
+pip install sofapython
+```
+
+Python 3.11+. The only dependency is
+[python-zeroconf](https://pypi.org/project/zeroconf/) (mDNS advertising and
+hub discovery).
+
+## Quickstart
+
+Find a hub, then proxy it. Blocking work runs in the event loop's
+executor and callbacks (plain functions or coroutines) are delivered on
+the loop, so application code never touches the engine threads:
+
+```python
+import asyncio
+from sofapython import AsyncX1Proxy, async_discover_hubs
+
+async def main():
+    hubs = await async_discover_hubs(timeout=5.0)   # physical hubs; proxies filtered
+    hub = hubs[0]
+
+    proxy = AsyncX1Proxy(
+        real_hub_ip=hub.host,
+        mdns_instance=hub.name,
+        mdns_txt=hub.txt,               # carries HVER -> X1/X1S/X2 classification
+        hub_version=hub.hub_version,
+    )
+    proxy.on_activity_change(lambda new, old, name: print(f"activity -> {name}"))
+
+    async with proxy:
+        await proxy.wait_until_controllable()      # own the hub (see below)
+        activities = await proxy.activities()      # {id: {name, active, ...}}
+        for dev_id in await proxy.devices():
+            print(dev_id, await proxy.commands(dev_id))   # {code: label}
+
+        await proxy.start_activity(next(iter(activities)))
+
+asyncio.run(main())
+```
+
+The reads return data directly — a cached result comes back immediately,
+otherwise the call fetches from the hub and awaits completion. The whole
+app-builder surface is a handful of coroutines: `activities()`,
+`devices()`, `commands(dev)`, `buttons(ent)`, `macros(act)`,
+`favorites(act)` to read; `press(ent, button)`, `start_activity(act)`,
+`stop_activity(act)`, `find_remote()` to control.
+
+### Two modes
+
+The proxy sits transparently between the hub and the official app, which
+gives it two distinct modes:
+
+- **Observe** — the app is connected through the proxy. You watch
+  activity changes, connects and OTA events in real time, but the app
+  owns the hub, so you can't issue commands. Gate on
+  `await proxy.wait_connected()`.
+- **Control** — no app attached; the proxy owns the hub, so reads fetch
+  fresh and commands/backup work. Gate on
+  `await proxy.wait_until_controllable()`.
+
+`start()` only spawns the transport; the connect handshake happens
+afterwards, so await the matching readiness primitive before reading or
+acting (otherwise a read raises with the reason — hub not connected, or
+an app holds it).
+
+A synchronous core (`X1Proxy`, `discover_hubs`) is also available for
+scripts and REPL use; the async class is a facade over it (its raw
+`get_*` snapshot getters are reachable via `proxy.sync`).
+
+A CLI ships as a console script:
+
+```
+sofapython discover                # scan the LAN for hubs
+sofapython run --hub 192.168.1.50  # proxy + interactive shell
+x1> status
+x1> activities
+x1> send 101 POWER_ON
+```
+
+Runnable examples — discovery, watching a live session (observe mode),
+taking control of a hub, reading per-entity detail
+(commands/macros/favorites), schema-versioned backup/restore, and
+building an HTTP callback listener on top of the library — live in
+[`sofapython/examples/`](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/tree/main/sofapython/examples).
+
+## Stability
+
+Names importable from the package root — `from sofapython import ...`,
+the set listed in `sofapython.__all__` — are the supported API and follow
+semver. Everything else (`sofapython.opcode_handlers`, frame parsing,
+wire schemas, the `proxy_*` mixin modules) is internal and may change
+between minor releases. The library raises stdlib exceptions
+(`ValueError` for malformed/unclassifiable input, `RuntimeError` /
+`TimeoutError` for transport and ack failures); there are no custom
+exception types. Until 1.0, pin a minor version.
+
+## License
+
+MIT — see [LICENSE](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/LICENSE).

sofapython-0.0.1rc1/custom_components/sofabaton_x1s/lib/__init__.py

@@ -0,0 +1,136 @@
+"""sofapython — unofficial Sofabaton X1/X1S/X2 protocol library and proxy.
+
+This module is the curated public API: every name exported here (see
+``__all__``) is semver-stable for the ``sofapython`` distribution.
+Submodule internals (``opcode_handlers``, frame parsing, wire schemas,
+the ``proxy_*`` mixins, ...) remain importable but are NOT a stable
+surface and may change between minor releases.
+
+The library raises stdlib exceptions (``ValueError`` for unclassifiable
+or malformed input, ``RuntimeError``/``TimeoutError`` for transport and
+ack failures) rather than custom exception types.
+
+In-tree, this package doubles as ``custom_components.sofabaton_x1s.lib``
+for the Home Assistant integration; the wheel build remaps it to the
+top-level ``sofapython`` package (see pyproject.toml).
+"""
+
+from .version import __version__  # noqa: F401
+
+# Protocol constants (ButtonName, BUTTONNAME_BY_CODE, DEVICE_CLASS_*,
+# opcode helpers, ...). Star re-export predates the curated API and is
+# kept for backward compatibility; protocol_const defines __all__.
+from . import protocol_const as _protocol_const
+from .protocol_const import *  # noqa: F401,F403
+
+# Hub-variant classification and shared defaults.
+from .hub_versions import (  # noqa: F401
+    ACTIVITY_BACKUP_SCHEMA_VERSION,
+    DEFAULT_HUB_LISTEN_BASE,
+    DEFAULT_PROXY_UDP_PORT,
+    DEVICE_BACKUP_SCHEMA_VERSION,
+    HUB_BUNDLE_SCHEMA_VERSION,
+    HUB_VERSION_BY_HVER,
+    HUB_VERSION_X1,
+    HUB_VERSION_X1S,
+    HUB_VERSION_X2,
+    HVER_BY_HUB_VERSION,
+    HVER_X1,
+    HVER_X1S,
+    HVER_X2,
+    MDNS_SERVICE_TYPE_BY_VERSION,
+    MDNS_SERVICE_TYPE_X1,
+    MDNS_SERVICE_TYPE_X2,
+    MDNS_SERVICE_TYPES,
+    PROXY_TXT_KEY,
+    PROXY_TXT_VALUE,
+    classify_hub_version,
+    is_proxy_advertisement,
+    mdns_service_type_for_props,
+)
+
+# Per-hub logging helper. LogTag/HubLogger remain importable from
+# sofapython.hub_logging but are internal plumbing, not public API.
+from .hub_logging import get_hub_logger  # noqa: F401
+
+# The proxy engine.
+from .x1_proxy import X1Proxy  # noqa: F401
+
+# LAN discovery of physical hubs.
+from .discovery import (  # noqa: F401
+    DEFAULT_DISCOVERY_TIMEOUT,
+    DiscoveredHub,
+    HubBrowser,
+    decode_txt_properties,
+    discover_hubs,
+    normalize_advertisement,
+)
+
+# Device catalog records and provisioning flows.
+from .devices import DeviceConfig, device_config_from_backup, parse_device_record  # noqa: F401
+from .device_create import (  # noqa: F401
+    DeviceCreateRequest,
+    DeviceCreateResult,
+    run_device_create,
+)
+
+# Step/ack result types surfaced by proxy operations.
+from .ack import AckOutcome, InputsBurstResult, SendStepResult  # noqa: F401
+
+# Asyncio facade over the threaded core.
+from .aio import AsyncHubBrowser, AsyncX1Proxy, async_discover_hubs  # noqa: F401
+
+_CURATED = [
+    "__version__",
+    # hub_versions
+    "ACTIVITY_BACKUP_SCHEMA_VERSION",
+    "DEFAULT_HUB_LISTEN_BASE",
+    "DEFAULT_PROXY_UDP_PORT",
+    "DEVICE_BACKUP_SCHEMA_VERSION",
+    "HUB_BUNDLE_SCHEMA_VERSION",
+    "HUB_VERSION_BY_HVER",
+    "HUB_VERSION_X1",
+    "HUB_VERSION_X1S",
+    "HUB_VERSION_X2",
+    "HVER_BY_HUB_VERSION",
+    "HVER_X1",
+    "HVER_X1S",
+    "HVER_X2",
+    "MDNS_SERVICE_TYPE_BY_VERSION",
+    "MDNS_SERVICE_TYPE_X1",
+    "MDNS_SERVICE_TYPE_X2",
+    "MDNS_SERVICE_TYPES",
+    "PROXY_TXT_KEY",
+    "PROXY_TXT_VALUE",
+    "classify_hub_version",
+    "is_proxy_advertisement",
+    "mdns_service_type_for_props",
+    # hub_logging
+    "get_hub_logger",
+    # proxy
+    "X1Proxy",
+    # discovery
+    "DEFAULT_DISCOVERY_TIMEOUT",
+    "DiscoveredHub",
+    "HubBrowser",
+    "decode_txt_properties",
+    "discover_hubs",
+    "normalize_advertisement",
+    # devices / provisioning
+    "DeviceConfig",
+    "device_config_from_backup",
+    "parse_device_record",
+    "DeviceCreateRequest",
+    "DeviceCreateResult",
+    "run_device_create",
+    # ack results
+    "AckOutcome",
+    "InputsBurstResult",
+    "SendStepResult",
+    # asyncio facade
+    "AsyncHubBrowser",
+    "AsyncX1Proxy",
+    "async_discover_hubs",
+]
+
+__all__ = list(getattr(_protocol_const, "__all__", [])) + _CURATED

sofapython-0.0.1rc1/custom_components/sofabaton_x1s/lib/ack.py

@@ -0,0 +1,79 @@
+"""Typed outcomes for hub ack waits.
+
+Every ``wait_for_*`` site distinguishes three states:
+
+* ``acked``    -- the hub answered, and the answer was a success ack.
+* ``rejected`` -- the hub answered explicitly, but the answer was a
+  rejection (e.g. ``STATUS_ACK`` carrying a non-zero status byte).
+* ``timeout``  -- the hub did not answer within the wait window.
+
+Conflating the latter two leads to fail-slow behaviour during multi-step
+sequences: the orchestration spins out the full per-step timeout rather
+than aborting at the first hub-side refusal. The dataclasses below give
+callers a uniform way to branch.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class AckOutcome(Enum):
+    """Three-way classification of an ack wait."""
+
+    acked = "acked"
+    rejected = "rejected"
+    timeout = "timeout"
+
+
+@dataclass(frozen=True, slots=True)
+class SendStepResult:
+    """Outcome of a single ``_send_step`` exchange."""
+
+    outcome: AckOutcome
+    ack_opcode: int | None = None
+    ack_payload: bytes | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.outcome is AckOutcome.acked
+
+    @property
+    def rejected(self) -> bool:
+        return self.outcome is AckOutcome.rejected
+
+    @property
+    def timed_out(self) -> bool:
+        return self.outcome is AckOutcome.timeout
+
+
+@dataclass(frozen=True, slots=True)
+class InputsBurstResult:
+    """Outcome of :meth:`X1Proxy.wait_for_activity_inputs_burst`.
+
+    ``payloads`` is populated on :attr:`AckOutcome.acked` and is empty
+    on rejection or timeout.
+    """
+
+    outcome: AckOutcome
+    payloads: tuple[bytes, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        return self.outcome is AckOutcome.acked
+
+    @property
+    def rejected(self) -> bool:
+        return self.outcome is AckOutcome.rejected
+
+    @property
+    def timed_out(self) -> bool:
+        return self.outcome is AckOutcome.timeout
+
+
+__all__ = [
+    "AckOutcome",
+    "InputsBurstResult",
+    "SendStepResult",
+]