Amélioration des performances

Le fait le plus marquant de cette version 1.8.5 est l’amélioration des performances notamment en ce qui concerne les explorateurs de StateObject et MessageCallbacks.

Là où une Constellation avec des milliers de SO/MC pouvait avoir du mal à être explorée depuis la Console, la réécriture du modèle de “binding” sur ces pages permette maintenant une navigation fluide.

Support de la recherche

Le “Configuration Editor” permettant d’éditer directement la configuration de votre Constellation se dote de différentes fonctions facilitant l’édition comme la Recherche, le remplacement ou encore le “aller à la ligne” :

Pour vous aider avec les différentes fonctions et raccourcis ajoutés, un écran d’aide a été ajouté :

Support des types Nullable<T>

Jusqu’à présent les paramètres de MessageCallback ou propriété d’objet de type “Nullable<T>” n’étaient pas pris en compte dans le “MessageCallback Explorer”. C’est désormais le cas avec la version 1.8.5 ce qui vous permettra de tester vos MC avec des types Nullable.

Aussi les valeurs par défaut pour les champs “Bool” ou “Enum” sont également supportés.

Des petits détails

En vrac :

• Il est désormais possible de copier dans le presse-papier (Ctrl+C) la sortie de la Console Log

• Il y a une demande de confirmation à chaque fermeture de modale si des changements sont en attente d’enregistrement

• L’expérience sur mobile est améliorée
• Mise à niveau des librairies utilisées par la Console Constellation (jQuery 3.4.1, AngularJS 1.7.8, SignalR 2.4.1, jQueryTerminal 2.6.1, UI Bootstrap 2.5, CodeMirror 5.47)

Comme d’habitude, relancez le “Web Platform Installer” sur Windows ou Linux pour mettre à jour votre Console.

The post Mise à jour de la Console 1.8.5 appeared first on Constellation.

Vous pouvez mettre à jour votre installation en lançant le « Web Platform Installer » sur Windows :

Constellation Web Platform Installer » Article
Constellation-Web-Platform-Installer-1.9.735.exe
Version: 1.9.735

1.2 MiB
2136 Downloads
Détails

Constellation Web Platform Installer pour Windows

Auteur:	MyConstellation.io
Plateformes:	Windows
Catégorie:	Web Platform Installers
Licence:	Constellation License Agreement
Date:	juin 15, 2020

Ou, sur Linux, en lançant la commande :

wget -O install.sh https://developer.myconstellation.io/download/installers/install-linux.sh && chmod +x install.sh && ./install.sh

Constellation Server 1.8.3

Tout d’abord les dépendances du serveur Constellation ont été mises à jour : Json.NET 9.0.1, NLog 4.4.11, SignalR 2.2.2 et enfin la stack OWIN en version 3.1. Chacune d’entre elles apportant des correctifs et améliorations de performance.

La modification la plus importante de cette version 1.8.3 est la refonte complète de la gestion des packages au niveau du serveur. En effet, jusqu’à présent seuls les packages réels (et non virtuels) étaient gérés par le hub de contrôle. Pour les packages virtuels, il fallait exploiter l’API de Management (ou lire la configuration XML) car ils n’existaient pas sur le hub de contrôle (d’où le terme “virtuel”).

Désormais, chaque package déclaré dans la configuration d’une Constellation, qu’il soit réel ou virtuel, est chargé sur le hub de contrôle. Il n’y a donc plus de Statut en “N/A” sur la Console Constellation : tous les packages ont par défaut un état à “Unknown”. Une simple connexion sur le hub de contrôle permet donc de récupérer l’intégralité des packages d’une Constellation sans devoir combiner des informations venant de la configuration XML pour y ajouter la partie « virtuelle ».

De plus les packages virtuels initialisant des abonnements aux messages ou StateObjects sont maintenant marqués comme “connecté” sur le hub de contrôle permettant de suivre leurs états. Par exemple, un Arduino/ESP est maintenant vu comme connecté sur le hub de contrôle :

Aussi chaque package envoie désormais, en plus de son n° de version et de la libraire Constellation utilisée, le type de la libraire utilisée : il s’agit de la propriété “ConstellationClientType”.

Aussi, il est possible définir le répertoire de base de la Constellation dans lequel trouver le fichier de configuration en spécifiant la clé « Constellation.BaseDirectory ». Cela permet de séparer les binaires Constellation de sa configuration, très utile dans un environnement Docker. Un article sur le sujet sera prochainement publié.

Outre différentes optimisations du code et correction de défauts mineurs on peut aussi noter :

• Server / ControlHub : le ReloadServerConfiguration envoi la liste des packages aux sentinelles seulement connectées et « Update settings » sur les packages connectés seulement et non à tous les groupes
• Server / ControlHub : prise en charge des mises à jour de configuration des packages à volée
• Server / Management API : ajout d’un objet de synchronisation pour les I/O vers le fichier de configuration pour éviter les écritures concurrentes
• Server / Licensing : LeaseLicensing dans le domaine serveur si multi-tenant sinon dans le domaine de la constellation si mono-instance (permettant ainsi de récupérer les erreurs de licence dans la Console Log)
• Server / API REST : le timeout des sessions HTTP est maintenant de 150 secondes par défaut configurable dans le fichier de configuration

Enfin notez que le serveur 1.8.3 est rétrocompatible avec les différents composants Constellation 1.8.x, que ce soit pour la Console, les packages ou les sentinelles. Autrement dit vous pouvez mettre à jour votre serveur en 1.8.3 tout en gardant vos packages et sentinelles 1.8.x fonctionnelles.

Constellation Sentinel 1.8.3

L’autre grande nouveauté de cette nouvelle version 1.8.3 est la refonte complète du gestionnaire de processus sur les sentinelles.

Jusqu’à présent lorsqu’une sentinelle recevait sa liste des packages, elle se chargeait de télécharger et démarrer chaque package de sa liste. Si le package était déjà en fonctionnement elle levait un Warning ce qui avait tendance à “polluer” les logs notamment lorsqu’on déployé la configuration au niveau d’une Constellation. Enfin lorsqu’un package en fonctionnement était supprimé de la liste, elle fermait le processus associé.

