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.

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.

Un consommateur peut :

• Consommer des StateObjects (Request ou Subscribe)
• Envoyer ou recevoir des messages

Généralités

Construction de l’URL

L’URL est :  <Root URI>/rest/consumer/<action>?<paramètres>

Partons du principe que votre Constellation est exposée en HTTP sur le port 8088 (sans path). On retrouvera dans le fichier de configuration la section suivante :

<listenUris>
  <uri listenUri="http://+:8088/" />
</listenUris>

La “Root URI “ est donc “http://<ip ou dns>:8088/”.

Par exemple si nous sommes en local, nous pourrions écrire :

http://localhost:8088/rest/consumer/xxxxx

Authentification

Comme pour toutes les requêtes vers Constellation vous devez impérativement spécifier dans les headers HTTP ou dans les paramètres de l’URL (querystring), les paramètres “SentinelName”, “PackageName” et “AccessKey” pour l’authentification.

Dans le cas de l’API “Consumer”, la “SentinelName” est “Consumer” et le “PackageName” est le nom de votre choix que l’on considère comme un “FriendlyName”. Typiquement le “FriendlyName” est par exemple le nom de l’application/page qui se connecte.

L’AccessKey doit bien sur être déclarée et activée sur le serveur.

Ainsi chaque appel sera sous la forme :

http://localhost:8088/rest/consumer/<action>?SentinelName=Consumer&PackageName=<Friendly name>&AccessKey=<access key>&<paramètres>

Check Access

Toutes les API REST de Constellation exposent une méthode en GET “CheckAccess” qui retourne un code HTTP 200 (OK). Cela permet de tester la connexion et l’authentification au serveur Constellation.

• Action : “CheckAccess” (GET)
• Paramètres : aucun

Exemple :

http://localhost:8088/rest/consumer/CheckAccess?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123

Envoyer des messages

• Action : “SendMessage” (GET ou POST)
• En GET, voici les paramètres de l’URL :
  • scope : le type de scope (All, Other, Group, Sentinel ou Package)
  • args : les arguments du scope (par exemple le nom du groupe, de la sentinelle, du package ou de l’instance du package – plusieurs valeurs possibles séparées par des virgules)
  • key : la clé du message (= la méthode à invoquer)
  • data : le contenu du message (= les arguments de la méthode)
  • sagaId (optionnel) : l’identification de la saga si le message est envoyé dans une saga

Vous pouvez également invoquer cette action en POST. Le corps de votre requête contiendra l’objet JSON suivant :

{
  "Scope" : { "Scope" : "<type>", Args: [ "<arg1>", "<args2>", .... ], "SagaId":"Identifiant de la Saga" },
  "Key" : "<Key>",
  "Data" : "<Data>"
}

La propriété “SagaId” dans le JSON ci-dessus est optionnelle.

Par exemple pour envoyer un message au package Nest en invoquant la méthode (key) “SetTargetTemperature” avec en paramètre le nombre “21” :

http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=Nest&key=SetTargetTemperature&data=21

Par exemple pour invoquer ce MessageCallback depuis cURL :

curl "http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=Nest&key=SetTargetTemperature&data=21"

Ce même MessageCallback “SetTargetTemperature” du package Nest peut être invoqué dans une saga afin de recevoir un un accusé de réception :

http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=Nest&key=SetTargetTemperature&data=21&sagaId=123456789

Il faudra ensuite “récupérer” les messages reçus (voir dessous) pour lire la réponse à votre saga que nous avons ici identifié par la clé “123456789”.

Autre exemple avec un MessageCallback avec plusieurs paramètres :

http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=MyPackage&key=MethodeAvec3Params&data=[ 'param 1', 123, true ]

Attention le contenu du paramètre « args » doit être encodé. De ce fait, avec cURL :

curl "http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=MyPackage&key=MethodeAvec3Params&data=%5B+%27param+1%27%2C+123%2C+true+%5D"

Pour invoquer ce même MC avec un « POST » depuis cURL :

curl -H "Content-Type: application/json" -X POST -i -d '{ "Scope" : { "Scope" : "Package", Args: [ "MyPackage"] }, "Key" : "MethodeAvec3Params", "Data" : [ "param 1", 123, true ] }' "http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123"

Recevoir des messages

Créer un abonnement de réception

Tout d’abord pour recevoir des messages il faut s’abonner aux messages.

• Action : “SubscribeToMessage” (GET)
• Paramètres :
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu

http://localhost:8088/rest/consumer/SubscribeToMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123

Vous obtiendrez en réponse l’ID de votre abonnement, le “Subscription Id”.

Relever les messages

• Action : “GetMessages” (GET)
• Paramètres :
  • subscriptionId : identifiant de l’abonnement
  • timeout (optionnel – par défaut 60000) : temps maximal en milliseconde de la mise en attente de la requête (entre 1000ms et 120000ms)
  • limit (optionnel – par défaut 0) : nombre maximum de message à retourner pour l’appel

