From e3b0a6162bd144b56d0ef03cd08047a4c4308eda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20L=C3=B3pez?= Date: Fri, 10 Feb 2023 09:11:28 +0100 Subject: [PATCH 1/3] FAQ added --- .github/ISSUE_TEMPLATE/bug_report.md | 1 + FAQ.md | 35 ++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 FAQ.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index cd35de4..8e5fd32 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -26,6 +26,7 @@ Steps to reproduce the behavior: - ideenergy integration version [e.g 1.0.0, main] - Instalation method [HassOS, docker, pip, pipenv] - i-de.es advanced user [yes / no] +- Have I read the [FAQ](https://github.com/ldotlopez/ha-ideenergy/FAQ.md)?: no **Expected behavior** A clear and concise description of what you expected to happen. diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..9850761 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,35 @@ +# FAQ + +## Q. Why "X" doesn't work + +A. Most features in this integration are experimental. If it's not listed as supported it's **not** supported. Double-check this. + + +## Q. Accumulated (or instant) consumption sensor is in an unknown state or doesn't show any data. + +A. Those two sensors read data directly from your service point. The i-de API for this data is **very** unreliable, > 50% of the calls fail. We try out best to circumvent this situation but we can't do magic. + +Give it some time, two or three days, before filing a bug. + + +## Q. Historical sensors (consumption and generation) doesn't have a value + +A. They are not supposed to. Historical sensors are a hack, HomeAssistant is not supposed to have historical sensors. + +Historical sensors can't provide the current state, Home Assistant will show "undefined" state forever, it's OK and intentional. To view historical data you have to go [History](https://my.home-assistant.io/redirect/history/) → Select any historical sensor → Go back some days. + +Keep in mind that historical data has a ~24h delay. + +Until 1.1.0 those sensors doen't generate statistic data. You need this data to them as an energy source in the energy panel. + +Before 1.1.0 you have to use the "Accumulated consumption" sensor as a source for the energy panel. + +## Q. I have a problem with multiple contracts: I got banned/Doesn't work + +We recommend disabling the "Accumulated" and "Instant" sensors if you have multiple contracts. + +Due to some issues with the API and rate limit it's very possible that i-de bans you have a few hours of running this integration. + +**Important**: Having multiple contracts it's different of having **configured** multiple contracts. You can have multiple contracts but have only one configured in Home Assistant, or you can have multiple contracts added in HomeAssistant but only one (or none) with mentioned sensors enabled. + +If you have multiple contracts I recommend you to only enable historical sensors. From c60b0f86ecd31b6baffcca5d657b0c1e77328a7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20L=C3=B3pez?= Date: Fri, 10 Feb 2023 12:58:41 +0100 Subject: [PATCH 2/3] Update docs --- .github/ISSUE_TEMPLATE/bug_report.md | 6 +- FAQ.md | 11 ++++ README.es.md | 85 ++++++++++++++++++++++++---- README.md | 79 ++++++++++++++++---------- 4 files changed, 137 insertions(+), 44 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 8e5fd32..9ca1252 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -8,9 +8,11 @@ assignees: '' --- Before filling a bug please provide as much as information as possible. - Not all information is required but the more the better. +Stick to English if bug is about code, Spanish is OK if bug is about configuration. + + **Describe the bug** A clear and concise description of what the bug is. @@ -26,7 +28,7 @@ Steps to reproduce the behavior: - ideenergy integration version [e.g 1.0.0, main] - Instalation method [HassOS, docker, pip, pipenv] - i-de.es advanced user [yes / no] -- Have I read the [FAQ](https://github.com/ldotlopez/ha-ideenergy/FAQ.md)?: no +- Did I read the [FAQ](https://github.com/ldotlopez/ha-ideenergy/blob/main/FAQ.md)?: no **Expected behavior** A clear and concise description of what you expected to happen. diff --git a/FAQ.md b/FAQ.md index 9850761..f11845c 100644 --- a/FAQ.md +++ b/FAQ.md @@ -7,11 +7,22 @@ A. Most features in this integration are experimental. If it's not listed as sup ## Q. Accumulated (or instant) consumption sensor is in an unknown state or doesn't show any data. + +Due to connectivity issues or i-DE server issues, you may not always obtain readings as expected. Keep in mind that sometimes a delay on the reading may occurr. + A. Those two sensors read data directly from your service point. The i-de API for this data is **very** unreliable, > 50% of the calls fail. We try out best to circumvent this situation but we can't do magic. +Also, due to connectivity issues or i-DE server issues, you may not always obtain readings as expected. + Give it some time, two or three days, before filing a bug. +## Q. Accumulated (or instant) consumption sensor shows 0 increment at some intervals. + +A. Readings from this sensors only returns integer values. If from the last reading your meter indicates a variance minor then 1 kWh, the integration will not reflect any variance and that will only be recorded once the variance from the previous reading is greater then 1. + +* The "instant" and "accumulated" readings are done directly to your meter. Due to connectivity issues or i-DE server issues, you may not always obtain readings as expected. Keep in mind that sometimes a delay on the reading may occurr. + ## Q. Historical sensors (consumption and generation) doesn't have a value A. They are not supposed to. Historical sensors are a hack, HomeAssistant is not supposed to have historical sensors. diff --git a/README.es.md b/README.es.md index 234a5a6..2214d70 100644 --- a/README.es.md +++ b/README.es.md @@ -1,27 +1,88 @@ -# home-assistant ideenergy +# i-DE (Iberdrola Distribución) Custom Integration for Home Assistant -Integración [ideenergy](https://github.com/ldotlopez/ideenergy) para [home-assistant](home-assistant.io/) + +[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs) +[![hassfest validation](https://github.com/ldotlopez/ha-ideenergy/workflows/Validate%20with%20hassfest/badge.svg)](https://github.com/ldotlopez/ha-ideenergy/actions/workflows/hassfest.yml) +[![HACS validation](https://github.com/ldotlopez/ha-ideenergy/workflows/Validate%20with%20HACS/badge.svg)](https://github.com/ldotlopez/ha-ideenergy/actions/workflows/hacs.yml) + + +![GitHub Release (latest SemVer including pre-releases)](https://img.shields.io/github/v/release/ldotlopez/ha-ideenergy?include_prereleases) +[![CodeQL](https://github.com/ldotlopez/ha-ideenergy/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/ldotlopez/ha-ideenergy/actions/workflows/codeql-analysis.yml) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) + +[ideenergy](https://github.com/ldotlopez/ideenergy) integration for [home-assistant](https://home-assistant.io/) Esta integración provee sensores para el distribuidor de energía español [i-DE](i-de.es). + Require de un usuario **avanzado** en la página web del distribuidor. -**⚠️ Asegurese de leer la sección 'Advertencias'** +**⚠️ Asegurese de leer la [FAQ](https://github.com/ldotlopez/ha-ideenergy/blob/main/FAQ.md)' y las secciones 'advertencias' y 'dependencias'.** ## Características -* Integración con el panel del energía de HomeAssistant -* Soporte para varios contratos. -* Sensor de consumo acumulado. -* Sensor experimental de datos históricos de consumo con mayor (sub-kWh) precesión. -* Configuración a través del [interfaz web de HomeAssistant](https://developers.home-assistant.io/docs/config_entries_options_flow_handler) sin necesidad de editar ficheros YAML. -* Algoritmo de actualización para leer el contador cerca del final de cada periodo horario (entre el minuto 50 y 59) y una mejor representación del consumo en el panel de energía de HomeAssistant -* Totalmente [asíncrono](https://developers.home-assistant.io/docs/asyncio_index) e integrado en HomeAssistant. +* Integración con el panel del energía de Home Assistant + +* Sensores de consumo instantaneo y acumulado. + +* Sensores históricos (consumulo y generación solar) con mayor precisión (sub-kWh). Estos datos no son tiempo real y normalmente llevan un retraso de entre 24 y 48 horas. + +* Soporte para varios contratos (puntos de servicio). + +* Configuración a través del [interfaz web de Home Assistant](https://developers.home-assistant.io/docs/config_entries_options_flow_handler) sin necesidad de editar ficheros YAML. + +* Algoritmo de actualización para leer el contador cerca del final de cada periodo horario (entre el minuto 50 y 59) y una mejor representación del consumo en el panel de energía de Home Assistant + +* Totalmente [asíncrono](https://developers.home-assistant.io/docs/asyncio_index) e integrado en Home Assistant. + + +## Dependencies + +Es necesario disponer de acceso al área de clientes de i-DE. +Puedes registrarte en el siguiente link: [Área Clientes | I-DE - Grupo Iberdrola](https://www.i-de.es/consumidores/web/guest/login). + +Además es necesario disponer del perfil de "Usuario avanzado". Si no se dispone de él hay que rellenar un formulario del [Perfil de cliente](https://www.i-de.es/consumidores/web/home/personal-area/userData). + +### Usando [HACS](https://hacs.xyz/) (recomendado) + +1. Copia la dirección de este repositorio: (https://github.com/ldotlopez/ha-ideenergy)[https://github.com/ldotlopez/ha-ideenergy/] +2. Añade este repositorio en HACS como "repositorio manual": + + - En el campo "Repositorio" pega la URL anterior. + - En el campo "Categoría" elige "Integración" + - Pulsa el botón "Descargar" y elige la última versión. + + ![Custom repository](https://user-images.githubusercontent.com/59612788/171965822-4a89c14e-9eb2-4134-8de2-1d3f380663e4.png) + +3. Reinicia Home Assistant + +4. Configura la integración + + - (Opción A) Pulsa el botón "Añadir integración" → [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=ideenergy) + + - (Opción B) Navega a "Ajustes" → "Dispositivos y servicios" y pulsa "Añadir integración". Elige "i-DE.es sensores de energía". + ![image](https://user-images.githubusercontent.com/59612788/171966005-e58f6b88-a952-4033-82c6-b1d4ea665873.png) + +5. Sigue los pasos del asistente: Proporciona tus credenciales de acceso para el área de cliente de "i-DE", después elige el contrato qu deseas monitorizar. Si necesitas añadir más contratos repite los pasos anteriores para cada uno de ellos. ## Instalación A través de custom_components o [HACS](https://hacs.xyz/) +1. Descarga o clona este repositorio: [https://github.com/ldotlopez/ha-ideenergy](https://github.com/ldotlopez/ha-ideenergy) + +2. Copia la carpeta [custom_components/ide](custom_components/ideenergy) en tu carpeta `custom_components` de tu instalación de Home Assistant. + +3. Reinicia Home Assistant +4. Configura la integración + + - (Opción A) Pulsa el botón "Añadir integración" → [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=ideenergy) + + - (Opción B) Navega a "Ajustes" → "Dispositivos y servicios" y pulsa "Añadir integración". Elige "i-DE.es sensores de energía". + ![image](https://user-images.githubusercontent.com/59612788/171966005-e58f6b88-a952-4033-82c6-b1d4ea665873.png) + +5. Sigue los pasos del asistente: Proporciona tus credenciales de acceso para el área de cliente de "i-DE", después elige el contrato qu deseas monitorizar. Si necesitas añadir más contratos repite los pasos anteriores para cada uno de ellos. + ## Capturas *Sensor de energía acumulada* @@ -37,7 +98,9 @@ A través de custom_components o [HACS](https://hacs.xyz/) ![snapshot](screenshots/configuration-1.png) ![snapshot](screenshots/configuration-2.png) + + ## Advertencias Esta integración provee un sensor 'histórico' que incorpora datos del pasado en la base de datos de Home Assistant. Por su propia seguridad este sensor no está habilitado y debe activarse manualmente. -☠️ El sensor histórico está basado en un **hack extremadamente experimental** y puede romper y/o corromper su base de datos y/o estadísticas. **Use lo bajo su propio riesgo**. +☠️ El sensor histórico está basado en un **hack extremadamente experimental** y puede romper y/o corromper su base de datos y/o estadísticas. **Use lo bajo su propio riesgo**. \ No newline at end of file diff --git a/README.md b/README.md index 9e846b0..0ea87d2 100644 --- a/README.md +++ b/README.md @@ -16,60 +16,77 @@ i-DE (Iberdrola Distribución) Custom Integration for Home Assistant, providing This integration requires an **advanced** user profile on i-DE website. -**⚠️ Make sure to read the 'Remarks', 'Dependencies' and 'Warning' sections** +**⚠️ Make sure to read the '[FAQ](https://github.com/ldotlopez/ha-ideenergy/blob/main/FAQ.md)', 'Dependencies' and 'Warning' sections** + ## Features * Integration with the Home Assistant Energy Panel. -* Support for several contracts. -* Accumulated consumption sensor. -* Experimental sensor for historical consumption data with better (sub-kWh) precision. Same data as available on i-DE website. This data is not realtime and usually has a 24-hour to 48-hour offset. -* Configuration through [Home Assistant Interface](https://developers.home-assistant.io/docs/config_entries_options_flow_handler) without the need to edit YAML files. -* Update algorithm to read the ICP near the end of each hourly period (between minute 50 and 59) with a better representation of consumption in the Home Assistant energy panel. -* Fully [asynchronous](https://developers.home-assistant.io/docs/asyncio_index) and integrated with HomeAssistant. -### Remarks -* The reading is done directly to your meter. Due to connectivity issues or i-DE server issues, you may not always obtain readings as expected. Keep in mind that sometimes a delay on the reading may occurr. -* The reading only returns integer values. If from the last reading your meter indicates a variance minor then 1 kWh, the integration will not reflect any variance and that will only be recorded once the variance from the previous reading is greater then 1. -* Solar Production (if applies on your case) is under development. +* Accumulated and Instant consumption sensors. + +* Historical sensors (both consumption and solar generation) with better (sub-kWh) precision. This data is not realtime and usually has a 24-hour to 48-hour offset. +* Support for multiple contracts (service points). -### Dependencies +* Configuration through [Home Assistant Interface](https://developers.home-assistant.io/docs/ +config_entries_options_flow_handler) without the need to edit YAML files. + +* Update algorithm to read the meter near the end of each hourly period (between minute 50 and 59) +with a better representation of consumption in the Home Assistant energy panel. + +* Fully [asynchronous](https://developers.home-assistant.io/docs/asyncio_index) and integrated with HomeAssistant. + + +## Dependencies You must have an i-DE username and access to the Clients' website. You may register here: [Área Clientes | I-DE - Grupo Iberdrola](https://www.i-de.es/consumidores/web/guest/login). It also necessary to have an "Advanced User" profile. Should you not have one already, you need to fill the request for from your [Profile Area](https://www.i-de.es/consumidores/web/home/personal-area/userData). + ## Installation ### Using [HACS](https://hacs.xyz/) (recommended) -- Copy this repo URL -- In the HACS section, add this repo as a custom one: +1. Copy this repository URL: (https://github.com/ldotlopez/ha-ideenergy)[https://github.com/ldotlopez/ha-ideenergy/] + +2. In the HACS section, add this repository as a custom one: + - ![Custom repository](https://user-images.githubusercontent.com/59612788/171965822-4a89c14e-9eb2-4134-8de2-1d3f380663e4.png) - - - On the "Repository" field put the URL copied before + - On the "repositorysitory" field put the URL copied before - On the "Category" select "Integration" - Click the "Download" button and download latest version. -- Restart HA -- Click this button >> -[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=ideenergy) -- or Go to "Settings" >> "Devices & Services" and click "+ ADD INTEGRATION" and select "i-de.es energy sensors" -![image](https://user-images.githubusercontent.com/59612788/171966005-e58f6b88-a952-4033-82c6-b1d4ea665873.png) -- Follow the configuration steps: provide your credentials for access to i-DE and select the contract that you want to monitor. (Should you need to add more contracts, just follow the previous step as many times as needed). + + ![Custom repositorysitory](https://user-images.githubusercontent.com/59612788/171965822-4a89c14e-9eb2-4134-8de2-1d3f380663e4.png) + +3. Restart HA + +4. Configure the integration + + - (Option A) Click the "Add integration" button → [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=ideenergy) + + - (Option B) Go to "Settings" "Devices & Services" and click "+ ADD INTEGRATION" and select "i-de.es energy sensors". + ![image](https://user-images.githubusercontent.com/59612788/171966005-e58f6b88-a952-4033-82c6-b1d4ea665873.png) + +5. Follow the configuration steps: provide your credentials for access to i-DE and select the contract that you want to monitor. (Should you need to add more contracts, just follow the previous step as many times as needed). ### Manually -- Download/clone this repo -- Copy the [custom_components/ide](custom_components/ideenergy) folder into your custom_components folder into your HA installation -- Restart HA -- Click this button >> -[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=ideenergy) -- or Go to "Settings" >> "Devices & Services" and click "+ ADD INTEGRATION" and select "i-de.es energy sensors" -![image](https://user-images.githubusercontent.com/59612788/171966005-e58f6b88-a952-4033-82c6-b1d4ea665873.png) -- Follow the configuration steps: provide your credentials for access to i-DE and select the contract that you want to monitor. (Should you need to add more contracts, just follow the previous step as many times as needed). +1. Download/clone this repository: (https://github.com/ldotlopez/ha-ideenergy)[https://github.com/ldotlopez/ha-ideenergy/] + +2. Copy the [custom_components/ide](custom_components/ideenergy) folder into your custom_components folder into your HA installation + +3. Restart HA + +4. Configure the integration + + - (Option A) Click on this button → [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=ideenergy) + - (Option B) Go to "Settings" → "Devices & Services" and click "+ ADD INTEGRATION" and select "i-de.es energy sensors". + ![image](https://user-images.githubusercontent.com/59612788/171966005-e58f6b88-a952-4033-82c6-b1d4ea665873.png) + +5. Follow the configuration steps: provide your credentials for access to i-DE and select the contract that you want to monitor. (Should you need to add more contracts, just follow the previous step as many times as needed). ## Snapshots From c097400835ec6412cd553725d96e352cfb4dca66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20L=C3=B3pez?= Date: Fri, 17 Feb 2023 09:17:11 +0100 Subject: [PATCH 3/3] Update FAQ.md Q. Why accumulated (or instant) consumption sensors are only updated once at hour? Can be this interval shorter? --- FAQ.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/FAQ.md b/FAQ.md index f11845c..01ba8f9 100644 --- a/FAQ.md +++ b/FAQ.md @@ -8,20 +8,29 @@ A. Most features in this integration are experimental. If it's not listed as sup ## Q. Accumulated (or instant) consumption sensor is in an unknown state or doesn't show any data. -Due to connectivity issues or i-DE server issues, you may not always obtain readings as expected. Keep in mind that sometimes a delay on the reading may occurr. +A. Due to connectivity issues or i-DE server issues, you may not always obtain readings as expected. Keep in mind that sometimes a delay on the reading may occurr. -A. Those two sensors read data directly from your service point. The i-de API for this data is **very** unreliable, > 50% of the calls fail. We try out best to circumvent this situation but we can't do magic. +Those two sensors read data directly from your service point. The i-de API for this data is **very** unreliable, > 50% of the calls fail. We try out best to circumvent this situation but we can't do magic. Also, due to connectivity issues or i-DE server issues, you may not always obtain readings as expected. Give it some time, two or three days, before filing a bug. +## Q. Why accumulated (or instant) consumption sensors are only updated once at hour? Can be this interval shorter? + +These sensors need to read the service point directly. + +The i-de.es service point API is not very reliable, we try up to three calls before giving up in each update window (interval 50-59 of each hour). + +On the other hand, the i-de.es platform blocks users if the service point is queried your user if he queries the service point too often. In our experience, no more than 5-6 calls in 10 minutes. + +The policy of updating the sensors only once an hour is given by the sum of these two situations. + ## Q. Accumulated (or instant) consumption sensor shows 0 increment at some intervals. A. Readings from this sensors only returns integer values. If from the last reading your meter indicates a variance minor then 1 kWh, the integration will not reflect any variance and that will only be recorded once the variance from the previous reading is greater then 1. -* The "instant" and "accumulated" readings are done directly to your meter. Due to connectivity issues or i-DE server issues, you may not always obtain readings as expected. Keep in mind that sometimes a delay on the reading may occurr. ## Q. Historical sensors (consumption and generation) doesn't have a value