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.
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. |
| Local Address | Your ONYX.CENTER local IP address. |
| Interpolation Frequency | Frequency (in ms) to interpolate the position or light intensity while moving. A lower value results in smoother transitions but more updates. Set to 0 to disable interpolation. (Default: 5000) |
| Additional Delay for forced STOP | Additional delay (in ms) to wait before sending a forced STOP command to update the shutter position. (Default: 1000) |
| [Lights] Minimum Dim Duration | The minimum dim duration to use when dimming a light. (Default: 200) |
| [Lights] Maximum Dim Duration | The maximum dim duration to use when dimming a light. (Default: 200) |
| 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. |
| 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.
To use local API access, you need to provide the local IP address of your ONYX.CENTER device. Additionally, follow Authentication to provide the necessary credentials.
If a local address is provided, the integration will always try to connect to the local API.
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. :)
