zeptrionair-api 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.
Files changed (42) hide show
  1. zeptrionair_api-0.1.0/.gitignore +32 -0
  2. zeptrionair_api-0.1.0/CHANGELOG.md +30 -0
  3. zeptrionair_api-0.1.0/LICENSE +21 -0
  4. zeptrionair_api-0.1.0/PKG-INFO +151 -0
  5. zeptrionair_api-0.1.0/README.md +120 -0
  6. zeptrionair_api-0.1.0/docs/protocol.md +209 -0
  7. zeptrionair_api-0.1.0/pyproject.toml +106 -0
  8. zeptrionair_api-0.1.0/src/zeptrionair_api/__init__.py +69 -0
  9. zeptrionair_api-0.1.0/src/zeptrionair_api/_version.py +24 -0
  10. zeptrionair_api-0.1.0/src/zeptrionair_api/capture.py +194 -0
  11. zeptrionair_api-0.1.0/src/zeptrionair_api/cli.py +425 -0
  12. zeptrionair_api-0.1.0/src/zeptrionair_api/const.py +102 -0
  13. zeptrionair_api-0.1.0/src/zeptrionair_api/device.py +379 -0
  14. zeptrionair_api-0.1.0/src/zeptrionair_api/discovery.py +94 -0
  15. zeptrionair_api-0.1.0/src/zeptrionair_api/events.py +209 -0
  16. zeptrionair_api-0.1.0/src/zeptrionair_api/exceptions.py +33 -0
  17. zeptrionair_api-0.1.0/src/zeptrionair_api/models.py +181 -0
  18. zeptrionair_api-0.1.0/src/zeptrionair_api/parsing.py +307 -0
  19. zeptrionair_api-0.1.0/src/zeptrionair_api/py.typed +0 -0
  20. zeptrionair_api-0.1.0/src/zeptrionair_api/testing/__init__.py +5 -0
  21. zeptrionair_api-0.1.0/src/zeptrionair_api/testing/fake_device.py +530 -0
  22. zeptrionair_api-0.1.0/tests/conftest.py +65 -0
  23. zeptrionair_api-0.1.0/tests/fixtures/README.md +53 -0
  24. zeptrionair_api-0.1.0/tests/fixtures/devices/device_01/responses.json +57 -0
  25. zeptrionair_api-0.1.0/tests/fixtures/devices/device_02/responses.json +57 -0
  26. zeptrionair_api-0.1.0/tests/fixtures/devices/device_03/responses.json +57 -0
  27. zeptrionair_api-0.1.0/tests/fixtures/devices/device_04/responses.json +57 -0
  28. zeptrionair_api-0.1.0/tests/fixtures/devices/device_05/responses.json +57 -0
  29. zeptrionair_api-0.1.0/tests/fixtures/devices/device_06/responses.json +57 -0
  30. zeptrionair_api-0.1.0/tests/fixtures/devices/device_07/responses.json +57 -0
  31. zeptrionair_api-0.1.0/tests/fixtures/devices/device_08/responses.json +57 -0
  32. zeptrionair_api-0.1.0/tests/fixtures/devices/index.json +186 -0
  33. zeptrionair_api-0.1.0/tests/fixtures/ws/cover_long_travel.jsonl +9 -0
  34. zeptrionair_api-0.1.0/tests/fixtures/ws/cover_wall_down_up_selfstop.jsonl +10 -0
  35. zeptrionair_api-0.1.0/tests/fixtures/ws/light_wall_keys.jsonl +13 -0
  36. zeptrionair_api-0.1.0/tests/fixtures/ws/smartbutton_remote.jsonl +3 -0
  37. zeptrionair_api-0.1.0/tests/test_capture.py +85 -0
  38. zeptrionair_api-0.1.0/tests/test_cli.py +246 -0
  39. zeptrionair_api-0.1.0/tests/test_device.py +267 -0
  40. zeptrionair_api-0.1.0/tests/test_discovery.py +119 -0
  41. zeptrionair_api-0.1.0/tests/test_events.py +217 -0
  42. zeptrionair_api-0.1.0/tests/test_parsing.py +275 -0
