pywemo 1.4.0__py3-none-any.whl

pywemo/util.py

@@ -0,0 +1,139 @@
+"""Miscellaneous utility functions."""
+from __future__ import annotations
+
+import os
+import socket
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+import ifaddr
+
+
+def interface_addresses() -> list[str]:
+    """
+    Return local address for broadcast/multicast.
+
+    Return local address of any network associated with a local interface
+    that has broadcast (and probably multicast) capability.
+    """
+    addresses = []
+
+    for iface in ifaddr.get_adapters():
+        for addr in iface.ips:
+            if not (addr.is_IPv4 and isinstance(addr.ip, str)):
+                continue
+            if addr.ip == "127.0.0.1":
+                continue
+
+            addresses.append(addr.ip)
+
+    return addresses
+
+
+def get_callback_address(host: str, port: int) -> str | None:
+    """Return IP address & port used by devices to send event notifications."""
+    pywemo_callback_address = os.getenv("PYWEMO_CALLBACK_ADDRESS")
+    if pywemo_callback_address is not None:
+        return pywemo_callback_address
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.connect((host, 9))
+        return f"{sock.getsockname()[0]}:{port}"
+    except OSError:
+        return None
+    finally:
+        del sock
+
+
+def signal_strength_to_dbm(value: dict[str, str] | str) -> int:
+    """Convert signal strength percentage into a RSSI dBm value.
+
+    WeMo devices use the algorithm described here to convert a RSSI dBm value
+    into a signal strength percentage:
+    https://community.cambiumnetworks.com/t/cnmaestro-wifi-analyzer-tool/63471
+
+    signal_strength_to_dbm is meant to be used with the
+    basicevent.GetSignalStrength UPnP Action.
+
+    signal_strength = device.basicevent.GetSignalStrength()
+    signal_strength_to_dbm(signal_strength)
+      or
+    signal_strength_to_dbm(signal_strength["SignalStrength"])
+    """
+    if isinstance(value, dict):
+        percent_str = value["SignalStrength"]
+    else:
+        percent_str = value
+
+    percent = round(float(percent_str))
+    if percent >= 100:
+        return -50
+    if percent >= 24:
+        return round((percent - 24) * 10 / 26 - 80)
+    if percent > 0:
+        return round(percent * 10 / 26 - 90)
+    return -90
+
+
+@dataclass
+class MetaInfo:
+    """Parsed output of the metainfo.GetMetaInfo() Action."""
+
+    mac: str
+    serial_number: str
+    device_sku: str
+    firmware_version: str
+    access_point_ssid: str
+    model_name: str
+
+    @classmethod
+    def from_meta_info(cls, value: dict[str, str] | str) -> MetaInfo:
+        """Initialize from metainfo.GetMetaInfo() output."""
+        info_str = value["MetaInfo"] if isinstance(value, dict) else value
+        if not info_str.isprintable():
+            raise ValueError("Invalid characters found in MetaInfo")
+        values = info_str.split("|")
+        if len(values) < 6:
+            raise ValueError(f"Could not unpack MetaInfo: {info_str}")
+        return cls(*values[:6])
+
+
+@dataclass
+class ExtMetaInfo:  # pylint: disable=too-many-instance-attributes
+    """Parsed output of the metainfo.GetExtMetaInfo() Action."""
+
+    current_client_state: int
+    ice_running: int
+    nat_initialized: int
+    last_auth_value: int
+    uptime: timedelta
+    firmware_update_state: int
+    utc_time: datetime
+    home_id: str
+    remote_access_enabled: bool
+    model_name: str
+
+    @classmethod
+    def from_ext_meta_info(cls, value: dict[str, str] | str) -> ExtMetaInfo:
+        """Initialize from metainfo.GetExtMetaInfo() output."""
+        info_str = value["ExtMetaInfo"] if isinstance(value, dict) else value
+        if not info_str.isprintable():
+            raise ValueError("Invalid characters found in ExtMetaInfo")
+        values = info_str.split("|")
+        if not len(values) > 9:
+            raise ValueError(f"Could not unpack ExtMetaInfo: {info_str}")
+
+        hours, minutes, seconds = (int(v) for v in values[4].split(":"))
+        return cls(
+            current_client_state=int(values[0]),
+            ice_running=int(values[1]),
+            nat_initialized=int(values[2]),
+            last_auth_value=int(values[3]),
+            uptime=timedelta(hours=hours, minutes=minutes, seconds=seconds),
+            firmware_update_state=int(values[5]),
+            utc_time=datetime.utcfromtimestamp(int(values[6])),
+            home_id=values[7],
+            remote_access_enabled=bool(int(values[8])),
+            model_name=values[9],
+        )

