Généralités

OpenSprinkler, dispositif d'arrosage Open Source, dispose d'une API (Application Programming Interface) permettant de le contrôler par exemple avec une autre application.

JSON

L'API permet avec de simple HTTP GET de questionner le dispositif, voir de le programmer. Le retour est fait en JSON (Javascript Serial Object Notation).

Lorsqu'il s'agit d'une action, on récupère un code de retour qui indique si cela s'est bien passé ou non, par exemple

{"result" :1}

Lorsqu'il s'agit d'une demande de paramètres, on obtient en retour les valeurs demandées :

{"fwv":217,"tz":56,"ntp":1,"dhcp":1,"ip1":0,"ip2":0,"ip3":0,"ip4":0,"gw1":0,"gw2":0,"gw3":0,"gw4":0,"hp0":80,"hp1":0,"hwv":30,"ext":0,"sdt":0,"mas":0,"mton":0,"mtof":0,"urs":0,"rso":0,"wl":123,"den":1,"ipas":0,"uwt":1,"ntp1":50,"ntp2":97,"ntp3":210,"ntp4":169,"lg":1,"mas2":0,"mton2":0,"mtof2":0,"fwm":2,"fpr0":100,"fpr1":0,"re":0,"dns1":8,"dns2":8,"dns3":8,"dns4":8,"sar":0,"ife":57,"reset":0,"dexp":0,"mexp":6,"hwt":172}

Cette notation, est toutefois améliorable dans sa présentation, en passant le bloc de texte retourné dans un "JSON Beautifier" (exemple https://jsonformatter.curiousconcept.com/ )

On obtient alors un bloc de texte beaucoup plus facilement compréhensible, ou l'on voit bien les varaiables et leurs valeurs :

{
   "fwv":217,
   "tz":56,
   "ntp":1,
   "dhcp":1,
   "ip1":0,
   "ip2":0,
   "ip3":0,
   "ip4":0,
   "gw1":0,
   "gw2":0,
   "gw3":0,
   "gw4":0,
   "hp0":80,
   "hp1":0,
   "hwv":30,
   "ext":0,
   "sdt":0,
   "mas":0,
   "mton":0,
   "mtof":0,
   "urs":0,
   "rso":0,!!!
    ...
}

Url d'appel

L'url d'appel se forge de la façon suivante :

http://Adresse_IP/CODE_API?pw=MOT_DE_PASSE&PARAMETRE1=Valeur1&PARAMETRE2=Valeur2 etc..

  • Adresse_IP: L'adresse IP de votre Open Sprinkler
  • Code_API : Commande à exécuter, comme documenté dans l'API OpenSprinkler. * IL s'agit d'un code de commande sur 2 lettres (ex jc = Get Controller variables)
  • MOT_DE_PASSE : Mot de passe de votre OpenSprinkler, Encodé en MD5. Pour l'encodage, vous pouvez utiliser un encodeur en ligne comme http://www.miraclesalad.com/webtools/md5.php. Ainsi le mot de passe TEST sera encodé en 033bd94b1168d7e4f0d644c3c95e35bf
  • PARAMETREx : Paramètres optionnels dépendant de la commande à exécuter.

Exemple d'appel, ici avec le mot de passe TEST encodé en MD5, pour demander les variables du contrôleur situé en 192.168.1.2:

http://192.168.1.2/jc?pw=033bd94b1168d7e4f0d644c3c95e35bf

Mise en œuvre

Tout comme dans l'article précédent sur la commande de chauffage nous allons utiliser IFTTT pour s'interfacer avec Google Home.

Il est supposé que vous avez déjà couplé IFTTT avec votre Google Home, de nombreux tutos dont disponibles sur le net sur ce sujet.

IFTTT va nous permettra d'associer une commande vocale de Google Home (écrite en langage naturel: "OK Google allume l'arrosage...") à une action personnalisée. La plupart de ces actions prévoient d'interagir avec des équipements commerciaux connectés ou des API d'applications internet (Twitter, Facebook, etc..). Fort heureusement, les concepteurs d'IFTTT ont pensé aux makers, en prévoyant une action spaciale permettant d'appeler une URL : les Wekhooks.

Pour pouvoir utiliser les "webhooks", il va nous falloir une URL d'appel intégrant la commande à exécuter et l'authentification, et que cette URL soit accessible de l'extérieur de votre domicile.

Préparation et test de l'URL

Supposons que nous ne disposions que d'un seul programme d'arrosage (le 1er), et que cela soit ce programme que vous souhaitiez démarrer ou arrêter. Les programmes étant numérotés à partir de zéro. le premier programme se nomme donc 0.

L'API 2.17 (téléchargeable ICI) nous indique au chapitre 12 qu'il va nous falloir utiliser la commande "mp" pour démarrer manuellement une station. Nous pourrons décider si nous souhaitons utiliser les prévisions météo (UWT=1) ou non (UWT=0).

L'url d'appel sera donc constituée ainsi : http://MON_IP/mp?pw=MD5_PASSWORD&pid=0&uwt=1

Pour la tester, il suffit (après l'avoir adaptée à votre IP, de la coller dans votre navigateur).

Pour l'arrêt, nous allons utiliser une autre commande de l'API, cm (manual station run) documentée au chapitre 11 de l'API. Ici les paramètres seront l'ID de la station a commander (numérotée à partir de 1), en=1 pour activer ou =0 pour désactiver, et le temps en secondes (t), qui n'est utile que pour l'activation.

Voici par exemple comment arrêter immédiatement la 2e électrovanne (sid=1) : http://MON_IP/cm?pw=MD5_PASSWORD&sid=1&en=0&t=0 . Il ne reste plus qu'à tester le bon fonctionnement du réseau local en utilisant les 2 urls ainsi générée.

Si vous désirez pousser plus loin l'intégration, il est possible d'utiliser des outils de test de web service comme Postman. Avec cet outils vous pourrez sauver les requêtes, documenter les paramètres, les faire varier, examiner le retour JSON formaté, les entêtes HTTP, etc...

Préparation du routeur

Maintenant que nos 2 urls sont prêtes à l'emploi, il va nous falloir rendre accessible OpenSprinkler de l'extérieur. Pour ce faire il va falloir programmer des règles NAT sur votre routeur. NAT? Kesako? Le NAT est la translation d'adresse et de port. Chacun des périphériques de votre réseau local possède une adresse ip et possiblement plusieurs services réseau. Chaque service réseau foncooinne sur un ou plusieurs ports, qui sont fort heureusement normalisés. Par exemple, si votre PC possède un serveur Web, celui ci occupera le port 80. Un serveur FTP utilisera le port 21, etc.. On peut voir le port comme une analogie à l'étage d'un bâtiment situé à une adresse donnée. Une adresse a plusieurs étages, mais chaque étage ne peut accueillir qu'un service. Les services fonctionnent pour la plupart d'entre eux à des numéros de port (d'étage) standard (normalisés). Par exemple le web est en 80, le web sécurisé en 443, le FTP en 21,etc...

Il est toutefois possible de faire fonctionner un service à un autre numéro de port que celui prévu, dès lors que l'on précise au client qu'il doit utiliser celui-ci. Ainsi par exemple, il est possible d'utiliser le protocole HTTP sur le port 8000 : http://mon_adresse_ip:8000/ . Ce sont les :numero_de_port qui indiquent à notre navigateur web d'utiliser un port alternatif au port par défaut.

Le problème est que votre fournisseur d'accès Internet ne vous prête qu'une seul adresse IP publique. De l'extérieur vous ne verrez donc qu'une seule adresse. Par défaut, dalleurs, tout bon routeur qui se respect bloquera tout le trafic entrant sur cette adresse. C'est ce qui protégera votre domicile (ou réseau d'entreprise) de toute accès extérieur.

