Comment débuter en PHP avec des modules Yoctopuce

Comment débuter en PHP avec des modules Yoctopuce

Cette semaine, nous poursuivons notre série d'articles "pour les débutants" et nous allons parler de PHP. Les scripts PHP sont très faciles à utiliser et à déployer. Nous allons voir qu'il est aussi facile d'interfacer les modules Yoctopuce depuis un script PHP.




Nous partons du principe que vous connaissez un minimum PHP et que vous êtes capable d'écrire et déployer sur un serveur Web un script PHP. Le but de cet article n'est pas écrire un cours sur PHP mais d'apprendre à utiliser les modules Yoctopuce dans un script PHP. De la même manière, si vous n'est pas familier avec les modules Yoctopuce, nous vous recommandons de commencer par la lecture des précédents articles de cette série en particulier celui sur la structure logique des modules Yoctopuce.

Les particularités de PHP


Il est impossible d'accéder directement aux périphériques USB depuis un script. Un script PHP peut interagir uniquement avec des modules Yoctopuce qui sont branchés à un YoctoHub ou à un ordinateur qui exécute un VirtualHub. Les communications entre le script PHP et les modules Yoctopuce passent par une connexion TCP entre le YoctoHub et le serveur qui exécute le script PHP. Les YoctoHubs transmettent ensuite les requêtes aux modules concernés.

Il est toutefois possible d’utiliser des modules branchés par USB sur le serveur qui exécute le script PHP, pour autant que cette machine ait installé l'application VirtualHub. Dans ce cas, le script PHP communique avec le VirtualHub en utilisant l'interface loopback du serveur et le VirtualHub transmet les requêtes aux modules correspondant.

La communication entre le script PHP et le module Yoctopuce passe obligatoirement par TCP
La communication entre le script PHP et le module Yoctopuce passe obligatoirement par TCP



Installation


La première chose à faire consiste à installer la librairie Yoctopuce pour PHP. Vous pouvez télécharger la librairie depuis le site de Yoctopuce ou depuis GitHub. L'archive contient trois répertoires. Le répertoire Documentation contient la documentation, le répertoire Sources les fichiers de la librairie et le répertoire Examples des exemples d'utilisation de la librairie.

Pour installer la librairie sur votre serveur web, il faut copier les fichiers qui se trouvent dans Sources sur votre serveur web, dans un répertoire accessible par votre script PHP. Pour inclure la librairie dans votre script, il suffit d'inclure ces fichiers à l'aide de la fonction include ou require.

Un petit exemple


Nous allons réaliser un petit script PHP qui va simplement afficher la température de la salle serveur à l'aide d'un Yocto-Temperature branché sur un port USB du serveur web.

Le VirtualHub


Comme le script PHP ne peut pas accéder directement au port USB, il faut installer et lancer le VirtualHub sur le serveur pour que le Yocto-Temperature soit disponible par TCP. La procédure pour installer le VirutalHub est expliquée dans cet article.

Les imports


La première chose à faire consiste à inclure les bons fichiers PHP dans le script. Nous avons besoin d'inclure l'indispensable "yocto_api.php" qui permet d'utiliser la librairie, mais aussi de "yocto_temperature.php" qui permet d'utiliser le capteur de température.

Notre script PHP commence donc par le code suivant:

require_once('Sources/yocto_api.php');
require_once('Sources/yocto_temperature.php');



Dans cette exemple, nous supposons que les fichiers de la librairie se trouvent dans le sous-répertoire Source, mais si vous avez copié ces fichiers dans un autre répertoire, il faut simplement remplacer "Sources/" par le chemin d'accès correspondant.

Établir la connexion avec le VirtualHub


Pour pouvoir accéder aux modules, il faut indiquer à la librairie l’adresse du YoctoHub ou du VirtualHub à l'aide de la méthode YAPI::RegisterHub. Dans cet exemple, le Yocto-Temperature est branché sur la même machine, on peut donc utiliser l’adresse "127.0.0.1".

YAPI::RegisterHub("127.0.0.1");


Vous trouverez plus de détails sur les divers usages de YAPI::RegisterHub dans cet autre article.


Récupération de l'objet YTemperature


Comme vous avez lu l'article sur la structure logique des modules Yoctopuce, vous savez que le Yocto-Temperature offre différentes fonctionnalités parmi lesquelles on trouve temperature.

Pour récupérer l'objet qui permet d’interagir avec cette fonctionnalité, il y a plusieurs manières.

FirstXXX


Si vous êtes sûr de n'avoir qu'une seule fonctionnalité temperature disponible, vous pouvez faire au plus simple et utiliser la méthode FirstTemperature de la classe YTemperature.

$ytemp = YTemperature::FirstTemperature();
if(is_null($ytemp)) {
    die("No temperature sensor found");
}


Les méthodes FirstXXXX renvoient la première occurrence de la fonctionnalité cherchée, ou null si rien ne correspond.

FindXXX et numéro de série


Vous pouvez aussi utiliser les méthodes FindTemperature de la classe YTemperature avec le numéro de série du module. Supposons que le numéro de série du Yocto-Temperature soit TMPSENS1-019CB, vous pouvez utiliser:

$ytemp = YTemperature::FindTemperature("TMPSENS1-019CB.temperature");
if (!$ytemp->isOnline()) {
  die("No temperature sensor found");
}


