Projet réalisé par Théo DELOOSE, Clara BOMY, Clément NOUGÉ, Mathieu GABRIEL, Marine DAEL et Thaï-Son DANG.

Introduction

Nous sommes six étudiants en troisième année à l’ISEN Lille. Dans le cadre de notre projet de fin d’année, nous avons conçu une serre connectée dédiée à un usage en intérieur. Celle-ci est équipée d’un système d’éclairage intelligent, d’une pompe d’arrosage automatique et d’un brumisateur intégré afin de garantir la bonne croissance des plantes, rassemblant les conditions nécessaires à leur développement. Pour une plus grande facilité d’utilisation, notre serre est associée à une application mobile simple et ludique permettant de suivre en temps réel les données de l’environnement de la serre et de contrôler celle-ci à distance.

En réalisant ce projet, notre but était de proposer une solution de serre connectée à un prix raisonnable et possédant une interface attrayante pour améliorer l’expérience de l’utilisateur.

De plus nous voulions que la serre puisse être intégrée dans différents systèmes facilement pour que l’utilisateur puisse utiliser les données à sa guise.

Fonctionnement général

Nous avons pensé FriendLeaf comme un système de monitoring et de pilotage. Il propose en effet de gérer automatiquement l’arrosage, l’humidité et la luminosité de la serre, ou bien de les activer manuellement à notre guise. Il synchronise les données récupérées par les différents capteurs grâce à la plateforme Constellation et active, par le biais d’un relais, les actionneurs. Enfin, FriendLeaf alerte l’utilisateur lorsque le réservoir d’eau est vide. Tout est synchronisé en temps réel comme par magie grâce à Constellation.

Nous avons donc ajouté dans la serre les capteurs permettant de relever les informations sur l’humidité de l’air et du sol, sur la température et sur la luminosité.  L’équipement installé comporte aussi une guirlande lumineuse ayant pour but d’éclairer et d’afficher les alertes, une pompe pour le système d’arrosage et un brumisateur permettant d’humidifier l’air.

Matériel utilisé

Pour réaliser notre projet, nous nous sommes servis des composants suivants :

Pour la Serre :

• Serre SOCKER Ikea (12,99€), Ikea
• Bac pour le terreau (1,50€), Jardinerie
• Carte Raspberry Pi 3B (40,80€), Amazon
• Relais 4 canaux supportant jusqu’à 5A et 250V (AC) et 30V (DC) (9,99€), Amazon
• Câbles de connexion
• Boîte de dérivation

Pour les capteurs :

• Humidité et température air : DHT11 (1,31€), Amazon
• Luminosité : TSL2561 (6,95€), Gotronic
• Humidité sol : GT110 (2,40€), Gotronic
• Niveau d’eau : Gravity SEN0205 (10,50€), Gotronic

Pour le brumisateur :

• Un émetteur à ultrasons (9,89€), Amazon
• Une alimentation pour le brumisateur (24V DC, 1A) (25€), Derotronic, Lille
• Un bol

Pour le système d’arrosage :

• Une pompe à eau (5,48€), Amazon
• Une alimentation 12V 600mA (12€), Derotronic, Lille
• Un jerrican (environ 10€)
• Un tuyau (ø7mm -ø10mm), Diall

Pour l’éclairage :

• 2m de guirlandes lumineuses (1m LED et 1m incandescent), Blachère
• Une alimentation pour fil lumière, Blachère
• Colliers de serrage

Conception de la serre

Étape 1 : Préparation de la serre

Dans la serre, nous avons disposé les capteurs, le pot et un bol pour le brumisateur. Nous avons également percé des trous pour pouvoir faire passer tous les capteurs et le tuyau d’arrosage.

Pour ce qui est de la guirlande lumineuse, il nous a fallu percer quelques trous supplémentaires dans les montants de la serre pour y glisser les colliers de serrage.

Étape 2 : Branchement du relais

Afin de pouvoir contrôler les actionneurs, nous avons branché le relais quatre canaux à une carte Raspberry Pi.

Celui-ci est analogue à un interrupteur. Pour chaque canal, une alimentation est nécessaire et chacun d’entre eux peut être piloté individuellement grâces aux différents pins dont dispose le relais. Il faut également prévoir une masse que l’on branche sur le pin “Gnd” du relais.

Par défaut, lorsque les pins d’entrée ne sont pas alimentés, les canaux du relais délivrent la tension d’alimentation correspondante sur la sortie NC (“Normally Closed”) ou sur la sortie NO (“Normally Open”) dans le cas contraire.

Etape 3 : Éclairage de la serre

Pour l’éclairage de notre serre, nous avons percé des trous dans la structure et fixé la guirlande avec des colliers de serrage. Celle-ci doit être alimentée par une tension de 230V (tension secteur) et est composée d’un mètre de LEDs rouge et d’un mètre incandescent jaune.

Elle est connectée au relais par la phase et le neutre, chacun branchés sur un canal différent, afin d’isoler totalement la guirlande du secteur et ainsi éviter tout problème avec le reste des composants.

Etape 4 : Installation du brumisateur

Pour augmenter l’humidité de l’air dans la serre, nous avons installé un brumisateur fonctionnant par émissions d’ultrasons. Il nécessite une alimentation de 24V/1A maximum. On le relie ensuite au relais. La masse est directement connectée à l’adaptateur secteur par le biais d’un domino.

Etape 5 : Installation du système d’arrosage

En ce qui concerne l’arrosage, nous disposons d’une pompe submersible qui nécessite une alimentation de 12V et 400mA. Elle est branchée en sortie à un tuyau percé pour un arrosage homogène. Nous la connectons ensuite à un des canaux du relais.

Pour le réservoir, nous avons récupéré un bidon de vinaigre de 5L sur lequel nous avons fait un trou pour le capteur de niveau d’eau et une ouverture pour le remplir et y faire passer la pompe.

Pour résumer…

Étape 6 : Mise en place des capteurs et paramétrage de la carte Arduino

Nous installons à présent les capteurs d’humidité/température de l’air, d’humidité du sol, de de luminosité et de niveau d’eau. Nous branchons tous ces capteurs aux pins de la Raspberry ou de l’Arduino en faisant attention au fait que :

• Les capteurs d’humidité du sol et de niveau d’eau se branchent sur du 5V.
• Les capteurs d’humidité/température de l’air et de luminosité sont alimentés en 3,3V.

Étape 6.1 : Capteur d’humidité et de température de l’air

Le capteur d’humidité et de température de l’air fournissant des données numériques, nous le relions directement à notre Raspberry Pi comme montré sur le schéma ci-dessous :

Étape 6.2 : Capteurs de luminosité, d’humidité du sol et de niveau d’eau

Ces capteurs fournissant des données analogiques, nous les avons branchés à une carte Arduino nano qui permet de lire ces données, contrairement à la Raspberry. Elle est reliée directement par USB à la Raspberry Pi comme montré ci-après :

Étape 6.3 : Programmation de la carte Arduino

Dans l’IDE Arduino, nous avons donc commencé par programmer la carte.

Nous ajoutons tout d’abord les librairies d’Adafruit pour pouvoir initialiser le capteur de luminosité et régler le temps d’intégration des données. Dans le gestionnaire de bibliothèque (menu Croquis > Inclure une bibliothèque), nous avons installé les librairies suivantes :

• Adafruit Unified Sensor
• Adafruit TSL2561

Au démarrage, dans la méthode “setup()”, nous configurons les pins utilisés. Nous décidons d’utiliser les pins analogiques A0 et A1, respectivement pour le capteur d’humidité du sol et du niveau d’eau et les pins A4 et A5 pour le capteur de luminosité :

void setup(void) 
{
  Serial.begin(9600);
 
  /*Réglage du capteur de luminosité*/
  if(!tsl.begin()) //Initialisation du capteur
  {
    //S'il y a un problème pour détecter le capteur, vérifier votre connexion
    Serial.print("Ooops, pas de capteur détecté... Vérifier votre connexion!");
    while(1);
  }
  
    //Configuration du gain du capteur et du temps d'intégration
    tsl.enableAutoRange(true);          
    tsl.setIntegrationTime(TSL2561_INTEGRATIONTIME_13MS);    
 
}

Dans la méthode “loop()”, nous recueillons ensuite les valeurs des capteurs et les faisons afficher sur le Monitor Série en utilisant les commandes analogRead() et Serial.print()  :

void loop(void) 
{  
  /*Pour recevoir une nouvelle donnée par le capteur de luminosité*/ 
  sensors_event_t event;
  tsl.getEvent(&event);
 
  //Lecture des pins analogiques pour les données des capteurs d'humidité du sol et de niveau d'eau
  Hum_value = analogRead(A0);
  Liquid_value=analogRead(A1);
 
  //Affichage des valeurs sur le Moniteur série
  Serial.print(event.light,0);
  Serial.print(',');
  Serial.print(map(Hum_value,0,1024,0,100)); //Le capteur d'humidité renvoie une valeur en pourcentage 
  Serial.print(',');
  Serial.println(map(Liquid_value,0,512,0,1)); //Le capteur de niveau d'eau retourne la valeur 1 quand il est en contact avec l'eau, 0 sinon
  delay(5000); //Retard de 5s pour éviter de surcharger le buffer de la Raspberry 
}

Nous récupèrerons ensuite les données des différents capteurs à l’aide de la carte Raspberry Pi.

La programmation vers Constellation

La programmation vers Constellation est divisée en deux packages : le premier correspond à la récupération des données des capteurs et à l’activation des actionneurs, le second a été créé pour gérer le stockage des données en vue de créer des graphiques sur notre application.

Etape 1 : Package relatif aux capteurs et actionneurs

Etape 1.1 : Acquisition des données des capteurs

Pour récupérer les données des différents capteurs cités précédemment, nous avons utilisé la librairie “Adafruit_DHT” pour Raspberry Pi et la librairie “serial” qui permet de faire le lien entre l’Arduino-Nano et la Raspberry Pi. Ces valeurs vont nous permettre de décider s’il faut activer ou non les actionneurs tels que la pompe, le brumisateur ou les LED.

La fonction ci-après permet de récupérer les valeurs des différents capteurs.

def getCapteur():
    humiditeAir, temperature = Adafruit_DHT.read_retry(11,4)
    lux, humiditeSol, eau = ser.readline()[:-2].split(",")

Nous avons ensuite créé un State Object rassemblant les valeurs d’humidité du sol, d’humidité de l’air, de température et de luminosité ambiante pour pouvoir les publier sur notre Constellation.

Constellation.PushStateObject("Capteurs", {"HumiditeSol": int(self.humiditeSol), "HumiditeAir": int(self.humiditeAir), "Temperature": int(self.temperature), "Luminosite": int(self.lux)}, "CapteursInfos")

Etape 1.2 : Activation et désactivation des différents actionneurs (brumisateur, guirlande lumineuse et pompe à eau)

Comme mentionné précédemment, les actionneurs sont reliés à la Raspberry Pi via un relais quatre canaux. Cela simplifie grandement la programmation : il nous suffit simplement de gérer l’ouverture et la fermeture des relais.

Nous avons donc fait en sorte que chaque actionneur soit associé à son relais grâce à la librairie GPIO de la Raspberry Pi. Ainsi, le code diffère seulement au niveau des numéros des pins utilisés par les actionneurs.

Voici un exemple du code de l’activation et de la désactivation de notre pompe :

GPIO.setmode(GPIO.BOARD)
GPIO.setup(12,GPIO.OUT)
GPIO.output(12,0)

Le pin 12 de la Raspberry est celui relié au relais contrôlant la pompe.

Etape 1.3 : Automatisation des actionneurs

Pour réaliser la fonction d’automatisation, nous nous sommes tout d’abord renseignés sur les conditions propices à la bonne croissance des plantes au niveau de l’humidité du sol et de l’air, de la luminosité et de la température de l’air.

Pour le brumisateur, nous avons choisi de l’activer si l’humidité est inférieure à 35% et de le désactiver si l’humidité remonte au dessus de 37%.

if humiditeAir > 37 and brumisateur:
    DesactiverBrumisateur()
elif humiditeAir < 35 and not brumisateur:
    ActiverBrumisateur()
    time.sleep(1)

Pour la pompe, le fonctionnement est différent. Puisque la diffusion de l’eau dans la terre est plus lente, nous activons la pompe pendant 5s avant de la désactiver pendant 30s pour laisser le temps au capteur de ressentir les changements.

if humiditeSol < 30 and not pompe:
    if self.ticks == 0:
            if self.next_water == 0:
                    ActiverPompe()
            self.next_water = 15
        else:
                    self.next_water -= 1
        elif humiditeSol > 30:
                    self.next_water = 0
    elif pompe:
            self.ticks += 1
               if self.ticks >= 3:
                    DesactiverPompe()
                       self.ticks = 0