Le problème dans ce mécanisme est que si vous arrêtez un package et que vous redéployer la configuration, par exemple en ajoutant, supprimant ou modifiant les settings d’un autre package, la liste était renvoyée à votre sentinelle qui relançait “bêtement” le package vous avez arrêté !

C’est pour cela que le fonctionnement interne de la sentinelle a été profondément revu et a conduit à la réécriture complète du mécanisme de gestion des processus. Ainsi la description de chaque package, démarré ou non, est maintenue en mémoire. Lorsqu’une sentinelle reçoit sa nouvelle liste, elle est toujours capable de charger/démarrer les nouveaux packages et supprimer/arrêter les packages retirés mais les packages existants ne sont pas redémarrés automatiquement, ils conservent leurs états.

Cette refonte a amélioré beaucoup de chose en apportant plus de fiabilité et stabilité dans le suivi du processus et elle apporte une meilleure cohérence des états de chaque package.

Aussi, comme le serveur, les dépendances ont été mises à jour : Json.NET 9.0.1, SignalR 2.2.2, NLog 4.4.11 et NLog.Windows.Form 4.2.3 pour la Sentinelle UI.

Notez enfin qu’une sentinelle 1.8.3 peut fonctionner sans aucun problème dans une Constellation 1.8.x de version antérieure tout comme une sentinelle antérieure à la version 1.8.3 pour fonctionner sur une Constellation 1.8.3.

Constellation Console 1.8.3

La Console Constellation a aussi reçu sont lot de nouveautés à l’occasion de cette nouvelle release 1.8.3.

Etant donné la refonte dans la gestion des packages sur le hub de contrôle, la Console Constellation a été impacté à ce niveau. Elle se base exclusivement sur le hub de contrôle sans devoir interroger la Management API en parallèle pour intégrer les packages virtuels ou non connectés.

Suite à la publication des nouvelles librairies Javascript et AngularJS 1.8.2 du mois dernier, les codes snippets du MessageCallbacks Explorer ont été mis à jour pour intégrer les nouveautés de ces librairies.

On notera aussi l’ajout d’un bouton pour vider la Console Log, l’ajout ConstellationClientType sur les packages ou encore du credential utilisé par une sentinelle sur la fenêtre de détail. Aussi la Console supporte pleinement les utilisateurs connectés sans droits de Management.

Mais aussi :

• Console / Package : Gestion des packages virtuels avec un statut Unknown, menu contextuel synchronisé et mise à jour de l’activité pour les packages virtuels
• Console / Packages : « Update Settings » affiché dans le menu contextuel si le package est connecté et démarré (package virtuel compris)
• Console / Packages : bugfix sur le déploiement de package avec un setting de type DateTime (module $filter non injecté dans le contrôleur principal)
• Console / Packages : bugfix sur le déploiement de la configuration une fois que le SetRecoveryOption est terminé et non en parallèle
• Console : déconnexion des deux hubs (consumer et controller) si l’un des deux est déconnecté (cas très rare où l’un des deux hubs parvient à se reconnecter et pas l’autre)
• Console : Mise à jour de l’API Constellation Javascript & AngularJS en version 1.8.2 et de la librairie SignalR 2.2.2

Autres nouveautés

La librairie .NET pour les packages a été mise à jour en version 1.8.3.17190, et est disponible sur le repository Nuget. Cette nouvelle version envoie le “ConstellationClientType” ( net40 » ou « net45 ») lors de la connexion de votre package à Constellation. De plus les dépendances ont été mises à jour vers JSON.NET 9.0.1 et SignalR 2.2.2.

Notez enfin qu’un package exploitant l’API 1.8.3 peut fonctionner sans aucun problème sur une Constellation 1.8.x de version antérieure tout comme un package antérieure à la version 1.8.3 peut fonctionner sur une Constellation 1.8.3.

Une nouvelle version SDK est également disponible. Il intègre une mise à jour des templates de projet Constellation pour prendre en compte les dernières versions des API 1.8.3.

Pour finir le Web Platform Installer pour Linux a lui aussi été mis à jour. Il garde en mémoire le jeton d’authentification entre les différents installeurs Server, Sentinel et Console de façon à éviter de devoir se ré authentifier à chaque composant mais surtout le pilotage des services Server et Sentinel dans Supervisor est désormais basé sur “supervisorctl” pour une gestion plus fine des services.

Pour consulter le changelog complet de cette nouvelle version cliquez ici. N’hésitez pas non plus à remonter vos feedbacks sur le forum.

The post Constellation 1.8.3 est disponible appeared first on Constellation.

Découvrons ces nouveautés en détail !

PythonProxy 1.8.2 :  amélioration de l’expérience de développement des packages Python

Configuration des scripts à démarrer

Depuis la sortie du “PythonProxy” en décembre 2014 permettant d’embarquer des scripts Python dans un package Constellation, tous les fichiers “.py” présents dans le répertoire “Scripts” étaient chargés à l’exception du fichier “Constellation.py” et des fichiers terminant par “lib.py” ce qui permettait d’inclure des librairies Python dans vos packages. De plus tous ces fichiers Python étaient lancés par ordre alphabétique.

Cela fait désormais partie du passé ! En effet, depuis la mise à jour 1.8.2, il faut déclarer la liste des fichiers Python à charger dans le fichier App.config en ajoutant la section suivante :

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

Sans oublier de déclarer dans la section <configSection> la ligne suivante :

<section name="pythonProxy" type="Constellation.PythonProxy.PythonConfigurationSection, Constellation.PythonProxy, Version=1.8.0.0, Culture=neutral, PublicKeyToken=null" />

Vous pouvez donc maintenant définir explicitement les scripts que vous voulez lancer et dans l’ordre que vous souhaitez sans devoir jouer sur les noms des fichiers.

Cela offre plus de souplesse dans la conception de vos packages avec un fonctionnement beaucoup plus clair et explicit.

Timeout de démarrage

