1. Description
1.1. mySensors, un protocole domotique DIY
Le plugin MySensors permet d’utiliser des équipement utilisant le protocole MySensors.
Les équiments MySensors sont des capteurs ou actionneurs à base d’Arduino et d’une puce NRF24L01 pour la communication
A monter soit même, dans la mouvance DIY (Do It Yourself, Faites le Vous Même), ce qui permet d’avoir un coût de revient très faible et une flexibilité sans limite. Les limites de possibilités mySensors sont celles du catalogue de composants connectables à un Arduino et les exemples existants.
1.2. Que fait le plugin Jeedom pour mySensors
Le plugin mySensors permet d’utiliser les équipements mySensors via une gateway série ou réseau.
Le plugin permet :
-
création automatique des noeuds comme équipements lors de leur démarrage (avec leur sketch, version de sketch et de lib)
-
création automatique des capteurs comme informations lors de leur démarrage
-
création automatique de certaines commandes en fonction du type de capteur
-
ajouter des commandes spécifiques sur un noeud qui ne peuvent être déduites
-
reboot d’un noeud depuis la page d’équipement (pour les noeuds dont le bootloader permet l’action)
1.3. mySensors, qu’est-ce que ca peut faire ?
mySensors reconnait la communication bidirectionnelle, on peut donc avoir de simples capteurs (température, mouvement …) mais aussi des actionneurs (relais, verrou …)
Le protocole prend en charge l’acquittement et le retour d’état. On y dispose d’une configuration de l’activation de l’association de nouveaux noeuds.
En revanche aujourd’hui le protocole n’est pas chiffré. Néanmoins, il est nécessaire de connaitre la fréquence de communication (réglable dans la lib) et connaitre le protocole pour déchiffrer les trames.
Tous les capteurs classiques sont faisables. Température, multi-capteurs, mouvement … A condition de mettre un peu d’huile de coude et souvent de la soudure pour obtenir un bon résultat sur ces capteurs nécessitant d’être apparent et de taille réduite.
Mais il est possible également de répondre à des besoins plus exotiques pour lesquels il n’existe pas de matériel sur le marché dans des protocoles classiques (Zwave, Enocean …)
Quelques exemples : mesure de niveau d’une citerne ou réservoir de pelets/granulés, systèmes de capteurs pour le jardin/aquarium …
2. Configuration
2.1. Configuration du plugin
Sur la page de configuration du plugin, vous pourrez sélectionner la ou les gateway à utiliser.
Attention toutefois, il n’est pas conseillé d’avoir 2 gateways pour le même réseau de nodes.
Aussi, vous pourrez avoir deux jeedom éloignés gérant le même type de noeuds (NRF) sur la même fréquence. Mais si les 2 sont à portée de plusieurs capteurs, il faudra avoir des fréquences différentes ou des puces RF différentes (NRF et RFM)
2.1.1. Serial Gateway
Vous pouvez sélectionner une gateway série par Jeedom installé (maitre ou esclave)
2.1.2. Network Gateway
Vous pouvez ajouter des gateways réseaux.
2.2. Menu mySensors
Vous retrouverez toute la configuration des équipements (informations et commandes) dans le menu Plugins→Protocole domotique→mySensors
2.2.1. Configuration des nodes et leurs capteurs
Les équipements Jeedom sont automatiquement créés au démarrage des nodes.
De la même facon que les équipements sont automatiquement créés à l’arrivée de nouveaux nodes, les capteurs des nodes sont automatiquement créés comme des "Informations" dans Jeedom.
Exemple : si on reprend le cas du capteur de température, le protocole mySensors inclut une présentation du noeud sur son réseau, il envoit les informations qu’il fournit : température, niveau de batterie, humidité … automatiquement, le controleur créé les informations associées avec leur SENSOR_ID (que vous avec dans le sketch injecté sur l’Arduino)
2.2.2. Configuration des commandes des nodes
Des commandes sont créées automatiquement pour certains capteurs.
-
Relais : on/off
-
Dimmer : slider
-
Verrou : activé/désactivé
2.2.3. Création de commandes avancées
Il est possible que certains capteurs nécessitent des commandes qui ne sont pas créées automatiquement car elles ne peuvent être déduites de la présentation. Dans ce cas, on créera une commande avec le bouton ajout commande et les options nécessaires.
3. FAQ
On peut utiliser une gateway sur port USB ou réseau (voir les liens de documentation plus bas pour plus d’informations)
La gateway USB peut être utilisée sur le Jeedom principal ou un satellite
Les gateway NRF ou RFM sont supportées (attention à bien utiliser un seul des deux sur un réseau unique)
mySensors est un protocole de transmission sans fil de capteurs à base d’Arduino et de puce NRF24L01
Des exemples de capteurs sont proposés sur le site mySensors, mais les limites sont celles du catalogue de capteurs Arduino existant
Dans la section autres documentations, un lien vers le site mySensors est disponible (en anglais) et également des liens vers des noeuds en francais
Vérifier votre configuration réseau Jeedom dans Général→Administration→Configuration dans la partie Réseau
Il faut adapter le sketch de la passerelle pour qu’elle envoit cette information, ce qui n’est pas le cas dans la lib 1.4.1
La ligne à ajouter :
Pour une passerelle USB après le gw.begin…:
Serial.print("0;0;3;0;2;");Serial.print(LIBRARY_VERSION);
Pour une passerelle Réseau après le server.begin();:
server.write("0;0;3;0;2;");server.write(LIBRARY_VERSION);
Oui, le plugin répond au GET en plus des SET des noeuds. Ce qui veut dire que tout capteur d’un noeud déclaré dans Jeedom, ce noeud peut y accéder.
Il faut bien penser à décocher la case "Evènement seulement" côté Jeedom.
Il existe également une possibilité de lier un capteur d’un noeud à une information quelconque de Jeedom.
Pour cela le sensor doit être déclaré en type "Custom", un bouton de sélection d’une information Jeedom est alors disponible à côté du champ valeur.
Il faut également du côté noeud, faire un get avec le type de données VAR5 pour que le plugin comprenne qu’on vient chercher une valeur virtuelle.
- Pour résumé
-
Sensor Custom + Data VAR5 : toute information de Jeedom devient accessible au noeud (température d’un capteur Zwave, consigne virtuelle …)
4. Troubleshoting
Sur la page de configuration vous pouvez vérifier que le service du plugin est démarré et connecté.
Allez voir dans la section logs de Jeedom : catégorie mySensors et eventuellement la catégorie API
Au démarrage d’un noeud, celui-ci se présente sur le réseau, un équipement lié est alors créé avec tous ses capteurs et les commandes associées le cas échéant
Il faut que l’inclusion soit activer également
Sur la page de configuration du plugin, vous avez une note d’information qui donne le statut du service du plugin Jeedom et également le statut de connexion de celui-ci à la gateway
Vérifier votre configuration réseau dans Jeedom. Vous devez bien avoir rempli tous les champs de votre adresse interne. Protocole, adresse et complément url surtout (si vous êtes sur une intstallation Jeedom DIY, vous devez avoir /jeedom dans "complément")
Vérifier par étapes que votre passerelle est fonctionnelle. 1-est-ce qu’elle répond à un ping 2-est-ce qu’elle répond à un telnet sur son port 5003 (le port par défaut dans les sketchs de gateway réseau)
Si un de ces 2 points ne fonctionnent pas, la passerelle à un problème. Revérifiez votre montage et votre sketch (attention aux différences entres l’ENC28J60 et le W5100)
Le module serialport n’a pas réussi à être installé sur Synology (npm exactement ne peut pas être installé). Il faut soit utiliser une esclave avec une gateway série ou directement une gateway réseau.
1- télécharger le fix pour UIPEthernet : https://github.com/ntruchsess/arduino_u … rata12.zip 2- supprimer tous les fichier dans le dossier UIPEthernet (dans le dossier libraries de arduino) 3- remplacer par les fichiers du zip 4- éditer le fichier UIPEthernet\utility\uipethernet-conf.h et mettre la ligne #define UIP_CONF_UDP à 0 (sinon une fois compilé ca rentre pas sur un arduino, d’origine c’est fait dans la librairie) 5- refaire la compilation et renvoyer sur l’arduino Bingo :)
5. mySensors, informations utiles
5.1. mySensors, qu’est-ce que c’est ?
mySensors est un protocole de communication sans fil orienté domotique
On a donc un réseau de noeuds qui communique sur la fréquence du 2.4GHz entre eux et ce réseau de noeuds dispose d’une passerelle qui fait le lien entre l’informatique et les noeuds
C’est elle qui est connectée à Jeedom par ce plugin et qui transmet les informations entre les noeuds et Jeedom dans le protocole mySensors.
Chaque nœud permet de répéter le signal d’un capteur qui serait hors de portée de la gateway avec si besoin des nœuds répéteurs.
Le plugin Jeedom permet d’utiliser une gateway USB (sur un Jeedom central ou déporté) ou une network gateway réseau.
5.2. mySensors, lexique
- Gateway
-
la passerelle entre le réseau mySensors et votre réseau informatique
- Controler
-
le service côté informatique qui communique avec la gateway
- Node
-
un nœud de capteur/actionneur
- Sensor
-
un capteur sur un noeud
- Sensor Type
-
le type de capteur (relais, lumière, température …)
- Data Type
-
le type de donnée pour un capteur
- Repeater
-
un noeud répéteur de signal (mais accessoirement, peut aussi être un capteur)
- NRF24L01
-
le composant qui assure la communication sans fil entre les Arduino du réseau mySensors
- RFM69
-
un autre composant qui peut assurer la communication sans fil entre les Arduino du réseau mySensors
5.3. mySensors, le protocole
Ce chapitre n’a pas vocation a remplacer la documentation officielle mySensors. C’est juste un apercu à prendre comme un bloc-note, un rappel, un mémo …
Mais pour la documentation complète, n’oubliez pas de voir la documentation officielle du site mySensors et également pour ceux qui peuvent sur le github de mySensors, la librairie étant bien documentée
5.3.1. Construction des messages mySensors
Les messages mySensors sont visible sur la sortie série de l’arduino noeud ou bien dans les logs du plugin pour la gateway.
Exemple d’un message : 16;0;1;0;0;20,1
| Noeud | Capteur | Type de Message | Acquittement | Type de Donnée | Valeur |
|---|---|---|---|---|---|
16 |
0 |
1 |
0 |
0 |
20,1 |
N°16 |
N°0 |
Paramétrage |
Sans Ack |
Température |
20,1 |
- Noeud
-
Le noeud cible ou source du message. C’est son identifiant numérique. Va de 1 à 254 pour les noeuds. 0 et 255 sont réservés. Cet identifiant est obtenu auprès du controleur au premier démarrage, puis utiliser par toute communication avec le noeud, il est visible sur la page de l’équipement.
- Capteur
-
Le capteur du noeud auquel le message se rapporte. Les valeurs utilisables sont de 0 à 254 par noeud. C’est l’identifiant unique sur le noeud d’un capteur. C’est le noeud lors de sa présentation qui déclare ses capteurs et leurs identifiants.
- Type de Message
-
Le protocole mySensors permet 5 types de messages suivant ce qu’on veut faire : présentation (0), paramétrage (1), récupération (2), interne (3), flux (4) Voir la section plus bas sur les types de message pour une information complète.
- Acquittement
-
Est-ce que le message doit être acquitté par la destination. C’est une valeur binaire (0 pour non acquitté, 1 pour acquittement) La trame d’acquittement est automatiquement émise par la lib mySensors
- Type de Donnée
-
C’est un type qui est laissé libre par message. Généralement concordant avec le type de capteur défini. Actuellement ils vont de 0 à 36. Voir la section plus bas sur les types de donnée pour une information complète.
- Valeur
-
C’est la valeur numérique associée au type de donnée.
5.3.2. Liste des types de sensors
Voici la liste des types de capteurs avec les actions jeedom qui sont créées pour chaque (note du relecteur : à compléter)
| ID | Type mySensors | Nom de Capteur | Widget par défaut | Commandes créées sous Jeedom |
|---|
5.3.3. Liste des types de messages
| Type de Message | Valeur dans la Trame | Utilisation |
|---|---|---|
Présentation |
0 |
pendant le setup d’un noeud pour présenter son sketch, sa lib et ses capteurs |
Paramétrage |
1 |
pour changer une valeur (noeud pour transmettre sa valeur, jeedom pour activé un relais …) |
Récupération |
2 |
pour demander la valeur (thermostat venant chercher sa consigne …) |
Interne |
3 |
pour les commandes internes mySensors |
OTA |
4 |
dédié au 'On The Air' (noeud téléchargeant leur sketch via le réseau) |
Pour le type paramétrage, il est utilisé par les noeuds pour fournir un changement d’état (exemple : température qui change) mais également lorsqu’on souhaite agir sur un activateur (exemple : envoi depuis jeedom d’un "On" sur un relais)
Pour le type récupération, il peut être utilisé pour "poller" un noeud et lui demander sa valeur (si le noeud accepte ce type de demande) mais également depuis un noeud pour interroger son controleur afin d’obtenir une valeur
A noter que pour ce type de message, dans le cas d'un capteur de type "Custom" et sur un type de donnée "Virtuel" (28), Jeedom fournira la valeur de l'information virtuelle que l'on a sélectionné sur l'équipement au noeud. Cela permet de mettre à disposition d'un noeud n'importe quelle information dans Jeedom. Exemple : une consigne liée à un virtuel ou une température venant d'un capteur Zwave.
5.3.4. Liste des types de données
| ID | Type mySensors | Nom de la Donnée |
|---|
5.4. mySensors, les fonctions utiles
5.4.1. Paramétrage d’un noeud
MySensor
MySensor(uint8_t cepin = 9, uint8_t cspin = 10);
cepin - La pin connectée au 'RF24 Chip Enable' sur le module RF (par défaut 9)
cspin - La pin connectée au 'RF24 Chip Select' (par défaut 10)
5.4.2. Présentation d’un noeud
gw.begin
void begin(void (*_msgCallback)(const MyMessage &), uint8_t nodeId, boolean repeaterMode,
uint8_t parentNodeId, rf24_pa_dbm_e paLevel, uint8_t channel, rf24_datarate_e dataRate);
incomingMessageCallback - Callback function for incoming messages from other nodes or controller and request responses. Default is NULL.
nodeId - L’id unique (1-254) pour ce noeud. Par défaut en AUTO(255) ce qui veut dire que le noeud l’obtiendra du controleur.
repeaterMode - Active le mode répéteur. Ce noeud fera suivre les messages aux autres dans le réseau. S’assurer d’appeler process() régulièrement. Par défaut false
parentNodeId - A utiliser pour forcer l’utilisation d’un noeud précis en tant que relais. Par défaut en AUTO ce qui laisse au noeud le choix de trouver son parent automatiquement.
paLevel - Radio PA Level du capteur. Par défaut RF24_PA_MAX
channel - Radio channel. Par défaut 76
dataRate - Vitesse de transmission Radio. Par défaut RF24_250KBPS
gw.present
void present(uint8_t childSensorId, uint8_t sensorType, bool ack);
childSensorId - L’ID unique du capteur à créér. Entre 0-254.
sensorType - Le type du capteur à créér.
ack - Permet de demander un acquittement de la communication. Par défaut, pas d’acquittement.
5.4.3. Sauvegarde d’état des capteurs
gw.saveState
void saveState(uint8_t pos, uint8_t value);
pos - La position où l’on veut conserver la valeur (0-255)
value - La valeur à sauvegarder
gw.loadState
uint8_t loadState(uint8_t pos);
pos - La position à récupérer de l’EEPROM (0-255)
5.4.4. Envoi de messages
gw.send
bool send(MyMessage &msg, bool ack);
msg - Le message à envoyer. Voir myMessage pour plus d’informations.
ack - Permet de demander un acquittement de la communication. Par défaut, pas d’acquittement.
MyMessage(uint8_t childSensorId, uint8_t variableType);
childSensorId - Le capteur lié à ce message. 0-254.
variableType - Type de variable.
gw.sendBatteryLevel
void sendBatteryLevel(uint8_t level, bool ack);
level - Niveau de batterie 0-100(%)
ack - Permet de demander un acquittement de la communication. Par défaut, pas d’acquittement.
gw.request
void request(uint8_t childSensorId, uint8_t variableType, uint8_t destination);
childSensorId - L’ID unique du capteur. 0-254.
variableType - Le type de variable à récupérer.
destination - Le nodeId du noeud depuis lequel on veut récupérer l’info. Par défaut la gateway.
5.4.5. Réception de messages
process
boolean process();
Le traitement des messages arrivant se fait dans une fonction nommée process().
Il est possible de vérifier le message par rapport à son type de donnée, le capteur destination … et de prendre les actions nécessaires.
gw.wait
gw.wait(500);
Fonction utile lorsqu’on utilise le mode sleep et que l’on souhaite en plus recevoir des commandes du controleur.
Cela permet d’attendre 0,5s avant de passer en sleep. A mettre juste avant le sleep.
5.4.6. Sleep et réveil
A noter que la librairie mySensors propose plusieurs fonctions sleep. Une basique sans interrupt, mais une aussi avec deux interrupt pour deux IO pouvant sortir l’Arduino du sleep (exemple : détecteur de mouvement + ouverture de porte)
void sleep(unsigned long ms);
bool sleep(uint8_t interrupt, uint8_t mode, unsigned long ms=0);
int8_t sleep(uint8_t interrupt1, uint8_t mode1, uint8_t interrupt2, uint8_t mode2, unsigned long ms=0);
Le dernier paramètre est toujours la durée du sleep.
Les paramètres interrupt correspondent à un IO qui servira d’interrupt (0 = D2 et 1 = D3 sur un Mini)
Les paramètres mode prennent pour valeur : RISING, FALLING, CHANGE