HueBLE 2.2.2__tar.gz → 2.2.4__tar.gz

{hueble-2.2.2 → hueble-2.2.4}/HueBLE.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: HueBLE
-Version: 2.2.2
+Version: 2.2.4
 Summary: Python module for controlling and monitoring Bluetooth Philips Hue bulbs
 Author-email: Harvey Lelliott <harveylelliott@duck.com>
 License: MIT License
@@ -64,7 +64,8 @@ Python module for controlling Bluetooth Philips Hue lights.
 
 This Python module enables you to control Philips Hue Bluetooth lights directly
 from your computer, without the need for a Hue bridge or ZigBee dongle.
-It leverages the Bleak library to interact with Bluetooth Philips Hue lights.
+It leverages the Bleak library to interact with Bluetooth Philips Hue lights including 
+the smart plugs.
 
 
 ## Features
@@ -73,10 +74,13 @@ It leverages the Bleak library to interact with Bluetooth Philips Hue lights.
 - 🌗 Brightness control
 - 🌡️ Colour temp control 
 - 🌈 XY colour control
+- ✨ Built-in effects with custom colour and speed
+- ⏱️ Custom transitions, including instant changes
 - ❔ Light state (power/brightness/temp/colour)
 - ⚙️ Light configuration (name)
 - 📊 Light metadata (manufacturer/model/zigbee address)
 - 🤜 Supports push & polling models
+- 🔌 Hue smart plug support
 - 🔂 Simple structure
 - 📜 Mediocre documentation
 - ✔️ More emojis than strictly necessary
