mirror of
https://github.com/YunoHost-Apps/domoticz_ynh.git
synced 2024-09-03 18:26:17 +02:00
Update documentation for zwave
This commit is contained in:
Krakinou
parent
ccdf9d823b
commit
3a1f4a4ec3
4 changed files with 225 additions and 217 deletions
113
doc/DESCRIPTION.md
Normal file
113
doc/DESCRIPTION.md
Normal file
|
|
@ -0,0 +1,113 @@
|
||||||
|
Domoticz is a Home Automation system design to control various devices and receive input from various sensors.
|
||||||
|
For example this system can be used with:
|
||||||
|
|
||||||
|
* Light switches
|
||||||
|
* Door sensors
|
||||||
|
* Doorbells
|
||||||
|
* Security devices
|
||||||
|
* Weather sensors like: UV/Rain/Wind Meters
|
||||||
|
* Temperature Sensors
|
||||||
|
* Pulse Meters
|
||||||
|
* Voltage / AD Meters
|
||||||
|
* And more ...
|
||||||
|
|
||||||
|
|
||||||
|
**Shipped version:** Always the last stable one. The last compiled version is retrieved from [this directory](https://releases.domoticz.com/releases/?dir=./release) during install.
|
||||||
|
Once installed, **updates from the uptream app are managed from within the app**. Yunohost upgrade script will only upgrade the Yunohost package.
|
||||||
|
|
||||||
|
The MQTT broker mosquitto is integrated into the package. It requires its own domain or subdomain. It's an optional setting: during install if you set the same domaine as your main app domain, it won't be installed.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Broker Mosquitto
|
||||||
|
|
||||||
|
During installation, a [MQTT](https://en.wikipedia.org/wiki/MQTT) broker, [Mosquitto](https://mosquitto.org/), is installed at the same time as Domoticz. The installed version is the one from the official project repo and not from Debian ones.
|
||||||
|
This broker requires a dedicated domain or subdomain to work (ex : mqtt.your.domain.tld) : creating this domain prior installation is a prerequisite
|
||||||
|
|
||||||
|
#### Adding in domoticz
|
||||||
|
|
||||||
|
To use mosquitto, you need to customize the communication between domoticz and the broker by following the [domoticz documentation](https://www.domoticz.com/wiki/MQTT#Installing_Mosquitto), part *Add hardware "MQTT Client Gateway"*.
|
||||||
|
User and password are automatically generated during installation, you may retrieve them with
|
||||||
|
````
|
||||||
|
sudo yunohost app setting domoticz mqtt_user
|
||||||
|
sudo yunohost app setting domoticz mqtt_pwd
|
||||||
|
````
|
||||||
|
|
||||||
|
#### Publish/Subscribe
|
||||||
|
|
||||||
|
By default, mosquitto will listen on 2 ports:
|
||||||
|
- 1883 on localhost using mqtt protocol
|
||||||
|
- 8883 using websocket protocol. Nginx redirect external port 443 to this internal port.
|
||||||
|
|
||||||
|
Hence, To publish/subscribe on a topic from the outside, you have to use a software supporting websocket protocol (ex : paho python library).
|
||||||
|
|
||||||
|
#### Mosquitto_pub et mosquitto_sub
|
||||||
|
|
||||||
|
These 2 tools do not support websocket protocol, only direct mqtt: base settings will not allow communication from an outside device.
|
||||||
|
If you're using them directly from your server, this kind of syntax should work:
|
||||||
|
````
|
||||||
|
mosquitto_pub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/in' -m '{ "idx" : 1, "nvalue" : 0, "svalue" : "25.0" }'
|
||||||
|
````
|
||||||
|
In the same way:
|
||||||
|
````
|
||||||
|
mosquitto_sub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/out'
|
||||||
|
````
|
||||||
|
|
||||||
|
If you wish to open direct mqtt protocol from an outside device, you'll need to:
|
||||||
|
- open port 1883 on Yunohost firewall (**Attention, security risk**)
|
||||||
|
- Allows IP addresses in mosquitto configuration for this listener
|
||||||
|
- Set the tls setting in mosquitto configuration by giving access to crt.pem and key.pem from your mqtt domain by setting respective certfile et keyfile variables. **This is mandatory to ensure a secure connection.**
|
||||||
|
|
||||||
|
#### Upgrade from version without mosquitto
|
||||||
|
If you have package ynh3 or below, mosquitto is not installed by default.
|
||||||
|
If you have chosen to not set a domain during initial installation also.
|
||||||
|
So, if you need to activate mosquitto in retrospect, do following actions:
|
||||||
|
1. Create a domain or a subdomain (for example : 'mqtt.your.domain.tld')
|
||||||
|
2. Connect to your server in command line
|
||||||
|
3. Type following command : `yunohost app setting domoticz mqtt_domain -v mqtt.your.domain.tld`
|
||||||
|
4. Upgrade domoticz to last package.
|
||||||
|
If you're already on the last package version, use the following command : `yunohost app upgrade domoticz --force`
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Sensors, language and this kind of stuff
|
||||||
|
Main configuration of the app take place inside the app itself.
|
||||||
|
|
||||||
|
### Zwave management
|
||||||
|
If you're using zwave devices, install mosquitto along domoticz and give a try to [zwave-JS-UI package](https://github.com/YunoHost-Apps/zwave-js-ui_ynh).
|
||||||
|
Once installed, just follow instructions from the [wiki](https://www.domoticz.com/wiki/Zwave-JS-UI)
|
||||||
|
|
||||||
|
### Access and API
|
||||||
|
By default, access for the [JSON API](https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's) is allowed on following path `/yourdomain.tld/api_/domoticzpath`.
|
||||||
|
So if you access domoticz via https://mydomainname.tld/domoticz, use the following webpath for the api : `/mydomainname.tld/api_/domoticz/json.htm?yourapicommand`
|
||||||
|
|
||||||
|
By default, only sensor updates and switch toogle are authorized. To authorized a new command, you have (for now) to manually update the nginx config file :
|
||||||
|
````
|
||||||
|
sudo nano /etc/nginx/conf.d/yourdomain.tld.d/domoticz.conf
|
||||||
|
````
|
||||||
|
Then edit the following block by adding the regex of the command you want to allow:
|
||||||
|
````
|
||||||
|
#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¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=switchlight&idx=[0-9]*&switchcmd=Toggle$) {
|
||||||
|
set $api "1";
|
||||||
|
}
|
||||||
|
````
|
||||||
|
For example, to add the json command to retrieve the status of a device (/json.htm?type=devices&rid=IDX),modify the line as this:
|
||||||
|
````
|
||||||
|
#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¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=switchlight&idx=[0-9]*&switchcmd=Toggle$|type=devices&rid=[0-9]* ) {
|
||||||
|
set $api "1";
|
||||||
|
}
|
||||||
|
````
|
||||||
|
|
||||||
|
All IPv4 addresses within the local network (192.168.0.0/24) and *all IPv6* addresses are authorized as API.
|
||||||
|
As far as I know, there is no way to filter for IPv6 address on local network : You may remove the authorization by removing or commenting this line in `/etc/nginx/conf.d/yourdomain.tld.d/domoticz.conf`:
|
||||||
|
````
|
||||||
|
allow ::/1;
|
||||||
|
````
|
||||||
|
This will authorized only IPv4 within local network to access your domoticz API.
|
||||||
|
You may add individual IPv6 address in the same way.
|
||||||
112
doc/DESCRIPTION_fr.md
Normal file
112
doc/DESCRIPTION_fr.md
Normal file
|
|
@ -0,0 +1,112 @@
|
||||||
|
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 (pour l'instant) manuellement éditer le fichier de configuration nginx :
|
||||||
|
````
|
||||||
|
sudo nano /etc/nginx/conf.d/yourdomain.tld.d/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¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=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:
|
||||||
|
````
|
||||||
|
#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¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=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.
|
||||||
|
|
@ -1,112 +1,3 @@
|
||||||
Domoticz is a Home Automation system design to control various devices and receive input from various sensors.
|
|
||||||
For example this system can be used with:
|
|
||||||
|
|
||||||
* Light switches
|
|
||||||
* Door sensors
|
|
||||||
* Doorbells
|
|
||||||
* Security devices
|
|
||||||
* Weather sensors like: UV/Rain/Wind Meters
|
|
||||||
* Temperature Sensors
|
|
||||||
* Pulse Meters
|
|
||||||
* Voltage / AD Meters
|
|
||||||
* And more ...
|
|
||||||
|
|
||||||
|
|
||||||
**Shipped version:** Always the last stable one. The last compiled version is retrieved from [this directory](https://releases.domoticz.com/releases/?dir=./beta) during install.
|
|
||||||
Once installed, **updates from the uptream app are managed from within the app**. Yunohost upgrade script will only upgrade the Yunohost package.
|
|
||||||
|
|
||||||
The MQTT broker mosquitto is integrated into the package. It requires its own domain or subdomain. It's an optional setting: during install if you set the same domaine as your main app domain, it won't be installed.
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
### Broker Mosquitto
|
|
||||||
|
|
||||||
During installation, a [MQTT](https://en.wikipedia.org/wiki/MQTT) broker, [Mosquitto](https://mosquitto.org/), is installed at the same time as Domoticz. The installed version is the one from the official project repo and not from Debian ones.
|
|
||||||
This broker requires a dedicated domain or subdomain to work (ex : mqtt.your.domain.tld) : creating this domain prior installation is a prerequisite
|
|
||||||
|
|
||||||
#### Adding in domoticz
|
|
||||||
|
|
||||||
To use mosquitto, you need to customize the communication between domoticz and the broker by following the [domoticz documentation](https://www.domoticz.com/wiki/MQTT#Installing_Mosquitto), part *Add hardware "MQTT Client Gateway"*.
|
|
||||||
User and password are automatically generated during installation, you may retrieve them with
|
|
||||||
````
|
|
||||||
sudo yunohost app setting domoticz mqtt_user
|
|
||||||
sudo yunohost app setting domoticz mqtt_pwd
|
|
||||||
````
|
|
||||||
|
|
||||||
#### Publish/Subscribe
|
|
||||||
|
|
||||||
By default, mosquitto will listen on 2 ports:
|
|
||||||
- 1883 on localhost using mqtt protocol
|
|
||||||
- 8883 using websocket protocol. Nginx redirect external port 443 to this internal port.
|
|
||||||
|
|
||||||
Hence, To publish/subscribe on a topic from the outside, you have to use a software supporting websocket protocol (ex : paho python library).
|
|
||||||
|
|
||||||
#### Mosquitto_pub et mosquitto_sub
|
|
||||||
|
|
||||||
These 2 tools do not support websocket protocol, only direct mqtt: base settings will not allow communication from an outside device.
|
|
||||||
If you're using them directly from your server, this kind of syntax should work:
|
|
||||||
````
|
|
||||||
mosquitto_pub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/in' -m '{ "idx" : 1, "nvalue" : 0, "svalue" : "25.0" }'
|
|
||||||
````
|
|
||||||
In the same way:
|
|
||||||
````
|
|
||||||
mosquitto_sub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoticz/out'
|
|
||||||
````
|
|
||||||
|
|
||||||
If you wish to open direct mqtt protocol from an outside device, you'll need to:
|
|
||||||
- open port 1883 on Yunohost firewall (**Attention, security risk**)
|
|
||||||
- Allows IP addresses in mosquitto configuration for this listener
|
|
||||||
- Set the tls setting in mosquitto configuration by giving access to crt.pem and key.pem from your mqtt domain by setting respective certfile et keyfile variables. **This is mandatory to ensure a secure connection.**
|
|
||||||
|
|
||||||
#### Upgrade from version without mosquitto
|
|
||||||
If you have package ynh3 or below, mosquitto is not installed by default.
|
|
||||||
If you have chosen to not set a domain during initial installation also.
|
|
||||||
So, if you need to activate mosquitto in retrospect, do following actions:
|
|
||||||
1. Create a domain or a subdomain (for example : 'mqtt.your.domain.tld')
|
|
||||||
2. Connect to your server in command line
|
|
||||||
3. Type following command : `yunohost app setting domoticz mqtt_domain -v mqtt.your.domain.tld`
|
|
||||||
4. Upgrade domoticz to last package.
|
|
||||||
If you're already on the last package version, use the following command : `yunohost app upgrade domoticz --force`
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
### Sensors, language and this kind of stuff
|
|
||||||
Main configuration of the app take place inside the app itself.
|
|
||||||
|
|
||||||
### Access and API
|
|
||||||
By default, access for the [JSON API](https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's) is allowed on following path `/yourdomain.tld/api_/domoticzpath`.
|
|
||||||
So if you access domoticz via https://mydomainname.tld/domoticz, use the following webpath for the api : `/mydomainname.tld/api_/domoticz/json.htm?yourapicommand`
|
|
||||||
|
|
||||||
By default, only sensor updates and switch toogle are authorized. To authorized a new command, you have (for now) to manually update the nginx config file :
|
|
||||||
````
|
|
||||||
sudo nano /etc/nginx/conf.d/yourdomain.tld.d/domoticz.conf
|
|
||||||
````
|
|
||||||
Then edit the following block by adding the regex of the command you want to allow:
|
|
||||||
````
|
|
||||||
#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¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=switchlight&idx=[0-9]*&switchcmd=Toggle$) {
|
|
||||||
set $api "1";
|
|
||||||
}
|
|
||||||
````
|
|
||||||
For example, to add the json command to retrieve the status of a device (/json.htm?type=devices&rid=IDX),modify the line as this:
|
|
||||||
````
|
|
||||||
#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¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=switchlight&idx=[0-9]*&switchcmd=Toggle$|type=devices&rid=[0-9]* ) {
|
|
||||||
set $api "1";
|
|
||||||
}
|
|
||||||
````
|
|
||||||
|
|
||||||
All IPv4 addresses within the local network (192.168.0.0/24) and *all IPv6* addresses are authorized as API.
|
|
||||||
As far as I know, there is no way to filter for IPv6 address on local network : You may remove the authorization by removing or commenting this line in `/etc/nginx/conf.d/yourdomain.tld.d/domoticz.conf`:
|
|
||||||
````
|
|
||||||
allow ::/1;
|
|
||||||
````
|
|
||||||
This will authorized only IPv4 within local network to access your domoticz API.
|
|
||||||
You may add individual IPv6 address in the same way.
|
|
||||||
|
|
||||||
## Limitations
|
## Limitations
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,111 +1,3 @@
|
||||||
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=./beta) 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.e
|
|
||||||
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
|
|
||||||
|
|
||||||
### 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, seuls la mise à jour de senseur et les interrupteurs sont autorisés. Pour autoriser une nouvelle commande, vous devez (pour l'instant) manuellement éditer le fichier de configuration nginx :
|
|
||||||
````
|
|
||||||
sudo nano /etc/nginx/conf.d/yourdomain.tld.d/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¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=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:
|
|
||||||
````
|
|
||||||
#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¶m=udevice&idx=[0-9]*&nvalue=[0-9]*&svalue=.*$|type=command¶m=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.
|
|
||||||
|
|
||||||
## Limitations
|
## Limitations
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue