Guide d'installation avancé de VirtualHub (for Web)

Guide d'installation avancé de VirtualHub (for Web)

Vous avez pu découvrir ces dernières semaines notre nouvelle solution Web pour contrôler et surveiller à distance des systèmes Yoctopuce. Nous avions pris soin de vous fournir un outil permettant une installation en quelques clicks dans la majeur partie des cas, mais comme nous avons rapidement rencontré des utilisateurs pour lesquels cela ne suffisait pas, voici un guide d'installation un peu plus détaillé de VirtualHub (for Web).



Pour expliquer comment VirtualHub (for Web) doit être installé, il faut commencer par comprendre comment il est prévu de fonctionner.

Structure d'une installation de VirtualHub (for Web)

1. Point d'entrée


VirtualHub (for Web) est destiné à émuler (sur un serveur PHP) le comportement du VirtualHub ou d'un YoctoHub. Il doit répondre à une quantité d'URL différentes, dont la liste exacte n'est pas déterminée à l'avance. Le serveur web doit donc être configuré pour renvoyer toutes les requêtes vers un unique script PHP qui sert de point d'entrée à l'application et qui analysera l'URL demandée pour fournir la réponse appropriée. C'est le mécanisme utilisé par la plupart des CMS, comme WordPress par exemple. Il se configure par le biais d'une règle de réécriture d'URL (une URL rewrite rule en anglais).

VirtualHub (for Web) n'ayant pas la prétention d'être la seule application sur votre serveur PHP, la règle de réécriture doit être spécifique au répertoire où il est installé. De plus, nous avons d'emblée prévu que vous puissiez faire cohabiter plusieurs instances de VirtualHub (for Web) sur le même serveur, utilisant possiblement des versions différentes du code afin de pouvoir tester les nouvelles versions en pré-production. La règle de réécriture d'URL doit donc renvoyer chaque requête à la bonne instance.

Voici à quoi pourrait ressembler l'arborescence publique sur un serveur Web sur lequel on a installé VirtualHub (for Web):

Arborescence des fichiers publics du serveur Web
Arborescence des fichiers publics du serveur Web


Notez que rien n'oblige à ce que le répertoire VirtualHubs porte ce nom, ni qu'il soit posé à la racine du site Web: vous pouvez bien sûr le mettre là où vous le désirez et lui donner le nom de votre choix.

Sur un serveur Apache, la règle de ré-écriture nécessaire peut généralement être configurée très simplement en mettant dans le répertoire VirtualHubs un fichier .htaccess avec le contenu suivant:

# Redirect all URLs to index.php for VirtualHub-4web processing
RewriteEngine on
RewriteRule ^([^/]*)/.*$ $1/index.php [PT]


C'est exactement ce que fait l'installeur de VirtualHub (for Web). Cette solution a l'avantage d'être entièrement locale: vous pouvez déplacer ou renommer le répertoire VirtualHubs, et la règle de réécriture continuera de fonctionner. Mais comme des esprits chagrins vous diront que l'utilisation de fichiers .htaccess a un impact négatif sur la performance du serveur web, vous pouvez aussi si vous le préférez mettre une règle équivalente dans la configuration globale du serveur Apache:

# Redirect all URLs to index.php for VirtualHub-4web processing
RewriteEngine on
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} !-f
RewriteRule ^(/VirtualHubs/[^/]*)/.*$ $1/index.php [PT]


La configuration correspondante sur un serveur nginx serait:

rewrite ^(/VirtualHubs/[^/]*)/.*$ $1/index.php;


Sur un server Microsoft IIS, ce sera plutôt:

<rule name="VirtualHub-4web" stopProcessing="true">
  <match url="^(VirtualHubs/[^/]*)/.*$"/>
  <action type="Rewrite" url="{R:1}/index.php;"/>
</rule>


Et sur un serveur Caddy, on ajouterait au Caddyfile:

@vhub4web {
    path_regexp static ^(/VirtualHubs/[^/]*)/.*$
}
rewrite @vhub4web {re.static.1}/index.php



2. Fichiers de code et de donnée


