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
Raw data
{
"_id": null,
"home_page": "https://github.com/pywemo/pywemo",
"name": "pywemo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0.0",
"maintainer_email": "",
"keywords": "wemo,api",
"author": "Eric Severance",
"author_email": "pywemo@esev.com",
"download_url": "https://files.pythonhosted.org/packages/0f/4f/5980c5c82452fca0164a1f94b29d671f20d1e8990d8ae4dd066250fde9ac/pywemo-1.4.0.tar.gz",
"platform": null,
"description": "pyWeMo |Build Badge| |PyPI Version Badge| |Coverage| |PyPI Downloads Badge| |Docs Badge| |Scorecard Badge| |Best Practices Badge| |SLSA 3 Badge|\n================================================================================================================================================\nPython 3 module to setup, discover and control WeMo devices.\n\nDependencies\n------------\npyWeMo depends on Python packages: requests, ifaddr, lxml, urllib3\n\nHow to use\n----------\n\n.. code-block:: python\n\n >>> import pywemo\n >>> devices = pywemo.discover_devices()\n >>> print(devices)\n [<WeMo Insight \"AC Insight\">]\n\n >>> devices[0].toggle()\n\nFor advanced usage, the ``device.explain()`` method will print all known actions that the device reports to PyWeMo.\n\nIf discovery doesn't work on your network\n-----------------------------------------\nAutomatic discovery may not work reliably on some networks.\nIn that case, you can use the device with an IP or hostname:\n\n.. code-block:: python\n\n >>> import pywemo\n >>> url = pywemo.setup_url_for_address(\"192.168.1.192\")\n >>> print(url)\n http://192.168.1.192:49153/setup.xml\n >>> device = pywemo.discovery.device_from_description(url)\n >>> print(device)\n <WeMo Maker \"Hi Fi Systemline Sensor\">\n\nPlease note that ``discovery.device_from_description`` requires a ``url`` with an IP address, rather than a hostname.\nThis is needed for the subscription update logic to work properly.\nIn addition, recent versions of the WeMo firmware may not accept connections from hostnames and will return a 500 error.\n\nThe ``setup_url_for_address`` function will lookup a hostname and provide a suitable ``url`` with an IP address.\n\nIf the WeMo device is not on your network, you can also connect to it directly.\nAfter 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``:\n\n.. code-block::\n\n $ arp -a\n _gateway (10.22.22.1) at [MAC ADDRESS REMOVED] [ether]\n \n.. code-block:: python\n\n >>> import pywemo\n >>> url = pywemo.setup_url_for_address(\"10.22.22.1\")\n >>> device = pywemo.discovery.device_from_description(url)\n >>> print(device)\n <WeMo Switch \"Wemo Mini\">\n >>> device.setup(ssid='MY SSID', password='MY NETWORK PASSWORD')\n ('1', 'success')\n\n\n\nTesting new products\n--------------------\nIf both methods above are not successful, then ``pywemo`` may not support your WeMo product yet.\nThis may be particularly true if it is a new WeMo product.\nTo test this, you can use a debug flag, ``pywemo.discover_devices(debug=True)`` or ``pywemo.discovery.device_from_description(url, debug=True)``.\nIf an ``UnsupportedDevice`` is found, then it is highly likely that the product can be added to ``pywemo``.\nThis ``UnsupportedDevice`` will allow manual interaction, but please open an issue to get first class support for the device.\n\nDevice Reset and Setup\n----------------------\nPyWeMo includes the ability to reset and setup devices, without using the Belkin app or needing to create a Belkin account.\nThis can be particularly useful if the intended use is fully local control, such as using Home Assistant.\n\nReset\n~~~~~\nReset can be performed with the ``reset`` method, which has 2 boolean input arguments, ``data`` and ``wifi``.\nWeMo devices contain a hardware reset procedure as well, so use of ``pywemo`` is for convenience or if physical access is not available.\nThis ``reset`` method may not work on all devices.\n\n======================================= ================= =======================\nMethod in ``pywemo`` Clears Name in WeMo App\n======================================= ================= =======================\n``device.reset(data=True, wifi=False)`` name, icon, rules Clear Personalized Info\n``device.reset(data=False, wifi=True)`` wifi information Change Wi-Fi\n``device.reset(data=True, wifi=True)`` everything Factory Restore\n======================================= ================= =======================\n\nSetup\n~~~~~\n\nDevice setup is through the ``setup`` method, which has two required arguments: ``ssid`` and ``password``.\nThe user must first connect to the devices locally broadcast access point, which typically starts with \"WeMo.\", and then discover the device there.\nOnce done, pass the desired SSID and password (WPA2/AES encryption only) to the ``setup`` method to connect it to your wifi network.\n\n``device.setup(ssid='wifi_name', password='special_secret')``\n\nA few important notes:\n\n- Not all devices are currently supported for setup.\n- 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.\n- If connecting to an open network, the password argument is ignored and you can provide anything, e.g. ``password=None``.\n- If connecting to a WPA2/AES-encrypted network, OpenSSL is used to encrypt the password by the ``pywemo`` library.\n It must be installed and available on your ``PATH`` via calling ``openssl`` from a terminal or command prompt.\n\nFirmware Warning\n----------------\nStarting in May of 2020, Belkin started requiring users to create an account and login to the app (Android app version 1.25).\nIn 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.\nAll of the commands that go through the cloud are encrypted and cannot be easily inspected.\nThis raises the possibility that Belkin could, in the future, update WeMo device firmware and make breaking API changes that can no longer be deciphered.\nIf this happens, ``pywemo`` may no longer function on that device.\nThus it would be prudent to upgrade firmware cautiously and preferably only after confirming that breaking API changes have not been introduced.\n\nDeveloping\n----------\nSetup and builds are fully automated.\nYou can run the build pipeline locally via:\n\n.. code-block::\n\n # setup, install, format, lint, test and build:\n ./scripts/build.sh\n\nNote that this will install a git ``pre-commit`` hook.\nFor this hook to work correctly, ``poetry`` needs to be globally accessible on your ``PATH`` or the local virtual environment must be activated.\nThis virtual environment can be activated with:\n\n.. code-block::\n\n . .venv/bin/activate\n\nHistory\n-------\nThis started as a stripped down version of `ouimeaux <https://github.com/iancmcc/ouimeaux>`_, copyright Ian McCracken, but has since taken its own path.\n\nLicense\n-------\nAll 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.\nThe rest of pyWeMo is released under the MIT license. See the top-level LICENSE file for more details.\n\n\n.. |Build Badge| image:: https://github.com/pywemo/pywemo/workflows/Build/badge.svg\n :target: https://github.com/pywemo/pywemo/actions?query=workflow%3ABuild\n :alt: GitHub build status\n.. |PyPI Version Badge| image:: https://img.shields.io/pypi/v/pywemo\n :target: https://pypi.org/project/pywemo/\n :alt: Latest PyPI version\n.. |Coverage| image:: https://coveralls.io/repos/github/pywemo/pywemo/badge.svg?branch=main\n :target: https://coveralls.io/github/pywemo/pywemo?branch=main\n :alt: Coveralls coverage\n.. |PyPI Downloads Badge| image:: https://img.shields.io/pypi/dm/pywemo\n :target: https://pypi.org/project/pywemo/\n :alt: Number of PyPI downloads\n.. |Docs Badge| image:: https://github.com/pywemo/pywemo/actions/workflows/docs.yml/badge.svg\n :target: https://pywemo.github.io/pywemo/\n :alt: API Documentation\n.. |Scorecard Badge| image:: https://api.securityscorecards.dev/projects/github.com/pywemo/pywemo/badge\n :target: https://securityscorecards.dev/viewer/?uri=github.com/pywemo/pywemo\n :alt: OpenSSF Scorecard\n.. |Best Practices Badge| image:: https://bestpractices.coreinfrastructure.org/projects/7467/badge\n :target: https://bestpractices.coreinfrastructure.org/projects/7467\n :alt: OpenSSF Best Practices\n.. |SLSA 3 Badge| image:: https://slsa.dev/images/gh-badge-level3.svg\n :target: https://github.com/pywemo/pywemo/releases/latest#user-content-SLSA\n :alt: SLSA level 3\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lightweight Python module to discover and control WeMo devices",
"version": "1.4.0",
"project_urls": {
"Homepage": "https://github.com/pywemo/pywemo",
"Repository": "https://github.com/pywemo/pywemo"
},
"split_keywords": [
"wemo",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3ccd197038700701b83631aefa7c5ff3630044e8c4c6387fdd19aac91215716b",
"md5": "f05bb7743a93fce7f80cd576ada82578",
"sha256": "7259dd26b5208804737af25cad626909ddda35ab561ccecca866459fc435822e"
},
"downloads": -1,
"filename": "pywemo-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f05bb7743a93fce7f80cd576ada82578",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0.0",
"size": 101127,
"upload_time": "2024-01-09T04:38:46",
"upload_time_iso_8601": "2024-01-09T04:38:46.437107Z",
"url": "https://files.pythonhosted.org/packages/3c/cd/197038700701b83631aefa7c5ff3630044e8c4c6387fdd19aac91215716b/pywemo-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0f4f5980c5c82452fca0164a1f94b29d671f20d1e8990d8ae4dd066250fde9ac",
"md5": "d8d639f10a9fd48bec1164980c8685bc",
"sha256": "38ffae2568d0beb8853967d68f9d9af2da6c98c89b0f014f9359dac504549825"
},
"downloads": -1,
"filename": "pywemo-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "d8d639f10a9fd48bec1164980c8685bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0.0",
"size": 89014,
"upload_time": "2024-01-09T04:38:48",
"upload_time_iso_8601": "2024-01-09T04:38:48.929787Z",
"url": "https://files.pythonhosted.org/packages/0f/4f/5980c5c82452fca0164a1f94b29d671f20d1e8990d8ae4dd066250fde9ac/pywemo-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-09 04:38:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pywemo",
"github_project": "pywemo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pywemo"
}
JSON
