aioprotegewx 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- aioprotegewx-0.1.0/.github/workflows/ci.yml +47 -0
- aioprotegewx-0.1.0/.github/workflows/release.yml +118 -0
- aioprotegewx-0.1.0/.gitignore +10 -0
- aioprotegewx-0.1.0/CHANGELOG.md +11 -0
- aioprotegewx-0.1.0/LICENSE +21 -0
- aioprotegewx-0.1.0/NOTICE +9 -0
- aioprotegewx-0.1.0/PKG-INFO +114 -0
- aioprotegewx-0.1.0/README.md +78 -0
- aioprotegewx-0.1.0/pyproject.toml +74 -0
- aioprotegewx-0.1.0/src/aioprotegewx/__init__.py +62 -0
- aioprotegewx-0.1.0/src/aioprotegewx/__main__.py +76 -0
- aioprotegewx-0.1.0/src/aioprotegewx/client.py +563 -0
- aioprotegewx-0.1.0/src/aioprotegewx/crypto.py +89 -0
- aioprotegewx-0.1.0/src/aioprotegewx/events.py +371 -0
- aioprotegewx-0.1.0/src/aioprotegewx/py.typed +0 -0
- aioprotegewx-0.1.0/src/aioprotegewx/status.py +286 -0
- aioprotegewx-0.1.0/tests/__init__.py +0 -0
- aioprotegewx-0.1.0/tests/fake_controller.py +297 -0
- aioprotegewx-0.1.0/tests/test_cli.py +38 -0
- aioprotegewx-0.1.0/tests/test_client.py +284 -0
- aioprotegewx-0.1.0/tests/test_client_more.py +113 -0
- aioprotegewx-0.1.0/tests/test_events.py +131 -0
- aioprotegewx-0.1.0/tests/test_status.py +57 -0
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
pull_request:
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
lint:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- uses: actions/setup-python@v5
|
|
17
|
+
with:
|
|
18
|
+
python-version: "3.14"
|
|
19
|
+
- run: pip install -e ".[lint]"
|
|
20
|
+
- run: ruff check .
|
|
21
|
+
- run: ruff format --check .
|
|
22
|
+
- run: mypy
|
|
23
|
+
|
|
24
|
+
test:
|
|
25
|
+
runs-on: ubuntu-latest
|
|
26
|
+
strategy:
|
|
27
|
+
fail-fast: false
|
|
28
|
+
matrix:
|
|
29
|
+
python: ["3.12", "3.13", "3.14"]
|
|
30
|
+
steps:
|
|
31
|
+
- uses: actions/checkout@v4
|
|
32
|
+
- uses: actions/setup-python@v5
|
|
33
|
+
with:
|
|
34
|
+
python-version: ${{ matrix.python }}
|
|
35
|
+
- run: pip install -e ".[test]"
|
|
36
|
+
- run: pytest -q --cov=aioprotegewx --cov-report=term-missing
|
|
37
|
+
|
|
38
|
+
build:
|
|
39
|
+
runs-on: ubuntu-latest
|
|
40
|
+
steps:
|
|
41
|
+
- uses: actions/checkout@v4
|
|
42
|
+
- uses: actions/setup-python@v5
|
|
43
|
+
with:
|
|
44
|
+
python-version: "3.14"
|
|
45
|
+
- run: pip install build twine
|
|
46
|
+
- run: python -m build
|
|
47
|
+
- run: twine check dist/*
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
# Releases happen by themselves: bump __version__ in src/aioprotegewx/__init__.py,
|
|
4
|
+
# add its CHANGELOG.md section, and push to main. If no release exists for that
|
|
5
|
+
# version yet, this builds it, publishes it to PyPI and creates the GitHub
|
|
6
|
+
# release and tag. Pushing a "v<version>" tag, or publishing a release by hand,
|
|
7
|
+
# still works too.
|
|
8
|
+
# PyPI publishing uses trusted publishing: no token is stored in GitHub.
|
|
9
|
+
|
|
10
|
+
on:
|
|
11
|
+
push:
|
|
12
|
+
branches: [main]
|
|
13
|
+
tags: ["v*"]
|
|
14
|
+
workflow_dispatch:
|
|
15
|
+
|
|
16
|
+
concurrency:
|
|
17
|
+
group: release
|
|
18
|
+
cancel-in-progress: false
|
|
19
|
+
|
|
20
|
+
jobs:
|
|
21
|
+
plan:
|
|
22
|
+
runs-on: ubuntu-latest
|
|
23
|
+
permissions:
|
|
24
|
+
contents: read
|
|
25
|
+
outputs:
|
|
26
|
+
tag: ${{ steps.plan.outputs.tag }}
|
|
27
|
+
release: ${{ steps.plan.outputs.release }}
|
|
28
|
+
steps:
|
|
29
|
+
- uses: actions/checkout@v4
|
|
30
|
+
- id: plan
|
|
31
|
+
env:
|
|
32
|
+
GH_TOKEN: ${{ github.token }}
|
|
33
|
+
run: |
|
|
34
|
+
version=$(python3 -c "import re,pathlib;print(re.search(r'__version__ = \"(.+?)\"', pathlib.Path('src/aioprotegewx/__init__.py').read_text())[1])")
|
|
35
|
+
tag="v$version"
|
|
36
|
+
echo "tag=$tag" >> "$GITHUB_OUTPUT"
|
|
37
|
+
if [ "$GITHUB_REF_TYPE" = "tag" ]; then
|
|
38
|
+
if [ "$GITHUB_REF_NAME" != "$tag" ]; then
|
|
39
|
+
echo "tag $GITHUB_REF_NAME != $tag"; exit 1
|
|
40
|
+
fi
|
|
41
|
+
echo "release=true" >> "$GITHUB_OUTPUT"
|
|
42
|
+
elif gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1 \
|
|
43
|
+
|| git ls-remote --exit-code --tags origin "refs/tags/$tag" >/dev/null 2>&1; then
|
|
44
|
+
echo "$tag already released"
|
|
45
|
+
echo "release=false" >> "$GITHUB_OUTPUT"
|
|
46
|
+
elif ! grep -qx "## $version" CHANGELOG.md; then
|
|
47
|
+
echo "CHANGELOG.md has no '## $version' section yet; not releasing"
|
|
48
|
+
echo "release=false" >> "$GITHUB_OUTPUT"
|
|
49
|
+
else
|
|
50
|
+
echo "release=true" >> "$GITHUB_OUTPUT"
|
|
51
|
+
fi
|
|
52
|
+
|
|
53
|
+
build:
|
|
54
|
+
needs: plan
|
|
55
|
+
if: needs.plan.outputs.release == 'true'
|
|
56
|
+
runs-on: ubuntu-latest
|
|
57
|
+
permissions:
|
|
58
|
+
contents: read
|
|
59
|
+
steps:
|
|
60
|
+
- uses: actions/checkout@v4
|
|
61
|
+
- uses: actions/setup-python@v5
|
|
62
|
+
with:
|
|
63
|
+
python-version: "3.14"
|
|
64
|
+
- run: pip install build
|
|
65
|
+
- run: python -m build
|
|
66
|
+
- uses: actions/upload-artifact@v4
|
|
67
|
+
with:
|
|
68
|
+
name: dist
|
|
69
|
+
path: dist/
|
|
70
|
+
|
|
71
|
+
pypi:
|
|
72
|
+
needs: build
|
|
73
|
+
runs-on: ubuntu-latest
|
|
74
|
+
environment:
|
|
75
|
+
name: pypi
|
|
76
|
+
url: https://pypi.org/project/aioprotegewx/
|
|
77
|
+
permissions:
|
|
78
|
+
id-token: write
|
|
79
|
+
steps:
|
|
80
|
+
- uses: actions/download-artifact@v4
|
|
81
|
+
with:
|
|
82
|
+
name: dist
|
|
83
|
+
path: dist/
|
|
84
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
85
|
+
|
|
86
|
+
github:
|
|
87
|
+
needs: [plan, pypi]
|
|
88
|
+
runs-on: ubuntu-latest
|
|
89
|
+
permissions:
|
|
90
|
+
contents: write
|
|
91
|
+
steps:
|
|
92
|
+
- uses: actions/checkout@v4
|
|
93
|
+
- uses: actions/download-artifact@v4
|
|
94
|
+
with:
|
|
95
|
+
name: dist
|
|
96
|
+
path: dist/
|
|
97
|
+
- name: Release notes from CHANGELOG.md
|
|
98
|
+
env:
|
|
99
|
+
TAG: ${{ needs.plan.outputs.tag }}
|
|
100
|
+
run: |
|
|
101
|
+
version="${TAG#v}"
|
|
102
|
+
awk -v v="## $version" '$0==v{f=1;next} /^## /{f=0} f' CHANGELOG.md > notes.md
|
|
103
|
+
# A release published by hand creates the tag that starts this workflow,
|
|
104
|
+
# so the release may already exist: then attach the files and fill in
|
|
105
|
+
# empty notes instead of creating it.
|
|
106
|
+
- env:
|
|
107
|
+
GH_TOKEN: ${{ github.token }}
|
|
108
|
+
TAG: ${{ needs.plan.outputs.tag }}
|
|
109
|
+
run: |
|
|
110
|
+
if gh release view "$TAG" >/dev/null 2>&1; then
|
|
111
|
+
gh release upload "$TAG" dist/* --clobber
|
|
112
|
+
body=$(gh release view "$TAG" --json body --jq .body)
|
|
113
|
+
if [ -z "$(echo "$body" | tr -d '[:space:]')" ] && [ -s notes.md ]; then
|
|
114
|
+
gh release edit "$TAG" --notes-file notes.md
|
|
115
|
+
fi
|
|
116
|
+
else
|
|
117
|
+
gh release create "$TAG" dist/* --title "$TAG" --notes-file notes.md --target "$GITHUB_SHA"
|
|
118
|
+
fi
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
First release, moved out of the [ICT Protege WX integration for Home Assistant](https://github.com/olliemaller/ha-protege-wx) so it can be used on its own.
|
|
6
|
+
|
|
7
|
+
- `ProtegeClient`: login (both web protocol versions, auto-detected), status for areas, doors, inputs, trouble inputs and outputs, controls, event log, health values and troubles, with `LoginGuard` limits that protect the controller.
|
|
8
|
+
- `EventParser`: event log lines into kind, subject, type, user and method.
|
|
9
|
+
- Fixed: when two names overlap (doors "Front" and "Front Door"), an event for the longer one is no longer matched to the shorter.
|
|
10
|
+
- `aioprotegewx` command-line tool: `status`, `events`.
|
|
11
|
+
- Fully typed (`mypy --strict`), 97% test coverage.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 olliemaller and the ha-protege-wx contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
aioprotegewx
|
|
2
|
+
Copyright (c) 2026 olliemaller and the aioprotegewx contributors
|
|
3
|
+
|
|
4
|
+
Portions of src/aioprotegewx are derived from protege-wx-cli
|
|
5
|
+
(https://github.com/mitchell-johnson/protege-wx-cli),
|
|
6
|
+
Copyright (c) Mitchell Johnson, used under the MIT License.
|
|
7
|
+
|
|
8
|
+
ICT and Protege are trademarks of Integrated Control Technology Ltd.
|
|
9
|
+
This project is not affiliated with or endorsed by ICT.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: aioprotegewx
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Async client for ICT Protege WX alarm and access controllers through their web interface
|
|
5
|
+
Project-URL: Homepage, https://github.com/olliemaller/aioprotegewx
|
|
6
|
+
Project-URL: Issues, https://github.com/olliemaller/aioprotegewx/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/olliemaller/aioprotegewx/blob/main/CHANGELOG.md
|
|
8
|
+
Author: Oliver Maller
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
License-File: NOTICE
|
|
12
|
+
Keywords: access-control,alarm,asyncio,home-assistant,ict,protege
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Framework :: AsyncIO
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Topic :: Home Automation
|
|
22
|
+
Classifier: Topic :: Security
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Python: >=3.12
|
|
25
|
+
Requires-Dist: aiohttp>=3.9
|
|
26
|
+
Requires-Dist: cryptography>=42
|
|
27
|
+
Requires-Dist: yarl>=1.9
|
|
28
|
+
Provides-Extra: lint
|
|
29
|
+
Requires-Dist: mypy>=1.13; extra == 'lint'
|
|
30
|
+
Requires-Dist: ruff>=0.8; extra == 'lint'
|
|
31
|
+
Provides-Extra: test
|
|
32
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
|
|
33
|
+
Requires-Dist: pytest-cov>=5; extra == 'test'
|
|
34
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
# aioprotegewx
|
|
38
|
+
|
|
39
|
+
Async Python client for **ICT Protege WX** alarm and access controllers, through the controller's own **web interface**.
|
|
40
|
+
|
|
41
|
+
ICT's official integration route, the Automation and Control service, needs a paid licence that many WX controllers don't have. Every WX has a web interface, and this library speaks the same encrypted protocol as its pages. If you can log in to the controller in a browser, you can use this.
|
|
42
|
+
|
|
43
|
+
It powers the [ICT Protege WX integration for Home Assistant](https://github.com/olliemaller/ha-protege-wx).
|
|
44
|
+
|
|
45
|
+
- Areas: status, arm (away, stay, instant, force), disarm, silence, walk test.
|
|
46
|
+
- Doors: lock state and position, lock, unlock (timed or latched).
|
|
47
|
+
- Inputs and trouble inputs: open, closed, tamper, short, bypass (temporary or permanent).
|
|
48
|
+
- Outputs: on, off, timed.
|
|
49
|
+
- Event log pages, parsed into what happened, to what, and who did it.
|
|
50
|
+
- Health values (serial number, firmware, voltages) and health troubles.
|
|
51
|
+
- Both web protocol versions, detected automatically: **2.3.x** (HTTP POST with a controller session cookie) and older (HTTP GET with a client session).
|
|
52
|
+
|
|
53
|
+
Python 3.12 or later. Plain HTTP only: controllers whose web interface is HTTPS-only need the Automation and Control route.
|
|
54
|
+
|
|
55
|
+
## Install
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install aioprotegewx
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Use
|
|
62
|
+
|
|
63
|
+
Create an **operator** on the controller for your program, with only the permissions it needs. Set its session timeout to about 15 minutes.
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import asyncio
|
|
67
|
+
import aiohttp
|
|
68
|
+
from aioprotegewx import ProtegeClient
|
|
69
|
+
|
|
70
|
+
async def main() -> None:
|
|
71
|
+
# The controller issues its own session cookie, so give the client a jar that accepts it.
|
|
72
|
+
async with aiohttp.ClientSession(cookie_jar=aiohttp.CookieJar(unsafe=True)) as session:
|
|
73
|
+
client = ProtegeClient(session, "192.168.1.10:7377", "homeassistant", "password")
|
|
74
|
+
try:
|
|
75
|
+
areas = await client.area_status()
|
|
76
|
+
for rec_id, area in areas.items():
|
|
77
|
+
print(rec_id, area.state, area.in_alarm)
|
|
78
|
+
await client.arm_area(16, "stay")
|
|
79
|
+
finally:
|
|
80
|
+
await client.close() # logs out
|
|
81
|
+
|
|
82
|
+
asyncio.run(main())
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The client logs in on first use and keeps one session. Unknown or unreadable states come back as `None` or `unknown_<code>`, never as a reassuring *disarmed*, *locked* or *closed*.
|
|
86
|
+
|
|
87
|
+
## Being gentle with the controller
|
|
88
|
+
|
|
89
|
+
A controller whose session table filled with abandoned sessions has been seen to stall and reboot, so the client is careful:
|
|
90
|
+
|
|
91
|
+
- **One session**, logged out by `close()`.
|
|
92
|
+
- **Gentle reconnects.** A dropped session is re-established once. If the controller refuses straight away, logins pause for 30 s, doubling up to 10 minutes, and never exceed 6 in 10 minutes. Share one `LoginGuard` between clients for the same controller so restarts can't get round these limits.
|
|
93
|
+
- **No operator lockouts.** A wrong password stops all login attempts after at most two tries (`auth_failed` stays set).
|
|
94
|
+
|
|
95
|
+
## Command line
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
aioprotegewx status 192.168.1.10:7377 --username homeassistant --password ...
|
|
99
|
+
aioprotegewx events 192.168.1.10:7377 --username homeassistant --password ...
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Development
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
pip install -e ".[test,lint]"
|
|
106
|
+
pytest --cov=aioprotegewx
|
|
107
|
+
ruff check . && ruff format --check . && mypy
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Releases are automatic: bump `__version__` in `src/aioprotegewx/__init__.py`, add a `CHANGELOG.md` section, and push to `main`.
|
|
111
|
+
|
|
112
|
+
## Credits and licence
|
|
113
|
+
|
|
114
|
+
Protocol work derived from [protege-wx-cli](https://github.com/mitchell-johnson/protege-wx-cli) by Mitchell Johnson (MIT), extended for web interface 2.3.x. [MIT](LICENSE); see [NOTICE](NOTICE).
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# aioprotegewx
|
|
2
|
+
|
|
3
|
+
Async Python client for **ICT Protege WX** alarm and access controllers, through the controller's own **web interface**.
|
|
4
|
+
|
|
5
|
+
ICT's official integration route, the Automation and Control service, needs a paid licence that many WX controllers don't have. Every WX has a web interface, and this library speaks the same encrypted protocol as its pages. If you can log in to the controller in a browser, you can use this.
|
|
6
|
+
|
|
7
|
+
It powers the [ICT Protege WX integration for Home Assistant](https://github.com/olliemaller/ha-protege-wx).
|
|
8
|
+
|
|
9
|
+
- Areas: status, arm (away, stay, instant, force), disarm, silence, walk test.
|
|
10
|
+
- Doors: lock state and position, lock, unlock (timed or latched).
|
|
11
|
+
- Inputs and trouble inputs: open, closed, tamper, short, bypass (temporary or permanent).
|
|
12
|
+
- Outputs: on, off, timed.
|
|
13
|
+
- Event log pages, parsed into what happened, to what, and who did it.
|
|
14
|
+
- Health values (serial number, firmware, voltages) and health troubles.
|
|
15
|
+
- Both web protocol versions, detected automatically: **2.3.x** (HTTP POST with a controller session cookie) and older (HTTP GET with a client session).
|
|
16
|
+
|
|
17
|
+
Python 3.12 or later. Plain HTTP only: controllers whose web interface is HTTPS-only need the Automation and Control route.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install aioprotegewx
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Use
|
|
26
|
+
|
|
27
|
+
Create an **operator** on the controller for your program, with only the permissions it needs. Set its session timeout to about 15 minutes.
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
import asyncio
|
|
31
|
+
import aiohttp
|
|
32
|
+
from aioprotegewx import ProtegeClient
|
|
33
|
+
|
|
34
|
+
async def main() -> None:
|
|
35
|
+
# The controller issues its own session cookie, so give the client a jar that accepts it.
|
|
36
|
+
async with aiohttp.ClientSession(cookie_jar=aiohttp.CookieJar(unsafe=True)) as session:
|
|
37
|
+
client = ProtegeClient(session, "192.168.1.10:7377", "homeassistant", "password")
|
|
38
|
+
try:
|
|
39
|
+
areas = await client.area_status()
|
|
40
|
+
for rec_id, area in areas.items():
|
|
41
|
+
print(rec_id, area.state, area.in_alarm)
|
|
42
|
+
await client.arm_area(16, "stay")
|
|
43
|
+
finally:
|
|
44
|
+
await client.close() # logs out
|
|
45
|
+
|
|
46
|
+
asyncio.run(main())
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The client logs in on first use and keeps one session. Unknown or unreadable states come back as `None` or `unknown_<code>`, never as a reassuring *disarmed*, *locked* or *closed*.
|
|
50
|
+
|
|
51
|
+
## Being gentle with the controller
|
|
52
|
+
|
|
53
|
+
A controller whose session table filled with abandoned sessions has been seen to stall and reboot, so the client is careful:
|
|
54
|
+
|
|
55
|
+
- **One session**, logged out by `close()`.
|
|
56
|
+
- **Gentle reconnects.** A dropped session is re-established once. If the controller refuses straight away, logins pause for 30 s, doubling up to 10 minutes, and never exceed 6 in 10 minutes. Share one `LoginGuard` between clients for the same controller so restarts can't get round these limits.
|
|
57
|
+
- **No operator lockouts.** A wrong password stops all login attempts after at most two tries (`auth_failed` stays set).
|
|
58
|
+
|
|
59
|
+
## Command line
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
aioprotegewx status 192.168.1.10:7377 --username homeassistant --password ...
|
|
63
|
+
aioprotegewx events 192.168.1.10:7377 --username homeassistant --password ...
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Development
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pip install -e ".[test,lint]"
|
|
70
|
+
pytest --cov=aioprotegewx
|
|
71
|
+
ruff check . && ruff format --check . && mypy
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Releases are automatic: bump `__version__` in `src/aioprotegewx/__init__.py`, add a `CHANGELOG.md` section, and push to `main`.
|
|
75
|
+
|
|
76
|
+
## Credits and licence
|
|
77
|
+
|
|
78
|
+
Protocol work derived from [protege-wx-cli](https://github.com/mitchell-johnson/protege-wx-cli) by Mitchell Johnson (MIT), extended for web interface 2.3.x. [MIT](LICENSE); see [NOTICE](NOTICE).
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.25"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "aioprotegewx"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Async client for ICT Protege WX alarm and access controllers through their web interface"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE", "NOTICE"]
|
|
12
|
+
authors = [{ name = "Oliver Maller" }]
|
|
13
|
+
requires-python = ">=3.12"
|
|
14
|
+
dependencies = ["aiohttp>=3.9", "cryptography>=42", "yarl>=1.9"]
|
|
15
|
+
keywords = ["ict", "protege", "alarm", "access-control", "home-assistant", "asyncio"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Framework :: AsyncIO",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Operating System :: OS Independent",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Programming Language :: Python :: 3.14",
|
|
25
|
+
"Topic :: Home Automation",
|
|
26
|
+
"Topic :: Security",
|
|
27
|
+
"Typing :: Typed",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://github.com/olliemaller/aioprotegewx"
|
|
32
|
+
Issues = "https://github.com/olliemaller/aioprotegewx/issues"
|
|
33
|
+
Changelog = "https://github.com/olliemaller/aioprotegewx/blob/main/CHANGELOG.md"
|
|
34
|
+
|
|
35
|
+
[project.scripts]
|
|
36
|
+
aioprotegewx = "aioprotegewx.__main__:main"
|
|
37
|
+
|
|
38
|
+
[project.optional-dependencies]
|
|
39
|
+
test = ["pytest>=8", "pytest-asyncio>=0.24", "pytest-cov>=5"]
|
|
40
|
+
lint = ["ruff>=0.8", "mypy>=1.13"]
|
|
41
|
+
|
|
42
|
+
[tool.hatch.version]
|
|
43
|
+
path = "src/aioprotegewx/__init__.py"
|
|
44
|
+
|
|
45
|
+
[tool.hatch.build.targets.wheel]
|
|
46
|
+
packages = ["src/aioprotegewx"]
|
|
47
|
+
|
|
48
|
+
[tool.pytest.ini_options]
|
|
49
|
+
asyncio_mode = "auto"
|
|
50
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
51
|
+
testpaths = ["tests"]
|
|
52
|
+
|
|
53
|
+
[tool.coverage.report]
|
|
54
|
+
fail_under = 95
|
|
55
|
+
|
|
56
|
+
[tool.ruff]
|
|
57
|
+
target-version = "py312"
|
|
58
|
+
line-length = 100
|
|
59
|
+
|
|
60
|
+
[tool.ruff.lint]
|
|
61
|
+
select = ["E", "F", "W", "I", "B", "UP", "S", "SIM", "RUF", "ASYNC", "PT"]
|
|
62
|
+
ignore = ["S101", "S104", "ASYNC109", "E501"]
|
|
63
|
+
|
|
64
|
+
[tool.ruff.lint.isort]
|
|
65
|
+
force-sort-within-sections = true
|
|
66
|
+
known-first-party = ["aioprotegewx"]
|
|
67
|
+
|
|
68
|
+
[tool.mypy]
|
|
69
|
+
strict = true
|
|
70
|
+
python_version = "3.12"
|
|
71
|
+
files = ["src"]
|
|
72
|
+
|
|
73
|
+
[tool.ruff.lint.per-file-ignores]
|
|
74
|
+
"tests/*" = ["S105", "S106", "S107", "S311", "S324", "E501", "ASYNC110", "PT011", "PT018"]
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Async client for ICT Protege WX controllers, through their web interface.
|
|
2
|
+
|
|
3
|
+
Speaks the same encrypted protocol as the controller's own web pages, so no
|
|
4
|
+
Automation and Control licence is needed. Protocol work derived from
|
|
5
|
+
protege-wx-cli by Mitchell Johnson (MIT licence), extended for web UI 2.3.x
|
|
6
|
+
controllers.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from .client import (
|
|
12
|
+
PROTOCOL_AUTO,
|
|
13
|
+
PROTOCOL_LEGACY,
|
|
14
|
+
PROTOCOL_POST,
|
|
15
|
+
TBL_AREAS,
|
|
16
|
+
TBL_DOORS,
|
|
17
|
+
TBL_INPUT_TYPES,
|
|
18
|
+
TBL_INPUTS,
|
|
19
|
+
TBL_OUTPUTS,
|
|
20
|
+
TBL_TROUBLE_INPUTS,
|
|
21
|
+
LoginGuard,
|
|
22
|
+
ProtegeAuthError,
|
|
23
|
+
ProtegeClient,
|
|
24
|
+
ProtegeCommandError,
|
|
25
|
+
ProtegeConnectionError,
|
|
26
|
+
ProtegeError,
|
|
27
|
+
ProtegeSessionError,
|
|
28
|
+
normalise_host,
|
|
29
|
+
)
|
|
30
|
+
from .events import EventParser, ParsedEvent, ProtegeEvent
|
|
31
|
+
from .status import NO_RECORD, AreaStatus, DoorStatus, InputStatus, OutputStatus
|
|
32
|
+
|
|
33
|
+
__version__ = "0.1.0"
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
"NO_RECORD",
|
|
37
|
+
"PROTOCOL_AUTO",
|
|
38
|
+
"PROTOCOL_LEGACY",
|
|
39
|
+
"PROTOCOL_POST",
|
|
40
|
+
"TBL_AREAS",
|
|
41
|
+
"TBL_DOORS",
|
|
42
|
+
"TBL_INPUTS",
|
|
43
|
+
"TBL_INPUT_TYPES",
|
|
44
|
+
"TBL_OUTPUTS",
|
|
45
|
+
"TBL_TROUBLE_INPUTS",
|
|
46
|
+
"AreaStatus",
|
|
47
|
+
"DoorStatus",
|
|
48
|
+
"EventParser",
|
|
49
|
+
"InputStatus",
|
|
50
|
+
"LoginGuard",
|
|
51
|
+
"OutputStatus",
|
|
52
|
+
"ParsedEvent",
|
|
53
|
+
"ProtegeAuthError",
|
|
54
|
+
"ProtegeClient",
|
|
55
|
+
"ProtegeCommandError",
|
|
56
|
+
"ProtegeConnectionError",
|
|
57
|
+
"ProtegeError",
|
|
58
|
+
"ProtegeEvent",
|
|
59
|
+
"ProtegeSessionError",
|
|
60
|
+
"__version__",
|
|
61
|
+
"normalise_host",
|
|
62
|
+
]
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
"""Command-line tool: ``python -m aioprotegewx`` or ``aioprotegewx``.
|
|
2
|
+
|
|
3
|
+
Examples::
|
|
4
|
+
|
|
5
|
+
aioprotegewx status 192.168.1.10:7377 --username homeassistant --password ...
|
|
6
|
+
aioprotegewx events 192.168.1.10:7377 --username homeassistant --password ...
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import argparse
|
|
12
|
+
import asyncio
|
|
13
|
+
from collections.abc import Sequence
|
|
14
|
+
from dataclasses import asdict
|
|
15
|
+
import json
|
|
16
|
+
import logging
|
|
17
|
+
import sys
|
|
18
|
+
from typing import Any
|
|
19
|
+
|
|
20
|
+
import aiohttp
|
|
21
|
+
|
|
22
|
+
from . import ProtegeClient, ProtegeError
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _print(value: Any) -> None:
|
|
26
|
+
print(json.dumps(value, indent=2, default=str))
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
async def _run(args: argparse.Namespace) -> None:
|
|
30
|
+
async with aiohttp.ClientSession(cookie_jar=aiohttp.CookieJar(unsafe=True)) as session:
|
|
31
|
+
client = ProtegeClient(session, args.host, args.username, args.password)
|
|
32
|
+
try:
|
|
33
|
+
await client.login()
|
|
34
|
+
if args.command == "status":
|
|
35
|
+
_print(
|
|
36
|
+
{
|
|
37
|
+
"health": await client.health_values(),
|
|
38
|
+
"areas": {k: v.state for k, v in (await client.area_status()).items()},
|
|
39
|
+
"doors": {
|
|
40
|
+
k: {"lock": v.lock, "position": v.position}
|
|
41
|
+
for k, v in (await client.door_status()).items()
|
|
42
|
+
},
|
|
43
|
+
"inputs": {k: v.state for k, v in (await client.input_status()).items()},
|
|
44
|
+
}
|
|
45
|
+
)
|
|
46
|
+
else:
|
|
47
|
+
_print([asdict(event) for event in await client.events()])
|
|
48
|
+
finally:
|
|
49
|
+
# Always log out: the controller has a small session table.
|
|
50
|
+
await client.close()
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def main(argv: Sequence[str] | None = None) -> None:
|
|
54
|
+
"""Run the command-line tool."""
|
|
55
|
+
parser = argparse.ArgumentParser(prog="aioprotegewx", description=__doc__.splitlines()[0])
|
|
56
|
+
parser.add_argument("-v", "--verbose", action="store_true", help="debug logging")
|
|
57
|
+
sub = parser.add_subparsers(dest="command", required=True)
|
|
58
|
+
for name, text in (
|
|
59
|
+
("status", "read areas, doors, inputs and health"),
|
|
60
|
+
("events", "read the newest page of the event log"),
|
|
61
|
+
):
|
|
62
|
+
cmd = sub.add_parser(name, help=text)
|
|
63
|
+
cmd.add_argument("host", help="address and port, e.g. 192.168.1.10:7377")
|
|
64
|
+
cmd.add_argument("--username", required=True)
|
|
65
|
+
cmd.add_argument("--password", required=True)
|
|
66
|
+
args = parser.parse_args(argv)
|
|
67
|
+
logging.basicConfig(level=logging.DEBUG if args.verbose else logging.WARNING)
|
|
68
|
+
try:
|
|
69
|
+
asyncio.run(_run(args))
|
|
70
|
+
except ProtegeError as err:
|
|
71
|
+
print(f"error: {err}", file=sys.stderr)
|
|
72
|
+
sys.exit(1)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
if __name__ == "__main__": # pragma: no cover
|
|
76
|
+
main()
|