BETA

Ceci est une version Bêta. Il y aura probablement des bogues, irritants, etc. Merci pour votre patience et d'ouvrir des "Issues".

Hilo

Intégration pour Home Assistant d'Hilo

⚠️ Breaking change (v2024.2.2 et antérieures non-fonctionnelles)

L'authentification (login) de Hilo est passée d'une méthode "Resource Owner Password Flow" vers une méthode "Authorization Code Flow with PKCE". L'ancienne méthode a été fermée définitivement le 10 avril 2024, les anciennes versions de l'intégration ne sont plus fonctionnelles.

Introduction

Ceci est l'intégration HACS non-officielle de Hilo sur Home Assistant. Hilo est une plateforme de domotique développée par une filliale d'Hydro-Québec. Cette intégration n'a aucun liens direct avec Hilo ou Hydro Québec. C'est une initiative communautaire. Merci de ne pas contacter Hilo ou Hydro-Québec pour tout problème avec cette intégration Home Assistant. Vous pouvez ouvrir un "issue" dans ce "repository" github à la place.

Si vous souhaitez aider avec le développement de cette intégration, vous pouvez toujours soumettre vos commentaires à partir du formulaire de l'app Hilo et demander à ce qu'ils ouvrent leur API publiquement et qu'ils fournissent un environnement de test pour les développeurs.

Remerciements

Gros merci à Francis Poisson qui est l'auteur de l'intégration originale. Sans le travail qu'il a fait sur cette intégration, je n'aurais probablement jamais considéré utiliser Hilo.

Un autre gros merci à @ic-dev21 pour son implication à plusieurs niveaux.

J'ai décidé de déplacer l'intégration ici, car la dernière mise à jour de Hilo a brisé l'original et j'ai pris le temps de complètement la récrire. Hilo pousse maintenant les lectures des appareils via websocket de SignalR.

Caractéristiques.

• Supporte les interrupteurs et gradateurs en tant que lumières.
• Voir la température actuelle et changer la consigne des thermostats.
• Obtenir la consommation énergétique des tous les appareils Hilo.
• Générer les "sensor" de puissance et d'énergie consommée.
• Sensor pour les Défis.
• Sensor pour la passerelle Hilo
• Configuration est maintenant faite via l'interface utilisateur
• Mise à jour des lectures plus près du temps réel.
• NOUVEAU: Authentification via le site de Hilo
• NOUVEAU: Capteur pour la météo extérieure avec icône changeante comme dans l'app Hilo

À faire:

• Ajouter la fonctionnalité pour d'autres appareils.
• Tests fonctionnels
• Ajouter des "type hints" au code
• Documenter la librairie d'appels API à Hilo Maintenant disponible ici
• Ajout automatique des compteurs de consommation électrique

Installation

Étape 0 : Avoir une installation compatible

L'intégration nécessite que l'installation du matériel Hilo soit complétée à votre domicile. Il ne sera pas possible de faire l'installation si ça n'est pas fait.

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

Assurez-vous d'avoir HACS d'installé. Sous HACS, cliquer le bouton '+ EXPLORE & DOWNLOAD REPOSITORIES' au bas de la page, rechercher "Hilo", le choisir, et cliquer sur download dans HACS.

Option 2 : Manuellement

Télécharger et copier le dossier custom_components/hilo de la dernière version dans votre dossier custom_components de Home Assistant.

Étape 2 : Ajouter l'intégration à HA (<--- étape souvent oubliée)

Dans HA, aller à Paramètres > Appareils et services > Intégrations. Dans le coin inférieur droit, cliquer sur le bouton '+ AJOUTER UNE INTÉGRATION'.

Si l'intégration est correctement installée, vous devriez pouvoir trouver "Hilo" dans la liste. Il est possible d'avoir besoin de vider la mémoire cache de votre navigateur pour que l'intégration s'affiche.

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.

Vous devez ensuite accepter de lier votre compte. Pour ce faire, saisir l'adresse (URL ou IP) de votre instance Home Assistant et appuyer sur Link Account.

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.

