Metadata-Version: 2.4
Name: xaal.yeelight
Version: 0.4.1
Summary: xAAL gateway for Yeelight devices
Author-email: Jerome Kerdreux <Jerome.Kerdreux@imt-atlantique.fr>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://recherche.imt-atlantique.fr/xaal/
Project-URL: Documentation, https://gitlab.imt-atlantique.fr/xaal/code/python/-/blob/main/devices/protocols/Yeelight/README.rst
Project-URL: Source, https://gitlab.imt-atlantique.fr/xaal/code/python/-/tree/main/devices/protocols/Yeelight
Keywords: xaal,yeelight
Classifier: Programming Language :: Python
Classifier: Topic :: Home Automation
Description-Content-Type: text/x-rst
Requires-Dist: xaal.lib
Requires-Dist: xaal.schemas
Requires-Dist: yeelight

xaal.yeelight
=============
This package provides a xAAL gateway for Yeelight lights. It supports most
Yeelight lights and bulbs. You have to enable local control on your
Yeelight device to use this package. You can do this by enabling the
"LAN Control" option in the Yeelight app.

The gateway loads bulbs from the configuration file and creates a xAAL
device for each of them. Check ``yeelight.ini`` after the first run to
see the devices created. A ``gateway.basic`` device is also registered
on the bus, tracking connected (embedded) and disconnected (inactive)
bulbs.

Notes
-----
This gateway uses the asyncio API provided by the Yeelight library
(``yeelight.aio.AsyncBulb``) and the xAAL ``AsyncEngine``.

Boot & Connect flow
~~~~~~~~~~~~~~~~~~~
On startup, ``setup()`` loads bulbs from config and starts
``async_listen`` on each. The Yeelight library handles reconnection
automatically:

* While connected: push notifications arrive in real time;
  ``sync()`` is rarely needed.
* If a bulb disconnects: backoff (15s) then retry, and
  ``on_properties({connected: False/True})`` updates the gateway status.

Important: if a bulb is offline at boot, ``async_listen`` fails
immediately with **no retry**. The bulb will only be picked up later
by ``discover()`` (which runs every 300 seconds). This is a limitation
of the library.

Rate limiting
~~~~~~~~~~~~~
Yeelight bulbs enforce a hardware limit of 60 commands/minute.
To stay under this limit:

* ``turn_on`` / ``turn_off`` skip if already in the target state.
* ``sync()`` coalesces multiple ``get_properties`` calls into one,
  and is skipped if a push notification arrived within the last 300ms.
* ``discover()`` is the only periodic poll (every 300s).
