Poursuite du développement

.sonarcloud.properties

@@ -0,0 +1 @@
+sonar.python.version=3.7.3

README.md

@@ -1,76 +1,108 @@
 # Domoticz Freebox Plugin
-Plugin Python Domoticz pour accéder au services de l'API V4 de la Freebox
-https://matdomotique.wordpress.com/2018/03/25/plugin-freebox-pour-domoticz/
+
+Le Plugin "Freebox API" permet de piloter votre Freebox depuis votre serveur Domoticz.
+
+**L'objectif est de continuer à faire vivre et enrichir le développement initialement proposé par supermat (mais qu'il ne maintient plus suite à son déménagement)**
+
+**_Remarque importantes_ :**
+
+ **- Si vous utilisiez le plugin initialement proposé par supermat, il sera nécessaire de supprimer la version  "matiériel" ainsi que le dossier "PluginDomoticzFreebox)" avant de poursuivre...**
+
+ **- Le plugin proposé a été testé dans un nombre limité de cas. Il peut comporter des "bugs" (merci dans ce cas de me le remonter). Il est fournis sans garentie.**
 
 ## Fonctionnalités
 
-* Création du token d'authentification lors du premier lancement (une validation est nécessaire sur l'écran de la Freebox serveur)
-* Création d'un dispositif par partition de disque dur connecté à la Freebox (disques internes et externes)
-* Création de 3 dispositifs pour suivre les températures de la Freebox
-* Création d'un dispositif switch par adresse mac pour laquelle vérifier la présence ou non à proximité de la Freebox.
-* Création d'un dispositif switch de suivi et modification de l'état du wifi (Actif/Inactif)
-* Création d'un dispositif switch de reboot de la Freebox serveur
-* Création d'un dispositif switch d'état de la connection Internet (WAN)
-* Création de deux dispositifs pour les debits montants et descendants en Ko/s
+* Création du token d'authentification lors du premier lancement (une validation est nécessaire via l'écran tactile du Freebox serveur)
+* Création d'un dispositif par partition (disques internes et externes) affichant son taux d'occupation
+* Création de dispositifs remontant l'ensemble des sondes de températures de la Freebox
+* Création d'un dispositif de type switch permettant de superviser la disponibilité d'un équipement connecté à la Freebox (via son adresse mac). Ainsi il est possible de déduire la présence d'une personne au domicile (via la supervision de son smartphone).
+* Création d'un dispositif switch de suivi et modification de l'état du wifi (actif/inactif)
+* Création d'un dispositif switch permettant le redémarrage du Freebox serveur
+* Création d'un dispositif switch d'état de la connexion Internet (WAN)
+* Création de deux dispositifs pour le suivi du debit montant et descendant (en Ko/s)
+* Création d'un dispositif switch  pour suivre l’état ou activer/désactiver l’alarme (uniquement en option sur Freebox Delta)
 
 ## Installation
 
-Requis : Python version 3.4 or supérieur & Domoticz version 3.81xx ou supérieur.
+Requis : Python version 3.8 or supérieur & Domoticz version 2022.1 ou supérieur.
 
 * En ligne de commande aller dans le répertoire plugin de Domoticz (domoticz/plugins)
-* Lancer la commande: ```git clone https://github.com/supermat/PluginDomoticzFreebox.git```
-* Redemmarrer le service Domoticz en lancant la commande ```sudo service domoticz.sh restart```
+* Lancer la commande: ```git clone https://github.com/ilionel/PluginDomoticzFreebox.git```
+* Redemmarrer le service Domoticz via la commande ```sudo service domoticz restart```
 
 ## Updating
 
 Pour mettre à jour le plugin :
 
-* En ligne de commande aller dans le répertoire plugin de Domoticz (domoticz/plugins)
+* En ligne de commande aller dans le répertoire des plugins de Domoticz (domoticz/plugins)
 * Lancer la commande: ```git pull```
-* Redemmarrer le service Domoticz en lancant la commande ```sudo service domoticz.sh restart```
+* Redemmarrer le service Domoticz via la commande ```sudo service domoticz restart```
 
 ## Configuration
 
 | Field | Information|
 | ----- | ---------- |
