tinkly 0.2.0__tar.gz

tinkly-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include uv.lock
+recursive-include doc *.md
+recursive-include scripts *.py

tinkly-0.2.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: tinkly
+Version: 0.2.0
+Summary: Low-level Twinkly discovery, authentication, HTTP, and realtime UDP transport
+Requires-Python: >=3.12

tinkly-0.2.0/README.md

@@ -0,0 +1,45 @@
+# tinkly: a tiny interface to Twinkly v2 lights
+
+I love the Twinkly lights but the [xled library](https://github.com/scrool/xled) is
+filled with complicated cruft which obscures the actual communication layer, and seems
+to no longer be in development.
+
+In particular, xled has a totally unnecessary ZMQ queue that
+slows everything down and prevents two clients from existing.
+
+I re-implemented just the Twinkly communication part, and left all the other
+parts behind. In particular, there is no CLI - for that, you'll have to see my
+upcoming general project, "lyte".
+
+## Device communication
+
+This package provides UDP discovery, authentication, HTTP endpoint access for generation
+2 Twinkly lights.
+
+```python
+from tinkly.client import TwinklyClient
+from tinkly.discovery import discover
+from tinkly.frame import send_frame
+
+devices = list(discover(timeout=2.0))
+client = TwinklyClient(host=devices[0].ip_address)
+info = client.get('gestalt', authenticated=False).data
+client.mac = str(info['mac'])
+token = client.authenticate()
+
+client.set_realtime_mode()
+frame = bytes((255, 0, 0)) * int(str(info['number_of_led']))
+send_frame(client.host, token.value, frame)
+client.set_off_mode()
+```
+
+## Frame buffers
+
+`lyte` uses `numpy`, but I decided not to make that a dependency. Instead, we use
+Python's buffer protocol `collections.abc.Buffer`. The input is C-style unsigned bytes
+in RGB order, with three bytes per LED.  Supported inputs include `bytes`, `bytearray`,
+`array.array('B')`, `memoryview`, and C-contiguous NumPy `uint8` arrays.
+
+## The API
+
+https://rec.github.io/tinkly/

tinkly-0.2.0/doc/contributing.md

@@ -0,0 +1,27 @@
+# Building and checking the documentation
+
+The documentation tools are development dependencies. They require Python 3.12
+or newer and are not installed with the runtime library.
+
+From the repository root:
+
+```sh
+uv sync --python 3.12
+uv run python scripts/build_docs.py
+```
+
+Open `.cache/reccy-docs/site/index.html` directly in your browser. The build uses
+explicit HTML links so navigation works from disk. It also checks every page
+reachable from the landing page for broken internal page links and empty content.
+Generated HTML stays in the ignored `.cache/reccy-docs/` directory.
+
+Reccy supplies the shared site builder. Griffe analyzes the package source
+without importing tinkly or contacting devices. The extension in
+`scripts/griffe_tinkly.py` describes the generated endpoint properties and gives
+the package API index a module overview. Endpoint-specific descriptions come
+from the docstrings following their declarations in `tinkly/client.py`.
+
+Documentation source belongs in `doc/` as Markdown. Python build and verification
+helpers belong in `scripts/`.
+
+[Return to the usage guide](index.md).

tinkly-0.2.0/doc/index.md

@@ -0,0 +1,76 @@
+# Control Twinkly lights with Python
+
+Tinkly lets Python programs find Twinkly controllers on the local network,
+read their settings, change their output, and send RGB animation frames.
+Each client connects to one controller. Python 3.12 or newer is required;
+the installed library has no third-party runtime dependencies.
+
+## Install
+
+From a checkout of this repository, create an environment and install the library:
+
+```sh
+uv venv --python 3.12
+uv pip install .
+```
+
+## Find a device and change its brightness
+
+Connect your computer and lights to the same local network, then run:
+
+```python
+from tinkly.client import TwinklyClient
+from tinkly.discovery import discover
+
+devices = list(discover())
+if not devices:
+    raise SystemExit('No Twinkly devices found on the local network')
+
+for device in devices:
+    print(device.device_id, device.ip_address)
+
+client = TwinklyClient(host=devices[0].ip_address)
+print('Firmware:', client.firmware_version.data)
+print('Brightness:', client.brightness.data)
+
+client.brightness = {'mode': 'enabled', 'type': 'A', 'value': 75}
+print('Updated brightness:', client.brightness.data)
+```
+
+This example chooses the first controller found. If you already know its address,
+create the client directly with `TwinklyClient(host='192.168.1.23')`.
+
+## Reading and writing settings
+
+Reading a property sends a fresh request to the device. The result has two fields:
+`data` contains the decoded JSON object, and `http_status` contains the HTTP status.
+Writing a property sends the assigned dictionary to the device. Assignment does
+not return a response; use `client.post()` if you need to inspect that response.
+
+Firmware version and status can be read without authentication. Protected
+requests obtain an authentication token automatically. Request failures raise
+exceptions for your program to handle.
+
+Authentication, echo, deleting a layout, starting a network scan, and switching
+to realtime or off mode are methods because they perform actions.
+
+## API reference
+
+Choose the part of the library you need:
+
+| Reference | What it covers |
+| --- | --- |
+| [HTTP client and settings](reference/tinkly/client.md) | Create a client, read and write properties, authenticate, and call endpoints directly. |
+| [Device discovery](reference/tinkly/discovery.md) | Find controllers and read their addresses and identifiers. |
+| [RGB frame transmission](reference/tinkly/frame.md) | Send packed RGB frames to a controller in realtime mode. |
+| [Errors](reference/tinkly/errors.md) | Handle authentication, endpoint, discovery, and protocol failures. |
+| [Authentication helpers](reference/tinkly/authentication.md) | Low-level MAC address and challenge-response functions. |
+
+For multiple controllers, create one client per controller and send each its own
+frame. Tinkly provides the transport; your application manages animation timing,
+retries, reconnection, and coordination between controllers.
+
+## Contributing
+
+See [Building and checking the documentation](contributing.md) for the dev setup,
+local build command, and generated-property documentation extension.

tinkly-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tinkly"
+version = "0.2.0"
+description = "Low-level Twinkly discovery, authentication, HTTP, and realtime UDP transport"
+requires-python = ">=3.12"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tinkly*"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+[dependency-groups]
+dev = [
+    "griffelib>=2",
+    "pytest>=9.2.0",
+    "pyupgrade>=3.22.0",
+    "reccy",
+    "ruff>=0.17.3",
+    "ty>=0.0.97",
+    "tyro",
+]
+
+[tool.uv.sources]
+reccy = { git = "ssh://git@github.com/rec/reccy.git", branch = "main" }
+
+[tool.reccy.documentation]
+extensions = ["scripts/griffe_tinkly.py"]
+use_directory_urls = false

tinkly-0.2.0/scripts/build_docs.py

@@ -0,0 +1,8 @@
+"""Build tinkly's documentation locally without publishing it."""
+
+import tyro
+from reccy.documentation import Documentation
+
+if __name__ == '__main__':
+    index = tyro.cli(Documentation).build()
+    print(f'Built and checked documentation: {index}')

tinkly-0.2.0/scripts/griffe_tinkly.py

@@ -0,0 +1,87 @@
+"""Describe tinkly's generated endpoint properties during static API analysis."""
+
+import ast
+
+import griffe
+
+
+class EndpointProperties(griffe.Extension):
+    """Recognize getter and setter declarations on TwinklyClient."""
+
+    def on_module_instance(self, *, mod: griffe.Module, **kwargs: object) -> None:
+        """Give the generated package index a useful overview of its modules."""
+        if mod.path == 'tinkly':
+            mod.docstring = griffe.Docstring(
+                'Twinkly protocol API.\n\n'
+                'Import the symbols you need from these modules:\n\n'
+                '- [HTTP client and settings][tinkly.client]: TwinklyClient, '
+                'endpoint properties, authentication tokens, and HTTP responses.\n'
+                '- [Device discovery][tinkly.discovery]: find controllers on '
+                'the local network.\n'
+                '- [RGB frame transmission][tinkly.frame]: validate pixel '
+                'buffers and send realtime UDP frames.\n'
+                '- [Errors][tinkly.errors]: exceptions raised by protocol '
+                'operations.\n'
+                '- [Authentication helpers][tinkly.authentication]: MAC address '
+                'decoding and challenge-response calculations.',
+                parent=mod,
+            )
+
+    def on_attribute_instance(
+        self,
+        *,
+        node: ast.AST | griffe.ObjectNode,
+        attr: griffe.Attribute,
+        **kwargs: object,
+    ) -> None:
+        """Add property labels, response types, and HTTP behavior to factory calls.
+
+        Only assignments on tinkly.client.TwinklyClient are processed. Preserve
+        any endpoint-specific attribute docstring after the generated details.
+        """
+        if attr.parent is None or attr.parent.path != 'tinkly.client.TwinklyClient':
+            return
+        if not isinstance(node, ast.Assign) or not isinstance(
+            call := node.value, ast.Call
+        ):
+            return
+        if not isinstance(call.func, ast.Name) or call.func.id not in (
+            'getter',
+            'setter',
+        ):
+            return
+
+        path = ast.literal_eval(call.args[0])
+        authenticated = next(
+            (
+                ast.literal_eval(k.value)
+                for k in call.keywords
+                if k.arg == 'authenticated'
+            ),
+            True,
+        )
+        writable = call.func.id == 'setter'
+        description = (
+            f'HTTP endpoint `GET {path}`.\n\n'
+            'Each read sends a fresh request and returns a '
+            '`tinkly.client.TwinklyResponse` containing `http_status` and `data`.\n\n'
+            f'Authentication is {"required" if authenticated else "not required"}.'
+        )
+        if writable:
+            description += (
+                f'\n\nAssign a `dict[str, object]` JSON body to send `POST {path}`. '
+                'Assignment does not return the response; use `post()` when needed.'
+            )
+        else:
+            description += '\n\nThis property is read-only.'
+        description += '\n\nRequest errors propagate to the caller.'
+        if attr.docstring is not None:
+            description += f'\n\n{attr.docstring.value}'
+
+        attr.labels.difference_update({'class-attribute', 'instance-attribute'})
+        attr.labels.add('property')
+        if writable:
+            attr.labels.add('writable')
+        attr.annotation = griffe.ExprName('TwinklyResponse', parent=attr.parent)
+        attr.value = None
+        attr.docstring = griffe.Docstring(description, parent=attr)

tinkly-0.2.0/setup.cfg

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

tinkly-0.2.0/tests/test_authentication.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import unittest
+
+from tinkly.authentication import CHALLENGE_KEY, derive_key, mac_bytes, rc4
+
+
+class CryptoTests(unittest.TestCase):
+    def test_mac_bytes_accepts_common_formats(self) -> None:
+        expected = b'\x5c\xcf\x7f\x33\xaa\xff'
+
+        self.assertEqual(mac_bytes('5C:CF:7F:33:AA:FF'), expected)
+        self.assertEqual(mac_bytes('5c-cf-7f-33-aa-ff'), expected)
+        self.assertEqual(mac_bytes('5ccf7f33aaff'), expected)
+
+    def test_derive_key_matches_original_driver(self) -> None:
+        key = derive_key(CHALLENGE_KEY, '5C:CF:7F:33:AA:FF')
+
+        self.assertEqual(key, b'9\xb9\x1a]\xc7\x90.\xaa\x0cV\xc9\x8d9\xbb^\x12')
+
+    def test_rc4_known_vector(self) -> None:
+        self.assertEqual(rc4(b'Plaintext', b'Key').hex(), 'bbf316e8d940af0ad3')