Introduction

Par exemple si vous disposez d’un Arduino il vous faudra un shield Ethernet ou Wifi bien que ces derniers ont été retirés du support Arduino.

Arduino propose en alternative des modèles déjà équipés d’une connectivité Ethernet et/ou Wifi comme le MKR1000, le Yun Shield ou le Wifi Shield 101.

En alternative vous avez les ESP8266 que j’ai pu vous présenter sur mon blog personnel.

Ce microcontrôleur est cadencé à 80Mhz par un processeur 32bits RISC avec 96K de RAM et une mémoire flash de 512Ko à 4Mo selon les modèles.

Il dispose d’une connectivité Wifi 802.11 b/g/n supportant le WEP, WPA/2/WPS et réseau ouvert et 16 GPIO dont le support du SPI, I²C, UART et un port ADC (pour les I/O analogiques).

Vous trouverez différents modèles sur internet, comme ceux produit par AI-Thinker mais il faudra réaliser vous même la carte de programmation comme je l’explique sur mon blog ou bien des modules “tout en un” comme ceux d’Adafruit ou Sparkfun disposant d’un port USB intégré pour une programmation facile :

Si vous débutez je vous recommande la Wemos D1 Mini qui intègre un ESP8266 avec 4M de mémoire Flash, 11 I/O digitales et 1 analogique (ADC) ainsi qu’une interface USB le tout pour moins de 5€ :

Pour bien comprendre les ESP8266, je vous recommande une nouvelle fois mon article Découverte des ESP8266 : le microcontrôleur connecté par Wifi pour 2€ au potentiel phénoménal avec Constellation

Le plus important étant que les ESP8266 peuvent être programmés comme les Arduino avec l’IDE Arduino.

Arduino/ESP8266 = package virtuel

Ce concept a déjà été abordé ici. En clair le micro-programme d’un Arduino ou d’un ESP est stocké dans la puce elle même et il n’y a pas de concept de “processus” sur ce genre de device. Il n’est donc pas possible d’avoir une véritable sentinelle qui tourne ce genre d’objet pour déployer et superviser des packages Constellation à la volée comme sur un système Windows ou Linux.

C’est pour cela qu’on parle de sentinelle et de package “virtuel” : on déclare bien dans la configuration de notre Constellation une sentinelle (par exemple nommée “Arduino” et associée à un credential) et contenant un package (par exemple nommé  “TemperatureSensor”). Ce package peut être joint à des groupes et avoir des settings qui lui sont propres.

Dans le microprogramme téléversé sur votre Arduino/ESP vous allez vous connecter en spécifiant le nom de la sentinelle et du package virtuel (ici Arduino/TemperatureSensor) et la clé d’accès associée. Votre device sera alors connecté à Constellation comme étant le package “TemperatureSensor” sur la sentinelle “Arduino”. Comme n’importe quel package il pourra produire des logs, publier des StateObjects, récupérer ses settings, envoyer ou recevoir des messages ou encore consommer les StateObjects d’autres packages.

Techniquement parlant l’Arduino/ESP utilise l’API REST “Constellation”.

Installer la librairie Constellation dans l’IDE Arduino

Ouvrez le « Gestionnaire de bibliothèque » dans le menu « Croquis > Inclure une bibliothèque > Gérer les bibliothèques » :

Avec le moteur de recherche, recherchez le terme « ArduinoJson » :

Vous trouverez lors la bibliothèque « ArduinoJson » de Benoit Blanchon (dépendance de la librairie Constellation) ainsi que la librairie Constellation.

Pour ces deux bibliothèques, cliquez sur le bouton « Installer » (ou « Mise à jour » si la librairie est déjà installée).

Hello World, Hello Constellation

Commencez par créer un nouveau sketch et ajoutez la librairie Constellation :

#include <Constellation.h>

Vous pouvez maintenant déclarer le client “Constellation” en l’initialisant avec l’adresse (IP ou DNS) de votre serveur Constellation, le port et les informations de connexion de Constellation, c’est à dire le nom de votre sentinelle et package ainsi que la clé d’accès que vous aurez déclarés sur votre serveur :

Constellation<WiFiClient> constellation("IP or DNS du serveur constellation", 8088, "MyVirtualSentinel", "MyVirtualPackage", "123456789");

Pour ajouter une sentinelle virtuelle cliquez sur le bouton “Add sentinel” sur la page “Sentinels” de la Console Constellation :

Puis ajoutons un package virtuel en cliquant sur le bouton contextuel de notre sentinelle “Deploy package” ou directement depuis la package “Packages” :

Déclarez ensuite le nom de votre package, ici “MyVirtualPackage” utilisant la même clé que celle définie au niveau de la sentinelle :

