YunoHost-Apps/domoticz_ynh
1
0
Fork 0
mirror of https://github.com/YunoHost-Apps/domoticz_ynh.git synced 2024-09-03 18:26:17 +02:00
Code Issues Activity Actions

Typo

Browse source
This commit is contained in:
Krakinou 2024-01-20 16:11:54 +01:00
parent 441395cf35
commit 9932be0258
2 changed files with 28 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
doc/ADMIN.md
View file

@ -3,11 +3,11 @@
### 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.
This broker requires a dedicated domain or subdomain to work (ex : mqtt.your.domain.tld) : creating this domain prior installation is a prerequisite
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
#### 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"*.
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
@ -17,10 +17,10 @@ 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.
- 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).
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
@ -35,17 +35,17 @@ mosquitto_sub -u *user* -P *password* -h mqtt.your.domain.tld -p 1883 -t 'domoti
````
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.**
- 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 2020.2~ynh3 or below or if you have chosen to not set a domain during initial installation, mosquitto is not installed by default.
#### Upgrade from version without Mosquitto
If you have package 2020.2~ynh3 or below or if you have chosen to not set a domain during initial installation, Mosquitto is not installed by default.
If you need to activate mosquitto in retrospect, do following actions:
1. Create a domain or a subdomain (for example : 'mqtt.your.domain.tld')
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.
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
@ -54,12 +54,12 @@ If you're already on the last package version, use the following command : `yuno
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).
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`
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 to manually update the nginx config file :
````
@ -67,14 +67,14 @@ sudo nano /etc/nginx/conf.d/yourdomain.tld.d/api_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
#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";
}
````
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:
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:
````
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";
@ -82,11 +82,11 @@ For example, to add the json command to retrieve the status of a device (/json.h
````
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`:
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.
This will authorized only IPv4 within local network to access your Domoticz API.
You may add individual IPv6 address in the same way.
## Limitations

18
doc/ADMIN_fr.md
View file

@ -2,29 +2,29 @@
### Broker MQTT Mosquitto
Vous pouvez install le broker [MQTT](https://fr.wikipedia.org/wiki/MQTT) [Mosquitto](https://github.com/YunoHost-Apps/mosquitto_ynh) simultanément à domoticz.
Vous pouvez install le broker [MQTT](https://fr.wikipedia.org/wiki/MQTT) [Mosquitto](https://github.com/YunoHost-Apps/mosquitto_ynh) simultanément à Domoticz.
#### Ajout dans domoticz
#### 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"*
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"*
#### Migration depuis la version 2020.2~ynh7
Avant la version 2023.2~ynh1, domoticz_ynh pouvait intégrer directement le broker mosquitto lors de son installation. Cette option n'est plus maintenu car trop complexe.
Pour migrer vers depuis une installation de mosquitto "intradomoticz" vers le package officiel de mosquitto pour domoticz, merci de consulter cette [documentation]
Avant la version 2023.2~ynh1, domoticz_ynh pouvait intégrer directement le broker Mosquitto lors de son installation. Cette option n'est plus maintenu car trop complexe.
Pour migrer vers depuis une installation de Mosquitto "intradomoticz" vers le package officiel de Mosquitto pour Domoticz, merci de consulter cette [documentation]
### 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).
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`
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 :
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
````
@ -49,7 +49,7 @@ A ma connaissance, il n'y a pas moyen d'effectuer un filtre pour les adresses IP
````
allow ::/1;
````
Ceci autorisera seulement les adresses IPv4 local a accéder aux API de domoticz.
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