Skip to main content

Onyx Client

Buy Me A Coffee

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) and disable_automation(identifier) read and switch the automations.
  • update_status(), check_for_update() and install_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 returns True if 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 the event_loop parameters are removed; use stream().
  • Configuration raises InvalidConfigurationException for an unsupported api_version.
  • verify() returns a VerifyResult instead of a boolean.
  • devices() has no include_details parameter anymore and returns summaries; use device(identifier) for the properties.
  • Devices are immutable by convention: update_with() and keys() 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_type keeps the API value.
  • NumericValue.read_only is renamed to readonly. BooleanValue is removed; enumerations are EnumValues.
  • AnimationKeyframe takes (value, duration, delay, interpolation).
  • Click and Switch take the same leading arguments as all other devices; all devices accept raw_type, tint and active_command as keyword arguments.
  • init_device(identifier, data) takes the complete API data; numeric_value(), boolean_value(), onyx_client.utils.device_type, onyx_client.utils.filter and UpdateException are 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

  1. Install all dependencies as shown above.
  2. Run pytest by:
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.

  1. Install all dependencies as shown above.
  2. (Optional) Install pre-commit hooks:
poetry run pre-commit install
  1. 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
Daniel Mühlbachler-Pietrzykowski

🚧 💻 📖
Mathias Mitterdorfer
Mathias Mitterdorfer

💻
Robert Weitlaner
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. :)

Buy Me A Coffee

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)

Source distribution for onyx-client 12.0.1
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)

Table of built distributions (wheels) for onyx-client 12.0.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

12.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page