sofapython 0.0.1rc1__py3-none-any.whl

sofapython-0.0.1rc1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,39 @@
+sofapython/__init__.py,sha256=mEJz7o-mpRi7wit1tpy4RF9XblQU0AowuH7x6O1xzMs,4091
+sofapython/ack.py,sha256=CCE1ph2FaZKdbY3_sQc0_m5Xei7Alyk7WC4797ZKh7M,2021
+sofapython/aio.py,sha256=iuOOk9VxYx3iycs45Nz2hW9tOe5gOfOoG-6LOi1ajfU,19947
+sofapython/backup_export.py,sha256=EwXMU6eLOwXAfiuGZ6Lft3_ffLbwRsJOfqgQ-KLbH4o,17897
+sofapython/blob_decoders.py,sha256=6RiZLSVAacnsT8U0mrwRzb5F3ZzhWrKIWnfdv0A1oQ8,30509
+sofapython/cli.py,sha256=Ux2wzPxHDuJ-BW8UAxdy4xJw6kUuPEbrXZVeQ2oApIQ,16297
+sofapython/commands.py,sha256=4QqKURFv6BUJu8g9hkL31gCFV2JyNJ_WWpa9i3AcgR8,42747
+sofapython/deframer.py,sha256=amMFAVUzhZyG_1-BpEwSNQaQT-m8rmLHZgLevlctPJ0,2448
+sofapython/device_create.py,sha256=Ej0J0j0z6uDPc9dnyxwVrauAjyqIf8Uem4VQ6VpSwv8,46651
+sofapython/devices.py,sha256=CObuF6kouXuG49e2CTMJqw5pSgMsIgSTJvjcbOMRJpE,20101
+sofapython/discovery.py,sha256=C-Ut7OpM0PRNxhg51zo856YXf-toXs-LI7IspZ3tBzs,10258
+sofapython/frame_handlers.py,sha256=RVqfiPfurdqJOqQ7HN3-7mwNRKtFVTzb_gRzJK6ytnQ,4479
+sofapython/hub_listener.py,sha256=VA4Uygig4rOQ8jFwmh_ERQdmBzzaNXGPZsWddozXrRk,8425
+sofapython/hub_logging.py,sha256=r46r53D_UnNFK5KQQb_X8jG1Do6L7ErQzCE4Ykfg9Io,5884
+sofapython/hub_versions.py,sha256=eyvY4J32eFO5TE_YWsgWuGaPuFg3yRWQx5W7goPR1eQ,4036
+sofapython/inputs.py,sha256=uHPeXjIyi3C8irUGSH7LIas09LTkjKlFJ0kwopXK2v8,18613
+sofapython/macros.py,sha256=L2D2ZKt3QaEY6RE4Y5ZLodXJg5rXtVn2qhq2zTonb_Q,24364
+sofapython/notify_demuxer.py,sha256=W7ibe2hiHwT6WBFpn4DS6TwESl1jvdhwlp2RvOtgo7Y,14570
+sofapython/opcode_handlers.py,sha256=OkqNW1vQOeBAviZJAU6l6rTH3tXdmN3K_F8vVaEeKbY,61830
+sofapython/protocol_const.py,sha256=uvDa4qmS6dRcAQgfHtowFzVup5RUm2WeZcreuRKP9ZE,24067
+sofapython/proxy_ack_waiters.py,sha256=O3UyQ9hQU1Uy2_lb0_YGrztNtoKyyTrlof8U7ljznms,27302
+sofapython/proxy_activity_ops.py,sha256=hyBU_lXSPhVHdFS3kzQmQ7ACdScTWDmniL-hkjAI6PU,36728
+sofapython/proxy_backup.py,sha256=9CluWy_Ik54Gu7PrlGS5jqoR_AqFTSCsvAD6HaKlgQE,21330
+sofapython/proxy_backup_export.py,sha256=TuzZdN1pcCZacvSYAQgrETS1laIr6Jn4HnF12LLRmvc,18547
+sofapython/proxy_catalog.py,sha256=5Cop0eJrhejXW_LzvgJgcUKtFYPybMxEu0fK4_a6r8o,36066
+sofapython/proxy_frame_decode.py,sha256=DfEqhQl6Oujo-JbTtPxwLJUe_C8xHjOh0fj7qeyW14s,9595
+sofapython/proxy_ir_blob.py,sha256=E7WBQdJmX_g06t83f-Ze8fU4s6-yHM34WBQyRVtgVZw,25604
+sofapython/proxy_restore.py,sha256=yPT7XwCSFtNE5r0u6_MPvKhfo-ADcdqU5I6DzwI1TVk,84890
+sofapython/proxy_wifi_device.py,sha256=YSpLpIrjp9e7Z0SdCoKP7ET9fg5r1zXCtjVtZwb2Yqk,41828
+sofapython/state_helpers.py,sha256=4hMAk7y_f7hU5Iai2wwEvNdpCRipuQ_dD4u_L4FmBik,26268
+sofapython/transport_bridge.py,sha256=iPSZLQfzpSUfcqUBvZ5zKUnYqhAb70LIHTmSaYuY370,31795
+sofapython/version.py,sha256=i9_xSxMzj7E9hJXj9QgXIWml3dOcpEl0mW0IqARoJuE,196
+sofapython/wire_schema.py,sha256=Nq8W62toS6GNMeH8EiOMwnwHCkC297MJ5C7yiyMIHX0,5542
+sofapython/x1_proxy.py,sha256=GN1ggPCzJmFoZb_sTle5TMlkNQjjDgnXNFAHSxcNjgE,67237
+sofapython-0.0.1rc1.dist-info/METADATA,sha256=IqG_hTZTtfy71R1FZvLrK16xPmko0bArkscdXWmSp1k,6669
+sofapython-0.0.1rc1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+sofapython-0.0.1rc1.dist-info/entry_points.txt,sha256=gnkMusJA3Bhc6kJFWq503XZu4kg17dko3emZXHWEvdU,51
+sofapython-0.0.1rc1.dist-info/licenses/LICENSE,sha256=NLcQ2crTlHYykQmFVhdgRs8I--N67dOjyHOfm4-j7sA,1065
+sofapython-0.0.1rc1.dist-info/RECORD,,

sofapython-0.0.1rc1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

sofapython-0.0.1rc1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sofapython = sofapython.cli:main

sofapython-0.0.1rc1.dist-info/licenses/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.