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
v3 >= 3.1.0
v2 >= 2.5.0 < 3.0.0

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

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

Initalization

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 = exchange_code("code", client_session)
client = (
    create(config=config, client_session=client_session)
    if client_session is not None
    else None
)

Events

You can register a event callback which will be triggered if the client receives a device update:

# all imports and a client exists...


def received_update(device):
    print(device)


client.set_event_callback(received_update)
client.start()

# you can stop the client listening for updates using:
client.stop()

Each device update will be pushed to your callback and will create an event loop in the background.

Streaming

You can stream device updates directly and process them through, e.g., an async for loop:

# all imports and a client exists...

async for device in client.events():
    print(device)

Examples

The following examples are available in the examples directory:

  • events: uses the callback mechanism (start(), stop())
  • streaming: uses the streaming mechanism (events())

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 11.2.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 11.2.1
File Size Uploaded Provenance Actions
onyx_client-11.2.1.tar.gz 19.8 kB With provenance Details for onyx_client-11.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 49.9 kB

Release files / onyx_client-11.2.1.tar.gz

Download URL onyx_client-11.2.1.tar.gz
Size 19.8 kB
Tags Source
SHA-256 checksum
How to use checksums
7ed1631891b2e9703816c91f8006fadce10fd4a9b63bb080632a3e15ae4effbb
BLAKE2b-256 checksum
How to use checksums
858f8687e6ede5808f8b95e828473a7e88731416d5bac616daff261774b86db8
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 11, 2026.

Transparency log

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

Download URL onyx_client-11.2.1-py3-none-any.whl
Size 30.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
42a9ba1a85a7a1c15814418b436e9726ae90f42657df49a2201055d53dad3763
BLAKE2b-256 checksum
How to use checksums
b5cd9ddba8e2845b08306a219f3609baec026aff0f61ea6eea69f987b1fa1c62
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 11, 2026.

Transparency log

Security for onyx-client 11.2.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-11.2.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 11, 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

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