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:
Newer release available (2.0.15)

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.14.tar.gz (73.1 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.14-py3-none-any.whl (41.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: habitron_client-2.0.14.tar.gz
  • Upload date:
  • Size: 73.1 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.14.tar.gz
Algorithm Hash digest
SHA256 200d98496aea670f85cd7cc92b9a3e313ec77f51108641e86dfae0ece47e874e
MD5 00fc793d3a6b95b82a11ea115c909b30
BLAKE2b-256 86eb820844d2d10f8baf7e2353684b0ccfb9e02314f0131d5e4944a55700d63c

See more details on using hashes here.

Provenance

The following attestation bundles were made for habitron_client-2.0.14.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.14-py3-none-any.whl.

File metadata

File hashes

Hashes for habitron_client-2.0.14-py3-none-any.whl
Algorithm Hash digest
SHA256 e42a012e7eb2f41ee7c9338f63f83881d542944a8614db8b30ab9872e2b48753
MD5 22f65503d0a095455f107fee47115c34
BLAKE2b-256 43ee078e429664f6049e6a860473e74a06d67fce0a37f5024028c6f0c9e5a3bf

See more details on using hashes here.

Provenance

The following attestation bundles were made for habitron_client-2.0.14-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