domoticz_ynh/README_fr.md

<!--
N.B.: This README was automatically generated by https://github.com/YunoHost/apps/tree/master/tools/README-generator
It shall NOT be edited by hand.
-->

# Domoticz pour YunoHost

[![Niveau d’intégration](https://dash.yunohost.org/integration/domoticz.svg)](https://dash.yunohost.org/appci/app/domoticz) ![Statut du fonctionnement](https://ci-apps.yunohost.org/ci/badges/domoticz.status.svg) ![Statut de maintenance](https://ci-apps.yunohost.org/ci/badges/domoticz.maintain.svg)

[![Installer Domoticz avec YunoHost](https://install-app.yunohost.org/install-with-yunohost.svg)](https://install-app.yunohost.org/?app=domoticz)

*[Read this readme in english.](./README.md)*

> *Ce package vous permet d’installer Domoticz rapidement et simplement sur un serveur YunoHost.
Si vous n’avez pas YunoHost, regardez [ici](https://yunohost.org/#/install) pour savoir comment l’installer et en profiter.*

## Vue d’ensemble

Domoticz est un système de domotique permettant de controler différents objets et de recevoir des données de divers senseurs
Il peut par exemple être utilisé avec :

* des interrupteurs
* des senseurs de portes
* des sonnettes d'entrées
* des systèmes de sécurité
* des stations météo pour les UV, la pluie, le vent...
* des sondes de températures
* des sondes d'impulsions
* des voltmètres
* Et bien d'autres

**Version incluse :** Toujours la dernière version stable. La dernière version compilée est récupérée dans [ce répertoire](https://releases.domoticz.com/releases/?dir=./release) lors de l'installation.
Une fois installée, **les mises à jour de l'application sont gérées depuis les menus de l'application elle même**. Le script de mise à jour Yunohost mettra uniquement à jour de nouvelles version du package.

Le broker MQTT mosquitto est intégré au package et nécessite un sous-domaine ou un domaine distinct. Il est optionnel et si vous indiquez lors de l'installation le même domaine que le domaine principal, il ne sera pas installé.

## Configuration

### Broker MQTT Mosquitto

A l'installation, un broker [MQTT](https://fr.wikipedia.org/wiki/MQTT), [Mosquitto](https://mosquitto.org/), est installé en même temps que Domoticz. La version installée est celle du dépot officiel du projet, et non des dépots Debian.
Ce broker nécessite un domaine ou un sous-domaine particulier pour fonctionner (ex : mqtt.your.domain.tld) : il est nécessaire de créer ce domaine auparavant.

#### Ajout dans domoticz

Pour pouvoir l'utiliser, vous devez paramétrer la communication avec entre domoticz et le broker en suivant la [documentation de domoticz](https://www.domoticz.com/wiki/MQTT#Installing_Mosquitto) dans la partie *Add hardware "MQTT Client Gateway"*
Les users et mot de passe du broker sont automatiquement générés lors de l'installation. Vous pouvez les récupérer avec
````
sudo yunohost app setting domoticz mqtt_user
sudo yunohost app setting domoticz mqtt_pwd
````

#### Publier/souscrire

Par défaut, mosquitto va écouter sur 2 ports:
- Le 1883 sur localhost en protocole mqtt
- Le 8883 en protocole websocket. Nginx redirige le port 443 externe vers ce port en interne.
Pour publier/souscrire sur un topic depuis l'exterieur, vous devez donc utiliser un programme supportant le protocole websocket (ex : la bibliothèque python paho).:

#### Mosquitto_pub et mosquitto_sub

Ces deux programmes ne supportent pas le protocole websocket mais uniquement le mqtt : le paramétrage de base ne vous autorise donc pas à les utiliser pour communiquer depuis un client externe.
Si vous les utilisez directement depuis votre serveur, ce genre de syntaxe devrait marcher:
````
mosquitto_pub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/in' -m '{ "idx" : 1, "nvalue" : 0, "svalue" : "25.0" }'
````
De la même manière:c
````
mosquitto_sub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/out'
````
Si vous souhaitez ouvrir le protocole mqtt depuis l'extérieur afin de pouvoir les utiliser depuis un autre serveur, il vous faudra:
- ouvrir le port 1883 sur le firewall Yunohost (**Attention, risque de sécurité**)
- autoriser les adresses IP souhaitées dans la configuration de mosquitto pour ce listener
- paramétrer le tls dans la configuration de mosquitto en donnant accès au crt.pem et key.pem de votre domaine mqtt en les paramétrant respectivement avec les variables certfile et keyfile. **Ceci est obligatoire pour sécuriser la connexion.**




#### Mise à jour depuis les versions n'ayant pas mosquittoo
Si vous êtes sur le package ynh3 ou inférieur, mosquitto n'est pas installé par défaut.
De même si vous avez choisi de ne pas indiquer de domaine pour mosquitto lors de l'installation initiale.
Pour pouvoir l'installer après coup, faites les actions suivantes:
1. créez un domaine ou sous-domaine pour recevoir les informations (par exemple : 'mqtt.your.domain.tld')
2. connecter vous en ligne de commande à votre serveur
3. taper la commande suivante : `yunohost app setting domoticz mqtt_domain -v mqtt.your.domain.tld`
4. Procédez à la mise à jour.
Si vous êtes déjà sur la dernière version, utiliser la commmande suivante : `yunohost app upgrade domoticz --force`


### Senseurs, langue et ce genre de choses
Toute la configuration de l'application a lieu dans l'application elle même

### Gestion du Zwave
Si vous utilisez des équipements zwave, installez mosquitto en plus de domoticz et essayez le [package zwave-JS-UI](https://github.com/YunoHost-Apps/zwave-js-ui_ynh).
Une fois installé, suivez simplement les indications du [wiki](https://www.domoticz.com/wiki/Zwave-JS-UI)

### Accès et API
Par défaut, l'accès aux [API JSON](https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's) est autorisé sur cette URL `/votredomaine.tld/api_/chemindedomoticz`.
Donc, si vous accédez à domoticz par https://votredomaine.tld/domoticz, utilisez le chemin suivant pour l'api: `/votredomaine.tld/api_/domoticz/json.htm?votrecommandeapi`

Par défaut, seule la mise à jour de senseur et les interrupteurs sont autorisés. Pour autoriser une nouvelle commande, vous devez manuellement éditer le fichier de configuration nginx :
````
sudo nano /etc/nginx/conf.d/yourdomain.tld.d/api_domoticz.conf
````
Puis éditer le bloc suivant en y ajoutant le regex de la commmande à autoriser :
````
  #set the list of authorized json command here in regex format
  #you may retrieve the command from https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's
  #By default, sensors updates and toggle switch are authorized
  if ( $args ~* type=command&param=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command&param=switchlight&idx=[0-9]*&switchcmd=Toggle$) {
    set $api "1";
    }
````
Par exemple, pour ajouter la commmande json pour retrouver le statut d'un équipement (/json.htm?type=devices&rid=IDX),il faut modifier la ligne comme ceci:
````
  if ( $args ~* type=command&param=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command&param=switchlight&idx=[0-9]*&switchcmd=Toggle$|type=devices&rid=[0-9]* ) {
    set $api "1";
    }
````

Toutes les adresses IPv4 du réseau local (192.168.0.0/24) et toutes les adresses IPv6 sont autorisées pour l'API.
A ma connaissance, il n'y a pas moyen d'effectuer un filtre pour les adresses IPv6 sur le réseau local, vous pouvez donc retirer leur autorisation en enlevant ou en commentant la ligne suivante dans `/etc/nginx/conf.d/yourdomain.tld.d/domoticz.conf`:
````
allow ::/1;
````
Ceci autorisera seulement les adresses IPv4 local a accéder aux API de domoticz.
Vous pouvez ajouter des adresses IPv6 de la même façon.


**Version incluse :** 2020.2~ynh7
## Avertissements / informations importantes


## Limitations

* Pas de gestion d'utilisateurs ni d'intégration LDAP. L'application ne [prévoit pas de gérer les utilisateurs par LDAP](https://github.com/domoticz/domoticz/issues/838), donc le package non plus.
* Un backup ne peut pas être restauré sur un type de machine différente de celle d'origine (x86, arm...) car les sources compilées sont différentes

## A propos de la sécurité

Bien que vous pouviez activer une page de connexion dans l'application (soit depuis le menu *Configuration/Paramètres/Système/Sécurité* ou depuis *Configuration/Plus d'options/Gérer les utilisateurs*), les fonctionnalités ne semblent pas très avancées ni safe pour l'instant (version 2022.2 au moment d'écrire). Un travail a été entrepris pour renforcer la sécurité ([voir ici](https://www.domoticz.com/wiki/Security)) dans les versions futures mais n'a pas encore été released.

### recommandations

Il semble conseillé de ne pas rendre l'application publique en dehors du sso yunohost (public = oui à l'installation ou mettre la permission domoticz à 'Visiteurs' dans le panel d'administration Yunohost). Si pour quelques raisons que ce soit, vous deviez le faire, je vous recommande:
 - d'activer la sécurité de connexion à domoticz (plutot avec la login page qu'avec la basic-auth)
 - Dans *Configuration/Système/Réseaux Locaux (pas d'authentification)* d'entrer les adresses du proxy nginx (cela devrait être "::1;127.0.0.1" dans une installation Yunohost Standard) afin que Fail2ban puisse bloquer les tentatives de connexions (voir les dernières lignes de [ce wiki](https://www.domoticz.com/wiki/WebServer_Proxy)
## Documentations et ressources

* Site officiel de l’app : <https://domoticz.com/>
* Documentation officielle utilisateur : <https://www.domoticz.com/DomoticzManual.pdf>
* Documentation officielle de l’admin : <https://www.domoticz.com/wiki/Main_Page>
* Dépôt de code officiel de l’app : <https://github.com/domoticz/domoticz>
* Documentation YunoHost pour cette app : <https://yunohost.org/app_domoticz>
* Signaler un bug : <https://github.com/YunoHost-Apps/domoticz_ynh/issues>

## Informations pour les développeurs

Merci de faire vos pull request sur la [branche testing](https://github.com/YunoHost-Apps/domoticz_ynh/tree/testing).

Pour essayer la branche testing, procédez comme suit.

``` bash
sudo yunohost app install https://github.com/YunoHost-Apps/domoticz_ynh/tree/testing --debug
ou
sudo yunohost app upgrade domoticz -u https://github.com/YunoHost-Apps/domoticz_ynh/tree/testing --debug
```

**Plus d’infos sur le packaging d’applications :** <https://yunohost.org/packaging_apps>