# Aioshelly
Asynchronous library to control Shelly devices
**This library is under development**
## Requirements
- Python >= 3.11
- bluetooth-data-tools
- aiohttp
- orjson
## Install
```bash
pip install aioshelly
```
## Install from Source
Run the following command inside this folder
```bash
pip install --upgrade .
```
## Examples
### Gen1 Device (Block/CoAP) example:
```python
import asyncio
from pprint import pprint
import aiohttp
from aioshelly.block_device import COAP, BlockDevice
from aioshelly.common import ConnectionOptions
from aioshelly.exceptions import DeviceConnectionError, InvalidAuthError
async def test_block_device():
"""Test Gen1 Block (CoAP) based device."""
options = ConnectionOptions("192.168.1.165", "username", "password")
async with aiohttp.ClientSession() as aiohttp_session, COAP() as coap_context:
try:
device = await BlockDevice.create(aiohttp_session, coap_context, options)
except InvalidAuthError as err:
print(f"Invalid or missing authorization, error: {repr(err)}")
return
except DeviceConnectionError as err:
print(f"Error connecting to {options.ip_address}, error: {repr(err)}")
return
for block in device.blocks:
print(block)
pprint(block.current_values())
print()
if __name__ == "__main__":
asyncio.run(test_block_device())
```
### Gen2 and Gen3 (RPC/WebSocket) device example:
```python
import asyncio
from pprint import pprint
import aiohttp
from aioshelly.common import ConnectionOptions
from aioshelly.exceptions import DeviceConnectionError, InvalidAuthError
from aioshelly.rpc_device import RpcDevice, WsServer
async def test_rpc_device():
"""Test Gen2/Gen3 RPC (WebSocket) based device."""
options = ConnectionOptions("192.168.1.188", "username", "password")
ws_context = WsServer()
await ws_context.initialize(8123)
async with aiohttp.ClientSession() as aiohttp_session:
try:
device = await RpcDevice.create(aiohttp_session, ws_context, options)
except InvalidAuthError as err:
print(f"Invalid or missing authorization, error: {repr(err)}")
return
except DeviceConnectionError as err:
print(f"Error connecting to {options.ip_address}, error: {repr(err)}")
return
pprint(device.status)
if __name__ == "__main__":
asyncio.run(test_rpc_device())
```
## Example script
The repository includes example script to quickly try it out.
### Connect to a device and print its status whenever we receive a state change:
```
python3 tools/example.py -ip <ip> [-u <username>] [-p <password] -i
```
### Connect to all the devices in `devices.json` at once and print their status:
```
python3 tools/example.py -d -i
```
### Show usage help:
```
python3 tools/example.py -h
```
## Contribution guidelines
Object hierarchy and property/method names should match the [Shelly API](https://shelly-api-docs.shelly.cloud/).
Raw data
{
"_id": null,
"home_page": "https://github.com/home-assistant-libs/aioshelly",
"name": "aioshelly",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Paulus Schoutsen",
"author_email": "paulus@home-assistant.io",
"download_url": "https://files.pythonhosted.org/packages/f3/08/e29a19831a4cf7577a4eb497ff070e3c85948caf20ead98e6d0415ec7589/aioshelly-10.0.0.tar.gz",
"platform": "any",
"description": "# Aioshelly\n\nAsynchronous library to control Shelly devices\n\n**This library is under development**\n\n## Requirements\n\n- Python >= 3.11\n- bluetooth-data-tools\n- aiohttp\n- orjson\n\n## Install\n```bash\npip install aioshelly\n```\n\n## Install from Source\nRun the following command inside this folder\n```bash\npip install --upgrade .\n```\n\n## Examples\n### Gen1 Device (Block/CoAP) example:\n\n```python\nimport asyncio\nfrom pprint import pprint\n\nimport aiohttp\n\nfrom aioshelly.block_device import COAP, BlockDevice\nfrom aioshelly.common import ConnectionOptions\nfrom aioshelly.exceptions import DeviceConnectionError, InvalidAuthError\n\n\nasync def test_block_device():\n \"\"\"Test Gen1 Block (CoAP) based device.\"\"\"\n options = ConnectionOptions(\"192.168.1.165\", \"username\", \"password\")\n\n async with aiohttp.ClientSession() as aiohttp_session, COAP() as coap_context:\n try:\n device = await BlockDevice.create(aiohttp_session, coap_context, options)\n except InvalidAuthError as err:\n print(f\"Invalid or missing authorization, error: {repr(err)}\")\n return\n except DeviceConnectionError as err:\n print(f\"Error connecting to {options.ip_address}, error: {repr(err)}\")\n return\n\n for block in device.blocks:\n print(block)\n pprint(block.current_values())\n print()\n\n\nif __name__ == \"__main__\":\n asyncio.run(test_block_device())\n```\n\n### Gen2 and Gen3 (RPC/WebSocket) device example:\n\n```python\nimport asyncio\nfrom pprint import pprint\n\nimport aiohttp\n\nfrom aioshelly.common import ConnectionOptions\nfrom aioshelly.exceptions import DeviceConnectionError, InvalidAuthError\nfrom aioshelly.rpc_device import RpcDevice, WsServer\n\n\nasync def test_rpc_device():\n \"\"\"Test Gen2/Gen3 RPC (WebSocket) based device.\"\"\"\n options = ConnectionOptions(\"192.168.1.188\", \"username\", \"password\")\n ws_context = WsServer()\n await ws_context.initialize(8123)\n\n async with aiohttp.ClientSession() as aiohttp_session:\n try:\n device = await RpcDevice.create(aiohttp_session, ws_context, options)\n except InvalidAuthError as err:\n print(f\"Invalid or missing authorization, error: {repr(err)}\")\n return\n except DeviceConnectionError as err:\n print(f\"Error connecting to {options.ip_address}, error: {repr(err)}\")\n return\n\n pprint(device.status)\n\n\nif __name__ == \"__main__\":\n asyncio.run(test_rpc_device())\n```\n\n## Example script\n\nThe repository includes example script to quickly try it out.\n\n### Connect to a device and print its status whenever we receive a state change:\n\n```\npython3 tools/example.py -ip <ip> [-u <username>] [-p <password] -i\n```\n\n### Connect to all the devices in `devices.json` at once and print their status:\n\n```\npython3 tools/example.py -d -i\n```\n### Show usage help:\n```\npython3 tools/example.py -h\n```\n\n## Contribution guidelines\n\nObject hierarchy and property/method names should match the [Shelly API](https://shelly-api-docs.shelly.cloud/).\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Asynchronous library to control Shelly devices.",
"version": "10.0.0",
"project_urls": {
"Homepage": "https://github.com/home-assistant-libs/aioshelly"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c6f4f39edb3a550da9329e3e923a56d81d3642b539e597a67aeb2b960d9542a",
"md5": "583da0378140a4bc4fd02ccd79720ae4",
"sha256": "b503a4b0863a079cfaac2e7c0b4ea4a31d127fa2b5356651eba9cc91cee93b7d"
},
"downloads": -1,
"filename": "aioshelly-10.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "583da0378140a4bc4fd02ccd79720ae4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 42501,
"upload_time": "2024-05-18T21:53:30",
"upload_time_iso_8601": "2024-05-18T21:53:30.535178Z",
"url": "https://files.pythonhosted.org/packages/3c/6f/4f39edb3a550da9329e3e923a56d81d3642b539e597a67aeb2b960d9542a/aioshelly-10.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f308e29a19831a4cf7577a4eb497ff070e3c85948caf20ead98e6d0415ec7589",
"md5": "2054cd62af2da1edb2772c71995aea5d",
"sha256": "f6a6c814cd5cef858e92c4cee057662a893519da4d9c1e2cfe44786d1af63622"
},
"downloads": -1,
"filename": "aioshelly-10.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2054cd62af2da1edb2772c71995aea5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 35553,
"upload_time": "2024-05-18T21:53:32",
"upload_time_iso_8601": "2024-05-18T21:53:32.731463Z",
"url": "https://files.pythonhosted.org/packages/f3/08/e29a19831a4cf7577a4eb497ff070e3c85948caf20ead98e6d0415ec7589/aioshelly-10.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-18 21:53:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "home-assistant-libs",
"github_project": "aioshelly",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "bluetooth-data-tools",
"specs": [
[
">=",
"1.19.0"
]
]
},
{
"name": "aiohttp",
"specs": []
},
{
"name": "habluetooth",
"specs": [
[
">=",
"2.1.0"
]
]
},
{
"name": "yarl",
"specs": []
},
{
"name": "orjson",
"specs": [
[
">=",
"3.8.1"
]
]
}
],
"tox": true,
"lcname": "aioshelly"
}
JSON