-| Address | L'adresse d'accès à la box avec le http(s) devant (~~http://mafreebox.free.fr~~ sur réseau local, visiblement, depuis la dernière mise à jour de Free Aout 2020, cette adresse ne fonctionne plus, il faudrait utiliser http://mafreebox.freebox.fr - Merci Kyrille et alranapa)  |
-| Port | Le port pour accéder à la Freebox (80 sur réseau local) |
-| Token | Le Token de connexion à la Freebox qui vous sera donné lors de la première connexion du plugin (voir les log) |
-| Liste mac adresse pour présence (séparé par ;) | Une liste d'adresse mac à vérifier sur les équipements enregistrés sur la Freebox comme étant présent à proximité de la box (reachable et active). Présent au domicile |
-| Debug | Si true plus de log apparaitront dans la console de log |
+| URL | L'adresse d'accès à la Freebox (typiquement "https://mafreebox.freebox.fr") |
+| Port | Le port pour accéder à l'interface Web de la Freebox (généralement "443" pour de https en réseau local) |
+| Token | Le « Token » de connexion à la Freebox qui vous sera communiqué lors de la première connexion du plugin (et visible dans les logs de Domoticz) |
+| Liste @mac pour la présence (séparé par ;) | La liste d'adresse mac dont vous souhaitez monitorer la disponibilité (quand elles sont connectées à la Freebox) |
+| Option Debug | Pour obtenir des logs « très » détaillés (visible dans les journaux de Domoticz) |
+
+Depuis le menu « Matériel » de Domoticz :
+ - Chercher 'Freebox (via API)'
+ - Laisser les valeurs par défaut, si votre serveur Domoticz est en un réseau local, ou sinon paramétrer l’adresse et port réseau de votre Freebox.
+ - Ajouter le Matériel puis consulter les journaux de logs (depuis le menu Paramètre de Domoticz).
 
-Dans la partie Matériel de Domoticz, chercher 'Freebox Python Plugin'.
-Laissez les valeur par defaut sur un réseau local, ou configurez votre adresse et port.
-Ajoutez le Matériel et rendez vous dans les log.
-Lors de la première utilisation, laissez le token vide.
+Note : Lors de la première utilisation le champ « Token » doit rester vide.
 
-Au démarrage, si le token n'est pas défini, le plugin en demander un à la Freebox, il vous faut alors vous déplacer jusqu'à l'écran de la Freebox pour répondre oui, puis revenir sur votre Domoticz pour copier coller le token qui s'affiche dans la fenetre de log, dans la partie Token de configuration du plugin.
+Au démarrage du plugin, si aucun token n’est renseigné, le plugin va s’enregistrer auprès de la Freebox. Vous devrez alors valider la demande directement depuis l’écran de votre box.  Après avoir répondu « oui » (il faudra vous déplacer jusqu’à votre Freebox), vous devrez « copier » (puis coller) le token qui s'affichera dans les logs du serveur Domoticz.
+Ce token sera à « coller » dans le champ « Token » de la configuration du plugin.
 
-Desactivez le plugin, autoriser l'ajout de nouveau dispositif pendant 5 minutes, puis réacivez le plugin pour le faire redemarrer.
-Les dispositifs vont se créer.
-A chaque démarrage du plugin, les dispositifs nouveaux ou maquant seront ajoutés.
-Vous pouvez supprimer ceux qui ne vous interresse pas et inclure ceux qui vous interresse.
+Enfin, pour créer les dispositifs il faudra:
+- Désactiver le plugin
+- Autoriser l'ajout de nouveau dispositif pendant 5 minutes
+- Réactiver le plugin
+
+A chaque démarrage du plugin, les dispositifs nouveaux ou maquants seront ajoutés.
+Vous pouvez choisir d’inclure ou non ces dispositifs à depuis l'interface dediée.
 
 | Dispositifs | Description|
 | ----- | ---------- |
-| Système | Températures de la Freebox et du switch interne  |
-| Disque | Pourcentage d'espace utilisé de chaque partition connectées à la Freebox au moment du démarrage du Plugin avec autorisation d'ajout de dispositifs |
-| Présence | Pour chaque adresse mac renseignée, si elle est trouvée enregistrée sur la Freebox, un dispositif switch est créé, indiquant la presence (on) ou l'absence (off) du matériel à proximité de la box. Cela permet de tester la presence d'une personne au domicile en vérifiant la presence de sont smartphone par exemple. Cela fonctionne, même avec les Iphones |
-| On/Off Wifi | Switch permettant de voir l'état du wifi (actif/Desactivé) et de le modifier  |
-| Reboot | Switch permettant de rebooter la Freebox  |
-| WANStatus | Etat de la connection Internet |
-| Debits | Debits montants et descendants en Ko/s |
-
-ATTENTION : Pour faire fonctionner le On/Off Wifi et le reboot, il faut autoriser le plugin a faire ces deux actions sur la Freebox. Lors de la génération du token, le plugin a été autorisé à récupérer les infos, mais pas à les modifier. Il faut pour cela aller dans l'interface Freebox OS via le menu Paramètres de la Freebox > Gestion des accès > onglet Applications, sélectionner le plugin Domoticz et cocher Modifications des réglages de la Freebox".
+| Système | Remontées des températures des sondes internes à la Freebox |
+| Disque | Affichage du taux d'occupation (en %) de chaque partitions du/des disque(s) connecté(s) à la Freebox |
+| Présence | Test la présence d'un équipement. Pour chaque adresse mac renseignée, si celle-ci est joignable par la Freebox, un dispositif de type Switch sera créé. Il indiquera la disponibilité (on) ou l'absence (off) de l'équipement. Cela permet de déduire la présence d'une personne au domicile en testant (par exemple) la présence de sont smartphone. |
+| Wifi | Affichage du statut du wifi (actif/inactif) et Switch permettant de modifier l'état (activation/désactivation) |
+| Reboot | Switch permettant le redémarrage de la Freebox |
+| WANStatus | État de la connexion Internet |
+| Debits | Débits montants et descendants en Ko/s |
+| Alarme | Dispositif de type Switch permettant de voir l'état de l'alarme (active/inactive) et de piloter son activation/désactivation |
+| Players | Dispositif(s) de type Switch permettant d'alumer / éteindre le(s) player(s) TV |
+| Precord | Dispositif indiquant dans combien de temps aura lieu le prochain enregistrement de programme TV. L'idée est de déterminer plus facilement si le serveur Freebox peut-être éteint ou non (exemple en pilotant une mutiprise la nuit) |
+
+IMPORTANT : Pour piloter le wifi, le redémarrage de la box, gérer le player ou l'alarme, il est nécessaire d'accorder des droits spécifiques au plugin. Effectivement après l'inscription, le plugin n'aura que de simples droits de consultations.
+Les droits de modification devront être positionnés manuellement via l'interface Freebox OS (depuis un navigateur http://mafreebox.freebox.fr) : menu "Paramètres de la Freebox" > "Gestion des accès" > "onglet Applications", sélectionner le plugin Domoticz puis cocher :
+- "Modifications des réglages de la Freebox" (pour permettre la gestion du wifi ou le redémarrage de la box)
+- "Gestion de l'alarme et maison connectée" (pour permettre la gestion de l'alarme "Freebox Delta")
+- "Contrôle du Freebox Player" (pour mettre la supervision du player TV)
 
 Note : Un fichier ```devicemapping.json``` est créé pour garder l'association des infos de la Freebox avec le bon device créé au moment du démarrage du Plugin.
 
 ## Change log
 
 | Version | Information|
 | ----- | ---------- |
-| 1.0 | Version initial : connexion (token), températures système, espace disque, présence |
-| 1.1 | Ajout des switch WIFI et Reboot. Ajout d'une pause au démarrage du plugin pour corriger certains pb |
+| 1.0 | Version initial : connexion (token), températures système, espace disque, présence (https://matdomotique.wordpress.com/2018/03/25/plugin-freebox-pour-domoticz/)|
+| 1.1 | Ajout des switch « WIFI » et « Reboot ». Ajout d'une pause au démarrage du plugin pour corriger certains pb |
 | 1.1.1 | Prise en compte de l'adresse MAC en Majuscule ou minuscule pour la présence |
 | 1.1.2 | Prise en compte de la Freebox mini 4K (qui n'a pas de disque interne) en conservant l'usage des disques externes |
 | 1.1.3 | Prise en compte de la Freebox POP pour les températures (slallemand) et Ajout des détails de connection debits montants et descendant en Ko/s (chupi33 et les tests des ViaudJV) |
+| 1.2.0 | Reprise et refonte du code pour un meilleur respect des standards de programmations Python |
+| 1.3.0 | Intégration de l'option alarme de la FreeBox Delta (sur base du développement proposé par nachonam) |
+| 1.4.0 | Ajout du support d'HTTPS/TLS (chiffrement des communications) |
+| 1.5.0 | Integration _*Expérimentale*_ du player TV (supervision de l’état allumé/éteint) |
+| 2.0.0 | Passage à l'API v8 + correctifs (sondes températures, alarme, disque...) |
+| 2.1.0 | Amélioration de la robustesse du code suite au passage en 2.0 |
+| 2.1.1 | Possibilitée de paramétrer la fréquence de rafraîchissement des valeurs |
+| 2.1.2 | Possibilité d'éteindre le Player via Domoticz |
+| 2.1.3 | Ajout compteur indiquant le délai (en seconde) avant le prochain enregistrement |
+| 2.1.4 | Suivi de recommandations Sonarcube (amélioration de la qualité du code) |