pywemo-1.4.0.dist-info/LICENSE

@@ -0,0 +1,54 @@
+Copyright 2014 Paulus Schoutsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+------------------------------------------------------------------------------
+
+The pyWeMo project also contains files that were originally from the
+ouimeaux project. https://github.com/iancmcc/ouimeaux/
+The following license applies to all content within the pywemo/ouimeaux_device
+directory:
+
+Copyright (c) 2014, Ian McCracken
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of ouimeaux nor the names of its contributors may be used to
+  endorse or promote products derived from this software without specific prior
+  written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pywemo-1.4.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.1
+Name: pywemo
+Version: 1.4.0
+Summary: Lightweight Python module to discover and control WeMo devices
+Home-page: https://github.com/pywemo/pywemo
+License: MIT
+Keywords: wemo,api
+Author: Eric Severance
+Author-email: pywemo@esev.com
+Requires-Python: >=3.8.1,<4.0.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: ifaddr (>=0.1.0)
+Requires-Dist: lxml (>=4.6)
+Requires-Dist: requests (>=2.0)
+Requires-Dist: urllib3 (>=1.26.0)
+Project-URL: Repository, https://github.com/pywemo/pywemo
+Description-Content-Type: text/x-rst
+
+pyWeMo |Build Badge| |PyPI Version Badge| |Coverage| |PyPI Downloads Badge| |Docs Badge| |Scorecard Badge| |Best Practices Badge| |SLSA 3 Badge|
+================================================================================================================================================
+Python 3 module to setup, discover and control WeMo devices.
+
+Dependencies
+------------
+pyWeMo depends on Python packages: requests, ifaddr, lxml, urllib3
+
+How to use
+----------
+
+.. code-block:: python
+
+    >>> import pywemo
+    >>> devices = pywemo.discover_devices()
+    >>> print(devices)
+    [<WeMo Insight "AC Insight">]
+
+    >>> devices[0].toggle()
+
+For advanced usage, the ``device.explain()`` method will print all known actions that the device reports to PyWeMo.
+
+If discovery doesn't work on your network
+-----------------------------------------
+Automatic discovery may not work reliably on some networks.
+In that case, you can use the device with an IP or hostname:
+
+.. code-block:: python
+
+    >>> import pywemo
+    >>> url = pywemo.setup_url_for_address("192.168.1.192")
+    >>> print(url)
+    http://192.168.1.192:49153/setup.xml
+    >>> device = pywemo.discovery.device_from_description(url)
+    >>> print(device)
+    <WeMo Maker "Hi Fi Systemline Sensor">
+
+Please note that ``discovery.device_from_description`` requires a ``url`` with an IP address, rather than a hostname.
+This is needed for the subscription update logic to work properly.
+In addition, recent versions of the WeMo firmware may not accept connections from hostnames and will return a 500 error.
+
+The ``setup_url_for_address`` function will lookup a hostname and provide a suitable ``url`` with an IP address.
+
+If the WeMo device is not on your network, you can also connect to it directly.
+After connecting, if the ``pywemo.discover_devices()`` doesn't work, you can get the IP Address by running an ``arp -a`` and use that in ``pywemo.setup_url_for_address``:
+
+.. code-block::
+
+    $ arp -a
+    _gateway (10.22.22.1) at [MAC ADDRESS REMOVED] [ether]
+    
+.. code-block:: python
+
+    >>> import pywemo
+    >>> url = pywemo.setup_url_for_address("10.22.22.1")
+    >>> device = pywemo.discovery.device_from_description(url)
+    >>> print(device)
+    <WeMo Switch "Wemo Mini">
+    >>> device.setup(ssid='MY SSID', password='MY NETWORK PASSWORD')
+    ('1', 'success')
+
+
+
+Testing new products
+--------------------
+If both methods above are not successful, then ``pywemo`` may not support your WeMo product yet.
+This may be particularly true if it is a new WeMo product.
+To test this, you can use a debug flag, ``pywemo.discover_devices(debug=True)`` or ``pywemo.discovery.device_from_description(url, debug=True)``.
+If an ``UnsupportedDevice`` is found, then it is highly likely that the product can be added to ``pywemo``.
+This ``UnsupportedDevice`` will allow manual interaction, but please open an issue to get first class support for the device.
+
+Device Reset and Setup
+----------------------
+PyWeMo includes the ability to reset and setup devices, without using the Belkin app or needing to create a Belkin account.
+This can be particularly useful if the intended use is fully local control, such as using Home Assistant.
+
+Reset
+~~~~~
+Reset can be performed with the ``reset`` method, which has 2 boolean input arguments, ``data`` and ``wifi``.
+WeMo devices contain a hardware reset procedure as well, so use of ``pywemo`` is for convenience or if physical access is not available.
+This ``reset`` method may not work on all devices.
+
+=======================================  =================  =======================
+Method in ``pywemo``                     Clears             Name in WeMo App
+=======================================  =================  =======================
+``device.reset(data=True, wifi=False)``  name, icon, rules  Clear Personalized Info
+``device.reset(data=False, wifi=True)``  wifi information   Change Wi-Fi
+``device.reset(data=True, wifi=True)``   everything         Factory Restore
+=======================================  =================  =======================
+
+Setup
+~~~~~
+
+Device setup is through the ``setup`` method, which has two required arguments: ``ssid`` and ``password``.
+The user must first connect to the devices locally broadcast access point, which typically starts with "WeMo.", and then discover the device there.
+Once done, pass the desired SSID and password (WPA2/AES encryption only) to the ``setup`` method to connect it to your wifi network.
+
+``device.setup(ssid='wifi_name', password='special_secret')``
+
+A few important notes:
+
+- Not all devices are currently supported for setup.
+- For a WeMo without internet access, see `this guide <https://github.com/pywemo/pywemo/wiki/WeMo-Cloud#disconnecting-from-the-cloud>`_ to stop any blinking lights.
+- If connecting to an open network, the password argument is ignored and you can provide anything, e.g. ``password=None``.
+- If connecting to a WPA2/AES-encrypted network, OpenSSL is used to encrypt the password by the ``pywemo`` library.
+  It must be installed and available on your ``PATH`` via calling ``openssl`` from a terminal or command prompt.
+
+Firmware Warning
+----------------
+Starting in May of 2020, Belkin started requiring users to create an account and login to the app (Android app version 1.25).
+In addition to the account, most of the app functionality now requires a connection to the cloud (internet access), even for simple actions such as toggling a switch.
+All of the commands that go through the cloud are encrypted and cannot be easily inspected.
+This raises the possibility that Belkin could, in the future, update WeMo device firmware and make breaking API changes that can no longer be deciphered.
+If this happens, ``pywemo`` may no longer function on that device.
+Thus it would be prudent to upgrade firmware cautiously and preferably only after confirming that breaking API changes have not been introduced.
+
+Developing
+----------
+Setup and builds are fully automated.
+You can run the build pipeline locally via:
+
+.. code-block::
+
+    # setup, install, format, lint, test and build:
+    ./scripts/build.sh
+
+Note that this will install a git ``pre-commit`` hook.
+For this hook to work correctly, ``poetry`` needs to be globally accessible on your ``PATH`` or the local virtual environment must be activated.
+This virtual environment can be activated with:
+
+.. code-block::
+
+    . .venv/bin/activate
+
+History
+-------
+This started as a stripped down version of `ouimeaux <https://github.com/iancmcc/ouimeaux>`_, copyright Ian McCracken, but has since taken its own path.
+
+License
+-------
+All contents of the pywemo/ouimeaux_device directory are licensed under a BSD 3-Clause license. The full text of that license is maintained within the pywemo/ouimeaux_device/LICENSE file.
+The rest of pyWeMo is released under the MIT license. See the top-level LICENSE file for more details.
+
+
+.. |Build Badge| image:: https://github.com/pywemo/pywemo/workflows/Build/badge.svg
+    :target: https://github.com/pywemo/pywemo/actions?query=workflow%3ABuild
+    :alt: GitHub build status
+.. |PyPI Version Badge| image:: https://img.shields.io/pypi/v/pywemo
+    :target: https://pypi.org/project/pywemo/
+    :alt: Latest PyPI version
+.. |Coverage| image:: https://coveralls.io/repos/github/pywemo/pywemo/badge.svg?branch=main
+    :target: https://coveralls.io/github/pywemo/pywemo?branch=main
+    :alt: Coveralls coverage
+.. |PyPI Downloads Badge| image:: https://img.shields.io/pypi/dm/pywemo
+    :target: https://pypi.org/project/pywemo/
+    :alt: Number of PyPI downloads
+.. |Docs Badge| image:: https://github.com/pywemo/pywemo/actions/workflows/docs.yml/badge.svg
+    :target: https://pywemo.github.io/pywemo/
+    :alt: API Documentation
+.. |Scorecard Badge| image:: https://api.securityscorecards.dev/projects/github.com/pywemo/pywemo/badge
+    :target: https://securityscorecards.dev/viewer/?uri=github.com/pywemo/pywemo
+    :alt: OpenSSF Scorecard
+.. |Best Practices Badge| image:: https://bestpractices.coreinfrastructure.org/projects/7467/badge
+    :target: https://bestpractices.coreinfrastructure.org/projects/7467
+    :alt: OpenSSF Best Practices
+.. |SLSA 3 Badge| image:: https://slsa.dev/images/gh-badge-level3.svg
+    :target: https://github.com/pywemo/pywemo/releases/latest#user-content-SLSA
+    :alt: SLSA level 3
+