Le point d'entrée de VirtualHub (for web) est un fichier index.php qui ne contient que quatre lignes de PHP.

  • Il définit le répertoire VHUB4WEB_CODE, où se trouve le code de l'application
  • Il définit le répertoire VHUB4WEB_DATA, où se trouvent les données spécifiques à l'instance
  • Il passe le contrôle à [VHUB4WEB_CODE]/vhub4web-init.php

Cette structure permet non seulement d'éviter de dupliquer le code pour chaque instance de VirtualHub (for web), mais aussi de faire cohabiter plusieurs versions du logiciel sur le serveur, permettant ainsi facilement de changer une instance d'une version à l'autre par le simple changement de la constante VHUB4WEB_CODE.

Voici donc à quoi ressemble une installation typique de VirtualHub (for Web), où cohabitent deux instances fonctionnant sur deux versions distinctes:

Arborescence complète
Arborescence complète



Le contenu du répertoire de code pour chaque version se résume à quatre fichiers:

  • vhub4web-init.php: le point de départ, qui définit les paramètres globaux du système et charge le code principal correspondant à la version de PHP détectée
  • vhub4web-php7.php: le code complet de VirtualHub (for Web), pour PHP 7.x
  • vhub4web-php8.php: le code complet de VirtualHub (for Web), pour PHP 8.x
  • YFSImg.yfs: les fichiers d'interface Web (pages HTML, feuilles de styles), empaquetés dans une archive monolithique

Notez que contrairement à ce que certains ont cru, les fichiers vhub4web-php*.php ne sont pas réellement les fichiers source: ce sont des bundles générés par un processus de build, qui facilitent l'installation sur le serveur et permettent un chargement de tout le code en un bloc.

Le répertoire de données de chaque instance contient une petite dizaine de fichiers dont le nom commence par VHUB4WEB, qui stockent différents aspects de l'état de l'instance de VirtualHub (for web), et un fichier .tar par module connecté à l'instance. Chacun de ces fichiers .tar stocke toutes les informations sur l'état du module concerné, y compris ses logs, les dernières valeurs de ses fonctions et l'historique des valeurs de capteurs transmises (datalogger). Il n'est pas nécessaire de configurer de gestionnaire de base de données pour utiliser VirtualHub (for Web), puisque toutes les mesures sont stockées dans ces fichiers .tar.

3. Variante d'installation simplifiée


La structure décrite ci-dessus correspond à l'installation en mode avancé proposée par l'installeur: c'est celle que nous utilisons le plus.

Pour les cas où l'utilisateur voudrait garder à un unique endroit tous les fichiers nécessaires au fonctionnement de VirtualHub (for Web), l'installeur propose aussi un mode simplifié (Basic), où tous les fichiers sont posés dans l'arborescence publique sur le serveur Web:

  • VHUB4WEB_CODE pointe alors sur le répertoire racine de toutes les instances;
  • VHUB4WEB_DATA pointe directement sur le répertoire de l'instance.

Une limitation importante de cette configuration simplifiée est que les instances partagent toutes nécessairement la même version du code.

Configuration des callbacks HTTP


