zeptrionair-api
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.
It is the library behind the Home Assistant integration ha-zeptrionair.
Features
- Read device info, channels (with their category: light, dimmer, blind, awning) and states.
- Control lights, dimmers and covers: on/off/toggle, open/close/stop, timed moves and dims, and scenes.
- Real-time events over the device WebSocket: channel changes, plus wall-key presses with their decoded function. Falls back to the
chnotifylong poll, and reconnects automatically. - Smartfront: key layout, temperature/light/humidity sensors, LED background colours.
- mDNS discovery.
zeptrionCLI for scripting and debugging.- A simulated device (
zeptrionair_api.testing) for your own tests.
Install
pip install zeptrionair-api # library only
pip install "zeptrionair-api[cli]" # + the zeptrion command and mDNS discovery
Requires Python 3.12 or newer.
Library
import asyncio
from zeptrionair_api import ChannelUpdate, KeyEvent, ZeptrionDevice
async def main() -> None:
async with ZeptrionDevice("zapp-12345678.local") as device:
info = await device.identify()
print(info.serial, info.type, info.sw_version)
for channel in await device.channels():
if channel.in_use:
print(channel.number, channel.category, channel.name)
await device.turn_on(1) # light
await device.close_cover(2) # blind: close fully
await device.move_open(2, 1500) # blind: move up for 1.5 s
async for event in device.events(): # runs until you break
if isinstance(event, ChannelUpdate):
print("channel", event.channel, "=", event.value)
elif isinstance(event, KeyEvent) and event.pressed:
print("key", event.key, event.function)
asyncio.run(main())
Notes:
- For covers, a channel value of 100 means the motor is running and 0 means it stopped. The devices don't report position.
- Pass your own
aiohttp.ClientSessionwithZeptrionDevice(host, session=...)to share connections. - 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.
CLI
zeptrion discover # find devices (mDNS)
zeptrion info zapp-12345678.local # identification, features, key layout, sensors
zeptrion channels zapp-12345678.local
zeptrion state zapp-12345678.local
zeptrion on|off|toggle HOST CH
zeptrion open|close|stop HOST CH
zeptrion move HOST CH open|close [--ms 1500]
zeptrion dim HOST CH up|down [--ms 800]
zeptrion scene HOST CH recall|store|delete N
zeptrion send HOST CH move_open_2000 # any valid raw command
zeptrion rename HOST CH --name "Kitchen" --group "Ground floor"
zeptrion watch HOST [HOST ...] [--json] # live channel changes and key presses
zeptrion dump OUTDIR HOST [HOST ...] # anonymised fixtures for bug reports
Most commands accept --json. Exit codes: 0 = success, 1 = device or network error, 2 = invalid input.
Documentation
- docs/protocol.md: the maintained protocol reference, including the WebSocket (which Feller never documented) and Smartfront key decoding.
- docs/10ZEPAPIE1612.pdf: Feller's original API document (v1.0).
Supported hardware
| Status | |
|---|---|
| 3340-2-B, firmware 01.08.28, on/off lights and blinds, Smartfront | tested on real devices |
| 3340-2-A, 3340-4-A/B, dimmers, awnings, sensor fronts, firmware before 01.08 | expected to work, untested |
If you have untested hardware, please capture anonymised fixtures and open an issue or PR:
zeptrion dump captures/ <host> [<host> ...]
# or, without the CLI extra:
python -m zeptrionair_api.capture captures/ <host> [<host> ...]
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.
Development
uv sync
uv run pytest --cov
uv run ruff check . && uv run ruff format --check . && uv run mypy src
Disclaimer
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 (MIT).
License
MIT
Metadata
Release files for zeptrionair-api 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zeptrionair_api-0.1.1.tar.gz | 49.3 kB | With provenance | Details for zeptrionair_api-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zeptrionair_api-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for zeptrionair_api-0.1.1-py3-none-any.whl |
Total release size: 84.9 kB
Release files / zeptrionair_api-0.1.1.tar.gz
| Download URL | zeptrionair_api-0.1.1.tar.gz |
|---|---|
| Size | 49.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8f2d985586c38401ef5556e2db13b32d03ad93e2e297fe45dd3e309cc5d7a8b2
|
|
BLAKE2b-256 checksum How to use checksums |
4763f8b45fff334653ec57c5dc21a72acb56ec6175bc75499f6970f9c774612d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / zeptrionair_api-0.1.1-py3-none-any.whl
| Download URL | zeptrionair_api-0.1.1-py3-none-any.whl |
|---|---|
| Size | 35.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f7dead8cce79ff881d875102f5198f388eaac40105ad8a5693622fc827ced830
|
|
BLAKE2b-256 checksum How to use checksums |
1a43179f25c59d1f3180741402fd93bb8a72c3f917cf6102ab2711af41fdd258
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for zeptrionair-api 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for zeptrionair_api-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.