Metadata-Version: 2.4
Name: aiohuesyncbox
Version: 0.1.5
Summary: Asyncio package to communicate with a Philips Hue Play HDMI Sync Box.
Author-email: Michel van de Wetering <michel.van.de.wetering@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/mvdwetering/aiohuesyncbox
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.13.2
Requires-Dist: mashumaro>=3.22
Provides-Extra: test
Requires-Dist: mypy==1.17.0; extra == "test"
Requires-Dist: ruff==0.14.10; extra == "test"
Requires-Dist: pytest>=9.1.1; extra == "test"
Requires-Dist: pytest-asyncio>=1.4.0; extra == "test"
Dynamic: license-file

# AIOHUESYNCBOX

Asyncio package to communicate with Philips Hue Play Sync devices (box and screen sync).

This package is aimed at basic control of the devices. Initial setup and configuration is assumed to have been done with the official Hue app.

## Installation

```bash
python3 -m pip install aiohuesyncbox
```

## Usage

Instantiate the HueSyncDevice class and access the API.

For more details on the API see the official API documentation on <https://developers.meethue.com> (requires free registration)

### Note on changing bridge

Changing a bridge is a bit more involved than other calls.
After calling `box.hue.set_bridge()` the syncbox will start switching which takes a while (seems to take about 15 seconds).
You will have to wait until the attributes match the expected endstate, but the status displayed on the API can be a bit confusing during the process.

These are the status changes I see when switching from bridge A to bridge B.

* ID: Bridge A, IP: Bridge A, Status: connected
* Call `box.hue.set_bridge()` with info for bridge B
* ID: Bridge B, IP: Bridge A, Status: connecting
* ID: Bridge B, IP: Bridge B, Status: disconnected
* ID: Bridge B, IP: Bridge B, Status: connected or ID: Bridge B, IP: Bridge B, Status: invalidgroup

## Examples

The examples below are available as a runnable script in the repository.
There is also an example on using `zeroconf` for device discovery.

### Registration

```python
from aiohuesyncbox import HueSyncDevice, InvalidState

# host and id can be obtained through mDNS/zeroconf discovery
# (or for testing look them up in the official Hue app)
# The ID is the number that looks like C43212345678
box = HueSyncDevice(host, id)

print("Press the button on the box for a few seconds until the light blinks green.")

registration_info = None
while not registration_info:
    try:
        registration_info = await box.register("Your application", "Your device")
    except InvalidState:
        # Indicates the button was not pressed
        pass
    await asyncio.sleep(1)

# Save registration_info somewhere and use the 'access_token' when instantiating HueSyncDevice next time
print(f"Registration ID: {registration_info.registration_id}")
print(f"Access Token: {registration_info.access_token}")

# Unregister by registration ID.
# HueSyncDevice needs to use the associated `access_token` to execute this request.
await box.unregister(registration_info['registration_id'])
```

### Basic usage

```python
from aiohuesyncbox import HueSyncDevice

# host and id can be obtained through mDNS/zeroconf discovery
# (or for testing look them up in the official Hue app)
box = HueSyncDevice(host, id, access_token_from_registration_info)

# Call initialize before interacting with the box
await box.initialize()
print(f"Name: {box.device.name}")
print(f"Sync Active: {box.execution.sync_active}")
print(f"Mode: {box.execution.mode}")
print(f"HDMI Source: {box.execution.hdmi_source}")

# Turn the box on, start syncing with video mode on input 4
await box.execution.set_state(sync_active=True, mode="video", hdmi_source="input4")

# Call refresh_data() to update with latest status from the box
await box.refresh_data()
print(f"Sync Active: {box.execution.sync_active}")
print(f"Mode: {box.execution.mode}")
print(f"HDMI Source: {box.execution.hdmi_source}")
```
