Habitron Client
An asynchronous, fully typed API client for the Habitron SmartHub, designed for integration with Home Assistant.
Features
- Non-blocking TCP communication via
asyncioStreamReader/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 validatedTypedDictmodels. - Async UDP discovery of SmartHubs on the local network.
- Typed exception hierarchy and a
py.typedmarker (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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file habitron_client-2.0.13.tar.gz.
File metadata
- Download URL: habitron_client-2.0.13.tar.gz
- Upload date:
- Size: 72.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
25673db941ae6990de34014365a202b6f62ebe903329b2a5b163c643b5f2a2bb
|
|
| MD5 |
7a17c868c115cba78f1f02b1833b2fba
|
|
| BLAKE2b-256 |
b611aef18244b9d8bf66aaafd7ed7769465e47dda8179978b103be9e1123f3ef
|
Provenance
The following attestation bundles were made for habitron_client-2.0.13.tar.gz:
Publisher:
release.yml on dneprojects/habitron-client
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
habitron_client-2.0.13.tar.gz -
Subject digest:
25673db941ae6990de34014365a202b6f62ebe903329b2a5b163c643b5f2a2bb - Sigstore transparency entry: 2334183470
- Sigstore integration time:
-
Permalink:
dneprojects/habitron-client@30d017bd2e843e1672a6a25b6af62b4cf8f1418e -
Branch / Tag:
refs/tags/v2.0.13 - Owner: https://github.com/dneprojects
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@30d017bd2e843e1672a6a25b6af62b4cf8f1418e -
Trigger Event:
push
-
Statement type:
File details
Details for the file habitron_client-2.0.13-py3-none-any.whl.
File metadata
- Download URL: habitron_client-2.0.13-py3-none-any.whl
- Upload date:
- Size: 41.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
33f1fb08840a59d9f1e41a3d75b80e22d73abdd3dbb7a8f4739327b4e6fa0e1c
|
|
| MD5 |
148ce5d7833d8e06d639c4c3ae5ec6df
|
|
| BLAKE2b-256 |
840b39cfb32323705b379994390d75e47dcf0520f030ac2433b1fae603eaaddf
|
Provenance
The following attestation bundles were made for habitron_client-2.0.13-py3-none-any.whl:
Publisher:
release.yml on dneprojects/habitron-client
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
habitron_client-2.0.13-py3-none-any.whl -
Subject digest:
33f1fb08840a59d9f1e41a3d75b80e22d73abdd3dbb7a8f4739327b4e6fa0e1c - Sigstore transparency entry: 2334183480
- Sigstore integration time:
-
Permalink:
dneprojects/habitron-client@30d017bd2e843e1672a6a25b6af62b4cf8f1418e -
Branch / Tag:
refs/tags/v2.0.13 - Owner: https://github.com/dneprojects
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@30d017bd2e843e1672a6a25b6af62b4cf8f1418e -
Trigger Event:
push
-
Statement type:
