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

Folders and files

NameName
Last commit message
Last commit date

Latest commit

f50f17d · Nov 24, 2021

History

36 Commits
Nov 24, 2021
Nov 24, 2021
Nov 24, 2021
Feb 9, 2021
Feb 9, 2021
Feb 9, 2021
Feb 12, 2021
Nov 24, 2021
Feb 9, 2021
Feb 9, 2021
Nov 24, 2021
Nov 24, 2021
Nov 24, 2021
Nov 24, 2021

Repository files navigation

Hella ONYX.CENTER Custom Component for Home Assistant

hacs_badge Buy Me A Coffee

This component creates an integration that provides raffstore/shutter entities to control Hella's ONYX.CENTER via Home Assistant.


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
Fingerprint, Access Token Authentication The API requires the ONYX.CENTER fingerprint and an access token. Basically, those can be retrieved programmatically, which is not implemented yet. Personal Needs
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

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.

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
  • next: the next, cutting-edge release (attention: may be unstable)
  • 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
Fingerprint Your ONYX.CENTER fingerprint (see below).
Access Token The access token (see below).
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.

Important! Please read ONYX.CENTER API's Access Control on how to retrieve the fingerprint and access token.

Once configured, the integration creates entities for:

Entity Description
Cover Manage the shutter. (API Reference)
Sensor (Device Type) The device type of the shutter. (API Reference)

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 flakehell as a wrapper for flake8, and black for automated code style 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 black:
$ poetry run black .
  1. Run flakehell:
$ poetry run flakehell lint

Commit Message

This project follows Conventional Commits, and your commit message must also adhere to the additional rules outlined in .conform.yaml.


Release

To draft a release, use standard-version:

$ standard-version
# alternatively
$ npx standard-version

Finally, push with tags:

$ git push --follow-tags

Note: releasing is automated through the master branch!


Contributions

Please feel free to contribute, be it with Issues or Pull Requests! Please read the Contribution guidelines

Supporting

If you enjoy the application and want to support my efforts, please feel free to buy me a coffe. :)

Buy Me A Coffee