Le seul type de callback HTTP qui offre les fonctions nécessaire à VirtualHub (for Web) est le callback Yocto-API. Pour la version PHP (la seule qui soit disponible pour l'instant), il faut utiliser une URL de type http:// pointant sur l'instance spécifique, avec comme suffixe HTTPCallback. Par exemple:

    http://my.server.example.com/VirtualHubs/production/HTTPCallback



Pour vous assurer que seuls vos hubs puissent se connecter à votre instance, utilisez la fenêtre de configuration du VirtualHub-4web pour définir un Incoming HTTP Yocto-API Callback password (MD5 Signature). Une fois configuré, seuls les callbacks HTTP signés avec ce mot de passe seront pris en compte. Vous devez donc au niveau du hub faire la configuration correspondante:

Sécurisation des callbacks HTTP
Sécurisation des callbacks HTTP


La fréquence des callbacks HTTP est un autre élément important à choisir en fonction de votre application. L'intervalle entre les callbacks peut varier typiquement de dix secondes à une ou deux heures, selon les besoins. Mais attention, si vous utilisez une transmission cellulaire, des transmissions trop fréquentes pourraient vous coûter cher!

Si le but est simplement de remonter des mesures pour les afficher à l'aide de Yocto-Visualization (for Web), la fréquence détermine directement le taux de rafraîchissement pour l'affichage des mesures. Par contre, grâce au fait que le YoctoHub est capable de mémoriser des mesures entre les callbacks HTTP, vous pouvez parfaitement utiliser un callback par minute et obtenir des graphiques de mesure avec un point toutes les dix secondes: il vous suffit pour cela de configurer la fréquence des mesures à "6/m" (six par minutes), et l'intervalle des callbacks à 60 secondes. Chaque minute, six nouveaux points apparaîtront simultanément dans le graphique.

Si votre graphique comporte des trous, c'est probablement que vous avez dépassé la capacité de stockage de mesures du hub. Un YoctoHub est capable de mémoriser environ 150 mesures, donc lorsque vous lui en demandez trop, les mesures les plus anciennes sont perdues. La cause la plus fréquente de ce problème de trous est le fait que d'autres capteurs coonnectés au hub, que vous n'utilisez peut-être même pas, envoient des mesures chaque seconde - c'est le réglage d'usine. Pour chaque module connecté à votre hub, prenez donc soin d'ouvrir l'interface de configuration des fréquences de mesures et désactivez ou ralentissez si nécessaire l'envoi (Reporting) de mesures vers le hub pour les capteurs qui ne vous sont pas utiles:

Fréquence d'envoi des mesures par les capteurs
Fréquence d'envoi des mesures par les capteurs



Pour vous aider à optimiser la fréquence des callbacks par rapport à la capacité de stockage du hub, vous pouvez utiliser les données statistiques collectées par VirtualHub (for Web): en cliquant sur le numéro de série VHUB4WEB-xxxx dans la liste des modules, vous obtenez la liste des hubs qui ce connectent sur cette instance. A côté de chaque hub, un bouton view stats permet d'obtenir des informations précises sur l'intervalle effectif entre les callbacks et le taux d'utilisation du tampon de stockage de mesures du hub. Lorsque le taux d'utilisation dépasse 100%, cela signifie que des mesures ont été perdues, et qu'il vous faut soit réduire le nombre de mesures transmises par les capteurs, soit rapprocher les callbacks HTTP proportionnellement au dépassement.

Statistiques d'utilisation du tampon de mesures
Statistiques d'utilisation du tampon de mesures



Cette fenêtre de statistiques comporte d'autres onglets, qui vous permettront aussi d'anticiper l'ordre de grandeur du coût en terme de données envoyées et reçues, ou de diagnostiquer des éventuelles anomalies de comportements des modules (nombre de modules connectés, redémarrages à froid, etc.)

Comportements déroutants


Bien que l'utilisation conjointe de Yocto-Visualization (for Web) et VirtualHub (for Web) soit généralement assez intuitive, l'utilisation directe de l'interface de VirtualHub (for Web) peut paraître parfois être un peu... étrange.

Il faut bien réaliser que les informations sur les modules affichées dans l'interface Web sont toujours basées sur le dernier état connu du module, lors du précédent callback HTTP. Mais lorsque vous faites un changement de configuration sur un module via cette interface (par exemple si vous changez la fréquence de transmission des mesures), ce changement ne sera appliqué au module que lors du prochain callback HTTP. Donc en attendant le prochain callback HTTP, c'est toujours l'état antérieur à votre changement qui est affiché, comme si votre réglage avait été ignoré. Ce n'est qu'un peu plus tard que votre changement apparaîtra effectivement sur l'interface.

Nous travaillons actuellement à une modification de l'interface qui évite cette bizarrerie et permette de voir alternativement l'état anticipé du module après application des changements de configuration ou le dernier état confirmé. Mais pour l'instant, soyez simplement avertis de cette problématique, et ne vous en inquiétez pas. Vous pouvez toujours si besoin aller consulter la liste des changements de configuration prévus d'être envoyés au hub dans l'onglet de la fenêtre de statistiques qui chiffre les données transmises et reçues.

Commenter aucun commentaire Retour au blog












Yoctopuce, get your stuff connected.