Après avoir lié votre compte comme montré à la section configuration initiale, le message suivant apparaitra.

Compteurs de consommation électrique

Les compteurs de consommation électrique sont une fonctionalité de cette intégration. Ils étaient initialement générés par des capteurs "template" et des automatisations mais sont maintenant intégré dans l'intégration.

Avertissement

Lorsque l'on active les compteurs, il est recommandé de retirer les anciens capteurs manuels afin de ne pas avoir de données en double.

Si vous avez un problème et voulez collaborer, merci de mettre en marche la journalisation debug et de fournir un extrait du fichier home-assistant.log. La méthode est expliquée ci-bas..

Procédure

Si vous souhaitez utiliser la génération automatique des capteurs de consommation électrique, suivez les étapes suivantes:

• S'assurer que la plateforme utility_meter est chargée dans votre fichier configuration.yaml de Home Assistant. Vous n'avez qu'à ajouter une ligne au fichier comme suit :

  utility_meter:
  

• Cliquer sur Configure dans l'interface utilisateur de l'intégration et cocher Générer compteurs de consommation électrique.

• (Optionnel) Redémarrez Home Assistant et attendez 5 minutes environ, l'entité sensor.hilo_energy_total_low sera créée et contiendra des données:

  • Le status devrait être collecting
  • L'état state devrait être un nombre plus grand que 0.

• Toutes les entités et capteurs créés seront préfixés ou suffixés de hilo_energy_ ou hilo_rate_.

• Si vous voyez l'erreur suivante dans le journal de Home Assistant, ceci est du à un bogue de Home Assistant causé par le fait que le compteur n'a pas encore accumulé suffisamment de données pour fonctionner. Elle peut être ignorée.

  2021-11-29 22:03:46 ERROR (MainThread) [homeassistant] Error doing job: Task exception was never retrieved
  Traceback (most recent call last):
  [...]
  ValueError: could not convert string to float: 'None'
  

Une fois créés, les compteurs devront être ajoutés manuellement au tableau de bord "Énergie".

Autres options de configuration

D'autres options sont disponibles sous le bouton "Configurer" dans Home Assistant:

• Générer compteurs de consommation électrique: Case à cocher

  Générer automatiquement des compteurs de consommation électrique, voir la procédure ci-dessus pour la configuration Nécessite la ligne suivante dans votre fichier configuration.yaml :

  utility_meter:
  

• Générer seulement les compteurs totaux pour chaque appareil: Case à cocher

  Calculez uniquement le total d'énergie sans diviser entre le cout faible et le cout élevé

• Enregistrer également les données de demande et les messages Websocket (nécessite un niveau de journal de débogage à la fois sur l'intégration et sur pyhilo): Case à cocher

  Permets un niveau de journalisation plus élevé pour les développeurs/le débogage

• Vérouiller les entités climate lors de défis Hilo, empêchant tout changement lorsqu'un défi est en cours.: Case à cocher

  Empêche la modification des consignes de température lors des défis Hilo

• Suivre des sources de consommation inconnues dans un compteur séparé. Ceci est une approximation calculée à partir de la lecture du compteur intelligent.: Case à cocher

  Toutes les sources d'énergie autres que le matériel Hilo sont regroupées dans un seul capteur. Utilise la lecture du compteur intelligent de la maison.

• Nom du tarif Hydro Québec ('rate d' ou 'flex d'): chaine

  Définissez le nom du plan tarifaire d'Hydro-Québec. Seules 2 valeurs sont prises en charge pour le moment:

  • 'rate d'
  • 'flex d'

• Intervalle de mise à jour (min: 60s): Nombre entier

  Nombre de secondes entre chaque mise à jour de l'appareil. Par défaut à 60s. Il n'est pas recommandé d'aller en dessous de 30, car cela pourrait entrainer une suspension de Hilo. Depuis 2023.11.1 le minimum est passé de 15s à 60s.

Exemples d'intégrations Lovelace et d'automatisations

Vous pouvez trouver de nombres exemples et idées pour votre tableau de bord, vos cartes et vos automatisations dans le wiki du projet

Références

Comme indiqué ci-dessus, il s'agit d'une intégration non officielle. Hilo ne prend pas en charge les appels API directs et peut obscurcir le service ou nous empêcher de l'utiliser.

Pour l'instant, voici les liens Swagger que nous avons trouvés:

• https://wapphqcdev01-automation.azurewebsites.net/swagger/index.html
• https://wapphqcdev01-notification.azurewebsites.net/swagger/index.html
• https://wapphqcdev01-clientele.azurewebsites.net/swagger/index.html

FAQ

Vous pouvez trouver la FAQ dans le wiki du projet: https://github.com/dvd-dev/hilo/wiki/FAQ

Contribuer

Rapporter tout problème est une bonne manière disponible à tous de contribuer au projet.

Si vous éprouvez des problèmes ou voyez des comportements étranges, merci de soumettre une "Issue" et d'y attacher vos journaux.

Pour mettre en fonction la journalisation de débogage, vous devez ajouter ceci dans votre fichier configuration.yaml:

logger:
  default: info
  logs:
     custom_components.hilo: debug
     pyhilo: debug

Si vous avez de l'expérience python ou Home Assistant et que vous souhaitez contribuer au code, n'hésitez pas à soumettre un pull request.

Préparer un environnement de développement sur macOS / Linux

1. Préparer les dossiers nécessaires:

$ 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: On clone aussi le repo de home-assistant, car c'est plus facile d'ajouter du debug à ce niveau.

2. Lancer le container:

$ 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. Vérifier que le container roule

$ 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. Vérifier les logs de home-assistant

$ less ${HASS_DEV}/config/home-assistant.log
$ grep hilo ${HASS_DEV}/config/home-assistant.log

5. Activer les logs debug

$ cat << EOF >> ${HASS_DEV}/config/configuration.yaml
logger:
  default: info
  logs:
     custom_components.hilo: debug
     pyhilo: debug
EOF
$ docker restart hass

Avant de soumettre une Pull Request

Il va sans dire qu'il est important de tester vos modifications sur une installation locale. Il est possible de modifier les fichiers .py de l'intégration directement dans votre dossier custom_components/hilo.

N'oubliez pas votre copie de sauvegarde!

Si vous devez modifier python-hilo pour vos tests, il est possible d'installer votre "fork" avec la commande suivante dans votre CLI :

$ pip install -e git+https://github.com/VOTRE_FORK_ICI/python-hilo.git#egg=python-hilo

Vous devrez ensuite redémarrer Home Assistant pour que votre installation prenne effet. Pour revenir en arrière, il suffit de faire:

$ pip install python-hilo

Et redémarrez Home Assistant

Soumettre une Pull Request

• D'abord, vous devez créer un fork du "repository" dans votre propre espace utilisateur.
• Ensuite, vous pouvez en faire un clone sur votre ordinateur.
• Afin de maintenir une sorte de propreté et de standard dans le code, nous avons des linters et des validateurs qui doivent être exécutés via pre-commit hooks :

$ pre-commit install --install-hooks

• Vous pouvez maintenant procéder à votre modification au code.
• Lorsque vous avez terminé, vous pouvez stage les fichiers pour un commit:

$ git add path/to/file

• Et vous pouvez créer un commit:

$ git commit -m "J'ai changé ceci parce que ..."

• Finalement, vous pouvez push le changement vers votre "upstream repository" :

$ git push

• Ensuite, si vous visitez le upstream repository, Github devrait vous proposer de créer un "Pull Request" (PR). Vous n'avez qu'à suivre les instructions.

Collaborateurs initiaux

• Francis Poisson
• David Vallee Delisle

Mentions très honorables

• Ian Couture: Il tient cet addon du bout de ces bras depuis un certain temps
• Hilo: Merci à Hilo pour son support et ses contributions.

---