# Python Wyze SDK
A modern Python client for controlling Wyze devices.
[![PyPI version][pypi-image]][pypi-url]
[![Python Version][python-version]][pypi-url]
[![Read the Docs][support-docs]][docs-url]
Whether you're building a custom app, or integrating into a third-party service like Home Assistant, Wyze Developer Kit for Python allows you to leverage the flexibility of Python to get your project up and running as quickly as possible.
The **Python Wyze SDK** allows interaction with:
- `wyze_sdk.client.bulbs`: for controlling Wyze Bulb, Wyze Bulb Color, Wyze Bulb White, and Wyze Light Strip
- `wyze_sdk.client.entry_sensors`: for interacting with Wyze Entry Sensor
- `wyze_sdk.client.cameras`: for interacting with Wyze Cameras
- `wyze_sdk.client.events`: for managing Wyze alarm events
- `wyze_sdk.client.locks`: for interacting with Wyze Lock and Wyze Lock Keypad
- `wyze_sdk.client.motion_sensors`: for interacting with Wyze Motion Sensor
- `wyze_sdk.client.plugs`: for controlling Wyze Plug and Wyze Plug Outdoor
- `wyze_sdk.client.scales`: for controlling Wyze Scale
- `wyze_sdk.client.switches`: for controlling Wyze Switch
- `wyze_sdk.client.thermostats`: for controlling Wyze Thermostat and Wyze Room Sensor
- `wyze_sdk.client.vacuums`: for controlling Wyze Robot Vacuum
**Disclaimer: This repository is for non-destructive use only. WyzeLabs is a wonderful company providing excellent devices at a reasonable price. I ask that you do no harm and be civilized.**
**As this repository is entirely reverse-engineered, it may break at any time. If it does, I will fix it to the best of my ability, but feel free to file a GitHub issue or patch yourself and submit a pull request.**
### Requirements
---
This library requires Python 3.8 and above. If you're unsure how to check what version of Python you're on, you can check it using the following:
> **Note:** You may need to use `python3` before your commands to ensure you use the correct Python path. e.g. `python3 --version`
```bash
python --version
-- or --
python3 --version
```
### Installation
We recommend using [PyPI][pypi] to install the Wyze Developer Kit for Python.
```bash
$ pip install wyze-sdk
```
### Basic Usage of the Web Client
---
Wyze does not provide a Web API that gives you the ability to build applications that interact with Wyze devices. This Development Kit is a reverse-engineered, module-based wrapper that makes interaction with that API possible. We have a few basic examples here with some of the more common uses but you are encouraged to [explore the full range of methods](https://wyze-sdk.readthedocs.io/en/latest/wyze_sdk.api.devices.html) available to you.
#### Authenticating
When performing user "authentication" with an email and password in the Wyze app, the credentials are exchanged for an access token and a refrsh token. These are long strings of the form `lvtx.XXXX`. When using this library, be aware that there are two method for handling authentiation:
##### Obtaining the Token and Storing it for Later Use (Preferred)
It is preferred that users first create an empty `Client` object and use the `login()` method to perform the token exchange.
```python
import os
from wyze_sdk import Client
response = Client().login(email=os.environ['WYZE_EMAIL'], password=os.environ['WYZE_PASSWORD'])
print(f"access token: {response['access_token']}")
print(f"refresh token: {response['refresh_token']}")
```
The returned values can be stored on disk or as environment variables for use in subsequent calls.
```python
import os
from wyze_sdk import Client
client = Client(token=os.environ['WYZE_ACCESS_TOKEN'])
...
```
##### (Deprecated) Automatically Authenticate Every New Client
This method has been deprecated due to issues with authentication rate limiting. While it is still a perfectly usable approach for testing or performing infrequent client actions, it **is not recommended** if you are scripting with this client library.
```python
import os
from wyze_sdk import Client
from wyze_sdk.errors import WyzeApiError
client = Client(email=os.environ['WYZE_EMAIL'], password=os.environ['WYZE_PASSWORD'])
...
```
##### Wyze API Key/ID Support
Visit the Wyze developer API portal to generate an API ID/KEY: https://developer-api-console.wyze.com/#/apikey/view
```python
import os
from wyze_sdk import Client
response = Client().login(
email=os.environ['WYZE_EMAIL'],
password=os.environ['WYZE_PASSWORD'],
key_id=os.environ['WYZE_KEY_ID'],
api_key=os.environ['WYZE_API_KEY']
)
...
```
##### Multi-Factor Authentication (2FA) Support
If your Wyze account has multi-factor authentication (2FA) enabled, you may be prompted for your 2FA code when authenticating via either supported method described above. If you wish to automate the MFA interaction, both the `Client` constructor and the `login()` method accept `totp_key` as input. If the TOTP key is provided, the MFA prompt should not appear. Your TOTP key can be obtained during the Wyze 2FA setup process and is the same code that you would typically input into an authenticator app during 2FA setup.
```python
import os
from wyze_sdk import Client
response = Client().login(
email=os.environ['WYZE_EMAIL'],
password=os.environ['WYZE_PASSWORD'],
totp_key=os.environ['WYZE_TOTP_KEY']
)
OR
client = Client(
email=os.environ['WYZE_EMAIL'],
password=os.environ['WYZE_PASSWORD'],
totp_key=os.environ['WYZE_TOTP_KEY']
)
...
```
**Note: This does not work with SMS or email-based MFA.**
#### Listing devices in your Wyze account
One of the most common use-cases is querying device state from Wyze. If you want to access devices you own, or devices shared to you, this method will do both.
```python
import os
from wyze_sdk import Client
from wyze_sdk.errors import WyzeApiError
client = Client(token=os.environ['WYZE_ACCESS_TOKEN'])
try:
response = client.devices_list()
for device in client.devices_list():
print(f"mac: {device.mac}")
print(f"nickname: {device.nickname}")
print(f"is_online: {device.is_online}")
print(f"product model: {device.product.model}")
except WyzeApiError as e:
# You will get a WyzeApiError if the request failed
print(f"Got an error: {e}")
```
#### Turning off a switch
Some devices - like cameras, bulbs, and plugs - can be switched on and off. This is done with a simple command and even supports delayed actions via timers.
```python
import os
from datetime import timedelta
from wyze_sdk import Client
from wyze_sdk.errors import WyzeApiError
client = Client(token=os.environ['WYZE_ACCESS_TOKEN'])
try:
plug = client.plugs.info(device_mac='ABCDEF1234567890')
print(f"power: {plug.is_on}")
print(f"online: {plug.is_online}")
if plug.is_on:
client.plugs.turn_off(device_mac=plug.mac, device_model=plug.product.model, after=timedelta(hours=3))
else:
client.plugs.turn_on(device_mac=plug.mac, device_model=plug.product.model)
plug = client.plugs.info(device_mac=plug.mac)
assert plug.is_on is True
except WyzeApiError as e:
# You will get a WyzeApiError if the request failed
print(f"Got an error: {e}")
```
#### Setting device properties
Every Wyze device has myriad properties and attributes that can be set in a common, intuitive way.
```python
import os
from wyze_sdk import Client
from wyze_sdk.errors import WyzeApiError
client = Client(token=os.environ['WYZE_ACCESS_TOKEN'])
try:
bulb = client.bulbs.info(device_mac='ABCDEF1234567890')
print(f"power: {bulb.is_on}")
print(f"online: {bulb.is_online}")
print(f"brightness: {bulb.brightness}")
print(f"temp: {bulb.color_temp}")
print(f"color: {bulb.color}")
client.bulbs.set_brightness(device_mac=bulb.mac, device_model=bulb.product.model, brightness=100)
client.bulbs.set_color(device_mac=bulb.mac, device_model=bulb.product.model, color='ff00ff')
client.bulbs.set_color_temp(device_mac=bulb.mac, device_model=bulb.product.model, color_temp=3800)
bulb = client.bulbs.info(device_mac='ABCDEF1234567890')
assert bulb.brightness == 100
assert bulb.color == 'ff00ff'
assert bulb.color_temp == 3800
client.bulbs.set_away_mode(device_mac=bulb.mac, device_model=bulb.product.model, away_mode=True)
except WyzeApiError as e:
# You will get a WyzeApiError if the request failed
print(f"Got an error: {e}")
```
#### Taking actions on devices
Want to unlock your lock, or tell your vacuum to clean certain rooms? Yeah, we got that.
```python
import os
import wyze_sdk
from wyze_sdk import Client
from wyze_sdk.errors import WyzeApiError
client = Client(token=os.environ['WYZE_ACCESS_TOKEN'])
try:
lock = client.locks.info(device_mac='YD.LO1.abcdefg0123456789abcdefg0123456789')
if lock is not None:
print(f"is open: {lock.is_open}")
print(f"is locked: {lock.is_locked}")
if not lock.is_locked:
## let's try to figure out when it was unlocked
for record in client.locks.get_records(device_mac='YD.LO1.abcdefg0123456789abcdefg0123456789', since=datetime.now() - timedelta(hours=12)):
print(f"lock record time: {record.time}")
print(f"lock record type: {record.type}")
print(f"lock record source: {record.details.source}")
## lock up
client.locks.lock(device_mac='YD.LO1.abcdefg0123456789abcdefg0123456789')
except WyzeApiError as e:
# You will get a WyzeApiError if the request failed
print(f"Got an error: {e}")
try:
vacuum = client.vacuums.info(device_mac='JA_RO2_ABCDEF123456')
from wyze_sdk.models.devices import VacuumMode
# if our vacuum is out sweeping, let's find out where he is and tell him to go home
if vacuum.mode == VacuumMode.SWEEPING:
print(f"current position: {vacuum.current_position}")
client.vacuums.dock(device_mac='JA_RO2_ABCDEF123456', device_model=vacuum.product.model)
# idle hands are the devil's playground - go clean the kitchen
elif vacuum.mode == VacuumMode.IDLE:
# want to see what's going on behind the scenes?
wyze_sdk.set_stream_logger('wyze_sdk', level=logging.DEBUG)
client.vacuums.sweep_rooms(device_mac='JA_RO2_ABCDEF123456', room_ids=[room.id for room in vacuum.current_map.rooms if room.name == 'Kitchen'])
except WyzeApiError as e:
# You will get a WyzeApiError if the request failed
print(f"Got an error: {e}")
```
<!-- Markdown links -->
[pypi-image]: https://badge.fury.io/py/wyze-sdk.svg
[pypi-url]: https://pypi.org/project/wyze-sdk/
[python-version]: https://img.shields.io/pypi/pyversions/wyze-sdk.svg
[pypi]: https://pypi.org/
[gh-issues]: https://github.com/shauntarves/wyze-sdk/issues
[support-docs]: https://img.shields.io/badge/support-docs-brightgreen
[docs-url]: https://wyze-sdk.readthedocs.io
Raw data
{
"_id": null,
"home_page": "https://github.com/shauntarves/wyze-sdk",
"name": "wyze-sdk",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": "",
"keywords": "wyze,wyze-labs,wyze-sdk,wyze-api,wyzeapy,wyze-apy,smart home,home automation",
"author": "Shaun Tarves",
"author_email": "shaun@tarves.net",
"download_url": "",
"platform": null,
"description": "# Python Wyze SDK\nA modern Python client for controlling Wyze devices.\n\n[![PyPI version][pypi-image]][pypi-url]\n[![Python Version][python-version]][pypi-url]\n[![Read the Docs][support-docs]][docs-url]\n\n\nWhether you're building a custom app, or integrating into a third-party service like Home Assistant, Wyze Developer Kit for Python allows you to leverage the flexibility of Python to get your project up and running as quickly as possible.\n\nThe **Python Wyze SDK** allows interaction with:\n\n- `wyze_sdk.client.bulbs`: for controlling Wyze Bulb, Wyze Bulb Color, Wyze Bulb White, and Wyze Light Strip\n- `wyze_sdk.client.entry_sensors`: for interacting with Wyze Entry Sensor\n- `wyze_sdk.client.cameras`: for interacting with Wyze Cameras\n- `wyze_sdk.client.events`: for managing Wyze alarm events\n- `wyze_sdk.client.locks`: for interacting with Wyze Lock and Wyze Lock Keypad\n- `wyze_sdk.client.motion_sensors`: for interacting with Wyze Motion Sensor\n- `wyze_sdk.client.plugs`: for controlling Wyze Plug and Wyze Plug Outdoor\n- `wyze_sdk.client.scales`: for controlling Wyze Scale\n- `wyze_sdk.client.switches`: for controlling Wyze Switch\n- `wyze_sdk.client.thermostats`: for controlling Wyze Thermostat and Wyze Room Sensor\n- `wyze_sdk.client.vacuums`: for controlling Wyze Robot Vacuum\n\n**Disclaimer: This repository is for non-destructive use only. WyzeLabs is a wonderful company providing excellent devices at a reasonable price. I ask that you do no harm and be civilized.**\n\n**As this repository is entirely reverse-engineered, it may break at any time. If it does, I will fix it to the best of my ability, but feel free to file a GitHub issue or patch yourself and submit a pull request.**\n\n### Requirements\n\n---\n\nThis library requires Python 3.8 and above. If you're unsure how to check what version of Python you're on, you can check it using the following:\n\n> **Note:** You may need to use `python3` before your commands to ensure you use the correct Python path. e.g. `python3 --version`\n\n```bash\npython --version\n\n-- or --\n\npython3 --version\n```\n\n### Installation\n\nWe recommend using [PyPI][pypi] to install the Wyze Developer Kit for Python.\n\n```bash\n$ pip install wyze-sdk\n```\n\n### Basic Usage of the Web Client\n\n---\n\nWyze does not provide a Web API that gives you the ability to build applications that interact with Wyze devices. This Development Kit is a reverse-engineered, module-based wrapper that makes interaction with that API possible. We have a few basic examples here with some of the more common uses but you are encouraged to [explore the full range of methods](https://wyze-sdk.readthedocs.io/en/latest/wyze_sdk.api.devices.html) available to you.\n\n#### Authenticating\n\nWhen performing user \"authentication\" with an email and password in the Wyze app, the credentials are exchanged for an access token and a refrsh token. These are long strings of the form `lvtx.XXXX`. When using this library, be aware that there are two method for handling authentiation:\n\n##### Obtaining the Token and Storing it for Later Use (Preferred)\n\nIt is preferred that users first create an empty `Client` object and use the `login()` method to perform the token exchange.\n\n```python\nimport os\nfrom wyze_sdk import Client\n\nresponse = Client().login(email=os.environ['WYZE_EMAIL'], password=os.environ['WYZE_PASSWORD'])\nprint(f\"access token: {response['access_token']}\")\nprint(f\"refresh token: {response['refresh_token']}\")\n```\n\nThe returned values can be stored on disk or as environment variables for use in subsequent calls.\n\n```python\nimport os\nfrom wyze_sdk import Client\n\nclient = Client(token=os.environ['WYZE_ACCESS_TOKEN'])\n...\n```\n\n##### (Deprecated) Automatically Authenticate Every New Client\n\nThis method has been deprecated due to issues with authentication rate limiting. While it is still a perfectly usable approach for testing or performing infrequent client actions, it **is not recommended** if you are scripting with this client library.\n\n```python\nimport os\nfrom wyze_sdk import Client\nfrom wyze_sdk.errors import WyzeApiError\n\nclient = Client(email=os.environ['WYZE_EMAIL'], password=os.environ['WYZE_PASSWORD'])\n...\n```\n\n##### Wyze API Key/ID Support\n\nVisit the Wyze developer API portal to generate an API ID/KEY: https://developer-api-console.wyze.com/#/apikey/view\n\n```python\nimport os\nfrom wyze_sdk import Client\n\nresponse = Client().login(\n email=os.environ['WYZE_EMAIL'],\n password=os.environ['WYZE_PASSWORD'],\n key_id=os.environ['WYZE_KEY_ID'],\n api_key=os.environ['WYZE_API_KEY']\n)\n...\n```\n\n##### Multi-Factor Authentication (2FA) Support\n\nIf your Wyze account has multi-factor authentication (2FA) enabled, you may be prompted for your 2FA code when authenticating via either supported method described above. If you wish to automate the MFA interaction, both the `Client` constructor and the `login()` method accept `totp_key` as input. If the TOTP key is provided, the MFA prompt should not appear. Your TOTP key can be obtained during the Wyze 2FA setup process and is the same code that you would typically input into an authenticator app during 2FA setup.\n\n```python\nimport os\nfrom wyze_sdk import Client\n\nresponse = Client().login(\n email=os.environ['WYZE_EMAIL'],\n password=os.environ['WYZE_PASSWORD'],\n totp_key=os.environ['WYZE_TOTP_KEY']\n)\n\nOR\n\nclient = Client(\n email=os.environ['WYZE_EMAIL'],\n password=os.environ['WYZE_PASSWORD'],\n totp_key=os.environ['WYZE_TOTP_KEY']\n)\n...\n```\n\n**Note: This does not work with SMS or email-based MFA.**\n\n#### Listing devices in your Wyze account\n\nOne of the most common use-cases is querying device state from Wyze. If you want to access devices you own, or devices shared to you, this method will do both.\n\n```python\nimport os\nfrom wyze_sdk import Client\nfrom wyze_sdk.errors import WyzeApiError\n\nclient = Client(token=os.environ['WYZE_ACCESS_TOKEN'])\n\ntry:\n response = client.devices_list()\n for device in client.devices_list():\n print(f\"mac: {device.mac}\")\n print(f\"nickname: {device.nickname}\")\n print(f\"is_online: {device.is_online}\")\n print(f\"product model: {device.product.model}\")\nexcept WyzeApiError as e:\n # You will get a WyzeApiError if the request failed\n print(f\"Got an error: {e}\")\n```\n\n#### Turning off a switch\n\nSome devices - like cameras, bulbs, and plugs - can be switched on and off. This is done with a simple command and even supports delayed actions via timers.\n\n```python\nimport os\nfrom datetime import timedelta\nfrom wyze_sdk import Client\nfrom wyze_sdk.errors import WyzeApiError\n\nclient = Client(token=os.environ['WYZE_ACCESS_TOKEN'])\n\ntry:\n plug = client.plugs.info(device_mac='ABCDEF1234567890')\n print(f\"power: {plug.is_on}\")\n print(f\"online: {plug.is_online}\")\n\n if plug.is_on:\n client.plugs.turn_off(device_mac=plug.mac, device_model=plug.product.model, after=timedelta(hours=3))\n else:\n client.plugs.turn_on(device_mac=plug.mac, device_model=plug.product.model)\n\n plug = client.plugs.info(device_mac=plug.mac)\n assert plug.is_on is True\nexcept WyzeApiError as e:\n # You will get a WyzeApiError if the request failed\n print(f\"Got an error: {e}\")\n```\n\n#### Setting device properties\n\nEvery Wyze device has myriad properties and attributes that can be set in a common, intuitive way.\n\n```python\nimport os\nfrom wyze_sdk import Client\nfrom wyze_sdk.errors import WyzeApiError\n\nclient = Client(token=os.environ['WYZE_ACCESS_TOKEN'])\n\ntry:\n bulb = client.bulbs.info(device_mac='ABCDEF1234567890')\n print(f\"power: {bulb.is_on}\")\n print(f\"online: {bulb.is_online}\")\n print(f\"brightness: {bulb.brightness}\")\n print(f\"temp: {bulb.color_temp}\")\n print(f\"color: {bulb.color}\")\n\n client.bulbs.set_brightness(device_mac=bulb.mac, device_model=bulb.product.model, brightness=100)\n client.bulbs.set_color(device_mac=bulb.mac, device_model=bulb.product.model, color='ff00ff')\n client.bulbs.set_color_temp(device_mac=bulb.mac, device_model=bulb.product.model, color_temp=3800)\n \n bulb = client.bulbs.info(device_mac='ABCDEF1234567890')\n assert bulb.brightness == 100\n assert bulb.color == 'ff00ff'\n assert bulb.color_temp == 3800\n\n client.bulbs.set_away_mode(device_mac=bulb.mac, device_model=bulb.product.model, away_mode=True)\n\nexcept WyzeApiError as e:\n # You will get a WyzeApiError if the request failed\n print(f\"Got an error: {e}\")\n```\n\n#### Taking actions on devices\n\nWant to unlock your lock, or tell your vacuum to clean certain rooms? Yeah, we got that.\n\n```python\nimport os\nimport wyze_sdk\nfrom wyze_sdk import Client\nfrom wyze_sdk.errors import WyzeApiError\n\nclient = Client(token=os.environ['WYZE_ACCESS_TOKEN'])\n\ntry:\n lock = client.locks.info(device_mac='YD.LO1.abcdefg0123456789abcdefg0123456789')\n if lock is not None:\n print(f\"is open: {lock.is_open}\")\n print(f\"is locked: {lock.is_locked}\")\n\n if not lock.is_locked:\n ## let's try to figure out when it was unlocked\n for record in client.locks.get_records(device_mac='YD.LO1.abcdefg0123456789abcdefg0123456789', since=datetime.now() - timedelta(hours=12)):\n print(f\"lock record time: {record.time}\")\n print(f\"lock record type: {record.type}\")\n print(f\"lock record source: {record.details.source}\")\n\n ## lock up\n client.locks.lock(device_mac='YD.LO1.abcdefg0123456789abcdefg0123456789')\n\nexcept WyzeApiError as e:\n # You will get a WyzeApiError if the request failed\n print(f\"Got an error: {e}\")\n\n\ntry:\n vacuum = client.vacuums.info(device_mac='JA_RO2_ABCDEF123456')\n\n from wyze_sdk.models.devices import VacuumMode\n\n # if our vacuum is out sweeping, let's find out where he is and tell him to go home\n if vacuum.mode == VacuumMode.SWEEPING:\n print(f\"current position: {vacuum.current_position}\")\n\n client.vacuums.dock(device_mac='JA_RO2_ABCDEF123456', device_model=vacuum.product.model)\n\n # idle hands are the devil's playground - go clean the kitchen\n elif vacuum.mode == VacuumMode.IDLE:\n # want to see what's going on behind the scenes?\n wyze_sdk.set_stream_logger('wyze_sdk', level=logging.DEBUG)\n\n client.vacuums.sweep_rooms(device_mac='JA_RO2_ABCDEF123456', room_ids=[room.id for room in vacuum.current_map.rooms if room.name == 'Kitchen'])\n\nexcept WyzeApiError as e:\n # You will get a WyzeApiError if the request failed\n print(f\"Got an error: {e}\")\n```\n\n<!-- Markdown links -->\n\n[pypi-image]: https://badge.fury.io/py/wyze-sdk.svg\n[pypi-url]: https://pypi.org/project/wyze-sdk/\n[python-version]: https://img.shields.io/pypi/pyversions/wyze-sdk.svg\n[pypi]: https://pypi.org/\n[gh-issues]: https://github.com/shauntarves/wyze-sdk/issues\n[support-docs]: https://img.shields.io/badge/support-docs-brightgreen\n[docs-url]: https://wyze-sdk.readthedocs.io\n",
"bugtrack_url": null,
"license": "The Unlicense",
"summary": "The Wyze Labs API Platform SDK for Python.",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/shauntarves/wyze-sdk"
},
"split_keywords": [
"wyze",
"wyze-labs",
"wyze-sdk",
"wyze-api",
"wyzeapy",
"wyze-apy",
"smart home",
"home automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7b6d825ccb18088548f38ffdcdfb9c0f4ac6f8ea8884437b48a0320027437df9",
"md5": "11ce7bb86cf649234afc28ecdb457232",
"sha256": "26cdea39e0417e62070fe399e6f3f69bee6bb56b37dc8d65f3dfed20b6186327"
},
"downloads": -1,
"filename": "wyze_sdk-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "11ce7bb86cf649234afc28ecdb457232",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 98678,
"upload_time": "2024-01-21T19:30:22",
"upload_time_iso_8601": "2024-01-21T19:30:22.054110Z",
"url": "https://files.pythonhosted.org/packages/7b/6d/825ccb18088548f38ffdcdfb9c0f4ac6f8ea8884437b48a0320027437df9/wyze_sdk-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-21 19:30:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shauntarves",
"github_project": "wyze-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "wyze-sdk"
}
JSON