time.sleep(1)

Ces différentes fonctions sont exécutées dans des threads séparés pour ne pas que le code soit bloquant.

Maintenant, il ne reste plus qu’à sécuriser notre système d’arrosage via le capteur de niveau d’eau. Connecté à la carte Arduino nano, ce capteur va nous renvoyer 1 s’il y a de l’eau dans le réservoir, 0 sinon.

Les données du capteur de niveau d’eau nous permettent d’arrêter le système d’arrosage lorsque le réservoir est presque vide et d’informer l’utilisateur via un PushBullet et l’allumage des LEDs qu’il faut remplir le réservoir.

Constellation.SendMessage("PushBullet", "PushNote", [ "FriendLead", "Le reservoir d'eau est vide"], Constellation.MessageScope.package)

Étape 2 : Package relatif au stockage des données

Afin d’historiser les valeurs des capteurs stockées dans un des State Objects du premier package, nous en avons créé un autre que l’on a déployé sur le même serveur que Constellation.

Ce package génère une base de données dans un fichier .csv qui est mis à jour toutes les minutes avec les nouvelles données.

Chaque ligne contient la date, l’heure, l’humidité du sol, l’humidité de l’air, la température et la luminosité.

@Constellation.StateObjectLink(package = "FriendLeafCapteurs", name = "Capteurs")
def RecupValue(stateObject):
    humiditeSol = stateObject.Value.HumiditeSol
    humiditeAir = stateObject.Value.HumiditeAir
    temperature = stateObject.Value.Temperature

Nous avons ensuite créé un message callback qui permet de visualiser le fichier CSV dans notre Constellation.

@Constellation.MessageCallback()
def LireBDD():
'''
: return string : La base de données 
'''
    file = open('BDD.csv','r')
    lines = file.readlines()
    return lines

L’interface utilisateur : l’application mobile de monitoring et de pilotage de la serre

Étape 1 : Le noyau de l’application

Pour développer l’application mobile nous nous sommes aidés de Cordova, un Framework permettant de créer des application Android et iOS avec des technologies web.

Nous avons également utilisé jQuery et AngularJS pour faciliter l’interaction entre Javascript et HTML.

De plus, pour gérer certaines fonctionnalités comme le traitement du CSV ou l’affichage des graphiques, nous avons utilisé des librairies externes comme PapaParser et Chartist. Finalement, pour embellir le CSS, nous avons utilisé le Framework SemanticUI qui ressemble en certain points à Bootstrap.

Étape 2 : Connexion à Constellation, State Object et Messages Callback

Pour nous connecter à Constellation avec AngularJS, nous avons utilisé ces lignes de codes :

Constellation.initializeClient(url_port, sha, "FriendLeaf");

Constellation.onConnectionStateChanged(function (change) {
   //suite
});

et une ligne de ce type pour chaque State Object :

Constellation.registerStateObjectLink("*", "FriendLeafCapteurs", "Actionneurs", "*", function (so) {
    //suite
});

Quant aux messages Callback, ils sont envoyés comme suit :

Constellation.sendMessage({ Scope: 'Package', Args: ['FriendLeafCapteurs'] }, 'DesactiverBrumisateur');

Pour que l’application soit utilisable sur n’importe quelle Constellation, nous avons créé un page de configuration où l’utilisateur rentre l’adresse de sa constellation, le port, et des identifiants.

Une fois tout cela rempli, le nom d’utilisateur et le mot de passe sont hachés en SHA1 grâce à une librairie externe et la connexion à Constellation commence.

Lorsque l’application se lance pour la première fois, l’utilisateur est directement redirigé vers cette page pour entrer les informations nécessaires.

Étape 3 : Affichage des données en temps réel

Pour l’affichage des données en temps réel nous avons utilisé des images SVG car elles sont très flexibles et nous voulions réaliser des barres de progression en arc de cercle. Pour les valeurs numériques on affiche un scope AngularJS dans lequel sont stockés les valeurs des capteurs.

Le code JS :

//Stockage des valeurs des capteurs dans la variable capteur
scope.capteurs["humiditeAir"] = so.Value.HumiditeAir;
scope.$apply(); //Applications des modifications du scope

//Pour changer le remplissage de la jauge 
$("#h_air_gauge").css("stroke-dasharray",(so.Value.HumiditeAir*18)/100 + " 18 0");

SVG en HTML :

<svg viewbox="0 0.5 10 8">
    <defs>
    <linearGradient id="linear" x1="0%" y1="0%" x2="100%" y2="0%">
        <stop offset="0%" stop-color="#00ee4f"/>
        <stop offset="66%" stop-color="#eeae00"/>
        <stop offset="100%" stop-color="#ee0000"/>
    </linearGradient>
    </defs>
    <text x="50%" y="50%" id="h_air_value" text-anchor="middle"  alignment-baseline="middle" fill="#00ee4f">
        {{Math.round(capteurs["humiditeAir"])}}%
    </text>
    <path d="M2 8 A 4 4 0 1 1 8 8" fill="none" stroke-width="0.78" stroke="#E8F6FD" />
    <path class="loader" id="h_air_gauge" d="M2 8 A 4 4 0 1 1 8 8" fill="none" stroke-width="0.8" 
stroke="url(#linear)" />
</svg>

Étape 4 : Contrôler sa serre

Nous avons également prévu dans l’application de pouvoir gérer les différents actionneurs de la serre.

Pour gérer le côté automatique du package responsable des capteurs nous avons utilisés des sliders qui lorsqu’activés, vont envoyer un Message Callback comme décrit ci-dessus. On va également suivre l’évolution du State Object indiquant si l’automatisation est activée pour tel ou tel actionneur et ainsi bloqué ou non le bouton d’activation manuel. Car oui, il est également possible d’activer manuellement chaque actionneur grâce à un bouton.

Étape 5 : Les graphiques

Pour ce qui est des graphiques nous avons utilisé une librairie externe que nous avons modifié pour la rendre compatible sur mobile. Cette librairie s’appelle Chartist. Grâce à elle nous avons pu faire de superbes graphiques.

Conclusion

Voilà qui conclut les grandes étapes de la réalisation de FriendLeaf. Comme vous avez pu le voir, la serre remplit complètement son rôle. C’est un projet ludique, simple à réaliser et facilement transposable sur d’autres installations grâce aux State Objects et aux messages Callback. C’est également un bon point de départ pour prendre en main la plateforme Constellation. Nous espérons vraiment qu’il vous a plu et que vous allez réaliser votre propre serre.

Nous tenons également à remercier Léa, le jardin de Théo et les parents de Marine qui nous ont fourni quelques accessoires nécessaires à la serre.

The post FriendLeaf : la serre connectée grâce à Constellation appeared first on Constellation.

Cette nouvelle version amène beaucoup de nouveautés que je vous propose de découvrir dans cet article. La librairie a été testé avec succès sur différentes cartes animées par un ESP8266 (ESP-01, 05, 07 et D1 Mini) ainsi qu’un Arduino/Genuino MKR1000.

Pour la mise à jour, téléchargez la libraire ci-dessous et dézippez les fichiers dans le dossier “Constellation” dans votre répertoire de libraire Arduino.

Attention : cette version 2.x de la librairie Constellation pour Arduino/ESP nécessite la version 1.8.1.16249 ou plus récente du serveur Constellation pour fonctionner correctement. Pour mettre à jour votre plateforme Constellation, lancez le Web Platform Installer.

Réception de message et StateObject “asynchrone”

Il s’agit d’une grosse évolution par rapport à la version 1.x. Pour “récupérer” du serveur Constellation les messages à destination de votre package virtuel ou les StateObjects pour lequel votre package (virtuel) s’est abonné, il faut invoquer les actions “GetMessages” et “GetStateObjects” sur l’interface REST.

Ces méthodes supportent le “long-polling” c’est à dire qu’elles mettent en attente la requête tant qu’il n’y a pas de messages ou StateObjects à retourner avec la notion de timeout (par défaut 60 secondes).

Le problème sur les versions 1.x de la libraire Arduino est que le client HTTP est “synchrone”, c’est à dire qu’il envoi la requête HTTP et attend la réponse du serveur pour traitement ce qui est incompatible avec du long-polling car cela bloquerait le code de l’Arduino. De ce fait, les anciennes versions spécifiées le “timeout” de ces requêtes à 1 seconde.

Ainsi jusqu’à maintenant, l’interrogation des messages et SO pouvaient bloquer jusqu’à 2 secondes votre Arduino (1 seconde pour le GetMessage et 1 seconde pour le GetStateObject) et engendrait donc 1 requêtes HTTP toutes les secondes entre votre ESP/Arduino et le serveur Constellation.

Dans cette nouvelle version, la librairie utilisent 3 clients HTTP différents : un pour toutes les requêtes synchrones, un pour la réception de message (GetMessage) et un pour la réception des StateObjects (GetStateObjects).

Le client synchrone est donc toujours disponible et il n’y a aucun blocage, aucune attente pour la réception de message et de SO. De plus il n’y a plus besoin de “poller” ou “flooder” le serveur d’une requête toute les secondes, en réactivant le long-polling le 2ème et 3ème client HTTP, on lance une requête toutes les minutes (60 sec par défaut) dans l’attente de message et SO.

De ce fait, il y a quelques modifications à apporter dans votre code !

Premièrement, vous ne devez plus passer la référence de votre client réseau mais plutôt spécifier le type de votre client dans le template de la classe Constellation. Par exemple, si vous utilisez un ESP8266 ou un Arduino MKR1000, vous utiliserez la classe “WifiClient “” :

/* Create the Constellation client */
Constellation<WiFiClient> constellation("constellation.monserveur.com", 8088, "MyVirtualSentine", "MyPackage", "MyAccessKey123!");

Ensuite, il n’y a plus besoin d’invoquer la méthode “poll” dans votre boucle principale avec un timer, vous devez tout simplement appeler la méthode “loop” autant de fois que vous voulez :

void loop(void) {
  // Process incoming message & StateObject updates
  constellation.loop();
}

Cette méthode vérifie en fait si il y a eu une réponse sur le client utilisé pour la réception de message et sur le client pour la réception de SO afin de les dispatcher dans votre code.

Support du PackageDescriptor

Autre nouveauté majeure pour cette version 2, le support du “Package Descriptor”.

Pour rappel le “Package Descriptor” est un objet envoyé par un package au serveur pour décrire ses StateObjects et ses MessageCallbacks exposés par le package.

Le MessageCallback Explorer de la Console Constellation s’appuie sur le “Package Descriptor” de chaque package pour lister chaque MessageCallback avec un formulaire de test. Sans cette description cela serait impossible !

Les versions 1.x ne supportaient pas “Package Descriptor”, de ce fait il n’était pas possible d’explorer/découvrir les MessageCallbacks d’un package Arduino/ESP. Vous devez nécessairement connaitre par vous même les MC exposés par le package et le type des StateObjects qu’il pouvait publier.

Avec la version 2.0, l’Arduino/ESP envoie au serveur la description des MC exposés et des types utilisés par les SO et arguments des MC.

Dans la suite de cet article, vous découvrirez comment ajouter des types dans la description de votre package, mais n’oubliez jamais d’envoyer votre “Package Descriptor” en invoquant la méthode “declarePackageDescriptor”, typiquement une fois votre code Arduino initialisé (par exemple à la fin de la méthode setup()) :

// Declare the package descriptor
constellation.declarePackageDescriptor();

Amélioration du PushStateObject

La méthode “PushStateObject” permet de publier un StateObject sur le serveur Constellation.

Tout d’abord la méthode expose des surcharges vous permettant de spécifier comme “value” de votre SO des int, uint, double, float, long et bool et supporte en paramètre optionnel le “lifetime”, c’st à dire la durée en seconde de “vie” de votre StateObject avant d’être considéré comme expiré.

// Dummy data
uint16_t lux = 123;

// Push a simple type on Constellation 
constellation.pushStateObject("DemoLux", lux);  

// Push a simple type on Constellation with lifetime of 20 seconds
constellation.pushStateObject("DemoLux", lux, 20);

Vous pouvez toujours publier des StateObjects dont la valeur (value) est un objet complexe (formaté en JSON).

Le JSON peut être formaté sous forme d’une chaine de caractère avec la méthode “stringFormat” :

// Push a complex object on Constellation with stringFormat
constellation.pushStateObject("DemoLux", stringFormat("{ 'Lux':%d, 'Broadband':%d, 'IR':%d }", lux, full, ir));

Vous pouvez également définir votre propre type pour ce StateObject, par exemple nommons cet objet “MyLuxData” :

constellation.pushStateObject("DemoLux", stringFormat("{ 'Lux':%d, 'Broadband':%d, 'IR':%d }", lux, full, ir), "MyLuxData");

Sans oublier d’ajouter ce type “personnalisé” dans le “package descriptor”. Par exemple, dans le “setup()” et avant de faire un “declarePackageDescriptor”, on aurait décrit “MyLuxData” de la façon suivante :

constellation.addStateObjectType("MyLuxData", TypeDescriptor().setDescription("MyLuxData demo").addProperty("Broadband", "System.Int32").addProperty("IR", "System.Int32").addProperty("Lux", "System.Int32"));

Pour finir, vous pouvez toujours publier un StateObject en construisant la valeur dans un objet JsonObject de façon suivante :

// Push a complex object on Constellation with JsonObject
const int BUFFER_SIZE = JSON_OBJECT_SIZE(5);
StaticJsonBuffer<BUFFER_SIZE> jsonBuffer;
JsonObject& myStateObject = jsonBuffer.createObject();
myStateObject["Lux"] = lux;
myStateObject["Broadband"] = full;
myStateObject["IR"] = ir;
constellation.pushStateObject("DemoLux", myStateObject);

Dans les surcharges de cette méthode, vous pouvez également spécifier le type de votre StateObject et/ou sa durée de vie :

constellation.pushStateObject("DemoLux", myStateObject, "MyLuxData", 20);

Pour finir, nouveauté de la librairie 2.0, vous pouvez également spécifier des “meta-données” à vos StateObjects. Par exemple :

// Ajout de metadatas au StateObject
JsonObject& metadatas = jsonBuffer.createObject();
metadatas["ChipId"] = ESP.getChipId();
metadatas["Timestamp"] = millis();
constellation.pushStateObject("DemoLux", myStateObject, "MyStateObject", 20, &metadatas);

Les StateObjectLinks

En version 1.x de la librairie Arduino, vous pouvez :

• interroger des StateObjects de la Constellation en invoquant la méthode “requestStateObjects” qui vous retourne les StateObjects à l’instant T correspondant à votre requête :

// Example : print the all SO's value named "/intelcpu/0/load/0" and produced by the "HWMonitor" package (on all sentinels)
JsonArray& cpus = constellation.requestStateObjects("*", "HWMonitor", "/intelcpu/0/load/0");
for(int i=0; i < cpus.size(); i++) { 
  constellation.writeInfo("CPU on %s is currently %d %", cpus[i]["SentinelName"].asString(), cpus[i]["Value"]["Value"].as<float>());
}

• vous abonnez aux mises à jour des StateObjects pour être notifié en temps réel des que les SO changent :

// set a StateObject update callback and subscribe to SO
constellation.setStateObjectUpdateCallback([] (JsonObject& so) {
constellation.writeInfo("StateObject updated ! StateObject name = %s", so["Name"].asString()); 
});
// Subscribe to SO named "/intelcpu/0/load/0" and produced by the "HWMonitor" package (on all sentinels)
constellation.subscribeToStateObjects("*", "HWMonitor", "/intelcpu/0/load/0");

Vous pouvez invoquer plusieurs fois la méthode “subscribeToStateObjects” pour ajouter des abonnements à d’autre StateObjects mais il n’y a qu’un seul callback de réception des SO (défini par la méthode setStateObjectUpdateCallback). C’est à vous de “dispatcher” les SO reçus.

La nouveauté en 2.0 vient de l’ajout de la méthode “registerStateObjectLink” qui vous permet d’associer un callback à un abonnement laissant ainsi à la librairie la charge du “dispatch”.

Par exemple, on peut désormais écrire :

constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", [](JsonObject& so) {
  constellation.writeInfo("CPU on %s is currently %d %", so["SentinelName"].asString(), so["Value"]["Value"].as<float>());
});

Ici on enregistre un “StateObject Link” sur tous les SO nommés « /intelcpu/0/load/0 » produits par le package “HWMonitor” de toutes les sentinelles de votre Constellation. Dès qu’un de ces StateObjects changent on exécutera le callback associé, qui ici écrit dans le log un message indiquant la nouvelle valeur du CPU.

Vous bien entendu enregistrer autant de StateObjectLink que vous souhaitez.

Enregistrement des MessageCallbacks

Le principe est le même que celui décrit ci-dessus pour les abonnements aux StateObjects.

En version 1.x, on devait définir un callback pour réception de message et invoquer la méthode “subscribeToMessage” :

// Set callback for all incoming messages
 constellation.setMessageReceiveCallback([](JsonObject& json) { 
   constellation.writeInfo("Message receive ! Message key = %s", json["Key"].asString());     
 }); 
 // Subscribe to message
 constellation.subscribeToMessage();

C’était donc à votre charge de “dispatcher” les messages reçus en fonction du “MessageKey”.

Désormais avec la version 2.0, vous pouvez enregistrer un callback pour un “MessageKey” donné. Par exemple :

constellation.registerMessageCallback("HelloWorld",
  [](JsonObject& json) {
    constellation.writeInfo("Hello Constellation !");
 });

Dans l’exemple ci-dessous, on ajoute/expose un MessageCallback “HelloWorld” qui écrit dans les logs !

Il n’y donc plus besoin de “dispatcher”, un MessageCallback est donc associé à un “MessageKey” unique et un callback. Il n’y a plus besoin non plus de faire un “subscribeToMessage” (cette méthode est invoquée implicitement par le registerMessageCallback).

De plus cette méthode ajoute implicitement les MessageCallbacks dans le Package Descriptor de sorte que chaque MC soit ainsi référencé dans la Constellation

(console)

Vous pouvez également passer un “MessageCallbackDescriptor” dans l’enregistrement de vos MC pour ajouter une description par exemple :

constellation.registerMessageCallback("HelloWorld",
  MessageCallbackDescriptor().setDescription("Say Hello to Constellation"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello Constellation !");
 });

Et même définir les paramètres de vos MC :

constellation.registerMessageCallback("SayHello",
  MessageCallbackDescriptor().setDescription("Say hello !").addParameter("FirstName", "System.String").addParameter("LastName", "System.String"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello %s %s", json["Data"][0].asString(), json["Data"][1].asString()); 
 });

Ici on déclare un MC nommé “SayHello” prenant deux paramètres de type String avec un texte de description. Dans la code nous verrons :

(console)

Tout comme les StateObjects, les types des arguments des MC peuvent être des types complexes.

Par exemple enregistrons un MC prenant un seul argument de type “SampleUserData” que nous allons décrire avec la méthode “addMessageCallbackType” comme un objet composé de deux propriétés de type String :

// Expose a MessageCallback with complex parameter :
constellation.registerMessageCallback("SayHello2",
  MessageCallbackDescriptor().setDescription("Say hello with complex object!").addParameter("User", "SampleUserData"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello %s %s", json["Data"][0]["FirstName"].asString(), json["Data"][0]["LastName"].asString()); 
});  
// and describe the complex parameter "SampleUserData"  
constellation.addMessageCallbackType("SampleUserData", TypeDescriptor().setDescription("This is a smaple user data").addProperty("FirstName", "System.String").addProperty("LastName", "System.String"));

Enfin la méthode “registerMessageCallback” accepte également des callbacks prenant en paramètre le “MessageContext” :

constellation.registerMessageCallback("HelloWorld",
  MessageCallbackDescriptor().setDescription("Say Hello to Constellation"),
  [](JsonObject& json, MessageContext ctx) {
    constellation.writeInfo("Message received from %s", ctx.sender.friendlyName);
 });

L’objet “MessageContext” est défini de la façon suivante :

typedef struct {
    const char* sagaId;
    bool isSaga;
    const char* messageKey;
    MessageSender sender;
    ScopeType scope;
} MessageContext;

typedef struct {
    SenderType type;
    const char* friendlyName;
    const char* connectionId;
} MessageSender;

Vous pouvez donc récupérer les informations sur l’émetteur (Sender) du message, le scope et l’identifiant de Saga si c’est une saga (isSaga = true).

Support des Saga (messages avec réponse)

Une saga est un identifiant unique qu’on affecte à des messages pour les lier entre eux. Cela permet de faire des couples de message “Requête / Réponse”. Une “réponse” étant un message renvoyé à l’émetteur de la requête avec le même identifiant de saga pour que ce dernier puisse l’identifier comme la “réponse” à son message d’origine.

Vous pouvez exposer des MessageCallbacks qui “répondent”, c’est à dire des  MessageCallbacks qui retournent un message de réponse.

Par exemple, exposons un MC pour réaliser des Additions sur un Arduino. Vous enregistrerez un MC “Addition” prenant en parametre deux entiers et qui en retourne un (le résultat) :

constellation.registerMessageCallback("Addition",
  MessageCallbackDescriptor().setDescription("Do addition on this tiny device").addParameter("a", "System.Int32").addParameter("b", "System.Int32").setReturnType("System.Int32"),
  [](JsonObject& json, MessageContext ctx) {        
    int a = json["Data"][0].as<int>();      
    int b = json["Data"][1].as<int>();
    int result = a + b;
    constellation.writeInfo("Addition %d + %d = %d", a, b, result);      
    if(ctx.isSaga) {
      constellation.writeInfo("Doing additoon for %s (sagaId: %s)", ctx.sender.friendlyName, ctx.sagaId);   
    // Return the result :
      constellation.sendResponse<int>(ctx, result);
    }
    else {
      constellation.writeInfo("No saga, no response !");
    }
 });

Vous remarquerez dans le “MessageCallbackDescriptor” l’appel de la méthode “setReturnType” pour spécifier le type de retour (et que le fait qu’il s’agit d’un MC acceptant les sagas).

L’envoi de la réponse étant réalisé par la méthode sendReponse. Cette méthode a plusieurs surcharges :

template<typename T> bool sendResponse(MessageContext context, T data);
bool sendResponse(MessageContext context, const char* data, ...);
bool sendResponse(MessageContext context, JsonObject& data);

Notez aussi que vous devriez faire un “sendResponse” si et seulement le message reçu est associé à une saga, c’est à dire que le champs “isSaga” du contexte (MessageContext) est “vrai”. Sinon ca ne sert à rien de répondre

Pour finir, cette nouvelle version supporte également l’envoi de message dans une saga. C’est à dire que vous pouvez envoyer un message qui attend une réponse et donc enregistrer un callback de traitement de la réponse.

Par exemple le package “NetworkTools” expose un MC “Ping” permettant de faire un ping. Le package retourne dans la saga un message contenant le temps en milliseconde du ping. On pourrait alors invoquer cette méthode depuis notre Arduino de la façon suivante :

const char* ip = "192.168.0.10";
// Send message in a saga and attach a callback for response :
constellation.sendMessageWithSaga([](JsonObject& json) {
  constellation.writeInfo("Ping response in %s ms", json["Data"].asString()); 
}, Package, "NetworkTools", "Ping", "[ '%s' ]", ip);

Ici on envoi un message au scope “Package” pour atteindre le(x) package(s) “NetworkTools” afin d’invoquer le MessageCallback “Ping” en passant en argument l’IP à pinger. Vous remarquerez qu’on utilise le formatage implicite des arguments.

La méthode n’est pas la traditionnelle “sendMessage” mais “sendMessageWithSaga” qui prend un argument supplémentaire : le callback de traitement de la réponse.

Ainsi quand le package “NetworkTools” répondra, on executera le callback associé qui ici affichera le temps de réponse de notre ping (Data) dans les logs Constellation (writeInfo).

De ce fait, avec cette nouvelle libraire vos Arduino/ESP peuvent invoquer des MC dans sagas pour exploiter la réponse mais également exposer des MC qui retournent des résultats.

Autres nouveautés

En vrac, vous disposez maintenant une méthode “purgeStateObjects” permettant de supprimer des StateObjects de votre package.

De plus la méthode “setDebugMode” accepte en argument l’énumération “DebugMode” composée des valeurs suivantes :

• “Quiet” (mode silencieux, la libraire ne produit aucune trace dans l’interface Serial)
• “Normal” (mode par défaut, écrit quelques informations dans l’interface Serial)
• “Verbose” (écrit beaucoup d’information dans l’interface Serial comme par exemple les requêtes et réponse HTTP v ers Constellation)

Enfin les exemples fournis dans la libraire ont été complètement revus.

The post Nouvelle librairie Constellation pour Arduino / ESP8266 en version 2.0 appeared first on Constellation.

Pour chaque MessageCallback déclaré vous retrouverez une description, la liste des paramètres du MessageCallback avec un formulaire de test et un bouton d’envoi.

Il est ainsi possible de tester directement les MC de vos packages depuis la Console Constellation.

Vous disposez également d’un moteur de recherche :

Si le package est déployé sur plusieurs sentinelle le bouton “Invoke” vous proposera d’envoyer votre message à une instance en particulier ou à toutes les instances du package dans votre Constellation :

Aussi le MessageCallbacks Explorer dispose d’un générateur de code permettant d’afficher des “code snippets” d’invocation du MC pour chaque API Constellation.

Vous pouvez ouvrir ce générateur de code en cliquant sur le bouton à côté du nom de chaque MessageCallback.

Les types personnalisés sont affichés sous forme de lien sur lesquels vous pouvez cliquer pour ouvrir la fenêtre de description de type :

Enfin pour les MessageCallbacks avec message de réponse, vous pouvez les invoquer en envoyant le message dans une saga en cochant la case “With Saga” :

Les messages de réponse des sagas apparaissent sous forme de notification dans la barre du haut :

En cliquant dessus vous pourrez consulter le message de réponse ainsi que l’ensemble des informations liées à la saga :

The post Le MessageCallbacks Explorer appeared first on Constellation.

Pour exposer une méthode Python dans Constellation vous devez tout simplement ajouter le décorateur “Constellation.MessageCallback” sur votre méthode :

@Constellation.MessageCallback()
def SimpleMessageCallback():
    Constellation.WriteInfo('Hello Python !')

Ici nous déclarons le MessageCallback “SimpleMessageCallback” sans paramètre ni documentation.

Vous pouvez ajouter un ou plusieurs arguments à votre MC et utiliser la syntaxe de Python pour commenter vos MC :

@Constellation.MessageCallback()
def DemoArg(data):
    "Ceci est la description du MessageCallback DemoArg avec 1 argument"
    Constellation.WriteInfo('arg = %s', data)

@Constellation.MessageCallback()
def DemoArgs(a, b, c):
    "Ceci est la description du MessageCallback DemoArgs avec 3 arguments"
    Constellation.WriteInfo(a)
    Constellation.WriteInfo(b)
    Constellation.WriteInfo(c)

Le ou les paramètres peuvent être des types simples (string, int, bool, etc..) ou des types (objets) complexes :

@Constellation.MessageCallback()
def ComplexMessageCallback(data):
    "Ceci est la description du MessageCallback ComplexMessageCallback avec un objet complexe en argument"
    Constellation.WriteInfo(data.A)
    Constellation.WriteInfo(data.B)
    Constellation.WriteInfo(data.C)

L’ensemble de ces méthodes déclarées “MessageCallbacks” seront alors référencées dans la Constellation. Vous pouvez les découvrir en interrogeant le Package Descriptor de votre package.

Par exemple, lancez la Console Constellation et rendez-vous dans le “MessageCallback Browser”. Vous aurez la liste de vos méthodes avec la possibilité de les invoquer directement depuis l’interface :

Documenter son MessageCallback

Description des MessageCallbacks

Comme vous l’avez remarqué dans les exemples précédents, nous utilisons la documentation des méthodes de Python :

@Constellation.MessageCallback()
def Demo():
    "Ceci est la description du MessageCallback !"
    pass

La documentation de la méthode est utilisée comme description du MessageCallback :

La description de la méthode peut être écrite sur plusieurs lignes :

@Constellation.MessageCallback()
def Demo():
    '''
    The first line is brief explanation, which may be completed with 
    a longer one. For instance to discuss about its methods.
    '''
    pass

Description des arguments des MessageCallbacks

Note : la description des arguments est disponible depuis l’API Python 1.8.4.x. Pensez à mettre à jour la référence de votre API par Nuget depuis Visual Studio ou en mettant à jour le template depuis la CLI.

Si vous regardez attentivement les arguments des MC dans le MessageCallback Explorer, ils sont reconnus comme « System.Object » étant donné que les arguments d’une fonction en Python ne sont pas typés.

Pour décrire les paramètres utilisez la syntaxe suivante dans la description du MC :

:param <type> <name> : <description>

Par exemple :

@Constellation.MessageCallback()
def Demo(a, b, c):
    '''
    Ceci est un exemple de MC avec 3 parametres

    :param int a: My int value
    :param bool b: My boolean value
    :param string c: My string value
    '''
    Constellation.WriteInfo("a = %s - type: %s" % (a, type(a)))
    Constellation.WriteInfo("b = %s - type: %s" % (b, type(b)))
    Constellation.WriteInfo("c = %s - type: %s" % (c, type(c)))

Ainsi en retournant sur le MC Explorer, chaque argument est correctement typé dans Constellation.

Paramètres optionnels avec valeur par défaut

Vous pouvez également définir que certains paramètres sont optionnels en spécifiant leurs valeurs par défaut avec la syntaxe [default: XXX] :

@Constellation.MessageCallback()
def DemoOptional(a, b):
    '''
    Ceci est un exemple de MC des paramètres optionnels

    :param int a: My int value [default:10]
    :param bool b: My boolean value [default:true]
    '''
    Constellation.WriteInfo("a = %s" % a)
    Constellation.WriteInfo("b = %s" % b)

Décrire les arguments de type complexe

Dans le cas où un MC prend en paramètre un (ou plusieurs) type complexe, il faudra d’abord décrie le type dans la méthode « Start ».

Par exemple, enregistrons au démarrage du package (méthode Start), le type “CredentialInfo” :

Constellation.DescribeMessageCallbackType("CredentialInfo", "Credential information", [
    { 'Name':'Username', 'Type':'string', 'Description': 'The username' },
    { 'Name':'Password', 'Type':'string', 'Description': 'The password' },
])

Une fois tous vos types déclarés, il faut publier le “Package Descriptor” de votre package à Constellation par la ligne :

Constellation.DeclarePackageDescriptor()

Nous pouvons maintenant déclarer un MC avec un parametre de type “CredentialInfo”. Par exemple :

@Constellation.MessageCallback()
def DemoAuth(credential):
    '''
    Demo MC avec avec un paramètre de type complexe

    :param CredentialInfo credential: the credential info
    '''
    Constellation.WriteInfo("User=%s Password=%s" % (credential.Username, credential.Password))

Comme vous pourrez le voir dans le MessageCallbacks Explorer, votre méthode Python est correctement décrite ainsi que son paramètre “credential” de type “Credentialnfo”.

Notez également que la description du type CredentialInfo est accessible en cliquant sur le type :

Personnaliser le MessageCallback

Comme pour l’API.NET, par défaut le nom du MessageCallback déclaré dans la Constellation est le nom de votre méthode mais vous pouvez redéfinir le nom exposé dans la Constellation :

@Constellation.MessageCallback("MySuperName")
def MyInternalMethodName():
    Constellation.WriteInfo("Hello")

Aussi vous pouvez “cacher” ce MessageCallback à la Constellation.

@Constellation.MessageCallback(False)
def HiddenMessageCallback():
    "Hidden message callback"
    Constellation.WriteInfo("I'm here !!")

Tous les packages ou consommateurs de votre Constellation pourront envoyer un message “HiddenMessageCallback” à votre package Python et donc invoquer votre méthode mais celle-ci ne sera pas déclarée dans le “Package  Descriptor”.

Récupérer le contexte

Comme avec l’API.NET, vous pouvez récupérer le contexte de réception du message en déclarant comme dernier argument de votre MessageCallback, le paramètre “context”.

Par exemple :

@Constellation.MessageCallback("MaMethode") # méthode renommée !
def DemoSeb5(context):
    "Test du contexte"
    Constellation.WriteInfo("Sender : %s" % context.Sender.FriendlyName)
    Constellation.WriteInfo("test sans parametre")

Ou avec des paramètres :

@Constellation.MessageCallback()
def DemoSeb5(a, b, context):
    "Test du contexte avec parametre"
    Constellation.WriteInfo("Sender : %s" % context.Sender.FriendlyName)
    Constellation.WriteInfo("a = %s et b = %s" % (a, b))

Il faut juste que le dernier argument soit nommé “context”. Notez qu’il ne fait pas partie de la signature de votre MessageCallback.

Ci-dessus, le 1er exemple est un MessageCallback caché et sans paramètre et le 2ème n’a que deux paramètres “a” et “b”.

L’objet “context” correspondant à la classe “Constellation.Package.MessageContext”. Vous retrouvez les propriétés suivantes :

• IsSaga : indique si le message reçu appartient à une Saga
• SagaId : identifiant de la Saga (si IsSaga = true)
• Scope : scope d’envoi du message reçu
  • Type : type du scope (All, Group, Package, Sentinel, Others)
  • Args : arguments du scope (ex : nom du groupe, du package ou de la sentinelle)
• Sender : représente l’émetteur du message
  • ConnectionId : identifiant de connexion unique de l’émetteur
  • Type : type de l’émetteur (ConsumerHub, ConstellationHub, ConsumerHttp ou ConstellationHttp)
  • FriendlyName : nom de l’émetteur

Répondre aux Sagas

Votre méthode peut également retourner une réponse à l’appelant, c’est ce que l’on appelle une saga. Pour cela vous pouvez spécifier le type de la valeur de retour dans le décorateur de la façon suivante :

@Constellation.MessageCallback(returnType='System.Boolean')
def DemoSaga(user, password):
    "Test de saga"
    Constellation.WriteInfo("User=%s Password=%s" % (user, password))
    return user == password

Cependant il est recommandé d’utiliser la description du MC pour spécifier le type de retour avec la syntaxe

:return <type>: <description>

Par exemple :

@Constellation.MessageCallback()
def DemoSaga(user, password):
    '''
    Test de saga

    :param string user: The username
    :param string password: The password
    :return bool: if user match
    '''
    Constellation.WriteInfo("User=%s Password=%s" % (user, password))
    return user == password

Cela marche également en combinant la récupération du contexte :

@Constellation.MessageCallback()
def DemoAuth(user, password, context):
    '''
    Test de saga

    :param string user: The username
    :param string password: The password
    :return bool: if user match
    '''
    Constellation.WriteInfo("Sender : %s" % context.Sender.FriendlyName)
    Constellation.WriteInfo("User=%s Password=%s" % (user, password))
    return user == password

Par exemple en ouvrant le “Message Callback Explorer” de la Console Constellation vous constaterez que votre MC “DemoAuth” est bien référencé comme retournant un “Booléen” en prenant deux arguments (car l’argument “context” n’est pas pris en compte dans la signature du MC) :

En invoquant cette méthode depuis la console, vous recevrez alors la réponse du package, ici un booléen :

Dans les logs, on retrouve bien la trace de l’invocation de notre Saga avec le “contexte” :

(le FriendlyName de la Console Constellation est “Consumer/ControlCenter:<user>”).

The post MessageCallback : Exposer des méthodes Python appeared first on Constellation.

Pour envoyer un message et donc invoquer un MessageCallback depuis un package Python vous devez utiliser la méthode “Constellation.SendMessage”. Par exemple :

Constellation.SendMessage("SMS", "SendMessage", [ "+33676903634", "Bonjour Constellation" ])

Ici par exemple on envoi un message au package “SMS” pour invoquer le MessageCallback “SendMessage” en passant en argument deux paramètres de type string.

Le MessageCallbacks Explorer de la Console Constellation permet de lister l’ensemble des MC déclarés par les packages de votre Constellation.

Par exemple, avec le package Nest déployé dans votre Constellation, on retrouvera un MessageCallback  “SetTargetTemperature” pour piloter la température de consigne d’un thermostat Nest.

Pour l’invoquer depuis notre code Python :

Constellation.SendMessage("Nest", "SetTargetTemperature", [ "thermostatId", 19 ], Constellation.MessageScope.package)

On peut également passer en paramètre un objet complexe. Par exemple le MC “AreaArm” du package Paradox permet d’armer le système d’alarme en passant en paramètre un objet “ArmingRequestData” contenant le secteur à armer, le mode d’armement et le PIN.

Le code Python pour invoquer ce MC sera alors :

Constellation.SendMessage("Paradox", "AreaArm", { "Area":"All", "Mode":1, "PinCode":"0000" }, Constellation.MessageScope.package)

Vous pouvez également passer plusieurs arguments à votre MC en combinant type simple et type complexe. Par exemple le MC “ShowNotification” du package Xbmc permettant d’afficher une notification sur une interface Kodi/XBMC prend deux paramètres : le nom d l’hôte XBMC (un type simple) et le détail de la notification à afficher (un type complexe) :

Constellation.SendMessage("Xbmc", "ShowNotification", [ xbmcName, { "Title":"Hello Constellation", "Message":"Hello I'm Python" } ], Constellation.MessageScope.package)

Les exemples de message ci-dessus sont tous envoyés à un package mais vous pouvez également envoyer vos messages à différents scopes.

Par exemple pour envoyer le message “Demo” sans aucun paramètre au groupe A, on écrira :

Constellation.SendMessage("A", "Demo", {}, Constellation.MessageScope.group)

Les scopes disponibles sont :

• group
• package
• sentinel
• others
• all

Notez par ailleurs que le paramètre “MessageScope” de la méthode “SendMessage” est optionnel. Si il n’est pas spécifié le scope par défaut est “package”.

Envoyer des messages avec réponse : les Sagas

Si le MC que vous invoquez retourne un message de réponse, vous devez envoyer votre message dans une saga. Pour cela vous pouvez utiliser la méthode “SendMessageWithSaga” dans laquelle vous devrez spécifier la fonction qui sera invoquée lors de la réception de la réponse.

Par exemple reprenons le MessageCallback “AreaArm” du package Paradox :

Comme vous le constatez, ce MessageCallback retourne un “Boolean” pour indiquer si l’armement a bien été déclenché.

On peut donc invoquer ce MC dans une saga et attacher un callback de réponse pour afficher dans le logs de notre package si l’armement a réussi :

Constellation.SendMessageWithSaga(lambda response:
   Constellation.WriteInfo("Arm result is %s" % response),
"Paradox", "AreaArm", { "Area":"All", "Mode":1, "PinCode":"0000" })

Ici nous avons utilisé une fonction lambda pour simplifier la lecture mais vous pouvez également définir une fonction classique dans votre code.

Le paramètre “response” utilisé dans la fonction callback est l’objet de la réponse envoyé par le package qui a reçu votre message. Ici “response” est un “Boolean” car le MC “AreaArm” retourne un booléen mais il peut être de n’importe quel type (simple ou complexe).

Le MessageCallback Explorer de la Console Constellation vous donnera tous les détails.

The post Envoyer des messages et invoquer des MessageCallbacks en Python appeared first on Constellation.

Message & Scope

Les notions de base du Messaging de Constellation sont :

Un message :

• porte obligatoirement une clé (le MessageKey), en quelque sorte l’équivalent du “Sujet” d’un mail.
• peut contenir optionnellement un contenu, nommé “Data”
• est envoyé à un scope.

Un scope :

• défini les destinataires d’un message
• peut être de différents types :
  • All : c’est à dire que tous les systèmes connectés dans Constellation recevront le message (y compris l’émetteur)
  • Other : tout le monde sauf l’émetteur
  • Package : cible un ou plusieurs packages
  • Sentinel : cible tous les packages hébergés sur les sentinelles visées par le scope
  • Group : cible les packages ou consommateurs appartenant aux groupes visés par le scope

Les scopes “Package”, “Sentinel” et “Group” peuvent déclarer une liste de packages, de sentinelles et de groupes.

• Lorsque l’on cible une sentinelle, on vise tous les packages qu’elle héberge.
• Lorsque l’on cible un package, on vise toutes les instances de ce package sur les sentinelles de votre Constellation.

Si vous voulez cibler un seul package en particulier, vous devez obligatoirement créer un scope de type Package et définir le nom du package préfixé du nom de la sentinelle avec la nomenclature “SENTINEL/Package”.

Chaque package ou consommateur peut s’inscrire à un groupe ou être inscrit d’office dans la configuration du serveur (lire l’article sur les groupes).

MessageCallback

Les messages dans Constellation servent essentiellement à invoquer des méthodes. On appelle cela des “MessageCallbacks” le fait de lier un message à une fonction de votre programme.

Il s’agit tout simplement déclarer une méthode de votre code comme « MessageCallback », c’est à dire que si le package reçoit un message dont la clé du message est le nom d’une méthode déclarée comme MessageCallback, alors cette méthode sera invoquée. Le contenu du message reçu (c’est à dire les “Datas”)  contiendra les paramètres de la méthode.

De la même façon, pour invoquer une méthode d’un autre package, il suffit d’envoyer un message dont la clé est la méthode à invoquer avec comme contenu de message les paramètres à passer à cette méthode.

Les Sagas

Chaque message envoyé dans Constellation est à sens unique. Il n’y a aucun retour.

Un message est envoyé à un scope,  il peut ne jamais être reçu (si « personne » n’est visée par le scope) ou à l’inverse être reçu par tout le monde.

Cependant il y a certain cas où il est indispensable d’obtenir une réponse à un message ! Comme en programmation, il n’y a pas que des procédures, il y a aussi des fonctions.

Pour cela, Constellation propose le concept de “Saga”. Une saga est un identifiant porté par un scope. Pour faire l’analogie, “La guerre des étoiles”, “L’Empire contre-attaque » ou “Le Retour du Jedi” sont trois films distincts qui portent le même identifiant de Saga : “Star Wars”.

Il en va de même pour les messages Constellation. Pour “répondre”, il suffit d’envoyer un message “de réponse” à un scope qui vise l’émetteur du message original en prenant soin d’utiliser le même identifiant de saga.

Ainsi l’émetteur en recevant ce message, pourra savoir qu’il s’agit de la réponse à son message car il retrouvera le même identifiant de saga.

Bien entendu l’identifiant de Saga doit être unique et aléatoire pour chaque couple “Request / Response” .

De ce fait, lorsque l’on reçoit un message, si le scope porte un identifiant de Saga cela veut dire que l’émetteur a envoyé le message “dans une Saga”, il s’attend donc à recevoir une réponse. Le clé d’un message de réponse est toujours “__Response”.

Auto-description des MessageCallbacks

Chaque packages (virtuel ou non) doit ou devrait déclarer son “Package Descriptor”.

Il s’agit de la description du package qui contient entre autre les MessageCallbacks du package, c’est à dire les méthodes que le package expose dans la Constellation.

Le MessageCallback Explorer de la Console Constellation exploite les “Package Descriptors” connus pour créer la liste de l’ensemble des MessageCallbacks exposés par les package d’une Constellation avec le détail des paramètres en entrée et le type de retour. Il est également possible d’invoquer ces MC avec une interface de test et de générer le code pour invoquer ces MC sur les différentes API de Constellation.

The post Messaging : Message, Scope, MessageCallback et Saga appeared first on Constellation.

Exposer des méthodes

Pour exposer une méthode .NET dans Constellation, il suffit d’ajouter l’attribut “MessageCallback” sur une méthode :

[MessageCallback]
void MyMethod()
{
    PackageHost.WriteInfo("This is a MessageCallback !");
}

Cela fonctionne que votre méthode soit privée ou public, d’instance ou statique.

Une méthode marquée MessageCallback peut accepter zéro, un ou plusieurs paramètres :

[MessageCallback]       
void MyMethodWithMultipleParameters(string input, int number, bool boolean)
{
    PackageHost.WriteInfo("Input= {0} - Number: {1} - Boolean: {2}", input, number, boolean);
}

De plus chaque paramètre peut être de type simple ou complexe :

[MessageCallback] 
void MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password); 
}

Par défaut seules les méthodes marquées [MessageCallback] sur votre classe ”IPackage” sont enregistrées.

Si vous souhaitez également enregistrer les MessageCallbacks référencés de vos autres types, vous devez appeler la méthode “RegisterMessageCallbacks” en passant en paramètre l’instance ou le type à enregistrer :

PackageHost.RegisterMessageCallbacks(source);

Testez vos MessageCallbacks depuis la Console Constellation

Si vous publiez votre package ou démarrer votre package depuis VS  avec les trois méthodes ci-dessus, vous retrouverez ces trois MessageCallbacks dans l’explorateur :

Tout y est décrit, y compris les types complexes :

Vous pourrez alors directement tester vos MC depuis la Console :

Ce qui compte tenu du code donné en exemple ci-dessus affichera des messages dans les logs Constellation visible sur la Console Log :

Personnaliser le nom du MessageCallback

Vous pouvez également changer le nom du MessageCallback sans forcement changer le nom de votre méthode :

[MessageCallback(Key="Logon")]
void MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password);
}

Ici la méthode se nomme toujours “MyMethodWithComplexParameter” dans notre code C# mais est vue dans Constellation comme le MessageCallback nommé “Logon” :

MessageCallback caché

Vous pouvez aussi exposer des MessageCallbacks que vous ne souhaitez “rendre publique”. En d’autre mots, vous ne souhaitez pas que votre MC soit référencé dans la description de votre package.

Exemple : vous avez un package qui envoie des messages à un groupe pour prévenir de l’arrivée d’un événement (ex: le téléphone sonne). Vous souhaitez, dans le code de votre package, déclencher une méthode lorsque cet événement se produit. Autrement dit, vous créez une méthode marquée “MessageCallback“ qui porte le même nom que le MessageKey envoyé par l’autre package (le même nom de méthode ou via la propriété Key comme vu ci-dessus).

Ainsi, comme votre package fait partie du groupe cible, lorsque le téléphone sonne, l’autre package envoie un message au groupe, vous recevez donc le message et comme vous avez un MessageCallback du même nom, votre méthode est invoquée !

C’est parfait à l’exception que tout le monde “voit l’existence” de cette méthode et peuvent tous l’invoquer !

Deux solutions :

• Cacher le MessageCallback (= ne pas le déclarer dans la description du package)
• Vérifier l’émetteur

Pour cacher un MC, il suffit simple de définir la propriété “IsHidden” à vrai :

[MessageCallback(IsHidden = true)]
void HiddenMethod()
{
    PackageHost.WriteInfo("This is a MessageCallback !");
}

Ainsi la méthode, n’apparaîtra nulle part, personne ne pourra savoir que votre package “écoute” des messages dont la clé est ici “HiddenMethod”.

MessageContext

Vous pouvez, dans le code d’un “MessageCallback”, accéder au contexte du message reçu via la propriété “MessageContext.Current”.

Le contexte du message contient notamment le MessageSender (identifié de l’émetteur du message) et le MessageScope (scope dans lequel le message a été envoyé ).

Par exemple on pourrait écrire :

[MessageCallback(IsHidden = true)]
void HiddenMethod()
{
    if(MessageContext.Current.Sender.FriendlyName == "SENTINEL-DEMO/MySafePackage")
    {
        PackageHost.WriteInfo("OK j’autorise le package MySafePackage de la sentinelle SENTINEL-DEMO");
    }
    else
    {
        PackageHost.WriteWarn("Je refuse que {0} puisse invoquer cette méthode !", MessageContext.Current.Sender.FriendlyName);
    }
}

Répondre à une saga

Comme nous l’avons vu dans les concepts, il est possible de répondre à un message en renvoyant un message avec le même identifiant de saga. De ce fait, un MessageCallback peut renvoyer une réponse.

Dans la pratique, il suffit de regarder dans le contexte du message si c’est une saga (c’est à dire que le scope porte un identifiant de saga). Si c’est une saga, vous pouvez appeler la méthode d’extension “SendResponse” qui se chargera pour vous d’envoyer le contenu de votre message dans un scope portant le même identifiant de saga et à destination du package émetteur.

De plus, pour indiquer que le MessageCallback répond aux sagas, on indique quel est le type de l’objet de réponse dans l’attribut [MessageCallback] avec la propriété ResponseType.

Par exemple :

[MessageCallback(Key="Logon", ResponseType=typeof(bool))]
void MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password);

    if (MessageContext.Current.IsSaga)
    {
        MessageContext.Current.SendResponse(user.User == user.Password);
    }
}

Avec Constellation 1.8, la syntaxe est encore plus simple. Vous pouvez simplement écrire votre MessageCallback avec une fonction .NET, c’est à dire une méthode qui retourne (return) une valeur :

[MessageCallback(Key="Logon")]
bool MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password);

    return user.User == user.Password;
}

La propriété “ResponseType” du MessageCallback est automatiquement définie avec le type de retour de la méthode. C’est l’API .NET qui se chargera d’envoyer la réponse si le message est reçu est une saga. La réponse renvoyée étant l’objet retourné par votre méthode, dans l’exemple ci-dessus un booléen.

Ainsi en republiant le package avec le code ci-dessus, vous constaterez dans le MessageCallbacks Explorer que votre MessageCallback indique son type de réponse dans le cas d’une saga :

Vous pourrez alors tester votre MessageCallback :

Et visualisez le message de retour, ici un booléen :

Décrire ses MessageCallbacks

Pour finir il est vivement conseillé de décrire ses MessageCallbacks et les types utilisés en paramètre ou en réponse.

Vous avez deux possibilités :

• Utilisez la propriété “Description” sur l’attribut MessageCallback (mais limité aux MC et non aux types)
• Utilisez les commentaires de documentation XML

Pour gagner en productivité, je vous recommande l’extension Visual Studio GhostDoc de SubMain pour générer automatiquement des commentaires de documentation XML dans votre code .NET.

Ainsi ajoutons des commentaires de documentation XML sur nos MessageCallbacks et sur la classe UserInfo utilisée dans nos exemples comme paramètre de notre MC :

/// <summary>
/// Methode d'identification d'un utilisateur.
/// </summary>
/// <param name="user">L'utilisateur à identifier.</param>
/// <returns><c>true</c> si identifié</returns>
[MessageCallback(Key="Logon")]
bool MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password);

    return user.User == user.Password;
}

/// <summary>
/// Classe decrivrant un utilisateur
/// </summary>
public class UserInfo
{
    /// <summary>
    /// Le nom d'utilisateur
    /// </summary>
    public string User { get; set; }

    /// <summary>
    /// Le mot de passe de l'utilisateur
    /// </summary>
    public string Password { get; set; }
}

Si vous redéployez le package, vous observerez que l’ensemble des MessageCallbacks et des paramètres sont décrits par vos commentaires XML :

S’abonner et recevoir les messages d’un groupe

Comme vous le savez, il existe plusieurs type de scope pour recevoir un message. Par défaut votre package recevra les messages adressés au scope “All” et “Other” (si il n’est pas l’émetteur du message) mais aussi et surtout ceux destinés au scope de sa sentinelle et/ou de son package.

Il y a un dernier type de scope fort utile : “les groupes”. Pour recevoir des messages destinés à un groupe, il faut d’abord s’abonner au groupe.

Vous avez deux manières d’ajouter votre package dans un groupe :

• Depuis la configuration du serveur
• Depuis le code de votre package

La première méthode se réalise dans la configuration de votre package directement dans la configuration du serveur Constellation.

Il suffit d’ajouter un élément “group” en indiquant les noms des groupes à rejoindre.

<sentinel name="PO-SWARIN" credential="StandardAccess">
    <packages>        
        <package name="HWMonitor" enable="true"></package>  
        <package name="ConstellationPackageConsole1" enable="true"></package> 
        <package name="MonPremierPackage" enable="true">
            <groups>
                <group name="MonGroupDemo" />
            </groups>
            <settings>
                <setting key="Interval" value="2000" />
            </settings>
        </package>  
    </packages>                
 </sentinel>

Vous pouvez aussi utiliser la Console Constellation pour éditer les groupes de chaque package.

Autre manière, directement dans votre code en utilisant la méthode “PackageHost.SubscribeMessages” (ou PackageHost.UnsubscribeMessages).

Par exemple :

PackageHost.SubscribeMessages("MonGroupDemo");

The post MessageCallbacks : exposez vos méthodes appeared first on Constellation.

Vous pouvez soit utiliser le gestionnaire de package Nuget depuis Visual Studio pour installer la dernière version du package “Constellation.Javascript” et ses dépendances :

Ou bien utiliser (ou copier en local) les scripts des CDN en ajoutant dans votre code HTML les balises suivantes :

<script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/signalr/jquery.signalr-2.2.2.min.js"></script>
<script type="text/javascript" src="https://cdn.myconstellation.io/js/Constellation-1.8.2.min.js"></script>

Une fois les scripts ajoutés dans votre page vous devez initialiser le client Constellation en spécifiant l’URL de votre serveur Constellation, la clé d’accès et le “Friendly name” de votre page :

var constellation = $.signalR.createConstellationConsumer("http://localhost:8088", "123456789", "Test API JS");

Vous pouvez créer une clé d’accès depuis la Console Constellation ou en éditant le fichier de configuration du serveur.

Enfin ajoutons un handler sur le changement d’état de la connexion pour afficher le message “Je suis connecté” dans la console de votre navigateur par exemple lorsque la connexion à Constellation est établie :

constellation.connection.stateChanged(function (change) {
    if (change.newState === $.signalR.connectionState.connected) {
        console.log("Je suis connecté");
    }
});

Il ne reste plus qu’à lancer la connexion en invoquant la méthode Start :

constellation.connection.start();

Et voilà, votre page est connectée à votre Constellation.

Envoyer des messages et invoquer des MessageCallbacks

Envoyer des messages

Pour envoyer des messages et donc invoquer des MessageCallbacks vous devez utiliser la méthode “constellation.server.sendMessage” en spécifiant :

• Le scope
• La clé du message
• Le contenu du message (= les paramètres du MessageCallback)

Par exemple, avec le package Nest déployé dans votre Constellation, on retrouvera un MessageCallback  “SetTargetTemperature” pour piloter la température de consigne d’un thermostat Nest.

N’hésitez pas à utiliser le MessageCallback Explorer pour découvrir l’ensemble des MessageCallbacks exposés par les packages de votre Constellation.

Pour invoquer le MessageCallback  “SetTargetTemperature” depuis votre page Web en passant en paramètre l’ID du thermostat et la température de consigne :

constellation.server.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'thermostatId', 19);

Vous pouvez également passer plusieurs arguments à votre MC combinant type simple et type complexe.

Par exemple le MC “ShowNotification” du package Xbmc permettant d’afficher une notification sur une interface Kodi/XBMC prend deux paramètres : le nom d l’hôte XBMC (un type string) et le détail de la notification à afficher (un type complexe) :

constellation.server.sendMessage({ Scope: 'Package', Args: ['Xbmc'] }, 'ShowNotification', xbmcName, { "Title":"Hello", "Message":"Hello from JS" });

Bien entendu vous pouvez invoquer des MessageCallbacks de n’importe quel package, réel (programme Linux/Windows) ou virtuel (Arduino/ESP) ou même sur d’autres consommateurs (pages Web par exemple).

Ainsi vos pages Web peuvent, en envoyant des messages, invoquer des méthodes sur n’importe quel système connecté dans votre Constellation.

Par exemple dans l’article sur les ESP/Arduinos, notre ESP8266 exposait un MC “Reboot” pour redémarrer la puce. Si l’on souhaite redémarrer notre Arduino/ESP depuis une page Web, il suffit d’envoyer un message sans paramètre au bon scope. Par exemple :

constellation.server.sendMessage({ Scope: 'Sentinel', Args: ['MyArduino'] }, 'Reboot');

Ici le scope est “Sentinel” avec l’argument “MyArduino”, c’est à dire que le message “Reboot” sera envoyé à tous les packages de la sentinelle “MyArduino”.

Les scopes peuvent être :

• Sentinel
• Package
• Group
• Others
• All

La propriété “Args” de l’objet scope est un tableau contenant le nom des groupes, des sentinelles ou packages en fonction du type de scope sélectionné. Seuls les scopes “All” et “Others” n’ont pas besoin d’argument.

Envoyer des messages avec réponse : les sagas

Les Sagas permettent de lier des messages et donc de créer des couples de “requêtes / réponses”.

Avec la libraire JavaScript, il est possible d’envoyer des messages dans une saga et d’enregistrer un callback pour traiter la réponse.

Par exemple, le package “NetworkTools” expose un MC “Ping” permettant de réaliser un ping réseau. Le résultat du ping est retourné dans un message de réponse (un Int64 représentant le temps du réponse du ping) :

De ce fait pour réaliser un ping vers « www.google.fr » depuis une page Web :

constellation.server.sendMessageWithSaga(function(response) {
        console.log("Ping %s ms", response.Data);
    }, { Scope: 'Package', Args: ['NetworkTools'] }, 'Ping', "www.google.fr");

Souvenez-vous de notre package virtuel de notre ESP8266 / Arduino, on exposait un MessageCallback “Addition” capable de réaliser une addition locale (sur le CPU de l’Arduino ou ESP) en prenant en paramètre deux entiers. Le résultat était retourné dans la saga.

constellation.server.sendMessageWithSaga(function(response) {
        console.log("Le resultat de 40+2 par l'Arduino est %s", response.Data);
    }, { Scope: 'Sentinel', Args: ['MyArduino'] }, 'Addition', 40, 2);

Ainsi vos pages Web peuvent invoquer des méthodes et exploiter la réponse de tous les systèmes connectés sur Constellation exposant des MessageCallbacks.

Recevoir des messages

Une page Web connectée sur Constellation peut elle même recevoir des messages et donc exposer des MessageCallbacks que d’autres consommateurs (autres pages Web) ou packages (réels et virtuels) pourront invoquer.

Ceci dit un consommateur tel qu’une page Web n’a pas réellement d’existence. Autrement dit elle n’a pas d’identité et donc ne peut recevoir que des messages adressés à un groupe qu’elle devra joindre.

Pour joindre un groupe vous devez utiliser la méthode “subscribeMessages“ (et “unSubscribeMessages” pour en sortir). Vous pouvez joindre autant de groupe que vous souhaitez.

Par exemple, pour ajouter votre page au groupe “Demo” :

constellation.server.subscribeMessages("Demo");

Vous pourrez ensuite recevoir les messages envoyés dans ce groupe en ajoutant un handler sur le “onReceiveMessage” :

constellation.client.onReceiveMessage(function (message) {
    console.log("Message recu !", message);
});

Dans ce handler vous recevrez TOUS les messages (quelque soit la clé du message).

Vous avez aussi un moyen plus simple consistant à définir un handler pour une clé de message spécifiquement via la méthode “registerMessageCallback”.

Par exemple :

constellation.client.registerMessageCallback("ChangeTitle", function (msg) {
    document.title = msg.Data;
});
constellation.client.registerMessageCallback("HelloWorld", function (msg) {
    alert("Hello World");
});

Ici on enregistre deux MessageCallbacks.

Si votre page reçoit un MessageCallback “HelloWorld”, une alerte sera ouverte, si elle reçoit un MessageCallback “ChangeTitle”, le titre de votre page sera modifié avec l’argument passé dans le MC.

Imaginez par exemple que vous ouvrez une page Web en plein écran sur différents devices dont vous n’avez pas de contrôle (par exemple des écrans Dashboard). Sur cette page vous affichez différentes données en temps réel, par exemple basées sur les StateObjects Constellation.

Vous modifiez votre page et vous souhaitez donc la rafraîchir sur tous les navigateurs qui ont ouvert votre page pour recharger la nouvelle version.

Pour ce faire, vous pouvez facilement exposer un MessageCallback “ReloadMe” qui recharge la page avec le code :

constellation.client.registerMessageCallback("ReloadMe", function (msg) {
    location.reload();
});

Puis vous ajoutez votre page dans le groupe “ControlPage” :

constellation.server.subscribeMessages("ControlPage");

Dans ce fait, vous pouvez maintenant créer une page “cachée” avec un bouton pour invoquer le MessageCallback “ReloadMe” sur le groupe “ControlPage” afin de recharger toutes les navigateurs qui ont ouvert votre page par la ligne :

constellation.server.sendMessage({ Scope:'Group', Args:['ControlPage'] }, "ReloadMe", {});

Bien entendu, comme vos pages HTML peuvent enregistrer autant de MessageCallbacks qu’elles souhaitent et que ces MessageCallbacks sont invocables depuis n’importe quel système connecté à Constellation, d’autres pages Web, des objets à base d’Arduino, ESP ou autre, des programmes Python, .NET, etc… vous pouvez imaginer tout type d’usage.

Consommer des StateObjects

Pour consommer des StateObjects produits par des packages (virtuels ou réels) de votre Constellation, vous avez deux méthodes : l’évènement “onUpdateStateObject” ou les StateObjectLinks.

La première méthode consiste à enregistre un ou plusieurs handlers sur l’évènement “onUpdateStateObject” :

constellation.client.onUpdateStateObject(function (stateobject) {
    console.log(stateobject);
});

Les handlers seront déclenchés à chaque mise à jour ou interrogation des StateObjects de votre page quelque soit le StateObject.

Pour interroger un ou plusieurs StateObjects à un instant T vous disposez de la méthode “requestStateObjects”.

Pour vous abonner aux mises à jour d’un ou plusieurs StateObjects, vous disposez de la méthode “subscribeStateObjects” (et “unSubscribeStateObjects” pour vous désabonner).

Enfin la méthode “requestSubscribeStateObjects” réalise un “requestStateObjects” et un “subscribeStateObjects” c’est à dire que la méthode demande la valeur actuelle du ou des StateObjects et s’abonne auprès du serveur Constellation pour être notifiée des mises à jour.

Toutes ces méthodes prennent en paramètre : le nom de la sentinelle, le nom du package, le nom du StateObject et le type du StateObject. Vous pouvez utiliser le wildcard “*” pour ne pas appliquer de filtre (plus d’information ici).

Par exemple, pour récupérer tous les StateObjects du package “Demo” quelque soit la sentinelle et pour s’abonner aux mises à jour de ces StateObjects :

constellation.server.requestSubscribeStateObjects("*", "Demo", "*", "*");

L’autre méthode consiste à enregistrer un (ou plusieurs) StateObjectLink. Cela permet de lier une fonction à un abonnement.

Par exemple :

constellation.client.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", "*", function (so) {
    // Code A
});

constellation.client.registerStateObjectLink("*", "Demo", "*", "*", function (so) {
    // Code B
});