A la différence de FirstXXX, FindXXX renvoie toujours un objet valide, c'est pourquoi il faut tester s'il correspond bien à un module connecté avec la méthode isOnline().

FindXXX et nom logique


A la place du numéro de série, vous pouvez utiliser un nom logique que vous aurez par exemple affecté à l'aide du VirtualHub.

Affectation d'un nom logique au capteur du Yocto-Temperature
Affectation d'un nom logique au capteur du Yocto-Temperature


Mettons que vous ayez appelé le capteur de température "myTemp". Il vous suffira alors d'écrire:

$ytemp = YTemperature::FindTemperature("myTemp");
if (!$ytemp->isOnline()) {
  die("No temperature sensor found");
}


L'intérêt des noms logiques est double: d'une part ils permettent de s'y retrouver plus facilement dans les systèmes complexes composés de nombreux modules Yoctopuce et d'autre part ils permettent de fabriquer des systèmes en plusieurs exemplaires sans avoir à adapter le code aux numéros de séries des modules de chaque exemplaire.

Utiliser l'objet YTemperature


Maintenant que l'on a récupéré l'objet YTemperature, il ne reste qu'à afficher la température en récupérant la valeur courante à l'aide de la méthode get_currentValue() et get_unit()

$value = $ytemp->get_currentValue();
$unit = $ytemp->get_unit();
Print("<h2>Temperature: $value $unit</h2>");



Stopper la librairie


Avant de terminer le script il faut appeler la méthode YAPI::FreeAPI qui va libérer toutes les ressources utilisées par la librairie mais surtout s'assurer que toutes les communications soient terminées correctement.

YAPI::FreeAPI();



Une fois tout mis bout à bout, notre script minimaliste ressemble à ceci:

<!DOCTYPE html>
<html lang="en">
<body>
<?php
require_once('Sources/yocto_api.php');
require_once('Sources/yocto_temperature.php');
YAPI::RegisterHub("127.0.0.1");
$ytemp = YTemperature::FirstTemperature();
if(is_null($ytemp)) {
    die("No temperature sensor found");
}
$value = $ytemp->get_currentValue();
$unit = $ytemp->get_unit();
Print("<h2>Temperature: $value $unit</h2>");
YAPI::FreeAPI();
?>
</body>
</html>



Quelques remarques


YSensor


Notre exemple ne gère que les capteurs de température, mais il est possible de le faire fonctionner avec n'importe quel senseur Yoctopuce en modifiant quelques lignes: Il suffit d'utiliser la classe YSensor à la place de la classe YTemperature:

<!DOCTYPE html>
<html lang="en">
<body>
<?php
require_once('Sources/yocto_api.php');

YAPI::RegisterHub("127.0.0.1");
$ysensor = YSensor::FirstSensor();
if(is_null($ysensor)) {
    die("No sensor found");
}
$value = $ysensor->get_currentValue();
$unit = $ysensor->get_unit();
Print("<h2>Sensor: $value $unit</h2>");
YAPI::FreeAPI();
?>
</body>
</html>



Avec cette version du code, le script PHP fonctionnera avec n'importe quel senseur Yoctopuce. C'est possible car toutes les classes Yoctopuce correspondant à des fonctionnalités de type senseur héritent de la classe YSensor. Les méthodes get_currentValue() et get_unit() sont implémentées dans cette classe et fonctionnent sur n'importe quel senseur.

La gestions des erreurs


Par défaut, si une erreur se produit, les fonctions de la librairie lance une exception de type YAPI_Exception.

Sans traitement particulier, l'erreur est affichée sur la page web
Sans traitement particulier, l'erreur est affichée sur la page web



Pour gérer les erreurs et afficher un message correctement formaté, il existe deux solutions. On peut attraper les exceptions à l'aide de blocs try {} catch().
Par exemple comme ceci:

try {
    YAPI::RegisterHub("127.0.0.1");
} catch (YAPI_Exception $ex) {
    die("Erreur:" . $ex->getMessage());
}



Mais il est aussi possible de désactiver la génération des exceptions par la librairie PHP à l'aide de la méthode "YAPI::DisableExceptions". Dans ce cas, il faut tester la valeur de retour de chaque appel à la librairie.

YAPI::DisableExceptions();
$errmsg='';
$res = YAPI::RegisterHub("127.0.0.1", $errmsg);
if ($res != YAPI_SUCCESS) {
    die("Erreur:" . $errmsg);
}



Ces deux solutions permettent de traiter correctement les erreurs et d'afficher un message clair. L'utilisation de l'une ou l'autre est surtout une question d'habitudes de programmation.

La suite...


Notre librairie PHP peut fonctionner dans deux modes: le mode direct et le mode callback HTTP. Le script que nous venons de réaliser fonctionne en mode direct, c'est-à-dire que c'est le script PHP qui établit la connexion TCP avec le YoctoHub ou le VirtualHub. Ce mode est simple à configurer et toutes les fonctionnalités de la libraire Yoctopuce peuvent être utilisé.

Cependant, il existe un autre mode, le mode callback HTTP qui fonctionne différemment: C'est le YoctoHub qui contacte le script PHP. Ce mode est particulièrement utile pour les scénarios où plusieurs senseurs sont répartis dans différents lieux. Mais ce sujet sera traité dans un prochain article car celui-ci est déjà bien assez long.

Commenter aucun commentaire Retour au blog












Yoctopuce, get your stuff connected.