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 |
|---|---|
| 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 and to install all dependencies and the build environment, run:
pip install poetry
poetry install
Testing
- Install all dependencies as shown above.
- Run
pytestby:
poetry run pytest
# or
pytest
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 💻 |
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. :)
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 onyx_client-11.0.0.tar.gz.
File metadata
- Download URL: onyx_client-11.0.0.tar.gz
- Upload date:
- Size: 18.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4b7559cad774737448e88d62d8fb4c088811d7ced0f1906ee011ed2e632b9204
|
|
| MD5 |
283b4fa2a73e5281b0e633f9b5c009dc
|
|
| BLAKE2b-256 |
e9a1282f8acfb323be2e3f2c85d5dff889c38672a2fb1616b306538e36a39aa3
|
Provenance
The following attestation bundles were made for onyx_client-11.0.0.tar.gz:
Publisher:
release.yml on muhlba91/onyx-client
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
onyx_client-11.0.0.tar.gz -
Subject digest:
4b7559cad774737448e88d62d8fb4c088811d7ced0f1906ee011ed2e632b9204 - Sigstore transparency entry: 2476388319
- Sigstore integration time:
-
Permalink:
muhlba91/onyx-client@a61cd69ea1d7550d75f7528c04413bd318d22db0 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/muhlba91
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@a61cd69ea1d7550d75f7528c04413bd318d22db0 -
Trigger Event:
push
-
Statement type:
File details
Details for the file onyx_client-11.0.0-py3-none-any.whl.
File metadata
- Download URL: onyx_client-11.0.0-py3-none-any.whl
- Upload date:
- Size: 27.3 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 |
2dfb0d105807742cd7e20147b7ca90f6f469aae23aa6fc4ee5e29f4b5f9aacd2
|
|
| MD5 |
3a5fb6a4d2ec5189ef7d584ed930c8ee
|
|
| BLAKE2b-256 |
3568e87e6448c0ec5d88bfebfe496c5b4cd0c91a54b982f69b5f060bbf88178c
|
Provenance
The following attestation bundles were made for onyx_client-11.0.0-py3-none-any.whl:
Publisher:
release.yml on muhlba91/onyx-client
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
onyx_client-11.0.0-py3-none-any.whl -
Subject digest:
2dfb0d105807742cd7e20147b7ca90f6f469aae23aa6fc4ee5e29f4b5f9aacd2 - Sigstore transparency entry: 2476388326
- Sigstore integration time:
-
Permalink:
muhlba91/onyx-client@a61cd69ea1d7550d75f7528c04413bd318d22db0 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/muhlba91
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@a61cd69ea1d7550d75f7528c04413bd318d22db0 -
Trigger Event:
push
-
Statement type:
