protocole_j2k.md

-# Protocole de cummunication entre RCowat et J2K
+[[_TOC_]]
+
+# Protocole de communication pour manipuler un modèle J2K
+
+Le module de communication `CouplingCommunication` doit être placé en début de boucle temporelle (TimeLoop). Une fois que le modèle J2K est lancé, ce module va interrompre l'exécution à chaque début de boucle temporelle et attendre qu'on lui envoie des commandes.
+
+La communication se fait par requêtes HTTP POST. Chaque requête contient une commande, comme un ordre donné au module de communication. On peut effectuer ces requêtes par le moyen de son choix. Le moyen le plus simple est d'utiliser l'outil CURL. On peut aussi effectuer ces requêtes avec tous les langages de programmation modernes (Python, C, C++, Java, R, Ruby etc...).
+
+Les exemples suivants partent du principe que les ordres sont données à partir de la machine qui fait aussi tourner le modèle. C'est pourquoi on donne `localhost` comme adresse de destination. On peut tout aussi bien communiquer avec une autre machine si on connait son adresse IP ou son nom de domaine.
 
 ## Avec CURL
 
+Voici un exemple de requête effectuée avec CURL :
+
 ``` bash
-curl http://localhost:9999 -X POST -d '{"foo": "bar"}' # any unrecognized json stuff : the model does one time loop
-curl http://localhost:9999 -X POST -d '{"command": "step", "nbStep": 10}' # tell the model to loop N times the time loop
-curl http://localhost:9999 -X POST -d '{"command": "stop"}' # stop the model, stop listening for commands
-curl http://localhost:9999 -X POST -d '{"command": "free"}' # free the model to run until the end, stop listening for commands
-curl http://localhost:9999 -X POST -d '{"command": "info"}' # return model state
-curl http://localhost:9999 -X POST -d '{"command": "set", "key": "infiltration", "value": {"939": 10000} }'
-curl http://localhost:9999 -X POST -d '{"command": "get", "key": "hru"}' # get state of all HRUs
-curl http://localhost:9999 -X POST -d '{"command": "get", "key": "reach"}' # get state of all reachs
+curl http://localhost:9999 -X POST -d '{"command": "step", "nbStep": 10}'
 ```
+Elle se décompose en plusieurs parties :
+* `http://localhost:9999` : c'est l'adresse et le port de destination, c'est une adresse HTTP car c'est le protocole que nous utilisons
+* `-X POST` : on indique qu'on veut utiliser la méthode POST pour envoyer des informations dans la requête
+* `-d '{"command": "step", "nbStep": 10}'` : on donne le corps de la requête avec l'option `-d`. Ce corps est une chaine de caractère qui doit contenir un objet JSON. Un tel objet est en fait un dictionnaire associant des clés et des valeurs. Dans cet exemple, la clé "command" a la valeur "step" et la clé "nbStep" a la valeur 10. On indique ainsi qu'on veut que le modèle fasse 10 pas de temps.
+
+## En R
+
+C'est le même protocole mais on envoie les requêtes HTTP différemment. On peut utiliser le module Rj2k.R qui contient des fonctions qui acceptent des dataframes en entrée et renvoient des dataframes en sortie.
+
+# Commandes
+
+Voici la liste des commandes disponibles :
+
+* `{"command": "step", "nbStep": 10}` : dire au modèle de faire 10 pas de temps
+* `{"command": "stop"}` :stopper le modèle et fermer JAMS
+* `{"command": "free"}` : libérer le modèle pour qu'il s'exécute jusqu'à la fin sans interruption
+* `{"command": "info"}` : demander des information sur l'état du modèle
+* `{"command": "set", "key": "infiltration", "value": {"939": 10000} }` : définir les valeurs d'un attribut pour un ensemble d'HRU. La clé "value" doit contenir un dictionnaire indexé par les identifiants des HRU et contenant les valeurs de l'attribut.
+* `{"command": "getHru", "key": "actRD1"}` get actRD1 of all HRUs
+* `{"command": "getReach", "key": "Runoff"}` get Runoff of all reachs
+
+## La commande set
+
+### Modules spécifiques
+
+La commande `set` est particulière. Elle permet de s'adresser directement aux modules spécialisés s'ils ont été placés dans le modèle.
+
+* infiltration (ajoute de l'infiltration des canaux dans les HRUs)
+* aspersion (ajoute de l'irrigation d'aspersion)
+* drip (ajoute de l'irrigation en goutte à goutte)
+* surface (ajoute de l'irrigation de surface)
+* reachin (rejets dans les reachs)
+* reachout (prélèvements dans les reachs)
+
+Exemple, on veut prélever 10000 litres dans le reach 333 et 5000 litres dans le reach 444:
+
+`{"command": "set", "key": "reachout", "value": {"333": 10000, "444": 5000} }`
 
-Valid keys for "set" command:
-* infiltration (per HRU)
-* aspersion (per HRU)
-* drip (per HRU)
-* surface (per HRU)
-* reachin (per reach)
-* reachout (per reach)
+### Modules génériques
 
-# En R
+La commande `set` permet aussi de s'adresser aux modules génériques de modification d'un attribut. Par exemple, si on place un module générique (CouplingReachVariableChanger ou CouplingHruVariableChanger) dont l'attribut `moduleName` vaut "modifHruAttributPrecip" et qu'on l'a lié à l'attribut "precip" dans JAMS, on peut donner des valeurs de cette manière :
 
-C'est le même protocole mais on envoie les requêtes HTTP différemment.
\ No newline at end of file
+`{"command": "set", "key": "modifHruAttributPrecip", "value": {"1": 55, "2": 56} }`