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.

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; 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); rejected credentials (HTTP 401/403) raise aiohttp.ClientResponseError. 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.

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

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.0
File Size Uploaded Provenance Actions
onyx_client-12.0.0.tar.gz 27.2 kB With provenance Details for onyx_client-12.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for onyx-client 12.0.0
File Interpreter ABI Platform Actions
onyx_client-12.0.0-py3-none-any.whl Python 3 none any Details for onyx_client-12.0.0-py3-none-any.whl

Total release size: 67.1 kB

Release files / onyx_client-12.0.0.tar.gz

Download URL onyx_client-12.0.0.tar.gz
Size 27.2 kB
Tags Source
SHA-256 checksum
How to use checksums
b21c7262ad343720a6cd201d13f48ffae3e39a09d0ea93c96217302d2851724c
BLAKE2b-256 checksum
How to use checksums
2c57f4cad709699ff3dacaf594e3fd33e26e584bbbc7f97ea6b5860863b66980
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 16, 2026.

Transparency log

Release files / onyx_client-12.0.0-py3-none-any.whl

Download URL onyx_client-12.0.0-py3-none-any.whl
Size 40.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5aa6775e8c4f063b7bd71246ca618479ae7effa394362c0a9ba7e3eb11b202a5
BLAKE2b-256 checksum
How to use checksums
2e5811f653e60f2d718721ab6c98e908f67df0da018b3ef3484b8bbee8764ec4
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 16, 2026.

Transparency log

Security for onyx-client 12.0.0

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.0.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 16, 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.0 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