Vous remarquerez que dans la déclaration du client Constellation nous avons spécifié dans le template de la classe Constellation le type de notre client réseau, qui dans le cas d’un ESP8266 ou d’un Arduino MKR1000 est “WifiClient”.

N’oubliez pas d’ajouter les librairies de votre client réseau, quelques exemples :

/* Arduino Wifi (ex: Wifi Shield) */
#include <SPI.h>
#include <WiFi.h>

/* Arduino Wifi101 (for WiFi Shield 101 and MKR1000 board) */
#include <SPI.h>
#include <WiFi101.h>

/* Arduino Ethernet */
#include <SPI.h>
#include <Ethernet.h>

/* ESP8266 Wifi */
#include <ESP8266WiFi.h>

Au démarrage du programme, nous allons d’abord connecter votre client réseau sur le réseau. Dans le cas d’un ESP8266, on se connecte au réseau Wifi de cette façon :

void setup(void) {
  Serial.begin(115200);

  // Connect to Wifi  
  WiFi.begin("MY-SSID", "MY-WIFI_KEY");  
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  // For WiFi101, wait 10 seconds for connection!
  // delay(10000);

  Serial.println("WiFi connected. IP: ");
  Serial.println(WiFi.localIP());
}

Une fois connecté au réseau, on peut utiliser les méthodes de la librairie Constellation.

Par exemple, produisons un log avec la méthode “WriteInfo” :

constellation.writeInfo("Hello Constellation");

Cette méthode gère nativement le formatage “à la printf”, par exemple :

constellation.writeInfo("Hello Constellation, I'm '%s !", constellation.getSentinelName());

Notez que vous pouvez produire de la même façon des messages de type “Info”, “Warning” ou “Error” :

constellation.writeInfo("This is an information"); 
constellation.writeWarn("This is a warning"); 
constellation.writeError("This is an error");

Bien entendu, comme n’importe quel package, les logs sont remontés en temps réel dans la Constellation ce qui permet à n’importe quel “contrôleur” de voir les logs de votre Arduino/ESP en temps réel.

Par exemple, en ouvrant la Console Constellation on pourra suivre votre Arduino/ESP en temps réel :

Accès aux settings

Tous les settings des packages de votre Constellation sont déclarés depuis le fichier de configuration de votre Constellation. Vous pouvez aussi utiliser la Console Constellation pour les administrer.

Dans votre code Arduino, vous devez utiliser la méthode “getSettings” pour récupérer un objet JSON contenant les settings (clé/valeur).

JsonObject& settings = constellation.getSettings();

Par exemple pour récupérer la valeur du setting “MonChiffre” déclarée sur le serveur à 42 :

JsonObject& settings = constellation.getSettings();
static int monChiffre= settings["MonChiffre"].as<int>()

La variable “monChiffre” sera donc affectée à la valeur “42”. Dans l’exemple ci-dessus, la variable est statique pour pouvoir être utilisée n’importe où dans votre code.

Pour les chaines de caractères vous pouvez utiliser la classe “String” :

JsonObject& settings = constellation.getSettings();
static String strMaChaine = String(settings["MaChaine"].as<char *>());

Encore une fois la variable est statique pour pouvoir l’utiliser n’importe où dans votre code.

Si vous devez convertir votre chaîne de caractères en const char *, vous pouvez utiliser la fonction c_str() :

const char* maChaine = strMaChaine.c_str();

Vous pouvez également tester la présence d’un setting avec la méthode « containsKey » :

if(settings.containsKey("MySetting")) {  
  // Do something with settings["MySetting"]  
}

Par exemple vous pouvez gérer les valeurs par défaut. Imaginez un code où la valeur d’un timeout est de 5 secondes par défaut mais vous vous laissez la possibilité de surcharger cette variable depuis les settings Constellation :

// Default value
int timeout = 5; // sec

setup() {
  // .....
  JsonObject& settings = constellation.getSettings();
  if(settings.containsKey("Timeout")) {  
    timeout = settings["Timeout"].as<int>();
  }
}

void loop() {
   // DO something with 'timeout'
}

Si le setting « Timeout » est défini dans les settings de votre package sur Constellation, la variable « timeout » sera affectée à votre valeur, autrement, si le setting n’existe pas, la valeur de cette variable sera de 5.

Publier des StateObjects

Pour produire et publier un StateObject dans votre Constellation vous devez invoquer la méthode “pushStateObject” :

constellation.pushStateObject(name, value);

Vous pouvez aussi passer le “type” de votre StateObject :

constellation.pushStateObject(name, value, type);

Notez que pour les types simples (int,bool, long, float et double) le type est spécifié implicitement.

Par exemple, pour publier un StateObject dont la valeur est un chiffre :

constellation.pushStateObject("Temperature", 21);

Vous pouvez aussi publier des StateObject avec un objet complexe en utilisant la fonction “stringFormat” pour formater votre valeur en JSON.

Par exemple pour publier un StateObject nommé “Lux” étant un objet contenant 3 propriétés :

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

Vous pouvez également faire la même chose en construisant un “JsonObject” :

StaticJsonBuffer<200> jsonBuffer;
JsonObject& root = jsonBuffer.createObject();

root["Lux"] = lux;
root["Broadband"] = full;
root["IR"] = ir;
constellation.pushStateObject("Lux", &root);

Une fois vos StateObjects publiés, ils sont accessibles en temps réel aux autres packages et consommateurs de votre Constellation. Vous pouvez également utiliser le “StateObject Explorer” de la Console Constellation pour explorer tous les StateObjects de votre Constellation :

Next steps

• Publier des StateObjects
• Envoyer des messages
• Recevoir des messages
• Consommer des StateObjects
• Connectez vos ESP8266 à Constellation en Lua avec NodeMCU

The post Connecter un Arduino ou un ESP8266 à Constellation appeared first on Constellation.

Pour produire et publier un StateObject dans votre Constellation vous devez invoquer la méthode “pushStateObject” en spécifiant au minimum le nom du StateObject et sa valeur :

constellation.pushStateObject(name, value);

Vous pouvez aussi spécifier “type” de votre StateObject :

constellation.pushStateObject(name, value, type);

Notez que pour les types simples (int,bool, long, float et double) le type est spécifié implicitement. Par exemple, pour publier un StateObject dont la valeur est un chiffre :

constellation.pushStateObject("Temperature", 21);

Vous pouvez aussi spécifier le “lifetime” de votre StateObject, c’est à dire sa durée de vie (en seconde) avant qu’il soit considéré comme “expiré”. Par exemple si votre valeur de T° (variable ‘temp’) est considérée comme valide que 60 secondes, on écrira :

constellation.pushStateObject("Temperature", temp, 60);

En ouvrant le “StateObject Explorer” de la Console Constellation vous retrouverez votre StateObject :

Si le StateObject n’est pas mis à jour dans les 60 secondes il sera marqué comme expiré.

Publication de valeur “complexe”

Avec un “string format”

Vous pouvez publier des StateObject avec un objet complexe en utilisant la fonction “stringFormat” pour formater votre valeur en JSON. Par exemple pour publier un StateObject nommé “Lux” étant un objet contenant 3 propriétés, on pourrait écrire :

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

Avec un JsonObject

Vous pouvez également faire la même chose en créant un JsonObject de la façon suivante :

StaticJsonBuffer<JSON_OBJECT_SIZE(3)> jsonBuffer;
JsonObject& myStateObject = jsonBuffer.createObject();
myStateObject["Lux"] = lux;
myStateObject["Broadband"] = full;
myStateObject["IR"] = ir;
constellation.pushStateObject("Lux", myStateObject);

Sur l’explorateur de StateObjects de la Console :

Définir la durée de vie de votre StateObject

Comme pour une valeur simple, vous pouvez également spécifier un “type” et le “lifetime” de votre StateObject. Par exemple :

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

Ou en utilisant le JsonObject “myStateObject” créé ci-dessus :

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

Dans les deux cas nous avons publié un StateObject nommé “DemoLux” de type “MyLuxData” avec une durée de vie de 20 secondes contenant comme valeur un objet avec trois propriétés (Lux, Broadband et IR).

Décrire ses types complexes

Lorsque vous utilisez des types personnalisés (ici “MyLuxData”) il vivement recommandé de les décrire dans le “Package Descriptor”.

Pour ce faire, au démarrage, invoquez la méthode “addStateObjectType” pour chaque type à déclarer puis appelez la méthode “declarePackageDescriptor” pour envoyer le “Package Descriptor” dans la Constellation.

Dans notre exemple nous écrirons :

// Describe your custom StateObject types  
constellation.addStateObjectType("MyLuxData", TypeDescriptor().setDescription("MyLuxData demo").addProperty("Broadband", "System.Int32").addProperty("IR", "System.Int32").addProperty("Lux", "System.Int32")); 

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

Vous remarquerez que le type “MyLuxData” est surligné vous permettant d’afficher le descriptif de votre StateObject :

Ajout de metadatas

Pour finir vous pouvez également ajouter des méta-données sur vos StateObjects.

Par exemple ajoutons l’ID de la puce ESP (ChipID) et le timestamp (millis) dans les méta-données de notre StateObject :

const int BUFFER_SIZE = JSON_OBJECT_SIZE(6);
StaticJsonBuffer<BUFFER_SIZE> jsonBuffer;
JsonObject& myStateObject = jsonBuffer.createObject();
myStateObject["Lux"] = lux;
myStateObject["Broadband"] = full;
myStateObject["IR"] = ir;
JsonObject& metadatas = jsonBuffer.createObject();
metadatas["ChipId"] = ESP.getChipId();
metadatas["Timestamp"] = millis();
constellation.pushStateObject("Lux", myStateObject, "MyLuxData", 20, &metadatas);

Note : dans ce dernier exemple vous remarquerez que nous avons défini la taille du buffer JSON (BUFFER_SIZE) à “JSON_OBJECT_SIZE(6)”, c’est à dire 6 propriétés et non 3 comme dans les exemples précédents de façon à tenir compte des propriétés JSON rajoutées par les metadatas (l’objet “Metadatas” lui même et ses deux propriétés “ChipId” et “Timestamp”). Pour plus d’info, consultez la documentation d’ArduinJson et plus particulièrement l’article concernant la gestion de la mémoire.

The post Produire des StateObjects depuis un Arduino/ESP 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.

Enregistrer un MessageCallback

Par exemple enregistrons un MessageCallback “HelloWorld” via une expression lambda C++ à l’initialisation de votre Arduino/ESP (c’est à dire dans la méthode setup()):

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

Enfin dans la boucle principal (loop), invoquez la méthode “constellation.loop” pour traiter et dispatcher les messages reçu par votre package virtuel :

constellation.loop();

Dès lors que votre Arduino/ESP recevra un message dont la clé (MessageKey) est “HelloWorld”, votre méthode associée (représentée ci-dessus par une lambda) sera invoquée.

Décrire son MessageCallback

Le MessageCallback enregistré ci-dessus est dit “caché”, car il n’est pas référencé sur Constellation ! Vous pouvez bien sur envoyer un message “HelloWorld” à votre package pour invoquer votre fonction lambda mais cela suppose que vous connaissez par avance que votre package a enregistré le MessageCallback ci-dessus nommé “HelloWorld”.

Pour enregistrer ET déclarer un MessageCallback vous devez ajouter un “MessageCallbackDescriptor” dans les arguments de la méthode. Par exemple pour reprendre notre exemple “HelloWorld” :

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

On a ici ajouté un “MessageCallbackDescriptor” en spécifiant la description de notre MC. Pour que la description du MC soit envoyée à Constellation, vous devez nécessairement publier le “Package Descriptor” à la fin de l’initialisation de votre Arduino/ESP par la ligne :

constellation.declarePackageDescriptor();

Maintenant, depuis la Console Constellation, ouvrez le “MessageCallback Explorer” et vous retrouvez un MC nommé “HelloWorld” pour votre package :

Vous pouvez cliquer sur le bouton “Invoke” pour envoyer un message “HelloWorld” au package “MyVirtualPackage” et donc invoquer le code de la lambda.

On retrouvera donc dans la Console Log Constellation un “Hello Constellation” tel que programmé dans la lambda (via un constellation.writeInfo)  :

Récupérer le contexte

Vous pouvez également récupérer le contexte de réception du message dans la fonction liée en ajoutant un argument « MessageContext » dans la signature du callback :

(*)(JsonObject&, MessageContext);

Le type “MessageContext” décrit de la façon suivante :

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

Avec :

enum SenderType : uint8_t {
   ConsumerHub = 0,
   ConsumerHttp = 1,
   ConstellationHub = 2,
   ConstellationHttp = 3
};

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

Ainsi vous pouvez obtenir des informations sur le contexte de réception du message à savoir :

• Si le message est dans une saga, si oui obtenir l’identifiant de la saga
• Connaitre le scope dans lequel a été envoyé le message
• Connaitre l’émetteur du message (ID de connexion, friendly name, …)

Par exemple, pour afficher le nom de l’émetteur (son FriendlyName) nous pourrions écrire :

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

En invoquant le MC depuis le “MessageCallback Explorer” en étant connecté sous l’utilisateur “seb”, nous obtiendrons dans les logs :

[MyVirtualSentinel/MyVirtualPackage] 17:28:41 : Hello Consumer/ControlCenter:seb from Constellation !

Décrire les paramètres de vos MessageCallbacks

Dans la philosophie des MessageCallbacks Constellation, un MessageCallback sert à invoquer des méthodes où la clé du message (MessageKey) est comme le nom d’une méthode.

Pour passer des paramètres à ces méthodes, on utilisera le contenu du message (Data).

Paramètres de types simples

Imaginez vouloir exposer une méthode “SayHello” qui prend en paramètre deux chaines de paramètres (= des types simples), le nom et prénom pour les afficher dans les logs.

On déclarera le MessageCallback suivant :

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].as<char *>(), json["Data"][1].as<char *>()); 
 });

On a ajouté deux paramètres de type “String” dans le MessageCallbackDescriptor via la méthode “addParameter”. Dans le code de notre MessageCallback, nous exploitons les valeurs des paramètres via la propriété “Data” de notre message “json”.

Le 1er paramètre (json[« Data »][0]) étant ici le “FirstName” d’après la description et le 2ème (json[« Data »][1]) le “LastName”.

Attention :

• lorsque plusieurs paramètres sont passés comme dans l’exemple ci-dessus, la propriété “Data” est un tableau contenant la valeur de chaque argument (ici [0] est “FirstName” et [1] le “LastName”)
• Si un seul paramètre est passé dans votre MC, la propriété “Data” est la valeur de l’argument directement et non un tableau.

Vous pouvez tester votre MC depuis le “MessageCallback Explorer” :

Bien entendu vous pouvez déclarer un ou plusieurs paramètres de type différent.

Les types de base sont :

• System.String
• System.Char
• System.Boolean
• System.Int16
• System.Int32
• System.Int64
• System.Double
• System.Decimal
• System.Float

Pour simplifier l’enregistrement des paramètres de type de base, vous pouvez les déclarer en utilisant la forme générique.

Par exemple pour un paramètre de type “String” on écrira :

addParameter<const char*>("FirstName")

Autre exemple pour ajouter des paramètres de type “Boolean” et “Int32” :

addParameter<bool>("IsEnable")
addParameter<int>("MyNumber")

De ce fait notre MC “SayHello” pourrait s’écrire :

constellation.registerMessageCallback("SayHello",
  MessageCallbackDescriptor().setDescription("Say hello !").addParameter<const char*>("FirstName").addParameter<const char*>("LastName"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello %s %s", json["Data"][0].as<char *>(), json["Data"][1].as<char *>()); 
 });

Paramètre de types complexes

Il est également possible de spécifier des objets complexes contenant des propriétés.

Reprenons l’exemple précédent “SayHello” sauf qu’au lieu de passer deux paramètres de type “simple”, passons qu’un seul paramètre : un objet contenant deux propriétés (LastName et FirstName).

constellation.registerMessageCallback("SayHello",
  MessageCallbackDescriptor().setDescription("Say hello with complex object!").addParameter("User", "SampleUserData"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello %s %s", json["Data"]["FirstName"].as<char *>(), json["Data"]["LastName"].as<char *>());
});

Dans le MessageCallbackDescriptor de notre MessageCallback nous déclarons qu’un seul paramètre nommé “User” et de type “SampleUserData”.

Au niveau du code de notre MessageCallback, nous récupérons nos deux valeurs via le 1èr et unique paramètre (json[« Data »]) en accédant à la propriété “FirstName” et “LastName”.

Bien entendu pour que cela fonctionne il faut déclarer le type “SampleUserData” via la méthode “addMessageCallbackType” :

constellation.addMessageCallbackType("SampleUserData", TypeDescriptor().setDescription("This is a smaple user data").addProperty<const char*>("FirstName").addProperty<const char*>("LastName");

Il n’y a donc plus maintenant qu’un seul paramètre, un objet complexe contenant deux propriétés de type “string”. Vous pouvez d’ailleurs cliquez sur le type “SampleUserData” pour afficher sa description :

Noter que vous pouvez enregistrer et déclarer des MessagesCallbacks mixant paramètre simple et paramètre complexe :

constellation.registerMessageCallback("MultipleParameters",
  MessageCallbackDescriptor().setDescription("Mixte de parametre simple & complexe").addParameter("User", "SampleUserData").addParameter<const char*>("Password"),
  [](JsonObject& json) {
    // json["Data"][0] is SampleUserData
    // json["Data"][1] is String
});

Exposer des MessageCallbacks avec réponse : les sagas

Pour finir un MessageCallback peut retourner un message de réponse, c’est ce que l’on appelle les sagas. C’est un peu comme une méthode en programmation, elle peut être “procédure” (sans retour, un void) ou “fonction” (retourne un type simple ou complexe).

Votre Arduino/ESP peut également enregistrer des MC retournant une réponse. Pour cela deux choses sont nécessaire :

• Appeler la méthode “sendReponse” dans votre callback pour envoyer la réponse
• Appeler la méthode “setReturnType” sur le MessageCallbackDescriptor de votre MC pour déclarer le type de retour

Par exemple exposons un MessageCallback “Addition” pour réaliser des additions sur un Arduino/ESP. Ce MessageCallback prend en paramètre deux entiers et retourne le résultat de type entier (Int32) également :

constellation.registerMessageCallback("Addition",
  MessageCallbackDescriptor().setDescription("Do addition on this tiny device").addParameter<int>("a").addParameter<int>("b").setReturnType<int>(),
  [](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 !");
    }
 });

Pour retourner une réponse vous devez disposer du contexte de réception du message (le “MessageContext”). Vous noterez qu’ici, nous testons que le message appartient bien à une saga afin de renvoyer la réponse car il ne sert à rien d’envoyer une réponse sans saga, il ne sera jamais reçu par l’émetteur.

En déclarant le type de retour (ici un Int32), le MessageCallback Explorer reconnait ce MC comme une saga. Vous pouvez donc envoyer le message dans une saga (c’est à dire avec un identifiant de Saga) ou non grâce à la case à cocher :

Si le message est envoyé dans une saga, notre code Arduino ci-dessus retournera une réponse, ici à la Console Constellation :

La Console Constellation vous présentera ici toutes informations quant à la réponse et au message initial.  On retrouve ici la réponse de notre addition :

Dans la Console Log, on retrouvera bien les logs produits par notre Arduino :

Vous pouvez également rejouer ce test mais cette fois ci en décochant la case “With Saga”, c’est à dire que nous invoquons le MC “Addition” sans n° de saga :

Dans la Console Log, notre Arduino réalise bien l’addition mais ne retourne pas de message de réponse car il ne dispose pas de n° de saga pour répondre :

Recevoir tous les messages dans une méthode

Vous pouvez aussi “attraper” tous les messages que votre package virtuel reçoit en définissant un “callback”, c’est à dire une fonction prenant en paramètre le message sous forme d’un JsonObject et qui sera appelée à chaque message reçu.

Par exemple, écrivez la méthode suivante pour afficher le “MessageKey” de chaque message reçu (si nécessaire n’hésitez pas à lire ou relire les fondamentaux du Messaging Constellation) :

void messageReceive(JsonObject& json) {
  Serial.print("MSG RCV : ");
  Serial.println(json["Key"].as<char *>());
}

Au “setup”, attachez cette méthode à la réception des messages (setMessageReceiveCallback) et abonnez-vous à la réception des messages (subscribeToMessage) :

constellation.setMessageReceiveCallback(messageReceive); 
constellation.subscribeToMessage();

Avec les expression lambda en C++, vous auriez pu aussi écrire directement :

constellation.setMessageReceiveCallback([](JsonObject& json) { 
  constellation.writeInfo("Message received ! Message key = %s", json["Key"].as<char *>());     
});
constellation.subscribeToMessage();

Enfin dans la boucle principal (loop), invoquez la méthode “constellation.loop” pour traiter et dispatcher les messages reçu par votre package virtuel :

constellation.loop();

Par exemple, imaginez un ESP8266 avec 2 MessageCallbacks : “Restart” sans paramètre qui redémarre l’ESP et “SendCode” avec un objet JSON en paramètre pour envoyer un signal infrarouge.

Le code pourrait être :

constellation.setMessageReceiveCallback([](JsonObject& json) { 
  Serial.print("Message receive : ");
  const char * key = json["Key"].as<char *>();  
  if (stricmp (key, "SendCode") == 0) {

    const char * encoder = json["Data"]["Encoding"].as<char *>();  
    unsigned long code = strtoul(json["Data"]["Code"].as<char *>(), NULL, 0);

    // TODO : send the IR signal "code"

    else {
      constellation.writeInfo("Unable to send IR code : encoding '%s' not found !", encoder); 
    }    
    irrecv.enableIRIn();
  }
  else if (stricmp (key, "Restart") == 0) {
    ESP.restart();
  }
});  
constellation.subscribeToMessage();

Avec cette façon de faire, votre “MessageReceiveCallback” est invoqué à chaque message reçu mais c’est à vous de “dispatcher” les messages en fonction de leur “MessageKey”.

De plus côté Constellation, il n’y a aucun “Message Callback” déclaré sur Constellation, c’est a vous de connaitre les “MessageKey” que votre package virtuel acceptent, ici “SendCode” et “Restart” !

Obtenir contexte de réception

Comme pour l’enregistrement d’un MessageCallback, vous pouvez ajouter un 2ème argument de type MessageContext pour récupérer le contexte de réception du message.

Par exemple nous pourrions écrire très simplement :

constellation.setMessageReceiveCallback([](JsonObject& json, MessageContext ctx) { 
  constellation.writeInfo("Message receive from %s. Message key = %s", ctx.sender.friendlyName, json["Key"].as<char *>());  
});  
constellation.subscribeToMessage();

S’abonner à un groupe Constellation

Jusqu’a présent votre package virtuel recevra les messages :

• Du Scope “All” (c’est à dire tout le monde connecté à Constellation)
• Du Scope “Others” si votre package n’est pas l’émetteur du message
• Du Scope de votre sentinelle
• Du Scope de votre package

Si nécessaire n’hésitez pas à lire ou relire les fondamentaux du Messaging Constellation.

Vous pouvez également vous abonner à des groupes pour recevoir les messages qui seraient envoyés dans ces groupes.

Pour cela il suffit d’invoquer la méthode “subscribeToGroup” en spécifiant le nom du groupe à joindre. Exemple :

constellation.subscribeToGroup("MonGroupe");

Noter cependant que l’appartenance d’un package, virtuel ou non, à un groupe peut être défini au niveau de la configuration de la Constellation éditable simplement via la Console Constellation afin de pouvoir faire évoluer ces appartenances à la volée sans devoir reprogrammer vos Arduino/ESP.

The post MessageCallback : exposer des méthodes et recevoir des messages sur un Arduino/ESP appeared first on Constellation.

Pour récupérer un ou plusieurs StateObject (à un instant T), vous pouvez utiliser la méthode “requestStateObjects” :

JsonArray& myStateObject = constellation.requestStateObjects(sentinel, package, name, type);

Utilisez le wildcard “” pour ne pas appliquer de filtre. Le symbole “” est aussi accessible via la constante “WILDCARD”.

Par exemple :

// All StateObjects for MyPackage on MySentinel
JsonArray& so = constellation.requestStateObjects("MySentinel", "MyPackage", "*", "*");
// All StateObjects named "Demo" in your Constellation
JsonArray& so = constellation.requestStateObjects(WILDCARD, WILDCARD, "Demo", WILDCARD);

Autre exemple, vous souhaitez afficher dans les logs Constellation, la consommation CPU de toutes vos machines Windows (vous avez au préalable déployé le package “HWMonitor” sur toutes vos sentinelles Windows) depuis votre Arduino :

// 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"].as<char *>(), cpus[i]["Value"]["Value"].as<float>());
}

S’abonner aux mises à jours des StateObjects en temps réel

Vous pouvez également vous abonnez aux mises à jour des StateObjects pour être notifié en temps réel de la modification des StateObjects.

En utilisant un callback global

Vous pouvez déclarer une fonction callback qui sera appelée à chaque mise à jour de StateObjects pour lesquels vous vous êtes abonné en invoquant la méthode setStateObjectUpdateCallback. Notez qu’il ne peut y avoir qu’une seule méthode callback enregistrée.

Ensuite vous abonnez aux différents StateObjects que vous souhaitez “suivre” avec la méthode “subscribeToStateObjects”.

Par exemple, pour être notifié en temps réel de la consommation CPU des différentes sentinelles Windows, on écrira :

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

Nous avons ici défini notre fonction callback dans une expression lambda mais vous pouvez aussi bien “extraire” cette fonction callback dans une fonction distincte.

Enfin dans la boucle principale (loop), vous devez invoquer la méthode “constellation.loop()” aussi souvent que possible afin que la libraire puisse dispatcher les SO dans votre méthode callback :

constellation.loop();

En utilisant des StateObjectLinks

Avec la méthode “subscribeToStateObjects” présentée ci-dessous vous avez une fonction callback qui recevra tous les StateObjects pour lesquels vous êtes abonné. Vous devez donc “dispatcher” vous même les différents StateObjects que vous recevrez.

Pour simplifier les choses, la libraire Arduino propose comme en .NET ou en Python, la notion de StateObjectLink : il s’agit de “lier” un abonnement à des StateObjects à une fonction de votre code.

Pour reprendre l’exemple du suivi des CPU en temps réel, nous pourrions écrire :

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

Vous pouvez enregistrer autant de StateObjectLink que vous le désirez. Là encore nous utilisé une expression lambda mais vous pouvez aussi bien “extraire” cette fonction callback dans une fonction distincte.

N’oubliez pas non plus d’appeler la méthode constellation.loop()” aussi souvent que possible dans la boucle principale de votre programme.

The post Consommer des StateObjects depuis un Arduino/ESP appeared first on Constellation.

Développer des applications natives sur ESP peut être assez compliqué pour celui qui ne connait pas le développement bas niveau !

NodeMCU a eu l’idée de créer un firmware ESP8266 embarquant eLua, un interpréteur Lua très minimaliste pour système embarqué. Grace à ce firmware vous pouvez développer des programmes pour votre ESP très facilement en Lua.

