From 4bff954610b9d8bcf24f2c37cef7c8c0d7a39d6c Mon Sep 17 00:00:00 2001 From: chemaaa <187996+chemaaa@users.noreply.github.com> Date: Wed, 17 Feb 2021 18:56:31 +0100 Subject: [PATCH 1/7] Add Legrand Home+ Control Integration document --- .../legrand_homepluscontrol.markdown | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 source/_integrations/legrand_homepluscontrol.markdown diff --git a/source/_integrations/legrand_homepluscontrol.markdown b/source/_integrations/legrand_homepluscontrol.markdown new file mode 100644 index 000000000000..116d97ebc186 --- /dev/null +++ b/source/_integrations/legrand_homepluscontrol.markdown @@ -0,0 +1,96 @@ +--- +title: Legrand Home+ Control +description: Instructions on how to integrate Legrand Home+ Control into Home Assistant. +ha_category: + - Switch +ha_release: '2021.03' +ha_iot_class: Cloud Polling +ha_codeowners: + - '@chemaaa' +ha_config_flow: true +ha_domain: homepluscontrol +--- + +The `Home+ Control` integration platform allows you to control a range of Legrand in-wall switches and power outlets that have smarthome functionality thanks to their "with Netatmo" capabilities. + +This integration works against the `Home+ Control` API, which is one of the many APIs offered through the *Works with Legrand* program (https://developer.legrand.com/). The API is capable of managing "Legrand/Btcino with Netatmo" devices, such as light switches, power outlets and rolling shutters. + +The devices that this API can manage are offered in different designs across different countries. The details of these can be found in the following page: https://developer.legrand.com/solutions/wiring-devices-with-netatmo/ + +Legrand offers the Home+ Control smartphone app to manage these devices. You can find this app in the Google Play and Apple App stores. + +This `Home+ Control` integration for Home Assitant currently has support for the following devices: +- Light switches +- Power outlets + +In both cases, the devices are modelled as simple on/off switches within Home Assistant. + +This integration has been tested to work with the following range of Legrand products: +- Valena Next™ with Netatmo + +{% include integrations/config_flow.md %} + +## Authentication +Before you are able to configure the Legrand `Home + Control` integration into Home Assistant, you must register with the *Works with Legrand* platform. + +These Legrand APIs rely on Oauth2 authentication, so you must follow these steps to obtain the necessary authentication parameters: + +1) Register an account at https://developer.legrand.com/ +2) Create a subscription to the *Starter Kit* (currently the only subscription available) and this will generate your SUBSCRIPTION_KEY. +3) Register an Application, where you will have to define a name, a redirect URL and the scopes of your application (for simplicity you can mark all scopes). + +Once the registered Application is confirmed, you should receive an email containing the CLIENT_IDENTIFIER and the CLIENT_SECRET which you will be using to set up the authentication flows. The Application confirmation email is usually received within a few hours of having issued the request. + +### Authentication Flow +Communication with the API, first requires Oauth2 authentication to obtain an access and a refresh token. Subsequent requests to the API, require the use of the SUBSCRIPTION_KEY in addition to the access token. + +Information about the Oauth2 exchange is provided here: https://developer.legrand.com/tutorials/0auth2-end-point-url/ + +As part of the authentication exchange, a callback request is made to the REDIRECT_URL that was entered when you registered the application with the *Works with Legrand* platform. This redirect URL will take on the default value of your Home Assistant instance URL, but because this could differ from the URL that you entered in the Legrand registration form, the integration allows you to explicitly specify the redirect URL parameter that you would like to use. + +## Polling Interval Configuration +The Legrand `Home+ Control` API is a cloud-based polling interface. This Home Assistant integration presents 3 different polling intervals: +1) Plant information request +2) Plant topology request +3) Module status request + +Refer to the [nomenclature](#api-nomenclature) section for details of what these names mean. +Refer to the [API limitations](#api-limitations) section to better understand the reason for these polling intervals. + +### Plant Information Request +This call retrieves the information of the plants that are associated to a user. It is assumed that this information does not change very often. For the most part, a user will have a single *Legrand Home+ Control* gateway in their home, i.e. a single *plant*, and this will not change frequently. + +For this reason, the default polling interval for the plant information is set to a large value: 7200 seconds (2 hours). + +### Plant Topology Request +This call retrieves the *layout* of the devices that make up a *plant*. This provide the list of device, their names and some additional information of the devices (but not their status). + +It is assumed that plant topology is not changing very often, so the default polling interval for this information is set to a default value of 3600 seconds (1 hour). + +### Module Status Request +This call retrieves the current operating status of the devices that make up the plant's topology - this includes the *reachability* of the device and its on/off status. + +This information is expected to change frequently, so the polling interval is set to a lower default value of 300 seconds (5 minutes). This is still not as frequent as would be ideal, but is still reasonable considering the API's calls-per-day limitation. + + +## API Nomenclature +Within the context of the `Home+ Control` API you may come across the following terms: +* *Plant*: This is the term used to represent a *home* that holds the Legrand devices. In practice, a *plant* is represented by the *Legrand Home+ Control* gateway that acts as the central hub of the rest of the devices in the home network (uses Zigbee). +* *Module*: This is the term used to represent a generic device within the *plant*, i.e. a light, a plug, a remote, etc. +* *Light*: This is the term used to represent a light switch (or a micro-module). It is not modeled as your usual light entity because there are no brightness, color, etc. controls. It is modeled as a simple on/off switch component. +* *Plug*: This is the term used to represent a power outlet. + +Other devices that are mentioned in the API, but that are not currently supported by this integration are: *remotes* (wireless switches), *heaters* and *automations*. + +## API Limitations +As mentioned in the [authentication](#authentication) section, this integration requires you to set up a subscription in the *Works with Legrand* platform. + +Currently, end-users only have access to the *Starter Kit* subscription which has a major limitation in the number of allowed API requests that are allowed - only 500 API calls per day (counter is reset at 00:00 every day). + +This means that the integration has to set default polling intervals that are considerably larger than one would want for a Home Assistant integration. These intervals are [configurable](#polling-interval-configuration), but take care not to exceed the daily quota to prevent the integration from failing with `403 Forbidden` HTTP responses. + + + + + + From 441e373759a1977bbe8926b2299eab6ccb63f29c Mon Sep 17 00:00:00 2001 From: chemaaa <187996+chemaaa@users.noreply.github.com> Date: Fri, 19 Feb 2021 14:51:37 +0100 Subject: [PATCH 2/7] Fix textlint failures. --- source/_integrations/legrand_homepluscontrol.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/legrand_homepluscontrol.markdown b/source/_integrations/legrand_homepluscontrol.markdown index 116d97ebc186..334fe546f2fe 100644 --- a/source/_integrations/legrand_homepluscontrol.markdown +++ b/source/_integrations/legrand_homepluscontrol.markdown @@ -19,7 +19,7 @@ The devices that this API can manage are offered in different designs across dif Legrand offers the Home+ Control smartphone app to manage these devices. You can find this app in the Google Play and Apple App stores. -This `Home+ Control` integration for Home Assitant currently has support for the following devices: +This `Home+ Control` integration for Home Assistant currently has support for the following devices: - Light switches - Power outlets @@ -70,7 +70,7 @@ It is assumed that plant topology is not changing very often, so the default pol ### Module Status Request This call retrieves the current operating status of the devices that make up the plant's topology - this includes the *reachability* of the device and its on/off status. -This information is expected to change frequently, so the polling interval is set to a lower default value of 300 seconds (5 minutes). This is still not as frequent as would be ideal, but is still reasonable considering the API's calls-per-day limitation. +This information is expected to change frequently, so the polling interval is set to a lower default value of 300 seconds (5 minutes). This is still not as frequent as would be ideal, but is still reasonable considering the API calls-per-day limitation. ## API Nomenclature From 8bad8c6c4efb6aedf6b2c264bf67bc6d8f59969f Mon Sep 17 00:00:00 2001 From: chemaaa <187996+chemaaa@users.noreply.github.com> Date: Sun, 28 Feb 2021 08:11:10 +0100 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Klaas Schoute --- source/_integrations/legrand_homepluscontrol.markdown | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/source/_integrations/legrand_homepluscontrol.markdown b/source/_integrations/legrand_homepluscontrol.markdown index 334fe546f2fe..a6173858a9ca 100644 --- a/source/_integrations/legrand_homepluscontrol.markdown +++ b/source/_integrations/legrand_homepluscontrol.markdown @@ -31,6 +31,7 @@ This integration has been tested to work with the following range of Legrand pro {% include integrations/config_flow.md %} ## Authentication + Before you are able to configure the Legrand `Home + Control` integration into Home Assistant, you must register with the *Works with Legrand* platform. These Legrand APIs rely on Oauth2 authentication, so you must follow these steps to obtain the necessary authentication parameters: @@ -42,6 +43,7 @@ These Legrand APIs rely on Oauth2 authentication, so you must follow these steps Once the registered Application is confirmed, you should receive an email containing the CLIENT_IDENTIFIER and the CLIENT_SECRET which you will be using to set up the authentication flows. The Application confirmation email is usually received within a few hours of having issued the request. ### Authentication Flow + Communication with the API, first requires Oauth2 authentication to obtain an access and a refresh token. Subsequent requests to the API, require the use of the SUBSCRIPTION_KEY in addition to the access token. Information about the Oauth2 exchange is provided here: https://developer.legrand.com/tutorials/0auth2-end-point-url/ @@ -49,6 +51,7 @@ Information about the Oauth2 exchange is provided here: https://developer.legran As part of the authentication exchange, a callback request is made to the REDIRECT_URL that was entered when you registered the application with the *Works with Legrand* platform. This redirect URL will take on the default value of your Home Assistant instance URL, but because this could differ from the URL that you entered in the Legrand registration form, the integration allows you to explicitly specify the redirect URL parameter that you would like to use. ## Polling Interval Configuration + The Legrand `Home+ Control` API is a cloud-based polling interface. This Home Assistant integration presents 3 different polling intervals: 1) Plant information request 2) Plant topology request @@ -58,22 +61,26 @@ Refer to the [nomenclature](#api-nomenclature) section for details of what these Refer to the [API limitations](#api-limitations) section to better understand the reason for these polling intervals. ### Plant Information Request + This call retrieves the information of the plants that are associated to a user. It is assumed that this information does not change very often. For the most part, a user will have a single *Legrand Home+ Control* gateway in their home, i.e. a single *plant*, and this will not change frequently. For this reason, the default polling interval for the plant information is set to a large value: 7200 seconds (2 hours). ### Plant Topology Request + This call retrieves the *layout* of the devices that make up a *plant*. This provide the list of device, their names and some additional information of the devices (but not their status). It is assumed that plant topology is not changing very often, so the default polling interval for this information is set to a default value of 3600 seconds (1 hour). ### Module Status Request + This call retrieves the current operating status of the devices that make up the plant's topology - this includes the *reachability* of the device and its on/off status. This information is expected to change frequently, so the polling interval is set to a lower default value of 300 seconds (5 minutes). This is still not as frequent as would be ideal, but is still reasonable considering the API calls-per-day limitation. ## API Nomenclature + Within the context of the `Home+ Control` API you may come across the following terms: * *Plant*: This is the term used to represent a *home* that holds the Legrand devices. In practice, a *plant* is represented by the *Legrand Home+ Control* gateway that acts as the central hub of the rest of the devices in the home network (uses Zigbee). * *Module*: This is the term used to represent a generic device within the *plant*, i.e. a light, a plug, a remote, etc. @@ -83,6 +90,7 @@ Within the context of the `Home+ Control` API you may come across the following Other devices that are mentioned in the API, but that are not currently supported by this integration are: *remotes* (wireless switches), *heaters* and *automations*. ## API Limitations + As mentioned in the [authentication](#authentication) section, this integration requires you to set up a subscription in the *Works with Legrand* platform. Currently, end-users only have access to the *Starter Kit* subscription which has a major limitation in the number of allowed API requests that are allowed - only 500 API calls per day (counter is reset at 00:00 every day). @@ -93,4 +101,3 @@ This means that the integration has to set default polling intervals that are co - From 701941f8a577d26ddaf2f753aabc46f25191b56a Mon Sep 17 00:00:00 2001 From: chemaaa <187996+chemaaa@users.noreply.github.com> Date: Wed, 3 Mar 2021 20:56:40 +0100 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Franck Nijhof --- .../legrand_homepluscontrol.markdown | 41 +++++++++---------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/source/_integrations/legrand_homepluscontrol.markdown b/source/_integrations/legrand_homepluscontrol.markdown index a6173858a9ca..f64dc49c6a76 100644 --- a/source/_integrations/legrand_homepluscontrol.markdown +++ b/source/_integrations/legrand_homepluscontrol.markdown @@ -11,19 +11,19 @@ ha_config_flow: true ha_domain: homepluscontrol --- -The `Home+ Control` integration platform allows you to control a range of Legrand in-wall switches and power outlets that have smarthome functionality thanks to their "with Netatmo" capabilities. +The Home+ Control integration platform allows you to control a range of Legrand in-wall switches and power outlets that have smart home functionality thanks to their "with Netatmo" capabilities. -This integration works against the `Home+ Control` API, which is one of the many APIs offered through the *Works with Legrand* program (https://developer.legrand.com/). The API is capable of managing "Legrand/Btcino with Netatmo" devices, such as light switches, power outlets and rolling shutters. +This integration works against the Home+ Control API, which is one of the many APIs offered through the *Works with Legrand* program (https://developer.legrand.com/). The API is capable of managing "Legrand/Btcino with Netatmo" devices, such as light switches, power outlets and rolling shutters. The devices that this API can manage are offered in different designs across different countries. The details of these can be found in the following page: https://developer.legrand.com/solutions/wiring-devices-with-netatmo/ Legrand offers the Home+ Control smartphone app to manage these devices. You can find this app in the Google Play and Apple App stores. -This `Home+ Control` integration for Home Assistant currently has support for the following devices: +This Home+ Control integration for Home Assistant currently has support for the following devices: - Light switches - Power outlets -In both cases, the devices are modelled as simple on/off switches within Home Assistant. +In both cases, the devices are modeled as on/off switches within Home Assistant. This integration has been tested to work with the following range of Legrand products: - Valena Next™ with Netatmo @@ -32,15 +32,15 @@ This integration has been tested to work with the following range of Legrand pro ## Authentication -Before you are able to configure the Legrand `Home + Control` integration into Home Assistant, you must register with the *Works with Legrand* platform. +Before you are able to configure the Legrand Home + Control integration into Home Assistant, you must register with the *Works with Legrand* platform. These Legrand APIs rely on Oauth2 authentication, so you must follow these steps to obtain the necessary authentication parameters: -1) Register an account at https://developer.legrand.com/ -2) Create a subscription to the *Starter Kit* (currently the only subscription available) and this will generate your SUBSCRIPTION_KEY. -3) Register an Application, where you will have to define a name, a redirect URL and the scopes of your application (for simplicity you can mark all scopes). +1. Register an account at . +2. Create a subscription to the *Starter Kit* (currently the only subscription available) and this will generate your `SUBSCRIPTION_KEY`. +3. Register an application, where you will have to define a name, a redirect URL and the scopes of your application (for simplicity you can mark all scopes). -Once the registered Application is confirmed, you should receive an email containing the CLIENT_IDENTIFIER and the CLIENT_SECRET which you will be using to set up the authentication flows. The Application confirmation email is usually received within a few hours of having issued the request. +Once the registered application is confirmed, you should receive an email containing the `CLIENT_IDENTIFIER` and the `CLIENT_SECRET` which you will be using to set up the authentication flows. The application confirmation email is usually received within a few hours of having issued the request. ### Authentication Flow @@ -53,22 +53,23 @@ As part of the authentication exchange, a callback request is made to the REDIRE ## Polling Interval Configuration The Legrand `Home+ Control` API is a cloud-based polling interface. This Home Assistant integration presents 3 different polling intervals: -1) Plant information request -2) Plant topology request -3) Module status request + +- Plant information request +- Plant topology request +- Module status request Refer to the [nomenclature](#api-nomenclature) section for details of what these names mean. Refer to the [API limitations](#api-limitations) section to better understand the reason for these polling intervals. ### Plant Information Request -This call retrieves the information of the plants that are associated to a user. It is assumed that this information does not change very often. For the most part, a user will have a single *Legrand Home+ Control* gateway in their home, i.e. a single *plant*, and this will not change frequently. +This call retrieves the information of the plants that are associated with a user. It is assumed that this information does not change very often. For the most part, a user will have a single *Legrand Home+ Control* gateway in their home, i.e., a single *plant*, and this will not change frequently. For this reason, the default polling interval for the plant information is set to a large value: 7200 seconds (2 hours). ### Plant Topology Request -This call retrieves the *layout* of the devices that make up a *plant*. This provide the list of device, their names and some additional information of the devices (but not their status). +This call retrieves the *layout* of the devices that make up a *plant*. This provides the list of devices, their names and some additional information about the devices (but not their status). It is assumed that plant topology is not changing very often, so the default polling interval for this information is set to a default value of 3600 seconds (1 hour). @@ -81,10 +82,11 @@ This information is expected to change frequently, so the polling interval is se ## API Nomenclature -Within the context of the `Home+ Control` API you may come across the following terms: +Within the context of the Home+ Control API you may come across the following terms: + * *Plant*: This is the term used to represent a *home* that holds the Legrand devices. In practice, a *plant* is represented by the *Legrand Home+ Control* gateway that acts as the central hub of the rest of the devices in the home network (uses Zigbee). -* *Module*: This is the term used to represent a generic device within the *plant*, i.e. a light, a plug, a remote, etc. -* *Light*: This is the term used to represent a light switch (or a micro-module). It is not modeled as your usual light entity because there are no brightness, color, etc. controls. It is modeled as a simple on/off switch component. +* *Module*: This is the term used to represent a generic device within the *plant*, i.e., a light, a plug, a remote, etc. +* *Light*: This is the term used to represent a light switch (or a micro-module). It is not modeled as your usual light entity because there are no brightness, color, etc. controls. It is modeled as an on/off switch. * *Plug*: This is the term used to represent a power outlet. Other devices that are mentioned in the API, but that are not currently supported by this integration are: *remotes* (wireless switches), *heaters* and *automations*. @@ -96,8 +98,3 @@ As mentioned in the [authentication](#authentication) section, this integration Currently, end-users only have access to the *Starter Kit* subscription which has a major limitation in the number of allowed API requests that are allowed - only 500 API calls per day (counter is reset at 00:00 every day). This means that the integration has to set default polling intervals that are considerably larger than one would want for a Home Assistant integration. These intervals are [configurable](#polling-interval-configuration), but take care not to exceed the daily quota to prevent the integration from failing with `403 Forbidden` HTTP responses. - - - - - From ac569b0a5198a4a9d402e1bd3cb7dfd7c3594fde Mon Sep 17 00:00:00 2001 From: chemaaa <187996+chemaaa@users.noreply.github.com> Date: Sat, 6 Mar 2021 07:36:31 +0100 Subject: [PATCH 5/7] Rename the file markdown file to match the new component name. --- ...ol.markdown => home_plus_control.markdown} | 61 +++++++++++++++---- 1 file changed, 48 insertions(+), 13 deletions(-) rename source/_integrations/{legrand_homepluscontrol.markdown => home_plus_control.markdown} (68%) diff --git a/source/_integrations/legrand_homepluscontrol.markdown b/source/_integrations/home_plus_control.markdown similarity index 68% rename from source/_integrations/legrand_homepluscontrol.markdown rename to source/_integrations/home_plus_control.markdown index f64dc49c6a76..870c6ca0afd1 100644 --- a/source/_integrations/legrand_homepluscontrol.markdown +++ b/source/_integrations/home_plus_control.markdown @@ -8,16 +8,14 @@ ha_iot_class: Cloud Polling ha_codeowners: - '@chemaaa' ha_config_flow: true -ha_domain: homepluscontrol +ha_domain: home_plus_control --- The Home+ Control integration platform allows you to control a range of Legrand in-wall switches and power outlets that have smart home functionality thanks to their "with Netatmo" capabilities. -This integration works against the Home+ Control API, which is one of the many APIs offered through the *Works with Legrand* program (https://developer.legrand.com/). The API is capable of managing "Legrand/Btcino with Netatmo" devices, such as light switches, power outlets and rolling shutters. +This integration works against the Home+ Control API, which is one of the many APIs offered through the [*Works with Legrand*](https://developer.legrand.com/) program. The API is capable of managing "Legrand/Btcino with Netatmo" devices, such as light switches, power outlets and rolling shutters. -The devices that this API can manage are offered in different designs across different countries. The details of these can be found in the following page: https://developer.legrand.com/solutions/wiring-devices-with-netatmo/ - -Legrand offers the Home+ Control smartphone app to manage these devices. You can find this app in the Google Play and Apple App stores. +The devices that this API can manage are offered in different designs across different countries. The details of these can be found [here](https://developer.legrand.com/solutions/wiring-devices-with-netatmo/). This Home+ Control integration for Home Assistant currently has support for the following devices: - Light switches @@ -28,7 +26,6 @@ In both cases, the devices are modeled as on/off switches within Home Assistant. This integration has been tested to work with the following range of Legrand products: - Valena Next™ with Netatmo -{% include integrations/config_flow.md %} ## Authentication @@ -38,21 +35,45 @@ These Legrand APIs rely on Oauth2 authentication, so you must follow these steps 1. Register an account at . 2. Create a subscription to the *Starter Kit* (currently the only subscription available) and this will generate your `SUBSCRIPTION_KEY`. -3. Register an application, where you will have to define a name, a redirect URL and the scopes of your application (for simplicity you can mark all scopes). +3. Register an application, where you will have to define a name, a redirect URL and the scopes of your application. When selecting the scopes, be sure to include all of the `.read` scopes, as well as the `light.write` and `plug.write` scopes to be able to control these modules from the integration. Once the registered application is confirmed, you should receive an email containing the `CLIENT_IDENTIFIER` and the `CLIENT_SECRET` which you will be using to set up the authentication flows. The application confirmation email is usually received within a few hours of having issued the request. -### Authentication Flow +Finally, to set up Oauth2 authentication in Home Assistant you should add the following information to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +home_plus_control: + client_id: CLIENT_IDENTIFIER + client_secret: CLIENT_SECRET + subscription_key: SUBSCRIPTION_KEY +``` + +{% configuration %} +client_id: + description: Client identifier for your registered application on the *Works with Legrand* platform. Received via email. + required: true + type: string +client_secret: + description: Client secret for your registered application on the *Works with Legrand* platform. Received via email. + required: true + type: string +subscription_key: + description: Subscription identifier for your registered account on the *Works with Legrand* platform. Provided upon registration. + required: true + type: string +{% endconfiguration %} + -Communication with the API, first requires Oauth2 authentication to obtain an access and a refresh token. Subsequent requests to the API, require the use of the SUBSCRIPTION_KEY in addition to the access token. +At this point, you are now ready to add the Home+ Control integration to your Home Assistant instance as described in the [Configuration](#configuration) section. -Information about the Oauth2 exchange is provided here: https://developer.legrand.com/tutorials/0auth2-end-point-url/ -As part of the authentication exchange, a callback request is made to the REDIRECT_URL that was entered when you registered the application with the *Works with Legrand* platform. This redirect URL will take on the default value of your Home Assistant instance URL, but because this could differ from the URL that you entered in the Legrand registration form, the integration allows you to explicitly specify the redirect URL parameter that you would like to use. +{% include integrations/config_flow.md %} + -## Polling Interval Configuration +## Polling Intervals -The Legrand `Home+ Control` API is a cloud-based polling interface. This Home Assistant integration presents 3 different polling intervals: +The Legrand Home+ Control API is a cloud-based polling interface. This Home Assistant integration presents 3 different polling intervals: - Plant information request - Plant topology request @@ -61,6 +82,8 @@ The Legrand `Home+ Control` API is a cloud-based polling interface. This Home As Refer to the [nomenclature](#api-nomenclature) section for details of what these names mean. Refer to the [API limitations](#api-limitations) section to better understand the reason for these polling intervals. +The polling intervals can be [configured](#polling-interval-configuration) via the integration's `OPTIONS` in the Home Assistant UI. + ### Plant Information Request This call retrieves the information of the plants that are associated with a user. It is assumed that this information does not change very often. For the most part, a user will have a single *Legrand Home+ Control* gateway in their home, i.e., a single *plant*, and this will not change frequently. @@ -79,6 +102,18 @@ This call retrieves the current operating status of the devices that make up the This information is expected to change frequently, so the polling interval is set to a lower default value of 300 seconds (5 minutes). This is still not as frequent as would be ideal, but is still reasonable considering the API calls-per-day limitation. +### Polling Interval Configuration + +The polling intervals can be configured via the integration's `OPTIONS` in the Home Assistant UI. + +{% configuration_basic %} +Plant Information: + description: Number of seconds between polling intervals of the plant information. +Plant Topology: + description: Number of seconds between polling intervals of the plant topology data. +Module Status: + description: Number of seconds between polling intervals of the module status information. +{% endconfiguration_basic %} ## API Nomenclature From 1cb6015d80818e0bbf12e2b1670f9ab31de45d0b Mon Sep 17 00:00:00 2001 From: chemaaa <187996+chemaaa@users.noreply.github.com> Date: Fri, 19 Mar 2021 09:24:26 +0100 Subject: [PATCH 6/7] Adapt documentation to latest changes in the code. --- .../_integrations/home_plus_control.markdown | 50 +------------------ 1 file changed, 2 insertions(+), 48 deletions(-) diff --git a/source/_integrations/home_plus_control.markdown b/source/_integrations/home_plus_control.markdown index 870c6ca0afd1..cbcf29425790 100644 --- a/source/_integrations/home_plus_control.markdown +++ b/source/_integrations/home_plus_control.markdown @@ -71,50 +71,6 @@ At this point, you are now ready to add the Home+ Control integration to your Ho {% include integrations/config_flow.md %} -## Polling Intervals - -The Legrand Home+ Control API is a cloud-based polling interface. This Home Assistant integration presents 3 different polling intervals: - -- Plant information request -- Plant topology request -- Module status request - -Refer to the [nomenclature](#api-nomenclature) section for details of what these names mean. -Refer to the [API limitations](#api-limitations) section to better understand the reason for these polling intervals. - -The polling intervals can be [configured](#polling-interval-configuration) via the integration's `OPTIONS` in the Home Assistant UI. - -### Plant Information Request - -This call retrieves the information of the plants that are associated with a user. It is assumed that this information does not change very often. For the most part, a user will have a single *Legrand Home+ Control* gateway in their home, i.e., a single *plant*, and this will not change frequently. - -For this reason, the default polling interval for the plant information is set to a large value: 7200 seconds (2 hours). - -### Plant Topology Request - -This call retrieves the *layout* of the devices that make up a *plant*. This provides the list of devices, their names and some additional information about the devices (but not their status). - -It is assumed that plant topology is not changing very often, so the default polling interval for this information is set to a default value of 3600 seconds (1 hour). - -### Module Status Request - -This call retrieves the current operating status of the devices that make up the plant's topology - this includes the *reachability* of the device and its on/off status. - -This information is expected to change frequently, so the polling interval is set to a lower default value of 300 seconds (5 minutes). This is still not as frequent as would be ideal, but is still reasonable considering the API calls-per-day limitation. - -### Polling Interval Configuration - -The polling intervals can be configured via the integration's `OPTIONS` in the Home Assistant UI. - -{% configuration_basic %} -Plant Information: - description: Number of seconds between polling intervals of the plant information. -Plant Topology: - description: Number of seconds between polling intervals of the plant topology data. -Module Status: - description: Number of seconds between polling intervals of the module status information. -{% endconfiguration_basic %} - ## API Nomenclature Within the context of the Home+ Control API you may come across the following terms: @@ -128,8 +84,6 @@ Other devices that are mentioned in the API, but that are not currently supporte ## API Limitations -As mentioned in the [authentication](#authentication) section, this integration requires you to set up a subscription in the *Works with Legrand* platform. - -Currently, end-users only have access to the *Starter Kit* subscription which has a major limitation in the number of allowed API requests that are allowed - only 500 API calls per day (counter is reset at 00:00 every day). +As described in the [authentication](#authentication) section, this integration requires you to set up a subscription in the *Works with Legrand* platform. -This means that the integration has to set default polling intervals that are considerably larger than one would want for a Home Assistant integration. These intervals are [configurable](#polling-interval-configuration), but take care not to exceed the daily quota to prevent the integration from failing with `403 Forbidden` HTTP responses. +Currently, end-users only have access to the *Starter Kit* subscription which has a major limitation in the number of allowed API requests that are allowed - only 500 API calls per day (counter is reset at 00:00 every day). If this daily quota is ever exceeded, the API will report `403 Forbidden` HTTP responses. From 048c03ce210fbb6d15043c88aaf4f056dc7361be Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Mon, 29 Mar 2021 10:19:56 +0200 Subject: [PATCH 7/7] Tweak ha_release --- source/_integrations/home_plus_control.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/home_plus_control.markdown b/source/_integrations/home_plus_control.markdown index cbcf29425790..e1e197ad441e 100644 --- a/source/_integrations/home_plus_control.markdown +++ b/source/_integrations/home_plus_control.markdown @@ -3,7 +3,7 @@ title: Legrand Home+ Control description: Instructions on how to integrate Legrand Home+ Control into Home Assistant. ha_category: - Switch -ha_release: '2021.03' +ha_release: 2021.4 ha_iot_class: Cloud Polling ha_codeowners: - '@chemaaa'