Découvrons dans cet article comment créer et déployer votre premier package Constellation en Python.

Prérequis

Tout d’abord, que vous soyez sur Windows ou Linux, il vous faudra un interpréteur Python 2 ou Python 3 et une ou deux libraires indispensables pour Constellation.

Notez que ces prérequis sont automatiquement installés sur Linux avec le Web Platform Installer.

Installer Python sur Windows

Téléchargez Python pour Windows (en version 2.x ou 3.x) puis lancez l’installation en choisissant une installation pour tous les utilisateurs :

Sélectionnez le composant “PIP” ( le gestionnaire de package Python) et ajoutez “Python.exe” dans les “Paths” Windows :

Une fois l’installation terminée, lancez une invite de commande (cmd.exe) et assurez-vous que la commande “python” fonctionne :

Toujours dans une invite de commande Windows, installez via PIP les librairies “pyzmq” (et “enum34” si vous êtes en Python 2.x) grâce aux commandes suivantes :

pip install pyzmq
pip install enum34

Si vous êtes sur Python 3.x, vous n’avez pas besoin du module “enum34”, seulement “pyzmq”.

Et voilà, votre environnement Windows est prêt !

Installer Python sur Linux

Sur un système Debian ou similaire (Raspbian, Ubuntu, etc …), vous n’avez qu’à installer (et enregistrer dans votre Constellation) une sentinelle Constellation.

Le Web Platform Installer vous proposera d’installer tous les prérequis nécessaires à savoir Python et les librairies “pyZmq” et “enum34” (si Python 2.x) via PIP.

Autrement, pour installer manuellement ces prérequis, vous pouvez utiliser les mêmes commandes que sur Windows :

sudo easy_install pip
sudo pip install pyzmq
sudo pip install enum34

Encore une fois, la libraire “enum34” est seulement requise sur Python 2.x.

Enfin si vous utilisez un Raspberry Pi, vous pouvez également consulter cet article en particulier.

Et voilà, votre environnement Linux est prêt !

Développer un package Python en ligne de commande

Vous pouvez soit utiliser le SDK Constellation basé sur Visual Studio pour créer, tester et déployer des packages Constellation (.NET ou Python) ou bien, utiliser l’outil en ligne de commande nommé « Constellation Package Tools CLI ».

Le développement sous Visual Studio est abordé ci-dessous. Pour l’outil en ligne de commande, rendez-vous sur la page : Créer, tester et déployer des packages Python en ligne de commande

Développer un package Python avec Visual Studio

Après avoir installé les prérequis et le SDK Constellation, lancez Visual Studio et créez un nouveau package Constellation de type “Python” :

Une fois créé le projet Visual Studio a la structure suivante :

Vous retrouverez une structure classique pour un package Constellation :

