dvd-dev · ic-dev21 · Mar 2, 2024 · Dec 19, 2023 · Dec 19, 2023 · Dec 20, 2023
diff --git a/README.en.md b/README.en.md
@@ -19,7 +19,7 @@ This is a beta release. There will be some bugs, issues, etc. Please bear with u
 # Hilo
 [Hilo](https://www.hydroquebec.com/hilo/en/) integration for Home Assistant
 
-# :warning: Breaking change coming soon
+# :warning: Breaking change (v2024.2.2 and lower)
 Hilo's login will stop using "Resource Owner Password Flow" and start using "Authorization Code Flow with PKCE". A few weeks after this change, the current login method will be permanently closed and unusable. We recommend watching this page for updates as previous versions of this integration will no longer work.
 
 ## Introduction
@@ -64,6 +64,10 @@ rewrite it. Hilo is now pushing device readings via websocket from SignalR.
 
 ## Installation
 
+### Step 0: Compatible install
+
+ This custom component has been tested to worked by various users on HA OS (as bare metal or VM), Docker with the official (ghcr.io) image and Podman. Other types of install may cause permissions issues during creation of a few files by the custom component.
+
 ### Step 1: Download files
 
 #### Option 1: Via HACS
@@ -80,13 +84,39 @@ Download and copy the `custom_components/hilo` directory from the [latest releas
 In HA, go to Settings > Devices & Services > Integrations.
 In the bottom right corner, click the '+ ADD INTEGRATION' button.
 
+![Add Integration](https://github.com/dvd-dev/hilo/assets/108159253/7906f2c9-9547-4478-a625-feaa68e62c5f)
+
 If the component is properly installed, you should be able to find the 'Hilo integration' in the list. You might need to clear you browser cache for the integration to show up.
 
-## Configuration
+![Search Integration](https://github.com/dvd-dev/hilo/assets/108159253/1b560a73-042b-46cf-963c-98e5326e98e8)
+
+
+## Configuration (new install)
+
+The configuration is done in the UI. When you add the integration, you will be redirected to Hilo's website login page to authenticate.
+
+![Open Website](https://github.com/dvd-dev/hilo/assets/108159253/23b4fb34-f8c3-40b3-8e01-b3e737cc9d44)
+
+
+![Auth Hilo](https://github.com/dvd-dev/hilo/assets/108159253/e4e98b32-78d0-4c49-a2d7-3bd0ae95e9e0)
+
+You must then accept to link your account. To do so, you must enter your Home Assistant instance's URL or IP address and click Link Account.
 
-The configuration is done in the UI. When you add the integration, you will be prompted with your
-Hilo username and password. After this, you will be prompted with assigning a room for each one of
-your devices.
+![Link](https://github.com/dvd-dev/hilo/assets/108159253/5eb945f7-fa5e-458f-b0fe-ef252aaadf93)
+
+![Link URL](https://github.com/dvd-dev/hilo/assets/108159253/2c54df64-2e1c-423c-89cf-0eee8f0d4b7b)
+
+After this, you will be prompted with assigning a room for each one of your devices.
+
+## Configuration (update from a version earlier than v2024.3.1)
+
+After update, you will get an error saying you must reauthenticate for the integration to work.
+
+![Reconfiguration 2](https://github.com/dvd-dev/hilo/assets/108159253/a711d011-17a9-456f-abf6-74cf099014f1)
+
+![Reath](https://github.com/dvd-dev/hilo/assets/108159253/70118e68-90b9-4667-b056-38ee2cd33133)
+
+After correctly linking your account like in the previous section, you should see a popup telling you the reauthentification was sucessful.
 
 ### Energy meters
 
@@ -168,6 +198,14 @@ Other options are available under the `Configure` button in Home Assistant:
   - `rate d`
   - `flex d`
 
+- `appreciation phase`: Integer (hours)
+
+  Add an appreciation phase of X hours before the preheat phase.
+
+- `pre_cold phase`: Integer (hours)
+
+  Add a cooldown phase of X hours to reduce temperatures before the appreciation phase
+
 - `Scan interval (min: 60s)`: Integer
 
   Number of seconds between each device update. Defaults to 60 and it's not recommended to go below 30 as it might
@@ -209,6 +247,61 @@ logger:
 
 If you have any kind of python/home-assistant experience and want to contribute to the code, feel free to submit a pull request.
 
+### Prepare a dev  environment in MacOS / Linux
+
+1. Prepare necessary directories:
+```console
+$ HASS_DEV=~/hass-dev/
+$ HASS_RELEASE=2023.12.3
+$ mkdir -p ${HASS_DEV}/config
+$ cd $HASS_DEV
+$ git clone https://github.com/dvd-dev/hilo.git
+$ git clone https://github.com/dvd-dev/python-hilo.git
+$ git clone https://github.com/home-assistant/core.git
+$ git --git-dir core/ checkout $HASS_RELEASE
+```
+
+**NOTE**: We also clone home-assistant's core to make it easier to add logging at that level [repo](https://github.com/home-assistant/core).
+
+2. Launch the container:
+
+```console
+$ docker run -d -p 8123:8123 \
+  --name hass \
+  -v ${HASS_DEV}/config:/config \
+  -v ${HASS_DEV}/python-hilo/pyhilo:/usr/local/lib/python3.11/site-packages/pyhilo:ro \
+  -v ${HASS_DEV}/hilo/custom_components/hilo/:/config/custom_components/hilo:ro \
+  -v ${HASS_DEV}/core/homeassistant:/usr/src/homeassistant/homeassistant:ro \
+  homeassistant/home-assistant:$HASS_RELEASE
+```
+
+3. Check the container is running
+
+```console
+$ docker ps
+CONTAINER ID   IMAGE                                    COMMAND   CREATED       STATUS          PORTS                    NAMES
+bace2264ee54   homeassistant/home-assistant:2023.12.3   "/init"   3 hours ago   Up 28 minutes   0.0.0.0:8123->8123/tcp   hass
+```
+
+4. Check home-assistant logs
+```console
+$ less ${HASS_DEV}/config/home-assistant.log
+$ grep hilo ${HASS_DEV}/config/home-assistant.log
+```
+
+5. Activate debug logs
+
+```console
+$ cat << EOF >> ${HASS_DEV}/config/configuration.yaml
+logger:
+  default: info
+  logs:
+     custom_components.hilo: debug
+     pyhilo: debug
+EOF
+$ docker restart hass
+```
+
 ### Before submiting a Pull Request
 
 It goes without saying you must test your modifications on your local install for problems. You may modify the .py files inside the following folder. Don't forget a backup!

diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ Ceci est une version Bêta. Il y aura probablements des bogues, irritants, etc.
 # Hilo
 Intégration pour Home Assistant d'[Hilo](https://www.hydroquebec.com/hilo/fr/)
 
-# :warning: Breaking change à venir
+# :warning: Breaking change (v2024.2.2 et antérieures)
 L'authentification (login) de Hilo passera d'une méthode "Resource Owner Password Flow" vers une méthode "Authorization Code Flow with PKCE". Quelques semaines après ce changement, l'ancienne méthode sera fermée définitivement et les anciennes version de Hilo ne seront plus fonctionnelles. Nous recommandons donc de surveiller cette page pour une mise à jour prochainement.
 
 ## Introduction
@@ -56,6 +56,9 @@ J'ai décidé de déplacer l'intégration ici car la dernière mise à jour de H
 
 ## Installation
 
+### Étape 0: Avoir une installation compatible
+ Cette intégration a été testée par des utilisateurs sous HA OS (bare metal et VM), Docker avec l'image officielle (ghcr.io), Podman. Tout autre type d'installation peut mener à des problèmes de permission pour certains fichiers créés lors de l'installation initiale du custom_component.
+
 ### Étape 1: Télécharger les fichiers
 
 #### Option 1: Via HACS
@@ -72,12 +75,37 @@ Télécharger et copier le dossier `custom_components/hilo` de la [dernière ver
 Dans HA, aller à  Paramètres > Appareils et services > Intégrations.
 Dans le coin inférieur droit, cliquer sur le bouton '+ AJOUTER UNE INTÉGRATION'.
 
+![Ajout intégration](https://github.com/dvd-dev/hilo/assets/108159253/e0529aca-9b13-40e0-9be4-29e347b980ab)
+
 Si l'intégration est correctement installée, vous devriez pouvoir trouver "Hilo" dans la list. Il est possible d'avoir besoin de vider la mémoire cache de votre navigateur pour que l'intégration s'affiche.
 
-## Configuration
+![Recherche intégration](https://github.com/dvd-dev/hilo/assets/108159253/7003a402-9369-4063-ac02-709bd0294e42)
+
+## Configuration (initiale)
+
+La configuration est faite via l'interface utilisateur. Lorsque vous ajoutez l'intégration, vous êtes redirigés vers le site de connexion d'Hilo afin de vous y authentifier.
+
+![Auth step 1](https://github.com/dvd-dev/hilo/assets/108159253/d2e396ea-e6df-40e6-9a14-626ef3be87c8)
+
+![Auth Hilo](https://github.com/dvd-dev/hilo/assets/108159253/e4e98b32-78d0-4c49-a2d7-3bd0ae95e9e0)
+
+Vous devez ensuite accepter de lier votre compte. Pour se faire, saisir l'addresse (URL ou IP) de votre instance Home Assistant et appuyez sur Link Account.
+
+![Link](https://github.com/dvd-dev/hilo/assets/108159253/5eb945f7-fa5e-458f-b0fe-ef252aaadf93)
+
+Après, vous devrez assigner une pièce de votre maison à chaque appareil.
+
+## Configuration (mise à jour depuis une version antérieure à v2024.3.1)
+
+Après la mise à jour, vous obtiendrez une erreur comme quoi vous devez vous réauthentifier pour que l'intégration fonctionne.
+
+![Reconfigurer](https://github.com/dvd-dev/hilo/assets/108159253/5b69da7f-d547-4ba7-8b64-8eb1d8f28bdb)
+
+![Réauthentifier](https://github.com/dvd-dev/hilo/assets/108159253/6b1bf2c3-0d7a-4eb8-815b-594401fc09ef)
 
-La configuration est faite via l'interface utilisateur. Lorsque vous ajoutez l'intégration, votre nom d'utilisateur et mot de passe Hio vous seront demandés. Après, vous devrez assigner une pièce de votre maison à chaque appareil.
+Après avoir lié votre compte comme montré à la section configuration initale, le message suivant apparaîtra.
 
+![Réauthentifié succès](https://github.com/dvd-dev/hilo/assets/108159253/7708b449-24c3-43c1-843b-8697ae192db1)
 
 ### :warning: Compteurs de consommation électrique
 

diff --git a/custom_components/hilo/__init__.py b/custom_components/hilo/__init__.py
@@ -16,9 +16,7 @@
     ATTR_CONNECTIONS,
     ATTR_DEVICE_CLASS,
     ATTR_UNIT_OF_MEASUREMENT,
-    CONF_PASSWORD,
     CONF_SCAN_INTERVAL,
-    CONF_TOKEN,
     CONF_USERNAME,
     EVENT_HOMEASSISTANT_STOP,
     Platform,
@@ -27,6 +25,7 @@
 from homeassistant.exceptions import ConfigEntryAuthFailed, ConfigEntryNotReady
 from homeassistant.helpers import (
     aiohttp_client,
+    config_entry_oauth2_flow,
     device_registry as dr,
     entity_registry as er,
 )
@@ -41,15 +40,15 @@
     DataUpdateCoordinator,
 )
 from pyhilo import API
-from pyhilo.const import DEFAULT_STATE_FILE
 from pyhilo.device import HiloDevice
 from pyhilo.devices import Devices
 from pyhilo.event import Event
 from pyhilo.exceptions import HiloError, InvalidCredentialsError, WebsocketError
+from pyhilo.oauth2 import AuthCodeWithPKCEImplementation
 from pyhilo.util import from_utc_timestamp, time_diff
 from pyhilo.websocket import WebsocketEvent
 
-from .config_flow import STEP_OPTION_SCHEMA
+from .config_flow import STEP_OPTION_SCHEMA, HiloFlowHandler
 from .const import (
     CONF_APPRECIATION_PHASE,
     CONF_CHALLENGE_LOCK,
@@ -131,43 +130,34 @@ async def async_setup_entry(  # noqa: C901
     hass: HomeAssistant, entry: ConfigEntry
 ) -> bool:
     """Set up Hilo as config entry."""
-    _async_standardize_config_entry(hass, entry)
+    HiloFlowHandler.async_register_implementation(
+        hass, AuthCodeWithPKCEImplementation(hass)
+    )
+
+    implementation = (
+        await config_entry_oauth2_flow.async_get_config_entry_implementation(
+            hass, entry
+        )
+    )
+
     current_options = {**entry.options}
-    log_traces = current_options.get(CONF_LOG_TRACES, DEFAULT_LOG_TRACES)
+
+    try:
+        api = await API.async_create(
+            session=aiohttp_client.async_get_clientsession(hass),
+            oauth_session=config_entry_oauth2_flow.OAuth2Session(
+                hass, entry, implementation
+            ),
+            log_traces=current_options.get(CONF_LOG_TRACES, DEFAULT_LOG_TRACES),
+        )
+    except Exception as err:
+        raise ConfigEntryAuthFailed(err) from err
+
+    _async_standardize_config_entry(hass, entry)
     scan_interval = current_options.get(CONF_SCAN_INTERVAL, DEFAULT_SCAN_INTERVAL)
     scan_interval = (
         scan_interval if scan_interval >= MIN_SCAN_INTERVAL else MIN_SCAN_INTERVAL
     )
-    state_yaml = hass.config.path(DEFAULT_STATE_FILE)
-
-    websession = aiohttp_client.async_get_clientsession(hass)
-
-    try:
-        if entry.data[CONF_TOKEN]:
-            LOG.debug("Trying auth with token")
-            api = await API.async_auth_refresh_token(
-                session=websession,
-                provided_refresh_token=entry.data[CONF_TOKEN],
-                log_traces=log_traces,
-                state_yaml=state_yaml,
-            )
-        else:
-            raise InvalidCredentialsError
-    except InvalidCredentialsError as err:
-        try:
-            LOG.debug(f"Trying auth with username/password: {err}")
-            api = await API.async_auth_password(
-                entry.data[CONF_USERNAME],
-                entry.data[CONF_PASSWORD],
-                session=websession,
-                log_traces=log_traces,
-                state_yaml=state_yaml,
-            )
-        except (KeyError, InvalidCredentialsError) as err:
-            raise ConfigEntryAuthFailed from err
-    except HiloError as err:
-        LOG.error("Config entry failed: %s", err)
-        raise ConfigEntryNotReady from err
 
     hilo = Hilo(hass, entry, api)
     try:
@@ -212,6 +202,25 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     return unload_ok
 
 
+async def async_migrate_entry(hass, config_entry: ConfigEntry):
+    """Migrate old entry."""
+    LOG.debug("Migrating from version %s", config_entry.version)
+
+    if config_entry.version > 1:
+        # This means the user has downgraded from a future version
+        return False
+
+    if config_entry.version == 1:
+        config_entry.version = 2
+        hass.config_entries.async_update_entry(
+            config_entry, unique_id="hilo", data={"auth_implementation": "hilo"}
+        )
+
+    LOG.debug("Migration to version %s successful", config_entry.version)
+
+    return True
+
+
 class Hilo:
     """Define a Hilo data object."""