Habitron Client

An asynchronous, fully typed API client for the Habitron SmartHub, designed for integration with Home Assistant.

Features

  • Non-blocking TCP communication via asyncio StreamReader/StreamWriter.
  • Persistent, lock-serialised connection with automatic reconnect on errors.
  • Automatic CRC16 calculation and command wrapping.
  • High-level coroutines for outputs, dimmers, RGB, shutters, climate and more.
  • Safe YAML parsing (yaml.safe_load) into validated TypedDict models.
  • Async UDP discovery of SmartHubs on the local network.
  • Typed exception hierarchy and a py.typed marker (PEP 561 compliant).

Requirements

  • Python 3.11+

Installation

pip install habitron-client

Usage

The client is async-only and is used as an async context manager:

import asyncio

from habitron_client import HabitronClient, HabitronError


async def main() -> None:
    async with HabitronClient("192.0.2.10") as client:
        info = await client.get_smhub_info()
        print(info["software"]["version"])

        await client.set_output(mod_addr=1, nmbr=2, val=True)


asyncio.run(main())

Error handling

All failures raise a typed exception:

HabitronError                 (root)
├── HabitronConnectionError   (refused / EOF / socket lost)
├── HabitronTimeoutError      (no response within the deadline)
└── HabitronProtocolError
    ├── HabitronChecksumError (CRC mismatch)
    └── HabitronBusError      (SmartHub reported an error)

Discovery

from habitron_client import discover_smarthubs

hubs = await discover_smarthubs()

Development

pip install -e ".[dev]"
ruff check .
ruff format --check .
mypy --strict src/habitron_client
pytest

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dneprojects from gravatar.com dneprojects

Credits

Author: Habitron GmbH

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache-2.0)

Requires

Python >=3.14

Provides Extra

dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

habitron_client-2.0.15.tar.gz (75.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

habitron_client-2.0.15-py3-none-any.whl (43.0 kB view details)

Uploaded Python 3

File details

Details for the file habitron_client-2.0.15.tar.gz.

File metadata

  • Download URL: habitron_client-2.0.15.tar.gz
  • Upload date:
  • Size: 75.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for habitron_client-2.0.15.tar.gz
Algorithm Hash digest
SHA256 9bff1cc6670378c05b3bbd22732fda446ef903f8d57d3bd1b4e8490fc11498d4
MD5 7c92d30e5e960618a5763fca8e01b3a4
BLAKE2b-256 743131bad1ad8268ffd19982058c1fa9ef56b21901b5a45ade867a5a4b2eb3bb

See more details on using hashes here.

Provenance

The following attestation bundles were made for habitron_client-2.0.15.tar.gz:

Publisher: release.yml on dneprojects/habitron-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file habitron_client-2.0.15-py3-none-any.whl.

File metadata

File hashes

Hashes for habitron_client-2.0.15-py3-none-any.whl
Algorithm Hash digest
SHA256 4e7dda5032638994316e98624e022608482fa0955ec78f3cde59f4eb67b5d4e3
MD5 d085c9ce03569fdf6afb69987b3afadb
BLAKE2b-256 5946a992b053b41c51143ede2927f6efff54d7f4812ef443f0e90f9af3aa69a8

See more details on using hashes here.

Provenance

The following attestation bundles were made for habitron_client-2.0.15-py3-none-any.whl:

Publisher: release.yml on dneprojects/habitron-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page