Concrètement il faut commencer par flasher votre ESP avec le firmware NodeMCU en utilisant un outil comme ESP Flash Download (voir ici). Vous pouvez télécharger le firmware directement sur le GitHub de NodeMCU ou bien sur http://nodemcu-build.com/  pour compiler son firmware à la demande en personnalisant différentes options (branche à compiler, modules à inclure, support ou non du SSL, activation du mode debug, etc..).

Une fois installé utilisez l’outil Esplorer, une application Java (compatible Linux/Windows et Mac OS) pour éditer les scripts Lua directement depuis le système de fichier de votre ESP.

A gauche vous retrouverez l’éditeur, à droite la sortie de votre ESP. Chaque fichier est enregistré dans le système de fichier de votre ESP avant d’être exécuté.

Par exemple pour se connecter au Wifi :

print("Démarrage")
wifi.setmode(wifi.STATION)
print("set mode=STATION (mode="..wifi.getmode()..")")
wifi.sta.config{ssid="MON RESEAU WIFI", pwd="Ma clé Wifi"}

tmr.alarm(0, 1000, 1, function()
   if wifi.sta.getip() == nil then
      print("Connecting to AP...")
   else
      print("Connected! IP: ",wifi.sta.getip())
      tmr.stop(0)
   end
end)

On commence par définir le mode Wifi à Station (client) puis on se connecte en spécifiant le SSID et la clé Wifi. Ensuite on lance une tache qu’on exécute sur le timer « 0 » (vous pouvez aller de 0 à 6), à une seconde d’intervalle (1000ms) de façon répétitive afin de récupérer l’IP. Si la connexion n’est pas encore effective on affiche le message « Connecting » sinon on coupe le timer « 0 » et on affiche l’adresse IP de votre ESP.

Pour plus d’information je vous invite à lire ou relire cet article : http://sebastien.warin.fr/2016/07/12/4138-decouverte-des-esp8266-le-microcontroleur-connecte-par-wifi-pour-2-au-potentiel-phenomenal-avec-constellation/

Connexion à Constellation

Commencez tout d’abord par télécharger la librairie “Constellation pour NodeMCU” et transférez les fichiers du fichier ZIP sur votre ESP avec Esplorer.

Créez ensuite un script Lua en incluant cette librairie afin d’initialiser le client Constellation avec l’adresse du serveur, votre Sentinelle & package virtuel ainsi que la clé d’accès :

local constellation = require("constellation")
constellation.init("constellation.monserveur.com", 8088, "MyVirtualSentinel", "MyVirtualPackage", "123456789")

Fonctionnalités de base

Vous pouvez écrire dans les logs Constellation grâce à la méthode “writeLog”. Par exemple :

constellation.writeLog("Je suis pret avec " .. node.heap())

Par défaut les logs sont envoyés comme “Information”, mais vous pouvez spécifier “Warn” ou “Error” dans le 2ème arguments de cette méthode :

constellation.writeLog("Ceci est un warning", "Warn")
constellation.writeLog("Ceci est une erreur", "Error")

Vous pouvez également récupérer les settings de votre package virtuel du serveur Constellation avec la méthode “getSettings” :

constellation.getSettings(function(messages)
      print("Settings received :")
      for k,v in pairs(messages) do
          print(" -> " .. k .. " = " .. v)
      end        
  end)

Publier des StateObjects

Pour publier un StateObject, vous disposez de la méthode “push” prenant en paramètre le nom et la valeur. Dans la version 1.0 le “lifetime”, “type” ou les “métadatas” ne sont pas supportés.

Vous pouvez publier soit des types simples, par exemple :

constellation.push("Lux", math.floor(lux))

Soit des types complexes, c’est à dire des objets formatés en JSON. Vous pouvez formater vous même vos objets par concaténation :

constellation.push("Lux", "{ Broadband:" .. broadband .. ", IR:" .. ir .. ", Lux:" .. math.floor(lux) .. "}")

Ou bien via le module Lua “cjson” :

constellation.push("Lux", cjson.encode({ Broadband=broadband, IR=ir, Lux= math.floor(lux) }))

Recevoir des messages

Vous pouvez également recevoir des messages sur votre ESP8266 en enregistrant une fonction “callback” qui sera invoquée à chaque message reçu.

Par exemple :

constellation.subscribeToMessage(function(message)
    print(message["Sender"]["FriendlyName"], message["Key"], message["Data"][2])  
    if message["Key"] == "Restart" then
        node.restart()
    end        
end)

Dans cette première version de la librairie la description des messages callback (Package Descriptor) n’est pas supportée.

The post Utiliser Lua sur NodeMCU pour connecter des ESP8266 à Constellation appeared first on Constellation.