Skip to content

Update README and driver description #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zehnm merged 1 commit into from
Apr 17, 2025
Merged

Update README and driver description #67

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 76 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
Expand All @@ -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:

Expand All @@ -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<br>Default: no tracing |
| UC_HASS_MSG_TRACING | `all` / `in` / `out` | Enables incoming and outgoing Home Assistant WS message tracing<br>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.

Expand Down Expand Up @@ -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).
Expand Down
15 changes: 8 additions & 7 deletions resources/driver.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -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."
}
}
}
Expand Down
Loading