Skip to main content

zeptrionair-api

CI PyPI

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 chnotify long poll, and reconnects automatically.
  • Smartfront: key layout, temperature/light/humidity sensors, LED background colours, and Smartbutton programming (the button then sends its commands directly between the zApps).
  • mDNS discovery.
  • zeptrion CLI 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.ClientSession with ZeptrionDevice(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 smartbutton HOST --send TARGET:CH:CMD [--send ...] [--raw JSON] [--wait 60]
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.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zeptrionair-api 0.2.0
File Size Uploaded Provenance Actions
zeptrionair_api-0.2.0.tar.gz 57.3 kB With provenance Details for zeptrionair_api-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zeptrionair-api 0.2.0
File Interpreter ABI Platform Actions
zeptrionair_api-0.2.0-py3-none-any.whl Python 3 none any Details for zeptrionair_api-0.2.0-py3-none-any.whl

Total release size: 98.2 kB

Release files / zeptrionair_api-0.2.0.tar.gz

Download URL zeptrionair_api-0.2.0.tar.gz
Size 57.3 kB
Tags Source
SHA-256 checksum
How to use checksums
54bf771243a2b3cdaebf8023462453d58adeef4cb988a52d9592107327dba51c
BLAKE2b-256 checksum
How to use checksums
2349a45a99669cd80a58dfcaeb053f6ab4749288fed3151127c7366a0359dcf1
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 log

Release files / zeptrionair_api-0.2.0-py3-none-any.whl

Download URL zeptrionair_api-0.2.0-py3-none-any.whl
Size 40.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
82458735fb820667f08610dfd78cb0fab680abd8c97608d162def46f12ee81ff
BLAKE2b-256 checksum
How to use checksums
4ad31874c62393a23599f3b34e5270fcb0496d5b93338c0c417e469e0418cdb6
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 log

Security for zeptrionair-api 0.2.0

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.

Select from 2 files

Attestation for zeptrionair_api-0.2.0.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page