Il s’agit d’une requête en “long-polling” c’est à dire que la requête sera “bloquée” sur le serveur tant qu’il n’y a pas de message reçu évitant ainsi de “flooder” en continue le serveur pour savoir si de nouveaux messages sont disponibles ou non. Par défaut la requête est bloquée 60 secondes maximum mais vous pouvez personnaliser cette valeur avec le paramètre “timeout”. Si il y a des messages disponibles, le serveur vous renvoi un tableau JSON avec les messages reçus. Si il n’y a pas de réponse dans le délai spécifié par le paramètre “timeout” (60 secondes par défaut), le tableau retourné sera vide.

A chaque réponse vous devez donc relancer une requête “GetMessages” pour “écouter” les prochains messages qui vont sont destinés.

Il est également possible de limiter le nombre de message dans la réponse avec le paramètre “limit” ce qui peut être utile sur de petits “devices” ne disposant pas de beaucoup de mémoire RAM pour désérialiser de gros tableaux JSON.

Exemple simple :

http://localhost:8088/rest/consumer/GetMessages?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx

Autre exemple en limitant le nombre de message à 2 par appel et en bloquant la requête pendant 10 secondes au maximum :

http://localhost:8088/rest/consumer/GetMessages?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx&timeout=10000&limit=2

S’abonner à un groupe

Vous pouvez vous abonner à des groupes pour recevoir les messages envoyés dans ces groupes par l’action “SubscribeToMessageGroup” en précisant le nom du groupe et votre ID d’abonnement.

• Action : “SubscribeToMessageGroup” (GET)
• Paramètres :
  • group : le nom du groupe à joindre
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu

http://localhost:8088/rest/consumer/SubscribeToMessageGroup?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx&group=A

Comme l’action “SubscribeToMessage”, cette action vous retourne l’ID d’abonnement à utiliser pour l’action “GetMessages”.

Consommation de StateObjects

Request

Cette méthode permet de récupérer la valeur actuelle d’un ou de plusieurs StateObjects.

• Action : “RequestStateObjects” (GET)
• Paramètres :
  • sentinel (optionnel – par défaut “*”): nom de la sentinelle
  • package (optionnel – par défaut “*”) : nom du package
  • name (optionnel – par défaut “*”) : nom du StateObject
  • type (optionnel – par défaut “*”) : type du StateObject

Par exemple pour récupérer tous les StateObject de votre Constellation :

http://localhost:8088/rest/consumer/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123

Ou seulement ceux produits par le package “HWMonitor” (quelque soit la sentinelle) :

http://localhost:8088/rest/consumer/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&package=HWMonitor

Ou encore tous les StateObjects nommés “/intelcpu/load/0” et produits le package “HWMonitor” (quelque soit la sentinelle) :

http://localhost:8088/rest/consumer/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&package=HWMonitor&name=/intelcpu/load/0

Subscribe

Vous pouvez également vous abonner aux mises à jour des StateObjects.

Le principe est le même qu’avec les messages : il faut récupérer un ID d’abonnement et invoquer une méthode en long-polling pour recevoir les mises à jour.

S’abonner à des StateObjects

• Action : “SubscribeToStateObjects” (GET)
• Paramètres :
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu
  • sentinel (optionnel – par défaut “*”): nom de la sentinelle
  • package (optionnel – par défaut “*”) : nom du package
  • name (optionnel – par défaut “*”) : nom du StateObject
  • type (optionnel – par défaut “*”) : type du StateObject

En retour vous obtiendrez l’ID d’abonnement (un GUID).

Par exemple pour s’abonner au SO “/intelcpu/load/0”, produit le package “HWMonitor” sur la sentinelle “MON-PC” :

http://localhost:8088/rest/consumer/SubscribeToStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&sentinel=MON-PC&package=HWMonitor&name=/intelcpu/load/0

ATTENTION : si vous souhaitez “ajouter” des SO à votre abonnement vous devez impérativement préciser votre ID d’abonnement récupéré lors du 1er appel autrement vous allez créer un nouvel abonnement.

Par exemple pour “ajouter” le SO correspondant à la consommation RAM :

http://localhost:8088/rest/consumer/SubscribeToStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&sentinel=MON-PC&package=HWMonitor&name=/ram/load&subscriptionId=<subId>

Relever les StateObjects mis à jour

Pour récupérer les SO de votre abonnement qui ont changés entre deux appels vous devez invoquer l’action “GetStateObjects” en spécifiant l’ID de votre abonnement :

• Action : “GetStateObjects” (GET)
• Paramètres :
  • subscriptionId : identifiant de l’abonnement
  • timeout (optionnel – par défaut 60000) : temps maximal en milliseconde de la mise en attente de la requête (entre 1000ms et 120000ms)
  • limit (optionnel – par défaut 0) : nombre maximum de message à retourner pour l’appel

Comme pour les message, vous pouvez limiter le nombre de SO (limit) et le timeout de la requête (timeout).

http://localhost:8088/rest/consumer/GetStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=<subId>

Notez que si un StateObject pour lequel vous êtes abonné change plusieurs fois entre deux appels “GetStateObjects”, vous obtiendrez la dernière valeur et non l’historique de tous les changements.

The post L’interface REST « Consumer » appeared first on Constellation.