• App.config : le fichier de configuration local pour définir les valeurs locales de vos settings (lire ici) ainsi que les scripts Python à démarrer
• PackageInfo.xml : le manifeste de votre package
• packages.config : le fichier des packages Nuget de votre projet (réservé à Nuget)
• Program.cs : le point d’entrée (C#) de votre package qui se chargera de lancer le “Python Proxy” (le pont entre vos scripts Python et Constellation)
• Le répertoire “Scripts” (qui contient vos scripts Python)
  • Constellation.py : le proxy Python Constellation (la librairie Python) : ne pas modifier !
  • Demo.py : un script Python d’exemple

Configurer les scripts à démarrer

Vous pouvez ajouter autant de scripts Python dans le dossier “Scripts” comme vous le souhaitez. Pour cela, cliquez-droit sur ce répertoire et sélectionnez « Ajouter un nouvel élément ».

Dans la catégorie « Constellation » sélectionnez « Constellation Python Script » :

Chaque script sera démarré dans un processus dédié et connecté à Constellation.

Attention : si vous rajoutez des scripts Python dans ce dossier, il faut obligatoirement les inclure dans le package en sélectionnant “Copy if newer” pour la propriété “Copy to Output directory”. Cette propriété est automatiquement définie à cette valeur si vous avez créé votre fichier Python en sélectionnant l’élément « Constellation Python Script » comme expliqué ci-dessus.

Dans le fichier « App.config » vous devez déclarer les fichiers Python à démarrer. Les scripts Python créé en sélectionnant l’élément « Constellation Python Script » sont automatiquement ajoutés dans ce fichier lors de la création. Si vous renommez ou supprimer vos scripts, n’oubliez pas de mettre à jour ce fichier.

<pythonProxy xmlns="urn:Constellation.PythonProxy">
  <scripts>
    <script filename="Scripts\Demo.py" />
    <script filename="Scripts\LightSensor.py" />
    <script filename="Scripts\Camera.py" />
  </scripts>
</pythonProxy>

Le script “Demo.py” est créé à titre d’exemple. Vous pouvez le supprimer, renommer ou modifier à votre convenance.

Grâce à Visual Studio et au SDK Constellation, vous bénéficiez d’un environnement de développement agréable pour créer vos packages Python avec la coloration syntaxique et l’IntelliSense :

Les bases

Chaque script Python doit impérativement importer la librairie Constellation et démarrer la “connexion” avec le proxy Python en invoquant la méthode “Start” :

import Constellation
# Votre code !
Constellation.Start()

Vous avez trois façon de démarrer cette connexion :

1 – La plus simple est d’invoquer la méthode “Start” :

Constellation.Start()

La méthode “Start” démarre la connexion et maintient le script en “vie” grâce à une boucle qui tourne tant que le package Constellation est lancé.

Autrement dit le code après la méthode “Start” ne sera jamais appelé !

2 – Invoquer la méthode “Start” en passant une fonction de démarrage :

Vous pouvez passer le nom d’une fonction en paramètre de la méthode “Start” qui sera invoquée dès que le script Python est connecté à Constellation.

Cela vous permet de définir du code au démarrage du package :

def OnStart():
    # Mon code de démarrage ici
    pass

Constellation.Start(OnStart);

3 – Troisième méthode : invoquer la méthode “StartAsync” (non bloquante)

Mais attention vous devrez vous même créer une boucle pour maintenant votre script “en vie” autrement il s’arrêtera automatiquement !

Constellation.StartAsync()
while Constellation.IsRunning:
    pass
    time.sleep(1)

Interpréteurs Python et environnements virtuels

Par défaut chaque script est lancé avec la commande “python”. C’est pour cela qu’il est recommandé d’ajouter Python dans le PATH de votre système afin de pouvoir “résoudre” la commande “python”.

Vous pouvez aussi définir dans le fichier App.config de votre package Python, l’attribut “pythonCmd” pour spécifier la commande à lancer. Ci-dessous un exemple avec l’interpréteur Python 2.7 :

<pythonProxy xmlns="urn:Constellation.PythonProxy" pythonCmd="C:\Python27\python.exe">
  <scripts>
    <script filename="Scripts\Demo.py" />
    <script filename="Scripts\Demo2.py" />
  </scripts>
</pythonProxy>

L’attribut “pythonCmd” peut-être également défini de manière individuelle pour chaque script. Prenez par exemple la configuration suivante :

<pythonProxy xmlns="urn:Constellation.PythonProxy" pythonCmd="python3">
  <scripts>
    <script filename="Scripts\Demo.py" />
    <script filename="Scripts\Demo2.py" pythonCmd="C:\Users\Sebastien\venv\Scripts\python.exe" />
    <script filename="Scripts\Demo3.py" pythonCmd="C:\Python27\python.exe" />
  </scripts>
</pythonProxy>

Ci-dessus le package Python démarre trois scripts Demo.py, Demo2.py et Demo3.py de la façon suivante :

• Demo.py sera lancé par l’interpréteur Python 3 (via la commande “python3” défini au niveau global)
• Demo2.py sera lancé par un environnement virtuel ici nommé “venv” (défini pour le script)
• Demo3.py sera lancé par l’interpréteur Python 2.7 installé dans “C:\Python27”

Vous pouvez donc utiliser cet attribut pour spécifier l’interpréteur Python à utiliser (Python 2 vs 3 ou même des interpréteurs dans des environnements virtuels). Quelque soit l’interpréteur utilisé n’oubliez d’installer les librairies “pyzmq” (et “enum34” si Python 2.x).

Note : vous pouvez aussi les Settings Constellation dans l’attribut « pythonCmd » vous permettant ainsi de définir/changer d’interpréteur sans modifier le code de votre package, simplement en manipulant les settings de votre package depuis la Console Constellation. Plus d’information sur ce billet.

Produire des logs

Pour écrire des logs dans le hub Constellation, tout comme en C#, vous disposez des méthodes suivantes :

• WriteInfo
• WriteWarn
• WriteError

Exemple :

Constellation.WriteInfo("Hello world from Python !")
Constellation.WriteWarn("This is a warning !")
Constellation.WriteError("This is an error !")

En Python vous pouvez formater vos messages avec des variables grâce à l’opérateur “%”.

Par exemple, affichons dans les logs Constellation l’état de notre package :

Constellation.WriteInfo("Hi I'm '%s' and I run on %s" % (Constellation.PackageName, Constellation.SentinelName))
Constellation.WriteInfo("IsConnected = %s | IsStandAlone = %s " % (Constellation.IsConnected, Constellation.IsStandAlone))

Vous remarquez par la même occasion quelques propriétés accessibles dans vos scripts Python (IsConnected, IsStandAlone, SentinelName, PackageName, etc…).

Accès aux settings

Le fonctionnement des settings est strictement identique à l’API .NET décrite ici.

Les settings sont définis sur le serveur au niveau du package ou via des groupes, et par héritage peuvent être définis dans le fichier local App.config et/ou dans le manifeste. Je vous invite vivement à lire cet article pour bien comprendre le fonctionnement des settings.

Avec l’API Python de Constellation vous disposez de la méthode “GetSetting” pour récupérer la valeur de vos settings.

Par exemple pour afficher la valeur du setting “Demo1” :

Constellation.WriteInfo("Demo1 = " + str(Constellation.GetSetting("Demo1")))

Si la valeur du setting n’existe pas, la méthode vous retourne un “Null” :

if Constellation.GetSetting("Demo1") <> Null:
     Constellation.WriteInfo("Demo1 = " + str(Constellation.GetSetting("Demo1")))

Vous avez également la possibilité d’attacher une méthode callback pour être notifier dans votre code Python lorsque les settings de votre packages sont mises à jour dans Constellation :

import Constellation

def OnSettingsUpdated():
    print("Mise à jour de mes settings depuis Constellation !!")

def Start():
    Constellation.OnSettingsUpdated = OnSettingsUpdated

Constellation.Start(Start);

Publier des StateObjects

Comme pour l’API .NET, vous disposez de la méthode PushStateObject pour publier un StateObject.

Chaque StateObject a obligatoirement un nom et une valeur de n’importe quel type :

Constellation.PushStateObject("MyString", "OK")
Constellation.PushStateObject("MyNumber", 123)
Constellation.PushStateObject("MyDecimal", 123.12)
Constellation.PushStateObject("MyBoolean", True)

Vous pouvez publier des StateObjects dont la valeur est un objet complexe :

Constellation.PushStateObject("Demo", { "UneString": "DemoPython", "UnNombre": 123 })

Dans l’exemple ce-dessus, le StateObject « Demo » est un objet contenant deux propriétés : « UneString » et « UnNombre ».

Lorsqu’il s’agit de type complexe, il est vivement conseiller de décrire le type du StateObject à Constellation.

Pour cela au démarrage de votre package (méthode Start), enregistrez vos différents types de StateObjects avec la méthode « DescribeStateObjectType ».

Par exemple :

Constellation.DescribeStateObjectType("MyStateObject", "StateObject à deux propriétés de démonstration", [
    { 'Name':'UneString', 'Type':'string', 'Description': 'Une chaine de caractère tout simplement' },        
    { 'Name':'UnNombre', 'Type':'int', 'Description': 'Un nombre entier' }
])

Pour chaque type on spécifiera un nom, une description du type et la liste ses propriétés. Sachant que pour chaque propriété nous avons un nom, un type et une description.

Le type d’une propriété peut faire elle-même référence à un autre type complexe que vous avez enregistré.

Pour finir il faudra déclarer le package descriptor après avoir décrit tous vos types :

Constellation.DeclarePackageDescriptor()

Enfin, pour chaque publication de StateObject, vous pouvez spécifier le type (simple ou complexe que vous aurez enregistré ci-dessus), un dictionnaire de méta-données ou encore une durée de vie (en seconde)  :

Constellation.PushStateObject("Demo", { "UneString": "DemoPython", "UnNombre": 123 }, type = "MyStateObject", metadatas = { "DeviceId": "RPi", "SerialNumber":"123" }, lifetime = 300)

Tester son package dans Visual Studio

Laissons le code de démo du script “Demo.py” créé par le Template du projet tel quel :

Notons simplement qu’au démarrage du package on enregistre la méthode “OnStart” pour :

• Produire différents logs via des “WriteInfo” (Warning & Error) contenant notamment différentes propriétés comme le IsConnected & IsStandalone.
• Publier le StateObject “Demo”

Debug local (hors Constellation)

Commençons par tester notre package hors Constellation en lançant simplement le package avec le bouton “Start” de Visual Studio (F5) :

Votre package démarre et vous pouvez suivre dans la console les différents logs produits par votre package.

Vous observerez que votre package n’est pas connecté à Constellation (IsConnected = false).

Debug dans Constellation

Maintenant lançons toujours le debugging de votre package Constellation depuis Visual Studio mais en connectant votre package à Constellation. (Assurez-vous d’avoir défini dans Visual Studio la Constellation à utiliser pour le debug comme nous l’avons vu dans ce guide).

Cette fois ci, votre package démarre dans Visual Studio mais en étant connecté à Constellation (IsConnected = true).

Vous pouvez donc suivre en temps réel les logs depuis la Console Constellation :

Vous retrouverez également dans le StateObject Explorer de la Console, le StateObject “Demo” publié par notre package :

Publiez votre package

Lorsque votre package est testé et validé, nous pouvons le publier dans Constellation.

Pour cela cliquez sur le bouton de publication :

Sélectionnez votre serveur Constellation cible et cliquez sur “Publish” :

Une fois publié, vous retrouverez votre package dans le “Package Repository” de la Console.

N’oubliez pas que vous pouvez personnaliser les différentes informations (nom du package, auteur, URL, version, description, etc…) en éditant le manifeste de votre package.

Déployez votre package sur une sentinelle

Maintenant que votre package est dans le catalogue de votre Constellation, vous pouvez le déployer sur autant de sentinelle que vous le souhaitez!

Par l’édition du fichier de configuration

Pour cela, vous pouvez éditer manuellement la configuration (via le Configuration Editor) pour ajouter une instance de package sur la sentinelle de votre choix par la ligne :

<package name="MonPackagePython" />

On peut également déclarer le setting “Demo1” pour cette instance de package :

<package name="MonPackagePython">
  <settings>
    <setting key="Demo1" value="Hello Python !!!!" />
  </settings>
</package>

Cliquez sur le bouton “Save & Deploy” et votre package sera automatiquement démarré sur la sentinelle ici nommée “PO-SWARIN” !

Par l’interface graphique de la Console Constellation

Autre moyen, plus intuitif et rapide pour déployer un package, cliquez sur le bouton “Deploy” dans menu contextuel de votre package Python :

Vous pouvez également cliquer sur le bouton “Deploy new package” sur la page “Packages”.

Un assistant vous proposera de sélectionner la sentinelle sur laquelle déployer votre package Python :

Si les settings de votre package sont déclarés dans le manifeste (voir ici), la Console vous affichera une fenêtre de paramétrage :

Une fois votre package déployé, vous pourrez suivre dans la Console Log votre package :

Et voilà votre premier package Python créé et déployé dans votre Constellation !

Next steps

• MessageCallback : exposer des méthodes Python dans la Constellation
• Envoyer des messages et invoquer des MessageCallbacks de la Constellation
• StateObjectLink : consommer des StateObjects de votre Constellation

The post Créez votre premier package Constellation en Python appeared first on Constellation.

Nous allons dans cet article créer, tester et déployer sur votre Constellation un package Python avec cet outil.

Prérequis

Le « Constellation Package Tools CLI » est un outil en ligne de commande compatible Windows et Linux. Il est écrit en Python et s’installe via PIP avec la commande :

pip install constellation-pkgtools-cli

Sur Windows vous devriez au préalable avoir installé Python 2.7 ainsi que l’outil « pip » et les libraires « pyzmq » et « enum34 ». La procédure complète d’installation est décrite sur cette page.

Via une invite de commande, tapez la commande ci-dessus :

Sur Linux, vous devez également avoir installé Python 2.7 (généralement installé par défaut),  l’outil « pip » et les libraires « pyzmq » et « enum34 » sans oublier le moteur Mono. Pour cela, utilisez le WPI (Web Platform Installer) pour installer une sentinelle Constellation. Celui-ci se chargera de déployer l’ensemble des prérequis nécessaire.

La commande « ctln »

Une fois le package Python « constellation-pkgtools-cli » installé via PIP, vous aurez accès à une commande nommée « ctln » (abréviation de Constellation)

Cette commande vous permettra de créer de nouveau package, les tester et déployer en local ou directement sur un serveur Constellation.

Créer son premier package Python

Pour créer un nouveau package utilisez simplement la commande “create” en spécifiant le nom de votre package. Par exemple :

ctln create <mon projet>

Et voilà, votre package “MyFirstPackage” est créé dans le répertoire du même nom !

Template de package

Chaque package est créé à partir d’un template. Vous pouvez lister les templates avec la commande :

ctln template list

A l’heure où est écrit cet article il y a deux templates de type “projet” :

• Python Base Template : le template de base (créé par défaut)
• Python Demo template : package Python avec du code de “demo”

Lorsque vous créez un package avec la commande “ctln create”, le template “python-base” est sélectionné par défaut.

Vous pouvez cependant préciser l’Id du template à utiliser dans la commande “ctln create”. Par exemple pour créer un package sur base du template de demo :

ctln create <mon projet> python-demo

Il y a aussi des templates de type “item”, c’est à dire des templates pour les scripts que vous allez rajouter par la suite à votre package.

Mise à jour du template

Comme vous le constatez dans le listing des templates ci-dessus, chaque template comporte un numéro de version car ils sont amenés à évoluer notamment en cas de mise à jour des librairies Constellation.

Avec le SDK Constellation Visual Studio, les nouvelles versions des librairies sont diffusées avec NuGet. Ici avec cet outil en ligne de commande, les nouvelles librairies sont embarquées dans des mises à jour des templates.

Ainsi pour mettre à jour vos packages, vous pouvez tout simplement mettre à jour le template de votre package par la commande :

ctln update

Cette commande doit être lancé depuis le répertorie racine de votre package.

Notez également que la mise à jour est “intelligente” dans la mesure où elle n’écrase pas vos fichiers de configuration, le manifeste du package ou encore vos scripts Python.

Développer son package

Le développement de package Python est expliqué dans cet article. Bien que l’article se base sur Visual Studio, l’API Python est strictement identique.

Ainsi, pour rappel, vous avez à la racine de votre projet le fichier « PackageInfo.xml » qui contient l’ensemble des informations de votre package (plus de détail ici) mais aussi le fichier de configuration nommé « PythonPackageHost.exe.config » qui contient la liste des scripts Python à lancer.

Les bases du développement d’un script Constellation Python sont expliquées ici.

Pour faciliter le développement, vous n’êtes pas obligé de modifier manuellement le fichier de configuration pour gérer les scripts Python. Pour cela vous avez à disposition différentes commandes pour lister, ajouter, renommer ou supprimer des scripts.

Lister les scripts du package

Les scripts Constellation Python lancés par votre package peuvent être listés par la commande :

ctln pyscript list

Ici votre package « MyFirstPackage » ne contient qu’un seul script nommé « Main.py » dans le répertoire Scripts du package.

Ajouter des scripts Python

Pour ajouter un script Constellation Python, vous pouvez soit ajouter un script existant sur votre système de fichier dans votre package ou soit créer un nouveau script à partir d’un modèle (template).

Ajouter un script existant

Pour un script existant, il suffit d’utiliser l’option « add » :

ctln pyscript add <filepath> [--filename=<name>]

Vous devez spécifier le chemin complet vers votre fichier à ajouter (filepath) et optionnellement le nom du fichier une fois ajouté dans votre package.

Par exemple la commande ci-dessous ajoutera dans votre package le fichier « ~/demo/MyDemo.py » sous le nom « DemoSeb.py »

ctln pyscript add ~/demo/MyDemo.py --filename=DemoSeb.py

Ajouter de nouveau script

L’action la plus courante sera de créer un nouveau script Python dans votre package avec l’action « new » via la commande suivante :

ctln pyscript new <filename> [<item_template_name>]

Vous devez obligatoirement spécifier le nom du fichier (filename) avec ou sans l’extension .py (rajoutée automatiquement). Le script sera créé dans le répertoire Scripts de votre package et automatiquement déclaré dans la configuration.

Vous pouvez également spécifier l’identifiant du template à utiliser. Les templates peuvent être listés avec la commande « ctln template list » comme vu ci-dessus.  A l’heure où cet article est écrit il y a trois templates de type « item » :

• « python-base » : le template de base
• « python-demo »  : un template avec du code de demonstration
• « python-empty »  : un squelette vide

Si vous ne précisez pas l’identifiant, c’est le template « python-base » qui sera utilisé.

Par exemple ajoutons à notre package un deuxième script (avec le template de base) :

ctln pyscript new Main2

Rajoutons également un troisieme scriupt de démonstation en utilisant le template de demo (python-demo) :

ctln pyscript new DemoConstellation python-demo

Notre package a maintenant trois scripts : Main.py (créé avec le template du package), Main2.py (créé ci-dessus avec le template de base), DemoConstellation.py (créé avec le template de demo) :

Renommer ou supprimer des scripts

Vous pouvez renommer les scripts du package avec l’option “rename”. Par exemple renommons “DemoConstellation” par “Demo” (les extensions “.py” sont optionnelles) :

ctln pyscript rename DemoConstellation Demo

Pour supprimer des scripts il suffit d’utiliser l’option “remove” en spécifiant le nom du script (avec ou sans son extension .py).

Par exemple supprimons les deux fichiers “Main2.py” et “Demo.py” que nous avons ajoutés (et renommés) ci-dessus :

ctln pyscript remove Main2
ctln pyscript remove Demo

Editer les scripts Python du package

Une fois vos scripts ajoutés, renommés ou supprimés avec la commande “ctln”, libre à vous d’utiliser votre éditeur de texte préféré pour éditer votre code !

Par exemple de le cas ici présent d’un accès SSH Linux, je pourrais utiliser “nano” ou “vim” (ou encore Notepad++ sur ma station WIndows via un tranfert SCP avec WInSCP par exemple).

nano Scripts/Main.py

Ici le script “Main” défini une fonction de démarrage (OnStart) et une fonction de fermeture (OnExit). Pour rappel, les bases de l’API Constellation Python sont expliquées ici.

Notez simplement que dans cet exemple, le WriteInfo déclenché au démarrage (OnStart) écrit un log dasn Constellation de type “Information” en concaténant dans un message textuel les propriétés suivantes :

• “PackageName” : le nom du package
• “SentinelName” : le nom de la sentinelle sur laquelle est déployée ce package
• “IsStandAlone” : un booléen indiquant si le package tourne de façon indépendante ou hébergée au sein d’une sentinelle
• “IsConnected” : un booléen indiquant si le package est connecté ou non à une Constellation

Tester son package

Pour tester notre package en local, il suffit de lancer la commande suivante :

ctln run

Comme vous pouvez le lire sur la console, le nom de la sentinelle affichée est “local sandbox” étant donné que la propriété IsStandalone est true (la propriété SentinelName est None). En effet votre package n’est pas déployé/démarré par Constellation sur une véritable sentinelle. Il est juste démarré en “standalone” par la commande “run”.

De plus la propriété “IsConnected” est false car votre package n’est pas connecté à une Constellation.

Vous pouvez donc tester des éléments de base de votre package mais de façon déconnecté, il manquera donc plusieurs fonctionnalités (les logs produits resterons local dans votre console, pas d’accès aux settings hormis ceux déclarés en local, la publication ou consommation de StateObjects sera impossible tout comme l’invocation ou l’exposition de MessageCallbacks).

Pour tester votre package complètement, il est possible de le lancer en local tout en le connectant à une Constellation.

Tout d’abord, il faudra déclarer des serveurs Constellation dans l’outil ctln.

Ajouter et gérer des serveurs Constellation

Les commandes sont les suivantes :

ctln server list
ctln server (add | set) <name> --url=<url> --accesskey=<key>
ctln server (add | set) <name> --url=<url> --username=<user>
ctln server check <name>
ctln server remove <name>

Vous pouvez lister les serveurs, ajouter ou mettre à jour des serveurs avec la clé d’accès ou un couple login/password, tester la connectivité ou supprimer des serveurs.

Par exemple je dispose d’une Constellation installée à l’adresse : http://pc-seb.ajsinfo.loc:8088. Un credential basé sur le couple login/password “admin/seb” a été configuré. Je peux donc ajouter ce serveur que je nommerai ici “pc-seb” via la commande :

ctln server add pc-seb --url=http://pc-seb.ajsinfo.loc:8088 --username=admin

Le serveur ajouté est testé au moment de l’ajout mais vous pouvez à tout moment tester la connectivité vers cette Constellation avec la commande “ctln server check”. Par exemple pour tester la Constellation nommée “pc-seb” :

ctln server check pc-seb

Tester son package dans Constellation

Maintenant que nous avons ajouté un serveur Constellation dans l’outil, nous pouvons relancé notre package en le connectant à notre Constellation nommée “pc-seb” via la commande :

ctln run --server=pc-seb

Le package démarre toujours dans la « sandbox locale » (IsStandalone = true) mais cette fois ci il est connecté à ma Constellation nommée « pc-seb » (IsConnected = true).

D’ailleurs en lançant la Console Constellation je peux maintenant suivre en temps réel les logs de ce package, les StatesObjects qu’il produit ou encore les MessageCallbacks qu’il expose.

Publier son package

Une fois le package développé et testé, il ne reste plus qu’à le packager pour pouvoir le déployer dans Constellation.

Vous pouvez soit le packager dans un fichier en local (que vous pourrez uploader sur une Constellation ou échanger avec d’autre) ou soit le déployer directement dans une Constellation référencée dans l’outil.

Par exemple pour publier ce package dans un fichier local dans le répertoire “/home/pi” :

ctln publish --output=/home/pi

Maintenant, pour déployer ce même package directement sur une Constellation, il suffit simplement de spécifier le nom du serveur Constellation enregistré sur la commande “publish”.

Par exemple pour publier ce package sur la Constellation nommée ici “pc-seb” :

ctln publish pc-seb

En vous rendant sur le Package Repository de votre Console Constellation, votre package fraîchement publié sera prêt à être déployé sur vos sentinelles Windows ou Linux de votre Constellation.

Next steps

Pour en savoir plus sur le développement de package en Python :

• Retour sur les bases de l’API Python  (produire des logs, accéder aux settings, publier des StateObjects)
• Exposer vos fonctions Python dans Constellation (les MessageCallbacks)
• Invoquer des MessageCallbacks des autres packages de votre Constellation en Python
• Consommer les StateObjects de votre Constellation

The post Créer, tester et déployer des packages Python en ligne de commande 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.

Par exemple si vous voulez récupérer en temps réel le StateObject correspondant à un thermostat Nest (partant de l’hypothèse où le package Nest est déployé dans votre Constellation).

Via le StateObjects Explorer de la Console Constellation, on retrouvera le StateObject ici nommé “Living Room” publié par le package Nest qui représente l’état du thermostat du salon :

On peut donc écrire une méthode qui sera liée à ce StateObject pour afficher un message de log à chaque fois que l’état du thermostat sera mis à jour :

@Constellation.StateObjectLink(package = "Nest", name = "Living Room")
def OnNestTargetTemperatureChanged(stateObject):
    Constellation.WriteInfo("The Nest target temperature has changed to : %s°C" % stateObject.Value.target_temperature_c)

Le décorateur “StateObjectLink” accepte les paramètres suivants : “sentinel”, “package”, “name” et “type”. Tous ces paramètres sont optionnels et par défaut défini à “*”, c’est à dire qu’aucun filtre n’est appliqué !

Une méthode décorée “StateObjectLink” doit accepter qu’un seul argument : le StateObject.

Un StateObject contient les propriétés suivantes :

• SentinelName : nom de la sentinelle qui a produit le StateObject
• PackageName : nom du package qui a produit le StateObject
• Name : le nom du StateObject
• UniqueId : identifiant unique du StateObject dans la Constellation (concaténation des 3 propriétés ci-dessus)
• Type : type du StateObject
• Lifetime : durée de vie en seconde du StateObject avant d’être considéré “expiré” (0 si infini)
• LastUpdate : date de la dernière publication du StateObject
• IsExpired : indique si le StateObject est expiré (c’est à dire que DateTime.Now >  LastUpdate  + Lifetime si et seulement si Lifetime > 0)
• Metadatas : dictionnaire de clé / valeur
• Value : la valeur du StateObject (peut être un type simple ou un objet complexe)

Important : la méthode sur laquelle est appliquée cet attribut sera invoquée au démarrage de votre package avec la valeur actuelle du ou des StateObjects (Request) puis à chaque mise à jour des StateObjects (Subscribe).

Autre exemple, affichons dans les logs de notre package Python la consommation des CPU de l’ensemble des sentinelles Windows connectées dans notre Constellation en utilisant le package HWMonitor :

@Constellation.StateObjectLink(package = "HWMonitor", name = "/intelcpu/0/load/0")
def CPUUpdated(stateobject):
    Constellation.WriteInfo("CPU on %s is currently %s %" % (stateobject.SentinelName, stateobject.Value.Value))

Dans le cas où vous souhaiterez conserver la valeur de votre StateObject dans une variable de votre script Python pour pouvoir vous en servir dans d’autre méthode, il suffit tout simplement d’affecter le StateObject dans une variable globale depuis un StateObjectLink.

Reprenons l’exemple du thermostat Nest ci-dessus. Commençons par déclarer cette variable globale au niveau de notre script :

global nestThermostat

Puis ajoutons un StateObjectLink vers le StateObject du thermostat Nest pour mettre à jour notre variable globale :

@Constellation.StateObjectLink(package = "Nest", name = "Living Room")
def OnNestThermostatChanged(stateObject):
    global nestThermostat
    nestThermostat = stateObject.Value

Ainsi la variable « nestThermostat » contiendra la dernière valeur du StateObject représentant le thermostat Nest. Vous pourrez y accéder depuis n’importe quel endroit de votre script.

The post Consommer des StateObjects depuis l’API Python appeared first on Constellation.