@@ -0,0 +1,32 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .eggs/
8
+
9
+ # Virtual environments
10
+ .venv/
11
+ venv/
12
+
13
+ # Tooling caches
14
+ .pytest_cache/
15
+ .mypy_cache/
16
+ .ruff_cache/
17
+ .coverage
18
+ .coverage.*
19
+ coverage.xml
20
+ htmlcov/
21
+
22
+ # Editors / OS
23
+ .vscode/
24
+ .idea/
25
+ .DS_Store
26
+ Thumbs.db
27
+
28
+ # Local fixture captures that haven't been reviewed (review, then move into tests/fixtures/)
29
+ captures/
30
+
31
+ # Generated by hatch-vcs
32
+ src/zeptrionair_api/_version.py
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ All notable changes are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
4
+
5
+ ## [Unreleased]
6
+
7
+ ## [0.1.0]
8
+
9
+ ### Added
10
+ - `ZeptrionDevice`: async client for one zApp device:
11
+ - identification, channels, states, RSSI and MAC;
12
+ - Smartfront key layout, sensors and LEDs;
13
+ - capability probing;
14
+ - channel commands (single and multi-channel), with validation;
15
+ - channel descriptor updates;
16
+ - LED background colours.
17
+ - Event stream:
18
+ - WebSocket `/zrap/ws`, with `chnotify` long-poll fallback;
19
+ - automatic reconnection with backoff;
20
+ - HTTP liveness checks (the device doesn't answer WebSocket pings);
21
+ - decoded key events.
22
+ - Lenient XML/JSON parsing that tolerates the quirks in the official documentation.
23
+ - mDNS discovery (`_zapp._tcp`, plus `_http._tcp` filtered to `zapp-*`).
24
+ - `zeptrion` CLI: `discover`, `info`, `channels`, `state`, `on`/`off`/`toggle`, `open`/`close`/`stop`, `move`, `dim`, `scene`, `send`, `rename`, `watch`, `dump`.
25
+ - Anonymised fixture capture (`zeptrion dump`, `python -m zeptrionair_api.capture`).
26
+ - Simulated device for tests (`zeptrionair_api.testing.FakeZeptrionDevice`).
27
+ - Protocol reference `docs/protocol.md`.
28
+
29
+ [Unreleased]: https://github.com/diaznet/zeptrionair-api/compare/v0.1.0...HEAD
30
+ [0.1.0]: https://github.com/diaznet/zeptrionair-api/releases/tag/v0.1.0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jeremy Diaz
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,151 @@
1
+ Metadata-Version: 2.5
2
+ Name: zeptrionair-api
3
+ Version: 0.1.0
4
+ Summary: Async Python library and CLI for Feller zeptrionAir devices (local HTTP/WebSocket API)
5
+ Project-URL: Homepage, https://github.com/diaznet/zeptrionair-api
6
+ Project-URL: Documentation, https://github.com/diaznet/zeptrionair-api/blob/main/docs/protocol.md
7
+ Project-URL: Issues, https://github.com/diaznet/zeptrionair-api/issues
8
+ Project-URL: Changelog, https://github.com/diaznet/zeptrionair-api/blob/main/CHANGELOG.md
9
+ Author-email: Jeremy Diaz <jd@diaznet.fr>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: asyncio,feller,home-automation,zapp,zeptrion,zeptrionair
13
+ Classifier: Development Status :: 3 - Alpha
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: Typing :: Typed
23
+ Requires-Python: >=3.12
24
+ Requires-Dist: aiohttp>=3.11
25
+ Provides-Extra: cli
26
+ Requires-Dist: typer>=0.12; extra == 'cli'
27
+ Requires-Dist: zeroconf>=0.132; extra == 'cli'
28
+ Provides-Extra: discovery
29
+ Requires-Dist: zeroconf>=0.132; extra == 'discovery'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # zeptrionair-api
33
+
34
+ [![CI](https://github.com/diaznet/zeptrionair-api/actions/workflows/ci.yml/badge.svg)](https://github.com/diaznet/zeptrionair-api/actions/workflows/ci.yml)
35
+ [![PyPI](https://img.shields.io/pypi/v/zeptrionair-api)](https://pypi.org/project/zeptrionair-api/)
36
+
37
+ Async Python library and command-line tool for **Feller zeptrionAir** WLAN devices (zApp: 3340-2-x and 3340-4-x), using their local HTTP and WebSocket interface. No cloud and no account needed.
38
+
39
+ It is the library behind the Home Assistant integration [ha-zeptrionair](https://github.com/diaznet/ha-zeptrionair).
40
+
41
+ ## Features
42
+
43
+ - Read device info, channels (with their category: light, dimmer, blind, awning) and states.
44
+ - Control lights, dimmers and covers: on/off/toggle, open/close/stop, timed moves and dims, and scenes.
45
+ - **Real-time events** over the device WebSocket: channel changes, plus wall-key presses with their decoded function. Falls back to the `chnotify` long poll, and reconnects automatically.
46
+ - Smartfront: key layout, temperature/light/humidity sensors, LED background colours.
47
+ - mDNS discovery.
48
+ - `zeptrion` CLI for scripting and debugging.
49
+ - A simulated device (`zeptrionair_api.testing`) for your own tests.
50
+
51
+ ## Install
52
+
53
+ ```bash
54
+ pip install zeptrionair-api # library only
55
+ pip install "zeptrionair-api[cli]" # + the zeptrion command and mDNS discovery
56
+ ```
57
+
58
+ Requires Python 3.12 or newer.
59
+
60
+ ## Library
61
+
62
+ ```python
63
+ import asyncio
64
+ from zeptrionair_api import ChannelUpdate, KeyEvent, ZeptrionDevice
65
+
66
+
67
+ async def main() -> None:
68
+ async with ZeptrionDevice("zapp-12345678.local") as device:
69
+ info = await device.identify()
70
+ print(info.serial, info.type, info.sw_version)
71
+
72
+ for channel in await device.channels():
73
+ if channel.in_use:
74
+ print(channel.number, channel.category, channel.name)
75
+
76
+ await device.turn_on(1) # light
77
+ await device.close_cover(2) # blind: close fully
78
+ await device.move_open(2, 1500) # blind: move up for 1.5 s
79
+
80
+ async for event in device.events(): # runs until you break
81
+ if isinstance(event, ChannelUpdate):
82
+ print("channel", event.channel, "=", event.value)
83
+ elif isinstance(event, KeyEvent) and event.pressed:
84
+ print("key", event.key, event.function)
85
+
86
+
87
+ asyncio.run(main())
88
+ ```
89
+
90
+ Notes:
91
+ - For covers, a channel value of **100 means the motor is running and 0 means it stopped**. The devices don't report position.
92
+ - Pass your own `aiohttp.ClientSession` with `ZeptrionDevice(host, session=...)` to share connections.
93
+ - At most 2 HTTP requests run at a time per device, because the device is a small embedded web server. GET requests are retried; commands (POST) never are.
94
+
95
+ ## CLI
96
+
97
+ ```text
98
+ zeptrion discover # find devices (mDNS)
99
+ zeptrion info zapp-12345678.local # identification, features, key layout, sensors
100
+ zeptrion channels zapp-12345678.local
101
+ zeptrion state zapp-12345678.local
102
+ zeptrion on|off|toggle HOST CH
103
+ zeptrion open|close|stop HOST CH
104
+ zeptrion move HOST CH open|close [--ms 1500]
105
+ zeptrion dim HOST CH up|down [--ms 800]
106
+ zeptrion scene HOST CH recall|store|delete N
107
+ zeptrion send HOST CH move_open_2000 # any valid raw command
108
+ zeptrion rename HOST CH --name "Kitchen" --group "Ground floor"
109
+ zeptrion watch HOST [HOST ...] [--json] # live channel changes and key presses
110
+ zeptrion dump OUTDIR HOST [HOST ...] # anonymised fixtures for bug reports
111
+ ```
112
+
113
+ Most commands accept `--json`. Exit codes: 0 = success, 1 = device or network error, 2 = invalid input.
114
+
115
+ ## Documentation
116
+
117
+ - [docs/protocol.md](docs/protocol.md): the maintained protocol reference, including the WebSocket (which Feller never documented) and Smartfront key decoding.
118
+ - [docs/10ZEPAPIE1612.pdf](docs/10ZEPAPIE1612.pdf): Feller's original API document (v1.0).
119
+
120
+ ## Supported hardware
121
+
122
+ | | Status |
123
+ |---|---|
124
+ | 3340-2-B, firmware 01.08.28, on/off lights and blinds, Smartfront | tested on real devices |
125
+ | 3340-2-A, 3340-4-A/B, dimmers, awnings, sensor fronts, firmware before 01.08 | expected to work, **untested** |
126
+
127
+ If you have untested hardware, please capture anonymised fixtures and open an issue or PR:
128
+
129
+ ```bash
130
+ zeptrion dump captures/ <host> [<host> ...]
131
+ # or, without the CLI extra:
132
+ python -m zeptrionair_api.capture captures/ <host> [<host> ...]
133
+ ```
134
+
135
+ Only GET requests are sent. Serial numbers, MAC addresses, channel and room names are replaced, and hostnames and IPs are never written. Please still review the files before sharing them.
136
+
137
+ ## Development
138
+
139
+ ```bash
140
+ uv sync
141
+ uv run pytest --cov
142
+ uv run ruff check . && uv run ruff format --check . && uv run mypy src
143
+ ```
144
+
145
+ ## Disclaimer
146
+
147
+ Not affiliated with or endorsed by Feller AG. "zeptrion" and "zeptrionAIR" are trademarks of Feller AG. The WebSocket endpoint was first used by [heldchen/ha-zeptrion-air](https://github.com/heldchen/ha-zeptrion-air) (MIT).
148
+
149
+ ## License
150
+
151
+ MIT
@@ -0,0 +1,120 @@
1
+ # zeptrionair-api
2
+
3
+ [![CI](https://github.com/diaznet/zeptrionair-api/actions/workflows/ci.yml/badge.svg)](https://github.com/diaznet/zeptrionair-api/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/zeptrionair-api)](https://pypi.org/project/zeptrionair-api/)
5
+
6
+ Async Python library and command-line tool for **Feller zeptrionAir** WLAN devices (zApp: 3340-2-x and 3340-4-x), using their local HTTP and WebSocket interface. No cloud and no account needed.
7
+
8
+ It is the library behind the Home Assistant integration [ha-zeptrionair](https://github.com/diaznet/ha-zeptrionair).
9
+
10
+ ## Features
11
+
12
+ - Read device info, channels (with their category: light, dimmer, blind, awning) and states.
13
+ - Control lights, dimmers and covers: on/off/toggle, open/close/stop, timed moves and dims, and scenes.
14
+ - **Real-time events** over the device WebSocket: channel changes, plus wall-key presses with their decoded function. Falls back to the `chnotify` long poll, and reconnects automatically.
15
+ - Smartfront: key layout, temperature/light/humidity sensors, LED background colours.
16
+ - mDNS discovery.
17
+ - `zeptrion` CLI for scripting and debugging.
18
+ - A simulated device (`zeptrionair_api.testing`) for your own tests.
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ pip install zeptrionair-api # library only
24
+ pip install "zeptrionair-api[cli]" # + the zeptrion command and mDNS discovery
25
+ ```
26
+
27
+ Requires Python 3.12 or newer.
28
+
29
+ ## Library
30
+
31
+ ```python
32
+ import asyncio
33
+ from zeptrionair_api import ChannelUpdate, KeyEvent, ZeptrionDevice
34
+
35
+
36
+ async def main() -> None:
37
+ async with ZeptrionDevice("zapp-12345678.local") as device:
38
+ info = await device.identify()
39
+ print(info.serial, info.type, info.sw_version)
40
+
41
+ for channel in await device.channels():
42
+ if channel.in_use:
43
+ print(channel.number, channel.category, channel.name)
44
+
45
+ await device.turn_on(1) # light
46
+ await device.close_cover(2) # blind: close fully
47
+ await device.move_open(2, 1500) # blind: move up for 1.5 s
48
+
49
+ async for event in device.events(): # runs until you break
50
+ if isinstance(event, ChannelUpdate):
51
+ print("channel", event.channel, "=", event.value)
52
+ elif isinstance(event, KeyEvent) and event.pressed:
53
+ print("key", event.key, event.function)
54
+
55
+
56
+ asyncio.run(main())
57
+ ```
58
+
59
+ Notes:
60
+ - For covers, a channel value of **100 means the motor is running and 0 means it stopped**. The devices don't report position.
61
+ - Pass your own `aiohttp.ClientSession` with `ZeptrionDevice(host, session=...)` to share connections.
62
+ - At most 2 HTTP requests run at a time per device, because the device is a small embedded web server. GET requests are retried; commands (POST) never are.
63
+
64
+ ## CLI
65
+
66
+ ```text
67
+ zeptrion discover # find devices (mDNS)
68
+ zeptrion info zapp-12345678.local # identification, features, key layout, sensors
69
+ zeptrion channels zapp-12345678.local
70
+ zeptrion state zapp-12345678.local
71
+ zeptrion on|off|toggle HOST CH
72
+ zeptrion open|close|stop HOST CH
73
+ zeptrion move HOST CH open|close [--ms 1500]
74
+ zeptrion dim HOST CH up|down [--ms 800]
75
+ zeptrion scene HOST CH recall|store|delete N
76
+ zeptrion send HOST CH move_open_2000 # any valid raw command
77
+ zeptrion rename HOST CH --name "Kitchen" --group "Ground floor"
78
+ zeptrion watch HOST [HOST ...] [--json] # live channel changes and key presses
79
+ zeptrion dump OUTDIR HOST [HOST ...] # anonymised fixtures for bug reports
80
+ ```
81
+
82
+ Most commands accept `--json`. Exit codes: 0 = success, 1 = device or network error, 2 = invalid input.
83
+
84
+ ## Documentation
85
+
86
+ - [docs/protocol.md](docs/protocol.md): the maintained protocol reference, including the WebSocket (which Feller never documented) and Smartfront key decoding.
87
+ - [docs/10ZEPAPIE1612.pdf](docs/10ZEPAPIE1612.pdf): Feller's original API document (v1.0).
88
+
89
+ ## Supported hardware
90
+
91
+ | | Status |
92
+ |---|---|
93
+ | 3340-2-B, firmware 01.08.28, on/off lights and blinds, Smartfront | tested on real devices |
94
+ | 3340-2-A, 3340-4-A/B, dimmers, awnings, sensor fronts, firmware before 01.08 | expected to work, **untested** |
95
+
96
+ If you have untested hardware, please capture anonymised fixtures and open an issue or PR:
97
+
98
+ ```bash
99
+ zeptrion dump captures/ <host> [<host> ...]
100
+ # or, without the CLI extra:
101
+ python -m zeptrionair_api.capture captures/ <host> [<host> ...]
102
+ ```
103
+
104
+ Only GET requests are sent. Serial numbers, MAC addresses, channel and room names are replaced, and hostnames and IPs are never written. Please still review the files before sharing them.
105
+
106
+ ## Development
107
+
108
+ ```bash
109
+ uv sync
110
+ uv run pytest --cov
111
+ uv run ruff check . && uv run ruff format --check . && uv run mypy src
112
+ ```
113
+
114
+ ## Disclaimer
115
+
116
+ Not affiliated with or endorsed by Feller AG. "zeptrion" and "zeptrionAIR" are trademarks of Feller AG. The WebSocket endpoint was first used by [heldchen/ha-zeptrion-air](https://github.com/heldchen/ha-zeptrion-air) (MIT).
117
+
118
+ ## License
119
+
120
+ MIT
@@ -0,0 +1,209 @@
1
+ # zeptrionAir local protocol
2
+
3
+ This document describes the local HTTP and WebSocket interface of Feller zeptrionAir WLAN devices ("zApp"). It combines:
4
+
5
+ - **[PDF]** Feller's official "zApp API" document `10.ZEPAPI-E.1612` (Version 1.0), in this folder as `10ZEPAPIE1612.pdf`;
6
+ - **[OBS]** behaviour observed on real devices (3340-2-B, firmware 01.08.28, captured 2026-11-02), with fixtures in `tests/fixtures/`;
7
+ - **[HEUR]** inferences drawn from those observations. These may not hold on other hardware.
8
+
9
+ The WebSocket endpoint and its message format are **not documented by Feller** at all; everything about them is [OBS].
10
+
11
+ > Feller has discontinued zeptrion/zeptrionAIR. No newer official API document is known.
12
+
13
+ ---
14
+
15
+ ## 1. Devices
16
+
17
+ | Product | Type | Channels | Notes |
18
+ |---|---|---|---|
19
+ | WLAN-Nebenstelle 4K | 3340-4-A / 3340-4-B (V2) | 4 | untested |
20
+ | WLAN-Zwischenmodul 2K | 3340-2-A / 3340-2-B (V2) | 2 | 3340-2-B tested |
21
+
22
+ [PDF] A Smartfront (front plate with keys, RGB LEDs and optional sensors) can be fitted on the 3340-2-B.
23
+
24
+ ## 2. Transport
25
+
26
+ - HTTP on port 80, **no authentication**, no TLS.
27
+ - Base paths: `/zrap/…` (XML) and `/zapi/…` (JSON).
28
+ - **Reads:** `GET`, response `text/xml`. [OBS] The whole document is on a single line, with an XML declaration of `encoding="US-ASCII"` or `"UTF-8"`. [PDF] Special characters are escaped as XML entities (`&amp;`, `&lt;`, …).
29
+ - **Writes:** `POST` with an `application/x-www-form-urlencoded` body, percent-encoded UTF-8 (`name=K%C3%BCche`). [PDF] Success is **HTTP 302**; clients must not follow the redirect.
30
+ - **Errors:** [PDF] HTTP status ≥ 400. [OBS] An unknown path returns 404 with a small HTML page.
31
+ - [OBS] Responses take about 30–330 ms. The device is a small embedded server, so keep concurrent requests low (≤ 2 per device recommended).
32
+ - [PDF] The examples in the PDF contain malformed XML (`</hnotify>`, `<chdes>` used as a closing tag). [OBS] Real responses were well-formed, but parsers should still be lenient.
33
+
34
+ ## 3. Discovery
35
+
36
+ - **mDNS:** [PDF] firmware ≥ 01.08.00 registers `_zapp._tcp`, and for backward compatibility also `_http._tcp`. Older firmware registers `_http._tcp` only.
37
+ - Instance and host name: `zapp-<serial>` (`zapp-YYWWNNNN.local`, where YY = production year, WW = production week, NNNN = sequence number).
38
+ - [OBS] TXT records: `type=3340-2-B`, `sw=01.08.28`, and an empty `path`.
39
+ - [OBS] **Unreliable:** one of 8 devices never answered an mDNS browse within 30 s, although it answered HTTP. Always provide manual host entry.
40
+ - [PDF] The hostname equals the factory SSID (`zApp-<serial>`), but case-insensitive.
41
+ - [PDF] In access-point mode (factory default) the device is at `192.168.0.1`.
42
+
43
+ ## 4. Endpoints
44
+
45
+ ### 4.1 `GET /zrap/id`: device identification
46
+ ```xml
47
+ <id><hw>01.05.02</hw><sn>99990001</sn><sys>ZEPTRION</sys><type>3340-2-B</type><oen>zApp</oen>
48
+ <sw>01.08.28 (Jun 1 2018 09:13:39)</sw><boot>01.04.02 (Apr 13 2018 10:08:29)</boot></id>
49
+ ```
50
+ - `sn` is the serial number, unique per device, and matches the hostname.
51
+ - Version format: `MM.mm.bb<other text>`, each part 2 digits; higher numbers are newer. A single attribute can be read with `/zrap/id/<attr>`.
52
+
53
+ ### 4.2 `GET|POST /zrap/chdes[/chN[/attr]]`: channel descriptors
54
+ ```xml
55
+ <chdes><ch1><name>Light 1</name><group>Room A</group><icon>1492</icon><type>00</type><cat>1</cat></ch1>…</chdes>
56
+ ```
57
+ | Attribute | Max bytes (UTF-8) | Meaning |
58
+ |---|---|---|
59
+ | `name` | 32 | channel name |
60
+ | `group` | 32 | room / group |
61
+ | `icon` | 24 | icon ID used by the Feller app |
62
+ | `type` | 4 | free use |
63
+ | `cat` | 4 | **channel category**, see below |
64
+
65
+ - [PDF] These are free-form fields for client apps.
66
+ - [OBS] The Feller app stores its channel configuration in them, and `cat` is the field that reliably identifies what is connected:
67
+
68
+ | `cat` | Meaning | Source |
69
+ |---|---|---|
70
+ | `1` | on/off light | OBS |
71
+ | `3` | dimmer | HEUR (from other projects, untested) |
72
+ | `5` | blind / shade / shutter | OBS |
73
+ | `6` | awning (Markise) | HEUR (from other projects, untested) |
74
+ | `00`, `-1` | unused channel | OBS; the name defaults to `zApp-<serial> (<n>)` |
75
+
76
+ To write: `POST /zrap/chdes/ch1` with body `name=Kitchen&group=First+floor`.
77
+
78
+ ### 4.3 `GET /zrap/chscan[/chN]`: channel state
79
+ ```xml
80
+ <chscan><ch1><val>0</val></ch1><ch2><val>100</val></ch2></chscan>
81
+ ```
82
+ - Lights: 0 = off, 100 = on. Dimmers: 0–100 (HEUR).
83
+ - [PDF] says "-1 for blinds". [OBS] On 01.08.28, covers report **0 = motor stopped, 100 = motor running**. See section 5.
84
+
85
+ ### 4.4 `GET /zrap/chnotify`: long poll
86
+ - [PDF] Same format as `chscan` (root element `<chnotify>`).
87
+ - The request is held open until a channel changes, or for at most 30 s; then the client re-requests.
88
+ - Use it as a fallback push channel when the WebSocket isn't available.
89
+ - [OBS] It works on 01.08.28 alongside the WebSocket; a change arrived about 140 ms after the command.
90
+
91
+ ### 4.5 `POST /zrap/chctrl/chN` and `POST /zrap/chctrl`: control
92
+ Single channel: `POST /zrap/chctrl/ch1` with `cmd=on`.
93
+ Several channels in one request: `POST /zrap/chctrl` with `cmd1=on&cmd2=off`.
94
+
95
+ | `cmd` | Effect |
96
+ |---|---|
97
+ | `on`, `off`, `toggle` | light on (100 %), off, or toggle |
98
+ | `dim_up`, `dim_down` | start dimming (`stop` to hold) |
99
+ | `open`, `close` | move the cover fully open / closed |
100
+ | `move_open`, `move_close` | start moving the cover (`stop` to hold) |
101
+ | `stop` | stop dimming or moving |
102
+ | `recall_s1` … `recall_s4` | recall scene 1–4 |
103
+ | `store_s1` … `store_s4` | store the current state as scene 1–4 |
104
+ | `delete_s1` … `delete_s4` | delete scene 1–4 |
105
+ | `dim_up_<t>`, `dim_down_<t>`, `dim_<t>` | dim for *t* ms, then stop (t = 100–32000) |
106
+ | `move_open_<t>`, `move_close_<t>` | move for *t* ms, then stop (t = 100–32000) |
107
+
108
+ ### 4.6 `GET /zrap/rssi`: Wi-Fi signal
109
+ `<rssi><dbm>-64</dbm></rssi>`. [PDF] Below −75 dBm the connection is unreliable.
110
+
111
+ ### 4.7 `GET /zrap/net/mac`: MAC address
112
+ `<mac>02:00:00:00:00:01</mac>`
113
+
114
+ > ⚠️ **Never request `/zrap/net` as a whole.** [PDF] It includes the Wi-Fi password `pw` while the device is in access-point mode. Read only `/zrap/net/mac`.
115
+
116
+ ### 4.8 Smartfront: `/zapi/smartfront/*` (JSON)
117
+ Present only when a Smartfront is fitted; otherwise the endpoints return 404.
118
+
119
+ **`GET /zapi/smartfront/id`**
120
+ ```json
121
+ {"btfu":"0,0,1000,1000,8501,8602,4501,4602","sw":"01.01.08","hw":"01.00.00","sys":"ZEPTRION","sid":"1","type":"920-3302.36.ZU"}
122
+ ```
123
+ `btfu` describes the key functions; see section 6.
124
+
125
+ **`GET /zapi/smartfront/sensors`**: [OBS] the path is **plural**. The PDF's `/zapi/smartfront/sensor` returns 404.
126
+ ```json
127
+ {"temp":"35.44C","lux":"none","hum":"none"}
128
+ ```
129
+ - Values are strings with units; `"none"` means the sensor isn't present.
130
+ - [OBS] Every front tested reports `temp`. [PDF] The temperature is affected by how the device is installed. [OBS] Readings around 35 °C suggest it measures the module's own heat.
131
+
132
+ **`GET|POST /zapi/smartfront/led`**
133
+ ```json
134
+ [{"id":1,"on":false,"rgb":"#000000","effect":"#fffff","bg":"#000020"}, …]
135
+ ```
136
+ - [OBS] The field is named `effect`; the PDF says `effects`.
137
+ - [PDF] Only `bg` (background colour) may be changed. `on`, `rgb` and `effect` are managed by the device itself.
138
+ - Set: `POST` a JSON array, e.g. `[{"id":2,"bg":"#220000"}]`.
139
+
140
+ **Smartbutton programming** (`/zapi/smartbt/prgm|prgn|prgs`): [PDF] programs a key to send HTTP requests. [OBS] `GET /zapi/smartbt/prgm` returns `{"on":false,"ntm":60}` on most fronts, but **404 on front type `920-3305.36.ZZ`**, so probe before use.
141
+
142
+ ### 4.9 Other endpoints (not used by this library)
143
+ | Endpoint | Purpose |
144
+ |---|---|
145
+ | `/zrap/sys` | `POST cmd=reboot` / `factory-default` / `network-default`. **Destructive.** |
146
+ | `/zrap/net`, `/zrap/netscan` | Wi-Fi provisioning (see the warning in 4.7) |
147
+ | `/zrap/loc` | free-form location string |
148
+ | `/zrap/date`, `/zrap/ntp` | clock |
149
+ | `/zrap/scheduler` | on-device timers |
150
+
151
+ ## 5. WebSocket `ws://<host>/zrap/ws` [OBS]
152
+
153
+ **Undocumented by Feller.**
154
+ - No sub-protocol and no authentication. The server sends JSON text frames; no client messages are needed.
155
+ - Several clients can be connected at the same time, and each receives every frame. Two parallel connections were tested.
156
+ - No frames were seen while idle for 150 s, so a client can't use silence to detect a dead connection.
157
+ - **The device does not answer WebSocket pings.** A client heartbeat (e.g. aiohttp `heartbeat=`) makes the client close the connection after the first unanswered ping. Check liveness with a cheap HTTP request instead (`/zrap/rssi`).
158
+ - Latency observed: a `chctrl` POST takes about 30 ms, and the matching `eid1` arrives 30–50 ms after the POST returns. The same change via `chnotify` arrives after about 140 ms.
159
+
160
+ ### 5.1 `eid1`: channel value changed
161
+ ```json
162
+ {"eid1":{"ch":1,"val":100}}
163
+ ```
164
+ - Lights: 0 / 100.
165
+ - **Covers: 100 = motor started, 0 = motor stopped.** This happens when a command arrives, when a wall key is pressed, and when the motor stops by itself at its end position.
166
+ - The direction is **not** included. It has to come from the command sent or from the key that was pressed (section 6).
167
+
168
+ ### 5.2 `eid2`: key state
169
+ ```json
170
+ {"eid2":{"bta":"......P.."}}
171
+ ```
172
+ - 9 characters: `P` = pressed, `.` = not pressed.
173
+ - When the key is released, a frame with all dots follows.
174
+ - Position *i* (0-based) is key *i+1*. The meaning of position 9 is unknown.
175
+
176
+ ### 5.3 Typical sequence for a wall press
177
+ ```
178
+ eid2 bta ".......P." press key 8
179
+ eid2 bta "........." release (~0.1–0.3 s later)
180
+ eid1 ch1 val 100 resulting state change
181
+ ```
182
+ A Smartbutton press produces `eid2` on the device that was pressed, and `eid1` on whatever device its programmed request targets, which may be a different device.
183
+
184
+ ## 6. Key functions (`btfu`) [HEUR]
185
+
186
+ `btfu` from `/zapi/smartfront/id` is a list of 8 comma-separated codes, one for each key 1–8 (key *k* = `bta` position *k−1*).
187
+
188
+ | Code | Meaning |
189
+ |---|---|
190
+ | `0` | key unused |
191
+ | `1000` | Smartbutton: sends its programmed HTTP request(s) |
192
+ | `XYZZ` | local channel function. **X** = channel bitmask (8 = ch1, 4 = ch2; presumably 2 = ch3, 1 = ch4). **Y** = direction: 5 = up/on, 6 = down/off. **ZZ** = unknown (01 for up/on, 02 for down/off in all samples). |
193
+
194
+ Observed layouts:
195
+
196
+ | Device | `btfu` | Keys |
197
+ |---|---|---|
198
+ | 2× light | `0,0,1000,1000,8501,8602,4501,4602` | 3–4 Smartbutton, 5/6 ch1 on/off, 7/8 ch2 on/off |
199
+ | 1× cover | `0,0,1000,1000,0,0,8501,8602` | 3–4 Smartbutton, 7/8 ch1 up/down |
200
+ | 2× cover | `0,0,1000,1000,8501,8602,4501,4602` | 3–4 Smartbutton, 5/6 ch1 up/down, 7/8 ch2 up/down |
201
+
202
+ Behaviour observed on covers: pressing the opposite direction while the motor runs **stops** it, and pressing the same direction again starts moving.
203
+
204
+ Treat unknown codes as raw key events. Without a Smartfront, wall-key direction is unknown.
205
+
206
+ ## 7. Security notes
207
+
208
+ - The local API has no authentication: anyone on the network can control the devices and rename channels.
209
+ - Never fetch `/zrap/net` (it can contain the Wi-Fi password); never call `/zrap/sys`.
@@ -0,0 +1,106 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.26", "hatch-vcs>=0.4"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "zeptrionair-api"
7
+ dynamic = ["version"]
8
+ description = "Async Python library and CLI for Feller zeptrionAir devices (local HTTP/WebSocket API)"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Jeremy Diaz", email = "jd@diaznet.fr" }]
13
+ requires-python = ">=3.12"
14
+ keywords = ["feller", "zeptrion", "zeptrionair", "zapp", "home-automation", "asyncio"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Framework :: AsyncIO",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: OS Independent",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Programming Language :: Python :: 3.14",
24
+ "Topic :: Home Automation",
25
+ "Typing :: Typed",
26
+ ]
27
+ dependencies = ["aiohttp>=3.11"]
28
+
29
+ [project.optional-dependencies]
30
+ discovery = ["zeroconf>=0.132"]
31
+ cli = ["typer>=0.12", "zeroconf>=0.132"]
32
+
33
+ [project.scripts]
34
+ zeptrion = "zeptrionair_api.cli:main"
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/diaznet/zeptrionair-api"
38
+ Documentation = "https://github.com/diaznet/zeptrionair-api/blob/main/docs/protocol.md"
39
+ Issues = "https://github.com/diaznet/zeptrionair-api/issues"
40
+ Changelog = "https://github.com/diaznet/zeptrionair-api/blob/main/CHANGELOG.md"
41
+
42
+ [dependency-groups]
43
+ dev = [
44
+ "mypy>=1.13",
45
+ "pytest>=8.3",
46
+ "pytest-asyncio>=1.0",
47
+ "pytest-cov>=6.0",
48
+ "ruff>=0.8",
49
+ "typer>=0.12",
50
+ "zeroconf>=0.132",
51
+ ]
52
+
53
+ [tool.hatch.version]
54
+ source = "vcs"
55
+
56
+ [tool.hatch.version.raw-options]
57
+ # PyPI/TestPyPI reject local versions ("+g1234abc"), so leave them out.
58
+ local_scheme = "no-local-version"
59
+
60
+ [tool.hatch.build.hooks.vcs]
61
+ version-file = "src/zeptrionair_api/_version.py"
62
+
63
+ [tool.hatch.build.targets.wheel]
64
+ packages = ["src/zeptrionair_api"]
65
+
66
+ [tool.hatch.build.targets.sdist]
67
+ include = ["src", "tests", "docs/protocol.md", "README.md", "LICENSE", "CHANGELOG.md"]
68
+
69
+ [tool.pytest.ini_options]
70
+ testpaths = ["tests"]
71
+ asyncio_mode = "auto"
72
+ asyncio_default_fixture_loop_scope = "function"
73
+ addopts = "--strict-markers"
74
+
75
+ [tool.coverage.run]
76
+ source = ["zeptrionair_api"]
77
+ branch = true
78
+ omit = ["*/_version.py"]
79
+
80
+ [tool.coverage.report]
81
+ fail_under = 90
82
+ show_missing = true
83
+ exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError", "if __name__ == .__main__.:"]
84
+
85
+ [tool.ruff]
86
+ line-length = 100
87
+ target-version = "py312"
88
+ extend-exclude = ["src/zeptrionair_api/_version.py"]
89
+
90
+ [tool.ruff.lint]
91
+ select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "ASYNC", "PT", "C4", "RET", "N"]
92
+ # A per-request `timeout` argument is part of the public API here.
93
+ ignore = ["ASYNC109"]
94
+
95
+ [tool.ruff.lint.per-file-ignores]
96
+ # Polling helpers, blocking file reads and fake class registries are fine in tests.
97
+ "tests/**" = ["ASYNC110", "ASYNC240", "RUF012"]
98
+
99
+ [tool.mypy]
100
+ strict = true
101
+ python_version = "3.12"
102
+ exclude = ["build/", "dist/"]
103
+
104
+ [[tool.mypy.overrides]]
105
+ module = ["zeroconf.*"]
106
+ ignore_missing_imports = true