Skip to main content

Duka Connect

An event-driven Python client for Duka One ventilation units on the local network, over the unit's own UDP protocol.

You subscribe to the values you care about and are told when one changes - with its quality, so "offline", "not on this unit" and a real value never look alike.

Supported units

Unit Status
Duka One (S6W, 50+) Points are from the manufacturer's connection guide; the clock battery's voltage has been read on a unit, the rest not yet

Every point is taken from the manufacturer's connection guide for the protocol, and most have not been tested on a unit. point.certainty says so: REPORTED until a point has been read on a Duka One, VERIFIED after. Values may be wrong or missing; reports of what a unit shows are welcome. What each point is: docs/protocol.md; the manufacturer's documents themselves: docs/models.

Installation

pip install duka-connect

Everything you use comes from duka_connect; a simulated unit for your own tests is in duka_connect.testing. It depends only on event_connect, the protocol-free core it is built on.

Usage

import asyncio
from duka_connect import Client, PointKey

def on_change(key, old, new):
    print(f"{key}: {new.value} ({new.quality.name})")

async def main():
    # The device id is in Duka's app; the password is 1111 unless it was changed there.
    client = Client("<unit-ip>", "<device-id>", "1111")
    await client.connect()              # reads every point once

    client.subscribe(PointKey.HUMIDITY, on_change)
    client.subscribe(PointKey.ALARM, on_change)
    client.subscribe(PointKey.RTC_BATTERY_VOLTAGE, on_change)

    while True:                         # you own the clock; the library owns the plan
        await client.poll()             # reads only what is due - free when nothing is
        await asyncio.sleep(1)

asyncio.run(main())

discover() lists the units that answer a broadcast, with their address and device id.

Values

Every value is a DataValue with .value, .quality, .timestamp (when the unit answered, in UTC), and .raw: the bytes the unit answered.

Quality Meaning
GOOD A value the unit answered.
NO_DATA The unit answered a number no state names.
STALE The last read failed; the value is the last good one.
MISSING The unit says it does not have this value.

A subscribed point is read on its poll rate: FAST 10 s, MEDIUM 30 s, SLOW 60 s, RARE 15 min, or STATIC, once when connecting. set_poll_interval(key or poll rate, seconds) changes one, and refresh() reads now.

A point names what its change affects, in on_change, and a command what it changes, in on_write: a Refresh of those points, after a wait, and read again until they settle where it says so. When the alarm clears, the battery and filter are read 10 seconds later, and again every 10 seconds while they change, for up to 2 minutes; a new speed has the fans read 3 seconds later, until they settle. What is read again is what is subscribed to. docs/protocol.md lists every one.

One request is sent at a time, and whatever is due when the unit is free goes out together. A read asked for after a change does not move a point's own rhythm, so points read together stay together. A request the unit does not answer is sent again, attempts times in all; a read still unanswered waits for its next turn, and its value meanwhile is the last good one, STALE. Once the unit answers again, whatever failed meanwhile is read at once. After two requests in a row go unanswered, the unit is not asked for 10 seconds, so a pass over a silent unit fails at once rather than waiting out every request; then one request probes it (DUKA_ONE_BREAKER, which a different CircuitBreaker given to Client replaces). The unit counts as not answering - Status.CONNECTED false - only after half a minute without an answer, so one lost packet does not make it unavailable; when it answers again, every subscribed point is read. A different Timing can be given to Client; DUKA_ONE_TIMING is the one a Duka One is read by.

client.status(Status.CONNECTED) says whether the unit answers, and subscribe_status(Status.CONNECTED, callback) tells every change. client.diagnostics() counts the requests, those left unanswered or held back while the unit is not asked, and the breaker's state, for a bug report; it never holds the address, device id or password.

Writing

from duka_connect import PointKey, Speed, VentilationMode, Write

await client.write(PointKey.VENTILATION_MODE, VentilationMode.HEAT_RECOVERY)
await client.write_sequence([Write(PointKey.SPEED, Speed.MANUAL), Write(PointKey.MANUAL_SPEED, 120)])
await client.write(PointKey.RESET_FILTER_TIMER, True)   # a command, sent with True

A write returns whether the unit took it. A setting is answered by the unit with its new value, which the client then holds. A command is not answered, so what it changed is read a second after it is sent, at the next poll().

A value outside a point's limits, or of another type, raises InvalidValueError before anything is sent; a point that cannot be written raises ValueError.

Error Meaning
CannotConnectError The unit did not answer. A unit does not answer a wrong device id or password either.
UnsupportedDeviceError The unit answered, but not as a Duka One does.

Measuring your unit

The waits after a change are first estimates, not yet measured on a Duka One. duka_connect.testing measures them on yours:

from duka_connect.testing import measure_fan_settling, measure_latency, recommended_refresh

print(await measure_latency(client))               # how long the unit takes to answer
settlings = await measure_fan_settling(client)       # low to high and back; changes the speed
for settling in settlings:
    print(settling)
print(recommended_refresh(settlings, every=0.5))     # an `after` and an `until_stable` for the fans

measure_fan_settling changes the unit's speed while it runs, and sets it back afterwards.

Trying it on your unit

pip install -e . -r requirements-test.txt
DUKA_HOST=<unit-ip> DUKA_DEVICE_ID=<device-id> python -m pytest -m live -s

It only reads, and prints what the unit answers for every point.

License

MIT

Metadata

Release files for duka-connect 0.6.5

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

Source distribution (sdist)

Source distribution for duka-connect 0.6.5
File Size Uploaded Provenance Actions
duka_connect-0.6.5.tar.gz 44.3 kB With provenance Details for duka_connect-0.6.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for duka-connect 0.6.5
File Interpreter ABI Platform Actions
duka_connect-0.6.5-py3-none-any.whl Python 3 none any Details for duka_connect-0.6.5-py3-none-any.whl

Total release size: 70.5 kB

Release files / duka_connect-0.6.5.tar.gz

Download URL duka_connect-0.6.5.tar.gz
Size 44.3 kB
Tags Source
SHA-256 checksum
How to use checksums
485933bafd15b16d64c50e35b3edb859cad50113649063f1e716368d39fe5eea
BLAKE2b-256 checksum
How to use checksums
b260ba41596f2f2a22a691ea061da0fb10cd20392265dfed9dcf900428d82421
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 15, 2026.

Transparency log

Release files / duka_connect-0.6.5-py3-none-any.whl

Download URL duka_connect-0.6.5-py3-none-any.whl
Size 26.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
258fed1d1e88d0d732a1bb81537b9d087c509af12ce87396dc973775548febf1
BLAKE2b-256 checksum
How to use checksums
09e606fa65fe1a8ca80b74c017836c218c9b44d9e84f802b30dc56cb7f2da7f8
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 15, 2026.

Transparency log

Security for duka-connect 0.6.5

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 duka_connect-0.6.5.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 15, 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