OWNd

OWNd is an asynchronous Python library and daemon for the Legrand / BTicino OpenWebNet home automation protocol.

It powers the Home Assistant MyHOME integration and serves as a standalone Python client for discovering, monitoring, and controlling OpenWebNet bus devices over TCP/IP gateways and serial USB interfaces.

• Hardened Dual-Session Architecture: Decouples real-time bus event monitoring (OWNEventSession) from command and query execution (OWNCommandSession), preventing command bursts from interrupting event monitoring.
• Strongly Typed CEN / CEN+ Command Builders (P2): Dedicated fluent builders (OWNCenCommand, OWNCenPlusCommand) with strict OpenWebNet golden corpus frame parity for short press, start pressure, still held, and release actions across pushbuttons and rotary encoders.
• Thermoregulation Central Unit Coordination (P4): Dedicated builder support for 3550 (#0) and 4695 (#0#1) central units (OWNHeatingCommand.set_central_mode, set_central_temperature, set_central_antifreeze, set_central_thermal_protection, set_central_off), enabling master heating/cooling state distribution.
• DALI Tunable White & Color Temperature: Built-in support for DALI DT8 ballasts (F429 / F461) with Dimension 14 color temperature encoding and bidirectional Kelvin/mireds conversion.
• OpenWebNet Golden Corpus Validation: Cross-checked and validated against the community OpenWebNet Golden Corpus (75+ real-world captured frame scenarios) ensuring exact frame encodings, dimensions, and edge cases.
• Serial & USB Dongle Support: Built-in single-channel serial transport (AsyncSerialTransport) for the Legrand 3578 USB/ZigBee interface with in-band event and command-reply demultiplexing.
• Connection Resilience:
  • Fail-closed SHA-1 and HMAC-SHA2 gateway authentication with constant-time signature verification.
  • OS-level TCP keepalive (SO_KEEPALIVE) with aggressive probing (30s idle / 10s interval / 3 count) to detect silent network drops (power loss, cable unplugged) in ~60s.
  • Periodic application-level keepalives and passive watchdogs.
  • Non-blocking bounded timeouts on handshakes and commands to prevent event loop stalls.
  • Multi-frame response collection for large bus status sweeps (up to 256 frames).
• Declarative Hardware Profiles: Tailored queue pacing, session concurrency, and subsystem limits for known Legrand/BTicino hardware (F454, F455, MH200, MH200N, MH201, MH202, MyHomeServer1, and conservative generic fallbacks).
• Modern Python & Strict 100% Test Coverage: Designed for Python 3.11+, tested continuously against Python 3.11, 3.12, 3.13, and 3.14 with strict 100.0% line coverage unconditionally enforced across all core modules.

Install the latest stable release from PyPI:

pip install OWNd

To test preview releases or beta builds:

pip install --pre OWNd

• Serial / USB support (required for Legrand 3578 USB dongles):

  pip install "OWNd[serial]"

• Development & test suite:

  pip install "OWNd[test]"

OWNd parses OpenWebNet frames and dispatches typed commands and events across the full MyHOME spectrum:

Gateways have varying processing limitations, socket budgets, and pacing requirements. OWNd uses declarative profiles to protect your hardware:

Profiles can be resolved automatically using get_gateway_profile(model_name):

from OWNd.profiles import get_gateway_profile

profile = get_gateway_profile("F454")
print(f"Max concurrent sessions: {profile.max_command_sessions}")
print(f"Command queue delay: {profile.command_queue_delay}s")

import asyncio
from OWNd.connection import OWNGateway
from OWNd.transport.tcp import AsyncTcpTransport
from OWNd.message import OWNMessage

async def main():
    # Configure gateway credentials
    gateway = OWNGateway({
        "address": "192.168.1.50",
        "port": 20000,
        "password": "12345",
    })

    transport = AsyncTcpTransport(gateway)

    # Register an event listener for bus notifications
    def on_event(msg: OWNMessage | str):
        if isinstance(msg, OWNMessage) and msg.is_event:
            print(f"Bus Event: {msg.human_readable_log}")

    transport.register_listener(on_event)

    # Connect both event and command channels
    if await transport.connect():
        print("Connected to OpenWebNet gateway!")

        # Send a command: Turn ON light at address 12 (*1*1*12##)
        response = await transport.send("*1*1*12##")
        print(f"Command response: {response}")

        # Keep listening for events
        await asyncio.sleep(10)
        await transport.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

For fine-grained control, OWNEventSession and OWNCommandSession can be operated independently:

import asyncio
from OWNd.connection import OWNGateway, OWNEventSession, OWNCommandSession

async def main():
    gateway = OWNGateway({"address": "192.168.1.50", "port": 20000, "password": "12345"})

    # Event listening session
    event_session = OWNEventSession(gateway=gateway)
    await event_session.connect()

    # Command session
    command_session = OWNCommandSession(gateway=gateway)
    await command_session.connect()

    # Query status of zone 1 climate: *#4*1*0##
    status = await command_session.send("*#4*1*0##", is_status_request=True)
    print(f"Status response: {status}")

    await event_session.close()
    await command_session.close()

asyncio.run(main())

import asyncio
from OWNd.transport.serial import AsyncSerialTransport

async def main():
    transport = AsyncSerialTransport(port="/dev/ttyUSB0")
    transport.register_listener(lambda msg: print(f"Serial Inbound: {msg}"))

    await transport.connect()
    # Send OpenWebNet frame over serial
    await transport.send("*1*1*12##")

    await asyncio.sleep(5)
    await transport.disconnect()

asyncio.run(main())

from OWNd.message import OWNCenCommand, OWNCenPlusCommand, OWNHeatingCommand

# CEN (WHO=15): Button 2 short press on scenario controller 12
frame_cen_press = OWNCenCommand.press(where="12", button=2)                # *15*02*12##
frame_cen_release = OWNCenCommand.release_short_press(where="12", button=2)  # *15*02#1*12##

# CEN+ (WHO=25): Button 5 short press on virtual object 21 -> *25*21#5*21##
frame_cenplus_press = OWNCenPlusCommand.press(where="21", button=5)

# CEN+ (WHO=25): Button 5 still held event -> *25*23#5*21##
frame_cenplus_held = OWNCenPlusCommand.still_held(where="21", button=5)

# CEN+ (WHO=25): Button 5 release after a long press -> *25*24#5*21##
frame_cenplus_rel = OWNCenPlusCommand.release(where="21", button=5)

# Central Unit (WHO=4): Set 3550 (#0) master mode to Heating at 21.5°C -> *4*1#0215*#0##
frame_heat = OWNHeatingCommand.set_central_mode(where="#0", mode="heating", temperature=21.5)

# Central Unit (WHO=4): Set 4695 (#0#1) master mode to Cooling at 24.0°C -> *4*2#0240*#0#1##
frame_cool = OWNHeatingCommand.set_central_mode(where="#0#1", mode="cooling", temperature=24.0)

# Central Unit (WHO=4): Turn Central Unit OFF -> *4*303#0215*#0##
frame_off = OWNHeatingCommand.set_central_off(where="#0", mode="heating", temperature=21.5)

OWNd includes a built-in CLI for discovering gateways and inspecting live bus events:

Scan the local network for OpenWebNet gateways and listen for events:

python -m OWNd

Connect to a known gateway IP address:

python -m OWNd --address 192.168.1.50 --port 20000 --password 12345 --verbose 2

Available options:

• -a, --address: IP address of the gateway
• -p, --port: Gateway TCP port (default: 20000)
• -P, --password: Numeric OPEN password or HMAC secret (default: 12345)
• -m, --mac: MAC address (used as unique identifier when skipping SSDP)
• -v, --verbose: Verbosity level (0 = WARNING, 1 = INFO, 2 = DEBUG)

Clone the repository and install development dependencies:

git clone https://github.com/OpenWebNet-HA/OWNd.git
cd OWNd
pip install -e ".[test,serial]" ruff mypy types-python-dateutil types-pytz

Execute the test suite across all subsystems:

python -m pytest -q

Verify type safety and coding standards:

ruff check OWNd tests setup.py
mypy OWNd

This project is licensed under the Apache License 2.0, the same license as Home Assistant Core. See the LICENSE file for details.

OWNd maintains an automated test suite with strict 100.0% line coverage (3,087 / 3,087 statements covered with 0 missing lines across all 9 core modules) verified continuously in CI across Python 3.11, 3.12, 3.13, and 3.14:

Live Test Execution: View detailed line-by-line coverage and test history on Codecov (OpenWebNet-HA/OWNd) or download the interactive coverage report from the CI GitHub Actions run.