This component creates an integration that provides the following entities to control Hella's ONYX.CENTER via Home Assistant:
- raffstore/shutter entities
- (dimmable) light entities
- weather station sensor entities
This integration is under development and based on personal needs and Hella's API design and Home Assistant's interpretation of values diverges in a few aspects.
Therefore, a few limitations are imposed on/by this integration:
| Limitation | Description | Bound By |
|---|---|---|
| Shutter Position | Home Assistant takes the position 0 as closed and 100 as open, Hella the opposite. | Home Assistant |
| Tilt Position | Home Assistant takes the position 0 as closed and 100 as open, Hella's values range between 0-90 and 0-180. | Home Assistant / Hella |
| Light Brightness | Home Assistant takes the dim value 0 as off and 100 as on, Hella's values range between 0-65535. | Home Assistant / Hella |
Since v2 of the ONYX API, a dedicated event streaming endpoint is available which pushed occurring events from the
ONYX.CENTER to all clients; however, pushes only include partial updates.
The integration makes use of this and keeps a connection open to the ONYX API server to update the devices in near-realtime. Since exceptions can occur, and the endpoint only pushes partial updates, all device states are updated periodically as well to ensure current states are available and correct. Please ensure a proper update interval, suggested is anywhere between 30-180 minutes.
This integration uses API v3.
Warning
The streaming API uses a HTTP GET request which, unfortunately, is timing out and ending the connection every ~10 minutes. Currently, the client is reconnecting after a short backoff time.
Hence, errors in your Home Assistant log like [onyx_client.client] Unexpected exception: ClientPayloadError('Response payload is not completed'). Retrying with backoff Xs. are to be expected.
The issue is tracked here: #30.
I recommend installation through HACS:
- Ensure HACS is installed.
- Search for and install the
Hella ONYX.CENTERintegration.
The integration offers the following possibilities:
main: the latest stable releasev*: releases following semantic versioning - if you need to pin the version, choose one of those
Add it from the Integrations menu, set the configuration, and you're good to go.
| Configuration Key | Description |
|---|---|
| API Code | The code retrieved by the ONYX app when allowing a new client to connect. |
| Fingerprint | Your ONYX.CENTER fingerprint. |
| Access Token | The access token. |
| Scan Interval | Interval for polling for updates. This is used as a fallback if near realtime updates are failing and can be set to a higher value. |
| [Lights] Minimum Dim Duration | The minimum dim duration to use when dimming a light. (Default: 200) |
| Disable partial updates? | The integration relies on the streaming API. Hence, only partial device data will be retrieved. Enable this option to always retrieve the full device data. Attention: this may lead to more API requests and is discouraged. |
To configure the integration you can either directly specify a fingerprint and an access token or use the issued API code from the ONYX app directly. The integration will then exchange this code through the API to retrieve the fingerprint and access token for your ONYX.CENTER.
Once configured, the integration creates entities for:
| Entity | Description |
|---|---|
| Cover | Manage the shutter. (API Reference) |
| Light | Manage the (dimmable) light. (API Reference) |
| Sensor (Device Type) | The device type of the ONYX device. (API Reference) |
| Sensor (Weather Humidity) | The humidity of the weather sensor. (API Reference) |
| Sensor (Weather Temperature) | The temperature of the weather sensor. (API Reference) |
| Sensor (Weather Air Pressure) | The air pressure of the weather sensor. (API Reference) |
| Sensor (Weather Wind Peak) | The wind peak of the weather sensor. (API Reference) |
| Sensor (Weather Sun Brightness Peak) | The sun brightness peak of the weather sensor. (API Reference) |
| Sensor (Weather Sun Brightness Sink) | The sun brightness sink of the weather sensor. (API Reference) |
The following ONYX devices are only community tested due to the lack of a testing device:
- Light (thank you @clostermannshof)
- Weather Station (thank you @mrogin-technic)
The project uses poetry and to install all dependencies and the build environment, run:
pip install poetry
poetry install- Install all dependencies as shown above.
- Run
pytestby:
poetry run pytest
# or
pytestThe 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 .This project follows Conventional Commits, and your commit message must also
adhere to the additional rules outlined in .conform.yaml.
Thanks goes to these wonderful people (emoji key):
 Daniel Mühlbachler-Pietrzykowski 🚧 💻 📖 |
 mrogin-technic 🤔 |
 Chris Jibber 🤔 |
 Fabian 🤔 |
 tbarth64 🤔 🐛 |
This project follows the all-contributors specification. Contributions of any kind welcome!
If you enjoy the application and want to support my efforts, please feel free to buy me a coffe. :)
