# SOMweb Client
A client library to control garage door operators produced by [SOMMER](https://www.sommer.eu) through their [SOMweb](https://www.sommer.eu/somweb.html) device.
> ⚠ It is not enough to have a [supported operator](https://www.sommer.eu/en/somweb.html#kompatibilitaet) to use this package. You also need the SOMWeb device.
## Made for home automation
The package is created as part of an extension to [Home Assistant](https://www.home-assistant.io/). There are no dependencies and no references to Home Assistant, so you can use the package directly from python or integrate it with any other home automation system.
## Test from terminal
In all samples replace **\*\*\*\*** with your values.
### Usage
```sh
$ python main.py -h
usage: main.py [-h] (--udi UDI | --url URL) --username USERNAME --password PASSWORD --action {alive,auth,is_admin,update_available,device_info,get_udi,get_all,status,open,close,toggle} [--door DOOR_ID]
SOMweb Client.
options:
-h, --help show this help message and exit
--udi UDI SOMweb UID (access through cloud service)
--url URL SOMweb URL (direct local access)
--username USERNAME SOMweb username
--password PASSWORD SOMweb password
--action {alive,auth,is_admin,update_available,device_info,get_udi,get_all,status,open,close,toggle}
Action to take
--door DOOR_ID Id of door to perform the following actions on: "status", "open", "close" or "toggle"
```
### Alive
Check if SOMweb is reachable and responding to requests
```sh
$ python main.py --udi ******** --username ******** --password ******** --action alive
True
Operation took 0 seconds
```
Same using direct local access
```sh
$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action alive
True
Operation took 0 seconds
```
Replace IP with your SOMweb device IP or FQDN.
### Is Admninistrator
```sh
$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action is_admin
True
Operation took 1 seconds
```
Replace IP with your SOMweb device IP or FQDN.
### Firmware Update Available
```sh
$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action update_available
False
Operation took 1 seconds
```
Replace IP with your SOMweb device IP or FQDN.
### Device Info
```sh
$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action device_info
DeviceInfo(remote_access_enabled=True, firmware_version='2.8.3', ip_address='192.168.10.10', wifi_signal_quality='4', wifi_signal_level='-58', wifi_signal_unit='dBm', time_zone='Europe/Oslo')
Operation took 3 seconds
```
Replace IP with your SOMweb device IP or FQDN.
### UDI
Get Device UDI
```sh
$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action get_udi
**********
Operation took 1 seconds
```
Replace IP with your SOMweb device IP or FQDN.
### Authenticate
Returns success, valid token and the html of the front page.
```sh
python main.py --udi ******** --username ******** --password ******** --action auth
AuthResponse(success=True, token='...', page_content='...')
Operation took 1 seconds
```
### Get Doors
Get all connected doors
```sh
$ python main.py --udi ******** --username ******** --password ******** --action get_all
[Door(id='2', name='Garage')]
Operation took 1 seconds
```
### Door Status
Get status of door with id 2
```sh
$ python main.py --udi ******** --username ******** --password ******** --action status --door 2
DoorStatusType.CLOSED
Operation took 1 seconds
```
### Toggle Door
Open a closed door and close an open door.
Does not wait for operation to finish so it takes 1s.
```sh
$ python main.py --udi ******** --username ******** --password ******** --action toggle --door 2
True
Operation took 1 seconds
```
### Open Door
Open door with id 2.
```sh
$ python main.py --udi ******** --username ******** --password ******** --action open --door 2
True
Operation took 23 seconds
```
### Close Door
Close door with id 2.
```sh
$ python main.py --udi ******** --username ******** --password ******** --action close --door 2
True
Operation took 26 seconds
```
## How to use
See models.py for class properties.
### Create client
#### With UDI (aka connecting through cloud service)
```py
somwebUDI = "1234567" # This is the SOMweb UDI. You can find it under device information
username = "automation" # Your home automation user as configured in SOMweb
password = "super_secret_password" # Your home automation user password
client = SomwebClient.createUsingUdi(somwebUDI, username, password)
# optionally with ClientSession from aiohttp.client:
client = SomwebClient.createUsingUdi(somwebUDI, username, password, session)
```
#### With IP or FQDN (aka connecting directly)
```py
somwebUri = http://192.168.10.10 # This is the SOMweb device IP or FQDN on the local network (could also be the FQDN to the cloud service).
username = "automation" # Your home automation user as configured in SOMweb
password = "super_secret_password" # Your home automation user password
client = SomwebClient(somwebUri, username, password)
# optionally with ClientSession from aiohttp.client:
client = SomwebClient(somwebUri, username, password, session)
```
### Alive
```py
# Check that SOMweb device is reachable
is_alive: bool = await client.is_alive()
```
### Authenticate
> ⚠ **Rembember to authenticate before calling any other operation**
is_alive is the only operation not requiring authentication.
```py
auth: AuthResponse = await client.authenticate()
if auth.success:
...
else
...
```
### Admin
```py
is_admin: bool = client.is_admin
```
### Firmware Update Available
```py
update_available: bool = await client.async_update_available()
```
### Firmware Update Available
```py
device_info: DeviceInfo = await client.async_get_device_info()
```
### UDI
```py
# The SOMweb device UDI
udi: str = client.udi
```
### Get Doors
```py
doors: List[Door] = client.get_doors()
```
### Door Status
Get status of door with id 2
```py
status: DoorStatusType = await client.get_door_status(2)
```
### Toggle Door
Open a closed door and close an open door.
```py
success: bool = await client.toogle_door_position(door_id)
```
### Open Door
```py
success: bool = await client.open_door(door_id)
```
### Close Door
```py
success: bool = await client.close_door(door_id)
```
### Await Door Status
Call this after opening/closing to wait for the operation to complete.
Will return false if timeout occurs before status is reached (currently 60 seconds).
```py
success: bool = await client.wait_for_door_state(door_id, door_status)
```
Sample usage:
```py
door_id = 2
auth = await client.authenticate()
await client.open_door(door_id):
await client.wait_for_door_state(door_id, DoorStatusType.OPEN)
```
## Build
Ensure Twine is installed before trying to upload: `pipenv install twine --dev`
```sh
python setup.py bdist_wheel sdist
pipenv shell
python setup.py upload
```
Note. When uploading to pypi you use an API token so the username and pwd are as follows:
```yml
Username: __token__
Password: pypi-<yourtoken>
```
Raw data
{
"_id": null,
"home_page": "https://github.com/taarskog/pysomweb",
"name": "somweb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": null,
"keywords": "sommer, SOMweb, garage door, home assistant, home automation, heiigjen",
"author": "Trond Aarskog",
"author_email": "somweb@heiigjen.com",
"download_url": "https://files.pythonhosted.org/packages/d5/3f/b207a6ebdfe030b7041e947c144176d3d035a98212ab13239c1da25942a6/somweb-1.3.2.tar.gz",
"platform": null,
"description": "\n# SOMweb Client\n\nA client library to control garage door operators produced by [SOMMER](https://www.sommer.eu) through their [SOMweb](https://www.sommer.eu/somweb.html) device.\n\n> \u26a0 It is not enough to have a [supported operator](https://www.sommer.eu/en/somweb.html#kompatibilitaet) to use this package. You also need the SOMWeb device.\n\n## Made for home automation\n\nThe package is created as part of an extension to [Home Assistant](https://www.home-assistant.io/). There are no dependencies and no references to Home Assistant, so you can use the package directly from python or integrate it with any other home automation system.\n\n## Test from terminal\n\nIn all samples replace **\\*\\*\\*\\*** with your values.\n\n### Usage\n\n```sh\n$ python main.py -h\nusage: main.py [-h] (--udi UDI | --url URL) --username USERNAME --password PASSWORD --action {alive,auth,is_admin,update_available,device_info,get_udi,get_all,status,open,close,toggle} [--door DOOR_ID]\n\nSOMweb Client.\n\noptions:\n -h, --help show this help message and exit\n --udi UDI SOMweb UID (access through cloud service)\n --url URL SOMweb URL (direct local access)\n --username USERNAME SOMweb username\n --password PASSWORD SOMweb password\n --action {alive,auth,is_admin,update_available,device_info,get_udi,get_all,status,open,close,toggle}\n Action to take\n --door DOOR_ID Id of door to perform the following actions on: \"status\", \"open\", \"close\" or \"toggle\"\n```\n\n### Alive\n\nCheck if SOMweb is reachable and responding to requests\n\n```sh\n$ python main.py --udi ******** --username ******** --password ******** --action alive\nTrue\nOperation took 0 seconds\n```\n\nSame using direct local access\n\n```sh\n$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action alive\nTrue\nOperation took 0 seconds\n```\nReplace IP with your SOMweb device IP or FQDN.\n\n### Is Admninistrator\n\n```sh\n$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action is_admin\nTrue\nOperation took 1 seconds\n```\nReplace IP with your SOMweb device IP or FQDN.\n\n### Firmware Update Available\n\n```sh\n$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action update_available\nFalse\nOperation took 1 seconds\n```\nReplace IP with your SOMweb device IP or FQDN.\n\n### Device Info\n\n```sh\n$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action device_info\nDeviceInfo(remote_access_enabled=True, firmware_version='2.8.3', ip_address='192.168.10.10', wifi_signal_quality='4', wifi_signal_level='-58', wifi_signal_unit='dBm', time_zone='Europe/Oslo')\nOperation took 3 seconds\n```\nReplace IP with your SOMweb device IP or FQDN.\n\n### UDI\n\nGet Device UDI\n\n```sh\n$ python main.py --url http://192.168.10.10 --username ******** --password ******** --action get_udi\n**********\nOperation took 1 seconds\n```\nReplace IP with your SOMweb device IP or FQDN.\n\n\n### Authenticate\n\nReturns success, valid token and the html of the front page.\n\n```sh\npython main.py --udi ******** --username ******** --password ******** --action auth\nAuthResponse(success=True, token='...', page_content='...')\nOperation took 1 seconds\n```\n\n### Get Doors\n\nGet all connected doors\n\n```sh\n$ python main.py --udi ******** --username ******** --password ******** --action get_all\n[Door(id='2', name='Garage')]\nOperation took 1 seconds\n```\n\n### Door Status\n\nGet status of door with id 2\n\n```sh\n$ python main.py --udi ******** --username ******** --password ******** --action status --door 2\nDoorStatusType.CLOSED\nOperation took 1 seconds\n```\n\n### Toggle Door\n\nOpen a closed door and close an open door.\n\nDoes not wait for operation to finish so it takes 1s.\n\n```sh\n$ python main.py --udi ******** --username ******** --password ******** --action toggle --door 2\nTrue\nOperation took 1 seconds\n```\n\n### Open Door\n\nOpen door with id 2.\n\n```sh\n$ python main.py --udi ******** --username ******** --password ******** --action open --door 2\nTrue\nOperation took 23 seconds\n```\n\n### Close Door\n\nClose door with id 2.\n\n```sh\n$ python main.py --udi ******** --username ******** --password ******** --action close --door 2\nTrue\nOperation took 26 seconds\n```\n\n## How to use\n\nSee models.py for class properties.\n\n### Create client\n\n#### With UDI (aka connecting through cloud service)\n```py\nsomwebUDI = \"1234567\" # This is the SOMweb UDI. You can find it under device information\nusername = \"automation\" # Your home automation user as configured in SOMweb\npassword = \"super_secret_password\" # Your home automation user password\n\nclient = SomwebClient.createUsingUdi(somwebUDI, username, password)\n# optionally with ClientSession from aiohttp.client:\nclient = SomwebClient.createUsingUdi(somwebUDI, username, password, session)\n```\n\n#### With IP or FQDN (aka connecting directly)\n```py\nsomwebUri = http://192.168.10.10 # This is the SOMweb device IP or FQDN on the local network (could also be the FQDN to the cloud service).\nusername = \"automation\" # Your home automation user as configured in SOMweb\npassword = \"super_secret_password\" # Your home automation user password\n\nclient = SomwebClient(somwebUri, username, password)\n# optionally with ClientSession from aiohttp.client:\nclient = SomwebClient(somwebUri, username, password, session)\n```\n\n### Alive\n\n```py\n# Check that SOMweb device is reachable\nis_alive: bool = await client.is_alive()\n\n```\n\n### Authenticate\n\n> \u26a0 **Rembember to authenticate before calling any other operation**\n\nis_alive is the only operation not requiring authentication.\n\n```py\nauth: AuthResponse = await client.authenticate()\nif auth.success:\n ...\nelse\n ...\n```\n\n### Admin\n\n```py\nis_admin: bool = client.is_admin\n\n```\n\n### Firmware Update Available\n\n```py\nupdate_available: bool = await client.async_update_available()\n```\n\n### Firmware Update Available\n\n```py\ndevice_info: DeviceInfo = await client.async_get_device_info()\n```\n\n### UDI\n\n```py\n# The SOMweb device UDI\nudi: str = client.udi\n\n```\n\n### Get Doors\n\n```py\ndoors: List[Door] = client.get_doors()\n```\n\n### Door Status\n\nGet status of door with id 2\n\n```py\nstatus: DoorStatusType = await client.get_door_status(2)\n```\n\n### Toggle Door\n\nOpen a closed door and close an open door.\n\n```py\nsuccess: bool = await client.toogle_door_position(door_id)\n```\n\n### Open Door\n\n```py\nsuccess: bool = await client.open_door(door_id)\n```\n\n### Close Door\n\n```py\nsuccess: bool = await client.close_door(door_id)\n```\n\n### Await Door Status\n\nCall this after opening/closing to wait for the operation to complete.\n\nWill return false if timeout occurs before status is reached (currently 60 seconds).\n\n```py\nsuccess: bool = await client.wait_for_door_state(door_id, door_status)\n```\n\nSample usage:\n\n```py\ndoor_id = 2\nauth = await client.authenticate()\nawait client.open_door(door_id):\nawait client.wait_for_door_state(door_id, DoorStatusType.OPEN)\n```\n\n## Build\n\nEnsure Twine is installed before trying to upload: `pipenv install twine --dev` \n\n\n```sh\npython setup.py bdist_wheel sdist\n\npipenv shell\npython setup.py upload\n```\n\nNote. When uploading to pypi you use an API token so the username and pwd are as follows:\n\n```yml\nUsername: __token__\nPassword: pypi-<yourtoken>\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "SOMweb client. Open/close Garage doors produced by SOMMER (base+/pro+/tiga/tiga+/barrier systems)",
"version": "1.3.2",
"project_urls": {
"Download": "https://github.com/taarskog/pysomweb/archive/v1.3.2.tar.gz",
"Homepage": "https://github.com/taarskog/pysomweb"
},
"split_keywords": [
"sommer",
" somweb",
" garage door",
" home assistant",
" home automation",
" heiigjen"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bdbd71a450f79c408a6bfce179c66beee28f5935b94677629a4b46a0da85dc8a",
"md5": "d857decc9260da51fed50c347e622040",
"sha256": "58e75692d76dd92e4a937a7bc3a325bb1aa6967355386a8efeabddee1b646c20"
},
"downloads": -1,
"filename": "somweb-1.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d857decc9260da51fed50c347e622040",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.0",
"size": 12532,
"upload_time": "2024-06-14T19:38:03",
"upload_time_iso_8601": "2024-06-14T19:38:03.738642Z",
"url": "https://files.pythonhosted.org/packages/bd/bd/71a450f79c408a6bfce179c66beee28f5935b94677629a4b46a0da85dc8a/somweb-1.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d53fb207a6ebdfe030b7041e947c144176d3d035a98212ab13239c1da25942a6",
"md5": "94506edcda888fcf330cc228f3653156",
"sha256": "15f146422ce35eda2d1671f4f7f51ede072d291475f0507252296f05533a77a2"
},
"downloads": -1,
"filename": "somweb-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "94506edcda888fcf330cc228f3653156",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 14573,
"upload_time": "2024-06-14T19:38:05",
"upload_time_iso_8601": "2024-06-14T19:38:05.421078Z",
"url": "https://files.pythonhosted.org/packages/d5/3f/b207a6ebdfe030b7041e947c144176d3d035a98212ab13239c1da25942a6/somweb-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-14 19:38:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "taarskog",
"github_project": "pysomweb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "aiohttp",
"specs": []
}
],
"lcname": "somweb"
}
JSON
