HAP-python 1.0.6__tar.gz → 1.0.7__tar.gz

{HAP-python-1.0.6 → HAP-python-1.0.7}/HAP_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: HAP-python
-Version: 1.0.6
+Version: 1.0.7
 Summary: HomeKit Accessory Protocol implementation in python3
 Home-page: https://github.com/ikalchev/HAP-python.git
 Author: Ivan Kalchev

{HAP-python-1.0.6 → HAP-python-1.0.7}/HAP_python.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ pyhap/accessories/FakeFan.py
 pyhap/accessories/Http.py
 pyhap/accessories/LightBulb.py
 pyhap/accessories/MotionSensor.py
+pyhap/accessories/SDS011.py
 pyhap/accessories/ShutdownSwitch.py
 pyhap/accessories/TSL2591.py
 pyhap/accessories/TemperatureSensor.py

{HAP-python-1.0.6 → HAP-python-1.0.7}/HAP_python.egg-info/requires.txt

@@ -3,3 +3,7 @@ tlslite-ng
 ed25519
 zeroconf
 curve25519-donna
+
+[dev]
+pytest
+tox

{HAP-python-1.0.6 → HAP-python-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: HAP-python
-Version: 1.0.6
+Version: 1.0.7
 Summary: HomeKit Accessory Protocol implementation in python3
 Home-page: https://github.com/ikalchev/HAP-python.git
 Author: Ivan Kalchev

HAP-python-1.0.7/pyhap/accessories/SDS011.py

@@ -0,0 +1,152 @@
+"""
+An Accessory wrapper for the SDS011 air particulate density sensor.
+
+The density sensor implementation can be found here:
+https://github.com/ikalchev/py-sds011
+Place the file under a package named sensors in your python path,
+or change the import alltogether.
+"""
+import time
+import logging
+
+from sensors.SDS011 import SDS011 as AirSensor
+from pyhap.accessory import Accessory, Category
+import pyhap.loader as loader
+
+logger = logging.getLogger(__name__)
+
+
+class SDS011(Accessory):
+    """Accessory wrapper for SDS011.
+    """
+
+    category = Category.SENSOR
+
+    SORTED_PM_QUALITY_MAP = ((200, 5), (150, 4), (100, 3), (50, 2), (0, 1))
+    """
+    Threshold-to-state tuples. These show the state for which the threshold is
+    lower boundry. Uses something like Air Quality Index (AQI).
+
+    The UI shows:
+        1 - Excellent
+        2 - Good
+        3 - Fair
+        4 - Inferior
+        5 - Poor
+    """
+
+    def __init__(self, serial_port, *args, sleep_duration_s=15*60, calib_duration_s=15,
+                 **kwargs):
+        """Initialise and start SDS011 on the given port.
+
+        @param serial_port: The SDS011 port, e.g. /dev/ttyUSB0.
+        @type serial_port: str
+
+        @param sleep_duration_s: The amount of time in seconds the sensor sleeps before
+            waking it up for reading. Defaults to 15 minutes.
+        @type sleep_duration_s: float
+
+        @param calib_duration_s: The amount of time in seconds to wait after the sensor
+            has been waken up before reading its data. Defaults to 15 seconds.
+        @type calib_duration_s: float
+        """
+        self.pm25_quality = None
+        self.pm25_density = None
+        self.pm10_quality = None
+        self.pm10_density = None
+        super(SDS011, self).__init__(*args, **kwargs)
+        self.sleep_duration_s = sleep_duration_s
+        self.calib_duration_s = calib_duration_s
+        self.serial_port = serial_port
+        self.sensor = AirSensor(serial_port)
+        self.sensor.sleep(sleep=False)
+
+    def _set_services(self):
+        """Add the AirQualitySensor services (one for PM2.5 and one for PM10).
+
+        Also adds and configures optional characteristics, such as Name,
+        AirParticulateSize, AirParticulateDensity.
+        """
+        super(SDS011, self)._set_services()
+        char_loader = loader.get_char_loader()
+
+        # PM2.5
+        air_quality_pm25 = loader.get_serv_loader().get("AirQualitySensor")
+        pm25_size = char_loader.get("AirParticulateSize")
+        pm25_size.set_value(0, should_notify=False)
+        self.pm25_density = char_loader.get("AirParticulateDensity")
+        pm25_name = char_loader.get("Name")
+        pm25_name.set_value("PM2.5", should_notify=False)
+        self.pm25_quality = air_quality_pm25.get_characteristic("AirQuality")
+        air_quality_pm25.add_opt_characteristic(pm25_name, pm25_size, self.pm25_density)
+
+        # PM10
+        air_quality_pm10 = loader.get_serv_loader().get("AirQualitySensor")
+        pm10_size = char_loader.get("AirParticulateSize")
+        pm10_size.set_value(1, should_notify=False)
+        self.pm10_density = char_loader.get("AirParticulateDensity")
+        pm10_name = char_loader.get("Name")
+        pm10_name.set_value("PM10", should_notify=False)
+        self.pm10_quality = air_quality_pm10.get_characteristic("AirQuality")
+        air_quality_pm10.add_opt_characteristic(pm10_name, pm10_size, self.pm10_density)
+
+        self.add_service(air_quality_pm25)
+        self.add_service(air_quality_pm10)
+
+    def __getstate__(self):
+        """Get the state, less the sensor.
+        """
+        state = super(SDS011, self).__getstate__()
+        state["sensor"] = None
+        return state
+
+    def __setstate__(self, state):
+        """Set the state of this Accessory and initialise the sensor
+            with the serial port in the state.
+        """
+        self.__dict__.update(state)
+        self.sensor = AirSensor(self.serial_port)
+
+    def get_quality_classification(self, pm, is_pm25=False):
+        """Get the air quality clasification based on the PM density.
+
+        Uses Air Quality Index (AQI), without averaging for an hour.
+
+        @see: SDS011.SORTED_PM_QUALITY_MAP
+
+        @rtype: int
+        """
+        assert pm >= 0
+        return next(state for threshold, state in self.SORTED_PM_QUALITY_MAP
+                    if threshold <= pm)
+
+    def run(self):
+        """Start updating the air quality readings.
+
+        Initially, we read from the sensor and update the values. Then we put
+        it in sleep mode and while the sentinel is not set:
+            - Sleep for `self.sleep_duration_s`.
+            - Wake up and wait `self.calib_duration_s` seconds.
+            - Get the sensor's readings and update.
+        """
+        pm25, pm10 = self.sensor.query()
+        self.pm25_density.set_value(pm25)
+        self.pm25_quality.set_value(
+            self.get_quality_classification(pm25, is_pm25=True))
+        self.pm10_density.set_value(pm10)
+        self.pm10_quality.set_value(
+            self.get_quality_classification(pm10, is_pm25=False))
+        self.sensor.sleep()
+        while not self.run_sentinel.wait(self.sleep_duration_s):
+            logger.debug("Waking up sensor.")
+            self.sensor.sleep(sleep=False)
+            time.sleep(self.calib_duration_s)
+            pm25, pm10 = self.sensor.query()
+            self.pm25_density.set_value(pm25)
+            self.pm25_quality.set_value(
+                self.get_quality_classification(pm25, is_pm25=True))
+            self.pm10_density.set_value(pm10)
+            self.pm10_quality.set_value(
+                self.get_quality_classification(pm10, is_pm25=False))
+            self.sensor.sleep()
+            logger.debug("Read cycle done. Sleeping.")

{HAP-python-1.0.6 → HAP-python-1.0.7}/pyhap/characteristic.py

@@ -1,5 +1,9 @@
-# All things for a HAP characteristic.
+"""
+All things for a HAP characteristic.
 
+A Characteristic is the smallest unit of the smart home, e.g.
+a temperature measuring or a device status.
+"""
 
 class HAP_FORMAT:
     BOOL = 'bool'
@@ -52,39 +56,59 @@ class CharacteristicError(Exception):
     pass
 
 
+_HAP_NUMERIC_FIELDS = {"maxValue", "minValue", "minStep", "unit"}
 """Fields that should be included in the HAP representation of the characteristic.
 
 That is, if they are present in the specification of a numeric-value characteristic.
 """
-_HAP_NUMERIC_FIELDS = {"maxValue", "minValue", "minStep", "unit"}
 
 
 class Characteristic(object):
+    """Represents a HAP characteristic, the smallest unit of the smart home.
+
+    A HAP characteristic is some measurement or state, like battery status or
+    the current temperature. Characteristics are contained in services.
+    Each charactaristic has a unique type UUID and a set of properties,
+    like format, min and max values, valid values and others.
+    """
 
     def __init__(self, display_name, type_id, properties, value=None, broker=None):
+        assert "Format" in properties and "Permissions" in properties
         self.display_name = display_name
         self.type_id = type_id
-        assert "Format" in properties and "Permissions" in properties
         self.properties = properties
-        self.allowed_values = self.properties.get("ValidValues")
+        self.has_valid_values = "ValidValues" in self.properties
         self.value = value or HAP_FORMAT.DEFAULT[properties["Format"]]
         self.broker = broker
         self.setter_callback = None
-        self.hap_value_template = self._create_value_HAP_template()
+        self.hap_template = self._create_hap_template()
+
+    def _create_hap_template(self):
+        """Create a HAP template for describing this Characteristic.
+
+        Contains properties that do not change or change rarely, e.g. the type.
+        """
+        template = dict()
+        if self.properties["Format"] in HAP_FORMAT.NUMERIC:
+            template = {k: self.properties[k]
+                        for k in self.properties.keys() & _HAP_NUMERIC_FIELDS}
+        return template
 
     def set_value(self, value, should_notify=True):
-        """Set the given value.
+        """Set the given raw value. It is checked if it is a valid value.
 
         @param value: The value to assign as this Characteristic's value.
         @type value: Depends on properties["Format"]
 
         @param should_notify: Whether a the change should be sent to subscribed clients.
+            The notification is called _after_ the setter callback.
         @type should_notify: bool
 
-        @raise ValueError: When the value being assigned is not one of the allowed values
+        @raise ValueError: When the value being assigned is not one of the valid values
             for this Characteristic.
         """
-        if self.allowed_values is not None and value not in self.allowed_values.values():
+        if (self.has_valid_values
+                and value not in self.properties["ValidValues"].values()):
             raise ValueError
         self.value = value
         if self.setter_callback is not None:
@@ -93,53 +117,49 @@ class Characteristic(object):
             self.notify()
 
     def get_value(self):
-        return self.value
-
-    def notify(self):
-        data = {
-          "type_id": self.type_id,
-          "value": self.value,
-        }
-        self.broker.publish(data, self)
+        """Get the raw value of this Characteristic.
 
-    def _create_value_HAP_template(self):
-        template = dict()
-        if self.properties["Format"] in HAP_FORMAT.NUMERIC:
-            template = {k: self.properties[k]
-                        for k in self.properties.keys() & _HAP_NUMERIC_FIELDS}
-        return template
-
-    def _value_to_HAP(self):
-        hap_rep = self.hap_value_template.copy()
+        @deprecated: Use self.value instead.
+        """
+        return self.value
 
+    def get_hap_value(self):
+        """Get the value of the characteristic, constrained with the HAP properties.
+        """
+        val = self.value
         if self.properties["Format"] == HAP_FORMAT.STRING:
-            val = self.value[:256]
-            if len(self.value) > 64:
-                hap_rep["maxLen"] = min(len(self.value), 256)
+            val = val[:256]
         elif self.properties["Format"] in HAP_FORMAT.NUMERIC:
-            val = self.value
-            if "maxValue" in hap_rep:
-                val = min(self.properties["maxValue"], self.value)
-            if "minValue" in hap_rep:
-                val = max(self.properties["minValue"], self.value)
-        else:
-            val = self.value
+            if "maxValue" in self.properties:
+                val = min(self.properties["maxValue"], val)
+            if "minValue" in self.properties:
+                val = max(self.properties["minValue"], val)
+        return val
 
-        if HAP_PERMISSIONS.READ in self.properties["Permissions"]:
-            hap_rep["value"] = val
+    def notify(self):
+        """Notify clients about a value change.
 
-        return hap_rep
+        @note: Non-blocking, i.e. does not wait for the update to be sent.
+        @note: Uses the `get_hap_value`, i.e. sends the HAP value.
+        @see: accessory_driver.publish
+        """
+        data = {
+            "type_id": self.type_id,
+            "value": self.get_hap_value(),
+        }
+        self.broker.publish(data, self)
 
-    def to_HAP(self, iid_manager=None):
+    def to_HAP(self, iid_manager):
         """Create a HAP representation of this Characteristic.
 
-        @param base_iid: The IID for this characteristic.
-        @type base_iid: int
+        @note: Uses the `get_hap_value`, i.e. sends the HAP value.
+
+        @param iid_manager: IID manager to query for this object's IID.
+        @type iid_manager: IIDManager
 
         @return: A HAP representation.
         @rtype: dict
         """
-        assert iid_manager is not None
         hap_rep = {
             "iid": iid_manager.get_iid(self),
             "type": str(self.type_id).upper(),
@@ -147,5 +167,14 @@ class Characteristic(object):
             "perms": self.properties["Permissions"],
             "format": self.properties["Format"],
         }
-        hap_rep.update(self._value_to_HAP())
+
+        value_info = self.hap_template.copy()
+        val = self.get_hap_value()
+        if self.properties["Format"] == HAP_FORMAT.STRING:
+            if len(val) > 64:
+                value_info["maxLen"] = min(len(val), 256)
+        if HAP_PERMISSIONS.READ in self.properties["Permissions"]:
+            value_info["value"] = val
+
+        hap_rep.update(value_info)
         return hap_rep

{HAP-python-1.0.6 → HAP-python-1.0.7}/setup.py

@@ -4,7 +4,7 @@ setup(
     name="HAP-python",
     description="HomeKit Accessory Protocol implementation in python3",
     author="Ivan Kalchev",
-    version="1.0.6",
+    version="1.0.7",
     url="https://github.com/ikalchev/HAP-python.git",
     classifiers=[
         "Development Status :: 5 - Production/Stable",
@@ -27,6 +27,12 @@ setup(
         "zeroconf",
         "curve25519-donna"
     ],
+    extras_require={
+        "dev": [
+            "pytest",
+            "tox",
+        ],
+    },
     package_data={
         "pyhap": ["resources/*"],
     }