Skip to content

Home Assistant integration (HACS) for Hella's ONYX.CENTER appliance

License

Notifications You must be signed in to change notification settings

muhlba91/onyx-homeassistant-integration

Repository files navigation

Hella ONYX.CENTER Custom Component for Home Assistant

hacs_badge Buy Me A Coffee

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

Limitations

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

Realtime Updates / Streaming API

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.


Installation

I recommend installation through HACS:

  • Ensure HACS is installed.
  • Search for and install the Hella ONYX.CENTER integration.

Releases / Versions

The integration offers the following possibilities:

  • main: the latest stable release
  • v*: releases following semantic versioning - if you need to pin the version, choose one of those

Configuration

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.

Entities

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:


Development

The project uses poetry and to install all dependencies and the build environment, run:

pip install poetry
poetry install

Testing

  1. Install all dependencies as shown above.
  2. Run pytest by:
poetry run pytest
# or
pytest

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 .

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

🚧 💻 📖
mrogin-technic
mrogin-technic

🤔
Chris Jibber
Chris Jibber

🤔
Fabian
Fabian

🤔
tbarth64
tbarth64

🤔 🐛

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