diff --git a/README.md b/README.md index 3b6f582..028e28f 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,86 @@ [![Rust](https://github.com/unfoldedcircle/integration-home-assistant/actions/workflows/build.yml/badge.svg)](https://github.com/unfoldedcircle/integration-home-assistant/actions/workflows/build.yml) -# Home-Assistant Integration for Remote Two +# Home-Assistant Integration for Remote Two/3 -This service application connects [Home Assistant](https://www.home-assistant.io/) with the -[Remote Two](https://www.unfoldedcircle.com/) and allows to interact with most entities on the remote. +This integration connects [Home Assistant](https://www.home-assistant.io/) (HA) with the +[Remote Two/3](https://www.unfoldedcircle.com/) and allows to interact with most Home Assistant entities on the remote. +Only a single HA server is supported. -The integration is included in the Remote Two firmware and no external service must be run to connect Home Assistant -with Remote Two. The standalone service can be used for development or connecting multiple Home Assistant servers. +The integration is included in the Remote firmware and no external service must be run to connect Home Assistant +with Remote Two/3. It can be run as an external integration for development or connecting multiple servers. -The integration implements the Remote Two [Integration-API](https://github.com/unfoldedcircle/core-api) which -communicates with JSON messages over WebSocket. - -The WebSocket server and client uses [Actix Web](https://actix.rs/) with the Actix actor system for internal service -communication. +The integration requires WebSocket API access to communicate with Home Assistant. +See [Home Assistant documentation](https://www.home-assistant.io/docs/authentication/) for more information on how to +create a long-lived access token. +When using the 3rd party [Unfolded Circle for Home Assistant component](https://github.com/JackJPowell/hass-unfoldedcircle), +the connection parameters are automatically configured, and you don't need to manually set an access token. -## Container Image +The integration implements the Remote Two [Integration-API](https://github.com/unfoldedcircle/core-api) which +communicates with JSON messages over WebSocket. The WebSocket server and client uses [Actix Web](https://actix.rs/) +with the Actix actor system for internal service communication. + +## Supported Home Assistant entities + +The following HA entities are supported in the Unfolded Circle Remote: + +- [Button](https://developers.home-assistant.io/docs/core/entity/button/) +- [Climate](https://developers.home-assistant.io/docs/core/entity/climate) + - Supported: on/off, heat, cool, current temperature, target temperature. + - Fan modes are planned, but not yet supported. +- [Cover](https://developers.home-assistant.io/docs/core/entity/cover) + - Supported: open, close, stop, set position. + - Tilt features are planned, but not yet supported. +- [Light](https://developers.home-assistant.io/docs/core/entity/light) + - Supported: on/off, dimming, set color, set color temperature. + - Color effects are not supported. +- [Media player](https://developers.home-assistant.io/docs/core/entity/media-player) + - Media browsing, playlist handling, group members are not supported. +- [Remote](https://developers.home-assistant.io/docs/core/entity/remote) + - Supported: on, off, toggle, command, sequence. + - Activities and command learning / deleting are not supported. +- [Sensor](https://developers.home-assistant.io/docs/core/entity/sensor) +- [Switch](https://developers.home-assistant.io/docs/core/entity/switch) +- [Input boolean](https://www.home-assistant.io/integrations/input_boolean/): mapped to switch +- [Binary sensor](https://www.home-assistant.io/integrations/binary_sensor/): mapped to sensor + +The following HA integrations are mapped to a button. The functionality is limited to trigger the default action and no +further interactions are possible: + +- [Input button](https://www.home-assistant.io/integrations/input_button/) +- [Scripts](https://www.home-assistant.io/integrations/script/) +- [Scenes](https://www.home-assistant.io/integrations/scene/) + +## Network requirements + +- The [Home Assistant WebSocket API](https://www.home-assistant.io/integrations/websocket_api/) endpoint must be + accessible by the Remote. + - The default url is: `ws://homeassistant.local:8123/api/websocket` +- A direct connection without SSL (`ws://` connection) from the Remote to the Home Assistant API is recommended when + used in same internal network. + - We cannot provide support for custom installations with reverse proxy, SSL setups, changed endpoints or URLs. + - Self-signed certificates are not supported and don’t work. + - If only an SSL endpoint is exposed, then the `wss://` connection URL must be used in the integration! + - Please note, that not all certificates or SSL setups seem to work. + - It has been successfully tested with Let’s Encrypt certificates and a nginx reverse proxy. + +## Home Assistant requirements + +- A long-lived access token is required for the integration to connect to the Home Assistant server. +- Very large Home Assistant setups require either to increase the message size or use the 3rd party HACS component. + How to increase the message size: + 1. Start the Home Assistant integration setup in the web-configurator. + 2. Select the *Configure enhanced options* checkbox in the first screen and press *Next.* + 3. Increase the “Max. WebSocket frame size”. + 4. Save the new setting by finishing the setup. + +## Usage + +### Container Image See [Docker image](./docker/README.md) for more information. -## Configuration +### Configuration - Optional read-only configuration file to override defaults: [configuration.yaml](configuration.yaml) - User provided Home Integration server settings are written to `$UC_CONFIG_HOME/$UC_USER_CFG_FILENAME` @@ -34,7 +95,7 @@ The configuration values can be overwritten with ENV variables. - ENV prefix: `UC_` - Example: `integration.interface` configuration setting: `UC_INTEGRATION_INTERFACE=127.0.0.1` -### Environment Variables +#### Environment Variables The following environment variables exist in addition to the configuration file: @@ -47,7 +108,7 @@ The following environment variables exist in addition to the configuration file: | UC_API_MSG_TRACING | `all` / `in` / `out` | Enables incoming and outgoing WS Core-API message tracing
Default: no tracing | | UC_HASS_MSG_TRACING | `all` / `in` / `out` | Enables incoming and outgoing Home Assistant WS message tracing
Default: no tracing | -On the Remote Two device, the integration is configured for the embedded runtime environment with several environment +On the Unfolded Remote device, the integration is configured for the embedded runtime environment with several environment variables. Mainly `UC_DISABLE_MDNS_PUBLISH=true`, `UC_CONFIG_HOME` and some `UC_INTEGRATION_*` to listen on the local interface only. @@ -88,7 +149,7 @@ cargo run ## Home Assistant WebSocket API test tool The [bin/ha_test.rs](src/bin/ha_test.rs) tool is a simple CLI tool to test the Home Assistant WebSocket API connectivity -with the exact same code & logic as the HA integration for Remote Two. +with the exact same code & logic as the HA integration for Remote Two/3. The main purpose of this tool is to troubleshoot connectivity issues from a PC. Linux, macOS and Windows x86 binaries are automatically built with a GitHub action and attached to [GitHub releases](https://github.com/unfoldedcircle/integration-home-assistant/releases). diff --git a/resources/driver.json b/resources/driver.json index 79a5dde..1c5e90e 100644 --- a/resources/driver.json +++ b/resources/driver.json @@ -13,13 +13,14 @@ }, "icon": "uc:integration", "description": { - "en": "Control Home Assistant entities with Remote Two.", - "de": "Steuere Home Assistant Entitäten mit Remote Two.", - "fr": "Contrôler les entités de Home Assistant avec Remote Two." + "en": "Control Home Assistant entities with Remote Two/3.", + "de": "Steuere Home Assistant Entitäten mit Remote Two/3.", + "fr": "Contrôler les entités de Home Assistant avec Remote Two/3." }, "developer": { "name": "Unfolded Circle ApS", - "url": "https://www.unfoldedcircle.com" + "email": "hello@unfoldedcircle.com", + "url": "https://support.unfoldedcircle.com/hc/en-us/articles/19479726340380" }, "home_page": "https://www.unfoldedcircle.com", "setup_data_schema": { @@ -38,9 +39,9 @@ "field": { "label": { "value": { - "en": "The driver requires WebSocket API access to communicate with Home Assistant.\nSee [Home Assistant documentation](https://www.home-assistant.io/docs/authentication/) for more information on how to create a long lived access token.\n\nWhen using the [Unfolded Circle for Home Assistant component](https://github.com/JackJPowell/hass-unfoldedcircle), the connection parameters are automatically configured and you don't need to manually set an access token.\n\nThe _enhanced options_ below can be used to change expert connection parameters.", - "de": "Der Treiber benötigt WebSocket-API Zugriff, um mit Home Assistant zu kommunizieren.\nWeitere Informationen zur Erstellung eines langlebigen Zugriffstokens findest du in der [Home Assistant Dokumentation](https://www.home-assistant.io/docs/authentication/).\n\nWenn Du die [Unfolded Circle for Home Assistant](https://github.com/JackJPowell/hass-unfoldedcircle) Komponente verwendest, werden die Verbindungsparameter automatisch konfiguriert, und Du musst kein Zugriffstoken manuell setzen.\n\nMit den _erweiterten Optionen_ können Experten-Verbindungsparameter geändert werden.", - "fr": "Le pilote nécessite l'accès à l'API WebSocket pour communiquer avec Home Assistant.\nVoir [Home Assistant documentation](https://www.home-assistant.io/docs/authentication/) pour plus d'informations sur la création d'un \"long lived access token\".\n\nLorsque vous utilisez le composant [Unfolded Circle for Home Assistant](https://github.com/JackJPowell/hass-unfoldedcircle), les paramètres de connexion sont automatiquement configurés et vous n'avez pas besoin de définir manuellement un jeton d'accès.\n\nLes _options avancées_ ci-dessous peuvent être utilisées pour modifier les paramètres de connexion des experts." + "en": "The driver requires WebSocket API access to communicate with Home Assistant.\nSee [Home Assistant documentation](https://www.home-assistant.io/docs/authentication/) for more information on how to create a long lived access token.\n\nWhen using the [Unfolded Circle for Home Assistant component](https://github.com/JackJPowell/hass-unfoldedcircle), the connection parameters are automatically configured and you don't need to manually set an access token.\n\nThe _enhanced options_ below can be used to change expert connection parameters.\n\nPlease see our [support article](https://support.unfoldedcircle.com/hc/en-us/articles/19479726340380) for requirements, features and restrictions.", + "de": "Der Treiber benötigt WebSocket-API Zugriff, um mit Home Assistant zu kommunizieren.\nWeitere Informationen zur Erstellung eines langlebigen Zugriffstokens findest du in der [Home Assistant Dokumentation](https://www.home-assistant.io/docs/authentication/).\n\nWenn Du die [Unfolded Circle for Home Assistant](https://github.com/JackJPowell/hass-unfoldedcircle) Komponente verwendest, werden die Verbindungsparameter automatisch konfiguriert, und Du musst kein Zugriffstoken manuell setzen.\n\nMit den _erweiterten Optionen_ können Experten-Verbindungsparameter geändert werden.\n\nBitte beachte unseren [Support-Artikel](https://support.unfoldedcircle.com/hc/en-us/articles/19479726340380) zu Anforderungen, unterstützten Funktionen und Einschränkungen.", + "fr": "Le pilote nécessite l'accès à l'API WebSocket pour communiquer avec Home Assistant.\nVoir [Home Assistant documentation](https://www.home-assistant.io/docs/authentication/) pour plus d'informations sur la création d'un \"long lived access token\".\n\nLorsque vous utilisez le composant [Unfolded Circle for Home Assistant](https://github.com/JackJPowell/hass-unfoldedcircle), les paramètres de connexion sont automatiquement configurés et vous n'avez pas besoin de définir manuellement un jeton d'accès.\n\nLes _options avancées_ ci-dessous peuvent être utilisées pour modifier les paramètres de connexion des experts.\n\nConsulte [l’article de support](https://support.unfoldedcircle.com/hc/en-us/articles/19479726340380) pour connaître les exigences, les fonctionnalités prises en charge et les restrictions." } } }