Ci-dessus le code A sera invoqué dès qu’un SO nommé « /intelcpu/0/load/0” et produit par le package “HWMonitor” est modifié alors que le code B sera déclenché dès qu’un StateObject du package “Demo” est modifié.

The post Consommer Constellation avec l’API Javascript appeared first on Constellation.

Vous pouvez soit utiliser le gestionnaire de package Nuget depuis Visual Studio pour installer la dernière version du package “Constellation.Angular” et ses dépendances :

Ou bien utiliser (ou copier en local) les scripts des CDN en ajoutant dans votre code HTML les balises suivantes :

<script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/signalr/jquery.signalr-2.2.2.min.js"></script>
<script type="text/javascript" src="https://cdn.myconstellation.io/js/Constellation-1.8.2.min.js"></script>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/angularjs/1.5.7/angular.min.js"></script>
<script type="text/javascript" src="https://cdn.myconstellation.io/js/ngConstellation-1.8.2.min.js"></script>

Dans votre code Javascript, vous devez créer un module Angular pour votre page que nous appelleront “MyDemoApp” et dans lequel nous injecterons le module “ngConstellation” :

var myDemoApp = angular.module('MyDemoApp', ['ngConstellation']);

Vous devez également ajouter l’attribut “ng-app” sur la balise <html> de votre page pour lier votre page HTML à votre module Angular :

<html xmlns="http://www.w3.org/1999/xhtml" ng-app="MyDemoApp">

Enfin vous devez créer un contrôleur AngularJS dans lequel nous injecterons la factory “constellationConsumer” que nous appellerons dans notre code “constellation” :

myDemoApp.controller('MyController', ['$scope',  'constellationConsumer', function ($scope, constellation) {

}]);

Sans oublier de lier votre corps de page (<body>) à ce contrôleur :

<body ng-controller="MyController">

Et voilà votre squelette est prêt !

Pour plus d’information sur AngularJS, je vous recommande la lecture de ce guide : https://docs.angularjs.org/misc/started

Pour résumer notre squelette page est donc :

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" ng-app="MyDemoApp">
<head>
    <title>Test API AngularJS</title>
    <script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
    <script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/signalr/jquery.signalr-2.2.2.min.js"></script>
    <script type="text/javascript" src="https://cdn.myconstellation.io/js/Constellation-1.8.2.min.js"></script>
    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/angularjs/1.5.7/angular.min.js"></script>
    <script type="text/javascript" src="https://cdn.myconstellation.io/js/ngConstellation-1.8.2.min.js"></script>
    
    <script>
        var myDemoApp = angular.module('MyDemoApp', ['ngConstellation']);
        myDemoApp.controller('MyController', ['$scope',  'constellationConsumer', function ($scope, constellation) {

        }]);
    </script>

</head>
<body ng-controller="MyController">

</body>
</html>

Connecter une page HTML à Constellation avec AngularJS

Dans notre contrôleur AngularJS, nous allons initialiser le client Consumer en spécifiant l’URL de votre serveur Constellation, la clé d’accès et le “Friendly name” de votre page :

constellation.initializeClient("http://localhost:8088", "123456789", "TestAPI");

Vous pouvez créer une clé d’accès depuis la Console Constellation ou en éditant le fichier de configuration du serveur.

Enfin ajoutons un handler sur le changement d’état de la connexion pour afficher le message “Je suis connecté” dans la console de votre navigateur par exemple lorsque la connexion à Constellation est établie :

constellation.onConnectionStateChanged(function (change) {
    if (change.newState === $.signalR.connectionState.connected) {
        console.log("Je suis connecté !");
    }
});

Il ne reste plus qu’à lancer la connexion en invoquant la méthode “connect” :

constellation.connect();

Et voilà, votre page AngularJS est connectée à votre Constellation.

Envoyer des messages et invoquer des MessageCallbacks

Envoyer des messages

Pour envoyer des messages et donc invoquer des MessageCallbacks vous devez utiliser la méthode “constellation.sendMessage” en spécifiant :

• Le scope
• La clé du message
• Le contenu du message (= les paramètres du MessageCallback)

Par exemple, avec le package Nest déployé dans votre Constellation, on retrouvera un MessageCallback  “SetTargetTemperature” pour piloter la température de consigne d’un thermostat Nest.

N’hésitez pas à utiliser le MessageCallback Explorer pour découvrir l’ensemble des MessageCallbacks exposés par les packages de votre Constellation.

Pour invoquer le MessageCallback  “SetTargetTemperature” depuis votre page Web en passant en paramètre l’ID du thermostat et la température de consigne :

constellation.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'my_thermostat_id', 19);

En AngularJS, pour lier l’invocation de ce code à un bouton, vous devez simplement ajouter l’attribut “ng-click” sur votre bouton.

Par exemple, dans votre code HTML :

<body ng-controller="MyController">
    <button ng-click="SetNestTemperature()">Set Nest to 19°C</button>
</body>

Et dans votre contrôleur :

$scope.SetNestTemperature = function () {
   constellation.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'my_thermostat_id', 19);
};

Autre solution, exposer le client Consumer dans le scope AngularJS :

$scope.constellation = constellation;

Et donc s’en servir directement dans le template HTML :

<body ng-controller="MyController">
    <button ng-click="constellation.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'my_thermostat_id', 19)">Set Nest to 19°C</button>
</body>

Allons un peu plus loin en ajoutant un champ permettant à l’utilisateur de définir la température de consigne.

Dans le template HTML :

Temperature : <input type="number" ng-model="targetTemperature" />
<button ng-click="SetNestTemperature()">Set target temperature</button>

Le champ “input” est de type “number” et est lié à la variable de scope (le modèle) que nous appellerons “targetTemperature”.

De ce  fait dans notre fonction “SetNestTemperature” nous pouvons récupérer la valeur définie par l’utilisateur :

$scope.SetNestTemperature = function () {
   constellation.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'my_thermostat_id', $scope.targetTemperature);
};

Comme pour l’API Javascript, vous pouvez également passer plusieurs arguments à votre MC combinant type simple et type complexe. Si il y a plusieurs paramètres vous devez les stocker dans un tableau.

Par exemple le MC “ShowNotification” du package Xbmc permettant d’afficher une notification sur une interface Kodi/XBMC prend deux paramètres : le nom d l’hôte XBMC (un type string) et le détail de la notification à afficher (un type complexe) :

constellation.sendMessage({ Scope: 'Package', Args: ['Xbmc'] }, 'ShowNotification', xbmcName, { "Title":"Hello", "Message":"Hello from JS" });

Bien entendu vous pouvez invoquer des MessageCallbacks de n’importe quel package, réel (programme Linux/Windows) ou virtuel (Arduino/ESP, scripts, etc..) ou même sur d’autres consommateurs (pages Web par exemple).

Ainsi vos pages Web peuvent, en envoyant des messages, invoquer des méthodes sur n’importe quel système connecté dans votre Constellation.

Par exemple dans l’article sur les ESP/Arduinos, notre ESP8266 exposait un MC “Reboot” pour redémarrer la puce. Si l’on souhaite redémarrer notre Arduino/ESP depuis une page Web, il suffirai d’envoyer un message sans paramètre au bon scope. Par exemple :

constellation.sendMessage({ Scope: 'Sentinel', Args: ['MyArduino'] }, 'Reboot');

Ici le scope est “Sentinel” avec l’argument “MyArduino”, c’est à dire que le message “Reboot” sera envoyé à tous les packages de la sentinelle “MyArduino”.

Les scopes peuvent être :

• Sentinel
• Package
• Group
• Others
• All

La propriété “Args” de l’objet scope est un tableau contenant le nom des groupes, des sentinelles ou packages en fonction du type de scope sélectionné. Seuls les scopes “All” et “Others” n’ont pas besoin d’argument.

Envoyer des messages avec réponse : les sagas

Les Sagas permettent de lier des messages et donc de créer des couples de “requêtes / réponses”.

Avec la libraire JavaScript, il est possible d’envoyer des messages dans une saga et d’enregistrer un callback pour traiter la réponse de ce message.

Par exemple, le package “NetworkTools” expose un MC “Ping” permettant de réaliser un ping réseau. Le résultat du ping est retourné dans un message de réponse (un Int64 représentant le temps du réponse du ping) :

De ce fait pour réaliser un ping depuis une page Web, on pourrait proposer à l’utilisateur un champ pour saisir l’adresse à pinger et afficher le résultat dans un paragraphe.

<body ng-controller="MyController">
   Host/IP : <input ng-model="host" />
   <button ng-click="Ping()">Ping</button>
   <p ng-show="pingResult">Result : {{pingResult}}ms</p>
</body>

Vous remarquez que le paragraphe du n’est affiché (ng-show) que si la valeur de scope “pingResult” est définie, ce qui n’est pas le cas à l’ouverture de la page.

Déclarons enfin la méthode de scope “Ping” pour envoyer un message au package “NetworkTools” afin d’invoquer dans une saga sur le MC “Ping” avec en paramètre du message variable « $scope.host » qui est liée à la zone de texte (input) de votre vue HTML.

Comme il s’agit d’une saga, nous utilisons la méthode “sendMessageWithSaga” dans laquelle nous passons la fonction callback qui sera invoquée lors de la réponse. A la réception cette réponse, nous allons tous simplement stocker le résultat de la réponse (propriété Data) dans la variable de scope “pingResult”.

L’affectation de la réponse dans la variable de scope “pingResult” est réalisée dans un “$scope.$apply”, une fonction AngularJS qui permet d’indiquer au contrôleur AngularJS que des variables de scope ont été modifiées et donc qu’il faut rafraîchir la vue.

scope.Ping = function () {
  constellation.sendMessageWithSaga(function(response) {
      $scope.$apply(function() {
        $scope.pingResult = response.Data;
      });
    }, { Scope: 'Package', Args: ['NetworkTools'] }, 'Ping', $scope.host);
};

Ainsi vos pages Web peuvent invoquer des méthodes et exploiter la réponse de tous les systèmes connectés sur Constellation exposant des MessageCallbacks.

Recevoir des messages

Une page Web connectée sur Constellation peut elle même recevoir des messages et donc exposer des MessageCallbacks que d’autres consommateurs (autres pages Web) ou packages (réels et virtuels) pourront invoquer.

Ceci dit un consommateur tel qu’une page Web n’a pas réellement d’existence. Autrement dit elle n’a pas d’identité et donc ne peut recevoir que des messages adressés à un groupe qu’elle devra joindre.

Pour joindre un groupe vous devez utiliser la méthode “subscribeMessages“ (et “unSubscribeMessages” pour en sortir). Vous pouvez joindre autant de groupe que vous souhaitez.

Par exemple, pour ajouter votre page au groupe “Demo” :

constellation.subscribeMessages("Demo");

Vous pourrez ensuite recevoir les messages envoyés dans ce groupe en ajoutant un handler sur le “onReceiveMessage” :

constellation.onReceiveMessage(function (message) {
    console.log("Message recu !", message);
});

Dans ce handler vous recevrez TOUS les messages (quelque soit la clé du message).

Vous avez aussi un moyen plus simple consistant à définir un handler pour une clé de message spécifiquement via la méthode “registerMessageCallback”.

Par exemple :

constellation.registerMessageCallback("ChangeTitle", function (msg) {
    document.title = msg.Data;
});
constellation.registerMessageCallback("HelloWorld", function (msg) {
    alert("Hello World");
});

Ici on enregistre deux MessageCallbacks.

Si votre page reçoit un MessageCallback “HelloWorld”, une alerte sera ouverte, si elle reçoit un MessageCallback “ChangeTitle”, le titre de votre page sera modifié avec l’argument passé dans le MC.

Bien entendu, comme vos pages HTML peuvent enregistrer autant de MessageCallbacks qu’elles souhaitent et que ces MessageCallbacks sont invocables depuis n’importe quel système connecté à Constellation, d’autres pages Web, des objets à base d’Arduino, ESP ou autre, des programmes Python, .NET, etc… vous pouvez imaginer tout type d’usage.

Consommer des StateObjects

Pour consommer des StateObjects produits par des packages (virtuels ou réels) de votre Constellation, vous avez deux méthodes : l’évènement “onUpdateStateObject” ou les StateObjectLinks.

La première méthode consiste à enregistre un ou plusieurs handlers sur l’évènement “onUpdateStateObject” :

constellation.onUpdateStateObject(function (stateobject) {
    console.log(stateobject);
});

Les handlers seront déclenchés à chaque mise à jour ou interrogation des StateObjects de votre page quelque soit le StateObject.

Pour interroger un ou plusieurs StateObjects à un instant T vous disposez de la méthode “requestStateObjects”.