@@ -177,6 +181,39 @@ if __name__ == "__main__":
 ```
 
 
+### Transitions
+
+Power, brightness, colour temperature and colour changes can use a custom
+transition time.
+
+```python
+await light.set_power(True, transition_ms=0)
+await light.set_brightness(254, transition_ms=100)
+await light.set_colour_temp(250, transition_ms=400)
+await light.set_colour_xy(0.3, 0.4, transition_ms=200)
+```
+
+`transition_ms=0` makes the change instant. Transition times use 100 ms steps.
+
+
+### Effects
+
+HueBLE supports Hue effects such as Candle, Fireplace, Sunrise and Sunset.
+Effects can use a custom colour, brightness and speed.
+
+```python
+await light.set_colour_effect(
+    0.30,
+    0.14,
+    254,
+    HueBLE.EffectType.CANDLE,
+    128,
+)
+```
+
+Effect speed ranges from `0` (slowest) to `255` (fastest).
+
+
 ### Demo program
 
 A more fully featured demo program can be found in  ``` examples/demo.py ``` which demonstrates all of the implemented features.

{hueble-2.2.2 → hueble-2.2.4}/HueBLE.py

@@ -17,7 +17,6 @@ from struct import pack, unpack
 from typing import Callable
 from enum import Enum
 
-
 #: String containing manufacturer. Handle 15.
 UUID_MANUFACTURER = "00002a29-0000-1000-8000-00805f9b34fb"
 
@@ -130,6 +129,10 @@ UNPACK_EFFECT_API_TEMPERATURE_WITH_EFFECT = "<xxBxxBxxHxxBxxB"
 #: data stream unpack format string for decoding plain temperature without effect (effect API)
 UNPACK_EFFECT_API_TEMPERATURE_WITHOUT_EFFECT = "<xxBxxBxxH"
 
+#: data stream unpack format string for decoding the onoff-only report (effect API),
+#: sent by devices that only support on/off, e.g. the Hue smart plug
+UNPACK_EFFECT_API_ONOFF_ONLY = "<xxB"
+
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -140,14 +143,23 @@ class EffectType(Enum):
     CANDLE = 0x01
     FIREPLACE = 0x02
     PRISM = 0x03
+    SUNRISE = 0x09
     SPARKLE = 0x0A
     OPAL = 0x0B
     GLISTEN = 0x0C
+    SUNSET = 0x0D
     UNDERWATER = 0x0E
     COSMOS = 0x0F
     SUNBEAM = 0x10
     ENCHANT = 0x11
 
+    @classmethod
+    def _missing_(cls, value):
+        _LOGGER.warning(
+            f"Unknown effect type: '{value}' reported by light, using default of none!"
+        )
+        return cls.NONE
+
 
 #: EFFECT_COMMANDS (hex string) for the Effect Characteristic endpoint containing one byte id and one byte data length
 class EffectCommands(Enum):
@@ -155,10 +167,26 @@ class EffectCommands(Enum):
     BRIGHTNESS = "0201"
     TEMPERATURE = "0302"
     COLOURXY = "0404"
+    TRANSITION_TIME = "0502"
     EFFECT = "0601"
     EFFECT_SPEED = "0801"
 
 
+def _transition_tlv(transition_ms: int) -> bytes:
+    if not isinstance(transition_ms, int):
+        raise TypeError("transition_ms must be an integer")
+    if transition_ms < 0 or transition_ms % 100 != 0:
+        raise ValueError("transition_ms must be a non-negative multiple of 100")
+
+    units = transition_ms // 100
+    if units > 0xFFFF:
+        raise ValueError("transition_ms is too large")
+
+    return bytes.fromhex(EffectCommands.TRANSITION_TIME.value) + units.to_bytes(
+        2, "little"
+    )
+
+
 class HueBleError(Exception):
     """
     Base exception of HueBLE.
@@ -469,10 +497,19 @@ class HueBleLight(object):
                         f"""Light "{self.name}" has informed us of a new"""
                         f""" colour temp state of ({self.colour_temp})"""
                     )
+                elif len(data) == 3:
+                    # device only reports its onoff value (e.g. smart plug)
+                    onoff = unpack(UNPACK_EFFECT_API_ONOFF_ONLY, data)[0]
+                    self._power_on = bool(onoff)
+
+                    _LOGGER.debug(
+                        f"""Light "{self.name}" has informed us of a new"""
+                        f""" power state ({self._power_on})"""
+                    )
                 else:
                     # so far unkown
                     _LOGGER.warning(
-                        "unrecognized effect response with length {len(data)}: {data}"
+                        f"unrecognized effect response with length {len(data)}: {data}"
                     )
 
                 if effect_state_changed:
@@ -1205,6 +1242,11 @@ class HueBleLight(object):
             if write_state:
                 self._colour_temp = colour_temp
                 self._power_on = bool(onoff)
+        elif len(buf) == 3:
+            # device only reports its onoff value (e.g. smart plug)
+            onoff = unpack(UNPACK_EFFECT_API_ONOFF_ONLY, buf)[0]
+            if write_state:
+                self._power_on = bool(onoff)
         else:
             # so far unkown
             _LOGGER.warning(
@@ -1217,28 +1259,77 @@ class HueBleLight(object):
         """Sets the name of the light. Not tested, use at own risk."""
         await self._write_gatt(UUID_NAME, str.encode(name))
 
-    async def set_power(self, on: bool):
+    async def set_power(self, on: bool, transition_ms: int | None = None):
         """Sets the power state of the light."""
-        await self._write_gatt(UUID_POWER, bytes([1 if on else 0]))
+        if transition_ms is None:
+            await self._write_gatt(UUID_POWER, bytes([1 if on else 0]))
+            return
+
+        buf = (
+            bytes.fromhex(EffectCommands.ONOFF.value)
+            + bytes([1 if on else 0])
+            + _transition_tlv(transition_ms)
+        )
+        await self._write_gatt(UUID_EFFECTS, buf)
 
-    async def set_brightness(self, brightness: int):
+    async def set_brightness(
+        self, brightness: int, transition_ms: int | None = None
+    ):
         """Sets the brightness from an integer between 0 and 255"""
-        await self._write_gatt(UUID_BRIGHTNESS, bytes([max(min(brightness, 254), 1)]))
+        brightness = max(min(brightness, 254), 1)
+        if transition_ms is None:
+            await self._write_gatt(UUID_BRIGHTNESS, bytes([brightness]))
+            return
 
-    async def set_colour_temp(self, colour_temp: int):
+        buf = (
+            bytes.fromhex(EffectCommands.BRIGHTNESS.value)
+            + bytes([brightness])
+            + _transition_tlv(transition_ms)
+        )
+        await self._write_gatt(UUID_EFFECTS, buf)
+
+    async def set_colour_temp(
+        self, colour_temp: int, transition_ms: int | None = None
+    ):
         """Sets the temperature from an int between 153 and 500.
         Uses mireds."""
         temp = max(min(int(colour_temp), 500), 153)
-        y = temp.to_bytes(2, "little")
-        await self._write_gatt(UUID_TEMPERATURE, y)
+        data = temp.to_bytes(2, "little")
+        if transition_ms is None:
+            await self._write_gatt(UUID_TEMPERATURE, data)
+            return
+
+        buf = (
+            bytes.fromhex(EffectCommands.TEMPERATURE.value)
+            + data
+            + _transition_tlv(transition_ms)
+        )
+        await self._write_gatt(UUID_EFFECTS, buf)
 
-    async def set_colour_xy(self, x: float, y: float):
+    async def set_colour_xy(
+        self, x: float, y: float, transition_ms: int | None = None
+    ):
         """Sets the XY colour coordinates from floats between 0.0 and 1.0."""
-        buf = pack("<HH", int(x * 0xFFFF), int(y * 0xFFFF))
-        await self._write_gatt(UUID_XY_COLOUR, buf)
+        data = pack("<HH", int(x * 0xFFFF), int(y * 0xFFFF))
+        if transition_ms is None:
+            await self._write_gatt(UUID_XY_COLOUR, data)
+            return
+
+        buf = (
+            bytes.fromhex(EffectCommands.COLOURXY.value)
+            + data
+            + _transition_tlv(transition_ms)
+        )
+        await self._write_gatt(UUID_EFFECTS, buf)
 
     async def set_colour_effect(
-        self, x: float, y: float, brightness: int, effect: EffectType, effect_speed: int
+        self,
+        x: float,
+        y: float,
+        brightness: int,
+        effect: EffectType,
+        effect_speed: int,
+        transition_ms: int | None = None,
     ):
         """
         Sets XY colour, brightness, effect and effect speed.
@@ -1262,7 +1353,7 @@ class HueBleLight(object):
                 bytes.fromhex(EffectCommands.EFFECT.value),
                 max(min(effect.value, 254), 1),
                 bytes.fromhex(EffectCommands.EFFECT_SPEED.value),
-                max(min(effect_speed, 254), 1),
+                max(min(effect_speed, 255), 0),
             )
         else:
             # if no effect is selected we can just operate in colourxy mode and ommit the effect data in the transfer
@@ -1276,10 +1367,17 @@ class HueBleLight(object):
                 int(x * 0xFFFF),
                 int(y * 0xFFFF),
             )
+        if transition_ms is not None:
+            buf += _transition_tlv(transition_ms)
         await self._write_gatt(UUID_EFFECTS, buf)
 
     async def set_temperature_effect(
-        self, colour_temp: int, brightness: int, effect: EffectType, effect_speed: int
+        self,
+        colour_temp: int,
+        brightness: int,
+        effect: EffectType,
+        effect_speed: int,
+        transition_ms: int | None = None,
     ):
         """
         Sets colour temperature, brightness, effect and effect speed.
@@ -1303,7 +1401,7 @@ class HueBleLight(object):
                 bytes.fromhex(EffectCommands.EFFECT.value),
                 max(min(effect.value, 254), 1),
                 bytes.fromhex(EffectCommands.EFFECT_SPEED.value),
-                max(min(effect_speed, 254), 1),
+                max(min(effect_speed, 255), 0),
             )
         else:
             # if no effect is selected we can just operate in colourxy mode and ommit the effect data in the transfer
@@ -1316,6 +1414,8 @@ class HueBleLight(object):
                 bytes.fromhex(EffectCommands.TEMPERATURE.value),
                 temperature,
             )
+        if transition_ms is not None:
+            buf += _transition_tlv(transition_ms)
         await self._write_gatt(UUID_EFFECTS, buf)
 
     @property

{hueble-2.2.2 → hueble-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: HueBLE
-Version: 2.2.2
+Version: 2.2.4
 Summary: Python module for controlling and monitoring Bluetooth Philips Hue bulbs
 Author-email: Harvey Lelliott <harveylelliott@duck.com>
 License: MIT License
@@ -64,7 +64,8 @@ Python module for controlling Bluetooth Philips Hue lights.
 
 This Python module enables you to control Philips Hue Bluetooth lights directly
 from your computer, without the need for a Hue bridge or ZigBee dongle.
-It leverages the Bleak library to interact with Bluetooth Philips Hue lights.
+It leverages the Bleak library to interact with Bluetooth Philips Hue lights including 
+the smart plugs.
 
 
 ## Features
@@ -73,10 +74,13 @@ It leverages the Bleak library to interact with Bluetooth Philips Hue lights.
 - 🌗 Brightness control
 - 🌡️ Colour temp control 
 - 🌈 XY colour control
+- ✨ Built-in effects with custom colour and speed
+- ⏱️ Custom transitions, including instant changes
 - ❔ Light state (power/brightness/temp/colour)
 - ⚙️ Light configuration (name)
 - 📊 Light metadata (manufacturer/model/zigbee address)
 - 🤜 Supports push & polling models
+- 🔌 Hue smart plug support
 - 🔂 Simple structure
 - 📜 Mediocre documentation
 - ✔️ More emojis than strictly necessary
@@ -177,6 +181,39 @@ if __name__ == "__main__":
 ```
 
 
+### Transitions
+
+Power, brightness, colour temperature and colour changes can use a custom
+transition time.
+
+```python
+await light.set_power(True, transition_ms=0)
+await light.set_brightness(254, transition_ms=100)
+await light.set_colour_temp(250, transition_ms=400)
+await light.set_colour_xy(0.3, 0.4, transition_ms=200)
+```
+
+`transition_ms=0` makes the change instant. Transition times use 100 ms steps.
+
+
+### Effects
+
+HueBLE supports Hue effects such as Candle, Fireplace, Sunrise and Sunset.
+Effects can use a custom colour, brightness and speed.
+
+```python
+await light.set_colour_effect(
+    0.30,
+    0.14,
+    254,
+    HueBLE.EffectType.CANDLE,
+    128,
+)
+```
+
+Effect speed ranges from `0` (slowest) to `255` (fastest).
+
+
 ### Demo program
 
 A more fully featured demo program can be found in  ``` examples/demo.py ``` which demonstrates all of the implemented features.

{hueble-2.2.2 → hueble-2.2.4}/README.md

@@ -15,7 +15,8 @@ Python module for controlling Bluetooth Philips Hue lights.
 
 This Python module enables you to control Philips Hue Bluetooth lights directly
 from your computer, without the need for a Hue bridge or ZigBee dongle.