La section Firewall de la configuration du routeur contient sur la plupart des routeurs modernes une fonction NAT (ou Network Address Translation) qui va nous permettre de router une demande entrante sur l'ip publique sur un port et un protocole donné, vers l'une des adresses de votre réseau local. Au passage on va même pouvoir changer le port de destination.. Comme

Ainsi, on va pouvoir faire en sorte qu'un accès externe sur le port 8000 redirige vers l'adresse IP interne de notre Opensprinkler sur le port 80.

MON_IP_PUBLIQUE:8002 > ADRESSE_OPEN_SPRINKLER:80

Ceci se fait assez simplement dans la fonction qui gère le NAT sur votre routeur. Sur Freebox OS, c'est la rubrique PORT qui est chargée de ceci.

Voici une copie d'écran de l'ajout d'une règle. L'IP de destination est celle de votre openSprinkler sur le réseau local, le Port de début, le numéro de port qui le rendra accessible de l'extérieur, et le port de destination le port de votre opensprinkler (80 pour HTTP). nat2.jpg

La règle sera ensuite matérialisée dans le tableau de synthèse comme suit : nat1.jpg

Il ne vous reste plus qu'à tester l'accès sur l'IP publique de votre connexion sur le port que vous avez choisi (http://mon_ip_publique:8002) et vérifier que vous joignez bien OpenSprinkler avec les 2 URLS que nous avons forgées précédemment.

Astuces :

  • Utilisez l'assignation d'IP fixes sur le DHCP pour avoir toujours la même adresse LAN sur votre Open Sprinkler. Ainsi vous serez sur que vos règles NAT ne seront pas perturbées, car lors d'une inactivité trop longue vote OpenSprinkler risque de changer d'adresse IP LAN.
  • Si vous ne connaissez pas votre ip publique vous pouvez utiliser http://www.mon-ip.com/ pour la connaitre.
  • Attention, le NAT constitue une faille de sécurité. Il faut donc que le périphérique soit sur, qu'il utilise une authentification et idéalement un chiffrement SSL (ce n'est pas le cas pour OpenSprinkler sur ce dernier point).
  • Enfin, lors de tests, soyez conscients que tous les routeurs ne permettent pas l'accès sur lIP publique du LAN. Faites donc vos tests avec un téléphone mobile en 3G :)
Association à IFTTT

Il ne vous reste plus qu'à céer une nouvelle applet sur ifttt.com :

  • +THIS
  • Choisir Google Assistant
  • Say a simple phrase
  • Phase: "Allume arrosage"
  • Language : French
  • Create Trigger
  • +THAT
  • Webhoock
  • Make a web request
  • URL : L'url d'allumage précédemmebn forgée (avec l'ip publique...)
  • Method : Get
  • Content type : Application JSON
  • Body ; rien
  • Create action

Et voila. I lne vous reste plus qu'à répéter l'opération pour créer une deuxième action pour couper l'arrosage....