Onyx Client
This repository contains a Python HTTP client for Hella' s ONYX.CENTER API.
API Versions
It is encouraged to always update Hella devices to the latest software. This will, mostly, also enforce using the newest API. In below table you can find an indication of what Hella API version is supported.
| Hella API Version | Client Version |
|---|---|
| v6 | >= 12.0.0 |
| v3 | >= 3.1.0 (deprecated, removed in 13.0.0) |
| v2 | >= 2.5.0 < 3.0.0 |
The client uses v6 by default. api_version="v3" is still accepted for ONYX.CENTERs that do not support v6; v6-only features (automations, update status, logout, tint, active command) are unavailable then and their calls fail.
Installation
The package is published in PyPi and can be installed via:
pip install onyx-client
Configuration
The configuration defines connection properties as a dict for the application running.
Attention: make sure to read the Onyx API Access Control description to retrieve the fingerprint and access token!
| Option | Description |
|---|---|
| fingerprint | The fingerprint of the ONYX.CENTER. |
| access_token | The permanent access token. |
| local_address | The local address to use (default: None). |
| client_session | The initialized aiohttp.ClientSession. (Default: None, create new session.) |
| api_version | The API version to use (default: v6, deprecated: v3). |
Local Access
The local address can be used to access the ONYX.CENTER API from within the local network. If set, the client will use this address for all API requests.
Logging
The client logs to the onyx_client.* loggers. Log messages and Resynced.reason never contain the access token; the fingerprint (or local address) identifies the ONYX.CENTER. repr(Configuration) masks the access token.
Access Control Helper
The method onyx_client.authorizer.exchange_code takes the API code and an optional local API address, and performs the exchange to a fingerprint and access token. Please follow the aforementioned documentation to retrieve the code.
Usage
Initialization
You can instantiate the client using the onyx_client.client.create method like:
import aiohttp
from onyx_client.client import create
from onyx_client.authorizer import exchange_code
# by providing the fingerprint and access token only
client = create(fingerprint="fingerprint", access_token="access_token")
# by providing the fingerprint, access token and aiohttp client session
client = create(
fingerprint="fingerprint",
access_token="access_token",
client_session=aiohttp.ClientSession(),
)
# by providing the fingerprint, access token and local API address
client = create(
fingerprint="fingerprint", access_token="access_token", local_address="localhost"
)
# by providing the configuration object
client_session = aiohttp.ClientSession()
# e.g. by exchanging the code first
config = await exchange_code("code", client_session)
client = (
create(config=config, client_session=client_session) if config is not None else None
)
Verification
verify() checks the connection and returns a VerifyResult: OK, UNREACHABLE (also on unexpected responses), UNAUTHORIZED (HTTP 401/403) or VERSION_UNSUPPORTED (the ONYX.CENTER does not offer the configured API version).
Streaming
stream() yields the state of the ONYX.CENTER as events while you iterate it. The client never runs background tasks.
# all imports and a client exists...
from onyx_client.stream.events import DeviceChanged, Snapshot
async for event in client.stream():
if isinstance(event, Snapshot):
print(event.devices)
elif isinstance(event, DeviceChanged):
print(event.device)
| Event | Emitted when |
|---|---|
Snapshot |
the stream (re)connects; carries all devices, groups, automations and the update status. |
DeviceAdded |
a device was added; carries the complete device. |
DeviceChanged |
a device changed; carries the complete device. |
DeviceRemoved |
a device was removed; carries its identifier. |
GroupsChanged |
any group changed; carries all groups. |
AutomationsChanged |
any automation changed; carries all automations. |
UpdateChanged |
the update status changed; carries the update status. |
Pulse |
the ONYX.CENTER sends its heartbeat (every 30 seconds on current firmware); carries its time. |
Resynced |
the stream reconnected; carries the reason (error class, HTTP status and path, never credentials). The following Snapshot replaces the state and is followed by the differences. |
The client applies the patches of the stream to its own copy of the state, so every event carries complete objects. On errors, or if no data arrives for 90 seconds, it reconnects with an exponential backoff (1 to 60 seconds). Before every (re)connect the clock offset is measured; if the ONYX.CENTER's clock does not answer within 10 seconds or sends invalid data, the previous offset is kept and the connect continues. Rejected credentials (HTTP 401/403) raise aiohttp.ClientResponseError without the request headers (it never carries the access token). resync() forces a reconnect, e.g. to periodically replace the state with a fresh snapshot. close() ends the stream at its next message or reconnect; break out of the loop inside contextlib.aclosing(client.stream()) to release the connection immediately.
Animations
ONYX reports movements as animations and keeps reporting the value from before a movement, even after it finished. Use effective_value(client.now()) to get the current value of animated properties (e.g. actual_position, actual_angle, actual_brightness); is_animating(client.now()) tells whether the property is still animated. client.now() is the ONYX.CENTER time, corrected by the clock offset measured on every (re)connect (kept from the previous connect if the clock does not answer).
Automations, Updates and Logout
automations(),enable_automation(identifier)anddisable_automation(identifier)read and switch the automations.update_status(),check_for_update()andinstall_update()read and install software updates of the ONYX.CENTER. Installing restarts the ONYX.CENTER; the stream reconnects once it is back.logout()revokes the access token and returnsTrueif the token is invalid afterwards.
Examples
The streaming example in the examples directory verifies the connection and streams shutter positions.
Migration from 11.x to 12.0.0
- The client uses API v6; pass
api_version="v3"to keep using v3 (deprecated, removed in 13.0.0). events(),start(),stop(),set_event_callback()and theevent_loopparameters are removed; usestream().ConfigurationraisesInvalidConfigurationExceptionfor an unsupportedapi_version.verify()returns aVerifyResultinstead of a boolean.devices()has noinclude_detailsparameter anymore and returns summaries; usedevice(identifier)for the properties.- Devices are immutable by convention:
update_with()andkeys()are removed; every event carries the complete device. - The device type is taken from the API's type only. Unknown types are
DeviceType.UNKNOWN;raw_typekeeps the API value. NumericValue.read_onlyis renamed toreadonly.BooleanValueis removed; enumerations areEnumValues.AnimationKeyframetakes(value, duration, delay, interpolation).ClickandSwitchtake the same leading arguments as all other devices; all devices acceptraw_type,tintandactive_commandas keyword arguments.init_device(identifier, data)takes the complete API data;numeric_value(),boolean_value(),onyx_client.utils.device_type,onyx_client.utils.filterandUpdateExceptionare removed.
Development
The project uses poetry. Tool versions (Python, uv, Poetry) are managed with mise: run mise trust and mise install once, then install all dependencies and the build environment:
poetry install
Testing
- Install all dependencies as shown above.
- Run
pytestby:
poetry run pytest
# or
pytest
Run mutation testing with mutmut by:
poetry run mutmut run
# check results
poetry run mutmut results
Linting and Code Style
The project uses ruff for automated code linting and fixing, also using pre-commit.
- Install all dependencies as shown above.
- (Optional) Install pre-commit hooks:
poetry run pre-commit install
- Run ruff:
poetry run ruff check .
# poetry run ruff format .
Building
This package uses poetry-dynamic-versioning which infers the version number based on the Git tags. Hence, to have a proper versioning for the distribution, use Python's build system like:
pip install build
python -m build
Your distribution will be in the dist directory.
Commit Message
This project follows Conventional Commits, and your commit message must also
adhere to the additional rules outlined in .conform.yaml.
Contributors
Thanks goes to these wonderful people (emoji key):
Daniel Mühlbachler-Pietrzykowski 🚧 💻 📖 |
Mathias Mitterdorfer 💻 |
Robert Weitlaner 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!
Supporting
If you enjoy the application and want to support my efforts, please feel free to buy me a coffe. :)
Metadata
Release files for onyx-client 12.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| onyx_client-12.0.1.tar.gz | 29.5 kB | With provenance | Details for onyx_client-12.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| onyx_client-12.0.1-py3-none-any.whl | Python 3 | none | any | Details for onyx_client-12.0.1-py3-none-any.whl |
Total release size: 72.1 kB
Release files / onyx_client-12.0.1.tar.gz
| Download URL | onyx_client-12.0.1.tar.gz |
|---|---|
| Size | 29.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e98690dff213d2fda6f7b1f1f9efd6bc9d98b0831b1c3e4e1590bebf2919b3de
|
|
BLAKE2b-256 checksum How to use checksums |
2c458a90684453e8d3749b5fb9e0e6eab9647432dd8519ab32a6e3b9c11d939d
|
| 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 17, 2026.
Transparency logRelease files / onyx_client-12.0.1-py3-none-any.whl
| Download URL | onyx_client-12.0.1-py3-none-any.whl |
|---|---|
| Size | 42.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1e594b4874dcb2dfe5a84b2e5afdd0ffa8511efdc55a2544d9a06a425c9c7d86
|
|
BLAKE2b-256 checksum How to use checksums |
0cd0acfe3dc99f664e77dda079a66b95c58b9c1c211ada9b3ff715a69a7095f4
|
| 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 17, 2026.
Transparency logSecurity for onyx-client 12.0.1
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.
Attestation for onyx_client-12.0.1.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 17, 2026.
Transparency logA 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.