-It leverages the Bleak library to interact with Bluetooth Philips Hue lights.
+It leverages the Bleak library to interact with Bluetooth Philips Hue lights including 
+the smart plugs.
 
 
 ## Features
@@ -24,10 +25,13 @@ It leverages the Bleak library to interact with Bluetooth Philips Hue lights.
 - 🌗 Brightness control
 - 🌡️ Colour temp control 
 - 🌈 XY colour control
+- ✨ Built-in effects with custom colour and speed
+- ⏱️ Custom transitions, including instant changes
 - ❔ Light state (power/brightness/temp/colour)
 - ⚙️ Light configuration (name)
 - 📊 Light metadata (manufacturer/model/zigbee address)
 - 🤜 Supports push & polling models
+- 🔌 Hue smart plug support
 - 🔂 Simple structure
 - 📜 Mediocre documentation
 - ✔️ More emojis than strictly necessary
@@ -128,6 +132,39 @@ if __name__ == "__main__":
 ```
 
 
+### Transitions
+
+Power, brightness, colour temperature and colour changes can use a custom
+transition time.
+
+```python
+await light.set_power(True, transition_ms=0)
+await light.set_brightness(254, transition_ms=100)
+await light.set_colour_temp(250, transition_ms=400)
+await light.set_colour_xy(0.3, 0.4, transition_ms=200)
+```
+
+`transition_ms=0` makes the change instant. Transition times use 100 ms steps.
+
+
+### Effects
+
+HueBLE supports Hue effects such as Candle, Fireplace, Sunrise and Sunset.
+Effects can use a custom colour, brightness and speed.
+
+```python
+await light.set_colour_effect(
+    0.30,
+    0.14,
+    254,
+    HueBLE.EffectType.CANDLE,
+    128,
+)
+```
+
+Effect speed ranges from `0` (slowest) to `255` (fastest).
+
+
 ### Demo program
 
 A more fully featured demo program can be found in  ``` examples/demo.py ``` which demonstrates all of the implemented features.

{hueble-2.2.2 → hueble-2.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "HueBLE"
-version = "2.2.2"
+version = "2.2.4"
 dependencies = [
   "bleak>=0.19.0",
   "bleak-retry-connector",

{hueble-2.2.2 → hueble-2.2.4}/tests/test_HueBLE.py

@@ -370,6 +370,49 @@ async def test_commands(
             },
             id="temperature_effect",
         ),
+        pytest.param(
+            {
+                HueBLE.UUID_MANUFACTURER: "Philippe Hue".encode(),
+                HueBLE.UUID_MODEL: "Fancy new light".encode(),
+                HueBLE.UUID_FW_VERSION: "1.7.10".encode(),
+                HueBLE.UUID_ZIGBEE_ADDRESS: bytes.fromhex("00010203040506070809"),
+                HueBLE.UUID_NAME: "L A M P".encode(),
+                HueBLE.UUID_EFFECTS: bytes.fromhex("01010102014503022c01060115080138"),
+            },
+            {
+                "manufacturer": "Philippe Hue",
+                "model": "Fancy new light",
+                "firmware": "1.7.10",
+                "zigbee_address": "00:01:02:03:04:05:06:07:08:09",
+                "name_in_app": "L A M P",
+                "power_state": True,
+                "brightness": 69,
+                "colour_temp": 300,
+                "colour_xy": None,
+                "effect": (HueBLE.EffectType.NONE, 56),
+            },
+            id="unknown_effect",
+        ),
+        pytest.param(
+            {
+                HueBLE.UUID_MANUFACTURER: "Philippe Hue".encode(),
+                HueBLE.UUID_MODEL: "Fancy new light".encode(),
+                HueBLE.UUID_FW_VERSION: "1.7.10".encode(),
+                HueBLE.UUID_ZIGBEE_ADDRESS: bytes.fromhex("00010203040506070809"),
+                HueBLE.UUID_NAME: "L A M P".encode(),
+                # on/off-only device (e.g. smart plug): only the onoff TLV is reported
+                HueBLE.UUID_EFFECTS: bytes.fromhex("010100"),
+            },
+            {
+                "manufacturer": "Philippe Hue",
+                "model": "Fancy new light",
+                "firmware": "1.7.10",
+                "zigbee_address": "00:01:02:03:04:05:06:07:08:09",
+                "name_in_app": "L A M P",
+                "power_state": False,
+            },
+            id="effect_onoff_only",
+        ),
     ],
 )
 async def test_poll_state(