Merge pull request #8 from home-assistant-ecosystem/dev

0.4.0

Author: fabaff

.github/workflows/python.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@v2

CHANGELOG.rst

@@ -1,6 +1,25 @@
 Changelog
 =========
 
+0.4.0 (2021-12-02)
+------------------
+
+- Support for dimmers
+- Allos later async_timeout
+- Refactored shades
+
+  - With version 0.3.0
+    ::
+
+          dingz.shade_down(shade_id)
+
+  - Starting from 0.4.0:
+    ::
+
+          shade = dingz.shades.get(shade_id)
+          shade.shade_down()
+
+
 0.3.0 (2020-11-08)
 ------------------
 

README.rst

@@ -46,13 +46,43 @@ The package is available in the `Python Package Index <https://pypi.python.org/>
 
     $ pip install dingz
 
+On a Fedora-based system or on a CentOS/RHEL machine which has EPEL enabled.
+
+.. code:: bash
+
+    $ sudo dnf -y install python3-dingz
+
 Module usage
 ------------
 
 Every unit has its own web interface: `http://IP_ADDRESS <http://IP_ADDRESS>`_ .
 
 See `example.py` for detail about module.
 
+
+How to operate shades / dimmers
+-------------------------------
+
+.. code:: python
+
+    d = Dingz("ip_address_or_host")
+    # Fetch config, this has to be done once to fetch all details about the shades/dimmers
+    await d.get_devices_config()
+
+    # Fetch the current state of the lights/vers
+    await d.get_state()
+
+    # Get details about shade
+    shade_0 = d.shades.get(0)
+    print("Blinds: %s Lamella: %s" % (shade_0.current_blind_level(), shade_0.current_lamella_level()))
+
+    # Operate shade
+    shade_0.shade_down()
+
+    # Turn on light
+    d.dimmers.get(2).turn_on(brightness_pct=70)
+
+
 CLI usage
 ---------
 

dingz/__init__.py

@@ -1,14 +1,13 @@
 """Base details for the dingz Python bindings."""
 import asyncio
-import json
 import socket
 from typing import Any, Mapping, Optional
 
 import aiohttp
 import async_timeout
 
 from .constants import TIMEOUT, USER_AGENT, CONTENT_TYPE_JSON, CONTENT_TYPE, CONTENT_TYPE_TEXT_PLAIN
-from .exceptions import DingzConnectionError, DingzError
+from .exceptions import DingzConnectionError
 
 
 async def make_call(

dingz/cli.py

@@ -1,11 +1,12 @@
 """Command-line interface to interact with dingz devices."""
-import click
-from .discovery import discover_dingz_devices
 import asyncio
+from functools import wraps
 
+import click
 
-import asyncio
-from functools import wraps
+from dingz.dingz import Dingz
+
+from .discovery import discover_dingz_devices
 
 
 def coro(f):
@@ -39,5 +40,61 @@ async def discover():
         )
 
 
+@main.group("info")
+def info():
+    """Get the information of a dingz device."""
+
+
+@info.command("config")
+@coro
+@click.option(
+    "--ip", prompt="IP address of the device", help="IP address of the device."
+)
+async def get_config(ip):
+    """Read the current configuration of a myStrom device."""
+    click.echo("Read configuration from %s" % ip)
+    async with Dingz(ip) as dingz:
+        await dingz.get_device_info()
+        click.echo(dingz.device_details)
+
+
+@main.group("front_led")
+def front_led():
+    """Handle the front LED of dingz."""
+
+
+@front_led.command("on")
+@coro
+@click.option(
+    "--ip", prompt="IP address of the device", help="IP address of the device."
+)
+async def set_on(ip):
+    """Turn the front LED on."""
+    async with Dingz(ip) as dingz:
+        await dingz.turn_on()
+
+
+@front_led.command("off")
+@coro
+@click.option(
+    "--ip", prompt="IP address of the device", help="IP address of the device."
+)
+async def set_off(ip):
+    """Turn the front LED off."""
+    async with Dingz(ip) as dingz:
+        await dingz.turn_off()
+
+
+@front_led.command("status")
+@coro
+@click.option(
+    "--ip", prompt="IP address of the device", help="IP address of the device."
+)
+async def get_status(ip):
+    """Get the status of the front LED off."""
+    async with Dingz(ip) as dingz:
+        click.echo(await dingz.enabled())
+
+
 if __name__ == "__main__":
     main()

dingz/constants.py

@@ -38,6 +38,7 @@
 # Configuration endpoints
 PIR_CONFIGURATION = "pir_config"
 BLIND_CONFIGURATION = "blind_config"
+DIMMER_CONFIGURATION = "dimmer_config"
 THERMOSTAT_CONFIGURATION = "thermostat_config"
 INPUT_CONFIGURATION = "input_config"
 

dingz/dimmer.py

@@ -0,0 +1,102 @@
+from yarl import URL
+
+from dingz import make_call
+from dingz.constants import DIMMER
+from dingz.registry import BaseRegistry, organize_by_absolute_index
+
+
+class Dimmer(object):
+    def __init__(self, absolute_index, dingz):
+        self.dingz = dingz
+        self.absolute_index = absolute_index
+        self.on = None
+        self.brightness_pct = None
+        self.enabled = None
+        self.dimmable = None
+        self.output = None
+        self.name = None
+        self.seen_state = False
+
+    async def toggle(self, brightness_pct=100):
+        """
+        Toggle light (based on internal state).
+        :param brightness_pct: brightness in percent, or None
+        :return:
+        """
+        action = "off" if self.on else "on"
+        await self.operate_light(action, brightness_pct)
+
+    async def turn_on(self, brightness_pct=100):
+        """ Turn light on.
+        :param brightness_pct: brightness in percent, or None.
+        """
+        await self.operate_light("on", brightness_pct)
+
+    async def turn_off(self):
+        """ Rurn light off."""
+        await self.operate_light("off")
+
+    VALID_OPERATIONS = ('on', 'off')
+
+    async def operate_light(self, action, brightness_pct=None):
+        """
+        Operate the light (turn it on or off).
+        :param action: 'on' or 'off'
+        :param brightness_pct: brightness in percent or None if not defined
+        :return:
+        """
+        if action not in Dimmer.VALID_OPERATIONS:
+            raise ValueError("invalid action %s, expected one of %s" %
+                             (repr(action), repr(Dimmer.VALID_OPERATIONS)))
+
+        if brightness_pct is not None and (brightness_pct > 100 or brightness_pct < 0):
+            raise ValueError("invalid brightness_pct %s, expected value between 0 and 100" %
+                             (repr(brightness_pct)))
+
+        url = URL(self.dingz.uri).join(URL("%s/%s/%s" % (DIMMER, self.index_relative, action)))
+        params = {}
+        if brightness_pct is not None:
+            params["value"] = str(brightness_pct)
+
+        await make_call(self.dingz, uri=url, method="POST", parameters=params)
+        self.on = action
+        if brightness_pct is not None:
+            self.brightness_pct = brightness_pct
+
+    def _consume_state(self, state_details):
+        """
+            Example for state_details:
+            {
+              "on": true, "output": 100, "ramp": 0, "readonly": false,
+              "index": { "relative": 0, "absolute": 2 }
+            }
+        :param state_details:
+        :return:
+        """
+        assert self.absolute_index == state_details['index']['absolute']
+        self.seen_state = True
+        self.index_relative = state_details['index']['relative']
+        self.on = state_details['on']
+        self.brightness_pct = state_details['output']
+
+    def _consume_config(self, config):
+        # "output": "halogen", "name": "Dimmable 3", "feedback": null, "feedback_intensity": 10
+        self.output = config['output']
+        self.enabled = config['output'] != 'not_connected'
+        self.dimmable = config['output'] != 'non_dimmable'
+        self.name = config['name']
+
+
+class DimmerRegistry(BaseRegistry[Dimmer]):
+    def __init__(self, dingz):
+        super().__init__(factory=lambda absolute_index: Dimmer(absolute_index, dingz))
+
+    def _consume_config(self, dimmer_configs):
+        for absolute_index, dimmer_config in enumerate(dimmer_configs):
+            dimmer = self._get_or_create(absolute_index)
+            dimmer._consume_config(dimmer_config)
+
+    def _consume_dimmer_state(self, dimmer_states):
+        for absolute_index, dimmer_state in organize_by_absolute_index(dimmer_states):
+            dimmer = self._get_or_create(absolute_index)
+            dimmer._consume_state(dimmer_state)