Lorsque le PythonProxy lance un script Python que vous avez écrit, il cherchera à se connecter avec lui avant d’invoquer votre méthode “OnStart”. Seulement en cas de problème, par exemple si votre script comporte des erreurs fatales, la connexion n’aura jamais lieu et votre package sera bloqué !

Désormais cette nouvelle version intègre la notion de “timeout” permettant de définir un temps maximal de démarrage. Si le PythonProxy ne parvient pas à se connecter à votre script dans le délai imparti, il affichera un message d’erreur et passera au script suivant sans bloquer indéfiniment.

Ce timeout peut être configuré pour chaque script avec l’attribut “startupTimeout” ou bien de manière globale.

Notez également qu’il existe un timout d’arrêt : si votre script n’est pas terminé après avoir reçu l’ordre d’arrêt dans un délai imparti, le PythonProxy mettra fin au processus Python qui l’héberge.

Par exemple :

<pythonProxy xmlns="urn:Constellation.PythonProxy" scriptStartupTimeout="20" scriptCloseTimeout="5">
  <scripts>
    <script filename="Scripts\Demo.py" startupTimeout="10" />
    <script filename="Scripts\LightSensor.py" closeTimeout="2" />
    <script filename="Scripts\Camera.py" />
  </scripts>
</pythonProxy>

Le 1er script (Demo.py) doit démarrer en moins de 10 secondes et le 2ème script (LightSensor.py) doit s’arrêter en moins de 2 secondes. Pour le reste, le temps de démarrage est de 20 secondes et 5 secondes pour l’arret.

Notez enfin que si aucune valeur n’est spécifiée (ni sur la balise <script> ni de manière globale sur la section <pythonProxy>), les valeurs par défaut sont :

• 30 secondes pour le démarrage
• 8 secondes pour l’arrêt

Redirection de la sortie et des erreurs Python sur Constellation

Avec cette nouvelle version du PythonProxy, l’ensemble du flux de sortie et d’erreur des processus Python qui hebergent vos scripts seront rédirigés vers les logs Constellation.

Autrement dit un simple “print” sera visible dans les logs Constellation mais surtout la moindre erreur, par exemple une erreur de syntaxe dans votre script empêchant son initialisation, sera remontée dans les logs Constellation vous donnant alors toutes les informations nécessaires pour sa correction.

Avec cette nouvelle version du Python Proxy, fini le côté “Black Box” lors du démarrage de vos scripts !

Surveillance de vos scripts

Il y a désormais un mécanisme de Ping/Pong entre le package Constellation et les scripts Python pour vérifier l’état de vie des deux parties. Si un processus Python ne reçoit plus de Ping reçu pendant plus de 30 secondes, il s’arrêtera automatiquement pour éviter les processus orphelins (notamment en cas de debug).

Mise à niveau

Pour en profiter il suffit de mettre à jour le package Nuget depuis Visual Studio et d’ajouter ensuite la section de configuration présentée ci-dessus dans votre fichier App.config.

Notez que tous les nouveaux projets Constellation créés avec le SDK 1.8.2 (présenté ci-dessous) sont déjà basés sur cette nouvelle version du Python Proxy, il n’y a aucune action à faire pour en profiter !

Mise à jour du SDK 1.8.2

Tout d’abord les templates des projets (C# et Python) ont été mis à jour avec les dernières versions des libraires (.NET et Python). Ainsi les nouveaux projets créés avec cette nouvelle version du SDK profiteront automatiquement des dernières versions de l’API .NET et du Python Proxy 1.8.2 décrit ci-dessus.

Lorsqu’un package est publié (en local ou directement sur un serveur Constellation), l’assistant effectuera un nettoyage de la solution avant de lancer la compilation. Cela permet de purger les fichiers qui ne sont plus utilisés dans votre package.

Autre détail fort bien utile, lorsque vous ajoutez une icone pour votre package, c’est à dire que vous ajoutez cette icone (png ou jpg) dans votre projet Visual Studio et que vous la déclarez dans le Package Manifeste, l’assistant de publication du package Constellation configuera automatique la propriété « Copy to Output directory » sur votre icone !

Suite à la sortie du Python Proxy 1.8.2, le schéma de configuration XSD de la nouvelle section <pythonProxy> décrite ci-dessus sera installée de façon à pouvoir profiter de l’IntelliSense dans Visual Studio lorsque vous éditez ce fichier.

De plus un nouvel « Item Template » nommé « Constellation Python Script » a été ajouté. Il permet de créer des scripts Constellation Python avec un template de base dans vos packages.

Dès qu’un script Constellation Python est ajouté, Visual Studio configurera automatiquement la propriété « Copy to Output directory » pour inclure votre script dans le package et ajoutera la référence de ce fichier dans la section  <pythonProxy> du fichier App.config toujours de manière automatique.

Autre : mise à jour de la Console et de la libraire .NET

Les différentes mises à jour de la Console du mois de Juin permettent de prendre en compte dynamiquement les packages uploadés via la Management API (sans devoir rafraichir la page). De plus plusieurs bugs ont été corrigés comme l’édition des settings de type boolean ou number sur les packages sans manifeste (eg. Virtual Package) ou encore un problème de la mise à jour des StateObjects qui n’étaient pas maintenus en cas de changement de page.

Aussi la libraire .NET Constellation a été mise à jour le 20 mai 2017 (1.8.2.17140) et le 29 juin (1.8.2.17178). Cela corrige un problème sur l’envoi de réponse à des sagas dans un environnement Linux/Mono et permet le déclenchement de la procédure d’arrêt (OnPreShutsown puis OnShutdown) sur les packages lancés hors sentinelle (par exemple depuis Visual Studio en phase de debug).

Retrouvez plus d’information sur le changelog.

The post Mise à jour de l’API Python et du SDK en version 1.8.2 appeared first on Constellation.

Vous pouvez mettre à jour votre installation en lançant le « Web Platform Installer » :

Constellation Web Platform Installer » Article
Constellation-Web-Platform-Installer-1.9.735.exe
Version: 1.9.735

1.2 MiB
2136 Downloads
Détails

Constellation Web Platform Installer pour Windows

Auteur:	MyConstellation.io
Plateformes:	Windows
Catégorie:	Web Platform Installers
Licence:	Constellation License Agreement
Date:	juin 15, 2020

Ou sur Linux en lançant la commande suivante :

wget -O install.sh https://developer.myconstellation.io/download/installers/install-linux.sh && chmod +x install.sh && ./install.sh

Constellation SDK 1.8.2 : support de Visual Studio 2017

La nouvelle version du SDK Constellation est désormais compatible avec toutes les éditions de Visual Studio 2012, 2013, 2015 et maintenant 2017.

Cette version embarque également une mise à jour du générateur de code pour supporter des booléens optionnels dans la signature des MC ou encore l’ajout de méthode d’extension pour les StateObjects de type générique.

Aussi, les fenêtres s’ouvrent maintenant au centre de l’instance Visual Studio et non sur l’écran principal ce qui était peu conviviale sur les environnements multi-écrans. Les templates de projet ont également été mis à jour.

Enfin avec l’arrivée de Visual Studio 2017, le programme d’installation du SDK a été révisé pour supporter cette nouvelle version ainsi que le concept de “multi-instance” de Visual Studio 2017. Vous aurez maintenant le programme “VSIX Installer” qui sera lancé automatiquement lors de l’installation pour sélectionner les instances de VS où installer le SDK Constellation.

Constellation Console 1.8.2 : plus de productivité

Cette mise à jour apporte beaucoup d’améliorations de la Console Constellation.

Déploiement des mises à jour des packages

Depuis Constellation 1.8.1, lorsqu’une mise à jour est disponible dans le catalogue en ligne, vous avez une notification avec la possibilité de télécharger la nouvelle version du package :

La nouvelle version du package est déployée dans votre repository local et c’est à vous, ensuite, de déployer manuellement cette nouvelle version sur les instances en cours de fonctionnement via le bouton “Reload”.

Désormais avec la version de 1.8.2 de la Console, une fenêtre s’ouvre automatiquement à la suite du déploiement d’une mise à jour d’un package pour vous proposer de recharger directement le ou les packages sur les sentinelles de votre Constellation où ils sont déployés :

Détachement des fenêtres

Sur toutes les pages de la Console 1.8.2, vous avez deux nouvelles icones en haut à droite :

La première icone permet de détacher la page en cours dans une pop-up et la deuxième icone permet de détacher la page en cours dans un nouvel onglet de votre navigateur.

Cela permet d’ouvrir plusieurs pages de la Console sur un même écran, pour suivre par exemple les logs, contrôler les packages, visualiser les StateObjects, etc. sans devoir changer constamment de page :

Contrôle de la compatibilité du déploiement des packages sur les sentinelles

Sur la fenêtre de déploiement d’un package, un contrôle de compatibilité est réalisé pour vous indiquer si le package est compatible avec la sentinelle sélectionnée.

Par exemple un package comme HWMonitor ou WindowsControl n’est pas compatible avec une sentinelle Linux, vous aurez donc directement l’information lors du déploiement d’un nouveau package.

Ce contrôle est basé sur les informations définies dans le manifeste du package. A charge au package de spécifier les informations de compatibilité dans leur manifeste.

Les filtres persistants

Les filtres de chaque page sont maintenant conservés lorsque l’on change puis revient sur une page (au sein d’une même session). Cela apporte plus de productivité en nous évitant de devoir constamment réappliquer les filtres lorsque l’on passe d’une page à l’autre.

Plus de réactivité

Outre les nouvelles fonctionnalités, la Console 1.8.2 apporte aussi plus de réactivité. Anciennement il y a certaines opérations comme la suppression de sentinelles ou de packages, la création d’un package virtuel, qui nécessitaient de recharger la Console (via un F5 par exemple). Désormais, les vues se mettent bien à jour en temps réel quelque soit les actions réalisées.

Il est également possible de déployer plusieurs instances d’un même package sur une même sentinelle.

Autre

En vrac :

• Extinction automatique des packages lors de la suppression d’une sentinelle
• Affichage du nombre d’élément filtré et total sur chaque page
• Limite de 500 lignes dans la Console Log et de 20 erreurs max dans la sidebar de notification pour éviter les dérives de performances
• Rafraichissement automatique du cookie d’authentification lorsque l’on est connecté (pour éviter les déconnexions au changement de page)
• Mise en forme des types génériques sur le StateObjects Explorer & MessageCallbacks Explorer
• Bugfix graphique sur le rédimensionnement de la Console log & editeur de configuration
• Mise à jour des codes snippets pour les appels HTTP (exemples pour l’API Constellation et l’API Consumer) dans le MessageCallbacks Explorer
• Appel des ressources JS/CSS et templates HTML avec le numéro de version pour éviter les problèmes de cache lors des mises à jour de la Console

Constellation Server 1.8.2 : section de configuration et compteurs de performance

Premièrement, le nom de la section de configuration “constellationSection” a été renommé en “constellation”.

Le programme d’installation du serveur 1.8.2 renommera automatiquement la section en cas de mise à jour de votre Constellation. Soyez simplement vigilant sur le fait que, désormais, la section est “<constellation>” et non “<constellationSection>”. Les schémas XSD fournis avec le SDK ainsi que l’IntelliSense du “Configuration Editor” de la Console ont été mis à jour dans ce sens.

Ensuite autre modification importante, les compteurs de performance sont activés si et seulement si la clé de configuration  “EnablePerformanceCounters” est définie à “true”.

Si la valeur est “false” ou encore si la clé n’est pas présente, les compteurs ne seront pas activés.

<appSettings>
  <add key="EnablePerformanceCounters" value="true" />
</appSettings>

Par défaut, lors d’une nouvelle installation la clé est définie à “false”. Dans le cas d’une mise à jour, la clé n’est pas ajoutée, autrement dit cette clé sera absente de votre configuration. De ce fait, les compteurs de performance sont désactivés par défaut.

C’est pourquoi, si vous souhaitez suivre les indicateurs de performance du serveur Constellation, vous devez explicitement ajouter ou modifier cette clé dans votre fichier de configuration et redémarrer le service Windows “Constellation Server”. Pour rappel, cette fonctionnalité n’est disponible que sur un environnement Windows.

N’hésitez pas à consulter le changelog complet et remonter vos feedbacks sur le forum.

The post Constellation 1.8.2 est disponible appeared first on Constellation.

Vous pouvez donc mettre à jour votre installation en lançant le « Web Platform Installer » :

Constellation Web Platform Installer » Article
Constellation-Web-Platform-Installer-1.9.735.exe
Version: 1.9.735

1.2 MiB
2136 Downloads
Détails

Constellation Web Platform Installer pour Windows

Auteur:	MyConstellation.io
Plateformes:	Windows
Catégorie:	Web Platform Installers
Licence:	Constellation License Agreement
Date:	juin 15, 2020

Ou sur Linux en lançant la commande suivante :

wget -O install.sh https://developer.myconstellation.io/download/installers/install-linux.sh && chmod +x install.sh && ./install.sh

A ce sujet, le « Web Platform Installer » pour Linux a été revu pour corriger les différents bugs remontés par la communauté.

Constellation Server 1.8.1 : ajout des compteurs de performance et nouvelle API de Management

Outre la refonte du manageur de StateObject et diverses optimisations et corrections de bugs mineurs, la nouvelle version du serveur Constellation supporte les compteurs de performance sous Windows pour pouvoir suivre l’activité du serveur.

Vous trouverez dans l’analyseur de performance Windows une nouvelle catégorie Constellation avec l’ensemble des compteurs du serveur :

L’autre grande nouveauté concerne l’API de Management. Elle met à disposition une API HTTP/REST d’édition de la configuration de votre Constellation :

• Gestion des sentinelles
• Gestion des packages
• Gestion des groupes
• Gestion des settings
• Gestion des RecoveryOptions
• Gestion des credentials et autorisations
• Gestion du Package Repository et upload de package
• Gestion de la licence
• Lire / Ecriture du fichier de configuration
• Récupération du numéro de version du serveur
• Rechargement et déploiement de la configuration

Vous trouverez sur cette page la documentation complète relative à cette API.

Constellation Sentinel 1.8.1

Les sentinelles remontent désormais au serveur des informations quant au moteur .NET utilisé et prennent en compte les changements de configuration des RecoveryOptions même si le package est déjà démarré. Aussi diverses optimisations et correctifs de bugs mineurs sont embarqués dans cette mise à jour.

Constellation Console 1.8.1 : une console vraiment complète !

C’est certainement la principale nouveauté de cette release 1.8.1 : l’évolution majeure de la Console !

Couplée à l’API de Management du serveur Constellation 1.8.1, il est désormais possible de configurer / piloter la quasi-totalité de Constellation depuis l’interface graphique de la Console sans devoir éditer le fichier de configuration XML manuellement.

De plus, cette version ajoute le catalogue en ligne de package Constellation directement dans la Console.

Gestion des sentinelles et packages

Il est maintenant possible d’ajouter, éditer ou supprimer les sentinelles depuis l’interface graphique.

De la même façon, il est possible de déployer des packages sans devoir éditer le fichier de configuration XML grâce à un assistant de déploiement :

De plus il est maintenant possible d’éditer la configuration ou les paramètres (settings) d’un package, de gérer les groupes de messages ou encore de supprimer les packages depuis l’interface de la Console :

Gestion des settings

La Console 1.8.1 rend possible l’édition des settings des packages sur base du manifeste. La Console tient compte des différentes informations contenues dans le manifeste comme les valeurs par défaut, le type du setting, son caractère obligatoire ou non, etc..

De plus l’éditeur s’adaptera en fonction du type du setting (types simples, section XML ou JSON) :

Le catalogue de package en ligne

Le catalogue de package officiel est directement intégré dans la console ce qui vous permettra de déployer des nouveaux packages ou les mises à jour sans quitter votre Console Constellation.

Gestion des crédentials et des autorisations

Il est désormais possible de gérer les crédentials depuis l’interface de la Console sans devoir éditer la configuration XML :

De plus, les autorisations sont également éditables depuis la Console :

Editeur de configuration

L’éditeur de configuration a évolué afin d’ajouter l’IntelliSense sur du base du schéma de configuration de Constellation pour simplifier l’édition bien qu’avec cette nouvelle version 1.8.1 il n’est plus tellement nécessaire de devoir éditeur ce fichier manuellement, l’interface de la Console permet la quasi-totalité des opérations.

Pour consulter le changelog complet de la version 1.8.1 :

• Release 1.8.1 (1.8.1.16259)
• Release 1.8.1 RC3 (1.8.1.16258)
• Release 1.8.1 RC2 (1.8.1.16203)
• Release 1.8.1 RC1 (1.8.1.16202)

N’hésitez pas à remonter vos feedbacks sur le forum.

The post Constellation 1.8.1 est disponible appeared first on Constellation.

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

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

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

Réception de message et StateObject “asynchrone”

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

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

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

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

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

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

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

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

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

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

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

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

Support du PackageDescriptor

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

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

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

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

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

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

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

Amélioration du PushStateObject

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

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

// Dummy data
uint16_t lux = 123;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Les StateObjectLinks

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

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

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

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

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

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

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

Par exemple, on peut désormais écrire :

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

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

Vous bien entendu enregistrer autant de StateObjectLink que vous souhaitez.

Enregistrement des MessageCallbacks

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

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

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

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

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

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

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

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

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

(console)

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

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

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

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

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

(console)

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

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

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

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

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

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

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

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

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

Support des Saga (messages avec réponse)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Autres nouveautés

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

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

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

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

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

Prérequis

La plateforme Constellation se compose :

• d’un serveur qui héberge et expose la Constellation en HTTP/s (un serveur = une Constellation)
• de sentinelles (UI ou Service) à installer sur vos différentes machines (tout système Windows ou Linux)
• d’une Console d’administration : application Web de pilotage de votre Constellation

Vous pouvez installer le serveur Constellation sur une machine Windows ou Linux, que ce soit un laptop, un desktop, un NUC, un SoC, un serveur local ou dans le Cloud.

Dans la rubrique Constellation Server vous retrouverez plusieurs articles sur les différentes installations possibles (système Linux,  Raspberry, cloud Azure ou Amazon, etc…).

Pour démarrer, nous allons déployer dans ce guide une Constellation complète (serveur, sentinelle, console et le SDK) sur une machine Windows.

Vous avez donc besoin pour suivre ce guide :

• d’un ordinateur ou serveur sous Windows (Windows 7/8/10 ou Windows Server)
• Pour installer le SDK : Visual Studio 2015, 2017 ou 2019

Si vous ne disposez pas de licence de Visual Studio, vous pouvez installer la version  “Community”, une version gratuite de Visual Studio compatible avec le SDK Constellation : https://www.visualstudio.com/fr-fr/products/visual-studio-community-vs.aspx

Télécharger la plateforme Constellation

Sur la page de téléchargement vous trouverez plusieurs programmes d’installation pour chaque composant Constellation  :

• Le serveur
• Les sentinelles (UI ou Service)
• La console
• Le SDK Visual Studio

Mais pour gagner en productivité, vous avez à votre disposition le “Web Platform Installer” (WPI), un programme d’installation tout-en-un qui télécharge automatiquement et configure les composants que vous souhaitez installer.

Commencez donc par télécharger le programme  “Constellation Web Platform Installer” pour Windows :

Constellation Web Platform Installer
Constellation-Web-Platform-Installer-1.9.735.exe
Version: 1.9.735

1.2 MiB
2136 Downloads
Détails

Constellation Web Platform Installer pour Windows

Auteur:	MyConstellation.io
Plateformes:	Windows
Catégorie:	Web Platform Installers
Licence:	Constellation License Agreement
Date:	juin 15, 2020

Installer la plateforme

Etape 1 : lancement de l’installation

Lancez le programme “Constellation Web Platform Installer.exe”

Etape 2 : identification

Vous devez dans cette étape renseigner votre compte myConstellation.io afin de pouvoir télécharger les composants Constellation et accéder à vos licences :

Etape 3 : acceptez la licence d’utilisation

Vous retrouverez le détail des licences Constellation sur cette page. Pour résumer, Constellation est gratuit pour un usage personnel ou éducatif sans aucun but lucratif et soumis à l’acquisition d’une licence pour un usage professionnel ou entreprise.

Etape 4 : choix du canal de distribution

Vous devez sélectionner le canal de distribution à utiliser : Stable ou Pre-release (versions Beta) :

Etape 5 : répertoire d’installation

Vous devez choisir le répertoire d’installation racine de la plateforme Constellation :

Etape 6 : sélectionnez les composants Constellation à installer

Vous pouvez sélectionner ici les composants à installer ou utiliser les profils prédéfinis :

• Full server installation : installation typique pour un serveur (le serveur, la sentinelle en version service et la console Constellation)
• Full developer installation : installation typique pour un poste de développement (le serveur, la sentinelle UI, la console et le SDK Visual Studio)
• Custom installation : sélectionnez à la carte les composants que vous souhaitez installer

Notez que le WPI vous indiquera la dernière version de chaque composant à installer et est capable de déployer les mises à jour pour chacun de ces composants si une nouvelle version plus récente est disponible.

Notez également que si Visual Studio n’est pas installé, le composant SDK sera grisé avec la mention “Not applicable”.

Dans ce guide, sélectionnons le profil “Développeur” :

Etape 7 : configuration du serveur Constellation

Entrons désormais dans les étapes de configuration de chacun des composants à installer en commençant par le serveur Constellation.

Etape 7.1 : sélection de la licence

Premièrement, vous devez sélectionner une licence pour l’utilisation du serveur. Vous pouvez utiliser une licence que vous aurez préalablement téléchargée depuis le portail Constellation ou  vous connecter directement sur le service de licence de Constellation depuis le WPI :

Vous obtiendrez l’ensemble des licences associées à votre compte avec la possibilité de créer des licences gratuites pour un usage personnel (plus d’information ici).

Dans notre cas créons une licence personnelle :

Etape 7.2 : choix du répertoire des packages

Dans cette étape vous devez définir le répertoire pour votre catalogue de packages de votre Constellation.

Par défaut, il s’agit du sous-dossier “Packages” de votre répertoire d’installation :

Etape 7.3 : choix du port d’écoute du serveur

Le serveur Constellation utilise le protocole HTTP pour exposer ses différents hubs et API. Pour cela vous avez besoin de choisir le port d’écoute et de l’ouvrir au niveau de votre firewall.

L’assistant peut déclarer le port que vous avez choisi dans le pare-feu de Windows. Si vous souhaitez ouvrir Constellation à l’extérieur de votre réseau local, à vous d’ouvrir le port sur votre routeur.

A noter que vous pouvez déclarer dans la configuration du serveur Constellation sur plusieurs ports HTTP et/ou HTTPS ou même définir un chemin HTTP personnalisé. Il est d’ailleurs conseillé d’activer le protocole HTTPS si vous souhaitez exposer votre serveur Constellation sur Internet. Vous retrouverez plusieurs articles sur la configuration avancée du serveur dans la rubrique Constellation Server.

Etape 7.4 : choix des clés d’accès

Pour se connecter à Constellation vous avez besoin de créer des clés d’accès (les “Access Keys”). Dans le cas d’une nouvelle installation, l’assistant vous proposera de créer deux clés :

• Une clé “Standard” (accès de base) que vous utiliserez pour connecter vos sentinelles et packages
• Une clé “Administrator” qui dispose des droits d’accès au hub de contrôle (pour le pilotage de la Constellation) et à l’API de Management (pour la configuration du serveur) :

Une clé d’accès est une chaîne de caractère. Il est conseillé de choisir des clés d’accès assez longues (> 16 caractères) et compliquées.

Pour simplifier leurs mémorisations et générations, Constellation propose d’utiliser un couple login/password pour créer des clés d’accès. Pour cela, on utilise le hash SHA1.

Exemple : pour le login “Admin” et le mot de passe “Password”, la clé d’accès sera “d882b8721a224d38ebb54559e6b54e5df3a1bc6d » (soit SHA1(“AdminPassword”)). Notez bien que la casse est importante !

Dans l’assistant d’installation, cliquez sur le bouton “Use Password” pour renseigner un couple login/password afin de générer les Access Keys :

Pour finir, vous pouvez ajouter le droit de débogage sur la clé “Administrator” en cochant la case correspondante. Cela nous permettra de tester des packages connectés à votre Constellation depuis Visual Studio.

Etape 8 : configuration de la Console Constellation

Comme la Console Constellation est déployée sur la même machine que le serveur Constellation, l’assistant vous propose héberger la console par le serveur Constellation lui-même.

Si vous désirez utiliser votre propre serveur Web pour exposer la Console (Apache, IIS ou autre) sélectionnez la deuxième option mais dans notre guide laissons le serveur Constellation héberger la console :

Vous pouvez ensuite fixer une clé d’accès en dur ou utiliser une page de login. De plus vous pouvez également restreindre l’accès à la console en local seulement.

Laissons les options par défaut (c’est à dire Console ouverte à tous avec une page de login) :

Etape 9 : configuration de la Sentinelle Constellation

Dans la sélection des composants nous avons indiqué vouloir installer la sentinelle UI. Vous arrivez donc à cette étape de configuration.

Comme la sentinelle est installée sur la même machine sur le serveur, vous pouvez l’inclure automatiquement dans votre Constellation ou bien l’inclure dans une autre Constellation en sélectionnant la deuxième option.

Dans notre cas, laissons la première option sélectionnée pour ajouter notre sentinelle UI à notre Constellation en cours d”installation :

Etape 10 : Installation

La configuration des composants est désormais terminée. Vous retrouverez tout le détail sur l’écran de confirmation :

En cliquant sur le bouton “Install”, le Web Platform Installer va télécharger les dernières versions de composants Constellation à installer :

Puis il déroulera l’installation et la configuration de chacun de ces composants :

A la fin de l’installation, l’assistant vous proposera de lancer la Console et la Sentinelle UI (car ces deux composants ont été installés) :

Etape 11 : Validation de l’installation

En fermant le programme d’installation, la sentinelle UI va être lancée :

En double-cliquant sur l’icone vous pourrez visualiser les logs de cette sentinelle qui doit être correctement connectée au serveur :

Vous aurez également la Console Constellation qui se lancera dans votre navigateur Internet par défaut :

Utilisez le Login/Password de la clé d’accès “Administrator” pour vous connecter. Sur la page “Sentinels” vous devriez voir votre sentinelle UI locale connectée :

Bravo vous avez déployé votre première Constellation avec succès !

Optionnellement : ajouter ou mettre à jour un composant

Vous pouvez à tout moment relancer le “Web Platform Installer” (WPI) pour ajouter ou mettre à jour des composants Constellation.

Ainsi quand des mises à jour Constellation sont disponibles, vous avez juste à relancer le WPI et vous laissez guider par l’assistant.

Dans notre exemple, relançons le WPI. Comme nous le montre l’écran ci-dessous, tous les composants sont bien à jour mais vous pouvez encore ajouter la “Sentinel Service” sur cette machine :

Vous entrez alors dans la configuration de la sentinelle avec la possibilité d’ajouter cette nouvelle sentinelle à votre Constellation locale (car précédemment installée) ou de l’ajouter à une autre Constellation.

Next steps

• Ajoutez des sentinelles dans votre Constellation
• Téléchargez et déployez des packages sur vos sentinelles
• Exposer votre serveur Constellation derrière avec reverse proxy IIS ou Nginx et ajouter le support du HTTPS/SSL

Vous souhaitez installer le serveur et sa console sur un système Linux ?

• Installer Constellation sur Linux

Prêt pour développer avec Constellation ?

• Créez votre premier package Constellation en C#
• Créez des packages UI en Winform ou WPF
• Connectez vos pages Web à Constellation
• Créez votre premier package Constellation en Python
• Connectez un Arduino ou un ESP8266 à Constellation

The post Installer la plateforme Constellation 1.8 appeared first on Constellation.

Introduction

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

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

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

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

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

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

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

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

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

Arduino/ESP8266 = package virtuel

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

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

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

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

Installer la librairie Constellation dans l’IDE Arduino

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

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

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

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

Hello World, Hello Constellation

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

#include <Constellation.h>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

constellation.writeInfo("Hello Constellation");

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

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

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

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

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

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

Accès aux settings

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

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

JsonObject& settings = constellation.getSettings();

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

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

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

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

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

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

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

const char* maChaine = strMaChaine.c_str();

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

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

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

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

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

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

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

Publier des StateObjects

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

constellation.pushStateObject(name, value);

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

constellation.pushStateObject(name, value, type);

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

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

constellation.pushStateObject("Temperature", 21);

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

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

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

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

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

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

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

Next steps

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

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

Dans le menu principal de gauche, cliquez sur “Sentinels” :

Vous retrouverez sur cette page l’ensemble des sentinelles de votre Constellation.

Le statut peut être :

• Unknow : une sentinelle qui ne sait jamais connectée ou une sentinelle virtuelle
• Disconnected : une sentinelle qui est déconnectée après avoir été connecté
• Connected : la sentinelle est connectée

Dans le cadre d’une sentinelle réelle (connectée ou déconnectée) vous obtiendrez également la version de la sentinelle, du système d’exploitation et autres informations sur le moteur d’execution .NET.

Le bouton “Détails” permet d’afficher l’ensemble des informations d’une sentinelle :

Il s’agit d’un menu contextuel qui vous permettra également d’éditer les informations de connexion de la sentinelle, de la supprimer ou encore de voir ou ajouter des packages sur cette sentinelle :

Ajouter une sentinelle

Pour déclarer une sentinelle réelle ou virtuelle, cliquez sur le bouton “Add sentinel” :

Dans la fenêtre d’ajout saisissez le nom de votre sentinelle ainsi que le credential à utiliser pour la connexion :

Pour ajouter et gérer vos credentials, rendez-vous sur la page “Server Management > Credentials”.

Note : dans le cas d’une sentinelle Service, le nom par défaut est le nom de la machine (hostname Linux ou Windows) et dans le cas d’une sentinelle UI (pour Windows seulement), il s’agit du nom de la machine suivi du suffixe “_UI”. Notez toutefois que vous pouvez modifier le nom de la sentinelle dans la configuration de celle-ci. De plus les installeurs Windows et Linux des sentinelles utilisent l’API de Management pour enregistrer automatiquement la sentinelle au serveur, vous n’avez donc pas à l’ajouter manuellement. Cet écran servira surtout pour l’ajout de sentinelle virtuelle.

The post Gérer les sentinelles avec la Console Constellation appeared first on Constellation.

Pour chaque package (réel) vous avez en temps réel :

• Le statut :
  • Starting : package en cours de démarrage
  • Started : package démarré et en cours de fonctionnement
  • Stopping : package en cours d’arrêt
  • Stopped : package arrêté
• L’état de connexion qui indique si le package est bien connecté au serveur
• La date de la dernière activité (il s’agit de la date de la dernière modification du statut)
• La consommation en CPU et RAM sur la sentinelle sur lequel le package est démarré
• Des informations quant à la version du package et de la librairie Constellation utilisée par le package

En fonction de l’état du package le bouton d’action permettra de démarrer le package (Start) et de l’arrêter (Stop).

Comme sur les autres pages de la Console, vous avez un menu contextuel pour chaque package vous permettant de contrôler le package, d’éditer sa configuration ou ses settings, etc.

La fenêtre d’information permet de retrouver toutes les informations sur le statut du package :

Notez également que vous avez la possibilité de filtrer dans la liste des packages soit avec la zone de texte ou soit en cliquant sur le bouton “Show filters” afin de filtrer le type de package (réel ou virtuel), l’état de connexion (connecté ou non) et l’état activé/désactivé. Par défaut tous les packages sont affichés à l’exception des packages marqués “Désactivé” (Enable=false).

Contrôler un package

Pour pouvez pour chaque package le démarrer ou l’arrêter avec le bouton d’action sur la droite ou depuis le menu contextuel.

Vous pouvez également redémarrer le package (restart) c’est à dire demander à la sentinelle de stopper le package (si il est “Started”)  puis de le démarrer.

Vous pouvez aussi faire un rechargement du package : “reload”. Cette action fonctionne comme un “restart” mais force la sentinelle à (re)télécharger le package du “Package Repository” du serveur. Cela permet de déployer les mises à jours de vos packages : vous envoyez la nouvelle version de votre package sur votre serveur Constellation puis vous faites un “reload” afin de reforcer les sentinelles à redémarrer le package avec sa nouvelle version.

Pour finir vous pouvez également “pousser” les settings vers un package en cas de modification (sans avoir à redémarrer le package).

Editer la configuration d’un package

Pour chaque package (réel ou virtuel) vous pouvez saisir le nom de l’instance (seulement lors de la création) et le credential utilisé pour la connexion du package. Vous pouvez également définir si le package est activé ou non.

S’il s’agit d’un package réel, vous pouvez définir si le package doit démarré automatiquement lorsque la sentinelle se démarre et vous pouvez également redéfinir les options de récupération :

Editer les settings d’un package

Il s’agit des paramètres propre au package (voir ici).

Pour chaque package vous définir autant de variable de configuration (= une clé et une valeur) que vous désirez en cliquant sur le bouton “Add new setting” :

Dans le cas d’un package dit “réel” il est grandement recommandé de déclarer les settings utilisés par le package dans son manifeste : voir ici.

Cette déclaration permet à la Console Constellation de connaitre les settings obligatoires ou non, le type de chaque setting, la description et valeur par défaut.

Editer les groupes d’un package

Pour rappel, un message peut être envoyé à un (ou plusieurs) groupe qui regroupe des packages ou des consommateurs. Chaque package ou consommateur peut joindre un groupe depuis les API mais vous pouvez également définir ces liens d’appartenance au niveau de la configuration du serveur.

Pour cela, cliquez sur “Group membership” dans le menu contextuel d’un page et définissez les groupes dont fait partie votre package :

Déployer un package

Pour déployer un package, vous avez plusieurs solutions :

• Cliquez sur le bouton “Deploy new package” depuis la page “Packages”
• Cliquez sur le bouton “Deploy new package” dans le menu contextuel d’une sentinelle sur la page « Sentinels »
• Utiliser la page “Package Repository”

Depuis la page des Packages, cliquez sur le bouton “Deploy new package” en haut à gauche  :

Vous obtiendrez alors une pop-in vous permettant de sélectionner la sentinelle sur laquelle déployer et le package à déployer :

S’il s’agit d’un page virtuel, sélectionnez “Virtual package” (voir ci-dessous) sinon sélectionner un package présent dans votre “Package repository”.

Vous serez alors guidé dans les étapes de configuration du package.

Note : par défaut le champ “Package file” est nul, c’est à dire que le fichier à utiliser pour votre instance sera déterminé dynamiquement (lire ici).

Dans le cas où une instance est déjà présente sur la sentinelle vous serez obligé de définir un autre nom et donc de spécifier le “Package file”.

Par exemple, ici je pourrais nommer cette nouvelle instance “HWMonitor2” en utilisant le fichier “HWMonitor”.

Veuillez lire ceci pour bien comprendre le mécanisme de résolution.

Les packages virtuels

Comme expliqué ici, un package virtuel n’est pas réel dans le sens où ce n’est pas un processus lancé et supervisé par une sentinelle.

De ce fait, dans la Console, vous n’aurez aucun information remontée à son sujet.

Vous pouvez seulement les déclarer ou supprimer, les associer à des credenitals, gérer l’appartenance aux groupes ou bien sûr gérer les settings.

The post Gérer les packages avec la Console Constellation appeared first on Constellation.