Skip to content

Commit f3714a0

Browse files
zehnmzehnm
authored
docs: update README and driver description (#67)
- Add support link to main driver setup page. - Enhance README with supported entities and requirements from the support article.
1 parent c1b1c6a commit f3714a0

File tree

2 files changed

+84
-22
lines changed

2 files changed

+84
-22
lines changed

‎README.md‎

Lines changed: 76 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,86 @@
11
[![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)
22

3-
# Home-Assistant Integration for Remote Two
3+
# Home-Assistant Integration for Remote Two/3
44

5-
This service application connects [Home Assistant](https://www.home-assistant.io/) with the
6-
[Remote Two](https://www.unfoldedcircle.com/) and allows to interact with most entities on the remote.
5+
This integration connects [Home Assistant](https://www.home-assistant.io/) (HA) with the
6+
[Remote Two/3](https://www.unfoldedcircle.com/) and allows to interact with most Home Assistant entities on the remote.
7+
Only a single HA server is supported.
78

8-
The integration is included in the Remote Two firmware and no external service must be run to connect Home Assistant
9-
with Remote Two. The standalone service can be used for development or connecting multiple Home Assistant servers.
9+
The integration is included in the Remote firmware and no external service must be run to connect Home Assistant
10+
with Remote Two/3. It can be run as an external integration for development or connecting multiple servers.
1011

11-
The integration implements the Remote Two [Integration-API](https://github.com/unfoldedcircle/core-api) which
12-
communicates with JSON messages over WebSocket.
13-
14-
The WebSocket server and client uses [Actix Web](https://actix.rs/) with the Actix actor system for internal service
15-
communication.
12+
The integration requires WebSocket API access to communicate with Home Assistant.
13+
See [Home Assistant documentation](https://www.home-assistant.io/docs/authentication/) for more information on how to
14+
create a long-lived access token.
1615

16+
When using the 3rd party [Unfolded Circle for Home Assistant component](https://github.com/JackJPowell/hass-unfoldedcircle),
17+
the connection parameters are automatically configured, and you don't need to manually set an access token.
1718

18-
## Container Image
19+
The integration implements the Remote Two [Integration-API](https://github.com/unfoldedcircle/core-api) which
20+
communicates with JSON messages over WebSocket. The WebSocket server and client uses [Actix Web](https://actix.rs/)
21+
with the Actix actor system for internal service communication.
22+
23+
## Supported Home Assistant entities
24+
25+
The following HA entities are supported in the Unfolded Circle Remote:
26+
27+
- [Button](https://developers.home-assistant.io/docs/core/entity/button/)
28+
- [Climate](https://developers.home-assistant.io/docs/core/entity/climate)
29+
- Supported: on/off, heat, cool, current temperature, target temperature.
30+
- Fan modes are planned, but not yet supported.
31+
- [Cover](https://developers.home-assistant.io/docs/core/entity/cover)
32+
- Supported: open, close, stop, set position.
33+
- Tilt features are planned, but not yet supported.
34+
- [Light](https://developers.home-assistant.io/docs/core/entity/light)
35+
- Supported: on/off, dimming, set color, set color temperature.
36+
- Color effects are not supported.
37+
- [Media player](https://developers.home-assistant.io/docs/core/entity/media-player)
38+
- Media browsing, playlist handling, group members are not supported.
39+
- [Remote](https://developers.home-assistant.io/docs/core/entity/remote)
40+
- Supported: on, off, toggle, command, sequence.
41+
- Activities and command learning / deleting are not supported.
42+
- [Sensor](https://developers.home-assistant.io/docs/core/entity/sensor)
43+
- [Switch](https://developers.home-assistant.io/docs/core/entity/switch)
44+
- [Input boolean](https://www.home-assistant.io/integrations/input_boolean/): mapped to switch
45+
- [Binary sensor](https://www.home-assistant.io/integrations/binary_sensor/): mapped to sensor
46+
47+
The following HA integrations are mapped to a button. The functionality is limited to trigger the default action and no
48+
further interactions are possible:
49+
50+
- [Input button](https://www.home-assistant.io/integrations/input_button/)
51+
- [Scripts](https://www.home-assistant.io/integrations/script/)
52+
- [Scenes](https://www.home-assistant.io/integrations/scene/)
53+
54+
## Network requirements
55+
56+
- The [Home Assistant WebSocket API](https://www.home-assistant.io/integrations/websocket_api/) endpoint must be
57+
accessible by the Remote.
58+
- The default url is: `ws://homeassistant.local:8123/api/websocket`
59+
- A direct connection without SSL (`ws://` connection) from the Remote to the Home Assistant API is recommended when
60+
used in same internal network.
61+
- We cannot provide support for custom installations with reverse proxy, SSL setups, changed endpoints or URLs.
62+
- Self-signed certificates are not supported and don’t work.
63+
- If only an SSL endpoint is exposed, then the `wss://` connection URL must be used in the integration!
64+
- Please note, that not all certificates or SSL setups seem to work.
65+
- It has been successfully tested with Let’s Encrypt certificates and a nginx reverse proxy.
66+
67+
## Home Assistant requirements
68+
69+
- A long-lived access token is required for the integration to connect to the Home Assistant server.
70+
- Very large Home Assistant setups require either to increase the message size or use the 3rd party HACS component.
71+
How to increase the message size:
72+
1. Start the Home Assistant integration setup in the web-configurator.
73+
2. Select the *Configure enhanced options* checkbox in the first screen and press *Next.*
74+
3. Increase the “Max. WebSocket frame size”.
75+
4. Save the new setting by finishing the setup.
76+
77+
## Usage
78+
79+
### Container Image
1980

2081
See [Docker image](./docker/README.md) for more information.
2182

22-
## Configuration
83+
### Configuration
2384

2485
- Optional read-only configuration file to override defaults: [configuration.yaml](configuration.yaml)
2586
- 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.
3495
- ENV prefix: `UC_`
3596
- Example: `integration.interface` configuration setting: `UC_INTEGRATION_INTERFACE=127.0.0.1`
3697

37-
### Environment Variables
98+
#### Environment Variables
3899

39100
The following environment variables exist in addition to the configuration file:
40101

@@ -47,7 +108,7 @@ The following environment variables exist in addition to the configuration file:
47108
| UC_API_MSG_TRACING | `all` / `in` / `out` | Enables incoming and outgoing WS Core-API message tracing<br>Default: no tracing |
48109
| UC_HASS_MSG_TRACING | `all` / `in` / `out` | Enables incoming and outgoing Home Assistant WS message tracing<br>Default: no tracing |
49110

50-
On the Remote Two device, the integration is configured for the embedded runtime environment with several environment
111+
On the Unfolded Remote device, the integration is configured for the embedded runtime environment with several environment
51112
variables. Mainly `UC_DISABLE_MDNS_PUBLISH=true`, `UC_CONFIG_HOME` and some `UC_INTEGRATION_*` to listen on the local
52113
interface only.
53114

@@ -88,7 +149,7 @@ cargo run
88149
## Home Assistant WebSocket API test tool
89150

90151
The [bin/ha_test.rs](src/bin/ha_test.rs) tool is a simple CLI tool to test the Home Assistant WebSocket API connectivity
91-
with the exact same code & logic as the HA integration for Remote Two.
152+
with the exact same code & logic as the HA integration for Remote Two/3.
92153

93154
The main purpose of this tool is to troubleshoot connectivity issues from a PC. Linux, macOS and Windows x86 binaries
94155
are automatically built with a GitHub action and attached to [GitHub releases](https://github.com/unfoldedcircle/integration-home-assistant/releases).

‎resources/driver.json‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,14 @@
1313
},
1414
"icon": "uc:integration",
1515
"description": {
16-
"en": "Control Home Assistant entities with Remote Two.",
17-
"de": "Steuere Home Assistant Entitäten mit Remote Two.",
18-
"fr": "Contrôler les entités de Home Assistant avec Remote Two."
16+
"en": "Control Home Assistant entities with Remote Two/3.",
17+
"de": "Steuere Home Assistant Entitäten mit Remote Two/3.",
18+
"fr": "Contrôler les entités de Home Assistant avec Remote Two/3."
1919
},
2020
"developer": {
2121
"name": "Unfolded Circle ApS",
22-
"url": "https://www.unfoldedcircle.com"
22+
"email": "hello@unfoldedcircle.com",
23+
"url": "https://support.unfoldedcircle.com/hc/en-us/articles/19479726340380"
2324
},
2425
"home_page": "https://www.unfoldedcircle.com",
2526
"setup_data_schema": {
@@ -38,9 +39,9 @@
3839
"field": {
3940
"label": {
4041
"value": {
41-
"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.",
42-
"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.",
43-
"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."
42+
"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.",
43+
"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.",
44+
"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."
4445
}
4546
}
4647
}

0 commit comments

Comments
 (0)