pywemo-1.4.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+pywemo/README.md,sha256=R8Wukt5JbfA-mORbvI_gyk1INAQ556XTLvOSeu3P3e4,2889
+pywemo/__init__.py,sha256=EF4qCw0GNmNsWV6MZNr1eeArx6OvvDy-akB_dRqsuZg,1254
+pywemo/color.py,sha256=eGQd0MODHV_tBCDW9BUDQ_MLvmR0k0MkhIj_s38bfuE,2762
+pywemo/discovery.py,sha256=1yI-QRrOQL0_-h-UoNv9huZ6obcMMCBZOp_NJcV2rNk,6806
+pywemo/exceptions.py,sha256=WY5iIf-JRfu9TzOqKa7vsGspqakY3UryYn6ugLlEDvQ,2759
+pywemo/ouimeaux_device/LICENSE,sha256=Ff3shOWJ0P7xPBq6BsFxkORe6BP2iaWj5ydiE0s7B6k,1468
+pywemo/ouimeaux_device/__init__.py,sha256=75NxqCVOX_0iRTGllGo-J7xfHhgP8EPdIjzjDtQniXg,26370
+pywemo/ouimeaux_device/api/__init__.py,sha256=TYTMhVymF43pAOH1M1oHZ-7El7G6tTAGBIMrfEGeYOs,23
+pywemo/ouimeaux_device/api/attributes.py,sha256=SxfqNOlCOMP4DrlrK5o0T5NApDq_p-Y5h3m99F2EcZU,4843
+pywemo/ouimeaux_device/api/db_orm.py,sha256=ODLZZZ6Nfz2OWrKcCVucDml8eVQy-uwHV-P6k4VBW2U,6733
+pywemo/ouimeaux_device/api/long_press.py,sha256=GM6Eg8lb7rVTxGgdkV2VvrPf9BK7KIvHthILeyrOvTc,6059
+pywemo/ouimeaux_device/api/rules_db.py,sha256=1CugXrlg6zHN07ebhK5e68DYUTPxRStf_EfNGpoY_JE,14976
+pywemo/ouimeaux_device/api/service.py,sha256=qeNThZXVPEuRIM9Xou8aVk34Up8F1ei1O6E_X8_FCMo,12705
+pywemo/ouimeaux_device/api/wemo_services.py,sha256=z5wbX10ok2ltdpucJr0H6Cy9CoIoCb3vfbkeMdWt8qc,912
+pywemo/ouimeaux_device/api/wemo_services.pyi,sha256=Amybn9pfO-EJUge6gYPeADw-_iQYmqfP_fSB1mlkpQk,6838
+pywemo/ouimeaux_device/api/xsd/__init__.py,sha256=xv1RKXPNighlx3L88tkedXQfSDYI5ifA8zPmSiXdiyY,60
+pywemo/ouimeaux_device/api/xsd/device.py,sha256=pQiE_wLh0-25mG97tx3azb4lb_UXX8zKH4spXD1r59k,126897
+pywemo/ouimeaux_device/api/xsd/device.xsd,sha256=D4yqFUD-kDXUXWz3Y2No_XTiNRY2TbxecjV5wEbh5Gw,4305
+pywemo/ouimeaux_device/api/xsd/service.py,sha256=RBh2o958Y8qIx89CdbG0z0P7-5IWF_k-9ihhHIGOQco,122589
+pywemo/ouimeaux_device/api/xsd/service.xsd,sha256=Hqzc1ovP7q8SbW-IDN7ZaLQCN_vP50Qrqx7PDAbDAyQ,3526
+pywemo/ouimeaux_device/api/xsd_types.py,sha256=pUzyktm26SK6nnwAJYVINkYx4tLFE0MDK4lOaLIOZ5A,7275
+pywemo/ouimeaux_device/bridge.py,sha256=yI_JCCqyO6Ye_Ol3wDtBuvVUuX82V4c1StnFEsqzMd8,18975
+pywemo/ouimeaux_device/coffeemaker.py,sha256=B80yKYZCJKr9tC-Zf7Bc4YlHYj74jAq2GLANsL_TqQo,3345
+pywemo/ouimeaux_device/crockpot.py,sha256=PXPvFRfwNXyvkhkQJl3Hcdf1VEpazJ2DGOrfa5WGKpQ,5035
+pywemo/ouimeaux_device/dimmer.py,sha256=k_GJIcMygOZ2VjzSlJslYh3T0X3BxyakcyNecvi4gA8,2398
+pywemo/ouimeaux_device/humidifier.py,sha256=dnqwTOlWun1crsBR8E5H-oMF0851qz2K_o3cH6qVDhs,7162
+pywemo/ouimeaux_device/insight.py,sha256=EVcFWZN2UVNj4vA4xrDk7FdbVvnELSdKg9OJ200BT4w,6125
+pywemo/ouimeaux_device/lightswitch.py,sha256=_lbaLmxPIKhWLmjEhZ6NBSzFHDvg9sW0Z3Dn4PiO5mw,328
+pywemo/ouimeaux_device/maker.py,sha256=azcPLnFBJRDgjAEV6oVVdaOGGg0JMLaPztuGtTafnNw,1645
+pywemo/ouimeaux_device/motion.py,sha256=ZepSPKKZxo8HPZ391z7SHIxmZXdV5vrEJBfac3z1NHg,141
+pywemo/ouimeaux_device/outdoor_plug.py,sha256=M8AmM_eaU43JaIPF1F-NGoY-zaE99JQucNs_BOCC-DU,157
+pywemo/ouimeaux_device/switch.py,sha256=VMLyoXRwOIFbjnwR2GcFRzwkzDNqVawu5z3f_9M7cB8,1023
+pywemo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pywemo/ssdp.py,sha256=koDFc8INDuWzPNWftnfCOpSUz4t3Q9giB6GeSbMOZVw,12531
+pywemo/subscribe.py,sha256=j_zbbgnWZZRPSE5fmpsX1sIPGbCxzGQmNIiI1GZ_dvA,29780
+pywemo/util.py,sha256=LHOD-MSIkl78jElP5uFnZVJ9dBovhYQ_2Gx2JRlbgxs,4417
+pywemo-1.4.0.dist-info/LICENSE,sha256=uEhWS0rrkJ-nVSDY4avaxJrszZOBwR_hIOiBVkd4Sk8,2831
+pywemo-1.4.0.dist-info/METADATA,sha256=CK0Q67O21Lr6C_TAJll9tJBW6yv0CV3TC2cqCjKfksc,9130
+pywemo-1.4.0.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+pywemo-1.4.0.dist-info/RECORD,,

pywemo-1.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.8.1
+Root-Is-Purelib: true
+Tag: py3-none-any