Pour vous abonner aux mises à jour d’un ou plusieurs StateObjects, vous disposez de la méthode “subscribeStateObjects” (et “unSubscribeStateObjects” pour vous désabonner).

Enfin la méthode “requestSubscribeStateObjects” réalise un “requestStateObjects” et un “subscribeStateObjects” c’est à dire que la méthode demande la valeur actuelle du ou des StateObjects et s’abonne auprès du serveur Constellation pour être notifiée des mises à jour.

Toutes ces méthodes prennent en paramètre : le nom de la sentinelle, le nom du package, le nom du StateObject et le type du StateObject. Vous pouvez utiliser le wildcard “*” pour ne pas appliquer de filtre (plus d’information ici).

Par exemple, pour récupérer tous les StateObjects du package “Demo” quelque soit la sentinelle et pour s’abonner aux mises à jour de ces StateObjects :

constellation.requestSubscribeStateObjects("*", "Demo", "*", "*");

L’autre méthode consiste à enregistrer un (ou plusieurs) StateObjectLink. Cela permet de lier une fonction à un abonnement.

Par exemple :

constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", "*", function (so) {
    // Code A
});

constellation.registerStateObjectLink("*", "Demo", "*", "*", function (so) {
    // Code B
});

Ci-dessus le code A sera invoqué dès qu’un SO nommé « /intelcpu/0/load/0” et produit par le package “HWMonitor” est modifié alors que le code B sera déclenché dès qu’un StateObject du package “Demo” est modifié.

Prenons un cas pratique, nous voulons afficher en temps réel la consommation de notre CPU. Comme expliqué ci-dessus, la consommation peut être connue avec le StateObject nommé « /intelcpu/0/load/0” et produit par le package “HWMonitor”.

Nous allons donc ajouter un StateObjectLink et affecter la variable de scope “cpu” à chaque mise à jour de ce SO. Comme pour la réception de message, nous devons utiliser la fonction Angular “$scope.$apply” pour informer le contrôleur Angular que nous avons changé une variable de scope :

Aussi vous devez enregistrer vos SOLink une fois connecté :

constellation.onConnectionStateChanged(function (change) {
  if (change.newState === $.signalR.connectionState.connected) {
    constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", "*", function (so) {
      $scope.$apply(function() {
        $scope.cpu = so.Value.Value;
      });
    });
  }
});

Et dans notre template :

<body ng-controller="MyController">
    <p>CPU : {{cpu}}</p>
</body>

Plutôt que stocker dans notre variable de scope la propriété “Value” de la valeur de notre StateObject, nous pouvons aussi stocker le StateObject lui même :

$scope.cpu = so;

De ce fait dans le template nous pouvons afficher différentes informations contenu dans notre StateObject  :

<body ng-controller="MyController">
    <p>CPU on {{cpu.SentinelName }} at {{cpu.LastUpdate}} is <strong>{{cpu.Value.Value}} {{cpu.Value.Unit}}</strong></p>
</body>

Alors bien sûr le format de la date ou encore la précision de la valeur mesurée par le package HWMonitor ne sont très lisibles. Nous pouvons ajouter des filtres AngularJS directement dans notre template pour rendre notre page plus “user-friendly”.

Utilisons le filtre “date” pour formater la date et “number” pour limiter le nombre de chiffre après la virgule :

<p>CPU on {{cpu.SentinelName }} at {{cpu.LastUpdate | date : 'dd//MM/yyyy @ hh:mm:ss' }} is <strong>{{cpu.Value.Value | number:2}} {{cpu.Value.Unit}}</strong></p>

C’est toute la magie d’AngularJS

Allons encore un peu plus loin !

Ici nous avons lié notre variable de scope “cpu” au StateObject nommé « /intelcpu/0/load/0” et produit par le package “HWMonitor”. Mais n’oubliez pas que l’unicité d’un StateObject est obtenu avec le triplet : Sentinelle + Package + Nom.

Autrement dit il peut y avoir plusieurs SO qui correspondent à ce filtre dans le cas où vous avez déployé le package HWMonitor sur plusieurs sentinelles.

Dans ce cas, la valeur du SO est sans cesse écrasée et notre page devient illisible :

Nous allons gérer ce cas en créant une variable de scope qui contiendra les différents StateObjects de nos CPUs.

Dans votre scope, commençons par déclarer une variable de scope nommée “cpus” en l’initialisant avec un objet vide :

$scope.cpus = {}

Modifions notre StateObjectLink pour stocker le StateObject dans notre objet “cpus” sous la propriété du nom de la sentinelle de notre StateObject.

constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", "*", function (so) {
  $scope.$apply(function() {
    $scope.cpus[so.SentinelName.replace("-", "")] = so;
  });
});

C’est à dire que notre variable de scope “cpus” est un objet avec des propriétés du nom de la sentinelle et qui contient le StateObject de son CPU associé.

Attention le nom de la sentinelle est utilisée comme nom de propriété de notre objet JavaScript et vous n’êtes pas sans savoir que les “-“ (entre autre) ne sont pas autorisés en JS ce qui explique que nous les effaçons avec le “replace”.

Ainsi si je veux afficher dans mon template le CPU de ma machine nommée ”PC-SEB_UI” (= propriété “PCSEB_UI”), je devrais écrire :

<p>CPU on {{cpus.PCSEB_UI.SentinelName }} at {{cpus.PCSEB_UI.LastUpdate | date : 'dd//MM/yyyy @ hh:mm:ss' }} is <strong>{{cpus.PCSEB_UI.Value.Value | number:2}} {{cpus.PCSEB_UI.Value.Unit}}</strong></p>

Il ni a plus d’effet indésirable de voir les StateObjects chevaucher constamment.

Mais on peut aller encore plus loin car notre variable “cpus” contient tous les SO de la consommation de CPU produits par l’ensemble des packages HWMonitor de notre Constellation.

Il suffit d’itérer sur cette variable pour afficher le SO de chaque propriété de notre objet. Avec AngularJS vous pouvez utiliser la directive “ng-repeat” :

<p ng-repeat="cpu in cpus">CPU on {{cpu.SentinelName }} at {{cpu.LastUpdate | date : 'dd//MM/yyyy @ hh:mm:ss' }} is <strong>{{cpu.Value.Value | number:2}} {{cpu.Value.Unit}}</strong></p>

Nous obtenons une page capable d’afficher en temps réel la consommation de toutes nos machines Windows dans une simple page HTML :

The post Consommer Constellation avec Angular JS appeared first on Constellation.

Pour envoyer des messages et invoquer des méthodes (MessageCallbacks) d’autres packages (ou consommateurs, pages Web, apps mobile, etc… ), vous pouvez utiliser la méthode “sendMessage” :

constellation.sendMessage(scope, args, messageKey, data);

C’est une fonction “variadic“ qui peut prendre plusieurs arguments qui seront utilisés pour formater le contenu (data) du message :

constellation.sendMessage(scope, args, messageKey, data, ...);

Par exemple pour envoyer un message “DemoMessage” avec en contenu un objet contenant deux propriétés (c’est à dire invoquer le MessageCallback “DemoMessage” en passant en paramètre un objet à deux propriétés) au package “MyCsharpPackage“ :

constellation.sendMessage(Package, "MyCsharpPackage", "DemoMessage", "{ A: '%s', B: %d  }",  myStringVal, myIntVal);

Autre exemple : envoyer un message “SignalReceive” au groupe “IR” (dans lequel plusieurs packages ou consommateurs peuvent s’inscrire) avec en paramètre une valeur de type ”long” formatée en hexadécimal :

unsigned long value = results.value; // the IR signal decoded
constellation.sendMessage(Group, "IR", "SignalReceive", "%#x", value);

Le scope

Le scope permet de définir les destinataires du message (plus d’information ici).

Dans la libraire Arduino/SP, l’argument Scope est une énumération définie de la façon suivante :

enum ScopeType : uint8_t {
  None = 0,
  Group = 1,
  Package = 2,
  Sentinel = 3,
  Other = 4,
  All = 5
};

L’argument “args” spécifie les arguments du scope, par exemple le ou les noms des packages, des sentinelles ou des groupes où envoyer le message. Pour cibler une instance d’un package vous spécifierez le nom de l’instance complet “SENTINEL/Package” (plus d’information ici).

Si vous avez plusieurs “args” vous devez les séparer par des virgules. Par exemple pour envoyer un message “HelloWorld” au groupe A et au groupe B :

constellation.sendMessage(Group, "A,B", "HelloWorld", "{}");

Le contenu (Data) du message

Dans la philosophie des MessageCallbacks, le contenu du message (Data) permet de stocker les arguments d’une fonction (MessageCallback) à invoquer.

Si vous invoquez un MC sans paramètre, vous devez spécifier un objet vide “{}” :

constellation.sendMessage(Package, "DemoPackage", "HelloWorld", "{}");

Si vous avez plusieurs paramètres à passer, vous formaterez vos arguments dans un tableau :

constellation.sendMessage(Package, "DemoPackage", "SayHello", "[ 'Sebastien', 'Warin' ]");

Vous pouvez également envoyer en tant qu’argument un objet complexe, par exemple :

constellation.sendMessage(Package, "DemoPackage", "SayHello", "{ 'FirstName':'Sebastien', 'LastName':'Warin' }");

Ou bien même un mixte, par exemple un MC prenant en paramètre un objet complexe et un entier :

constellation.sendMessage(Package, "DemoPackage", "SayHello", "[ { 'FirstName':'Sebastien', 'LastName':'Warin' }, 42 ]");

Ici le contenu du message est formaté en JSON via une chaine de caractère mais vous pouvez également passer un JsonObject à cette méthode :

const int BUFFER_SIZE = JSON_OBJECT_SIZE(2);
StaticJsonBuffer<BUFFER_SIZE> jsonBuffer;
JsonObject& data = jsonBuffer.createObject();
myStateObject["FirstName"] = "Sebastien";
myStateObject["LastName"] = "Warin";
constellation.sendMessage(Package, "DemoPackage", "SayHello", data);

Notez aussi que la Console Constellation liste les MessageCallbacks déclarés par l’ensemble des packages de votre Constellation et vous génère le code pour chaque API.

Par exemple, si vous souhaitez invoquer le MessageCallback “PushNote” du package “PushBullet” qui vous permettra d’envoyer une notification sur un smartphone vous pouvez cliquez sur l’icone de génération de code :

Sélectionnez ensuite le langage “Arduino” pour avoir le modèle correspondant :

Ainsi pour envoyer une notification sur mon smartphone depuis un Arduino/ESP :

constellation.sendMessage(Package, "PushBullet", "PushNote", "[ 'Demo from Arduino', 'Ceci est une demo', 'Device', '' ]");

Bien entendu, n’importe quel package ou consommateur peut recevoir des messages. Vous pouvez donc invoquer des méthodes C#, Python, JS, etc.. depuis un Arduino/ESP.

Envoyer des messages avec réponse : les Sagas

Les Sagas permettent de lier des messages et donc de créer des couples de “requêtes / réponses”.

Avec la libraire Arduino/ESP, il est possible d’envoyer des messages dans une saga afin d’enregistrer un callback de traitement de la réponse.

Par exemple, le package “NetworkTools” expose entre autre un MessageCallback “Ping” permettant de pinger une machine. Si le MC est invoqué dans une saga, le package répondra dans la saga un message contenant le temps de réponse du ping.

De ce fait, si nous souhaitons invoquer cette méthode depuis notre Arduino et traiter la réponse, nous pouvons écrire :

const char* ip = "192.168.0.10";
constellation.sendMessageWithSaga([](JsonObject& json) {
    constellation.writeInfo("Ping response in %s ms", json["Data"].as<char *>()); 
  }, Package, "NetworkTools", "Ping", "[ '%s' ]", ip);

La signature de la méthode “sendMessageWithSaga” est la même que la méthode “sendMessage” présentée ci-dessus à la seule différence qu’elle prend comme 1er argument un callback vers une fonction traitant la réponse ici passée en tant que lambda.

Dans l’exemple ci-dessus, votre Arduino envoie donc un message “Ping” avec une adresse IP en paramètre au(x) package(s) “NetworkTools” en associant un n° de saga. Ce package exécutera le ping et vous retournera un message de réponse avec le résultat du ping. Cette réponse sera traitée par la fonction lambda qui dans l’exemple affichera dans les logs Constellation le résultat du ping.

Ainsi vos Arduino/ESP peuvent très facilement invoquer des méthodes (MessageCallback) avec ou sans retour des différents packages (virtuels ou non) ou consommateurs de votre Constellation; scripts Javascripts, Powershell, Bash, programmes .NET, Python, etc…

The post Envoyer des messages et invoquer des MessageCallbacks depuis un Arduino/ESP appeared first on Constellation.