Yocto-maxiknob : manuel d'utilisation

Yocto-MaxiKnob : Manuel d'utilisation

1. Introduction
1.1 Informations de sécurité
1.2 Conditions environnementales
2. Présentation
2.1 Les éléments communs
2.2 Les éléments spécifiques
2.3 Accessoires optionnels
3. Premiers pas
3.1 Prérequis
3.2 Test de la connectivité USB
3.3 Localisation
3.4 Test du module
3.5 Configuration
4. Montage et connectique
4.1 Fixation
4.2 Configuration matérielle
4.3 Connecter les entrées AnButton
4.4 Multiplexage de boutons sur les entrées AnButton
4.5 Connecter les entrées pour encodeur en quadratures
4.6 Ajouter des LEDs
4.7 Consommation
4.8 Contraintes d'alimentation par USB
4.9 Compatibilité électromagnétique (EMI)
5. Programmation, concepts généraux
5.1 Paradigme de programmation
5.2 Le module Yocto-MaxiKnob
5.3 Module
5.4 Buzzer
5.5 AnButton
5.6 QuadratureDecoder
5.7 ColorLedCluster
5.8 Les espaces de couleurs: RGB et HSL
5.9 Les séquences
5.10 Quelle interface: Native, DLL ou Service?
5.11 Accéder aux modules à travers un hub
5.12 Programmation, par où commencer?
6. Utilisation du Yocto-MaxiKnob en ligne de commande
6.1 Installation
6.2 Utilisation: description générale
6.3 Contrôle de la fonction AnButton
6.4 Contrôle de la partie module
6.5 Limitations
7. Utilisation du Yocto-MaxiKnob en Python
7.1 Fichiers sources
7.2 Librairie dynamique
7.3 Contrôle de la fonction AnButton
7.4 Contrôle de la partie module
7.5 Gestion des erreurs
8. Utilisation du Yocto-MaxiKnob en C++
8.1 Contrôle de la fonction AnButton
8.2 Contrôle de la partie module
8.3 Gestion des erreurs
8.4 Intégration de la librairie Yoctopuce en C++
9. Utilisation du Yocto-MaxiKnob en C#
9.1 Installation
9.2 Utilisation l'API yoctopuce dans un projet Visual C#
9.3 Contrôle de la fonction AnButton
9.4 Contrôle de la partie module
9.5 Gestion des erreurs
10. Utilisation du Yocto-MaxiKnob avec LabVIEW
10.1 Architecture
10.2 Compatibilité
10.3 Installation
10.4 Présentation des VIs Yoctopuce
10.5 Fonctionnement et utilisation des VIs
10.6 Utilisation des objets Proxy
10.7 Gestion du datalogger
10.8 Énumération de fonctions
10.9 Un mot sur les performances
10.10 Un exemple complet de programme LabVIEW
10.11 Différences avec les autres API Yoctopuce
11. Utilisation du Yocto-MaxiKnob en Java
11.1 Préparation
11.2 Contrôle de la fonction AnButton
11.3 Contrôle de la partie module
11.4 Gestion des erreurs
12. Utilisation du Yocto-MaxiKnob avec Android
12.1 Accès Natif et VirtualHub
12.2 Préparation
12.3 Compatibilité
12.4 Activer le port USB sous Android
12.5 Contrôle de la fonction AnButton
12.6 Contrôle de la partie module
12.7 Gestion des erreurs
13. Utilisation du Yocto-MaxiKnob en TypeScript
13.1 Utiliser la librairie Yoctopuce pour TypeScript
13.2 Petit rappel sur les fonctions asynchrones en JavaScript
13.3 Contrôle de la fonction AnButton
13.4 Contrôle de la partie module
13.5 Gestion des erreurs
14. Utilisation du Yocto-MaxiKnob en JavaScript / EcmaScript
14.1 Fonctions bloquantes et fonctions asynchrones en JavaScript
14.2 Utiliser la librairie Yoctopuce pour JavaScript / EcmaScript 2017
14.3 Contrôle de la fonction AnButton
14.4 Contrôle de la partie module
14.5 Gestion des erreurs
15. Utilisation du Yocto-MaxiKnob en PHP
15.1 Préparation
15.2 Contrôle de la fonction AnButton
15.3 Contrôle de la partie module
15.4 API par callback HTTP et filtres NAT
15.5 Gestion des erreurs
16. Utilisation du Yocto-MaxiKnob en VisualBasic .NET
16.1 Installation
16.2 Utilisation l'API yoctopuce dans un projet Visual Basic
16.3 Contrôle de la fonction AnButton
16.4 Contrôle de la partie module
16.5 Gestion des erreurs
17. Utilisation du Yocto-MaxiKnob en Delphi / Lazarus
17.1 Préparation
17.2 Contrôle de la fonction AnButton
17.3 Contrôle de la partie module
17.4 Gestion des erreurs
18. Utilisation du Yocto-MaxiKnob avec Universal Windows Platform
18.1 Fonctions bloquantes et fonctions asynchrones
18.2 Installation
18.3 Utilisation l'API Yoctopuce dans un projet Visual Studio
18.4 Contrôle de la fonction AnButton
18.5 Un exemple concret
18.6 Contrôle de la partie module
18.7 Gestion des erreurs
19. Utilisation du Yocto-MaxiKnob en Objective-C
19.1 Contrôle de la fonction AnButton
19.2 Contrôle de la partie module
19.3 Gestion des erreurs
20. Utilisation avec des langages non supportés
20.1 Utilisation en ligne de commande
20.2 Assembly .NET
20.3 Virtual Hub et HTTP GET
20.4 Utilisation des librairies dynamiques
20.5 Port de la librairie haut niveau
21. Programmation avancée
21.1 Programmation par événements
22. Mise à jour du firmware
22.1 Le VirtualHub ou le YoctoHub
22.2 La librairie ligne de commandes
22.3 L'application Android Yocto-Firmware
22.4 La librairie de programmation
22.5 Le mode "mise à jour"
23. Référence de l'API de haut niveau
23.1 La classe YAPI
23.2 La classe YModule
23.3 La classe YAnButton
23.4 La classe YQuadratureDecoder
23.5 La classe YBuzzer
23.6 La classe YColorLedCluster
24. Problèmes courants
24.1 Par où commencer ?
24.2 Linux et USB
24.3 Plateformes ARM: HF et EL
24.4 Les exemples de programmation n'ont pas l'air de marcher
24.5 Module alimenté mais invisible pour l'OS
24.6 Another process named xxx is already using yAPI
24.7 Déconnexions, comportement erratique
24.8 Le module ne marche plus après une mise à jour ratée
24.9 RegisterHub d'une instance de VirtualHub déconnecte la précédente
24.10 Commandes ignorées
24.11 Module endommagé
25. Caractéristiques
26. Index

1. Introduction

Le Yocto-MaxiKnob est un module électronique de 50x58mm qui permet de mesurer l'état de multiples interrupteurs, boutons poussoir, potentiomètres et/ou d'encodeurs en quadrature. Il est aussi équipé d'un petit buzzer et d'une LED RGB avec la possibilité d'en piloter beaucoup plus. Ce module a été conçu pour offrir une méthode simple et compacte de créer des panneaux de commande.


Le module Yocto-MaxiKnob

Le Yocto-MaxiKnob n'est pas en lui-même un produit complet. C'est un composant destiné à être intégré dans une solution d'automatisation en laboratoire, ou pour le contrôle de procédés industriels, ou pour des applications similaires en milieu résidentiel ou commercial. Pour pouvoir l'utiliser, il faut au minimum l'installer à l'intérieur d'un boîtier de protection et le raccorder à un ordinateur de contrôle.

Yoctopuce vous remercie d'avoir fait l'acquisition de ce Yocto-MaxiKnob et espère sincèrement qu'il vous donnera entière satisfaction. Les ingénieurs Yoctopuce se sont donné beaucoup de mal pour que votre Yocto-MaxiKnob soit facile à installer n'importe où et soit facile à piloter depuis un maximum de langages de programmation. Néanmoins, si ce module venait à vous décevoir, ou si vous avez besoin d'informations supplémentaires, n'hésitez pas à contacter Yoctopuce:

Adresse e-mail:support@yoctopuce.com
Site Internet:www.yoctopuce.com
Adresse postale:Route de Cartigny 33
Localité:1236 Cartigny
Pays:Suisse

1.1. Informations de sécurité

Le Yocto-MaxiKnob est conçu pour respecter la norme de sécurité IEC 61010-1:2010. Il ne causera pas de danger majeur pour l'opérateur et la zone environnante, même en condition de premier défaut, pour autant qu'il soit intégré et utilisé conformément aux instructions contenues dans cette documentation, et en particulier dans cette section.

Boîtier de protection

Le Yocto-MaxiKnob ne doit pas être utilisé sans boîtier de protection, en raison des composants électriques à nu. Pour une sécurité optimale, il devrait être mis dans un boîtier non métallique, non-inflammable, résistant à un choc de 5 J, par exemple en polycarbonate (LEXAN ou autre) d'indice de protection IK08 et classifié V-1 ou mieux selon la norme IEC 60695-11-10. L'utilisation d'un boîtier de qualité inférieure peut nécessiter des avertissements spécifiques pour l'utilisateur et/ou compromettre la conformité avec la norme de sécurité.

Entretien

Si un dégat est constaté sur le circuit électronique ou sur le boîtier, il doit être remplacé afin de ne pas compromettre la sécurité d'utilisation et d'éviter d'endommager d'autres parties du système par les surcharges éventuelles que pourrait causer un court-circuit.

Identification

Pour faciliter l'entretien du circuit et l'identification des risques lors de la maintenance, vous devriez coller l'étiquette autocollante synthétique identifiant le Yocto-MaxiKnob, fournie avec le circuit électronique, à proximité immédiate du module. Si le module est dans un boîtier dédié, l'étiquette devrait être collée sur la surface extérieur du boîtier. L'étiquette est résistante à l'humidité et au frottement usuel qui peut survenir durant un entretien normal.


L'étiquette d'identification est intégrée à l'étiquette de l'emballage.

Applications

La norme de sécurité vérifiée correspond aux instruments de laboratoire, pour le contrôle de procédés industriels, ou pour des applications similaires en milieu résidentiel ou commercial. Si vous comptez l'utiliser le Yocto-MaxiKnob pour un autre type d'applications, vous devrez vérifier les critères de conformité en fonction de la norme applicable à votre application.

En particulier, le Yocto-MaxiKnob n'est pas certifié pour utilisation dans un environnement médical, ni pour les applications critiques à la santé, ni pour toute autre application menaçant la vie humaine.

Environnement

Le Yocto-MaxiKnob n'est pas certifié pour utilisation dans les zones dangereuses, ni pour les environnements explosifs. Les conditions environnementales assignées sont décrites ci-dessous.

Classe de protection III (IEC 61140)

Le module Yocto-MaxiKnob a été conçu pour travailler uniquement avec des très basses tension de sécurité. Ne dépassez pas les tensions indiquées dans ce manuel, et ne raccordez en aucun cas sur le bornier du Yocto-MaxiKnob un fil susceptible d'être connecté au réseau secteur.

1.2. Conditions environnementales

Les produits Yoctopuce sont conçus pour une utilisation intérieure dans un environnement usuel de bureau ou de laboratoire (degré de pollution 2 selon IEC 60664): la pollution de l'air doit être faible et essentiellement non conductrice. L'humidité relative prévue est de 10% à 90% RH, sans condensation. L'utilisation dans un environnement avec une pollution solide ou conductrice significative exige de protéger le module contre cette pollution par un boîtier certifié IP67 ou IP68. Les produits sont conçus pour une utilisation jusqu'à une altitude de 2000m.

Le fonctionnement de tous les modules Yoctopuce est garanti conforme à la documentation et aux spécifications de précision pour des conditions de température ambiante normales selon IEC61010-1, soit 5°C à 40°C. De plus, la plupart des modules peuvent aussi être utilisés sur une plage de température étendue, à laquelle quelques limitations peuvent s'appliquer selon les cas.

La plage de température de fonctionnement étendue du Yocto-MaxiKnob est -20...70°C. Cette plage de température a été déterminée en fonction des recommandations officielles des fabricants des composants utilisés dans le Yocto-MaxiKnob, et par des tests de durée limitée (1h) dans les conditions extrêmes, en environnement controllé. Si vous envisagez d'utiliser le Yocto-MaxiKnob dans des conditions de température extrêmes pour une période prolongée, il est recommandé de faire des tests extensifs avant la mise en production.

2. Présentation


1:Prise USB 8:Entrée encodeur en quadrature 1
2:Yocto-bouton 9:Entrée encodeur en quadrature 2
3:Yocto-LED 10:Entrée analogique 1
4:MicroSwitchs de configuration11:Entrée analogique 2
5:Buzzer 12:Bouton test canal 1
6:LED RGB 13:LED témoin canal 1
7:Sortie LED RGB

2.1. Les éléments communs

Tous les Yocto-modules ont un certain nombre de fonctionnalités en commun.

Le connecteur USB

Les modules de Yoctopuce sont tous équipés d'une connectique USB 2.0 au format micro-B. Attention, le connecteur USB est simplement soudé en surface et peut être arraché si la prise USB venait à faire levier. Si les pistes sont restées en place, le connecteur peut être ressoudé à l'aide d'un bon fer et de flux. Alternativement, vous pouvez souder un fil USB directement dans les trous espacés de 1.27mm prévus à cet effet, prêt du connecteur.

Si vous utilisez une source de tension autre qu'un port USB hôte standard pour alimenter le module par le connecteur USB, vous devez respecter les caractéristiques assignées par le standard USB 2.0:

En cas de tension supérieure, le module risque fort d'être détruit. En cas de tension inférieure, le comportement n'est pas déterminé, mais il peut conduire à une corruption du firmware.

Le Yocto-bouton

Le Yocto-bouton a deux fonctions. Premièrement, il permet d'activer la Yocto-balise (voir la Yocto-led ci-dessous). Deuxièmement, si vous branchez un Yocto-module en maintenant ce bouton appuyé, il vous sera possible de reprogrammer son firmware avec une nouvelle version. Notez qu'il existe une méthode plus simple pour mettre à jour le firmware depuis l'interface utilisateur, mais cette méthode-là peut fonctionner même lorsque le firmware chargé sur le module est incomplet ou corrompu.

La Yocto-Led

En temps normal la Yocto-Led sert à indiquer le bon fonctionnement du module: elle émet alors une faible lumière bleue qui varie lentement mimant ainsi une respiration. La Yocto-Led cesse de respirer lorsque le module ne communique plus, par exemple s'il est alimenté par un hub sans connexion avec un ordinateur allumé.

Lorsque vous appuyez sur le Yocto-bouton, la Led passe en mode Yocto-balise: elle se met alors à flasher plus vite et beaucoup plus fort, dans le but de permettre une localisation facile d'un module lorsqu'on en a plusieurs identiques. Il est en effet possible de déclencher la Yocto-balise par logiciel, tout comme il est possible de détecter par logiciel une Yocto-balise allumée.

La Yocto-Led a une troisième fonctionnalité moins plaisante: lorsque ce logiciel interne qui contrôle le module rencontre une erreur fatale, elle se met à flasher SOS en morse1. Si cela arrivait débranchez puis rebranchez le module. Si le problème venait à se reproduire vérifiez que le module contient bien la dernière version du firmware, et dans l'affirmative contactez le support Yoctopuce2.

La sonde de courant

Chaque Yocto-module est capable de mesurer sa propre consommation de courant sur le bus USB. La distribution du courant sur un bus USB étant relativement critique, cette fonctionnalité peut être d'un grand secours. La consommation de courant du module est consultable par logiciel uniquement.

Le numéro de série

Chaque Yocto-module a un numéro de série unique attribué en usine, pour les modules Yocto-MaxiKnob ce numéro commence par YMXBTN01. Le module peut être piloté par logiciel en utilisant ce numéro de série. Ce numéro de série ne peut pas être changé.

Le nom logique

Le nom logique est similaire au numéro de série, c'est une chaîne de caractères sensée être unique qui permet référencer le module par logiciel. Cependant, contrairement au numéro de série, le nom logique peut être modifié à volonté. L'intérêt est de pouvoir fabriquer plusieurs exemplaires du même projet sans avoir à modifier le logiciel de pilotage. Il suffit de programmer les mêmes noms logiques dans chaque exemplaire. Attention, le comportement d'un projet devient imprévisible s'il contient plusieurs modules avec le même nom logique et que le logiciel de pilotage essaye d'accéder à l'un de ces module à l'aide de son nom logique. A leur sortie d'usine, les modules n'ont pas de nom logique assigné, c'est à vous de le définir.

2.2. Les éléments spécifiques

Les entrées analogiques

Le module Yocto-MaxiKnob met à disposition jusqu'à 12 entrées auxquelles il est possible de connecter tout type de capteur résistif tel qu'un interrupteur, bouton poussoir, potentiomètres, photo-transistor, contact reed, etc. Vous pouvez utiliser n'importe quelle valeur de potentiomètre entre 1KΩ et 200KΩ

Votre module Yocto-MaxiKnob est capable de mesurer si les boutons poussoirs et les interrupteurs qui lui sont raccordés sont ouverts ou fermés. Il est aussi capable de mesurer la position relative des potentiomètres qui lui sont reliés. En fait, le module se contente de mesurer la résistance de chaque circuit qui est raccordé.

Le circuit de mesure est un circuit de très basse tension de sécurité (TBTS). Il ne doit pas être connecté à une quelconque source de tension, mais uniquement être raccordé à des composants passifs. Il ne doit en aucun cas être mis en commun avec un circuit d'alimentation réseau.

Potentiomètres et calibration

Ce module vous permet d'utiliser une grande plage de valeurs de potentiomètres. Mais pour qu'il vous donne des mesures cohérentes pour le modèle de potentiomètre que vous utiliserez, vous devrez calibrer les canaux correspondant. Cela peut être fait très simplement grâce l'interface de configuration. Il n'est pas nécessaire de faire une calibration si vous utilisez de simples interrupteurs ou encore des boutons poussoirs.

Les entrées pour encodeurs en quadrature

Le module Yocto-MaxiKnob met à disposition jusqu'à 6 entrées pour encodeur en quadrature. Un encodeur en quadrature se présente généralement sous la forme d'un bouton rotatif sans butée, qui génère des impulsions différentes en fonction du sens de rotation. Le Yocto-MaxiKnob est capable de compter ces impulsions et donc de calculer les changements de position du bouton. Notez qu'un encodeur en quadrature est un capteur de position relatif: il permet des connaître tous les changements de position, mais pas la position de départ.

Entrées analogiques vs encodeur en quadrature

Vous pouvez avoir un maximum de 12 entrées analogiques ou de 6 entrées pour encodeurs en quadrature. Chaque couple d'entrée analogique peut être converti en une entrée pour encodeurs en quadrature ce qui explique cette limitation. Le choix de la répartition entre entrées analogiques et encodeurs en quadrature se fait grâce aux trois micro-interrupteurs présents sur le Yocto-MaxiKnob. Un redémarrage du module est nécessaire pour qu'un changement de configuration soit pris en compte.


Position des entrées analogiques et entrées pour encodeur en quadrature.

Le buzzer

Le buzzer embarqué par le module Yocto-MaxiKnob est capable de générer un son entre 25Hz et 5000Hz. Le volume peut être contrôlé explicitement, cependant la fréquence choisie a elle aussi une influence importante sur le volume sonore maximum que peut générer le buzzer. L'API Yoctopuce permet de pré-programmer des petites mélodies simples, sous forme de séquences, qui pourront être jouées sans intervention extérieure.

La LED RGB

Cette LED a la particularité de pouvoir émettre simultanément trois couleurs différentes: rouge, vert et bleu. Il s'agit en fait de trois LEDs distinctes logées dans le même boîtier. En modulant précisément la puissance de chacune ces trois LEDs, le module peut créer à peu près n'importe quelle couleur, blanc compris.

La sortie pour LEDs RGB

Cette sortie permet de connecter des LEDs RGB supplémentaires. Les LEDs RGB utilisées dans le Yocto-MaxiKnob sont des LED dites "intelligentes" (smart LED) qui peuvent être chaînées. Ces LEDs sont conçues pour recevoir en entrée un signal de commande numérique qu'elles sont capables d'interpréter puis de rediriger sur leur sortie vers les LEDs suivantes de la chaîne. Cette technologie permet de chaîner un nombre important de ces LEDs avec seulement trois fils: Masse, 5V, et signal. Le Yocto-MaxiKnob peut piloter jusqu'à 150 LEDs simultanément, sous réserve du courant disponible sur le port USB. Le contrôleur de LED est compatible avec les LEDs RGB WS2812B, WS2812C, SK6812, WS2811, et les LEDs RGBW SK6812RGBW, ce qui permet de l'utiliser avec des nombreux dispositifs basés sur ces LEDs3 Pour plus de détails, voir les schémas du chapitre Montage et connectique.

2.3. Accessoires optionnels

Les accessoires ci-dessous ne sont pas nécessaires à l'utilisation du module Yocto-MaxiKnob, mais pourraient vous être utiles selon l'utilisation que vous en faites. Il s'agit en général de produits courants que vous pouvez vous procurer chez vos fournisseurs habituels de matériel de bricolage. Pour vous éviter des recherches, ces produits sont en général aussi disponibles sur le shop de Yoctopuce.

Vis et entretoises

Pour fixer le module Yocto-MaxiKnob à un support, vous pouvez placer des petites vis de 3mm avec une tête de 8mm au maximum dans les trous prévus ad-hoc. Il est conseillé de les visser dans des entretoises filetées, que vous pourrez fixer sur le support. Vous trouverez plus de détail à ce sujet dans le chapitre concernant le montage et la connectique.

Micro-hub USB

Si vous désirez placer plusieurs modules Yoctopuce dans un espace très restreint, vous pouvez les connecter ensemble à l'aide d'un micro-hub USB. Yoctopuce fabrique des hubs particulièrement petits précisément destinés à cet usage, dont la taille peut être réduite à 20mm par 36mm, et qui se montent en soudant directement les modules au hub via des connecteurs droits ou des câbles nappe. Pour plus de détails, consulter la fiche produit du micro-hub USB.

YoctoHub-Ethernet, YoctoHub-Wireless and YoctoHub-GSM

Vous pouvez ajouter une connectivité réseau à votre Yocto-MaxiKnob grâce aux hubs YoctoHub-Ethernet, YoctoHub-Wireless et YoctoHub-GSM qui offrent respectivement une connectivité Ethernet, Wifi et GSM. Chacun de ces hubs peut piloter jusqu'à trois modules Yoctopuce et se comporte exactement comme un ordinateur normal qui ferait tourner VirtualHub.

Connecteurs 1.27mm (ou 1.25mm)

Si vous désirez raccorder le module Yocto-MaxiKnob à un Micro-hub USB ou a un YoctoHub en évitant l'encombrement d'un vrai cable USB, vous pouvez utiliser les 4 pads au pas 1.27mm juste derrière le connecteur USB. Vous avez alors deux possibilités.

Vous pouvez monter directement le module sur le hub à l'aide d'un jeu de vis et entretoises, et les connecter à l'aide de connecteurs board-to-board au pas 1.27mm. Pour éviter les court-circuits, soudez de préférence le connecteur femelle sur le hub et le connecteur mâle sur le Yocto-MaxiKnob.

Vous pouvez aussi utiliser un petit câble à 4 fils doté de connecteurs au pas 1.27mm (ou 1.25mm, la différence est négligeable pour 4 pins), ce qui vous permet de déporter le module d'une dizaine de centimètres. N'allongez pas trop la distance si vous utilisez ce genre de câble, car il n'est pas blindé et risque donc de provoquer des émissions électromagnétiques indésirables.

Boîtier

Votre Yocto-MaxiKnob a été conçu pour pouvoir être installé tel quel dans votre projet. Néanmoins Yoctopuce commercialise des boîtiers spécialement conçus pour les modules Yoctopuce. Vous trouverez plus d'informations à propos de ces boîtiers sur le site de Yoctopuce4. Le boîtier recommandé pour votre Yocto-MaxiKnob est le modèle YoctoBox-MaxiIO-Transp


Vous pouvez installer votre Yocto-MaxiKnob dans un boîtier optionnel.

Câble de servo et broche

Si vous désirez ajouter des LEDs du module Yocto-MaxiKnob, vous pouvez câbler l'ensemble en utilisant du câble de servo-moteur de modélisme, et des broches, coudées ou non, espacées de 2.54mm.


Vous pouvez utiliser du câble de servo pour câbler les LEDs supplémentaires

Panneau et ruban de RGB

Le Yocto-MaxiKnob peut contrôler simultanément jusqu'à 150 LEDs RGB numériques, pour autant que ce soit des modèles WS2812B, WS2812C, SK6812, WS2811 (RGB) ou SK6812RGBW (RGBW). Vous trouverez dans le commerce des dispositifs équipés de ces LEDs sous forme de ruban, panneau, barrette ou encore d'anneau. Yoctopuce ne vend pas ce genre d'accessoires mais vous en trouverez par exemple chez Adafruit5 sous la marque NEOPIXEL.

3. Premiers pas

Par design, tous les modules Yoctopuce se pilotent de la même façon, c'est pourquoi les documentations des modules de la gamme sont très semblables. Si vous avez déjà épluché la documentation d'un autre module Yoctopuce, vous pouvez directement sauter à la description de sa configuration.

3.1. Prérequis

Pour pouvoir profiter pleinement de votre module Yocto-MaxiKnob, vous devriez disposer des éléments suivants.

Un ordinateur

Les modules de Yoctopuce sont destinés à être pilotés par un ordinateur (ou éventuellement un microprocesseur embarqué). Vous écrirez vous-même le programme qui pilotera le module selon vos besoins, à l'aide des informations fournies dans ce manuel.

Yoctopuce fourni les librairies logicielles permettant de piloter ses modules pour les systèmes d'exploitation suivants: Windows, Linux, macOS et Android. Les modules Yoctopuce ne nécessitent pas l'installation de driver (ou pilote) spécifiques, car ils utilisent le driver HID6 fourni en standard dans tous les systèmes d'exploitation.

La règle générale concernant les versions de système d'exploitation supportées est la suivante: les outils de développement Yoctopuce sont supportés pour toutes les versions couvertes par le support de l'éditeur du système d'exploitation, y compris la durée du support étendu (long term support ou LTS). Yoctopuce attache une attention particulière au support à long terme, et lorsque c'est possible avec un effort raisonnable, nos outils sont construits de sorte à pouvoir être utilisés sur des anciens systèmes même plusieurs années encore après la fin du support étendu par le fabricant.

De plus, les librairies de programmation pour piloter nos modules étant disponibles en code source, il vous est en généralement possible de les recompiler pour fonctionner sur des systèmes d'exploitation encore plus anciens. A ce jour, notre librairie de programmation peut toujours être compilée pour fonctionner sur des systèmes d'exploitation publiés en 2008, tels que Windows XP SP3 ou Linux Debian Squeeze.

Les architectures supportées par les librairies logicielles de Yoctopuce sont les suivantes:

Sous Linux, la communication avec nos modules USB requiert impérativement la librairie libusb en version 1.0 ou plus récente, qui est disponible sur toutes les distributions courantes. Les librairies et les outils en ligne de commande devraient pouvoir être facilement recompilés sur n'importe quelle variante d'UNIX (Linux, FreeBSD, ...) datant des quinze dernières années pour laquelle libusb-1.0 est disponible et fonctionnel.

Sous Android, la possibilité de connecter un module USB dépend du fait que la tablette ou le téléphone supporte le mode USB Host.

Un cable USB 2.0 de type A-micro B

Il existe plusieurs formes de connecteurs USB. La taille "normale" correspond à celle que vous utilisez probablement pour brancher votre imprimante. La taille "mini" a plus ou moins disparu. La taille "micro" était la plus petite au moment où les modules Yoctopuce sont apparus, et c'est toujours celle que nous utilisons. Depuis quelques années, des connecteurs USB-C sont apparus, mais pour ne pas multiplier le type de connecteurs dans notre gamme de produit, nous sommes pour l'instant resté au standard "micro-B".


Les connecteurs USB 2.0 les plus courants: A, B, Mini B, Micro B et USB-C.

Pour connecter votre module Yocto-MaxiKnob à un ordinateur, vous avez donc besoin d'un cable USB 2.0 de type A-micro B. Vous trouverez ce cable en vente à des prix très variables selon les sources, sous la dénomination USB A to micro B Data cable. Prenez garde à ne pas acheter par mégarde un simple câble de charge, qui ne fournirait que le courant mais sans les fils de données. Le bon câble est disponible sur le shop de Yoctopuce.


Vous devez raccorder votre module Yocto-MaxiKnob à l'aide d'un cable USB 2.0 de type A - micro B

Si vous branchez un hub USB entre l'ordinateur et le module Yocto-MaxiKnob, prenez garde à ne pas dépasser les limites de courant imposées par USB, sous peine de faire face des comportements instables non prévisibles. Vous trouverez plus de détails à ce sujet dans le chapitre concernant le montage et la connectique.

3.2. Test de la connectivité USB

Arrivé à ce point, votre Yocto-MaxiKnob devrait être branché à votre ordinateur, qui devrait l'avoir reconnu. Il est temps de le faire fonctionner.

Rendez-vous sur le site de Yoctopuce et téléchargez le programme VirtualHub7, Il est disponible pour Windows, Linux et macOS. En temps normal le programme VirtualHub sert de couche d'abstraction pour les langages qui ne peuvent pas accéder aux couches matérielles de votre ordinateur. Mais il offre aussi une interface sommaire pour configurer vos modules et tester les fonctions de base, on accède à cette interface à l'aide d'un simple browser web 8. Lancez VirtualHub en ligne de commande, ouvrez votre browser préféré et tapez l'adresse http://127.0.0.1:4444. Vous devriez voir apparaître la liste des modules Yoctopuce raccordés à votre ordinateur.


Liste des modules telle qu'elle apparaît dans votre browser.

3.3. Localisation

Il est alors possible de localiser physiquement chacun des modules affichés en cliquant sur le bouton beacon, cela a pour effet de mettre la Yocto-Led du module correspondant en mode "balise", elle se met alors à clignoter ce qui permet de la localiser facilement. Cela a aussi pour effet d'afficher une petite pastille bleue à l'écran. Vous obtiendrez le même comportement en appuyant sur le Yocto-bouton d'un module.

3.4. Test du module

La première chose à vérifier est le bon fonctionnement de votre module: cliquez sur le numéro de série correspondant à votre module, et une fenêtre résumant les propriétés de votre Yocto-MaxiKnob.


Propriétés du module Yocto-MaxiKnob.

Cette fenêtre vous permet entre autres de tester les entrées du Yocto-MaxiKnob, de tester le buzzer en changeant la fréquence et le volume, et de changer la couleur des LEDs RGB.

3.5. Configuration

Si, dans la liste de modules, vous cliquez sur le bouton configure correspondant à votre module, la fenêtre de configuration apparaît.


Configuration du module Yocto-MaxiKnob.

Firmware

Le firmware du module peut être facilement mis à jour à l'aide de l'interface. Les firmwares destinés aux modules Yoctopuce se présentent sous la forme de fichiers .byn et peuvent être téléchargés depuis le site web de Yoctopuce.

Pour mettre à jour un firmware, cliquez simplement sur le bouton upgrade de la fenêtre de configuration et suivez les instructions. Si pour une raison ou une autre, la mise à jour venait à échouer, débranchez puis rebranchez le module. Recommencer la procédure devrait résoudre alors le problème. Si le module a été débranché alors qu'il était en cours de reprogrammation, il ne fonctionnera probablement plus et ne sera plus listé dans l'interface. Mais il sera toujours possible de le reprogrammer correctement en utilisant le programme VirtualHub9 en ligne de commande 10.

Nom logique du module

Le nom logique est un nom choisi par vous, qui vous permettra d'accéder à votre module, de la même manière qu'un nom de fichier vous permet d'accéder à son contenu. Un nom logique doit faire au maximum 19 caractères, les caractères autorisés sont les caractères A..Z a..z 0..9 _ et -. Si vous donnez le même nom logique à deux modules raccordés au même ordinateur, et que vous tentez d'accéder à l'un des modules à l'aide de ce nom logique, le comportement est indéterminé: vous n'avez aucun moyen de savoir lequel des deux va répondre.

Luminosité

Ce paramètre vous permet d'agir sur l'intensité maximale des leds présentes sur le module. Ce qui vous permet, si nécessaire, de le rendre un peu plus discret tout en limitant sa consommation. Notez que ce paramètre agit sur toutes les leds de signalisation du module, y compris la Yocto-Led. Si vous branchez un module et que rien ne s'allume, cela veut peut être dire que sa luminosité a été réglée à zéro.

Nom logique des fonctions

Chaque module Yoctopuce a un numéro de série, et un nom logique. De manière analogue, chaque fonction présente sur chaque module Yoctopuce a un nom matériel et un nom logique, ce dernier pouvant être librement choisi par l'utilisateur. Utiliser des noms logiques pour les fonctions permet une plus grande flexibilité au niveau de la programmation des modules

En fonction de la configuration matériel 8 à 14 fonctions sont disponibles sur le Yocto-MaxiKnob: un Buzzer, qui correspond au buzzer embarqué sur le module, un ColorLedCluster qui permet de manipuler les LEDs RGB, et zéro a douze AnButton qui correspondent aux entrées analogiques et zéro à 6 QuadratureDecoder qui correspondent aux entrée pour décodeurs en quadrature. Plus il y a de décodeurs en quadrature activés, moins il y a d'entrées analogiques puisque les deux types de fonction partagent les mêmes contacts physiques d'entrée.

La fonction ColorLedCluster

La fonction ColorLedCluster permet de contrôler un nombre arbitraire de LEDs RGB, jusqu'à 150 LEDs au maximum. Si la fonction est configurée pour piloter plus de LEDs qu'effectivement connectées, cela ne causera pas de problème majeur. Cependant, plus il y a de LEDs à piloter, plus le processeur du module est mis à contribution. Avec ce paramètre réglé au maximum, de légères saccades pourraient apparaître lors de transitions automatiques. Il n'est donc pas forcément souhaitable de configurer le module pour piloter des LED qui n'existent pas.

Couleur au démarrage

Le module peut mémoriser une couleur de démarrage pour chaque LED. Cliquez simplement sur le carré coloré correspondant à la LED à configurer pour obtenir une palette de couleurs. Il est aussi possible d'utiliser la couleur courante des LEDs comme couleur de démarrage.

Une application de cette fonction consiste à configurer la couleur de démarrage des LEDs à l'aide d'un ordinateur, et ensuite d'alimenter le module à l'aide d'un simple chargeur USB. Vous pouvez ainsi facilement fabriquer un éclairage dont la couleur est configurable.

4. Montage et connectique

Ce chapitre fournit des explications importantes pour utiliser votre module Yocto-MaxiKnob en situation réelle. Prenez soin de le lire avant d'aller trop loin dans votre projet si vous voulez éviter les mauvaises surprises.

4.1. Fixation

Pendant la mise au point de votre projet vous pouvez vous contenter de laisser le module se promener au bout de son câble. Veillez simplement à ce qu'il ne soit pas en contact avec quoi que soit de conducteur (comme vos outils). Une fois votre projet pratiquement terminé il faudra penser à faire en sorte que vos modules ne puissent pas se promener à l'intérieur.


Exemples de montage sur un support.

Le module Yocto-MaxiKnob dispose de trous de montage 3mm. Vous pouvez utiliser ces trous pour y passer des vis. Le diamètre de la tête de ces vis ne devra pas dépasser 8mm, sous peine d'endommager les circuits du module. Veillez à que la surface inférieure du module ne soit pas en contact avec le support. La méthode recommandée consiste à utiliser des entretoises, mais il en existe d'autres. Rien ne vous empêche de le fixer au pistolet à colle; ça ne sera pas très joli mais ça tiendra.

4.2. Configuration matérielle

Le nombre d'entrées analogique et d'entrées pour encodeurs en quadrature est déterminé par la position des micro-interrupteurs présents sur le module. Le nombre d'entrées analogiques plus le nombre d'entrée pour encodeurs en quadrature fois deux est toujours égal à douze. Pour les deux type de fonctions, la numérotation est fixe mais commence à des côtés opposés


Configuration des micro-interrupteurs

Après un changement de position des micro-interrupteurs le module doit être suivi d'un redémarrage pour que la nouvelle configuration soit prise en compte.

4.3. Connecter les entrées AnButton

Les entrées analogiques anButton se trouvent sur les headers coudés 2x12 positions. Tous les contacts de la rangée du bas sont en commun avec la masse du module. Chaque contact de la rangée du haut correspond à une entrée. La fonction AnButton1 se trouve sur le côté opposé à la LED RGB. Vous pouvez utiliser les entrées AnButton pour mesurer l'état d'interrupteurs, boutons poussoirs, interrupteurs à lame souple, photo-transistors, potentiomètres, etc. Pour la mesure de potentiomètres, si vous avez le choix, utilisez de préférence des potentiomètres avec une valeur de 10KΩ. Sinon, n'importe quelle valeur entre 1KΩ et 200KΩ fera l'affaire.


Exemples de connexion d'interrupteur, boutons poussoir, potentiomètres..

4.4. Multiplexage de boutons sur les entrées AnButton

Si nécessaire, vous pouvez multiplexer jusqu'à quatre interrupteurs ou boutons poussoirs par entrée analogique à l'aide de résistances externes. En configurant l'entrée en mode "digitale 4 bits" dans la configuration du module, celui-ci effectuera directement la correspondance entre la valeur de résistance mesurée et la position des quatres boutons binaires. Pour cela, raccordez-les selon le schéma ci-dessous:


Multiplexage d'entrées on/off sur une entrée analogique

Utilisez impérativement des résistances 1%, et utilisez des fils aussi courts que possible, en paire torsadée avec le fil de terre. Méfiez-vous néanmoins du fait qu'un tel multiplexage rend le système plus sensible aux perturbations électromagnétiques, en particulier pour l'entrée binaire liée à la valeur de résistance la plus faible.

4.5. Connecter les entrées pour encodeur en quadratures

Un encodeur en quadrature est généralement constitué d'une partie rotative qui actionne deux interrupteurs qui s'ouvrent et se ferment avec un léger décalage au fur et à mesure que la partie mobile tourne, pas par pas. Le nombre de pas par rotation est fixe et dépend du modèle d'encodeur. Un encodeur a généralement trois sorties: A, B et Common. Pour connecter un encodeur sur le Yocto-MaxiKnob, branchez A et B sur les contacts du haut et Common sur l'un des contacts du bas.


Exemple de connexion d'un encodeur en quadrature

Pour vérifier que l'encodeur en quadrature est bien branché, vérifiez que si vous faites tourner très lentement le bouton vous voyez les LEDs s'allumer puis s'éteindre en décalage, l'une après l'autre. Si les deux s'allument ou éteignent simultanément sur l'un des flancs, c'est probablement que vous avez croisé le commun avec l'une des entrées A ou B.

Si le compteur décroit quand vous voudriez qu'il croisse, ou vice-versa, vous pouvez simplement croiser les entrées A et B. S'il augmente de plus de pas par cran de rotation que vous ne le désirez, vous pouvez configurer un diviseur dans l'interface du Yocto-MaxiKnob.

Certains encodeurs disposent en plus d'une fonctionnalité bouton poussoir que vous pourrez connecter à une entrée anButton.

4.6. Ajouter des LEDs

Le module Yocto-MaxiKnob dispose d'une sortie qui vous permet de rajouter des LED RGB au système. De nombreux vendeurs en propose sous forme de rubans, barrettes, panneaux etc. Vous pouvez même ré-utiliser les sous-modules LED d'un Yocto-Color-V211.


Le module Yocto-MaxiKnob dispose d'une sortie pour piloter des LED supplémentaires

Plusieurs solutions s'offrent à vous pour connecter des modules LED supplémentaires: vous pouvez raccorder des modules en soudant des fils électriques tout simples, c'est la solution la plus accessible mais c'est loin d'être la plus pratique. Le module met à disposition trois trous avec un espacement standard de 2.54mm. Vous pourrez y souder un bornier12. Vous pouvez aussi utiliser des broches coudées au pas 2.54mm et des cables de servo-moteur de modélisme.


Exemple de câblage des modules LED à l'aide de câbles de servos

Le raccordement entre modules LED se fait entre à l'aide de 3 fils: Signal, 5V, et masse. Sur le Yocto-MaxiKnob, la masse est indiquée par la signalétique GND.

Attention, les modules LED doivent être connectés en série, c'est-à-dire chaînés. Chaque module LED a une entrée et une sortie, chaque sortie d'un module LED doit être connectée à l'entrée du module suivant LED. La longueur de câblage entre deux modules LED voisins doit être inférieure à 1 mètre.


Attention à la polarité et au sens des modules LED, chacun a une entrée et une sortie.

Vous pouvez aussi connecter n'importe quel dispositif de LED basé sur les les modèles WS2812B, WS2812C, SK6812, WS2811 (RGB) ou SK6812RGBW (RGBW) jusqu'à concurrence de 150 LEDs distinctes.


Le Yocto-MaxiKnob est capable de piloter de nombreuses LEDs

Il n'y a pas de moyen logiciel direct de savoir combien LEDs sont raccordées au module de contrôle; mais il est possible de se faire une idée en testant les variations de consommation du module: si vous donnez l'ordre d'allumer une LED et que la consommation augmente, cela signifie que la LED correspondante est présente.

4.7. Consommation

Une LED RGB peut facilement consommer jusqu' à 45mA lorsqu'elle émet une lumière blanche à pleine puissance. Cependant, un module USB n'est pas censé consommer plus de 500 mA. Le Yocto-MaxiKnob est lui-même capable de dépasser cette limite de 500mA, mais il va se mettre à chauffer. C'est pourquoi, si souhaitez utiliser beaucoup de LEDs et pensez que vous allez largement dépasser les 500mA, il est conseillé d'utiliser une alimentation externe, câblée selon l'illustration ci-dessous.


Câblage avec une alimentation externe

Chacun de ces modules LED dits intelligents contient un petit processeur et est accompagné d'un petit condensateur SMD, généralement soudé juste à côté de la LED, qui sert à assurer une alimentation raisonnablement stable. Si un grand nombre de modules LED est branché d'un seul coup à un Yocto-MaxiKnob déjà sous tension, la brève baisse de tension due au fort appel de courant causé par les nombreux condensateurs en parallèle peut faire redémarrer le Yocto-MaxiKnob. Ce comportement est normal.

4.8. Contraintes d'alimentation par USB

Bien que USB signifie Universal Serial BUS, les périphériques USB ne sont pas organisés physiquement en bus mais en arbre, avec des connections point-à-point. Cela a des conséquences en termes de distribution électrique: en simplifiant, chaque port USB doit alimenter électriquement tous les périphériques qui lui sont directement ou indirectement connectés. Et USB impose des limites.

En théorie, un port USB fournit 100mA, et peut lui fournir (à sa guise) jusqu'à 500mA si le périphérique les réclame explicitement. Dans le cas d'un hub non-alimenté, il a droit à 100mA pour lui-même et doit permettre à chacun de ses 4 ports d'utiliser 100mA au maximum. C'est tout, et c'est pas beaucoup. Cela veut dire en particulier qu'en théorie, brancher deux hub USB non-alimentés en cascade ne marche pas. Pour cascader des hubs USB, il faut utiliser des hubs USB alimentés, qui offriront 500mA sur chaque port.

En pratique, USB n'aurait pas eu le succès qu'il a s'il était si contraignant. Il se trouve que par économie, les fabricants de hubs omettent presque toujours d'implémenter la limitation de courant sur les ports: ils se contentent de connecter l'alimentation de tous les ports directement à l'ordinateur, tout en se déclarant comme hub alimenté même lorsqu'ils ne le sont pas (afin de désactiver tous les contrôles de consommation dans le système d'exploitation). C'est assez malpropre, mais dans la mesure où les ports des ordinateurs sont eux en général protégés par une limitation de courant matérielle vers 2000mA, ça ne marche pas trop mal, et cela fait rarement des dégâts.

Ce que vous devez en retenir: si vous branchez des modules Yoctopuce via un ou des hubs non alimentés, vous n'aurez aucun garde-fou et dépendrez entièrement du soin qu'aura mis le fabricant de votre ordinateur pour fournir un maximum de courant sur les ports USB et signaler les excès avant qu'ils ne conduisent à des pannes ou des dégâts matériels. Si les modules sont sous-alimentés, ils pourraient avoir un comportement bizarre et produire des pannes ou des bugs peu reproductibles. Si vous voulez éviter tout risque, ne cascadez pas les hubs non-alimentés, et ne branchez pas de périphérique consommant plus de 100mA derrière un hub non-alimenté.

Pour vous faciliter le contrôle et la planification de la consommation totale de votre projet, tous les modules Yoctopuce sont équipés d'une sonde de courant qui indique (à 5mA près) la consommation du module sur le bus USB.

Notez enfin que le câble USB lui-même peut aussi représenter une cause de problème d'alimentation, en particulier si les fils sont trop fins ou si le câble est trop long 13. Les bons câbles utilisent en général des fils AWG 26 ou AWG 28 pour les fils de données et des fils AWG 24 pour les fils d'alimentation.

4.9. Compatibilité électromagnétique (EMI)

Les choix de connectique pour intégrer le Yocto-MaxiKnob ont naturellement une incidence sur les émissions électromagnétiques du système, et donc sur la conformité avec les normes concernées.

Les mesures de référence que nous effectuons pour valider la conformité avec la norme IEC CISPR 11 sont faites sans aucun boîtier, mais en raccordant les modules par un câble USB blindé, conforme à la spécification USB 2.0: le blindage du câble est relié au blindage des deux connecteurs, et la résistance totale entre le blindage des deux connecteurs est inférieure 0.6Ω. Le câble utilisé fait 3m, de sorte à exposer un segment d'un mètre horizontal, un segment d'un mètre vertical et de garder le dernier mètre le plus proche de l'ordinateur hôte à l'intérieur d'un bloc de ferrite.

Si vous utilisez un câble non blindé ou incorrectement blindé, votre système fonctionnera sans problème mais vous risquez de n'être pas conforme à la norme. Dans le cadre de systèmes composés de plusieurs modules raccordés par des câbles au pas 1.27mm, ou de capteurs déportés, vous pourrez en général récupérer la conformité avec la norme d'émission en utilisant un boîtier métallique offrant une enveloppe de blindage externe.

Toujours par rapport aux normes de compatibilité électromagnétique, la longueur maximale supportée du câble USB est de 3m. En plus de pouvoir causer des problèmes de chute de tension, l'utilisation de câbles plus long aurait des incidences sur les tests d'immunité électromagnétique à effectuer pour respecter les normes.

5. Programmation, concepts généraux

L'API Yoctopuce a été pensée pour être à la fois simple à utiliser, et suffisamment générique pour que les concepts utilisés soient valables pour tous les modules de la gamme Yoctopuce et ce dans tous les langages de programmation disponibles. Ainsi, une fois que vous aurez compris comment piloter votre Yocto-MaxiKnob dans votre langage de programmation favori, il est très probable qu'apprendre à utiliser un autre module, même dans un autre langage, ne vous prendra qu'un minimum de temps.

5.1. Paradigme de programmation

L'API Yoctopuce est une API orientée objet. Mais, dans un souci de simplicité, seules les bases de la programmation objet ont été utilisées. Même si la programmation objet ne vous est pas familière, il est peu probable que cela vous soit un obstacle à l'utilisation des produits Yoctopuce. Notez que vous n'aurez jamais à allouer ou désallouer un objet lié à l'API Yoctopuce: cela est géré automatiquement.

Il existe une classe par type de fonctionnalité Yoctopuce. Le nom de ces classes commence toujours par un Y suivi du nom de la fonctionnalité, par exemple YTemperature, YRelay, YPressure, etc.. Il existe aussi une classe YModule, dédiée à la gestion des modules en temps que tels, et enfin il existe la classe statique YAPI, qui supervise le fonctionnement global de l'API et gère les communications à bas niveau.


Structure de l'API Yoctopuce.

La classe YSensor

A chaque fonctionnalité d'un module Yoctopuce, correspond une classe: YTemperature pour mesurer la température, YVoltage pour mesurer une tension, YRelay pour contrôler un relais, etc. Il existe cependant une classe spéciale qui peut faire plus: YSensor.

Cette classe YSensor est la classe parente de tous les senseurs Yoctopuce, elle permet de contrôler n'importe quel senseur, quel que soit son type, en donnant accès au fonctions communes à tous les senseurs. Cette classe permet de simplifier la programmation d'applications qui utilisent beaucoup de senseurs différents. Mieux encore, si vous programmez une application basée sur la classe YSensor, elle sera compatible avec tous les senseurs Yoctopuce, y compris ceux qui n'existent pas encore.

Programmation

Dans l'API Yoctopuce, la priorité a été mise sur la facilité d'accès aux fonctionnalités des modules en offrant la possibilité de faire abstraction des modules qui les implémentent. Ainsi, il est parfaitement possible de travailler avec un ensemble de fonctionnalités sans jamais savoir exactement quel module les héberge au niveau matériel. Cela permet de considérablement simplifier la programmation de projets comprenant un nombre important de modules.

Du point de vue programmation, votre Yocto-MaxiKnob se présente sous la forme d'un module hébergeant un certain nombre de fonctionnalités. Dans l'API , ces fonctionnalités se présentent sous la forme d'objets qui peuvent être retrouvés de manière indépendante, et ce de plusieurs manières.

Accès aux fonctionnalités d'un module

Accès par nom logique

Chacune des fonctionnalités peut se voir assigner un nom logique arbitraire et persistant: il restera stocké dans la mémoire flash du module, même si ce dernier est débranché. Un objet correspondant à une fonctionnalité Xxx munie d'un nom logique pourra ensuite être retrouvée directement à l'aide de ce nom logique et de la méthode YXxx.FindXxx. Notez cependant qu'un nom logique doit être unique parmi tous les modules connectés.

Accès par énumération

Vous pouvez énumérer toutes les fonctionnalités d'un même type sur l'ensemble des modules connectés à l'aide des fonctions classiques d'énumération FirstXxx et nextXxxx disponibles dans chacune des classes YXxx.

Accès par nom hardware

Chaque fonctionnalité d'un module dispose d'un nom hardware, assigné en usine qui ne peut être modifié. Les fonctionnalités d'un module peuvent aussi être retrouvées directement à l'aide de ce nom hardware et de la fonction YXxx.FindXxx de la classe correspondante.

Différence entre Find et First

Les méthodes YXxx.FindXxxx et YXxx.FirstXxxx ne fonctionnent pas exactement de la même manière. Si aucun module n'est disponible YXxx.FirstXxxx renvoie une valeur nulle. En revanche, même si aucun module ne correspond, YXxx.FindXxxx renverra objet valide, qui ne sera pas "online" mais qui pourra le devenir, si le module correspondant est connecté plus tard.

Manipulation des fonctionnalités

Une fois l'objet correspondant à une fonctionnalité retrouvé, ses méthodes sont disponibles de manière tout à fait classique. Notez que la plupart de ces sous-fonctions nécessitent que le module hébergeant la fonctionnalité soit branché pour pouvoir être manipulées. Ce qui n'est en général jamais garanti, puisqu'un module USB peut être débranché après le démarrage du programme de contrôle. La méthode isOnline(), disponible dans chaque classe, vous sera alors d'un grand secours.

Accès aux modules

Bien qu'il soit parfaitement possible de construire un projet en faisant abstraction de la répartition des fonctionnalités sur les différents modules, ces derniers peuvent être facilement retrouvés à l'aide de l'API. En fait, ils se manipulent d'une manière assez semblable aux fonctionnalités. Ils disposent d'un numéro de série affecté en usine qui permet de retrouver l'objet correspondant à l'aide de YModule.Find(). Les modules peuvent aussi se voir affecter un nom logique arbitraire qui permettra de les retrouver ensuite plus facilement. Et enfin la classe YModule comprend les méthodes d'énumération YModule.FirstModule() et nextModule() qui permettent de dresser la liste des modules connectés.

Interaction Function / Module

Du point de vue de l'API, les modules et leurs fonctionnalités sont donc fortement décorrélés à dessein. Mais l'API offre néanmoins la possibilité de passer de l'un à l'autre. Ainsi la méthode get_module(), disponible dans chaque classe de fonctionnalité, permet de retrouver l'objet correspondant au module hébergeant cette fonctionnalité. Inversement, la classe YModule dispose d'un certain nombre de méthodes permettant d'énumérer les fonctionnalités disponibles sur un module.

5.2. Le module Yocto-MaxiKnob

Le module Yocto-MaxiKnob offre une instance de colorLedCluster permettant de controler une chaîne de leds RGB. Il offre aussi douze instances de la fonction anButton correspondant aux entrées analogiques, ces fonctions anButton peuvent aussi être converties en QuadratureDecoder à l'aide du micro- interrupteur placé sur la carte. Il y a aussi une instance de la fonction buzzer permettant de controler le haut-parleur.

module : Module

attributtypemodifiable ?
productName  Texte  lecture seule
serialNumber  Texte  lecture seule
logicalName  Texte  modifiable
productId  Entier (hexadécimal)  lecture seule
productRelease  Entier (hexadécimal)  lecture seule
firmwareRelease  Texte  lecture seule
persistentSettings  Type énuméré  modifiable
luminosity  0..100%  modifiable
beacon  On/Off  modifiable
upTime  Temps  lecture seule
usbCurrent  Courant consommé (en mA)  lecture seule
rebootCountdown  Nombre entier  modifiable
userVar  Nombre entier  modifiable

anButton1 : AnButton
anButton2 : AnButton
anButton3 : AnButton
anButton4 : AnButton
anButton5 : AnButton
anButton6 : AnButton
anButton7 : AnButton
anButton8 : AnButton
anButton9 : AnButton
anButton10 : AnButton
anButton11 : AnButton
anButton12 : AnButton
attributtypemodifiable ?
logicalName  Texte  modifiable
advertisedValue  Texte  modifiable
calibratedValue  Nombre entier  lecture seule
rawValue  Nombre entier  lecture seule
analogCalibration  On/Off  modifiable
calibrationMax  Nombre entier  modifiable
calibrationMin  Nombre entier  modifiable
sensitivity  Nombre entier  modifiable
isPressed  Booléen  lecture seule
lastTimePressed  Temps  lecture seule
lastTimeReleased  Temps  lecture seule
pulseCounter  Nombre entier  modifiable
pulseTimer  Temps  lecture seule
inputType  Type énuméré  modifiable

quadratureDecoder1 : QuadratureDecoder
quadratureDecoder2 : QuadratureDecoder
quadratureDecoder3 : QuadratureDecoder
quadratureDecoder4 : QuadratureDecoder
quadratureDecoder5 : QuadratureDecoder
quadratureDecoder6 : QuadratureDecoder
attributtypemodifiable ?
logicalName  Texte  modifiable
advertisedValue  Texte  modifiable
unit  Texte  lecture seule
currentValue  Nombre (virgule fixe)  modifiable
lowestValue  Nombre (virgule fixe)  modifiable
highestValue  Nombre (virgule fixe)  modifiable
currentRawValue  Nombre (virgule fixe)  lecture seule
logFrequency  Fréquence  modifiable
reportFrequency  Fréquence  modifiable
advMode  Type énuméré  modifiable
calibrationParam  Paramètrs de calibration  modifiable
resolution  Nombre (virgule fixe)  modifiable
sensorState  Nombre entier  lecture seule
speed  Nombre (virgule fixe)  lecture seule
decoding  On/Off  modifiable
edgesPerCycle  Nombre entier  modifiable

buzzer : Buzzer
attributtypemodifiable ?
logicalName  Texte  modifiable
advertisedValue  Texte  modifiable
frequency  Nombre (virgule fixe)  modifiable
volume  0..100%  modifiable
playSeqSize  Nombre entier  lecture seule
playSeqMaxSize  Nombre entier  lecture seule
playSeqSignature  Nombre entier  lecture seule
command  Texte  modifiable

colorLedCluster : ColorLedCluster
attributtypemodifiable ?
logicalName  Texte  modifiable
advertisedValue  Texte  modifiable
activeLedCount  Nombre entier  modifiable
ledType  Type énuméré  modifiable
maxLedCount  Nombre entier  lecture seule
dynamicLedCount  Nombre entier  lecture seule
blinkSeqMaxCount  Nombre entier  lecture seule
blinkSeqMaxSize  Nombre entier  lecture seule
command  Texte  modifiable

files : Files
attributtypemodifiable ?
logicalName  Texte  modifiable
advertisedValue  Texte  modifiable
filesCount  Nombre entier  lecture seule
freeSpace  Nombre entier  lecture seule

5.3. Module

Interface de contrôle des paramètres généraux des modules Yoctopuce

La classe YModule est utilisable avec tous les modules USB de Yoctopuce. Elle permet de contrôler les paramètres généraux du module, et d'énumérer les fonctions fournies par chaque module.

productName

Chaîne de caractères contenant le nom commercial du module, préprogrammé en usine.

serialNumber

Chaîne de caractères contenant le numéro de série, unique et préprogrammé en usine. Pour un module Yocto-MaxiKnob, ce numéro de série commence toujours par YMXBTN01. Il peut servir comme point de départ pour accéder par programmation à un module particulier.

logicalName

Chaîne de caractères contenant le nom logique du module, initialement vide. Cet attribut peut être changé au bon vouloir de l'utilisateur. Une fois initialisé à une valeur non vide, il peut servir de point de départ pour accéder à un module particulier. Si deux modules avec le même nom logique se trouvent sur le même montage, il n'y a pas moyen de déterminer lequel va répondre si l'on tente un accès par ce nom logique. Le nom logique du module est limité à 19 caractères parmi A..Z,a..z,0..9,_ et -.

productId

Identifiant USB du module, préprogrammé à la valeur 158 en usine.

productRelease

Numéro de révision du module hardware, préprogrammé en usine. La révision originale du retourne la valeur 1, la révision B retourne la valeur 2, etc.

firmwareRelease

Version du logiciel embarqué du module, elle change à chaque fois que le logiciel embarqué est mis à jour.

persistentSettings

Etat des réglages persistants du module: chargés depuis la mémoire non-volatile, modifiés par l'utilisateur ou sauvegardés dans la mémoire non volatile.

luminosity

Intensité lumineuse maximale des leds informatives (comme la Yocto-Led) présentes sur le module. C'est une valeur entière variant entre 0 (leds éteintes) et 100 (leds à l'intensité maximum). La valeur par défaut est 50. Pour changer l'intensité maximale des leds de signalisation du module, ou les éteindre complètement, il suffit donc de modifier cette valeur.

beacon

Etat de la balise de localisation du module.

upTime

Temps écoulé depuis la dernière mise sous tension du module.

usbCurrent

Courant consommé par le module sur le bus USB, en milli-ampères.

rebootCountdown

Compte à rebours pour déclencher un redémarrage spontané du module.

userVar

Attribut de type entier 32 bits à disposition de l'utilisateur.

5.4. Buzzer

Interface pour intéragir avec les buzzers, disponibles par exemple dans le Yocto-Buzzer, le Yocto-MaxiBuzzer et le Yocto-MaxiKnob

La classe YBuzzer permet de piloter un buzzer (avertisseur sonore). Elle permet de choisir la fréquence et le volume à laquelle le buzzer doit sonner. Il est aussi possible de pré-programmer une séquence à jouer.

logicalName

Chaîne de caractères contenant le nom logique du buzzer, initialement vide. Cet attribut peut être changé au bon vouloir de l'utilisateur. Un fois initialisé à une valeur non vide, il peut servir de point de départ pour accéder à directement au buzzer. Si deux buzzers portent le même nom logique dans un projet, il n'y a pas moyen de déterminer lequel va répondre si l'on tente un accès par ce nom logique. Le nom logique du module est limité à 19 caractères parmi A..Z,a..z,0..9,_ et -.

advertisedValue

Fréquence courante, qui sera publiée automatiquement jusqu'au hub parent.

frequency

Fréquence du signal envoyé dans le buzzer/speaker.

volume

Volume du signal envoyé dans le buzzer/speaker.

playSeqSize

Taille actuelle de la séquence à jouer

playSeqMaxSize

Taille maximale de la séquence à jouer

playSeqSignature

Signature de la séquence à jouer

command

Attribut magique permettant d'envoyer des commandes avancées au module. Si une commande n'est pas interprétée comme attendue, consultez les logs du module.

5.5. AnButton

Interface pour intéragir avec les entrées analogiques, disponibles par exemple dans le Yocto-Buzzer, le Yocto-Knob, le Yocto-MaxiBuzzer et le Yocto-MaxiDisplay

La classe YAnButton permet d'accéder à une entrée résistive simple. Cela permet aussi bien de mesurer l'état d'un simple bouton que de lire un potentiomètre analogique (résistance variable), comme par exmple un bouton rotatif continu, une poignée de commande de gaz ou un joystick. Le module est capable de se calibrer sur les valeurs minimales et maximales du potentiomètre, et de restituer une valeur calibrée variant proportionnellement avec la position du potentiomètre, indépendant de sa résistance totale.

logicalName

Chaîne de caractères contenant le nom logique de l'entrée analogique, initialement vide. Cet attribut peut être changé au bon vouloir de l'utilisateur. Un fois initialisé à une valeur non vide, il peut servir de point de départ pour accéder à directement à l'entrée analogique. Si deux entrées analogiques portent le même nom logique dans un projet, il n'y a pas moyen de déterminer lequel va répondre si l'on tente un accès par ce nom logique. Le nom logique du module est limité à 19 caractères parmi A..Z,a..z,0..9,_ et -.

advertisedValue

Courte chaîne de caractères résumant l'état actuel de l'entrée analogique, et qui sera publiée automatiquement jusqu'au hub parent. Pour une entrée analogique, la valeur publiée est la valeur mesurée recalibrée (a number between 0 and 1000).

calibratedValue

Valeur recalibrée de l'entrée analogique, sous forme d'un entier variant entre 0 et 1000 inclus. Si aucune calibration n'est été faite, la valeur recalibrée est simplement la valeur mesurée ramenée dans l'intervalle 0...1000, sans correction de linéarité.

rawValue

Valeur mesurée de l'entrée analogique telle-quelle, sous forme d'un entier variant entre 0 et 4095. Elle vaut zéro lorsque la résistance à l'entrée est nulle (contact fermé), et tends vers 4095 lorsque la résistance à l'entrée tends vers l'infini (contact ouvert). Attention, cette valeur ne varie pas proportionnellement à la résistance (donc à la position du potentiomètre). Pour obtenir une valeur proportionnelle, lancez une calibration et utilisez la valeur calculée calibratedValue.

analogCalibration

Permet d'enclencher et de déclencher la procédure de calibration automatique de l'entrée analogique. Lorsque la calibration est enclenchée, le module enregistre les valeurs mesurées minimales et maximales dans calibrationMin et calibrationMax. Une fois la calibration terminée (déclenchée), le module peut calculer automatiquement en permanence une valeur recalibrée de la mesure, variant linéairement avec la valeur de résistance mesurée.

calibrationMax

Valeur mesurée maximale observée durant la calibration. Vous pouvez aussi changer cette valeur par logiciel pour imposer une calibration théorique.

calibrationMin

Valeur mesurée minimale observée durant la calibration. Vous pouvez aussi changer cette valeur par logiciel pour imposer une calibration théorique.

sensitivity

Sensibilité de l'entrée analogique pour le déclenchement de callbacks utilisateur. La sensibilité correspond à la différence de valeur nécessaire pour déclencher la propagation d'une nouvelle valeur publiée et l'appel du callback utilisateur correspondant. Une valeur trop petite peut pourrait causer des appels inutiles si l'entrée mesurée n'est pas suffisamment stable.

isPressed

Etat logique de l'entrée, si on la traite comme une entrée binaire (bouton on/off). L'état logique est pressé lorsque l'entrée est fermée, et non pressé lorsque l'entrée est ouverte. Le module implémente un léger lissage et un schmitt trigger qui permettent une mesure logique convenable.

lastTimePressed

Temps absolu de la dernière occurrence de "pression de bouton" observée sur l'entrée (transition du contact de ouvert à fermé). La base de temps est la même que l'attribut upTime du module, c'est à dire le temps écoulé depuis la dernière mise sous tension du module.

lastTimeReleased

Temps absolu de la dernière occurrence de "relâchement de bouton" observée sur l'entrée (transition du contact de fermé à ouvert). La base de temps est la même que l'attribut upTime du module, c'est à dire le temps écoulé depuis la dernière mise sous tension du module. Si on soustrait à cette valeur le lastTimePressed, on obtien la durée de la dernière pression.

pulseCounter

Compteur d'impulsions 32 bits, incrémenté à chaque fois que l'état du bouton passe chaque d'état (PRESSED / RELEASED) ce qui signifie que le compteur est incrémenté de deux après chaque impulsion. Ce compteur commence à zéro à chaque redémarage du module, il peut aussi être réinitialisé avec resetCounter().

pulseTimer

Temps écoulé depuis la dernière initilialisation du compteur d'impulsion (millisecondes)

inputType

Type de dispositif connecté à l'entrée (entrée analogique ou entrées binaires multiplexées)

5.6. QuadratureDecoder

Interface pour intéragir avec les décodeurs de quadrature, disponibles par exemple dans le Yocto-MaxiKnob et le Yocto-PWM-Rx

La classe YQuadratureDecoder permet de lire et de configurer les décodeurs de quadrature Yoctopuce. Elle hérite de la classe YSensor toutes les fonctions de base des capteurs Yoctopuce: lecture de mesures, callbacks, enregistreur de données.

logicalName

Chaîne de caractères contenant le nom logique du décodeur de quadrature, initialement vide. Cet attribut peut être changé au bon vouloir de l'utilisateur. Un fois initialisé à une valeur non vide, il peut servir de point de départ pour accéder à directement au décodeur de quadrature. Si deux décodeurs de quadrature portent le même nom logique dans un projet, il n'y a pas moyen de déterminer lequel va répondre si l'on tente un accès par ce nom logique. Le nom logique du module est limité à 19 caractères parmi A..Z,a..z,0..9,_ et -.

advertisedValue

Courte chaîne de caractères résumant l'état actuel du décodeur de quadrature, et qui sera publiée automatiquement jusqu'au hub parent. Pour un décodeut de quadrature, la valeur publiée est la valeur courante de la position.

unit

Courte chaîne de catactères représentant l'unité dans laquelle la position est exprimée.

currentValue

Valeur actuelle de la position, en pas, sous forme de nombre à virgule.

lowestValue

Valeur minimale de la position, en pas, sous forme de nombre à virgule.

highestValue

Valeur maximale de la position, en pas, sous forme de nombre à virgule.

currentRawValue

Valeur brute mesurée par le capteur (sans arrondi ni calibration), sous forme de nombre à virgule.

logFrequency

Fréquence d'enregistrement des mesures dans le datalogger, ou "OFF" si les mesures ne doivent pas être stockées dans la mémoire de l'enregistreur de données.

reportFrequency

Fréquence de notification périodique des valeurs mesurées, ou "OFF" si les notifications périodiques de valeurs sont désactivées.

advMode

Mode de calcul de la valeur publiée jusqu'au hub parent (advertisedValue).

calibrationParam

Paramètres de calibration supplémentaires (par exemple pour compenser l'effet d'un boîtier), sous forme de tableau d'entiers 16 bit.

resolution

Résolution de la mesure (précision de la représentation, mais pas forcément de la mesure elle-même).

sensorState

Etat du capteur (zero lorsque qu'une mesure actuelle est disponible).

speed

Fréquence des cycles, en Hz

decoding

Etat d'activation du décodeur de quadrature

edgesPerCycle

Nombre de flancs par cycle

5.7. ColorLedCluster

Interface pour intéragir avec les clusters de LEDs RGB, disponibles par exemple dans le Yocto-Color-V2, le Yocto-MaxiBuzzer et le Yocto-MaxiKnob

La class YColorLedCluster permet de piloter un cluster de LED. Contrairement a la classe ColorLed, la classe YColorLedCluster permet de changer modifier plusieurs LEDs à la fois. Les changements de couleur peuvent être fait aussi bien en coordonnées RGB qu'en coordonnées HSL, les conversions RGB vers HSL étant faites automatiquement par le module. Ceci permet aisément d'allumer les LEDs avec une certaine teinte et d'en faire progressivement varier la saturation ou la luminosité.

logicalName

Chaîne de caractères contenant le nom logique du cluster de LEDs RGB, initialement vide. Cet attribut peut être changé au bon vouloir de l'utilisateur. Un fois initialisé à une valeur non vide, il peut servir de point de départ pour accéder à directement au cluster de LEDs RGB. Si deux clusters de LEDs RGB portent le même nom logique dans un projet, il n'y a pas moyen de déterminer lequel va répondre si l'on tente un accès par ce nom logique. Le nom logique du module est limité à 19 caractères parmi A..Z,a..z,0..9,_ et -.

advertisedValue

Courte chaîne de caractères résumant l'état actuel du cluster de LEDs RGB, et qui sera publiée automatiquement jusqu'au hub parent. Pour un cluster de LEDs RGB, la valeur publiée est le checksum du buffer de LEDs (6 digits hexadécimaux).

activeLedCount

Nombre de LEDs actuellement gérées par le module

ledType

Type de LEDs RGB actuellement gérées par le module

maxLedCount

Nombre maximal de LEDs gérable par le module

dynamicLedCount

Nombre maximal de LEDs capables d'exécuter des séquences et des transitions autonomes

blinkSeqMaxCount

Nombre maximal de sequences enregistrées

blinkSeqMaxSize

Taille maximale d'une sequence

command

Attribut magique permettant d'envoyer des commandes avancées au module. Si une commande n'est pas interprétée comme attendue, consultez les logs du module.

5.8. Les espaces de couleurs: RGB et HSL

Espace RGB

Il existe plusieurs manières de définir une couleur. La plus connue consiste à utiliser ses composantes Rouge, Verte, et Bleue (RGB en anglais). Chaque couleur peut en effet être définie comme un mélange des trois couleurs primaires. Malheureusement ce système est assez difficile à manipuler avec précision dès qu'il s'agit de définir une couleur non saturée. Obtenir du rose bonbon par exemple, demande pas mal de tâtonnements avant d'arriver au résultat escompté.


L'espace de couleur RGB, il est souvent représenté sous la forme d'un cube.

En informatique on a l'habitude de définir une couleur RGB comme un triplet 0..255 exprimé en hexadécimal14. Ainsi le rouge pur est défini par 0xFF0000, le vert pur 0x00FF00, le bleu pur 0x0000FF, le noir 000000, le blanc 0xFFFFFF etc. Cette notation est, entre autres, utilisés en HTML pour définir les couleurs, on utilise alors le # comme préfixe au lieu du 0x.

Espace HSL

Il existe une autre manière, un peu plus simple, de définir une couleur. Elle consiste à décomposer une couleur en Teinte, Saturation et Luminosité (HSL en anglais). La teinte est définie de 0 à 360° et passe successivement par le rouge (0°) le jaune (60°), le vert (120°) le cyan (180°) le bleu (240°), le magenta (300°) pour finalement revenir au rouge (360°). La saturation, définie de 0 à 100%, décrit l'intensité de la couleur, plus on se rapproche du 0% plus la couleur parait délavée, plus on s'approche du 100% plus la couleur apparaît éclatante. La luminosité, définie de 0 a 100%, décrit la clarté de la couleur, elle devient plus sombre quand on se rapproche du 0% et devient plus claire quand on se rapproche du 100%. Lorsqu'on utilise ce système il est beaucoup assez facile de prévoir comment va évoluer une couleur quand on manipule une de ces coordonnées. Ce qui est loin d'être le cas avec le système RGB.


L'espace de couleur HSL, il souvent représenté sous la forme d'un double cone, dont la base est noire (L=0%) et la pointe supérieure est blanche (L=100%). La teinte est mappée sur le circonférence et la saturation sur le rayon.

En informatique on a tendance a normaliser les coordonnées HSL sur une gamme 0..255 et on représente une couleur HSL sous la forme d'un triplet hexadécimal. Ainsi 00FF80 représente le rouge pur, F0FF80 représente le bleu pur. Il est à noter que dans ce système, plusieurs notations différentes peuvent représenter la même couleur. Ainsi toutes les notations se terminant par 00 représentent le noir, toutes les notations se terminant par FF représentent le blanc. Une notation dont la saturation est zéro représente du gris, quelque soit la valeur de la teinte.

5.9. Les séquences

Le Yocto-MaxiKnob est capable de jouer des animations en toute autonomie c'est à dire sans l'intervention d'un ordinateur. Ces animations sont basées sur un concept de séquences. Une séquence est une suite de pseudo instructions gérées par la classe colorLedCluster qui peut gérer jusqu'à 8 de ces séquences en parallèle. Chaque LED ne peut être affectée qu'à une seule séquence à la fois.

Changement de couleurs

Une séquence est essentiellement définie comme une suite de changements de couleurs exécutés en boucle. Ainsi le code ci-dessous ré-initialise la séquence n°0 et ajoute deux transitions: une vers le rouge, une vers le bleu. Chacune durant une seconde.


YColorLedCluster c= YColorLedCluster.FirstColorLedCluster();
c.resetBlinkSeq(0);
c.addRgbMoveToBlinkSeq(0, 0xFF0000, 1000);
c.addRgbMoveToBlinkSeq(0, 0x0000FF, 1000);

Ainsi, toutes les LEDs affectées à cette séquence vont se mettre à osciller entre le rouge et le bleu avec une période totale de deux secondes. Les lignes suivantes affectent les deux premières LEDs à la séquence 0 et lance l'exécution de cette dernière.


c.linkLedToBlinkSeq(0, 2, 0, 0);
c.startBlinkSeq(0);

L'illustration ci-dessous montre l'évolution des deux LEDs au cours du temps.


Exécution d'une séquence automatique rouge-bleue avec une période de 2 secondes

Décalage

Il est possible d'introduire un offset lors de la liaison des LEDs à une séquence. Les LEDs exécutent alors toujours la même séquence mais avec un décalage. Le code ci-dessous affecte la LED 0 à la séquence 0 avec un offset de 0ms, puis affecte la LED 1, toujours à la séquence 0 mais avec un offset de 1000ms.


c.linkLedToBlinkSeq(0, 1, 0, 0);
c.linkLedToBlinkSeq(1, 1, 0, 1000);
c.startBlinkSeq(0);

Au lieu de changer de couleur ensemble, les LEDs vont changer de couleur en alternance puisque l'offset a été défini comme une demi-période.


Exécution de la séquence précédente avec un offset de 1 sec entre les deux LEDs

Les offsets dans l'exécution permettent de faire des effets de chenillard très spectaculaires. Imaginons que l'on dispose de 5 LEDs connectées en série au Yocto-MaxiKnob, le code suivant crée un séquence qui passe une led en bleu pendant 200 ms puis l'éteint pendant 800 ms.


YColorLedCluster c= YColorLedCluster.FirstColorLedCluster();
c.resetBlinkSeq(0);
c.addRgbMoveToBlinkSeq(0, 0x0000FF, 0);
c.addRgbMoveToBlinkSeq(0, 0x0000FF, 200);
c.addRgbMoveToBlinkSeq(0, 0x000000, 0);
c.addRgbMoveToBlinkSeq(0, 0x000000, 800);
for (int i = 0; i < 5; i++) {
  c.linkLedToBlinkSeq(i,1,0,200*i);
}

Notez que pour passer instantanément d'une couleur à l'autre, il suffit d'utiliser un move avec une durée de zéro. L'exécution de la séquence crée une lumière bleue qui passe d'une LED à l'autre toutes les 200ms.


On peut créer un chenillard en quelques lignes

Vitesse d'exécution

La vitesse d'exécution d'une séquence peut être modifiée. La vitesse par défaut est 1000, mais il est possible de la diminuer, et même de l'inverser. Ci dessous le code qui fait passer une led du rouge au jaune et inversement avec un periode de 400ms.


YColorLedCluster c= YColorLedCluster.FirstColorLedCluster();
c.resetBlinkSeq(0);
c.addRgbMoveToBlinkSeq(0, 0xFF0000, 200);
c.addRgbMoveToBlinkSeq(0, 0xFFFF00, 200);
c.linkLedToBlinkSeq(0, 2, 0, 0);
c.startBlinkSeq(0);


Alternance rouge jaune avec une fréquence de 400ms (vitesse normale : 1000)

Si on diminue la vitesse d'un facteur 2 à l'aide de set_blinkSeqSpeed, la période s'allonge d'un facteur 2, les transitions restent progressives car elles sont calculées en temps réel.


c.set_blinkSeqSpeed(0, 500);


Même séquence, demi vitesse (500).

Taux de rafraichissement

Attention, les séquences sont calculées en temps réel, en revanche les LEDs du Yocto-MaxiKnob sont rafraichies à un taux de 100Hz. Par conséquent un changement durant moins de 10ms à vitesse normale sera pris en compte, mais risque de ne pas être affiché, faute de durer assez longtemps.

Persistance des séquences

Les séquences peuvent être sauvegardées dans la mémoire non volatile du Yocto-MaxiKnob, de même qu'il est possible de sauver l'affectation des LEDs aux différentes séquences. Par ailleurs il est possible de configurer une séquence pour qu'elle démarre automatiquement au démarrage du module. Le code suivant configure une séquence puis sauve le tout de manière à ce qu'elle démarrage automatiquement au prochaine redémarrage du module.


YColorLedCluster c= YColorLedCluster.FirstColorLedCluster();
c.set_blinkSeqStateAtPowerOn(0, 1);
c.saveBlinkSeq(0);

Cette technique permet de fabriquer des effets lumineux simples qui n'ont pas besoin d'un ordinateur pour fonctionner. Si des séquence sont préprogrammées dans le module, il suffira de l'alimenter avec un simple chargeur USB pour qu'elles démarrent dès la mise sous tension.

5.10. Quelle interface: Native, DLL ou Service?

Il y existe plusieurs méthodes pour contrôler un module USB Yoctopuce depuis un programme.

Contrôle natif

Dans ce cas de figure le programme pilotant votre projet est directement compilé avec une librairie qui offre le contrôle des modules. C'est objectivement la solution la plus simple et la plus élégante pour l'utilisateur final. Il lui suffira de brancher le câble USB et de lancer votre programme pour que tout fonctionne. Malheureusement, cette technique n'est pas toujours disponible ou même possible.


L'application utilise la librairie native pour contrôler le module connecté en local

Contrôle natif par DLL

Ici l'essentiel du code permettant de contrôler les modules se trouve dans une DLL, et le programme est compilé avec une petite librairie permettant de contrôler cette DLL. C'est la manière la plus rapide pour coder le support des modules dans un language particulier. En effet la partie "utile" du code de contrôle se trouve dans la DLL qui est la même pour tous les langages, offrir le support pour un nouveau langage se limite à coder la petite librairie qui contrôle la DLL. Du point de de l'utilisateur final, il y a peu de différences: il faut simplement être sûr que la DLL sera installée sur son ordinateur en même temps que le programme principal.


L'application utilise la DLL pour contrôler nativement le module connecté en local

Contrôle par un service

Certains langages ne permettent tout simplement pas d'accéder facilement au niveau matériel de la machine. C'est le cas de Javascript par exemple. Pour gérer ce cas, Yoctopuce offre la solution sous la forme d'un petit service, appelé VirtualHub qui, lui, est capable d'accéder aux modules, et votre application n'a plus qu'à utiliser une librairie qui offrira toutes les fonctions nécessaires au contrôle des modules en passant par l'intermédiaire de ce VirtualHub. L'utilisateur final se verra obligé de lancer VirtualHub avant de lancer le programme de contrôle du projet proprement dit, à moins qu'il ne décide d'installer VirtualHub sous la forme d'un service/démon, auquel cas VirtualHub se lancera automatiquement au démarrage de la machine..


L'application se connecte au service VirtualHub pour connecter le module.

En revanche la méthode de contrôle par un service offre un avantage non négligeable: l'application n'est pas n'obligée de tourner sur la machine où se trouvent les modules: elle peut parfaitement se trouver sur un autre machine qui se connectera au service pour piloter les modules. De plus, les librairie natives et DLL évoquées plus haut sont aussi capables de se connecter à distance à une ou plusieurs instances de VirtualHub.


Lorsqu'on utilise VirtualHub, l'application de contrôle n'a plus besoin d'être sur la même machine que le module.

Quel que soit langage de programmation choisi et le paradigme de contrôle utilisé, la programmation reste strictement identique. D'un langage à l'autre les fonctions ont exactement le même nom, prennent les mêmes paramètres. Les seules différences sont liées aux contraintes des langages eux-mêmes.

Language Natif  Natif avec .DLL/.so  VirtualHub 
Ligne de commande -
Python -
C++
C# .Net -
C# UWP -
LabVIEW -
Java -
Java pour Android -
TypeScript - -
JavaScript / ECMAScript - -
PHP - -
VisualBasic .Net -
Delphi -
Objective-C -

Méthode de support pour les différents langages.

5.11. Accéder aux modules à travers un hub

VirtualHub pour contourner la limitation d'accès à USB

Une seule application à la fois peut avoir accès nativement aux modules Yoctopuce. Cette limitation est liée au fait que deux processus différents ne peuvent pas parler en même temps à un périphérique USB. En général, ce type de problème est réglé par un driver qui se charge de faire la police pour éviter que plusieurs processus ne se battent pour le même périphérique. Mais les produits Yoctopuce n'utilisent pas de drivers. Par conséquent, le premier processus qui arrive à accéder au mode natif le garde pour lui jusqu'à ce que UnregisterHub ou FreeApi soit appelé.

Si votre application essaie de communiquer en mode natif avec les modules Yoctopuce, mais qu'une autre application vous empêche d'y accéder, vous revecrez le message d'erreur suivant:


Another process is already using yAPI

La solution est d'utiliser VirtualHub localement sur votre machine et de vous en servir comme passerelle pour vos applications. Ainsi, si toutes vos application utilisent VirtualHub, vous n'aurez plus de conflit et vous pourrez accéder en tout temps à tous vos modules.

Pour passer du mode natif au mode réseau sur votre machine locale, il vous suffit de changer le paramètre de l'appel à YAPI.RegisterHub et d'indiquer 127.0.0.1 à la place de usb.

Avec un YoctoHub

Un YoctoHub se comporte exactement comme un ordinateur faisant tourner VirtualHub. La seule différence entre un programme utilisant l'API Yoctopuce utilisant des modules en USB natif et ce même programme utilisant des modules Yoctopuce connectés à un YoctoHub se situe au niveau de l'appel à RegisterHub. Pour utiliser des modules USB connectés en natif, le paramètre de RegisterHub est usb, pour utiliser des modules connectés à un YoctoHub, il suffit de remplacer ce paramètre par l'adresse IP du YoctoHub.

Il y a donc trois cas de figure: le mode natif, le mode réseau à travers VirtualHub sur votre machine locale, ou à travers un YoctoHub. Pour passer de l'un à l'autre, il vous suffit de changer le paramètre de l'appel à YAPI.RegisterHub comme dans les exemples ci-dessous:


YAPI.RegisterHub("usb",errmsg);  // utilisation en mode natif USB

YAPI.RegisterHub("127.0.0.1",errmsg);  // utilisation en mode réseau local avec VirtualHub

YAPI.RegisterHub("192.168.0.10",errmsg); // utilisation avec YoctoHub dont l'adresse IP est 192.168.0.10

5.12. Programmation, par où commencer?

Arrivé à ce point du manuel, vous devriez connaître l'essentiel de la théorie à propos de votre Yocto-MaxiKnob. Il est temps de passer à la pratique. Il vous faut télécharger la librairie Yoctopuce pour votre language de programmation favori depuis le site web de Yoctopuce15. Puis sautez directement au chapitre correspondant au langage de programmation que vous avez choisi.

Tous les exemples décrits dans ce manuel sont présents dans les librairies de programmation. Dans certains langages, les librairies comprennent aussi quelques applications graphiques complètes avec leur code source.

Une fois que vous maîtriserez la programmation de base de votre module, vous pourrez vous intéresser au chapitre concernant la programmation avancée qui décrit certaines techniques qui vous permettront d'exploiter au mieux votre Yocto-MaxiKnob.

6. Utilisation du Yocto-MaxiKnob en ligne de commande

Lorsque vous désirez effectuer une opération ponctuelle sur votre Yocto-MaxiKnob, comme la lecture d'une valeur, le changement d'un nom logique, etc.. vous pouvez bien sur utiliser VirtualHub, mais il existe une méthode encore plus simple, rapide et efficace: l'API en ligne de commande.

L'API en ligne de commande se présente sous la forme d'un ensemble d'exécutables, un par type de fonctionnalité offerte par l'ensemble des produits Yoctopuce. Ces exécutables sont fournis pré-compilés pour toutes les plateformes/OS officiellement supportés par Yoctopuce. Bien entendu, les sources de ces exécutables sont aussi fournies16.

6.1. Installation

Téléchargez l'API en ligne de commande17. Il n'y a pas de programme d'installation à lancer, copiez simplement les exécutables correspondant à votre plateforme/OS dans le répertoire de votre choix. Ajoutez éventuellement ce répertoire à votre variable environnement PATH pour avoir accès aux exécutables depuis n'importe où. C'est tout, il ne vous reste plus qu'à brancher votre Yocto-MaxiKnob, ouvrir un shell et commencer à travailler en tapant par exemple:

C:\>YBuzzer any set_frequency 1000
C:\>YAnbutton any get_isPressed
C:\>YColorLedCluster any set_rgbColor 0 1 0xFF0000
C:\>YQuadratureDecoder any get_currentValue

Sous Linux, pour utiliser l'API en ligne de commande, vous devez soit être root, soit définir une règle udev pour votre système. Vous trouverez plus de détails au chapitre Problèmes courants.

6.2. Utilisation: description générale

Tous les exécutables de l'API en ligne de commande fonctionnent sur le même principe: ils doivent être appelés de la manière suivante:


C:\>Executable [options] [cible] commande [paramètres]

Les [options] gèrent le fonctionnement global des commandes , elles permettent par exemple de piloter des modules à distance à travers le réseau, ou encore elles peuvent forcer les modules à sauver leur configuration après l'exécution de la commande.

La [cible] est le nom du module ou de la fonction auquel la commande va s'appliquer. Certaines commandes très génériques n'ont pas besoin de cible. Vous pouvez aussi utiliser les alias "any" ou "all", ou encore une liste de noms, séparés par des virgules, sans espace.

La commande est la commande que l'on souhaite exécuter. La quasi-totalité des fonctions disponibles dans les API de programmation classiques sont disponibles sous forme de commandes. Vous n'êtes pas obligé des respecter les minuscules/majuscules et les caractères soulignés dans le nom de la commande.

Les [paramètres] sont, assez logiquement, les paramètres dont la commande a besoin.

A tout moment les exécutables de l'API en ligne de commande sont capables de fournir une aide assez détaillée: Utilisez par exemple


C:\>executable /help

pour connaître la liste de commandes disponibles pour un exécutable particulier de l'API en ligne de commande, ou encore:


C:\>executable commande /help

Pour obtenir une description détaillée des paramètres d'une commande.

6.3. Contrôle de la fonction AnButton

Pour contrôler la fonction AnButton de votre Yocto-MaxiKnob, vous avez besoin de l'exécutable YAnButton.

Vous pouvez par exemple lancer:

C:\>YBuzzer any set_frequency 1000
C:\>YAnbutton any get_isPressed
C:\>YColorLedCluster any set_rgbColor 0 1 0xFF0000
C:\>YQuadratureDecoder any get_currentValue

Cet exemple utilise la cible "any" pour signifier que l'on désire travailler sur la première fonction AnButton trouvée parmi toutes celles disponibles sur les modules Yoctopuce accessibles au moment de l'exécution. Cela vous évite d'avoir à connaître le nom exact de votre fonction et celui de votre module.

Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté).


C:\>YAnButton YMXBTN01-123456.anButton1 describe

C:\>YAnButton YMXBTN01-123456.MaFonction describe

C:\>YAnButton MonModule.anButton1 describe

C:\>YAnButton MonModule.MaFonction describe

C:\>YAnButton MaFonction describe

Pour travailler sur toutes les fonctions AnButton à la fois, utilisez la cible "all".


C:\>YAnButton all describe

Pour plus de détails sur les possibilités de l'exécutableYAnButton, utilisez:


C:\>YAnButton /help

6.4. Contrôle de la partie module

Chaque module peut être contrôlé d'une manière similaire à l'aide de l'exécutable YModule. Par exemple, pour obtenir la liste de tous les modules connectés, utilisez:


C:\>YModule inventory

Vous pouvez aussi utiliser la commande suivante pour obtenir une liste encore plus détaillée des modules connectés:


C:\>YModule all describe

Chaque propriété xxx du module peut être obtenue grâce à une commande du type get_xxxx(), et les propriétés qui ne sont pas en lecture seule peuvent être modifiées à l'aide de la commande set_xxx(). Par exemple:


C:\>YModule YMXBTN01-12346 set_logicalName MonPremierModule

C:\>YModule YMXBTN01-12346 get_logicalName

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'utiliser la commande set_xxx correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la commande saveToFlash. Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode revertFromFlash. Par exemple:


C:\>YModule YMXBTN01-12346 set_logicalName MonPremierModule
C:\>YModule YMXBTN01-12346 saveToFlash

Notez que vous pouvez faire la même chose en seule fois à l'aide de l'option -s


C:\>YModule -s  YMXBTN01-12346 set_logicalName MonPremierModule

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la commande saveToFlash que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette commande depuis l'intérieur d'une boucle.

6.5. Limitations

L'API en ligne de commande est sujette à la même limitation que les autres API: il ne peut y avoir q'une seule application à la fois qui accède aux modules de manière native. Par défaut l'API en ligne de commande fonctionne en natif.

Cette limitation peut aisément être contournée en utilisant VirtualHub: il suffit de faire tourner VirtualHub18 sur la machine concernée et d'utiliser les executables de l'API en ligne de commande avec l'option -r par exemple, si vous utilisez:


C:\>YModule  inventory

Vous obtenez un inventaire des modules connectés par USB, en utilisant un accès natif. Si il y a déjà une autre commande en cours qui accède aux modules en natif, cela ne fonctionnera pas. Mais si vous lancez VirtualHub et que vous lancez votre commande sous la forme:


C:\>YModule -r 127.0.0.1 inventory

cela marchera parce que la commande ne sera plus exécutée nativement, mais à travers VirtualHub. Notez que VirtualHub compte comme une application native.

7. Utilisation du Yocto-MaxiKnob en Python

Python est un langage interprété orienté objet développé par Guido van Rossum. Il offre l'avantage d'être gratuit et d'être disponible pour la plupart de plate-formes tant Windows qu'Unix. C'est un language idéal pour écrire des petits scripts sur un coin de table. La librairie Yoctopuce est compatible avec Python 2.7 et 3.x jusqu'aux toutes dernières versions officielles. Elle fonctionne sous Windows, macOS et Linux tant Intel qu'ARM. Les interpréteurs Python sont disponibles sur le site de Python 19.

7.1. Fichiers sources

Les classes de la librairie Yoctopuce20 pour Python que vous utiliserez vous sont fournies au format source. Copiez tout le contenu du répertoire Sources dans le répertoire de votre choix et ajoutez ce répertoire à la variable d'environnement PYTHONPATH. Si vous utilisez un IDE pour programmer en Python, référez-vous à sa documentation afin le configurer de manière à ce qu'il retrouve automatiquement les fichiers sources de l'API.

7.2. Librairie dynamique

Une partie de la librairie de bas-niveau est écrite en C, mais vous n'aurez a priori pas besoin d'interagir directement avec elle: cette partie est fournie sous forme de DLL sous Windows, de fichier .so sous Unix et de fichier .dylib sous macOS. Tout a été fait pour que l'interaction avec cette librairie se fasse aussi simplement que possible depuis Python: les différentes versions de la librairie dynamique correspondant aux différents systèmes d'exploitation et architectures sont stockées dans le répertoire cdll. L'API va charger automatiquement le bon fichier lors de son initialisation. Vous n'aurez donc pas à vous en soucier.

Si un jour vous deviez vouloir recompiler la librairie dynamique, vous trouverez tout son code source dans la librairie Yoctopuce pour le C++.

Afin de les garder simples, tous les exemples fournis dans cette documentation sont des applications consoles. Il va de soit que que le fonctionnement des librairies est strictement identiques si vous les intégrez dans une application dotée d'une interface graphique.

7.3. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code Python qui utilise la fonction AnButton.


[...]
# On active la détection des modules sur USB
errmsg=YRefParam()
YAPI.RegisterHub("usb",errmsg)
[...]

# On récupère l'objet permettant d'intéragir avec le module
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1")

# Pour gérer le hot-plug, on vérifie que le module est là
if anbutton.isOnline():
    # use anbutton.get_calibratedValue()
    [...]
   
[...]  

Voyons maintenant en détail ce que font ces quelques lignes.

YAPI.RegisterHub

La fonction YAPI.RegisterHub initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Utilisée avec le paramètre "usb", elle permet de travailler avec les modules connectés localement à la machine. Si l'initialisation se passe mal, cette fonction renverra une valeur différente de YAPI.SUCCESS, et retournera via l'objet errmsg une explication du problème.

YAnButton.FindAnButton

La fonction YAnButton.FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1")
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.MaFonction")
anbutton = YAnButton.FindAnButton("MonModule.anButton1")
anbutton = YAnButton.FindAnButton("MonModule.MaFonction")
anbutton = YAnButton.FindAnButton("MaFonction")

YAnButton.FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

A propos des imports Python

Cette documentation suppose que vous utilisez la librairie Python téléchargée directement depuis le site web de Yoctopuce, mais si vous avez installé la librairie Yoctopuce avec PIP, alors vous devrez préfixer tous les imports avec yoctopuce.. Ainsi tous les exemples donnés dans la documentation, tels que:


from yocto_api import *

doivent être convertis, lorsque que la librairie Yoctopuce a été installée par PIP, en:


from yoctopuce.yocto_api import *

La méthode get_isPressed() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YQuadratureDecoder.FindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YBuzzer.FindBuzzer ou YBuzzer.FirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YColorLedCluster.FindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Lancez votre interpréteur Python et ouvrez le script correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

#!/usr/bin/python
# -*- coding: utf-8 -*-
import os, sys
# !/usr/bin/python


from yocto_buzzer import *
from yocto_colorledcluster import *
from yocto_quadraturedecoder import *
from yocto_anbutton import *


def usage():
    scriptname = os.path.basename(sys.argv[0])
    print("Usage:")
    print(scriptname + ' <serial_number>  ')
    print(scriptname + ' <logical_name>   ')
    print(scriptname + ' any ')
    print('Example:')
    print(scriptname + ' any ')
    sys.exit()


def die(msg):
    sys.exit(msg + ' (check USB cable)')


def notefreq(note):
    return 220.0 * math.exp(note * math.log(2) / 12)

if len(sys.argv) < 2:
    usage()

target = sys.argv[1].upper()

# Setup the API to use local USB devices
errmsg = YRefParam()
if YAPI.RegisterHub("usb", errmsg) != YAPI.SUCCESS:
    sys.exit("init error" + errmsg.value)

if target == 'ANY':
    # retrieve any Buzzer
    buz = YBuzzer.FirstBuzzer()
    if buz is None:
        die('no device connected')
else:
    buz = YBuzzer.FindBuzzer(target)

if not (buz.isOnline()):
    die('device not connected')
serial = buz.get_module().get_serialNumber()
leds = YColorLedCluster.FindColorLedCluster(serial + ".colorLedCluster")
button = YAnButton.FindAnButton(serial + ".anButton1")
qd = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1")

if (not button.isOnline()) or (not qd.isOnline()):
    sys.exit("Make sure the Yocto-MaxiKnob is configured with at least one AnButton and One Quadrature decoder.")

lastPos = qd.get_currentValue()
buz.set_volume(100)
qd.set_edgesPerCycle(2)

print("press button 1, or turn the encoder")
while button.isOnline():
    if button.get_isPressed() and lastPos != 0:
        lastPos = 0
        qd.set_currentValue(0)
        buz.playNotes("'E32 C8")
        leds.set_rgbColor(0, 1, 0x000000)
    else:
        p = math.floor(qd.get_currentValue())
        if lastPos != p:
            lastPos = p
            buz.pulse(notefreq(p), 250)
            leds.set_hslColor(0, 1, 0x00FF7f | (p % 255) << 16)

YAPI.FreeAPI()
 

7.4. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci-dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

#!/usr/bin/python
# -*- coding: utf-8 -*-
import os, sys

from yocto_api import *


def usage():
    sys.exit("usage: demo <serial or logical name> [ON/OFF]")


errmsg = YRefParam()
if YAPI.RegisterHub("usb", errmsg) != YAPI.SUCCESS:
    sys.exit("RegisterHub error: " + str(errmsg))

if len(sys.argv) < 2:
    usage()

m = YModule.FindModule(sys.argv[1])  # # use serial or logical name

if m.isOnline():
    if len(sys.argv) > 2:
        if sys.argv[2].upper() == "ON":
            m.set_beacon(YModule.BEACON_ON)
        if sys.argv[2].upper() == "OFF":
            m.set_beacon(YModule.BEACON_OFF)

    print("serial:       " + m.get_serialNumber())
    print("logical name: " + m.get_logicalName())
    print("luminosity:   " + str(m.get_luminosity()))
    if m.get_beacon() == YModule.BEACON_ON:
        print("beacon:       ON")
    else:
        print("beacon:       OFF")
    print("upTime:       " + str(m.get_upTime() / 1000) + " sec")
    print("USB current:  " + str(m.get_usbCurrent()) + " mA")
    print("logs:\n" + m.get_lastLogs())
else:
    print(sys.argv[1] + " not connected (check identification and USB cable)")
YAPI.FreeAPI()
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type YModule.get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode YModule.set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction YModule.set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode YModule.saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode YModule.revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

#!/usr/bin/python
# -*- coding: utf-8 -*-
import os, sys

from yocto_api import *


def usage():
    sys.exit("usage: demo <serial or logical name> <new logical name>")


if len(sys.argv) != 3:
    usage()

errmsg = YRefParam()
if YAPI.RegisterHub("usb", errmsg) != YAPI.SUCCESS:
    sys.exit("RegisterHub error: " + str(errmsg))

m = YModule.FindModule(sys.argv[1])  # use serial or logical name
if m.isOnline():
    newname = sys.argv[2]
    if not YAPI.CheckLogicalName(newname):
        sys.exit("Invalid name (" + newname + ")")
    m.set_logicalName(newname)
    m.saveToFlash()  # do not forget this
    print("Module: serial= " + m.get_serialNumber() + " / name= " + m.get_logicalName())
else:
    sys.exit("not connected (check identification and USB cable")
YAPI.FreeAPI()

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction YModule.saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction YModule.yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la mehode nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un null. Ci-dessous un petit exemple listant les module connectés

#!/usr/bin/python
# -*- coding: utf-8 -*-
import os, sys


from yocto_api import *

errmsg = YRefParam()

# Setup the API to use local USB devices
if YAPI.RegisterHub("usb", errmsg) != YAPI.SUCCESS:
    sys.exit("init error" + str(errmsg))

print('Device list')

module = YModule.FirstModule()
while module is not None:
    print(module.get_serialNumber() + ' (' + module.get_productName() + ')')
    module = module.nextModule()
YAPI.FreeAPI()

7.5. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

8. Utilisation du Yocto-MaxiKnob en C++

Le C++ n'est pas le langage le plus simple à maîtriser. Pourtant, si on prend soin à se limiter aux fonctionnalités essentielles, c'est un langage tout à fait utilisable pour des petits programmes vite faits, et qui a l'avantage d'être très portable d'un système d'exploitation à l'autre. Sous Windows, C++ est supporté avec Microsoft Visual Studio 2017 et les versions plus récentes. Sous macOS, nous supportons les versions de XCode supportées par Apple. Sous Linux, nous supportons toutes les versions de gcc publiées depuis 2008. Par ailleurs, aussi bien sous macOS que sous Linux, vous pouvez compiler les exemples en ligne de commande avec GCC en utilisant le GNUmakefile fourni. De même, sous Windows, un Makefile vous permet de compiler les exemples en ligne de commande, en pleine connaissance des arguments de compilation et link.

Les librairies Yoctopuce21 pour C++ vous sont fournies au format source dans leur intégralité. Une partie de la librairie de bas-niveau est écrite en C pur sucre, mais vous n'aurez à priori pas besoin d'interagir directement avec elle: tout a été fait pour que l'interaction soit le plus simple possible depuis le C++. La librairie vous est fournie bien entendu aussi sous forme binaire, de sorte à pouvoir la linker directement si vous le préférez.

Vous allez rapidement vous rendre compte que l'API C++ defini beaucoup de fonctions qui retournent des objets. Vous ne devez jamais désallouer ces objets vous-même. Ils seront désalloués automatiquement par l'API à la fin de l'application.

Afin des les garder simples, tous les exemples fournis dans cette documentation sont des applications consoles. Il va de soit que que les fonctionnement des librairies est strictement identiques si vous les intégrez dans une application dotée d'une interface graphique. Vous trouverez dans la dernière section de ce chapitre toutes les informations nécessaires à la création d'un projet à neuf linké avec les librairies Yoctopuce.

8.1. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code C++ qui utilise la fonction AnButton.


#include "yocto_api.h"
#include "yocto_anbutton.h"

[...]
// On active la détection des modules sur USB
String errmsg;
YAPI::RegisterHub("usb", errmsg);
[...]

// On récupère l'objet permettant d'intéragir avec le module
YAnButton *anbutton;
anbutton = YAnButton::FindAnButton("YMXBTN01-123456.anButton1");

// Pour gérer le hot-plug, on vérifie que le module est là
if(anbutton->isOnline())
{
    // Utiliser anbutton->get_calibratedValue()
    [...]
}

Voyons maintenant en détail ce que font ces quelques lignes.

yocto_api.h et yocto_anbutton.h

Ces deux fichiers inclus permettent d'avoir accès aux fonctions permettant de gérer les modules Yoctopuce. yocto_api.h doit toujours être utilisé, yocto_anbutton.h est nécessaire pour gérer les modules contenant une entrée analogique, comme le Yocto-MaxiKnob.

YAPI::RegisterHub

La fonction YAPI::RegisterHub initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Utilisée avec le paramètre "usb", elle permet de travailler avec les modules connectés localement à la machine. Si l'initialisation se passe mal, cette fonction renverra une valeur différente de YAPI_SUCCESS, et retournera via le paramètre errmsg un explication du problème.

YAnButton::FindAnButton

La fonction YAnButton::FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


YAnButton *anbutton = YAnButton::FindAnButton("YMXBTN01-123456.anButton1");
YAnButton *anbutton = YAnButton::FindAnButton("YMXBTN01-123456.MaFonction");
YAnButton *anbutton = YAnButton::FindAnButton("MonModule.anButton1");
YAnButton *anbutton = YAnButton::FindAnButton("MonModule.MaFonction");
YAnButton *anbutton = YAnButton::FindAnButton("MaFonction");

YAnButton::FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par YAnButton::FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YFindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YFindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YFindBuzzer ou YFirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YFindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Lancez votre environnement C++ et ouvrez le projet exemple correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce. Si vous préférez travailler avec votre éditeur de texte préféré, ouvrez le fichier main.cpp, vous taperez simplement make dans le répertoire de l'exemple pour le compiler.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

#include "yocto_api.h"
#include "yocto_buzzer.h"
#include "yocto_anbutton.h"
#include "yocto_colorledcluster.h"
#include "yocto_quadraturedecoder.h"
#include <iostream>

using namespace std;

static void usage(void)
{
  cout << "usage: demo <serial_number> " << endl;
  cout << "       demo any  (use any discovered device)" << endl;
  u64 now = yGetTickCount();
  while (yGetTickCount() - now < 3000) {
    // wait 3 sec to show the message
  }
  exit(1);
}

static int notefreq(int note)
{
  return (int)( 220.0 * exp(note * log(2.0) / 12));
}

int main(int argc, const char* argv[])
{
  string errmsg;
  string target, serial;
  YBuzzer* buz;
  YColorLedCluster* leds;
  YAnButton* button;
  YQuadratureDecoder* qd;
  double lastPos;

  if (argc < 2) {
    usage();
  }
  target = (string)argv[1];

  // Setup the API to use local USB devices
  if (YAPI::RegisterHub("usb", errmsg) != YAPI_SUCCESS) {
    cerr << "RegisterHub error: " << errmsg << endl;
    return 1;
  }

  if (target == "any") {
    buz = YBuzzer::FirstBuzzer();
    if (buz == NULL) {
      cout << "No module connected (check USB cable)" << endl;
      return 1;
    }
  } else {
    buz = YBuzzer::FindBuzzer(target + ".buzzer");
  }

  if (!buz->isOnline()) {
    cout << "Module not connected (check identification and USB cable)" << endl;
    return 1;
  }

  serial = buz->get_module()->get_serialNumber();
  leds = YColorLedCluster::FindColorLedCluster(serial + ".colorLedCluster");
  button = YAnButton::FindAnButton(serial + ".anButton1");
  qd = YQuadratureDecoder::FindQuadratureDecoder(serial + ".quadratureDecoder1");

  if ((!button->isOnline()) || (!qd->isOnline())) {
    cout << "Make sure the Yocto-MaxiKnob is configured with at least one AnButton and One Quadrature decoder."
         << endl;
    return 1;
  }

  cout << "press a test button, or turn the encoder or hit Ctrl-C" << endl;
  lastPos = (int) qd->get_currentValue();
  buz->set_volume(75);
  while (button->isOnline()) {
    if (button->isPressed() && (lastPos != 0)) {
      lastPos = 0;
      qd->set_currentValue(0);
      buz->playNotes("'E32 C8");
      leds->set_rgbColor(0, 1, 0x000000);
    } else {
      int p = (int) qd->get_currentValue();
      if (lastPos != p) {
        lastPos = p;
        buz->pulse(notefreq(p), 500);
        leds->set_hslColor(0, 1, 0x00FF7f | (p % 255) << 16);
      }
    }
  }
  YAPI::FreeAPI();
}
 

8.2. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

#include <iostream>
#include <stdlib.h>

#include "yocto_api.h"

using namespace std;

static void usage(const char *exe)
{
  cout << "usage: " << exe << " <serial or logical name> [ON/OFF]" << endl;
  exit(1);
}


int main(int argc, const char * argv[])
{
  string      errmsg;

  // Setup the API to use local USB devices
  if(YAPI::RegisterHub("usb", errmsg) != YAPI::SUCCESS) {
    cerr << "RegisterHub error: " << errmsg << endl;
    return 1;
  }

  if(argc < 2)
    usage(argv[0]);

  YModule *module = YModule::FindModule(argv[1]);  // use serial or logical name

  if (module->isOnline()) {
    if (argc > 2) {
      if (string(argv[2]) == "ON")
        module->set_beacon(Y_BEACON_ON);
      else
        module->set_beacon(Y_BEACON_OFF);
    }
    cout << "serial:       " << module->get_serialNumber() << endl;
    cout << "logical name: " << module->get_logicalName() << endl;
    cout << "luminosity:   " << module->get_luminosity() << endl;
    cout << "beacon:       ";
    if (module->get_beacon() == Y_BEACON_ON)
      cout << "ON" << endl;
    else
      cout << "OFF" << endl;
    cout << "upTime:       " << module->get_upTime() / 1000 << " sec" << endl;
    cout << "USB current:  " << module->get_usbCurrent() << " mA" << endl;
    cout << "Logs:" << endl << module->get_lastLogs() << endl;
  } else {
    cout << argv[1] << " not connected (check identification and USB cable)"
         << endl;
  }
  YAPI::FreeAPI();
  return 0;
}
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

#include <iostream>
#include <stdlib.h>

#include "yocto_api.h"

using namespace std;

static void usage(const char *exe)
{
  cerr << "usage: " << exe << " <serial> <newLogicalName>" << endl;
  exit(1);
}

int main(int argc, const char * argv[])
{
  string      errmsg;

  // Setup the API to use local USB devices
  if(YAPI::RegisterHub("usb", errmsg) != YAPI::SUCCESS) {
    cerr << "RegisterHub error: " << errmsg << endl;
    return 1;
  }

  if(argc < 2)
    usage(argv[0]);

  YModule *module = YModule::FindModule(argv[1]);  // use serial or logical name

  if (module->isOnline()) {
    if (argc >= 3) {
      string newname =  argv[2];
      if (!yCheckLogicalName(newname)) {
        cerr << "Invalid name (" << newname << ")" << endl;
        usage(argv[0]);
      }
      module->set_logicalName(newname);
      module->saveToFlash();
    }
    cout << "Current name: " << module->get_logicalName() << endl;
  } else {
    cout << argv[1] << " not connected (check identification and USB cable)"
         << endl;
  }
  YAPI::FreeAPI();
  return 0;
}
 

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la fonction nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un NULL. Ci-dessous un petit exemple listant les module connectés

#include <iostream>

#include "yocto_api.h"

using namespace std;

int main(int argc, const char * argv[])
{
  string      errmsg;

  // Setup the API to use local USB devices
  if(YAPI::RegisterHub("usb", errmsg) != YAPI::SUCCESS) {
    cerr << "RegisterHub error: " << errmsg << endl;
    return 1;
  }

  cout << "Device list: " << endl;

  YModule *module = YModule::FirstModule();
  while (module != NULL) {
    cout << module->get_serialNumber() << " ";
    cout << module->get_productName()  << endl;
    module = module->nextModule();
  }
  YAPI::FreeAPI();
  return 0;
}
 

8.3. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

8.4. Intégration de la librairie Yoctopuce en C++

Selon vos besoins et vos préférences, vous pouvez être mené à intégrer de différentes manières la librairie à vos projets. Cette section explique comment implémenter les différentes options.

Intégration au format source (recommandé)

L'intégration de toutes les sources de la librairie dans vos projets a plusieurs avantages:

Pour intégrer le code source, le plus simple est d'inclure simplement le répertoire Sources de la librairie Yoctopuce à votre IncludePath, et d'ajouter tous les fichiers de ce répertoire (y compris le sous-répertoire yapi) à votre projet.

Pour que votre projet se construise ensuite correctement, il faudra linker avec votre projet les librairies systèmes requises, à savoir:

Intégration en librairie statique

L'intégration de de la librairie Yoctopuce sous forme de librairie statique permet une compilation rapide du programme en une seule commande. Elle ne requiert pas non plus l'installation d'une librairie dynamique spécifique à Yoctopuce sur le système final, tout est dans l'exécutable.

Pour utiliser la librairie statique, il faut la compiler à l'aide du shell script build.sh sous UNIX, ou build.bat sous Windows. Ce script qui se situe à la racine de la librairie, détecte l'OS et recompile toutes les librairies ainsi que les exemples correspondants.

Ensuite, pour intégrer la librairie statique Yoctopuce à votre projet, vous devez inclure le répertoire Sources de la librairie Yoctopuce à votre IncludePath, et ajouter le sous-répertoire de Binaries/... correspondant à votre système d'exploitation à votre LibPath.

Finalement, pour que votre projet se construise ensuite correctement, il faudra linker avec votre projet la librairie Yoctopuce et les librairies systèmes requises:

Attention, sous Linux, si vous voulez compiler en ligne de commande avec GCC, il est en général souhaitable de linker les librairies systèmes en dynamique et non en statique. Pour mélanger sur la même ligne de commande des librairies statiques et dynamiques, il faut passer les arguments suivants:

gcc (...) -Wl,-Bstatic -lyocto-static -Wl,-Bdynamic -lm -lpthread -lusb-1.0 -lstdc++

Intégration en librairie dynamique

L'intégration de la librairie Yoctopuce sous forme de librairie dynamique permet de produire un exécutable plus petit que les deux méthodes précédentes, et de mettre éventuellement à jour cette librairie si un correctif s'avérait nécessaire sans devoir recompiler le code source de l'application. Par contre, c'est un mode d'intégration qui exigera systématiquement de copier la librairie dynamique sur la machine cible ou l'application devra être lancée (yocto.dll sous Windows, libyocto.so.1.0.1 sous macOS et Linux).

Pour utiliser la librairie dynamique, il faut la compiler à l'aide du shell script build.sh sous UNIX, ou build.bat sous Windows. Ce script qui se situe à la racine de la librairie, détecte l'OS et recompile toutes les librairies ainsi que les exemples correspondant.

Ensuite, pour intégrer la librairie dynamique Yoctopuce à votre projet, vous devez inclure le répertoire Sources de la librairie Yoctopuce à votre IncludePath, et ajouter le sous-répertoire de Binaries/... correspondant à votre système d'exploitation à votre LibPath.

Finalement, pour que votre projet se construise ensuite correctement, il faudra linker avec votre projet la librairie dynamique Yoctopuce et les librairies systèmes requises:

Avec GCC, la ligne de commande de compilation est simplement:

gcc (...) -lyocto -lm -lpthread -lusb-1.0 -lstdc++

9. Utilisation du Yocto-MaxiKnob en C#

C# (prononcez C-Sharp) est un langage orienté objet promu par Microsoft qui n'est pas sans rappeller Java. Tout comme Visual Basic et Delphi, il permet de créer des applications Windows relativement facilement. C# est supporté sous Windows Visual Studio 2017 et ses versions plus récentes.

Notre librairie est aussi compatible avec Mono, la version open source de C# qui fonctionne sous Linux et macOS. Sous Linux, utilisez la version 5.20 ou plus récente. Le support de Mono sous macOS est limité aux systèmes 32bits, ce qui le rend de nos jours à peu près inutile.Vous trouverez sur notre site web différents articles qui décrivent comment indiquer à Mono comment accéder à notre librairie.

9.1. Installation

Téléchargez la librairie Yoctopuce pour Visual C# depuis le site web de Yoctopuce22. Il n'y a pas de programme d'installation, copiez simplement de contenu du fichier zip dans le répertoire de votre choix. Vous avez besoin essentiellement du contenu du répertoire Sources. Les autres répertoires contiennent la documentation et quelques programmes d'exemple. Les projets d'exemple sont des projets Visual C# 2010, si vous utilisez une version antérieure, il est possible que vous ayez à reconstruire la structure de ces projets.

9.2. Utilisation l'API yoctopuce dans un projet Visual C#

La librairie Yoctopuce pour Visual C# .NET se présente sous la forme d'une DLL et de fichiers sources en Visual C#. La DLL n'est pas une DLL .NET mais une DLL classique, écrite en C, qui gère les communications à bas niveau avec les modules23. Les fichiers sources en Visual C# gèrent la partie haut niveau de l'API. Vous avez donc besoin de cette DLL et des fichiers .cs du répertoire Sources pour créer un projet gérant des modules Yoctopuce.

Configuration d'un projet Visual C#

Les indications ci-dessous sont fournies pour Visual Studio express 2010, mais la procédure est semblable pour les autres versions.

Commencez par créer votre projet, puis depuis le panneau Explorateur de solutions effectuez un clic droit sur votre projet, et choisissez Ajouter puis Elément existant.

Une fenêtre de sélection de fichiers apparaît: sélectionnez le fichier yocto_api.cs et les fichiers correspondant aux fonctions des modules Yoctopuce que votre projet va gérer. Dans le doute, vous pouvez aussi sélectionner tous les fichiers.

Vous avez alors le choix entre simplement ajouter ces fichiers à votre projet, ou les ajouter en tant que lien (le bouton Ajouter est en fait un menu déroulant). Dans le premier cas, Visual Studio va copier les fichiers choisis dans votre projet, dans le second Visual Studio va simplement garder un lien sur les fichiers originaux. Il est recommandé d'utiliser des liens, une éventuelle mise à jour de la librairie sera ainsi beaucoup plus facile.

Ensuite, ajoutez de la même manière la dll yapi.dll, qui se trouve dans le répertoire Sources/dll24. Puis depuis la fenêtre Explorateur de solutions, effectuez un clic droit sur la DLL, choisissez Propriété et dans le panneau Propriétés, mettez l'option Copier dans le répertoire de sortie à toujours copier. Vous êtes maintenant prêt à utiliser vos modules Yoctopuce depuis votre environnement Visual Studio.

Afin de les garder simples, tous les exemples fournis dans cette documentation sont des applications consoles. Il va de soit que que les fonctionnement des librairies est strictement identiques si vous les intégrez dans une application dotée d'une interface graphique.

9.3. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code C# qui utilise la fonction AnButton.


[...]
// On active la détection des modules sur USB
string errmsg = "";
YAPI.RegisterHub("usb", errmsg);
[...]

// On récupère l'objet permettant d'intéragir avec le module
YAnButton anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1");

// Pour gérer le hot-plug, on vérifie que le module est là
if (anbutton.isOnline())
{
    // Utiliser anbutton.get_calibratedValue()
    [...]
}

Voyons maintenant en détail ce que font ces quelques lignes.

YAPI.RegisterHub

La fonction YAPI.RegisterHub initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Utilisée avec le paramètre "usb", elle permet de travailler avec les modules connectés localement à la machine. Si l'initialisation se passe mal, cette fonction renverra une valeur différente de YAPI.SUCCESS, et retournera via le paramètre errmsg une explication du problème.

YAnButton.FindAnButton

La fonction YAnButton.FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1");
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.MaFonction");
anbutton = YAnButton.FindAnButton("MonModule.anButton1");
anbutton = YAnButton.FindAnButton("MonModule.MaFonction");
anbutton = YAnButton.FindAnButton("MaFonction");

YAnButton.FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YQuadratureDecoder.FindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YBuzzer.FindBuzzer ou YBuzzer.FirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YColorLedCluster.FindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Lancez Visual C# et ouvrez le projet exemple correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

using System;

namespace ConsoleApplication1
{
  class Program
  {
    static void usage()
    {
      string execname = AppDomain.CurrentDomain.FriendlyName;
      Console.WriteLine("Usage:");
      Console.WriteLine(execname + "  <serial_number> ");
      Console.WriteLine(execname + "  <logical_name> ");
      Console.WriteLine(execname + "  any ");
      System.Threading.Thread.Sleep(2500);
      Environment.Exit(0);
    }

    static int notefreq(int note)
    {
      return (int) (220.0 * Math.Exp(note * Math.Log(2) / 12));
    }

    static void Main(string[] args)
    {
      string errmsg = "";
      string target, serial;
      YBuzzer buz;
      YColorLedCluster leds;
      YQuadratureDecoder qd;
      YAnButton button;

      if (args.Length < 1) usage();
      target = args[0].ToUpper();

      if (YAPI.RegisterHub("usb", ref errmsg) != YAPI.SUCCESS) {
        Console.WriteLine("RegisterHub error: " + errmsg);
        Environment.Exit(0);
      }

      if (target == "ANY") {
        buz = YBuzzer.FirstBuzzer();
        if (buz == null) {
          Console.WriteLine("No module connected (check USB cable) ");
          Environment.Exit(0);
        }
      } else buz = YBuzzer.FindBuzzer(target + ".buzzer");

      if (!buz.isOnline()) {
        Console.WriteLine("Module not connected");
        Console.WriteLine("check identification and USB cable");
        Environment.Exit(0);
      }

      serial = buz.get_module().get_serialNumber();
      leds = YColorLedCluster.FindColorLedCluster(serial + ".colorLedCluster");
      button = YAnButton.FindAnButton(serial + ".anButton1");
      qd = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1");

      if ((!button.isOnline()) || (!qd.isOnline())) {
        Console.WriteLine(
          "Make sure the Yocto-MaxiBuzzer is configured with at least one anButton and one quadrature Decoder");
        Environment.Exit(0);
      }

      Console.WriteLine("press a test button, or turn the encoder or hit Ctrl-C");

      int lastPos = (int) qd.get_currentValue();
      buz.set_volume(75);
      while (button.isOnline()) {
        if ((button.get_isPressed() == YAnButton.ISPRESSED_TRUE) && (lastPos != 0)) {
          lastPos = 0;
          qd.set_currentValue(0);
          buz.playNotes("'E32 C8");
          leds.set_rgbColor(0, 1, 0x000000);
        } else {
          int p = (int) qd.get_currentValue();
          if (lastPos != p) {
            lastPos = p;
            buz.pulse(notefreq(p), 500);
            leds.set_hslColor(0, 1, 0x00FF7f | (p % 255) << 16);
          }
        }
      }

      YAPI.FreeAPI();
    }
  }
}

9.4. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci-dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;


namespace ConsoleApplication1
{
  class Program
  {
    static void usage()
    {
      string execname = System.AppDomain.CurrentDomain.FriendlyName;
      Console.WriteLine("Usage:");
      Console.WriteLine(execname + " <serial or logical name> [ON/OFF]");
      System.Threading.Thread.Sleep(2500);
      Environment.Exit(0);
    }

    static void Main(string[] args)
    {
      YModule m;
      string errmsg = "";

      if (YAPI.RegisterHub("usb", ref errmsg) !=  YAPI.SUCCESS) {
        Console.WriteLine("RegisterHub error: " + errmsg);
        Environment.Exit(0);
      }


      if (args.Length < 1)  usage();

      m = YModule.FindModule(args[0]); // use serial or logical name

      if (m.isOnline()) {
        if (args.Length >= 2) {
          if (args[1].ToUpper() == "ON") {
            m.set_beacon(YModule.BEACON_ON);
          }
          if (args[1].ToUpper() == "OFF") {
            m.set_beacon(YModule.BEACON_OFF);
          }
        }

        Console.WriteLine("serial:       " + m.get_serialNumber());
        Console.WriteLine("logical name: " + m.get_logicalName());
        Console.WriteLine("luminosity:   " + m.get_luminosity().ToString());
        Console.Write("beacon:       ");
        if (m.get_beacon() == YModule.BEACON_ON)
          Console.WriteLine("ON");
        else
          Console.WriteLine("OFF");
        Console.WriteLine("upTime:       " + (m.get_upTime() / 1000 ).ToString() + " sec");
        Console.WriteLine("USB current:  " + m.get_usbCurrent().ToString() + " mA");
        Console.WriteLine("Logs:\r\n" + m.get_lastLogs());

      } else {
        Console.WriteLine(args[0] + " not connected (check identification and USB cable)");
      }
      YAPI.FreeAPI();
    }
  }
}
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type YModule.get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode YModule.set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction YModule.set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode YModule.saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode YModule.revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ConsoleApplication1
{
  class Program
  {
    static void usage()
    {
      string execname = System.AppDomain.CurrentDomain.FriendlyName;
      Console.WriteLine("Usage:");
      Console.WriteLine("usage: demo <serial or logical name> <new logical name>");
      System.Threading.Thread.Sleep(2500);
      Environment.Exit(0);
    }

    static void Main(string[] args)
    {
      YModule m;
      string errmsg = "";
      string newname;

      if (args.Length != 2) usage();

      if (YAPI.RegisterHub("usb", ref errmsg) !=  YAPI.SUCCESS) {
        Console.WriteLine("RegisterHub error: " + errmsg);
        Environment.Exit(0);
      }

      m = YModule.FindModule(args[0]); // use serial or logical name

      if (m.isOnline()) {
        newname = args[1];
        if (!YAPI.CheckLogicalName(newname)) {
          Console.WriteLine("Invalid name (" + newname + ")");
          Environment.Exit(0);
        }

        m.set_logicalName(newname);
        m.saveToFlash(); // do not forget this

        Console.Write("Module: serial= " + m.get_serialNumber());
        Console.WriteLine(" / name= " + m.get_logicalName());
      } else {
        Console.Write("not connected (check identification and USB cable");
      }
      YAPI.FreeAPI();
    }
  }
}
 

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction YModule.saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction YModule.yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la méthode nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un null. Ci-dessous un petit exemple listant les module connectés

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ConsoleApplication1
{
  class Program
  {
    static void Main(string[] args)
    {
      YModule m;
      string errmsg = "";

      if (YAPI.RegisterHub("usb", ref errmsg) !=  YAPI.SUCCESS) {
        Console.WriteLine("RegisterHub error: " + errmsg);
        Environment.Exit(0);
      }

      Console.WriteLine("Device list");
      m = YModule.FirstModule();
      while (m != null) {
        Console.WriteLine(m.get_serialNumber() + " (" + m.get_productName() + ")");
        m = m.nextModule();
      }
      YAPI.FreeAPI();
    }
  }
}
 

9.5. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

10. Utilisation du Yocto-MaxiKnob avec LabVIEW

LabVIEW est édité par National Instruments depuis 1986. C'est un environnement de développement graphique: plutôt que d'écrire des lignes de code, l'utilisateur dessine son programme, un peu comme un organigramme. LabVIEW est surtout pensé pour interfacer des instruments de mesures d'où le nom Virtual Instruments (VI) des programmes LabVIEW. Avec la programmation visuelle, dessiner des algorithmes complexes devient très vite fastidieux, c'est pourquoi la librairie Yoctopuce pour LabVIEW a été pensée pour être aussi simple de possible à utiliser. Autrement dit, LabVIEW étant un environnement extrêmement différent des autres langages supportés par l'API Yoctopuce, vous rencontrerez des différences majeures entre l'API LabVIEW et les autres API.

10.1. Architecture

La librairie LabVIEW est basée sur la librairie Yoctopuce DotNetProxy contenue dans la DLL DotNetProxyLibrary.dll. C'est en fait cette librairie DotNetProxy qui se charge du gros du travail en s'appuyant sur la librairie Yoctopuce C# qui, elle, utilise l'API bas niveau codée dans yapi.dll (32bits) et amd64\yapi.dll (64bits).


Architecture de l'API Yoctopuce pour LabVIEW

Vos applications LabVIEW utilisant l'API Yoctopuce devront donc impérativement être distribuées avec les DLL DotNetProxyLibrary.dll, yapi.dll et amd64\yapi.dll

Si besoin est, vous trouverez les sources de l'API bas niveau dans la librairie C# et les sources de DotNetProxyLibrary.dll dans la librairie DotNetProxy.

10.2. Compatibilité

Firmwares

Pour que la librairie Yoctopuce pour LabVIEW fonctionne convenablement avec vos modules Yoctopuce, ces derniers doivent avoir au moins le firmware 37120

LabVIEW pour Linux et MacOS

Au moment de l'écriture de ce manuel, l'API Yoctopuce pour LabVIEW n'a été testée que sous Windows. Il y a donc de fortes chances pour qu'elle ne fonctionne tout simplement pas avec les versions Linux et MacOS de LabVIEW.

LabVIEW NXG

La librairie Yoctopuce pour LabVIEW faisant appel à de nombreuses techniques qui ne sont pas encore disponibles dans la nouvelle génération de LabVIEW, elle n'est absolument pas compatible avec LabVIEW NXG.

A propos de DotNetProxyLibrary.dll

Afin d'être compatible avec un maximum de version de Windows, y compris Windows XP, la librairie DotNetProxyLibrary.dll est compilée en .NET 3.5, qui est disponible par défaut sur toutes les versions de Windows depuis XP.

10.3. Installation

Téléchargez la librairie pour LabVIEW depuis le site web de Yoctopuce25. Il s'agit d'un fichier ZIP dans lequel vous trouverez un répertoire par version de LabVIEW. Chacun de ses répertoires contient deux sous-répertoires. Le premier contient des exemples de programmation pour chaque produit Yoctopuce; le second, nommé VIs, contient tous les VI de l'API et les DLL nécessaires.

Suivant la configuration de Windows et la méthode utilisée pour la copier, la DLL DotNetProxyLibrary.dll peut se faire bloquer par Windows parce que ce dernier aura détecté qu'elle provient d'une autre machine. Un cas typique est la décompression de l'archive de la librairie avec l'explorateur de fichier de Windows. Si la DLL est bloquée, LabVIEW ne pourra pas la charger, ce qui entrainera une erreur 1386 lors de l'exécution de n'importe quel VI de la librairie Yoctopuce.

Il y a deux manières de corriger le problème. La plus simple consiste à utiliser l'explorateur de fichier de Windows pour afficher les propriétés de la DLL et la débloquer. Mais cette manipulation devra être répété à chaque fois qu'une nouvelle version de la DLL sera copiée sur votre système.


Débloquer la DLL DotNetProxyLibrary.dll.

La seconde méthode consiste à créer dans le même répertoire que l'exécutable labview.exe un fichier XML nommé labview.exe.config et contenant le code suivant :


<?xml version ="1.0"?>
<configuration>
 <runtime>
 <loadFromRemoteSources enabled="true" />
 </runtime>
</configuration>

Veillez à choisir le bon répertoire en fonction de la version de LabVIEW que vous utilisez (32 bits vs 64 bits). Vous trouverez plus d'information à propos de ce fichier sur le site web de National Instrument26.

Pour installer l'API Yoctopuce pour LabVIEW vous avez plusieurs méthodes à votre disposition.

Méthode 1 : Installation "à l'emporter"

La manière la plus simple pour installer la librairie Yoctopuce consiste à copier le contenu du répertoire VIs où bon vous semble, et à utiliser les VIs dans LabVIEW avec une simple opération de Drag and Drop.

Pour pouvoir utiliser les exemples fournis avec l'API, vous aurez avantage à ajouter le répertoire des VIs Yoctopuce dans la liste des répertoires où LabVIEW doit chercher les VIs qu'il n'a pas trouvé. Cette liste est accessible via le menu Tools > Options > Paths > VI Search Path.


Configuration du "VI Search Path"

Méthode 2 : Installeur fourni avec la librairie

Dans chaque répertoire LabVIEW200xx de la librairie, vous trouverez un VI appelé "Install.vi". Ouvrez simplement celui qui correspond à votre version de LabVIEW.


L'installeur fourni avec la librairie

Cet installeur offre trois options d'installation:

Install: Keep VI and documentation files where they are.

Avec cette option, les VI sont conservés à l'endroit où la librairie à été décompressée. Vous aurez donc à faire en sorte qu'ils ne soit pas effacés tant que vous en aurez besoin. Voici ce que fait exactement l'installeur quand cette option est choisie:

Install: Copy VI and documentation files into LabVIEW's vi.lib folder

Dans ce cas, tous les fichiers nécessaires au bon fonctionnement de la librairie sont copiés dans le répertoire d'installation de LabVIEW. Vous pourrez donc effacer les fichiers originaux une fois l'installation terminée. Notez cependant que les exemples de programmation ne sont pas copiés. Voici ce que fait l'installeur exactement:

Uninstall Yoctopuce Library

Cette option supprime la Librairie Yoctopuce de votre installation LabVIEW:

Dans tous les cas, si le fichier labview.ini a besoin d'être modifié, une copie de backup est automatiquement réalisée avant.

L'installeur reconnait les répertoires contenant la librairie Yoctopuce en testant l'existence du fichier YRegisterHub.vi.

Une fois l'installation terminée, vous trouverez une palette Yoctopuce dans le menu Fonction/Suppléments.

Méthode 3 Installation manuelle dans la palette LabVIEW

Les étapes pour installer manuellement les VIs directement dans la Palette LabView sont un peu plus complexes, vous trouverez la procédure complète sur le site de National Instruments27, mais voici un résumé:

  1. Créez un répertoire Yoctopuce\API dans le répertoire C:\Program Files\National Instruments\LabVIEW xxxx\vi.lib, et copiez tous les VIs et les DLL du répertoire VIs dedans.
  2. Créez un répertoire Yoctopuce dans le répertoire C:\Program Files\National Instruments\LabVIEW xxxx\menus\Categories
  3. Lancez LabVIEW, et choisissez l'option Tools>Advanced>Edit Palette Set

    Trois fenêtres vont apparaître:

    • "Edit Controls and Functions Palette Set"
    • "Functions"
    • "Controls"
    .

    Dans la fenêtre Function, vous trouverez une icône Yoctopuce. Double-cliquez dessus, ce qui fera apparaitre une fenêtre "Yoctopuce" vide.

  4. Dans la fenêtre Yoctopuce, faites un Clic Droit>Insert>Vi(s)..

    ce qui fera apparaître un sélecteur de fichier. Placer le sélecteur dans le répertoire vi.lib\Yoctopuce\API que vous avez créé au point 1 et cliquez sur Current Folder

    Tous les VIs Yoctopuce vont apparaitre dans la fenêtre Yoctopuce. Par défaut, ils sont triés dans l'ordre alphabétique, mais vous pouvez les arranger comme bon vous semble en les glissant avec la souris. Pour que la palette soit bien utilisable, nous vous suggérons de réorganiser les icônes sur 8 colonnes.
  5. Dans la fenêtre "Edit Controls and Functions Palette Set", cliquez sur le bouton "Save Changes", la fenêtre va vous indiquer qu'elle a créé un fichier dir.mnu dans votre répertoire Documents.

    Copiez ce fichier dans le répertoire "menus\Categories\Yoctopuce" que vous avez créé au point 2.
  6. Redémarrez LabVIEW, la palette de LabVIEW contient maintenant une sous-palette Yoctopuce et avec tous les VIs de l'API

10.4. Présentation des VIs Yoctopuce

La librairie Yoctopuce pour LabVIEW comprend un VI par classe de l'API Yoctopuce, plus quelques VI spéciaux. Tous les VIs disposent des connecteurs traditionnels Error IN et Error Out.

YRegisterHub

Le VI YRegisterHub permet d'initialiser l'API. Ce VI doit impérativement être appelé une fois avant de faire quoi que ce soit qui soit en relation avec des modules Yoctopuce


Le VI YRegisterHub

Le VI YRegisterHub prend un paramètre url qui peut être soit:

Dans le cas d'une adresse IP, le VI YRegisterHub va essayer de contacter cette adresse et génèrera une erreur s'il n'y arrive pas, à moins que le paramètre async ne soit mis à TRUE. Si async est mis à TRUE, aucune erreur ne sera générée, et les modules Yoctopuce correspondant à cette adresse IP seront automatiquement mis à disposition dès que la machine concernée sera joignable.

Si tout s'est bien passé, la sortie successful contiendra la valeur TRUE. Dans le cas contraire elle contiendra la valeur FALSE et la sortie error msg contiendra une chaîne de caractères contenant une description de l'erreur

Vous pouvez utiliser plusieurs VI YRegisterHub avec des urls différentes si vous le souhaitez. En revanche, sur la même machine, il ne peut y avoir qu'un seul processus qui accède aux modules Yoctopuce locaux directement par USB (url mis à "usb"). Cette limitation peut facilement être contournée en faisant tourner le logiciel VirtualHub sur la machine locale et en utilisant l'url "127.0.0.1".

YFreeAPI

Le VI YFreeAPI permet de libérer les ressources allouée par l'API Yoctopuce.


Le VI YFreeAPI

Le VI YFreeAPI doit être appelé une fois que votre code en a fini avec l'API Yoctopuce, faute de quoi l'accès direct par USB (url mis à "usb") pourrait rester bloqué une fois l'exécution de votre VI terminé, et ce tant que LabVIEW n'aura pas été complètement fermé.

Structure des VI correspondant à une classe

Les autres VIs correspondent à une fonction/classe de l'API Yoctopuce, ils ont tous la même structure:


Structure de la plupart des VIs de l'API.

Vous trouverez la liste des fonctions disponibles sur votre Yocto-MaxiKnob au chapitre Programmation, concepts généraux.

Si la fonction recherchée (paramètre name) n'est pas accessible, cela ne génèrera pas d'erreur mais la sortie is online contiendra FALSE et toutes les sorties contiendront les valeurs "N/A" quand c'est possible. Si la fonction recherchée devient disponible plus tard dans la vie de votre programme, is online passera à TRUE.

Si le paramètre name contient une chaîne vide, le VI ciblera la première fonction disponible du même type qu'il trouvera. Si aucune fonction n'est disponible, is online contiendra FALSE.

Le VI YModule

Le module YModule permet d'interfacer la partie "module" de chaque module Yoctopuce. Il permet de piloter la balise du module et de connaître le numéro de série d'un module.


Le VI YModule

L'entrée name fonctionne de manière légèrement différente des autres VIs. S'il est appelé avec le paramètre name correspondant à un nom de fonction, le VI YModule trouvera la fonction Module du module hébergeant la fonction. Il est donc possible de trouver facilement le numéro de série du module d'une fonction quelconque. Cela permet de construire le nom d'autres fonctions qui se trouveraient sur le même module. L'exemple ci dessous trouve la première fonction YHumidity disponible et construit le nom de la fonction YTemperature qui se trouve sur le même module. Les exemples fournis avec l'API Yoctopuce font un usage extensif de cette technique.


Utilisation du VI YModule pour retrouver les fonctions hébergés sur le même module

Les VI senseurs

Tous les VI correspondant à des senseurs Yoctopuce ont exactement la même géométrie. Les deux sorties permettent de récupérer la valeur mesurée par le capteur correspondant ainsi que l'unité utilisée.


Les VI senseurs ont tous exactement la même géométrie

Le paramètre d'entrée update freq est une chaîne de caractères qui permet de configurer la façon dont la valeur de sortie est mis à jour:

La fréquence de mise à jour du VI est un paramètre géré par le module Yoctopuce physique. Si plusieurs VI essayent de changer la fréquence d'un même capteur, la configuration retenue sera celle du dernier appel. Par contre, il est tout à fait possible de configurer des fréquences différentes pour des capteurs du même module Yoctopuce.


Changement de la fréquence de mise à jour du même module

La fréquence de mise à jour du VI est complètement indépendante de la fréquence d'échantillonnage du capteur qui n'est généralement pas modifiable. Il est inutile et contre-productif de définir une fréquence de mise à jour supérieure à la fréquence d'échantillonnage du capteur.

10.5. Fonctionnement et utilisation des VIs

Voici un exemple parmi les plus simples de VI utilisant l'API Yoctopuce.


Exemple minimal d'utilisation de l'API Yoctopuce pour LabVIEW

Cet exemple s'appuie sur le VI YSensor qui est un VI générique qui permet d'interfacer n'importe quelle fonction senseur d'un module Yoctopuce. Vous pouvez remplacer ce VI par n'importe quel autre de l'API Yoctopuce, ils ont tous la même géométrie et fonctionnent tous de la même manière. Cet exemple se contente de faire trois choses:

  1. Il initialise l'API en mode natif ("usb") avec le VI YRegisterHub
  2. Il affiche la valeur du premier capteur Yoctopuce qu'il trouve à l'aide du VI YSensor
  3. Il libère l'API grâce au VI YFreeAPI

Cet exemple cherche automatiquement un senseur disponible, si un tel senseur est trouvé on pourra connaitre son nom via la sortie hardware name et la sortie isOnline sera à TRUE. Si aucun senseur n'est disponible, le VI ne génèrera pas d'erreur mais émulera un senseur fantôme qui sera "offline". Par contre si plus tard, dans la vie de l'application, un senseur devient disponible parce qu'il à été branché, isOnline passera à TRUE et le hardware name contiendra le nom du capteur. On peut donc facilement ajouter quelques indicateurs à l'exemple précédent pour savoir comment se passe l'exécution.


Utilisation des sorties hardware name et isOnline

Les VIs de l'API Yoctopuce ne sont qu'une porte d'entrée sur la mécanique interne de la librairie Yoctopuce. Cette mécanique fonctionne indépendamment des VIs Yoctopuce. En effet, la plupart des communications avec les modules électroniques sont gérées automatiquement en arrière plan. C'est pourquoi vous n'avez pas forcément besoin de prendre de précaution particulière pour utiliser les VI Yoctopuce, vous pouvez par exemple les utiliser dans une boucle non temporisée sans que cela pose de problème particulier à l'API.


Les VIs Yoctopuce peuvent être utilisés dans une boucle non temporisée

Notez que le VI YRegisterHub n'est pas dans la boucle. Le VI YRegisterHub sert à l'initialiser l'API, donc à moins que vous n'ayez plusieurs url à enregistrer, il n'est pas souhaitable de l'appeler plusieurs fois.

Lorsque que le paramètre name est initialisé à une chaîne vide, les VI Yoctopuce recherchent automatiquement la fonction avec laquelle ils peuvent travailler, ce qui est très pratique lorsqu'on sait qu'il n'y a qu'une seule fonction du même type disponible que qu'on ne souhaite pas se soucier de gérer som nom. Si le paramètre name contient un nom matériel ou un nom logique, le VI cherchera la fonction correspondante, si il ne la trouve pas il émulera une fonction qui sera offline en attendant que la vraie fonction devienne disponible.


Utilisation de noms pour identifier les fonctions à utiliser

Gestion des erreurs

L'API Yoctopuce pour LabVIEW est codée pour gérer les erreurs d'une manière aussi gracieuse que possible: par exemple si vous utilisez un VI pour accéder à une fonction qui n'existe pas, sa sortie isOnline sera à FALSE, les autres sorties seront affecté à NaN et les entrées n'auront pas d'effet. Les erreurs fatales sont propagée à travers le canal traditionnel error in, error out.

Cependant, le VI YRegisterHub gère les erreurs de connexion de manière un peu différente. Afin de les rendre plus faciles à gérer, les erreurs de connexions sont signalées à l'aide de sorties Success et error msg. Si un problème apparait lors de l'appel au VI YRegisterHub, success contiendra FALSE et error msg contiendra une description de l'erreur.


Gestion des erreurs

Le message d'erreur le plus courant est "Another process is already using yAPI". Il signifie qu'une autre application, LabVIEW ou autre, utilise déjà l'API en module USB natif. En effet, pour des raison techniques, l'API USB native ne peut être utilisée que par une seule application à la fois sur la même machine. Cette limitation peut être facilement contourné en utilisant le mode réseau.

10.6. Utilisation des objets Proxy

L'API Yoctopuce contient des centaines de méthodes, fonctions et propriétés. Il n'était ni possible, ni souhaitable de créer un VI pour chacune d'entre elles. C'est pourquoi il y a un VI par classe qui expose les deux propriétés que Yoctopuce a jugé les plus utiles, mais cela ne veut pas dire que les autres ne sont pas accessibles.

Chaque VI correspondant à une classe dispose de deux connecteurs create ref et optional ref qui permettent d'obtenir une référence sur l'objet Proxy de l'API .NET Proxy sur laquelle est construite la librairie LabVIEW.


Les connecteurs pour obtenir une référence sur l'objet Proxy correspondant au VI

Pour obtenir cette référence, il suffit de mettre optional ref à TRUE. Attention, il est impératif de fermer toute référence créée de cette manière, sous peine de saturer rapidement la mémoire de l'ordinateur.

Voici un exemple qui utilise cette technique pour modifier la luminosité des LEDs d'un module Yoctopuce



Contrôle de la luminosité des LEDs d'un module

Notez que chaque référence permet d'obtenir aussi bien des propriétés (noeud property) que des méthodes (noeud invoke). Par convention, les propriétés sont optimisées pour générer un minimum de communication avec les modules, c'est pourquoi il est recommandé de les utiliser plutôt les méthodes get_xxx et set_xxx correspondantes qui pourraient sembler équivalentes mais qui ne sont pas optimisées. Les propriétés permettent aussi récupérer les différentes constantes de l'API, qui sont préfixées avec le caractère "_". Pour des raisons techniques, les méthodes get_xxx et set_xxx ne sont pas toutes disponibles sous forme de propriétés.



Noeuds Property et Invoke: Utilisation de propriétés, méthodes et constantes

Vous trouverez la description de toutes les propriétés, fonctions et méthodes disponibles dans la documentation de l'API .NET Proxy.

Utilisation en réseau

Sur une même machine, il ne peut y avoir qu'un seul processus qui accède aux modules Yoctopuce locaux directement par USB (url mis à "usb"). Par contre, plusieurs processus peuvent se connecter en parallèle à des YoctoHubs31 ou à une machine sur laquelle tourne le logiciel VirtualHub32, y compris la machine locale. Si vous utilisez l'adresse réseau locale de votre machine (127.0.0.1) et qu'un VirtualHub tourne dessus, vous pourrez ainsi contourner la limitation qui empêche l'utilisation en parallèle de l'API native USB.


Utilisation en mode réseau

Il n'y a pas non plus de limitation sur le nombre d'interfaces réseau auxquels l'API peut se connecter en parallèle. Autrement dit, il est tout à fait possible de faire des appels multiples au VI YRegisterHub. C'est le seul cas où il y a un intérêt à appeler le VI YRegisterHub plusieurs fois au cours de la vie de l'application.


Les connexions réseau multiples sont possibles

Par défaut, le VI YRegisterHub essaye se connecter sur l'adresse donnée en paramètre et génère une erreur (success=FALSE) s'il n'y arrive pas parce que personne ne répond. Mais si le paramètre async est initialisé à TRUE, aucune erreur ne sera générée en cas d'erreur de connexion, mais si la connexion devient possible plus tard dans la vie de l'application, les modules correspondants seront automatiquement accessibles.


Connexion asynchrone

10.7. Gestion du datalogger

Quasiment tous les senseurs Yoctopuce disposent d'un enregistreur de données qui permet de stocker les mesures des senseurs dans la mémoire non volatile du module. La configuration de l'enregistreur de données peut être réalisée avec le VirtualHub, mais aussi à l'aide d'un peu de code LabVIEW

Enregistrement

Pour ce faire, il faut configurer la fréquence d'enregistrement en utilisant la propriété "LogFrequency" que l'on atteint avec une référence sur l'objet Proxy du senseur utilisé, puis il faut mettre en marche l'enregistreur grâce au VI YDataLogger. Noter qu'à la manière du VI YModule, le VI YDataLogger correspondant à un module peut être obtenu avec son propre nom, mais aussi avec le nom de n'importe laquelle des fonctions présentes sur le même module.


Enclenchement de l'enregistrement de données dans le datalogger

Lecture

La récupération des données de l'enregistreur se fait l'aide du VI YDataLoggerContents.


Le VI YDataLoggerContents

Extraire les données de l'enregistreur d'un module Yoctopuce est un processus lent qui peut prendre plusieurs dizaines de secondes. C'est pourquoi le VI qui permet cette opération a été conçu pour fonctionner de manière itérative.

Dans un premier temps le VI doit être appelé avec un nom de senseur, une date de début et une date de fin (timestamp UNIX en UTC). Le couple (0,0) permet d'obtenir la totalité du contenu de l'enregistreur. Ce premier appel permet d'obtenir un résumé du contenu du datalogger et un contexte.

Dans un deuxième temps, il faut rappeler le VI YDataLoggerContents en boucle avec le paramètre contexte, jusqu'à ce que la sortie progress atteigne la valeur 100. A ce moment la sortie data représente le contenu de l'enregistreur


Récupération du contenu de l'engistreur de données

Les résultats et le résumé sont rendus sous la forme d'un tableau de structures qui contiennent les champs suivants:

Notez que si la fréquence d'enregistrement est supérieure à 1 Hz, l'enregistreur ne mémorise que des valeurs instantanées, dans ce cas averageValue, minValue, et maxValue auront la même valeur.

10.8. Énumération de fonctions

Chaque VI correspondant à un objet de l'API .NET Proxy permet de faire une énumération de toutes les fonctions de la même classe via la méthode getSimilarfunctions() de l'objet Proxy correspondant. Ainsi il est ainsi aisé de faire un inventaire de tous les modules connectés, de tous les capteurs connectés, de tous les relais connectés, etc....


Récupération de la liste de tous les modules connectés

10.9. Un mot sur les performances

L'API Yoctopuce pour LabVIEW été optimisée de manière à ce que les tous les VIs et les propriétés de objets Proxy génèrent un minimum de communication avec les modules Yoctopuce. Ainsi vous pouvez les utiliser dans des boucles sans prendre de précaution particulière: vous n'êtes pas obligés de ralentir les boucles avec un timer.


Ces deux boucles génèrent peu de communications USB et n'ont pas besoin d'être ralenties

En revanche, presque toutes les méthodes des objets Proxy disponibles vont générer une communication avec les modules Yoctopuce à chaque fois qu'elles seront appelées, il conviendra donc d'éviter de les appeler trop souvent inutilement.


Cette boucle, qui utilise une méthode, doit être ralentie

10.10. Un exemple complet de programme LabVIEW

Voici un exemple qui illustre l'utilisation d'un Yocto-MaxiKnob dans LabVIEW. Après un appel au VI RegisterHub, le VI YBuzzer trouve le premier buzzer disponible, et utilise le VI YModule pour trouver le numéro de série du module. Ce numéro de série est utilisé pour construire le nom hardware de toutes les autres fonctions hébergées par le module. Ces noms sont utilisés comme paramètres pour initialiser les VI correspondant à chaque fonction. Cette technique évite les ambiguïtés au cas où plusieurs Yocto-MaxiKnob seraient branchés. Une fois les VIs correspondants aux fonctions initialisés, le programme vérifie si l'encodeur 1 a bougé, si oui il jour une note correspondant à la position de l'encodeur et change légèrement la couleur de la LED RGB. Si l'utilisateur appuie sur le bouton 1, le programme réinitialise la position de l'encodeur. Si l'utilisateur appuie sur le bouton STOP de l'interface , la programme s'arrête et l'API Yoctopuce est libérée à l'aide du du VI YFreeAPI.


Exemple d'utilisation du Yocto-MaxiKnob dans LabVIEW

Si vous lisez cette documentation sur un écran, vous pouvez zoomer sur l'image ci-dessus. Vous pourrez aussi retrouver cet exemple dans la librairie Yoctopuce pour LabVIEW

10.11. Différences avec les autres API Yoctopuce

Yoctopuce fait tout son possible pour maintenir une forte cohérence entre les différentes librairies de programmation. Cependant, LabVIEW étant un environnement clairement à part, il en résulte des différences importantes avec les autres librairies.

Ces différences ont aussi été introduites pour rendre l'utilisation des modules aussi facile et intuitive que possible en nécessitant un minimum de code LabVIEW.

YFreeAPI

Contrairement aux autres langages, il est indispensable de libérer l'API native en appelant le VI YFreeApi lorsque votre code n'a plus besoin d'utiliser l'API. Si cet appel est omis, l'API native risque de rester bloquée pour les autres applications tant que LabVIEW ne sera pas complètement fermé.

Propriétés

Contrairement aux classes des autres API, les classes disponibles dans LabVIEW implémentent des propriétés. Par convention, ces propriétés sont optimisées pour générer un minimum de communication avec les modules tout en se rafraichissant automatiquement. En revanche, les méthodes de type get_xxx et set_xxx génèrent systématiquement des communications avec les modules Yoctopuce et doivent être appelées à bon escient.

Callback vs Propriétés

Il n'y a pas de callbacks dans l'API Yoctopuce pour LabVIEW, les VIs se rafraichissenti automatiquement: ils sont basés sur les propriétés des objets de l'API .NET Proxy.

11. Utilisation du Yocto-MaxiKnob en Java

Java est un langage orienté objet développé par Sun Microsystem. Son principal avantage est la portabilité, mais cette portabilité a un coût. Java fait une telle abstraction des couches matérielles qu'il est très difficile d'interagir directement avec elles. C'est pourquoi l'API java standard de Yoctopuce ne fonctionne pas en natif: elle doit passer par l'intermédiaire de VirtualHub pour pouvoir communiquer avec les modules Yoctopuce.

11.1. Préparation

Connectez vous sur le site de Yoctopuce et téléchargez les éléments suivants:

La librairie est disponible en fichier sources, mais elle aussi disponible sous la forme d'un fichier jar. Branchez vos modules, Décompressez les fichiers de la librairie dans un répertoire de votre choix. Lancez VirtualHub et vous pouvez commencer vos premiers tests. Vous n'avez pas besoin d'installer de driver.

Afin de les garder simples, tous les exemples fournis dans cette documentation sont des applications consoles. Il va de soit que que le fonctionnement des librairies est strictement identiques si vous les intégrez dans une application dotée d'une interface graphique.

11.2. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code Java qui utilise la fonction AnButton.


[...]
// On active l'accès aux modules locaux à travers le VirtualHub
YAPI.RegisterHub("127.0.0.1");
[...]

// On récupère l'objet permettant d'intéragir avec le module
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1");

// Pour gérer le hot-plug, on vérifie que le module est là
if (anbutton.isOnline())
{
    // Utiliser anbutton.get_calibratedValue()
    [...]
}
   
[...]

Voyons maintenant en détail ce que font ces quelques lignes.

YAPI.RegisterHub

La fonction YAPI.RegisterHub initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Le paramètre est l'adresse du virtual hub capable de voir les modules. Si l'initialisation se passe mal, une exception sera générée.

YAnButton.FindAnButton

La fonction YAnButton.FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1")
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.MaFonction")
anbutton = YAnButton.FindAnButton("MonModule.anButton1")
anbutton = YAnButton.FindAnButton("MonModule.MaFonction")
anbutton = YAnButton.FindAnButton("MaFonction")

YAnButton.FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YQuadratureDecoder.FindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YBuzzer.FindBuzzer ou YBuzzer.FirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YColorLedCluster.FindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Lancez votre environnement java et ouvrez le projet correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

import com.yoctopuce.YoctoAPI.*;

import static java.lang.Math.exp;
import static java.lang.Math.log;

public class Demo {

    public static void main(String[] args) {
        try {
            // setup the API to use local VirtualHub
            YAPI.RegisterHub("127.0.0.1");
        } catch (YAPI_Exception ex) {
            System.out.println("Cannot contact VirtualHub on 127.0.0.1 (" + ex.getLocalizedMessage() + ")");
            System.out.println("Ensure that the VirtualHub application is running");
            System.exit(1);
        }
        YBuzzer buzzer;
        if (args.length > 0) {
            buzzer = YBuzzer.FindBuzzer(args[0]);
        } else {
            buzzer = YBuzzer.FirstBuzzer();
            if (buzzer == null) {
                System.out.println("No module connected (check USB cable)");
                System.exit(1);
            }
        }
        if (!buzzer.isOnline()) {
            System.out.println("Module not connected (check identification and USB cable)");
            System.exit(1);
        }

        try {
            String serial = buzzer.get_module().get_serialNumber();
            YColorLedCluster leds = YColorLedCluster.FindColorLedCluster(serial + ".colorLedCluster");
            YAnButton button = YAnButton.FindAnButton(serial + ".anButton1");
            YQuadratureDecoder qd = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1");

            int lastPos = (int) qd.get_currentValue();
            buzzer.set_volume(75);
            System.out.println("press  button #1, turn encoder #1  or hit Ctrl-C");
            while (button.isOnline()) {
                if ((button.get_isPressed() == YAnButton.ISPRESSED_TRUE) && (lastPos != 0)) {
                    lastPos = 0;
                    qd.set_currentValue(0);
                    buzzer.playNotes("'E32 C8");
                    leds.set_rgbColor(0, 1, 0x000000);
                } else {
                    int p = (int) qd.get_currentValue();
                    if (lastPos != p) {
                        lastPos = p;
                        buzzer.pulse(notefreq(p), 100);
                        leds.set_hslColor(0, 1, 0x00FF7f | (p % 255) << 16);
                    }
                }
            }
        } catch (YAPI_Exception ex) {
            System.out.println("Module not connected (check identification and USB cable)");
        }
        YAPI.FreeAPI();
    }

    private static int notefreq(int note) {
        return (int) (220.0 * exp(note * log(2) / 12));
    }
}
 

11.3. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci-dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.


import com.yoctopuce.YoctoAPI.*;
import java.util.logging.Level;
import java.util.logging.Logger;

public class Demo {

    public static void main(String[] args)
    {
        try {
            // setup the API to use local VirtualHub
            YAPI.RegisterHub("127.0.0.1");
        } catch (YAPI_Exception ex) {
            System.out.println("Cannot contact VirtualHub on 127.0.0.1 (" + ex.getLocalizedMessage() + ")");
            System.out.println("Ensure that the VirtualHub application is running");
            System.exit(1);
        }
        System.out.println("usage: demo [serial or logical name] [ON/OFF]");

        YModule module;
        if (args.length == 0) {
            module = YModule.FirstModule();
            if (module == null) {
                System.out.println("No module connected (check USB cable)");
                System.exit(1);
            }
        } else {
            module = YModule.FindModule(args[0]);  // use serial or logical name
        }

        try {
            if (args.length > 1) {
                if (args[1].equalsIgnoreCase("ON")) {
                    module.setBeacon(YModule.BEACON_ON);
                } else {
                    module.setBeacon(YModule.BEACON_OFF);
                }
            }
            System.out.println("serial:       " + module.get_serialNumber());
            System.out.println("logical name: " + module.get_logicalName());
            System.out.println("luminosity:   " + module.get_luminosity());
            if (module.get_beacon() == YModule.BEACON_ON) {
                System.out.println("beacon:       ON");
            } else {
                System.out.println("beacon:       OFF");
            }
            System.out.println("upTime:       " + module.get_upTime() / 1000 + " sec");
            System.out.println("USB current:  " + module.get_usbCurrent() + " mA");
            System.out.println("logs:\n" + module.get_lastLogs());
        } catch (YAPI_Exception ex) {
            System.out.println(args[1] + " not connected (check identification and USB cable)");
        }
        YAPI.FreeAPI();
    }
}
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type YModule.get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode YModule.set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction YModule.set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode YModule.saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode YModule.revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

import com.yoctopuce.YoctoAPI.*;

public class Demo {

    public static void main(String[] args)
    {
        try {
            // setup the API to use local VirtualHub
            YAPI.RegisterHub("127.0.0.1");
        } catch (YAPI_Exception ex) {
            System.out.println("Cannot contact VirtualHub on 127.0.0.1 (" + ex.getLocalizedMessage() + ")");
            System.out.println("Ensure that the VirtualHub application is running");
            System.exit(1);
        }

        if (args.length != 2) {
            System.out.println("usage: demo <serial or logical name> <new logical name>");
            System.exit(1);
        }

        YModule m;
        String newname;

        m = YModule.FindModule(args[0]); // use serial or logical name

        try {
            newname = args[1];
            if (!YAPI.CheckLogicalName(newname))
                {
                    System.out.println("Invalid name (" + newname + ")");
                    System.exit(1);
                }

            m.set_logicalName(newname);
            m.saveToFlash(); // do not forget this

            System.out.println("Module: serial= " + m.get_serialNumber());
            System.out.println(" / name= " + m.get_logicalName());
        } catch (YAPI_Exception ex) {
            System.out.println("Module " + args[0] + "not connected (check identification and USB cable)");
            System.out.println(ex.getMessage());
            System.exit(1);
        }

        YAPI.FreeAPI();
    }
}
 

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction YModule.saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction YModule.yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la mehode nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un null. Ci-dessous un petit exemple listant les module connectés

import com.yoctopuce.YoctoAPI.*;

public class Demo {

    public static void main(String[] args)
    {
        try {
            // setup the API to use local VirtualHub
            YAPI.RegisterHub("127.0.0.1");
        } catch (YAPI_Exception ex) {
            System.out.println("Cannot contact VirtualHub on 127.0.0.1 (" + ex.getLocalizedMessage() + ")");
            System.out.println("Ensure that the VirtualHub application is running");
            System.exit(1);
        }

        System.out.println("Device list");
        YModule module = YModule.FirstModule();
        while (module != null) {
            try {
                System.out.println(module.get_serialNumber() + " (" + module.get_productName() + ")");
            } catch (YAPI_Exception ex) {
                break;
            }
            module = module.nextModule();
        }
        YAPI.FreeAPI();
    }
}
 

11.4. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme.

Dans l'API java, le traitement d'erreur est implémenté au moyen d'exceptions. Vous devrez donc intercepter et traiter correctement ces exceptions si vous souhaitez avoir un projet fiable qui ne crashera pas des que vous débrancherez un module.

12. Utilisation du Yocto-MaxiKnob avec Android

A vrai dire, Android n'est pas un langage de programmation, c'est un système d'exploitation développé par Google pour les appareils portables tels que smart phones et tablettes. Mais il se trouve que sous Android tout est programmé avec le même langage de programmation: Java. En revanche les paradigmes de programmation et les possibilités d'accès au hardware sont légèrement différentes par rapport au Java classique, ce qui justifie un chapitre à part sur la programmation Android.

12.1. Accès Natif et VirtualHub

Contrairement à l'API Java classique, l'API Java pour Android accède aux modules USB de manière native. En revanche, comme il n'existe pas de VirtualHub tournant sous Android, il n'est pas possible de prendre le contrôle à distance de modules Yoctopuce pilotés par une machine sous Android. Bien sûr, l'API Java pour Android reste parfaitement capable de se connecter à VirtualHub tournant sur un autre OS.

12.2. Préparation

Connectez-vous sur le site de Yoctopuce et téléchargez la librairie de programmation pour Java pour Android35. La librairie est disponible en fichiers sources, mais elle aussi disponible sous la forme d'un fichier jar. Branchez vos modules, décompressez les fichiers de la librairie dans le répertoire de votre choix. Et configurez votre environnement de programmation Android pour qu'il puisse les trouver.

Afin de les garder simples, tous les exemples fournis dans cette documentation sont des fragments d'application Android. Vous devrez les intégrer dans vos propres applications Android pour les faire fonctionner. En revanche vous pourrez trouver des applications complètes dans les exemples fournis avec la librairie Java pour Android.

12.3. Compatibilité

Dans un monde idéal, il suffirait d'avoir un téléphone sous Android pour pouvoir faire fonctionner des modules Yoctopuce. Malheureusement, la réalité est légèrement différente, un appareil tournant sous Android doit répondre à un certain nombre d'exigences pour pouvoir faire fonctionner des modules USB Yoctopuce en natif.

Version d'Android

Notre librairie peut être compilée pour fonctionner avec les anciennes versions aussi longtemps que les outils Android nous permettent de les supporter, soit environ les versions des dix dernières années.

Support USB host

Il faut bien sûr que votre machine dispose non seulement d'un port USB, mais il faut aussi que ce port soit capable de tourner en mode host. En mode host, la machine prend littéralement le contrôle des périphériques qui lui sont raccordés. Les ports USB d'un ordinateur bureau, par exemple, fonctionnent mode host. Le pendant du mode host est le mode device. Les clefs USB par exemple fonctionnent en mode device: elles ne peuvent qu'être contrôlées par un host. Certains ports USB sont capables de fonctionner dans les deux modes, ils s'agit de ports OTG (On The Go). Il se trouve que beaucoup d'appareils portables ne fonctionnent qu'en mode "device": ils sont conçus pour être branchés à chargeur ou un ordinateur de bureau, rien de plus. Il est donc fortement recommandé de lire attentivement les spécifications techniques d'un produit fonctionnant sous Android avant d'espérer le voir fonctionner avec des modules Yoctopuce.

Disposer d'une version correcte d'Android et de ports USB fonctionnant en mode host ne suffit malheureusement pas pour garantir un bon fonctionnement avec des modules Yoctopuce sous Android. En effet certains constructeurs configurent leur image Android afin que les périphériques autres que clavier et mass storage soit ignorés, et cette configuration est difficilement détectable. En l'état actuel des choses, le meilleur moyen de savoir avec certitude si un matériel Android spécifique fonctionne avec les modules Yoctopuce consiste à essayer.

12.4. Activer le port USB sous Android

Par défaut Android n’autorise pas une application à accéder aux périphériques connectés au port USB. Pour que votre application puisse interagir avec un module Yoctopuce branché directement sur votre tablette sur un port USB quelques étapes supplémentaires sont nécessaires. Si vous comptez uniquement interagir avec des modules connectés sur une autre machine par IP, vous pouvez ignorer cette section.

Il faut déclarer dans son AndroidManifest.xml l'utilisation de la fonctionnalité "USB Host" en ajoutant le tag <uses-feature android:name="android.hardware.usb.host" /> dans la section manifest.


<manifest ...>
    ...
    <uses-feature android:name="android.hardware.usb.host" />;
    ...
</manifest>

Lors du premier accès à un module Yoctopuce, Android va ouvrir une fenêtre pour informer l'utilisateur que l'application va accéder module connecté. L'utilisateur peut refuser ou autoriser l’accès au périphérique. Si l'utilisateur accepte, l'application pourra accéder au périphérique connecté jusqu'à la prochaine déconnexion du périphérique. Pour que la librairie Yoctopuce puisse gérer correctement ces autorisations, il faut lui fournir un pointeur sur le contexte de l'application en appelant la méthode EnableUSBHost de la classe YAPI avant le premier accès USB. Cette fonction prend en argument un objet de la classe android.content.Context (ou d'une sous-classe). Comme la classe Activity est une sous-classe de Context, le plus simple est de d'appeler YAPI.EnableUSBHost(this); dans la méthode onCreate de votre application. Si l'objet passé en paramètre n'est pas du bon type, une exception YAPI_Exception sera générée.


...
@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    try {
                // Pass the application Context to the Yoctopuce Library
        YAPI.EnableUSBHost(this);
        } catch (YAPI_Exception e) {
                Log.e("Yocto",e.getLocalizedMessage());
        }
}
...

Lancement automatique

Il est possible d'enregistrer son application comme application par défaut pour un module USB, dans ce cas des qu'un module sera connecté au système, l'application sera lancée automatiquement. Il faut ajouter <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"/> dans la section <intent-filter> de l'activité principale. La section <activity> doit contenir un pointeur sur un fichier xml qui contient la liste des modules USB qui peuvent lancer l'application.


<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    <uses-feature android:name="android.hardware.usb.host" />
    ...
    <application ... >
        <activity
            android:name=".MainActivity" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

            <meta-data
                android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
                android:resource="@xml/device_filter" />
        </activity>
    </application>

</manifest>

Le fichier XML qui contient la liste des modules qui peuvent lancer l'application doit être sauvé dans le répertoire res/xml. Ce fichier contient une liste de vendorId et deviceID USB en décimal. L'exemple suivant lance l'application dès qu'un Yocto-Relay ou un Yocto-PowerRelay est connecté. Vous pouvez trouver le vendorId et deviceId des modules Yoctopuce dans la section caractéristiques de la documentation.


<?xml version="1.0" encoding="utf-8"?>

<resources>
    <usb-device vendor-id="9440" product-id="12" />
    <usb-device vendor-id="9440" product-id="13" />
</resources>

12.5. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code Java qui utilise la fonction AnButton.


[...]
// On active la détection des modules sur USB
YAPI.EnableUSBHost(this);
YAPI.RegisterHub("usb");
[...]
// On récupère l'objet permettant de communiquer avec le module
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1");

// Pour gérer le hot-plug, on vérifie que le module est là
if (anbutton.isOnline())
{
    // Utilisez anbutton.get_calibratedValue()
    [...]
}

[...]

Voyons maintenant en détail ce que font ces quelques lignes.

YAPI.EnableUSBHost

La fonction YAPI.EnableUSBHost initialise l'API avec le Context de l'application courante. Cette fonction prend en argument un objet de la classe android.content.Context (ou d'une sous-classe). Si vous comptez uniquement vous connecter à d'autres machines par IP vous cette fonction est factultative.

YAPI.RegisterHub

La fonction YAPI.RegisterHub initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Le paramètre est l'adresse du virtual hub capable de voir les modules. Si l'on passe la chaine de caractère "usb", l'API va travailler avec les modules connectés localement à la machine. Si l'initialisation se passe mal, une exception sera générée.

YAnButton.FindAnButton

La fonction YAnButton.FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1")
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.MaFonction")
anbutton = YAnButton.FindAnButton("MonModule.anButton1")
anbutton = YAnButton.FindAnButton("MonModule.MaFonction")
anbutton = YAnButton.FindAnButton("MaFonction")

YAnButton.FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YQuadratureDecoder.FindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YBuzzer.FindBuzzer ou YBuzzer.FirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YColorLedCluster.FindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Lancez votre environnement java et ouvrez le projet correspondant, fourni dans le répertoire Examples/Doc-Examples de la librairie Yoctopuce.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

package com.yoctopuce.doc_examples;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.AdapterView;
import android.widget.AdapterView.OnItemSelectedListener;
import android.widget.ArrayAdapter;
import android.widget.Spinner;
import android.widget.TextView;

import com.yoctopuce.YoctoAPI.YAPI;
import com.yoctopuce.YoctoAPI.YAPI_Exception;
import com.yoctopuce.YoctoAPI.YBuzzer;
import com.yoctopuce.YoctoAPI.YAnButton;
import com.yoctopuce.YoctoAPI.YQuadratureDecoder;
import com.yoctopuce.YoctoAPI.YColorLedCluster;
import com.yoctopuce.YoctoAPI.YModule;

import static java.lang.Math.exp;
import static java.lang.Math.log;

public class GettingStarted_Yocto_MaxiKnob extends Activity implements OnItemSelectedListener, Runnable {

    private String serial = null;
    private ArrayAdapter<String> aa;
    private Thread bgthread;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.gettingstarted_yocto_maxiknob);
        Spinner my_spin = (Spinner) findViewById(R.id.spinner1);
        my_spin.setOnItemSelectedListener(this);
        aa = new ArrayAdapter<>(this, android.R.layout.simple_spinner_item);
        aa.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
        my_spin.setAdapter(aa);
    }

    @Override
    protected void onStart() {
        super.onStart();
        try {
            aa.clear();
            YAPI.EnableUSBHost(this);
            YAPI.RegisterHub("usb");
            YModule module = YModule.FirstModule();
            while (module != null) {
                if (module.get_productName().equals("Yocto-MaxiKnob")) {
                    String serial = module.get_serialNumber();
                    aa.add(serial);
                }
                module = module.nextModule();
            }
        } catch (YAPI_Exception e) {
            e.printStackTrace();
        }
        aa.notifyDataSetChanged();
    }

    @Override
    protected void onStop() {
        super.onStop();
        serial = null;
        try {
            bgthread.join();
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        YAPI.FreeAPI();
    }

    @Override
    public void onItemSelected(AdapterView<?> parent, View view, int pos, long id) {
        serial = parent.getItemAtPosition(pos).toString();
        bgthread = new Thread(this);
        bgthread.start();
        TextView textView = (TextView) findViewById(R.id.message);
        textView.setText("Press a test button, or turn the encoder on the Yocto-MaxiBuzzer");
    }

    @Override
    public void onNothingSelected(AdapterView<?> arg0) {
    }

    @Override
    public void run() {
        while (serial != null) {
            try {
                YBuzzer buzzer = YBuzzer.FindBuzzer(serial + ".buzzer");
                YColorLedCluster leds = YColorLedCluster.FindColorLedCluster(serial + ".colorLedCluster");
                YAnButton button = YAnButton.FindAnButton(serial + ".anButton1");
                YQuadratureDecoder qd = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1");
                int lastPos = (int) qd.get_currentValue();
                buzzer.set_volume(75);
                while (button.isOnline()) {
                    if ((button.get_isPressed() == YAnButton.ISPRESSED_TRUE) && (lastPos != 0)) {
                        lastPos = 0;
                        qd.set_currentValue(0);
                        buzzer.playNotes("'E32 C8");
                        leds.set_rgbColor(0, 1, 0x000000);
                    } else {
                        int p = (int) qd.get_currentValue();
                        if (lastPos != p) {
                            lastPos = p;
                            buzzer.pulse(notefreq(p), 100);
                            leds.set_hslColor(0, 1, 0x00FF7f | (p % 255) << 16);
                        }
                    }
                }
            } catch (YAPI_Exception ex) {
                ex.printStackTrace();
            }
        }
    }

    private int notefreq(int note) {
        return (int) (220.0 * exp(note * log(2) / 12));
    }
}
 

12.6. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci-dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

package com.yoctopuce.doc_examples;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.AdapterView;
import android.widget.AdapterView.OnItemSelectedListener;
import android.widget.ArrayAdapter;
import android.widget.Spinner;
import android.widget.Switch;
import android.widget.TextView;

import com.yoctopuce.YoctoAPI.YAPI;
import com.yoctopuce.YoctoAPI.YAPI_Exception;
import com.yoctopuce.YoctoAPI.YModule;

public class ModuleControl extends Activity implements OnItemSelectedListener
{

    private ArrayAdapter<String> aa;
    private YModule module = null;

    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.modulecontrol);
        Spinner my_spin = (Spinner) findViewById(R.id.spinner1);
        my_spin.setOnItemSelectedListener(this);
        aa = new ArrayAdapter<String>(this, android.R.layout.simple_spinner_item);
        aa.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
        my_spin.setAdapter(aa);
    }

    @Override
    protected void onStart()
    {
        super.onStart();

        try {
            aa.clear();
            YAPI.EnableUSBHost(this);
            YAPI.RegisterHub("usb");
            YModule r = YModule.FirstModule();
            while (r != null) {
                String hwid = r.get_hardwareId();
                aa.add(hwid);
                r = r.nextModule();
            }
        } catch (YAPI_Exception e) {
            e.printStackTrace();
        }
        // refresh Spinner with detected relay
        aa.notifyDataSetChanged();
    }

    @Override
    protected void onStop()
    {
        super.onStop();
        YAPI.FreeAPI();
    }

    private void DisplayModuleInfo()
    {
        TextView field;
        if (module == null)
            return;
        try {
            field = (TextView) findViewById(R.id.serialfield);
            field.setText(module.getSerialNumber());
            field = (TextView) findViewById(R.id.logicalnamefield);
            field.setText(module.getLogicalName());
            field = (TextView) findViewById(R.id.luminosityfield);
            field.setText(String.format("%d%%", module.getLuminosity()));
            field = (TextView) findViewById(R.id.uptimefield);
            field.setText(module.getUpTime() / 1000 + " sec");
            field = (TextView) findViewById(R.id.usbcurrentfield);
            field.setText(module.getUsbCurrent() + " mA");
            Switch sw = (Switch) findViewById(R.id.beaconswitch);
            sw.setChecked(module.getBeacon() == YModule.BEACON_ON);
            field = (TextView) findViewById(R.id.logs);
            field.setText(module.get_lastLogs());

        } catch (YAPI_Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onItemSelected(AdapterView<?> parent, View view, int pos, long id)
    {
        String hwid = parent.getItemAtPosition(pos).toString();
        module = YModule.FindModule(hwid);
        DisplayModuleInfo();
    }

    @Override
    public void onNothingSelected(AdapterView<?> arg0)
    {
    }

    public void refreshInfo(View view)
    {
        DisplayModuleInfo();
    }

    public void toggleBeacon(View view)
    {
        if (module == null)
            return;
        boolean on = ((Switch) view).isChecked();

        try {
            if (on) {
                module.setBeacon(YModule.BEACON_ON);
            } else {
                module.setBeacon(YModule.BEACON_OFF);
            }
        } catch (YAPI_Exception e) {
            e.printStackTrace();
        }
    }
}
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type YModule.get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode YModule.set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction YModule.set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode YModule.saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode YModule.revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

package com.yoctopuce.doc_examples;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.AdapterView;
import android.widget.AdapterView.OnItemSelectedListener;
import android.widget.ArrayAdapter;
import android.widget.EditText;
import android.widget.Spinner;
import android.widget.TextView;
import android.widget.Toast;

import com.yoctopuce.YoctoAPI.YAPI;
import com.yoctopuce.YoctoAPI.YAPI_Exception;
import com.yoctopuce.YoctoAPI.YModule;

public class SaveSettings extends Activity implements OnItemSelectedListener
{

    private ArrayAdapter<String> aa;
    private YModule module = null;

    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.savesettings);
        Spinner my_spin = (Spinner) findViewById(R.id.spinner1);
        my_spin.setOnItemSelectedListener(this);
        aa = new ArrayAdapter<String>(this, android.R.layout.simple_spinner_item);
        aa.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
        my_spin.setAdapter(aa);
    }

    @Override
    protected void onStart()
    {
        super.onStart();

        try {
            aa.clear();
            YAPI.EnableUSBHost(this);
            YAPI.RegisterHub("usb");
            YModule r = YModule.FirstModule();
            while (r != null) {
                String hwid = r.get_hardwareId();
                aa.add(hwid);
                r = r.nextModule();
            }
        } catch (YAPI_Exception e) {
            e.printStackTrace();
        }
        // refresh Spinner with detected relay
        aa.notifyDataSetChanged();
    }

    @Override
    protected void onStop()
    {
        super.onStop();
        YAPI.FreeAPI();
    }

    private void DisplayModuleInfo()
    {
        TextView field;
        if (module == null)
            return;
        try {
            YAPI.UpdateDeviceList();// fixme
            field = (TextView) findViewById(R.id.logicalnamefield);
            field.setText(module.getLogicalName());
        } catch (YAPI_Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onItemSelected(AdapterView<?> parent, View view, int pos, long id)
    {
        String hwid = parent.getItemAtPosition(pos).toString();
        module = YModule.FindModule(hwid);
        DisplayModuleInfo();
    }

    @Override
    public void onNothingSelected(AdapterView<?> arg0)
    {
    }

    public void saveName(View view)
    {
        if (module == null)
            return;

        EditText edit = (EditText) findViewById(R.id.newname);
        String newname = edit.getText().toString();
        try {
            if (!YAPI.CheckLogicalName(newname)) {
                Toast.makeText(getApplicationContext(), "Invalid name (" + newname + ")", Toast.LENGTH_LONG).show();
                return;
            }
            module.set_logicalName(newname);
            module.saveToFlash(); // do not forget this
            edit.setText("");
        } catch (YAPI_Exception ex) {
            ex.printStackTrace();
        }
        DisplayModuleInfo();
    }

}
 

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction YModule.saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction YModule.yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la mehode nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un null. Ci-dessous un petit exemple listant les module connectés

package com.yoctopuce.doc_examples;

import android.app.Activity;
import android.os.Bundle;
import android.util.TypedValue;
import android.view.View;
import android.widget.LinearLayout;
import android.widget.TextView;

import com.yoctopuce.YoctoAPI.YAPI;
import com.yoctopuce.YoctoAPI.YAPI_Exception;
import com.yoctopuce.YoctoAPI.YModule;

public class Inventory extends Activity
{

    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.inventory);
    }

    public void refreshInventory(View view)
    {
        LinearLayout layout = (LinearLayout) findViewById(R.id.inventoryList);
        layout.removeAllViews();

        try {
            YAPI.UpdateDeviceList();
            YModule module = YModule.FirstModule();
            while (module != null) {
                String line = module.get_serialNumber() + " (" + module.get_productName() + ")";
                TextView tx = new TextView(this);
                tx.setText(line);
                tx.setTextSize(TypedValue.COMPLEX_UNIT_SP, 20);
                layout.addView(tx);
                module = module.nextModule();
            }
        } catch (YAPI_Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    protected void onStart()
    {
        super.onStart();
        try {
            YAPI.EnableUSBHost(this);
            YAPI.RegisterHub("usb");
        } catch (YAPI_Exception e) {
            e.printStackTrace();
        }
        refreshInventory(null);
    }

    @Override
    protected void onStop()
    {
        super.onStop();
        YAPI.FreeAPI();
    }

}
 

12.7. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme.

Dans l'API java pour Android, le traitement d'erreur est implémenté au moyen d'exceptions. Vous devrez donc intercepter et traiter correctement ces exceptions si vous souhaitez avoir un projet fiable qui ne crashera pas des que vous débrancherez un module.

13. Utilisation du Yocto-MaxiKnob en TypeScript

TypeScript est une version améliorée du langage de programmation JavaScript. Il s'agit d'un sur-ensemble syntaxique avec typage fort, permettant d'améliorer la fiabilité du code, mais qui est transcompilé en JavaScript avant l'exécution, pour être ensuite interprêté par n'importe quel navigateur Web ou par Node.js.

Cette librairie de programmation Yoctopuce permet donc de coder des applications JavaScript tout en bénéficiant d'un typage fort. Comme notre librairie EcmaScript, elle utilise les fonctionnalités asynchrones introduites dans la version ECMAScript 2017 et qui sont maintenant disponibles nativement dans tous les environnements JavaScript modernes. Néanmoins, à ce jour, le code TypeScript n'est pas utilisable directement dans un navigateur Web ou Node.js, donc il est nécessaire de le compiler en JavaScript avant l'exécution.

La librairie peut travailler aussi bien dans un navigateur internet que dans un environnement Node.js. Pour satisfaire aux exigences de résolution statique des dépendances, et pour éviter les ambiguïtés qui surgiraient lors de l'utilisation d'environnements hybrides tels qu'Electron, la sélection de l'environnement doit être faite explicitement à l'import de la librairie, en important dans le projet soit yocto_api_nodejs.js, soit yocto_api_html.js.

La librairie peut être intégrée à vos projets de plusieurs manières, selon ce qui convient le mieux à votre projet:

13.1. Utiliser la librairie Yoctopuce pour TypeScript

1. Commencez par installer TypeScript sur votre machine si cela n'est pas déjà fait. Pour cela:

2. Connectez-vous ensuite sur le site Web de Yoctopuce et téléchargez les éléments suivants:

3. Décompressez les fichiers de la librairie dans un répertoire de votre choix, et ouvrez une fenêtre de commande dans le répertoire où vous l'avez installée. Lancez la commande suivante pour installer les quelques dépendances qui sont nécessaires au lancement des exemples:


npm install

Une fois cette commande terminée sans erreur, vous êtes prêt pour l'exploration des exemples. Ceux-ci sont fournis dans deux exemples différents, selon l'environnement d'exécution choisi: example_html pour l'exécution de la librairie Yoctopuce dans un navigateur Web, ou example_nodejs si vous provoyez d'utiliser la librairie dans un environnement Node.js.

La manière de lancer les exemples dépend de l'environnement choisi. Vous trouverez les instructions détaillées un peu plus loin.

13.2. Petit rappel sur les fonctions asynchrones en JavaScript

JavaScript a été conçu pour éviter toute situation de concurrence durant l'exécution. Il n'y a jamais qu'un seul thread en JavaScript. Pour gérer les attentes dans les entrées/sorties, JavaScript utilise les opérations asynchrones: lorsqu'une fonction potentiellement bloquante doit être appelée, l'opération est déclenchée mais le flot d'exécution est immédiatement suspendu. Le moteur JavaScript est alors libre pour exécuter d'autres tâches, comme la gestion de l'interface utilisateur par exemple. Lorsque l'opération bloquante se termine finalement, le système relance le code en appelant une fonction de callback, en passant en paramètre le résultat de l'opération, pour permettre de continuer la tâche originale.

L'utilisation d'opérations asynchrones avec des fonctions de callback a la fâcheuse tendance de rentre le code illisible puisqu'elle découpe systématiquement le flot du code en petites fonctions de callback déconnectées les unes des autres. Heureusement, le standard ECMAScript 2015 a apporté les objets Promise et la syntaxe async / await pour la gestion des appels asynchrones:

En clair, async et await permettent d'écrire du code TypeScript avec tous les avantages des entrées/sorties asynchrones, mais sans interrompre le flot d'écriture du code. Cela revient quasiment à une exécution multi-tâche, mais en garantissant que le passage de contrôle d'une tâche à l'autre ne se produira que là où le mot-clé await apparaît.

Cette librairie TypeScript utilise donc les objets Promise et des méthodes async, pour vous permettre d'utiliser la notation await si pratique. Et pour ne pas devoir vous poser la question pour chaque méthode de savoir si elle est asynchrone ou pas, la convention est la suivante: en principe toutes les méthodes publiques de la librairie TypeScript sont async, c'est-à-dire qu'elles retournent un objet Promise, sauf:

Dans la plupart des cas, le typage fort de TypeScript sera là pour vous rappeler d'utiliser await lors de l'appel d'une méthode asynchrone.

13.3. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code TypeScript qui utilise la fonction AnButton.


// En Node.js, on référence la librairie via son package NPM
// En HTML, on utiliserait plutôt un path relatif (selon l'environnement)
import { YAPI, YErrorMsg, YModule } from 'yoctolib-cjs/yocto_api_nodejs.js';
import { YAnButton } from 'yoctolib-cjs/yocto_anbutton.js';

[...]
// On active l'accès aux modules locaux à travers le VirtualHub
await YAPI.RegisterHub('127.0.0.1');
[...]

// On récupère l'objet permettant d'intéragir avec le module
let anbutton: YAnButton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1");

// Pour gérer le hot-plug, on vérifie que le module est là
if(await anbutton.isOnline())
{
    // Utiliser anbutton.get_calibratedValue()
    [...]
}

Voyons maintenant en détail ce que font ces quelques lignes.

Import de yocto_api et yocto_anbutton

Ces deux imports permettent d'avoir accès aux fonctions permettant de gérer les modules Yoctopuce. yocto_api doit toujours être inclus, et yocto_anbutton est nécessaire pour gérer les modules contenant une entrée analogique, comme le Yocto-MaxiKnob. D'autres classes peuvent être utiles dans d'autres cas, comme YModule qui vous permet de faire une énumération de n'importe quel type de module Yoctopuce.

Pour que yocto_api soit correctement lié aux librairies réseau à utiliser pour établir la connexion (soit celles de Node.js, soit celles du navigateur dans le cas d'une application HTML), il faut que vous référenciez au moins une fois dans votre projet soit la variante yocto_api_nodejs.js, soit yocto_api_html.js.

Notez que cet exemple importe la librairie au format CommonJS, le plus utilisé avec Node.JS à ce jour, mais si votre projet est construit pour utiliser les modules natifs EcmaScript, il suffit de remplace dans l'import le préfix yoctolib-cjs par yoctolib-esm.

YAPI.RegisterHub

La méthode RegisterHub permet d'indiquer sur quelle machine se trouvent les modules Yoctopuce, ou plus exactement la machine sur laquelle tourne le programme VirtualHub. Dans notre cas l'adresse 127.0.0.1:4444 indique la machine locale, en utilisant le port 4444 (le port standard utilisé par Yoctopuce). Vous pouvez parfaitement changer cette adresse, et mettre l'adresse d'une autre machine sur laquelle tournerait un autre VirtualHub, ou d'un YoctoHub. Si l'hôte n'est pas joignable, la fonction déclanche une exception.

Comme expliqué précédemment, il n'est pas possible d'utiliser directement RegisterHub("usb") en TypeScript, car la machine virtuelle JavaScript n'a pas accès directement aux périphériques USB. Elle doit nécessairement passer par le programme VirtualHub via une connection par l'adresse 127.0.0.1.

YAnButton.FindAnButton

La méthode FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1")
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.MaFonction")
anbutton = YAnButton.FindAnButton("MonModule.anButton1")
anbutton = YAnButton.FindAnButton("MonModule.MaFonction")
anbutton = YAnButton.FindAnButton("MaFonction")

YAnButton.FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YQuadratureDecoder.FindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YBuzzer.FindBuzzer ou YBuzzer.FirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YColorLedCluster.FindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple concret, en Node.js

Ouvrez une fenêtre de commande (un terminal, un shell...) et allez dans le répertoire example_nodejs/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce pour TypeScript. Vous y trouverez un fichier nommé demo.ts avec le code d'exemple ci-dessous, qui reprend les fonctions expliquées précédemment, mais cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

Si le Yocto-MaxiKnob n'est pas branché sur la machine où fonctionne le navigateur internet, remplacez dans l'exemple l'adresse 127.0.0.1 par l'adresse IP de la machine où est branché le Yocto-MaxiKnob et où vous avez lancé le VirtualHub.

import { YAPI, YErrorMsg, YModule } from 'yoctolib-cjs/yocto_api_nodejs.js';
import { YBuzzer } from "yoctolib-cjs/yocto_buzzer.js"
import { YColorLedCluster } from "yoctolib-cjs/yocto_colorledcluster.js"
import { YAnButton } from "yoctolib-cjs/yocto_anbutton.js"
import { YQuadratureDecoder } from "yoctolib-cjs/yocto_quadraturedecoder.js"

var lastPos: number = 0;
var buz: YBuzzer;
var leds: YColorLedCluster;
var button: YAnButton;
var qd: YQuadratureDecoder;

async function startDemo(): Promise<void>
{
    await YAPI.LogUnhandledPromiseRejections();

    // Setup the API to use the VirtualHub on local machine
    let errmsg: YErrorMsg = new YErrorMsg();
    if(await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        console.log('Cannot contact VirtualHub on 127.0.0.1: '+errmsg.msg);
        return;
    }

    // Select specified device, or use first available one
    let serial: string = process.argv[process.argv.length-1];
    if(serial[8] != '-') {
        // by default use any connected module suitable for the demo
        let buzzer = YBuzzer.FirstBuzzer();
        if(buzzer) {
            let module = await buzzer.module();
            serial = await module.get_serialNumber();
        } else {
            console.log('No matching sensor connected, check cable !');
            return;
        }
    }
    console.log('Using device '+serial);
    buz = YBuzzer.FindBuzzer(serial + ".buzzer");
    leds = YColorLedCluster.FindColorLedCluster(serial + ".colorLedCluster");
    button = YAnButton.FindAnButton(serial + ".anButton1");
    qd = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1");
    lastPos = await qd.get_currentValue() >> 0;
    await buz.set_volume(75);
    if  (!await button.isOnline() || !await qd.isOnline()) {
        console.log("Make sure the Yocto-MaxiKnob is configured with at least on AnButton and  one QuadratureDecoder");
        return;
    }
    console.log("press button #1 or turn encoder #1 or hit Ctrl-C");

    refresh();
}

function notefreq(note: number)
{
    return 220.0 * Math.exp(note * Math.log(2) / 12);
}

async function refresh(): Promise<void>
{
    if (await button.get_isPressed() == YAnButton.ISPRESSED_TRUE) {
        lastPos = 0;
        await qd.set_currentValue(0);
        await buz.playNotes("'E32 C8");
        await leds.set_rgbColor(0, 1, 0x000000);
    } else {
        let p: number = await qd.get_currentValue() >> 0;
        if (lastPos != p) {
            lastPos = p;
            await buz.pulse(notefreq(p), 100);
            await leds.set_hslColor(0, 1, 0x00FF7f | (p % 255) << 16);
        }
    }
    setTimeout(refresh, 10);
}

startDemo();
 

Comme décrit au début de ce chapitre, vous devez avoir installé le complateur TypeScript sur votre machine pour essayer ces exemples, et installé les dépendances de la librairie TypeScript. Si vous l'avez fait, vous pouvez maintenant taper la commande suivantes dans le répertoire de l'exemple lui-même, pour finaliser la résolution de ses dépendances:


npm install
Vous êtes maintenant prêt pour lancer le code d'exemple dans Node.js. La manière la plus simple de le faire est d'utiliser la commande suivante, en remplaçant les [...] par les arguments que vous voulez passer au programme:

npm run demo [...]

Cette commande, définie dans le fichier package.json, a pour effet de compiler le code source TypeScript à l'aide de la simple commande tsc, puis de lancer le code compilé dans Node.js.

La compilation utilise les paramètres spécifiés dans le fichier tsconfig.json, et produit

Notez que le fichier package.json de nos exemples référence directement la version locale de la librairie par un path relatif, pour éviter de dupliquer la librairie dans chaque exemple. Bien sur, pour votre application de production, vous pourrez utiliser le package directement depuis le repository npm en l'ajoutant à votre projet à l'aide de la commande:


npm install yoctolib-cjs

Le même exemple, mais dans un navigateur

Si vous voulez voir comment utiliser la librairie dans un navigateur plutôt que dans Node.js, changez de répertoire et allez dans example_html/Doc-GettingStarted-Yocto-MaxiKnob. Vous y trouverez un fichier html app.html, et un fichier TypeScript app.ts similaire au code ci-dessus, mais avec quelques variantes pour permettre une interaction à travers la page HTML plutôt que sur la console JavaScript.

Aucune installation n'est nécessaire pout utiliser cet exemple HTML, puisqu'il référence la librairie TypeScript via un chemin relatif. Par contre, pour que le navigateur puisse exécuter le code, il faut que la page HTML soit publié par un serveur Web. Nous fournissons un petit serveur de test pour cet usage, que vous pouvez lancer avec la commande:


npm run app-server

Cette commande va compiler le code d'exemple TypeScript, le mettre à disposition via un serveur HTTP sur le port 3000 et ouvrir un navigateur sur cet exemple. Si vous modifiez le code d'exemple, il sera automatiquement recompilé et il vous suffira de recharger la page sur le navigateur pour retester.

Comme pour l'exemple Node.js, la compilation produit un fichier .js.map qui permet de debugger dans le navigateur directement sur le fichier source TypeScript. Notez qu'au moment où cette documentation est rédigée, le debug en format source dans le navigateur fonctionne pour les browsers basés sur Chromium, mais pas encore dans Firefox.

13.4. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

import { YAPI, YErrorMsg, YModule } from 'yoctolib-cjs/yocto_api_nodejs.js';

async function startDemo(args: string[]): Promise<void>
{
    await YAPI.LogUnhandledPromiseRejections();

    // Setup the API to use the VirtualHub on local machine
    let errmsg: YErrorMsg = new YErrorMsg();
    if (await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        console.log('Cannot contact VirtualHub on 127.0.0.1: '+errmsg.msg);
        return;
    }

    // Select the device to use
    let module: YModule = YModule.FindModule(args[0]);
    if(await module.isOnline()) {
        if(args.length > 1) {
            if(args[1] == 'ON') {
                await module.set_beacon(YModule.BEACON_ON);
            } else {
                await module.set_beacon(YModule.BEACON_OFF);
            }
        }
        console.log('serial:       '+await module.get_serialNumber());
        console.log('logical name: '+await module.get_logicalName());
        console.log('luminosity:   '+await module.get_luminosity()+'%');
        console.log('beacon:       '+
            (await module.get_beacon() == YModule.BEACON_ON ? 'ON' : 'OFF'));
        console.log('upTime:       '+
            ((await module.get_upTime()/1000)>>0) +' sec');
        console.log('USB current:  '+await module.get_usbCurrent()+' mA');
        console.log('logs:');
        console.log(await module.get_lastLogs());
    } else {
        console.log("Module not connected (check identification and USB cable)\n");
    }
    await YAPI.FreeAPI();
}

if(process.argv.length < 3) {
    console.log("usage: npm run demo <serial or logicalname> [ ON | OFF ]");
} else {
    startDemo(process.argv.slice(2));
}
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode set_xxx() Pour plus de détails concernant ces méthodes utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la méthode set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

import { YAPI, YErrorMsg, YModule } from 'yoctolib-cjs/yocto_api_nodejs.js';

async function startDemo(args: string[]): Promise<void>
{
    await YAPI.LogUnhandledPromiseRejections();

    // Setup the API to use the VirtualHub on local machine
    let errmsg: YErrorMsg = new YErrorMsg();
    if (await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        console.log('Cannot contact VirtualHub on 127.0.0.1: '+errmsg.msg);
        return;
    }

    // Select the device to use
    let module: YModule = YModule.FindModule(args[0]);
    if(await module.isOnline()) {
        if(args.length > 1) {
            let newname: string = args[1];
            if (!await YAPI.CheckLogicalName(newname)) {
                console.log("Invalid name (" + newname + ")");
                process.exit(1);
            }
            await module.set_logicalName(newname);
            await module.saveToFlash();
        }
        console.log('Current name: '+await module.get_logicalName());
    } else {
        console.log("Module not connected (check identification and USB cable)\n");
    }
    await YAPI.FreeAPI();
}

if(process.argv.length < 3) {
    console.log("usage: npm run demo <serial> [newLogicalName]");
} else {
    startDemo(process.argv.slice(2));
}
 

Attention, le nombre de cycle d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit de que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employé par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la méthode saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette méthode depuis l'intérieur d'une boucle.

Énumération des modules

Obtenir la liste des modules connectés se fait à l'aide de la méthode YModule.FirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la méthode nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un null. Ci-dessous un petit exemple listant les module connectés

import { YAPI, YErrorMsg, YModule } from 'yoctolib-cjs/yocto_api_nodejs.js';

async function startDemo(): Promise<void>
{
    await YAPI.LogUnhandledPromiseRejections();

    // Setup the API to use the VirtualHub on local machine
    let errmsg = new YErrorMsg();
    if (await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        console.log('Cannot contact VirtualHub on 127.0.0.1');
        return;
    }
    refresh();
}

async function refresh(): Promise<void>
{
    try {
        let errmsg: YErrorMsg = new YErrorMsg();
        await YAPI.UpdateDeviceList(errmsg);

        let module = YModule.FirstModule();
        while(module) {
            let line: string = await module.get_serialNumber();
            line += '(' + (await module.get_productName()) + ')';
            console.log(line);
            module = module.nextModule();
        }
        setTimeout(refresh, 500);
    } catch(e) {
        console.log(e);
    }
}

startDemo();
 

13.5. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

14. Utilisation du Yocto-MaxiKnob en JavaScript / EcmaScript

EcmaScript est le nom officiel de la version standardisée du langage de programmation communément appelé JavaScript. Cette librairie de programmation Yoctopuce utilise les nouvelles fonctionnalités introduites dans la version EcmaScript 2017. La librairie porte ainsi le nom Librairie pour JavaScript / EcmaScript 2017, afin de la différentier de la précédente Librairie pour JavaScript qu'elle remplace.

Cette librairie permet d'accéder aux modules Yoctopuce depuis tous les environnements JavaScript modernes. Elle fonctionne aussi bien depuis un navigateur internet que dans un environnement Node.js. La librairie détecte automatiquement à l'initialisation si le contexte d'utilisation est un browser ou une machine virtuelle Node.js, et utilise les librairies systèmes les plus appropriées en conséquence.

Les communications asynchrones avec les modules sont gérées dans toute la librairie à l'aide d'objets Promise, en utilisant la nouvelle syntaxe EcmaScript 2017 async / await non bloquante pour la gestion des entrées/sorties asynchrones (voir ci-dessous). Cette syntaxe est désormais disponible sans autres dans la plupart des moteurs JavaScript: il n'est plus nécessaire de transpiler le code avec Babel ou jspm. Voici la version minimum requise de vos moteurs JavaScript préférés, tous disponibles au téléchargement:

Si vous avez besoin de la compatibilité avec des anciennes versions, vous pouvez toujours utiliser Babel pour transpiler votre code et la libriairie vers un standard antérieur de JavaScript, comme décrit un peu plus bas.

Nous ne recommendons plus l'utilisation de jspm dès lors que async / await sont standardisés.

14.1. Fonctions bloquantes et fonctions asynchrones en JavaScript

JavaScript a été conçu pour éviter toute situation de concurrence durant l'exécution. Il n'y a jamais qu'un seul thread en JavaScript. Cela signifie que si un programme effectue une attente active durant une communication réseau, par exemple pour lire un capteur, le programme entier se trouve bloqué. Dans un navigateur, cela peut se traduire par un blocage complet de l'interface utilisateur. C'est pourquoi l'utilisation de fonctions d'entrée/sortie bloquantes en JavaScript est sévèrement découragée de nos jours, et les API bloquantes se font toutes déclarer deprecated.

Plutôt que d'utiliser des threads parallèles, JavaScript utilise les opérations asynchrones pour gérer les attentes dans les entrées/sorties: lorsqu'une fonction potentiellement bloquante doit être appelée, l'opération est uniquement déclenchée mais le flot d'exécution est immédiatement terminé. La moteur JavaScript est alors libre pour exécuter d'autres tâches, comme la gestion de l'interface utilisateur par exemple. Lorsque l'opération bloquante se termine finalement, le système relance le code en appelant une fonction de callback, en passant en paramètre le résultat de l'opération, pour permettre de continuer la tâche originale.

Lorsqu'on les utilises avec des simples fonctions de callback, comme c'est fait quasi systématiquement dans les librairies Node.js, les opérations asynchrones ont la fâcheuse tendance de rentre le code illisible puisqu'elles découpent systématiquement le flot du code en petites fonctions de callback déconnectées les unes des autres. Heureusement, de nouvelles idées sont apparues récemment pour améliorer la situation. En particulier, l'utilisation d'objets Promise pour travailler avec les opérations asynchrones aide beaucoup. N'importe quelle fonction qui effectue une opération potentiellement longue peut retourner une promesse de se terminer, et cet objet Promise peut être utilisé par l'appelant pour chaîner d'autres opérations en un flot d'exécution. La classe Promise fait partie du standard EcmaScript 2015.

Les objets Promise sont utiles, mais ce qui les rend vraiment pratique est la nouvelle syntaxe async / await pour la gestion des appels asynchrones:

En clair, async et await permettent d'écrire du code EcmaScript avec tous les avantages des entrées/sorties asynchrones, mais sans interrompre le flot d'écriture du code. Cela revient quasiment à une exécution multi-tâche, mais en garantissant que le passage de contrôle d'une tâche à l'autre ne se produira que là où le mot-clé await apparaît.

Nous avons donc décidé d'écrire cette nouvelle librairie EcmaScript en utilisant les objets Promise et des fonctions async, pour vous permettre d'utiliser la notation await si pratique. Et pour ne pas devoir vous poser la question pour chaque méthode de savoir si elle est asynchrone ou pas, la convention est la suivante: toutes les méthodes publiques de la librairie EcmaScript sont async, c'est-à-dire qu'elles retournent un objet Promise, sauf:

14.2. Utiliser la librairie Yoctopuce pour JavaScript / EcmaScript 2017

JavaScript fait partie de ces langages qui ne vous permettront pas d'accéder directement aux couches matérielles de votre ordinateur. C'est pourquoi si vous désirez travailler avec des modules USB branchés par USB, vous devrez faire tourner la passerelle de Yoctopuce appelée VirtualHub sur la machine à laquelle sont branchés les modules.

Connectez vous sur le site de Yoctopuce et téléchargez les éléments suivants:

Décompressez les fichiers de la librairie dans un répertoire de votre choix, branchez vos modules et lancez le programme VirtualHub. Vous n'avez pas besoin d'installer de driver.

Utiliser la librairie Yoctopuce officielle pour node.js

Commencez par installer sur votre machine de développement la version actuelle de Node.js (7.6 ou plus récente), C'est très simple. Vous pouvez l'obtenir sur le site officiel: http://nodejs.org. Assurez vous de l'installer entièrement, y compris npm, et de l'ajouter à votre system path.

Vous pouvez ensuite prendre l'exemple de votre choix dans le répertoire example_nodejs (par exemple example_nodejs/Doc-Inventory). Allez dans ce répertoire. Vous y trouverez un fichier décrivant l'application (package.json) et le code source de l'application (demo.js). Pour charger automatiquement et configurer les librairies nécessaires à l'exemple, tapez simplement:


npm install

Une fois que c'est fait, vous pouvez directement lancer le code de l'application:


node demo.js

Utiliser une copie locale de la librairie Yoctopuce avec node.js

Si pour une raison ou une autre vous devez faire des modifications au code de la librairie, vous pouvez facilement configurer votre projet pour utiliser le code source de la librairie qui se trouve dans le répertoire lib/ plutôt que le package npm officiel. Pour cela, lancez simplement la commande suivante dans le répertoire de votre projet:


npm link ../../lib

Utiliser la librairie Yoctopuce dans un navigateur (HTML)

Pour les exemples HTML, c'est encore plus simple: il n'y a rien à installer. Chaque exemple est un simple fichier HTML que vous pouvez ouvrir directement avec un navigateur pour l'essayer. L'inclusion de la librairie Yoctopuce ne demande rien de plus qu'un simple tag HTML <script>.

Utiliser la librairie Yoctopuce avec des anciennes version de JavaScript

Si vous avez besoin d'utiliser cette librairie avec des moteurs JavaScript plus anciens, vous pouvez utiliser Babel40 pour transpiler votre code et la librairie dans une version antérieure du langage. Pour installer Babel avec les réglages usuels, tapez:


npm instal -g babel-cli
npm instal babel-preset-env

Normalement vous demanderez à Babel de poser les fichiers transpilés dans un autre répertoire, nommé comopat par exemple. Pour ce faire, utilisez par exemple les commandes suivantes:


babel --presets env demo.js --out-dir compat/
babel --presets env ../../lib --out-dir compat/

Bien que ces outils de transpilation soient basés sur node.js, ils fonctionnent en réalité pour traduire n'importe quel type de fichier JavaScript, y compris du code destiné à fonctionner dans un navigateur. La seule chose qui ne peut pas être faite aussi facilement est la transpilation de sciptes codés en dure à l'intérieur même d'une page HTML. Il vous faudra donc sortir ce code dans un fichier .js externe si il utiliser la syntaxe EcmaScript 2017, afin de le transpiler séparément avec Babel.

Babel dipose de nombreuses fonctionnalités intéressantes, comme un mode de surveillance qui traduite automatiquement au vol vos fichiers dès qu'il détecte qu'un fichier source a changé. Consultez les détails dans la documentation de Babel.

Compatibilité avec l'ancienne librairie JavaScript

Cette nouvelle librairie n'est pas compatible avec l'ancienne librairie JavaScript, car il n'existe pas de possibilité d'implémenter l'ancienne API bloquante sur la base d'une API asynchrone. Toutefois, les noms des méthodes sont les mêmes, et l'ancien code source synchrone peut facilement être rendu asynchrone simplement en ajoutant le mot-clé await devant les appels de méthode. Remplacez par exemple:


beaconState = module.get_beacon();

par


beaconState = await module.get_beacon();

Mis à part quelques exceptions, la plupart des méthodes redondantes XXX_async ont été supprimées, car elles auraient introduit de la confusion sur la manière correcte de gérer les appels asynchrones. Si toutefois vous avez besoin d'appeler un callback explicitement, il est très facile de faire appeler une fonction de callback à la résolution d'une méthode async, en utilisant l'objet Promise retourné. Par exemple, vous pouvez réécrire:


module.get_beacon_async(callback, myContext);

par


module.get_beacon().then(function(res) { callback(myContext, module, res); });

Si vous portez une application vers la nouvelle librairie, vous pourriez être amené à désirer des méthodes synchrones similaires à l'ancienne librairie (sans objet Promise), quitte à ce qu'elles retournent la dernière valeur reçue du capteur telle que stockée en cache, puisqu'il n'est pas possible de faire des communications bloquantes. Pour cela, la nouvelle librairie introduit un nouveau type de classes appelés proxys synchrones. Un proxy synchrone est un objet qui reflète la dernière value connue d'un objet d'interface, mais peut être accédé à l'aide de fonctions synchrones habituelles. Par exemple, plutôt que d'utiliser:


async function logInfo(module)
{
    console.log('Name: '+await module.get_logicalName());
    console.log('Beacon: '+await module.get_beacon());
}

...
logInfo(myModule);
...

on peut utiliser:


function logInfoProxy(moduleSyncProxy)
{
    console.log('Name: '+moduleProxy.get_logicalName());
    console.log('Beacon: '+moduleProxy.get_beacon());
}

logInfoSync(await myModule.get_syncProxy());

Ce dernier appel asynchrone peut aussi être formulé comme:


myModule.get_syncProxy().then(logInfoProxy);

14.3. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code JavaScript qui utilise la fonction AnButton.


// En Node.js, on utilise la fonction require()
// En HTML, on utiliserait &lt;script src="..."&gt;
require('yoctolib-es2017/yocto_api.js');
require('yoctolib-es2017/yocto_anbutton.js');

[...]
// On active l'accès aux modules locaux à travers le VirtualHub
await YAPI.RegisterHub('127.0.0.1');
[...]

// On récupère l'objet permettant d'intéragir avec le module
let anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1");

// Pour gérer le hot-plug, on vérifie que le module est là
if(await anbutton.isOnline())
{
    // Utiliser anbutton.get_calibratedValue()
    [...]
}

Voyons maintenant en détail ce que font ces quelques lignes.

Require de yocto_api et yocto_anbutton

Ces deux imports permettent d'avoir accès aux fonctions permettant de gérer les modules Yoctopuce. yocto_api doit toujours être inclus, yocto_anbutton est nécessaire pour gérer les modules contenant une entrée analogique, comme le Yocto-MaxiKnob. D'autres classes peuvent être utiles dans d'autres cas, comme YModule qui vous permet de faire une énumération de n'importe quel type de module Yoctopuce.

YAPI.RegisterHub

La méthode RegisterHub permet d'indiquer sur quelle machine se trouvent les modules Yoctopuce, ou plus exactement la machine sur laquelle tourne le programme VirtualHub. Dans notre cas l'adresse 127.0.0.1:4444 indique la machine locale, en utilisant le port 4444 (le port standard utilisé par Yoctopuce). Vous pouvez parfaitement changer cette adresse, et mettre l'adresse d'une autre machine sur laquelle tournerait un autre VirtualHub, ou d'un YoctoHub. Si l'hôte n'est pas joignable, la fonction déclanche une exception.

YAnButton.FindAnButton

La méthode FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1")
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.MaFonction")
anbutton = YAnButton.FindAnButton("MonModule.anButton1")
anbutton = YAnButton.FindAnButton("MonModule.MaFonction")
anbutton = YAnButton.FindAnButton("MaFonction")

YAnButton.FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YQuadratureDecoder.FindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YBuzzer.FindBuzzer ou YBuzzer.FirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YColorLedCluster.FindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple concret, en Node.js

Ouvrez une fenêtre de commande (un terminal, un shell...) et allez dans le répertoire example_nodejs/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce pour JavaScript / EcmaScript 2017. Vous y trouverez un fichier nommé demo.js avec le code d'exemple ci-dessous, qui reprend les fonctions expliquées précédemment, mais cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

Si le Yocto-MaxiKnob n'est pas branché sur la machine où fonctionne le navigateur internet, remplacez dans l'exemple l'adresse 127.0.0.1 par l'adresse IP de la machine où est branché le Yocto-MaxiKnob et où vous avez lancé le VirtualHub.


"use strict";

require('yoctolib-es2017/yocto_api.js');
require('yoctolib-es2017/yocto_anbutton.js');
require('yoctolib-es2017/yocto_buzzer.js');
require('yoctolib-es2017/yocto_colorledcluster.js');
require('yoctolib-es2017/yocto_quadraturedecoder.js');

let buz, leds, button, qd, lastPos;

function notefreq( note)
{
    return 220.0 * Math.exp(note * Math.log(2) / 12);
}

async function startDemo()
{
    await YAPI.LogUnhandledPromiseRejections();
    await YAPI.DisableExceptions();

    // Setup the API to use the VirtualHub on local machine
    let errmsg = new YErrorMsg();
    if(await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        console.log('Cannot contact VirtualHub on 127.0.0.1: '+errmsg.msg);
        return;
    }

    // Select specified device, or use first available one
    let serial = process.argv[process.argv.length-1];
    if(serial[8] != '-') {
        // by default use any connected module suitable for the demo
        let buzzer = YBuzzer.FirstBuzzer();
        if(buzzer) {
            let module = await buzzer.module();
            serial = await module.get_serialNumber();
        } else {
            console.log('No matching sensor connected, check cable !');
            return;
        }
    }
    console.log('Using device '+serial);
    buz = YBuzzer.FindBuzzer(serial + ".buzzer");
    leds = YColorLedCluster.FindColorLedCluster(serial + ".colorLedCluster");
    button = YAnButton.FindAnButton(serial + ".anButton1");
    qd = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1");
    lastPos = parseInt(await  qd.get_currentValue());
    await buz.set_volume(75);
    if  (!await button.isOnline() || !await qd.isOnline()) {
        console.log("Make sure the Yocto-MaxiKnob is configured with at least on AnButton and  one QuadratureDecoder");
        return;
    }
    console.log("press button #1 or turn encoder #1 or hit Ctrl-C");

    refresh();
}

async function refresh()
{
    if (await buz.isOnline()) {
        if (await buz.isOnline()) {
            if (await button.get_isPressed() == YAnButton.ISPRESSED_TRUE) {
                lastPos = 0;
                await qd.set_currentValue(0);
                await buz.playNotes("'E32 C8");
                await leds.set_rgbColor(0, 1, 0x000000);
            } else {
                let p = parseInt(await  qd.get_currentValue());
                if (lastPos != p)
                {
                    lastPos = p;
                    await buz.pulse(notefreq(p), 100);
                    await leds.set_hslColor(0, 1, 0x00FF7f | (p & 0xff ) << 16);
                }
            }
        }
    } else {
        console.log('Module not connected');
    }
    setTimeout(refresh, 10);
}

startDemo();
 

Comme décrit au début de ce chapitre, vous devez avoir installé Node.js v7.6 ou suivant pour essayer ces exemples. Si vous l'avez fait, vous pouvez maintenant taper les deux commandes suivantes pour télécharger automatiquement les librairies dont cet exemple dépend:


npm install
Une fois terminé, vous pouvez lancer votre code d'exemple dans Node.js avec la commande suivante, en remplaçant les [...] par les arguments que vous voulez passer au programme:

node demo.js [...]

Le même exemple, mais dans un navigateur

Si vous voulez voir comment utiliser la librairie dans un navigateur plutôt que dans Node.js, changez de répertoire et allez dans example_html/Doc-GettingStarted-Yocto-MaxiKnob. Vous y trouverez un fichier html, avec une section JavaScript similaire au code précédent, mais avec quelques variantes pour permettre une interaction à travers la page HTML plutôt que sur la console JavaScript

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Hello World</title>
  <script src="../../lib/yocto_api.js"></script>
  <script src="../../lib/yocto_buzzer.js"></script>
  <script src="../../lib/yocto_colorledcluster.js"></script>
  <script src="../../lib/yocto_anbutton.js"></script>
  <script src="../../lib/yocto_quadraturedecoder.js"></script>
 
  <script>
    var first_run = true;
    var lastPos = 0;
    async function startDemo()
    {
      await YAPI.LogUnhandledPromiseRejections();
      await YAPI.DisableExceptions();

      // Setup the API to use the VirtualHub on local machine
      let errmsg = new YErrorMsg();
      if(await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        alert('Cannot contact VirtualHub on 127.0.0.1: '+errmsg.msg);
        return;
      }
      refresh();
    }

    function notefreq( note)
    {
      return 220.0 * Math.exp(note * Math.log(2) / 12);
    }

    async function refresh()
    {
      let serial = document.getElementById('serial').value;
      if(serial == '') {
        let buzzer = YBuzzer.FirstBuzzer();
        if(buzzer) {
          let module = await buzzer.module();
          serial = await module.get_serialNumber();
        }
      }
      let buz    = YBuzzer.FindBuzzer(serial + ".buzzer");
      let leds   = YColorLedCluster.FindColorLedCluster(serial + ".colorLedCluster");
      let button = YAnButton.FindAnButton(serial + ".anButton1");
      let qd     = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1");

          if (!await button.isOnline() || !await qd.isOnline()) {
            document.write("Make sure the Yocto-MaxiKnob is configured with at least on AnButton and  one QuadratureDecoder");
            return;
      }
      if (first_run) {
        lastPos = parseInt(await qd.get_currentValue());
        await buz.set_volume(75);
        first_run = false;
      }


      if (await buz.isOnline()) {
        if (await button.get_isPressed() == YAnButton.ISPRESSED_TRUE) {
          lastPos = 0;
          await qd.set_currentValue(0);
          await buz.playNotes("'E32 C8");
          await leds.set_rgbColor(0, 1, 0x000000);
        } else {
          let p = parseInt(await qd.get_currentValue());
          if (lastPos != p) {
            lastPos = p;
            await buz.pulse(notefreq(p), 100);
            await leds.set_hslColor(0, 1, 0x00FF7f | (p % 255) << 16);
         }
       }
     }
     setTimeout(refresh, 10);
   }

   startDemo();
 </script>
</head>
<body>
Module to use: <input id='serial'>
<input id='msg' style='color:red;border:none;' readonly><br>
Press a  button #1, or turn the encoder #1
</body>
</html>
 

Aucune installation n'est nécessaire pout utiliser cet exemple, il suffit d'ouvrir la page HTML avec un navigateur web.

14.4. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

"use strict";

require('yoctolib-es2017/yocto_api.js');

async function startDemo(args)
{
    await YAPI.LogUnhandledPromiseRejections();

    // Setup the API to use the VirtualHub on local machine
    let errmsg = new YErrorMsg();
    if(await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        console.log('Cannot contact VirtualHub on 127.0.0.1: '+errmsg.msg);
        return;
    }

    // Select the relay to use
    let module = YModule.FindModule(args[0]);
    if(await module.isOnline()) {
        if(args.length > 1) {
            if(args[1] == 'ON') {
                await module.set_beacon(YModule.BEACON_ON);
            } else {
                await module.set_beacon(YModule.BEACON_OFF);
            }
        }
        console.log('serial:       '+await module.get_serialNumber());
        console.log('logical name: '+await module.get_logicalName());
        console.log('luminosity:   '+await module.get_luminosity()+'%');
        console.log('beacon:       '+(await module.get_beacon()==YModule.BEACON_ON?'ON':'OFF'));
        console.log('upTime:       '+parseInt(await module.get_upTime()/1000)+' sec');
        console.log('USB current:  '+await module.get_usbCurrent()+' mA');
        console.log('logs:');
        console.log(await module.get_lastLogs());
    } else {
        console.log("Module not connected (check identification and USB cable)\n");
    }
    await YAPI.FreeAPI();
}

if(process.argv.length < 2) {
    console.log("usage: node demo.js <serial or logicalname> [ ON | OFF ]");
} else {
    startDemo(process.argv.slice(2));
}
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

"use strict";

require('yoctolib-es2017/yocto_api.js');

async function startDemo(args)
{
    await YAPI.LogUnhandledPromiseRejections();

    // Setup the API to use the VirtualHub on local machine
    let errmsg = new YErrorMsg();
    if(await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        console.log('Cannot contact VirtualHub on 127.0.0.1: '+errmsg.msg);
        return;
    }
   
    // Select the relay to use
    let module = YModule.FindModule(args[0]);
    if(await module.isOnline()) {
        if(args.length > 1) {
            let newname = args[1];
            if (!await YAPI.CheckLogicalName(newname)) {
                console.log("Invalid name (" + newname + ")");
                process.exit(1);
            }
            await module.set_logicalName(newname);
            await module.saveToFlash();
        }
        console.log('Current name: '+await module.get_logicalName());
    } else {
        console.log("Module not connected (check identification and USB cable)\n");
    }
    await YAPI.FreeAPI();
}

if(process.argv.length < 2) {
    console.log("usage: node demo.js <serial> [newLogicalName]");
} else {
    startDemo(process.argv.slice(2));
}
 

Attention, le nombre de cycle d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit de que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employé par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Énumération des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction YModule.FirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la fonction nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un null. Ci-dessous un petit exemple listant les module connectés

"use strict";

require('yoctolib-es2017/yocto_api.js');

async function startDemo()
{
    await YAPI.LogUnhandledPromiseRejections();
    await YAPI.DisableExceptions();

    // Setup the API to use the VirtualHub on local machine
    let errmsg = new YErrorMsg();
    if (await YAPI.RegisterHub('127.0.0.1', errmsg) != YAPI.SUCCESS) {
        console.log('Cannot contact VirtualHub on 127.0.0.1');
        return;
    }
    refresh();
}

async function refresh()
{
    try {
        let errmsg = new YErrorMsg();
        await YAPI.UpdateDeviceList(errmsg);

        let module = YModule.FirstModule();
        while(module) {
            let line = await module.get_serialNumber();
            line += '(' + (await module.get_productName()) + ')';
            console.log(line);
            module = module.nextModule();
        }
        setTimeout(refresh, 500);
    } catch(e) {
        console.log(e);
    }
}

try {
    startDemo();
} catch(e) {
    console.log(e);
}
 

14.5. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

15. Utilisation du Yocto-MaxiKnob en PHP

PHP est, tout comme Javascript, un langage assez atypique lorsqu'il s'agit de discuter avec du hardware. Néanmoins, utiliser PHP avec des modules Yoctopuce offre l'opportunité de construire très facilement des sites web capables d'interagir avec leur environnement physique, ce qui n'est pas donné à tous les serveurs web. Cette technique trouve une application directe dans la domotique: quelques modules Yoctopuce, un serveur PHP et vous pourrez interagir avec votre maison depuis n'importe ou dans le monde. Pour autant que vous ayez une connexion internet.

PHP fait lui aussi partie de ces langages qui ne vous permettront pas d'accéder directement aux couches matérielles de votre ordinateur. C'est pourquoi vous devrez faire tourner VirtualHub sur la machine à laquelle sont branchés les modules.

Pour démarrer vos essais en PHP, vous allez avoir besoin d'un serveur PHP 7.1 ou plus récent 41 de préférence en local sur votre machine. Si vous souhaiter utiliser celui qui se trouve chez votre provider internet, c'est possible, mais vous devrez probablement configurer votre routeur ADSL pour qu'il accepte et forwarde les requêtes TCP sur le port 4444.

15.1. Préparation

Connectez vous sur le site de Yoctopuce et téléchargez les éléments suivants:

Notre librairie PHP est basée sur PHP 8.x. C'est-à-dire que notre librairie fonctionne parfaitement avec n'importe quelle version de PHP actuellement encore supportée. Toutefois, afin de ne pas abandonner nos clients qui ont des installations plus anciennes, nous maintenons une version compatible avec PHP 7.1. qui date de 2016.

Par ailleurs, nous proposons également une version de la librairie qui suit les recommandations PSR. Pour simplifier, cette version est de même code que la version php8 mais chaque classe est stockée dans un fichier séparé. De plus, cette version utilise un namespace Yoctopuce\YoctoAPI. Ces changements rendent notre librairie beaucoup plus facilement utilisable avec des installations qui utilisent l'autoload.

Notez que les exemples de la documentation n'utilisent pas la version PSR.

Dans l'archive de la librairie, il y a donc trois sous-répertoire :

Choisissez le bon répertoire en fonction de la version de la librairie que vous souhaitez utiliser, décompressez les fichiers de ce répertoire dans un répertoire de votre choix accessible à votre serveur web, branchez vos modules, lancez VirtualHub, et vous pouvez commencer vos premiers tests. Vous n'avez pas besoin d'installer de driver.

15.2. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code PHP qui utilise la fonction AnButton.


include('yocto_api.php');
include('yocto_anbutton.php');

[...]
// On active l'accès aux modules locaux à travers le VirtualHub
YAPI::RegisterHub('http://127.0.0.1:4444/',$errmsg);
[...]

// On récupère l'objet permettant d'intéragir avec le module
$anbutton = YAnButton::FindAnButton("YMXBTN01-123456.anButton1");

// Pour gérer le hot-plug, on vérifie que le module est là
if($anbutton->isOnline())
{
    // Utiliser anbutton->get_calibratedValue()
    [...]
}

Voyons maintenant en détail ce que font ces quelques lignes.

yocto_api.php et yocto_anbutton.php

Ces deux includes PHP permettent d'avoir accès aux fonctions permettant de gérer les modules Yoctopuce. yocto_api.php doit toujours être inclus, yocto_anbutton.php est nécessaire pour gérer les modules contenant une entrée analogique, comme le Yocto-MaxiKnob.

YAPI::RegisterHub

La fonction YAPI::RegisterHub permet d'indiquer sur quelle machine se trouve les modules Yoctopuce, ou plus exactemenent sur quelle machine tourne le programme VirtualHub. Dans notre cas l'adresse 127.0.0.1:4444 indique la machine locale, en utilisant le port 4444 (le port standard utilisé par Yoctopuce). Vous pouvez parfaitement changer cette adresse, et mettre l'adresse d'une autre machine sur laquelle tournerait un autre VirtualHub.

YAnButton::FindAnButton

La fonction YAnButton::FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


$anbutton = YAnButton::FindAnButton("YMXBTN01-123456.anButton1");
$anbutton = YAnButton::FindAnButton("YMXBTN01-123456.MaFonction");
$anbutton = YAnButton::FindAnButton("MonModule.anButton1");
$anbutton = YAnButton::FindAnButton("MonModule.MaFonction");
$anbutton = YAnButton::FindAnButton("MaFonction");

YAnButton::FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par YAnButton::FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YFindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YFindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YFindBuzzer ou YFirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YFindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Ouvrez votre éditeur de texte préféré44, recopiez le code ci dessous, sauvez-le dans un répertoire accessible par votre serveur web/PHP avec les fichiers de la librairie, et ouvrez-la page avec votre browser favori. Vous trouverez aussi ce code dans le répertoire Examples/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

<?php
include('../../php8/yocto_api.php');
include('../../php8/yocto_buzzer.php');
include('../../php8/yocto_colorledcluster.php');
include('../../php8/yocto_anbutton.php');
include('../../php8/yocto_quadratureDecoder.php');

function notefreq($note)
{
    return intval(220.0 * exp($note * log(2) / 12));
}

// Use explicit error handling rather than exceptions
YAPI::DisableExceptions();

// Setup the API to use the VirtualHub on local machine
if (YAPI::RegisterHub('http://127.0.0.1:4444/', $errmsg) != YAPI_SUCCESS) {
    die("Cannot contact VirtualHub on 127.0.0.1");
}

@$serial = $_GET['serial'];
if ($serial != '') {
    // Check if a specified module is available online
    $buz = YBuzzer::FindBuzzer("$serial.buzzer");
    if (!$buz->isOnline()) {
        die("Module not connected (check serial and USB cable)");
    }
} else {
    // or use any connected module suitable for the demo
    $buz = YBuzzer::Firstbuzzer();
    if (is_null($buz)) {
        die("No module connected (check USB cable)");
    } else {
        $serial = $buz->module()->get_serialnumber();
    }
}

print("Module in use: $serial\n");

// Drive the selected module
if ($buz->isOnline()) {
    $button = YAnButton::FindAnButton($serial . ".anButton1");
    $qd = YQuadratureDecoder::FindQuadratureDecoder($serial . ".quadratureDecoder1");
    $leds = YColorLedCluster::FindColorLedCluster($serial . ".colorLedCluster");

    if ((!$button->isOnline()) || (!$qd->isOnline())) {
        die("Make sure the Yocto-MaxiBuzzer is configured with at least one anButton and one quadrature Decoder\n");
    }
    $lastPos = intval($qd->get_currentValue());
    $buz->set_volume(75);

    print("press anbutton #1,  turn the encoder #1 or hit Ctrl-C\n");
    while ($button->isOnline()) {
        if (($button->get_isPressed() == YAnButton::ISPRESSED_TRUE) && ($lastPos != 0)) {
            $lastPos = 0;
            $qd->set_currentValue(0);
            $buz->playNotes("'E32 C8");
            $leds->set_rgbColor(0, 1, 0x000000);
        } else {
            $p = intval($qd->get_currentValue());
            if ($lastPos != $p) {
                $lastPos = $p;
                $buz->pulse(notefreq($p), 500);
                $leds->set_hslColor(0, 1, 0x00FF7f | ($p % 255) << 16);
            }
        }
    }
}
YAPI::FreeAPI();
?>

15.3. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

<HTML>
<HEAD>
 <TITLE>Module Control</TITLE>
</HEAD>
<BODY>
<FORM method='get'>
<?php
  include('../../php8/yocto_api.php');

  // Use explicit error handling rather than exceptions
  YAPI::DisableExceptions();

  // Setup the API to use the VirtualHub on local machine
  if(YAPI::RegisterHub('http://127.0.0.1:4444/',$errmsg) != YAPI::SUCCESS) {
      die("Cannot contact VirtualHub on 127.0.0.1 : ".$errmsg);
  }

  @$serial = $_GET['serial'];
  if ($serial != '') {
      // Check if a specified module is available online
      $module = YModule::FindModule("$serial");
      if (!$module->isOnline()) {
          die("Module not connected (check serial and USB cable)");
      }
  } else {
      // or use any connected module suitable for the demo
      $module = YModule::FirstModule();
      if($module) { // skip VirtualHub
          $module = $module->nextModule();
      }
      if(is_null($module)) {
          die("No module connected (check USB cable)");
      } else {
          $serial = $module->get_serialnumber();
      }
  }
  Print("Module to use: <input name='serial' value='$serial'><br>");

  if (isset($_GET['beacon'])) {
      if ($_GET['beacon']=='ON')
          $module->set_beacon(Y_BEACON_ON);
      else
          $module->set_beacon(Y_BEACON_OFF);
  }
  printf('serial: %s<br>',$module->get_serialNumber());
  printf('logical name: %s<br>',$module->get_logicalName());
  printf('luminosity: %s<br>',$module->get_luminosity());
  print('beacon: ');
  if($module->get_beacon() == Y_BEACON_ON) {
      printf("<input type='radio' name='beacon' value='ON' checked>ON ");
      printf("<input type='radio' name='beacon' value='OFF'>OFF<br>");
  } else {
      printf("<input type='radio' name='beacon' value='ON'>ON ");
      printf("<input type='radio' name='beacon' value='OFF' checked>OFF<br>");
  }
  printf('upTime: %s sec<br>',intVal($module->get_upTime()/1000));
  printf('USB current: %smA<br>',$module->get_usbCurrent());
  printf('logs:<br><pre>%s</pre>',$module->get_lastLogs());
  YAPI::FreeAPI();
?>
<input type='submit' value='refresh'>
</FORM>
</BODY>
</HTML>
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

<HTML>
<HEAD>
 <TITLE>save settings</TITLE>
<BODY>
<FORM method='get'>
<?php
  include('../../php8/yocto_api.php');

  // Use explicit error handling rather than exceptions
  YAPI::DisableExceptions();

  // Setup the API to use the VirtualHub on local machine
  if(YAPI::RegisterHub('http://127.0.0.1:4444/',$errmsg) != YAPI::SUCCESS) {
      die("Cannot contact VirtualHub on 127.0.0.1");
  }

  @$serial = $_GET['serial'];
  if ($serial != '') {
      // Check if a specified module is available online
      $module = YModule::FindModule("$serial");
      if (!$module->isOnline()) {
          die("Module not connected (check serial and USB cable)");
      }
  } else {
      // or use any connected module suitable for the demo
      $module = YModule::FirstModule();
      if($module) { // skip VirtualHub
          $module = $module->nextModule();
      }
      if(is_null($module)) {
          die("No module connected (check USB cable)");
      } else {
          $serial = $module->get_serialnumber();
      }
  }
  Print("Module to use: <input name='serial' value='$serial'><br>");

  if (isset($_GET['newname'])){
      $newname = $_GET['newname'];
      if (!yCheckLogicalName($newname))
          die('Invalid name');
      $module->set_logicalName($newname);
      $module->saveToFlash();
  }
  printf("Current name: %s<br>", $module->get_logicalName());
  print("New name: <input name='newname' value='' maxlength=19><br>");
  YAPI::FreeAPI();
?>
<input type='submit'>
</FORM>
</BODY>
</HTML>
 

Attention, le nombre de cycle d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit de que la sauvegarde des réglages se passera correctement. Cette limite, lié à la technologie employé par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumération des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la fonction nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un NULL. Ci-dessous un petit exemple listant les module connectés

<HTML>
<HEAD>
    <TITLE>inventory</TITLE>
</HEAD>
<BODY>
<H1>Device list</H1>
<TT>
    <?php
    include('../../php8/yocto_api.php');
    YAPI::RegisterHub("http://127.0.0.1:4444/");
    $module = YModule::FirstModule();
    while (!is_null($module)) {
        printf("%s (%s)<br>\n", $module->get_serialNumber(),
               $module->get_productName());
        $module=$module->nextModule();
    }
    YAPI::FreeAPI();
    ?>
</TT>
</BODY>
</HTML>
 

15.4. API par callback HTTP et filtres NAT

La librairie PHP est capable de fonctionner dans un mode spécial appelé Yocto-API par callback HTTP. Ce mode permet de contrôler des modules Yoctopuce installés derrière un filtre NAT tel qu'un routeur DSL par exemple, et ce sans avoir à un ouvrir un port. L'application typique est le contrôle de modules Yoctopuce situés sur réseau privé depuis un site Web publique.

Le filtre NAT, avantages et inconvénients

Un routeur DSL qui effectue de la traduction d'adresse réseau (NAT) fonctionne un peu comme un petit central téléphonique privé: les postes internes peuvent s'appeler l'un l'autre ainsi que faire des appels vers l'extérieur, mais vu de l'extérieur, il n'existe qu'un numéro de téléphone officiel, attribué au central téléphonique lui-même. Les postes internes ne sont pas atteignables depuis l'extérieur.


Configuration DSL typique, les machines du LAN sont isolées de l'extérieur par le router DSL

Ce qui, transposé en terme de réseau, donne : les appareils connectés sur un réseau domestique peuvent communiquer entre eux en utilisant une adresse IP locale (du genre 192.168.xxx.yyy), et contacter des serveurs sur Internet par leur adresse publique, mais vu de l'extérieur, il n'y a qu'une seule adresse IP officielle, attribuée au routeur DSL exclusivement. Les différents appareils réseau ne sont pas directement atteignables depuis l'extérieur. C'est assez contraignant, mais c'est une protection relativement efficace contre les intrusions.


Les réponses aux requêtes venant des machines du LAN sont routées.


Mais les requêtes venant de l'extérieur sont bloquées.

Voir Internet sans être vu représente un avantage de sécurité énorme. Cependant, cela signifie qu'a priori, on ne peut pas simplement monter son propre serveur Web publique chez soi pour une installation domotique et offrir un accès depuis l'extérieur. Une solution à ce problème, préconisée par de nombreux vendeurs de domotique, consiste à donner une visibilité externe au serveur de domotique lui-même, en ouvrant un port et en ajoutant une règle de routage dans la configuration NAT du routeur DSL. Le problème de cette solution est qu'il expose le serveur de domotique aux attaques externes.

L'API par callback HTTP résoud ce problème sans qu'il soit nécessaire de modifier la configuration du routeur DSL. Le script de contrôle des modules est placé sur un site externe, et c'est le Virtual Hub qui est chargé de l'appeler à intervalle régulier.


L'API par callback HTTP utilise le VirtualHub, et c'est lui qui initie les requêtes.

Configuration

L'API callback se sert donc du Virtual Hub comme passerelle. Toutes les communications sont initiées par le Virtual Hub, ce sont donc des communication sortantes, et par conséquent parfaitement autorisée par le routeur DSL.

Il faut configurer le VirtualHub pour qu'il appelle le script PHP régulièrement. Pour cela il faut:

  1. Lancer un VirtualHub
  2. Accéder à son interface, généralement 127.0.0.1:4444
  3. Cliquer sur le bouton configure de la ligne correspondant au VirtualHub lui-même
  4. Cliquer sur le bouton edit de la section Outgoing callbacks


Cliquer sur le bouton "configure" de la première ligne


Cliquer sur le bouton "edit" de la section Outgoing callbacks.


Et choisir "Yocto-API callback".

Il suffit alors de définir l'URL du script PHP et, si nécessaire, le nom d'utilisateur et le mot de passe pour accéder à cette URL. Les méthodes d'authentification supportées sont basic et digest. La seconde est plus sûre que la première car elle permet de ne pas transférer le mot de passe sur le réseau.

Utilisation

Du point de vue du programmeur, la seule différence se trouve au niveau de l'appel à la fonction yRegisterHub; au lieu d'utiliser une adresse IP, il faut utiliser la chaîne callback (ou http://callback, qui est équivalent).


include("yocto_api.php");
yRegisterHub("callback");

La suite du code reste strictement identique. Sur l'interface du VirtualHub, il y a en bas de la fenêtre de configuration de l'API par callback HTTP un bouton qui permet de tester l'appel au script PHP.

Il est à noter que le script PHP qui contrôle les modules à distance via l'API par callback HTTP ne peut être appelé que par le VirtualHub. En effet, il a besoin des informations postées par le VirtualHub pour fonctionner. Pour coder un site Web qui contrôle des modules Yoctopuce de manière interactive, il faudra créer une interface utilisateur qui stockera dans un fichier ou une base de données les actions à effectuer sur les modules Yoctopuce. Ces actions seront ensuite lues puis exécutés par le script de contrôle.

Problèmes courants

Pour que l'API par callback HTTP fonctionne, l'option de PHP allow_url_fopen doit être activée. Certains hébergeurs de site web ne l'activent pas par défaut. Le problème se manifeste alors avec l'erreur suivante:

error: URL file-access is disabled in the server configuration

Pour activer cette option, il suffit de créer dans le même répertoire que le script PHP de contrôle un fichier .htaccess contenant la ligne suivante:
php_flag "allow_url_fopen" "On"
Selon la politique de sécurité de l'hébergeur, il n'est parfois pas possible d'autoriser cette option à la racine du site web, où même d'installer des scripts PHP recevant des données par un POST HTTP. Dans ce cas il suffit de placer le script PHP dans un sous-répertoire.

Limitations

Cette méthode de fonctionnement qui permet de passer les filtres NAT à moindre frais a malgré tout un prix. Les communications étant initiées par le Virtual Hub à intervalle plus ou moins régulier, le temps de réaction à un événement est nettement plus grand que si les modules Yoctopuce étaient pilotés en direct. Vous pouvez configurer le temps de réaction dans la fenêtre ad-hoc du Virtual Hub, mais il sera nécessairement de quelques secondes dans le meilleur des cas.

Le mode Yocto-API par callback HTTP n'est pour l'instant disponible qu'en PHP, EcmaScript (Node.JS) et Java.

15.5. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

16. Utilisation du Yocto-MaxiKnob en VisualBasic .NET

VisualBasic a longtemps été la porte d'entrée privilégiée vers le monde Microsoft. Nous nous devions donc d'offrir notre interface pour ce langage, même si la nouvelle tendance est le C#. Nous supportons Visual Studio 2017 et les versions plus récentes.

16.1. Installation

Téléchargez la librairie Yoctopuce pour Visual Basic depuis le site web de Yoctopuce45. Il n'y a pas de programme d'installation, copiez simplement de contenu du fichier zip dans le répertoire de votre choix. Vous avez besoin essentiellement du contenu du répertoire Sources. Les autres répertoires contiennent la documentation et quelques programmes d'exemple. Les projets d'exemple sont des projets Visual Basic 2010, si vous utilisez une version antérieure, il est possible que vous ayez à reconstruire la structure de ces projets.

16.2. Utilisation l'API yoctopuce dans un projet Visual Basic

La librairie Yoctopuce pour Visual Basic .NET se présente sous la forme d'une DLL et de fichiers sources en Visual Basic. La DLL n'est pas une DLL .NET mais une DLL classique, écrite en C, qui gère les communications à bas niveau avec les modules46. Les fichiers sources en Visual Basic gèrent la partie haut niveau de l'API. Vous avez donc besoin de cette DLL et des fichiers .vb du répertoire Sources pour créer un projet gérant des modules Yoctopuce.

Configuration d'un projet Visual Basic

Les indications ci-dessous sont fournies pour Visual Studio express 2010, mais la procédure est semblable pour les autres versions.

Commencez par créer votre projet, puis depuis le panneau Explorateur de solutions effectuez un clic droit sur votre projet, et choisissez Ajouter puis Elément existant.

Une fenêtre de sélection de fichiers apparaît: sélectionnez le fichier yocto_api.vb et les fichiers correspondant aux fonctions des modules Yoctopuce que votre projet va gérer. Dans le doute, vous pouvez aussi sélectionner tous les fichiers.

Vous avez alors le choix entre simplement ajouter ces fichiers à votre projet, ou les ajouter en tant que lien (le bouton Ajouter est en fait un menu déroulant). Dans le premier cas, Visual Studio va copier les fichiers choisis dans votre projet, dans le second Visual Studio va simplement garder un lien sur les fichiers originaux. Il est recommandé d'utiliser des liens, une éventuelle mise à jour de la librairie sera ainsi beaucoup plus facile.

Ensuite, ajoutez de la même manière la dll yapi.dll, qui se trouve dans le répertoire Sources/dll47. Puis depuis la fenêtre Explorateur de solutions, effectuez un clic droit sur la DLL, choisissez Propriété et dans le panneau Propriétés, mettez l'option Copier dans le répertoire de sortie à toujours copier. Vous êtes maintenant prêt à utiliser vos modules Yoctopuce depuis votre environnement Visual Studio.

Afin de les garder simples, tous les exemples fournis dans cette documentation sont des applications consoles. Il va de soit que que les fonctionnement des librairies est strictement identiques si vous les intégrez dans une application dotée d'une interface graphique.

16.3. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code VisualBasic .NET qui utilise la fonction AnButton.


[...]
' On active la détection des modules sur USB
Dim errmsg As String
YAPI.RegisterHub("usb", errmsg)
[...]

' On récupère l'objet permettant d'intéragir avec le module
Dim anbutton As YAnButton
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1")

' Pour gérer le hot-plug, on vérifie que le module est là
If (anbutton.isOnline()) Then
    ' Utiliser anbutton.get_calibratedValue()
    [...]
End If

[...]

Voyons maintenant en détail ce que font ces quelques lignes.

YAPI.RegisterHub

La fonction YAPI.RegisterHub initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Utilisée avec le paramètre "usb", elle permet de travailler avec les modules connectés localement à la machine. Si l'initialisation se passe mal, cette fonction renverra une valeur différente de YAPI_SUCCESS, et retournera via le paramètre errmsg un explication du problème.

YAnButton.FindAnButton

La fonction YAnButton.FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1")
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.MaFonction")
anbutton = YAnButton.FindAnButton("MonModule.anButton1")
anbutton = YAnButton.FindAnButton("MonModule.MaFonction")
anbutton = YAnButton.FindAnButton("MaFonction")

YAnButton.FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YFindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YFindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YFindBuzzer ou YFirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YFindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Lancez Microsoft VisualBasic et ouvrez le projet exemple correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

Module Module1
  Private Sub Usage()
    Dim execname = System.AppDomain.CurrentDomain.FriendlyName
    Console.WriteLine("Usage:")
    Console.WriteLine(execname + "  <serial_number>  frequency")
    Console.WriteLine(execname + "  <logical_name> frequency")
    Console.WriteLine(execname + "  any frequency")
    System.Threading.Thread.Sleep(2500)
    End
  End Sub

  Sub Main()
    Dim argv() As String = System.Environment.GetCommandLineArgs()
    Dim errmsg As String = ""

    Dim buz As YBuzzer
    Dim leds As YColorLedCluster
    Dim button1 As YAnButton
    Dim qd As YQuadratureDecoder
    Dim target, serial As String
    Dim lastpos As Integer

    If argv.Length < 2 Then Usage()
    target = argv(1)

    REM Setup the API to use local USB devices
    If (YAPI.RegisterHub("usb", errmsg) <> YAPI_SUCCESS) Then
      Console.WriteLine("RegisterHub error: " + errmsg)
      End
    End If

    If target = "any" Then
      buz = YBuzzer.FirstBuzzer()
      If buz Is Nothing Then
        Console.WriteLine("No module connected (check USB cable) ")
        End
      End If
    Else
      buz = YBuzzer.FindBuzzer(target + ".buzzer")
    End If

    If (Not buz.isOnline()) Then
      Console.WriteLine("No module connected (check identification and USB cable)")
      End
    End If

    serial = buz.get_module().get_serialNumber()
    leds = YColorLedCluster.FindColorLedCluster(serial + ".colorLed")
    button1 = YAnButton.FindAnButton(serial + ".anButton1")
    qd = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1")

    If (Not button1.isOnline() Or Not qd.isOnline()) Then
      Console.WriteLine("Make sure the Yocto-MaxiBuzzer is configured with at least one anButton and one quadrature Decoder")
      End
    End If

    Console.WriteLine("press a test button, or turn the encoder or hit Ctrl-C")
    lastpos = CType(qd.get_currentValue(), Integer)
    buz.set_volume(75)
    While (button1.isOnline())

      If (button1.get_isPressed() = YAnButton.ISPRESSED_TRUE And lastpos <> 0) Then
        lastpos = 0
        qd.set_currentValue(0)
        buz.playNotes("'E32 C8")
        leds.set_rgbColor(0, 1, 0)
      Else
        Dim p As Integer = CType(qd.get_currentValue(), Integer)
        If (lastpos <> p) Then
          lastpos = p
          buz.pulse(notefreq(p), 500)
          leds.set_hslColor(0, 1, &HFF7F Or (p Mod 255) << 16)
        End If
      End If

    End While
    YAPI.FreeAPI()
  End Sub

  Private Function notefreq(note As Integer) As Integer
    Return CType((220.0 * Math.Exp(note * Math.Log(2) / 12)), Integer)
  End Function
End Module
 

16.4. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.


Imports System.IO
Imports System.Environment

Module Module1

  Sub usage()
    Console.WriteLine("usage: demo <serial or logical name> [ON/OFF]")
    End
  End Sub

  Sub Main()
    Dim argv() As String = System.Environment.GetCommandLineArgs()
    Dim errmsg As String = ""
    Dim m As ymodule

    If (YAPI.RegisterHub("usb", errmsg) <> YAPI_SUCCESS) Then
      Console.WriteLine("RegisterHub error:" + errmsg)
      End
    End If

    If argv.Length < 2 Then usage()

    m = YModule.FindModule(argv(1)) REM use serial or logical name
    If (m.isOnline()) Then
      If argv.Length > 2 Then
        If argv(2) = "ON" Then m.set_beacon(Y_BEACON_ON)
        If argv(2) = "OFF" Then m.set_beacon(Y_BEACON_OFF)
      End If
      Console.WriteLine("serial:       " + m.get_serialNumber())
      Console.WriteLine("logical name: " + m.get_logicalName())
      Console.WriteLine("luminosity:   " + Str(m.get_luminosity()))
      Console.Write("beacon:       ")
      If (m.get_beacon() = Y_BEACON_ON) Then
        Console.WriteLine("ON")
      Else
        Console.WriteLine("OFF")
      End If
      Console.WriteLine("upTime:       " + Str(m.get_upTime() / 1000) + " sec")
      Console.WriteLine("USB current:  " + Str(m.get_usbCurrent()) + " mA")
      Console.WriteLine("Logs:")
      Console.WriteLine(m.get_lastLogs())
    Else
      Console.WriteLine(argv(1) + " not connected (check identification and USB cable)")
    End If
    YAPI.FreeAPI()
  End Sub

End Module
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

Module Module1


  Sub usage()

    Console.WriteLine("usage: demo <serial or logical name> <new logical name>")
    End
  End Sub

  Sub Main()
    Dim argv() As String = System.Environment.GetCommandLineArgs()
    Dim errmsg As String = ""
    Dim newname As String
    Dim m As YModule

    If (argv.Length <> 3) Then usage()

    REM Setup the API to use local USB devices
    If YAPI.RegisterHub("usb", errmsg) <> YAPI_SUCCESS Then
      Console.WriteLine("RegisterHub error: " + errmsg)
      End
    End If

    m = YModule.FindModule(argv(1)) REM use serial or logical name
    If m.isOnline() Then
      newname = argv(2)
      If (Not YAPI.CheckLogicalName(newname)) Then
        Console.WriteLine("Invalid name (" + newname + ")")
        End
      End If
      m.set_logicalName(newname)
      m.saveToFlash() REM do not forget this
      Console.Write("Module: serial= " + m.get_serialNumber)
      Console.Write(" / name= " + m.get_logicalName())
    Else
      Console.Write("not connected (check identification and USB cable")
    End If
    YAPI.FreeAPI()

  End Sub

End Module
 

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la fonction nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un Nothing. Ci-dessous un petit exemple listant les module connectés

Module Module1

  Sub Main()
    Dim M As ymodule
    Dim errmsg As String = ""

    REM Setup the API to use local USB devices
    If YAPI.RegisterHub("usb", errmsg) <> YAPI_SUCCESS Then
      Console.WriteLine("RegisterHub error: " + errmsg)
      End
    End If

    Console.WriteLine("Device list")
    M = YModule.FirstModule()
    While M IsNot Nothing
      Console.WriteLine(M.get_serialNumber() + " (" + M.get_productName() + ")")
      M = M.nextModule()
    End While
    YAPI.FreeAPI()
  End Sub

End Module
 

16.5. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

17. Utilisation du Yocto-MaxiKnob en Delphi / Lazarus

Delphi est l'héritier de Turbo-Pascal. A l'origine, Delphi était produit par Borland, mais c'est maintenant Embarcadero qui l'édite. Sa force réside dans sa facilité d'utilisation, il permet à quiconque ayant des notions de Pascal de programmer une application Windows en deux temps trois mouvements. Son seul défaut est d'être payant48.

Lazarus49 est un IDE gratuit basé sur Free-Pascal qui n'a pas grand chose à envier à Delphi. Il a aussi l'avantage d'exister pour Windows et Linux. La librairie Yoctopuce pour Delphi est compatible avec Lazarus tant sous Windows que Linux.

Les librairies pour Delphi / Lazarus sont fournies non pas sous forme de composants VCL, mais directement sous forme de fichiers source. Ces fichiers sont compatibles avec la plupart des versions de Delphi / Lazarus 50.

17.1. Préparation

Connectez-vous sur le site de Yoctopuce et téléchargez la la librairie Yoctopuce pour Delphi51. Décompressez le tout dans le répertoire de votre choix.

Windows

Sous Windows, la librairie Delphi / Lazarus utilise deux DLL: yapi.dll pour exécutables 32bits et yapi64.dll pour les exécutable 64bits. Toutes les applications que vous créerez avec Delphi ou Lazarus devront avoir accès à ces DLL. Le plus simple est de faire en sorte qu'elles soient présentes dans le même répertoire que l'exécutable de votre application. Vous trouverez ces DLL dans le répertoire sources/dll.

Linux

Sous Linux, la librairie Delphi / Lazarus utilise les librairies suivantes:

Vous trouverez ces fichiers lib dans le répertoire sources/dll. Vous devez faire en sorte que :

La solution la plus simple pour remplir ces conditions consiste à copier ces quatre fichiers dans le répertoire /usr/lib. Une autre solution consiste à les copier dans le même répertoire que votre code source et à ajuster votre variable d'environnement LD_LIBRARY_PATHen conséquence.

A propos des exemples

Afin de les garder simples, tous les exemples fournis dans cette documentation sont des applications consoles. Il va de soit que le fonctionnement des librairies est strictement identique avec des applications fenêtrées.

Notez que la plupart de ces exemples utilisent des paramètres passés sur le ligne de commande54.

Vous allez rapidement vous rendre compte que l'API Delphi définit beaucoup de fonctions qui retournent des objets. Vous ne devez jamais désallouer ces objets vous-même. Ils seront désalloués automatiquement par l'API à la fin de l'application.

17.2. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code Delphi qui utilise la fonction AnButton.


uses yocto_api, yocto_anbutton;

var errmsg: string;
    anbutton: TYAnButton;

[...]
// On active la détection des modules sur USB
yRegisterHub('usb',errmsg)
[...]

// On récupère l'objet permettant d'intéragir avec le module
anbutton = yFindAnButton("YMXBTN01-123456.anButton1")

// Pour gérer le hot-plug, on vérifie que le module est là
if anbutton.isOnline() then
    begin
        // use anbutton.get_calibratedValue()
        [...]
    end;
[...]

Voyons maintenant en détail ce que font ces quelques lignes.

yocto_api et yocto_anbutton

Ces deux unités permettent d'avoir accès aux fonctions permettant de gérer les modules Yoctopuce. yocto_api doit toujours être utilisé, yocto_anbutton est nécessaire pour gérer les modules contenant une entrée analogique, comme le Yocto-MaxiKnob.

yRegisterHub

La fonction yRegisterHub initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Utilisée avec le paramètre 'usb', elle permet de travailler avec les modules connectés localement à la machine. Si l'initialisation se passe mal, cette fonction renverra une valeur différente de YAPI_SUCCESS, et retournera via le paramètre errmsg un explication du problème.

yFindAnButton

La fonction yFindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton := yFindAnButton("YMXBTN01-123456.anButton1");
anbutton := yFindAnButton("YMXBTN01-123456.MaFonction");
anbutton := yFindAnButton("MonModule.anButton1");
anbutton := yFindAnButton("MonModule.MaFonction");
anbutton := yFindAnButton("MaFonction");

yFindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par yFindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YFindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YFindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YFindBuzzer ou YFirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YFindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Lancez votre environnement Delphi, copiez la DLL yapi.dll dans un répertoire et créez une nouvelle application console dans ce même répertoire, et copiez-coller le code ci dessous.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

program helloworld;
{$APPTYPE CONSOLE}
uses
  SysUtils,
  {$IFNDEF UNIX}
  windows,
  {$ENDIF UNIX}  
  yocto_api,
  yocto_buzzer,
  yocto_anbutton,
  yocto_colorledcluster,
  yocto_quadraturedecoder;

Procedure  Usage();
  var
   exe : string;

  begin
    exe:= ExtractFileName(paramstr(0));
    WriteLn(exe+' <serial_number>');
    WriteLn(exe+' <logical_name>');
    WriteLn(exe+' any ');
    WriteLn('');
    WriteLn('Example:');
    WriteLn(exe+' any');
    sleep(3000);
    halt;
  End;

 function notefreq( note:integer) :integer;
    begin
      notefreq := round(220.0 * Exp(note * ln(2) / 12));
    end ;

var
  m               : TYmodule;
  buz             : TYBuzzer;
  leds            : TYColorLedCluster;
  button          : TYAnButton;
  qd              : TYQuadratureDEcoder;
  lastPos,p         : integer;
  serial          : string;
  errmsg          : string;

begin

  if (paramcount<1) then usage();

  // Setup the API to use local USB devices
  if yRegisterHub('usb', errmsg)<>YAPI_SUCCESS then
  begin
    Write('RegisterHub error: '+errmsg);
    sleep(3000);
    exit;
  end;

  if paramstr(1)='any' then
    begin
      // try to first the first relay available
      buz := yFirstbuzzer();
      if buz=nil then
         begin
           writeln('No module connected (check USB cable)');
           sleep(3000);
           halt;
         end
      end
  else // or use the one specified the command line
    buz:= YFindBuzzer(paramstr(1)+'.buzzer');

  // make sure it connected
  if not buz.isOnline() then
    begin
       writeln('No module connected (check USB cable)');
       sleep(3000);
       halt;
    end;

  m:= buz.get_module();
  serial := m.get_serialNumber();
  leds:= YFindColorLedCluster(serial+'.colorLedCluster');
  button := YFindAnButton(serial+'.anButton1');
  qd := YFindQuadratureDecoder(serial+'.quadratureDecoder1');

  writeln('press button #1, or turn the encoder #1 or hit Ctrl-C');
  lastPos := round(qd.get_currentValue());
  buz.set_volume(75);
  while (button.isOnline())do
    begin
      if ((button.get_isPressed()=Y_ISPRESSED_TRUE) and (lastPos <> 0))  then
      begin
          lastPos := 0;
          qd.set_currentValue(0);
          buz.playNotes('''E32 C8');
          leds.set_rgbColor(0, 1, $000000);
      end
        else
       begin
          p := round(qd.get_currentValue());
          if (lastPos <> p) then
          begin
            lastPos := p;
            buz.pulse(notefreq(p), 500);
            leds.set_hslColor(0, 1, $00FF7f or (p mod 255) shl 16);
         end

      end
  end;

  yFreeAPI();
end.

17.3. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

program modulecontrol;
{$APPTYPE CONSOLE}
uses
  SysUtils,
  yocto_api;

const
  serial = 'YMXBTN01-123456'; // use serial number or logical name

procedure refresh(module:Tymodule) ;
  begin
    if (module.isOnline())  then
     begin
       Writeln('');
       Writeln('Serial       : ' + module.get_serialNumber());
       Writeln('Logical name : ' + module.get_logicalName());
       Writeln('Luminosity   : ' + intToStr(module.get_luminosity()));
       Write('Beacon    :');
       if  (module.get_beacon()=Y_BEACON_ON) then Writeln('on')
                                             else Writeln('off');
       Writeln('uptime       : ' + intToStr(module.get_upTime() div 1000)+'s');
       Writeln('USB current  : ' + intToStr(module.get_usbCurrent())+'mA');
       Writeln('Logs         : ');
       Writeln(module.get_lastlogs());
       Writeln('');
       Writeln('r : refresh / b:beacon ON / space : beacon off');
     end
    else Writeln('Module not connected (check identification and USB cable)');
  end;


procedure beacon(module:Tymodule;state:integer);
  begin
    module.set_beacon(state);
    refresh(module);
  end;

var
  module : TYModule;
  c      : char;
  errmsg : string;

begin
  // Setup the API to use local USB devices
  if yRegisterHub('usb', errmsg)<>YAPI_SUCCESS then
  begin
    Write('RegisterHub error: '+errmsg);
    exit;
  end;

  module := yFindModule(serial);
  refresh(module);

  repeat
    read(c);
    case c of
     'r': refresh(module);
     'b': beacon(module,Y_BEACON_ON);
     ' ': beacon(module,Y_BEACON_OFF);
    end;
  until  c = 'x';
  yFreeAPI();
end.

Chaque propriété xxx du module peut être lue grâce à une méthode du type get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

program savesettings;
{$APPTYPE CONSOLE}
uses
  SysUtils,
  yocto_api;

const
  serial = 'YMXBTN01-123456'; // use serial number or logical name

var
  module  : TYModule;
  errmsg  : string;
  newname : string;

begin
  // Setup the API to use local USB devices
  if yRegisterHub('usb', errmsg)<>YAPI_SUCCESS then
  begin
    Write('RegisterHub error: '+errmsg);
    exit;
  end;

  module := yFindModule(serial);
  if (not(module.isOnline)) then
   begin
     writeln('Module not connected (check identification and USB cable)');
     exit;
   end;

  Writeln('Current logical name : '+module.get_logicalName());
  Write('Enter new name : ');
  Readln(newname);
  if (not(yCheckLogicalName(newname))) then
   begin
     Writeln('invalid logical name');
     exit;
   end;
  module.set_logicalName(newname);
  module.saveToFlash();
  yFreeAPI();
  Writeln('logical name is now : '+module.get_logicalName());
end.
 

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Énumération des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la fonction nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un nil. Ci-dessous un petit exemple listant les module connectés

program inventory;
{$APPTYPE CONSOLE}
uses
  SysUtils,
  yocto_api;

var
  module : TYModule;
  errmsg : string;

begin
  // Setup the API to use local USB devices
  if yRegisterHub('usb', errmsg)<>YAPI_SUCCESS then
  begin
    Write('RegisterHub error: '+errmsg);
    exit;
  end;

  Writeln('Device list');

  module := yFirstModule();
  while module<>nil  do
   begin
     Writeln( module.get_serialNumber()+' ('+module.get_productName()+')');
     module := module.nextModule();
   end;
  yFreeAPI();

end.

17.4. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

18. Utilisation du Yocto-MaxiKnob avec Universal Windows Platform

Universal Windows Platform, abrégé UWP, est n'est pas un langage à proprememt parler mais une plate-forme logicielle créée par Micorosft. Cette platform permet d'executer un nouveau type d'applications : les application universelle Windows. Ces applicaiton peuvent fonctionner sur toutes les machines qui fonctione sous Windows 10. Cela comprend les PCs, les tablettes, les smartphones, la XBox One, mais aussi Windows IoT Core.

La librairie Yoctopuce UWP permet d'utiliser les modules Yoctopuce dans une application universelle Winodws et est entièrement écrite C#. Elle peut être ajoutée a un projet Visual Studio 201755.

18.1. Fonctions bloquantes et fonctions asynchrones

La librairie Universal Windows Platform n'utilise pas l'API win32 mais uniquement l'API Windows Runtime qui est disponible sur toutes les versions de Windows 10 et pour n'importe quelle architecture. Grâce à cela la librairie UWP peut être utilisé sur toutes les versions de Windows 10, y compris Windows 10 IoT Core.

Cependant, l'utilisation des nouvelles API UWP n'est pas sans conséquence: l'API Windows Runtime pour accéder aux ports USB est asynchrone, et par conséquent la librairie Yoctopuce doit aussi être asynchrone. Concrètement les méthodes asynchrones ne retournent pas directement le résultat mais un objet Task ou Task<> et le résultat peut être obtenu plus tard. Fort heureusement, le langage C# version 6 supporte les mots-clefs async et await qui simplifie beaucoup l'utilisation de ces fonctions. Il est ainsi possible d'utiliser les fonctions asynchrones de la même manière que les fonctions traditionnelles pour autant que les deux règles suivantes soient respectées:

Exemple:

async Task<int> MyFunction(int  val)
{
    // do some long computation
    ...

    return result;
}

int res = await MyFunction(1234);

Notre librairie suit ces deux règles et peut donc d’utiliser la notation await.

Pour ne pas devoir vous poser la question pour chaque méthode de savoir si elle est asynchrone ou pas, la convention est la suivante: toutes les méthodes publiques de la librairie UWP sont asyncrones, c'est-à-dire qui faut les appeler en ajoutant le mot clef await, sauf:

18.2. Installation

Téléchargez la librairie Yoctopuce pour Universal Windows Platform depuis le site web de Yoctopuce 56. Il n'y a pas de programme d'installation, copiez simplement de contenu du fichier zip dans le répertoire de votre choix. Vous avez besoin essentiellement du contenu du répertoire Sources. Les autres répertoires contiennent la documentation et quelques programmes d'exemple. Les projets d'exemple sont des projets Visual Studio 2017 qui est disponible sur le site de Microsoft 57.

18.3. Utilisation l'API Yoctopuce dans un projet Visual Studio

Commencez par créer votre projet , puis depuis le panneau Explorateur de solutions effectuez un clic droit sur votre projet, et choisissez Ajouter puis Élément existant .

Une fenêtre de sélection de fichiers apparaît: sélectionnez tous les fichiers du répertoire Sources de la librairie.

Vous avez alors le choix entre simplement ajouter ces fichiers à votre projet, ou les ajouter en tant que lien (le bouton Ajouter est en fait un menu déroulant). Dans le premier cas, Visual Studio va copier les fichiers choisis dans votre projet, dans le second Visual Studio va simplement garder un lien sur les fichiers originaux. Il est recommandé d'utiliser des liens, une éventuelle mise à jour de la librairie sera ainsi beaucoup plus facile.

Le fichier Package.appxmanifest

Par défaut, une application Universal Windows n'a pas le droit d’accéder aux ports USB. Si l'on désire accéder à un périphérique USB, il faut impérativement le déclarer dans le fichier Package.appxmanifest.

Malheureusement, la fenêtre d'édition de ce fichier ne permet pas cette opération et il faut modifier le fichier Package.appxmanifest à la main. Dans le panneau "Solutions Explorer", faites un clic droit sur le fichier Package.appxmanifest et sélectionner "View Code".

Dans ce fichier XML, il faut rajouter un nœud DeviceCapability dans le nœud Capabilities. Ce nœud doit avoir un attribut "Name" qui vaut "humaninterfacedevice".

A l’intérieur de ce nœud, il faut déclarer tous les modules qui peuvent être utilisés. Concrètement, pour chaque module, il faut ajouter un nœud "Device" avec un attribut "Id" dont la valeur est une chaîne de caractères "vidpid:USB_VENDORID USB_DEVICE_ID". Le USB_VENDORID de Yoctopuce est 24e0 et le USB_DEVICE_ID de chaque module Yoctopuce peut être trouvé dans la documentation dans la section "Caractéristiques". Pour finir, le nœud "Device" doit contenir un nœud "Function" avec l'attribut "Type" dont la valeur est "usage:ff00 0001".

Pour le Yocto-MaxiKnob voici ce qu'il faut ajouter dans le nœud "Capabilities":


  <DeviceCapability Name="humaninterfacedevice">
      <!-- Yocto-MaxiKnob -->
      <Device Id="vidpid:24e0 009E">
        <Function Type="usage:ff00 0001" />
      </Device>
    </DeviceCapability>

Malheureusement, il n'est pas possible d'écrire un règle qui autorise tous les modules Yoctopuce, par conséquent il faut impérativement ajouter chaque module que l'on désire utiliser.

18.4. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code c# qui utilise la fonction AnButton.


[...]
// On active la détection des modules sur USB
await YAPI.RegisterHub("usb");
[...]

// On récupère l'objet permettant d'intéragir avec le module
YAnButton anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1");

// Pour gérer le hot-plug, on vérifie que le module est là
if (await anbutton.isOnline())
{
        // Use anbutton.get_calibratedValue()
    ...
}

[...]

Voyons maintenant en détail ce que font ces quelques lignes.

YAPI.RegisterHub

La fonction YAPI.RegisterHub initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Le paramètre est l'adresse du virtual hub capable de voir les modules. Si l'on passe la chaîne de caractère "usb", l'API va travailler avec les modules connectés localement à la machine. Si l'initialisation se passe mal, une exception sera générée.

YAnButton.FindAnButton

La fonction YAnButton.FindAnButton permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


anbutton = YAnButton.FindAnButton("YMXBTN01-123456.anButton1");
anbutton = YAnButton.FindAnButton("YMXBTN01-123456.MaFonction");
anbutton = YAnButton.FindAnButton("MonModule.anButton1");
anbutton = YAnButton.FindAnButton("MonModule.MaFonction");
anbutton = YAnButton.FindAnButton("MaFonction");

YAnButton.FindAnButton renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YQuadratureDecoder.FindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YBuzzer.FindBuzzer ou YBuzzer.FirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YColorLedCluster.FindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

18.5. Un exemple concret

Lancez Visual Studio et ouvrez le projet correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce.

Le projets Visual Studio contient de nombreux fichiers dont la plupart ne sont pas liés à l'utilisation de la librairie Yoctopuce. Pour simplifier la lecture du code nous avons regroupé tout le code qui utilise la librairie dans la classe Demo qui se trouve dans le fichier demo.cs. Les propriétés de cette classe correspondent aux différentes champs qui sont affichés à l'écran, et la méthode Run() contient le code qui est exécuté quand le bouton "Start" est pressé.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using Windows.UI.Xaml.Controls;
using com.yoctopuce.YoctoAPI;

namespace Demo
{
  public class Demo : DemoBase
  {
    public string HubURL { get; set; }
    public string Target { get; set; }

    static int notefreq(int note)
    {
      return (int) (220.0 * Math.Exp(note * Math.Log(2) / 12));
    }

    public override async Task<int> Run()
    {
      try {
        await YAPI.RegisterHub(HubURL);

        YBuzzer buz;
        YColorLedCluster leds;
        YQuadratureDecoder qd;
        YAnButton button;

        if (Target.ToLower() == "any") {
          buz = YBuzzer.FirstBuzzer();
          if (buz == null) {
            WriteLine("No module connected (check USB cable) ");
            return -1;
          }
        } else buz = YBuzzer.FindBuzzer(Target + ".buzzer");

        if (!await buz.isOnline()) {
          WriteLine("Module not connected (check identification and USB cable)");
          return -1;
        }

        string serial = await (await buz.get_module()).get_serialNumber();
        leds = YColorLedCluster.FindColorLedCluster(serial + ".colorLedCluster");
        button = YAnButton.FindAnButton(serial + ".anButton1");
        qd = YQuadratureDecoder.FindQuadratureDecoder(serial + ".quadratureDecoder1");

        if ((!await button.isOnline()) || (!await qd.isOnline())) {
          WriteLine("Make sure the Yocto-MaxiBuzzer is configured with at least one anButton and one quadrature Decoder");
          return -1;
        }

        WriteLine("press a test button, or turn the encoder or hit Ctrl-C");
        int lastPos = (int) await qd.get_currentValue();
        await buz.set_volume(75);
        while (await button.isOnline()) {
          if ((await button.get_isPressed() == YAnButton.ISPRESSED_TRUE)
              && (lastPos != 0)) {
            lastPos = 0;
            await qd.set_currentValue(0);
            await buz.playNotes("'E32 C8");
            await leds.set_rgbColor(0, 1, 0x000000);
          } else {
            int p = (int) await qd.get_currentValue();
            if (lastPos != p) {
              lastPos = p;
              await buz.pulse(notefreq(p), 500);
              await leds.set_hslColor(0, 1, 0x00FF7f | (p % 255) << 16);
            }
          }
        }
      } catch (YAPI_Exception ex) {
        WriteLine("error: " + ex.Message);
      }

      await YAPI.FreeAPI();
      return 0;
    }
  }
}

18.6. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci-dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using Windows.UI.Xaml.Controls;
using com.yoctopuce.YoctoAPI;

namespace Demo
{
  public class Demo : DemoBase
  {

    public string HubURL { get; set; }
    public string Target { get; set; }
    public bool Beacon { get; set; }

    public override async Task<int> Run()
    {
      YModule m;
      string errmsg = "";

      if (await YAPI.RegisterHub(HubURL) != YAPI.SUCCESS) {
        WriteLine("RegisterHub error: " + errmsg);
        return -1;
      }
      m = YModule.FindModule(Target + ".module"); // use serial or logical name
      if (await m.isOnline()) {
        if (Beacon) {
          await m.set_beacon(YModule.BEACON_ON);
        } else {
          await m.set_beacon(YModule.BEACON_OFF);
        }

        WriteLine("serial: " + await m.get_serialNumber());
        WriteLine("logical name: " + await m.get_logicalName());
        WriteLine("luminosity: " + await m.get_luminosity());
        Write("beacon: ");
        if (await m.get_beacon() == YModule.BEACON_ON)
          WriteLine("ON");
        else
          WriteLine("OFF");
        WriteLine("upTime: " + (await m.get_upTime() / 1000) + " sec");
        WriteLine("USB current: " + await m.get_usbCurrent() + " mA");
        WriteLine("Logs:\r\n" + await m.get_lastLogs());
      } else {
        WriteLine(Target + " not connected  on" + HubURL +
                  "(check identification and USB cable)");
      }
      await YAPI.FreeAPI();
      return 0;
    }
  }
}

Chaque propriété xxx du module peut être lue grâce à une méthode du type YModule.get_xxxx(), et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode YModule.set_xxx() Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction YModule.set_xxx() correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode YModule.saveToFlash(). Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode YModule.revertFromFlash(). Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using Windows.UI.Xaml.Controls;
using com.yoctopuce.YoctoAPI;

namespace Demo
{
  public class Demo : DemoBase
  {

    public string HubURL { get; set; }
    public string Target { get; set; }
    public string LogicalName { get; set; }

    public override async Task<int> Run()
    {
      try {
        YModule m;

        await YAPI.RegisterHub(HubURL);

        m = YModule.FindModule(Target); // use serial or logical name
        if (await m.isOnline()) {
          if (!YAPI.CheckLogicalName(LogicalName)) {
            WriteLine("Invalid name (" + LogicalName + ")");
            return -1;
          }

          await m.set_logicalName(LogicalName);
          await m.saveToFlash(); // do not forget this
          Write("Module: serial= " + await m.get_serialNumber());
          WriteLine(" / name= " + await m.get_logicalName());
        } else {
          Write("not connected (check identification and USB cable");
        }
      } catch (YAPI_Exception ex) {
        WriteLine("RegisterHub error: " + ex.Message);
      }
      await YAPI.FreeAPI();
      return 0;
    }
  }
}

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction YModule.saveToFlash() que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction YModule.yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la méthode nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un null. Ci-dessous un petit exemple listant les module connectés

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using Windows.UI.Xaml.Controls;
using com.yoctopuce.YoctoAPI;

namespace Demo
{
  public class Demo : DemoBase
  {
    public string HubURL { get; set; }

    public override async Task<int> Run()
    {
      YModule m;
      try {
        await YAPI.RegisterHub(HubURL);

        WriteLine("Device list");
        m = YModule.FirstModule();
        while (m != null) {
          WriteLine(await m.get_serialNumber()
                    + " (" + await m.get_productName() + ")");
          m = m.nextModule();
        }
      } catch (YAPI_Exception ex) {
        WriteLine("Error:" + ex.Message);
      }
      await YAPI.FreeAPI();
      return 0;
    }
  }
}

18.7. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme.

Dans la librairie Universal Windows Platform, le traitement d'erreur est implémenté au moyen d'exceptions. Vous devrez donc intercepter et traiter correctement ces exceptions si vous souhaitez avoir un projet fiable qui ne crashera pas des que vous débrancherez un module.

Les exceptions lancées de la librairie sont toujours de type YAPI_Exception, ce qui permet facilement de les séparer des autres exceptions dans un bloc try{...} catch{...}.

Exemple:


try {
        ....
} catch (YAPI_Exception ex) {
        Debug.WriteLine("Exception from Yoctopuce lib:" + ex.Message);
} catch (Exception ex) {
        Debug.WriteLine("Other exceptions :" + ex.Message);
}

19. Utilisation du Yocto-MaxiKnob en Objective-C

Objective-C est le langage de prédilection pour programmer sous macOS, en raison de son intégration avec le générateur d'interfaces Cocoa. Yoctopuce supporte les versions de XCode supportées par Apple. La librairie Yoctopuce est compatible ARC. Il vous sera donc possible de coder vos projet soit en utilisant la traditionnelle méthode de retain / release, soit en activant l'Automatic Reference Counting.

Les librairies Yoctopuce58 pour Objective-C vous sont fournies au format source dans leur intégralité. Une partie de la librairie de bas-niveau est écrite en C pur sucre, mais vous n'aurez à priori pas besoin d'interagir directement avec elle: tout a été fait pour que l'interaction soit le plus simple possible depuis Objective-C.

Vous allez rapidement vous rendre compte que l'API Objective-C définit beaucoup de fonctions qui retournent des objets. Vous ne devez jamais désallouer ces objets vous-même. Ils seront désalloués automatiquement par l'API à la fin de l'application.

Afin des les garder simples, tous les exemples fournis dans cette documentation sont des applications consoles. Il va de soit que que les fonctionnement des librairies est strictement identiques si vous les intégrez dans une application dotée d'une interface graphique. Vous trouverez sur le blog de Yoctopuce un exemple détaillé59 avec des séquences vidéo montrant comment intégrer les fichiers de la librairie à vos projets.

19.1. Contrôle de la fonction AnButton

Il suffit de quelques lignes de code pour piloter un Yocto-MaxiKnob. Voici le squelette d'un fragment de code Objective-C qui utilise la fonction AnButton.


#import "yocto_api.h"
#import "yocto_anbutton.h"

...
NSError *error;
[YAPI RegisterHub:@"usb": &error]
...
// On récupère l'objet représentant le module (ici connecté en local sur USB)
anbutton = [YAnButton FindAnButton:@"YMXBTN01-123456.anButton1"];

// Pour gérer le hot-plug, on vérifie que le module est là
if([anbutton isOnline])
{
    // Utiliser [anbutton get_calibratedValue]
    ...
}

Voyons maintenant en détail ce que font ces quelques lignes.

yocto_api.h et yocto_anbutton.h

Ces deux fichiers importés permettent d'avoir accès aux fonctions permettant de gérer les modules Yoctopuce. yocto_api.h doit toujours être utilisé, yocto_anbutton.h est nécessaire pour gérer les modules contenant une entrée analogique, comme le Yocto-MaxiKnob.

[YAPI RegisterHub]

La fonction [YAPI RegisterHub] initialise l'API de Yoctopuce en indiquant où les modules doivent être recherchés. Utilisée avec le paramètre @"usb", elle permet de travailler avec les modules connectés localement à la machine. Si l'initialisation se passe mal, cette fonction renverra une valeur différente de YAPI_SUCCESS, et retournera via le paramètre errmsg un explication du problème.

[AnButton FindAnButton]

La fonction [AnButton FindAnButton], permet de retrouver une entrée analogique en fonction du numéro de série de son module hôte et de son nom de fonction. Mais vous pouvez tout aussi bien utiliser des noms logiques que vous auriez préalablement configurés. Imaginons un module Yocto-MaxiKnob avec le numéros de série YMXBTN01-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction anButton1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):


YAnButton *anbutton = [YAnButton FindAnButton:@"YMXBTN01-123456.anButton1"];
YAnButton *anbutton = [YAnButton FindAnButton:@"YMXBTN01-123456.MaFonction"];
YAnButton *anbutton = [YAnButton FindAnButton:@"MonModule.anButton1"];
YAnButton *anbutton = [YAnButton FindAnButton:@"MonModule.MaFonction"];
YAnButton *anbutton = [YAnButton FindAnButton:@"MaFonction"];

[YAnButton FindAnButton] renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler l'entrée analogique.

isOnline

La méthode isOnline de l'objet renvoyé par [YAnButton FindAnButton] permet de savoir si le module correspondant est présent et en état de marche.

La méthode get_isPressed() de l'objet renvoyé par YAnButton.FindAnButton permet de savoir si le bouton correspondant est pressé ou pas. Notez la comparaison avec une constante: la valeur renvoyée est en fait un entier.

La méthode get_currentValue() de l'objet renvoyé par YQuadratureDecoder.FindQuadratureDecoder renvoie la position de l'encodeur.

La méthode pulse() de l'objet renvoyé par YBuzzer.FindBuzzer ou YBuzzer.FirstBuzzer permettent de produire un son à une fréuence donnée. La fonction playNotes du même objet permet de jouer des mélodie simples. La fonction set_volume() sert a changer le volume. Par défaut, le volume du buzzer est à zéro.

Les méthodes set_rgbColor() et set_hslColor() de l'objet renvoyé par YColorLedCluster.FindColorLedCluster permettent de changer la couleur de la LED RGB en spécifiant la couleur dans l'espace RGB ou HSL.

Un exemple réel

Lancez Xcode 4.2 et ouvrez le projet exemple correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-MaxiKnob de la librairie Yoctopuce.

Vous reconnaîtrez dans cet exemple l'utilisation des fonctions expliquées ci-dessus, cette fois utilisées avec le décorum nécessaire à en faire un petit programme d'exemple concret.

#import <Foundation/Foundation.h>
#import "yocto_api.h"
#import "yocto_buzzer.h"
#import "yocto_anbutton.h"
#import "yocto_colorledcluster.h"
#import "yocto_quadraturedecoder.h"

static void usage(void)
{
  NSLog(@"usage: demo <serial_number>");
  NSLog(@"       demo <logical_name>");
  NSLog(@"       demo any (use any discovered device)");
  exit(1);
}

static int notefreq(int note)
{
  return (int) (220.0 * exp(note * log(2) / 12));
}

int main(int argc, const char * argv[])
{
  if (argc < 2) {
    usage();
  }

  @autoreleasepool {
    NSError *error;
    // Setup the API to use local USB devices
    if([YAPI RegisterHub:@"usb" :&error] != YAPI_SUCCESS) {
      NSLog(@"RegisterHub error: %@", [error localizedDescription]);
      return 1;
    }
    NSString *target = [NSString stringWithUTF8String:argv[1]];
    YBuzzer  *buz;
    YColorLedCluster *leds;
    YAnButton *button1;
    YQuadratureDecoder *qd;

    if ([target isEqualToString:@"any"]) {
      buz =  [YBuzzer FirstBuzzer];
      if (buz == NULL) {
        NSLog(@"No module connected (check USB cable)");
        return 1;
      }
    } else {
      buz = [YBuzzer FindBuzzer:target];
    }
    if (![buz isOnline]) {
      NSLog(@"Module not connected (check identification and USB cable)");
    }

    NSString *serial = [[buz module] serialNumber];
    leds       = [YColorLedCluster FindColorLedCluster:[serial stringByAppendingString:
                  @".colorLedCluster"]];
    button1   = [YAnButton FindAnButton:[serial stringByAppendingString:@".anButton1"]];
    qd = [YQuadratureDecoder FindQuadratureDecoder:[serial stringByAppendingString:
          @".quadratureDecoder1"]];

    if (![button1 isOnline] || ![qd isOnline]) {
      NSLog(@"Make sure the Yocto-MaxiKnob is configured with at least one AnButton and One Quadrature decoder.");
      return 1;
    }

    NSLog(@"press a test button, or turn the encoder or hit Ctrl-C");
    int lastPos = (int) [qd get_currentValue];
    [buz set_volume:75];
    while ([button1 isOnline]) {
      if ([button1 isPressed] && (lastPos != 0)) {
        lastPos = 0;
        [qd set_currentValue:0];
        [buz playNotes:@"'E32 C8"];
        [leds set_rgbColor:0 :1 :0x000000];
      } else {
        int p = (int)[qd get_currentValue];
        if (lastPos != p) {
          lastPos = p;
          [buz pulse:notefreq(p) :500];
          [leds set_hslColor:0 :1 :(0x00FF7f | (p % 255) << 16)];
        }
      }
    }
    [YAPI FreeAPI];
  }
  return 0;
}
 

19.2. Contrôle de la partie module

Chaque module peut-être contrôlé d'une manière similaire, vous trouverez ci dessous un simple programme d'exemple affichant les principaux paramètres d'un module et permettant d'activer la balise de localisation.

#import <Foundation/Foundation.h>
#import "yocto_api.h"

static void usage(const char *exe)
{
  NSLog(@"usage: %s <serial or logical name> [ON/OFF]\n", exe);
  exit(1);
}


int main (int argc, const char * argv[])
{
  NSError *error;

  @autoreleasepool {
    // Setup the API to use local USB devices
    if([YAPI RegisterHub:@"usb": &error] != YAPI_SUCCESS) {
      NSLog(@"RegisterHub error: %@", [error localizedDescription]);
      return 1;
    }
    if(argc < 2)
      usage(argv[0]);
    NSString *serial_or_name = [NSString stringWithUTF8String:argv[1]];
    // use serial or logical name
    YModule *module = [YModule FindModule:serial_or_name];
    if ([module isOnline]) {
      if (argc > 2) {
        if (strcmp(argv[2], "ON") == 0)
          [module setBeacon:Y_BEACON_ON];
        else
          [module setBeacon:Y_BEACON_OFF];
      }
      NSLog(@"serial:       %@\n", [module serialNumber]);
      NSLog(@"logical name: %@\n", [module logicalName]);
      NSLog(@"luminosity:   %d\n", [module luminosity]);
      NSLog(@"beacon:       ");
      if ([module beacon] == Y_BEACON_ON)
        NSLog(@"ON\n");
      else
        NSLog(@"OFF\n");
      NSLog(@"upTime:       %ld sec\n", [module upTime] / 1000);
      NSLog(@"USB current:  %d mA\n",  [module usbCurrent]);
      NSLog(@"logs:  %@\n",  [module get_lastLogs]);
    } else {
      NSLog(@"%@ not connected (check identification and USB cable)\n",
            serial_or_name);
    }
    [YAPI FreeAPI];
  }
  return 0;
}
 

Chaque propriété xxx du module peut être lue grâce à une méthode du type get_xxxx, et les propriétés qui se sont pas en lecture seule peuvent être modifiées à l'aide de la méthode set_xxx: Pour plus de détails concernant ces fonctions utilisées, reportez-vous aux chapitre API

Modifications des réglages du module

Lorsque que vous souhaitez modifier les réglages d'un module, il suffit d'appeler la fonction set_xxx: correspondante, cependant cette modification n'a lieu que dans la mémoire vive du module: si le module redémarre, les modifications seront perdues. Pour qu'elle soient mémorisées de manière persistante, il est nécessaire de demander au module de sauvegarder sa configuration courante dans sa mémoire non volatile. Pour cela il faut utiliser la méthode saveToFlash. Inversement il est possible de forcer le module à oublier ses réglages courants en utilisant la méthode revertFromFlash. Ce petit exemple ci-dessous vous permet changer le nom logique d'un module.

#import <Foundation/Foundation.h>
#import "yocto_api.h"

static void usage(const char *exe)
{
  NSLog(@"usage: %s <serial> <newLogicalName>\n", exe);
  exit(1);
}


int main (int argc, const char * argv[])
{
  NSError *error;

  @autoreleasepool {
    // Setup the API to use local USB devices
    if([YAPI RegisterHub:@"usb" :&error] != YAPI_SUCCESS) {
      NSLog(@"RegisterHub error: %@", [error localizedDescription]);
      return 1;
    }

    if(argc < 2)
      usage(argv[0]);

    NSString *serial_or_name = [NSString stringWithUTF8String:argv[1]];
    // use serial or logical name
    YModule *module = [YModule FindModule:serial_or_name];

    if (module.isOnline) {
      if (argc >= 3) {
        NSString *newname =  [NSString stringWithUTF8String:argv[2]];
        if (![YAPI CheckLogicalName:newname]) {
          NSLog(@"Invalid name (%@)\n", newname);
          usage(argv[0]);
        }
        module.logicalName = newname;
        [module saveToFlash];
      }
      NSLog(@"Current name: %@\n", module.logicalName);
    } else {
      NSLog(@"%@ not connected (check identification and USB cable)\n",
            serial_or_name);
    }
    [YAPI FreeAPI];
  }
  return 0;
}
 

Attention, le nombre de cycles d'écriture de la mémoire non volatile du module est limité. Passé cette limite plus rien ne garantit que la sauvegarde des réglages se passera correctement. Cette limite, liée à la technologie employée par le micro-processeur du module se situe aux alentour de 100000 cycles. Pour résumer vous ne pouvez employer la fonction saveToFlash que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

Obtenir la liste des modules connectés se fait à l'aide de la fonction yFirstModule() qui renvoie le premier module trouvé, il suffit ensuite d'appeler la fonction nextModule() de cet objet pour trouver les modules suivants, et ce tant que la réponse n'est pas un NULL. Ci-dessous un petit exemple listant les module connectés

#import <Foundation/Foundation.h>
#import "yocto_api.h"

int main (int argc, const char * argv[])
{
  NSError *error;

  @autoreleasepool {
    // Setup the API to use local USB devices
    if([YAPI RegisterHub:@"usb" :&error] != YAPI_SUCCESS) {
      NSLog(@"RegisterHub error: %@\n", [error localizedDescription]);
      return 1;
    }

    NSLog(@"Device list:\n");

    YModule *module = [YModule FirstModule];
    while (module != nil) {
      NSLog(@"%@ %@", module.serialNumber, module.productName);
      module = [module nextModule];
    }
    [YAPI FreeAPI];
  }
  return 0;
}
 

19.3. Gestion des erreurs

Lorsque vous implémentez un programme qui doit interagir avec des modules USB, vous ne pouvez pas faire abstraction de la gestion des erreurs. Il y aura forcément une occasion où un utilisateur aura débranché le périphérique, soit avant de lancer le programme, soit même en pleine opération. La librairie Yoctopuce est prévue pour vous aider à supporter ce genre de comportements, mais votre code doit néanmoins être fait pour se comporter au mieux pour interpréter les erreurs signalées par la librairie.

La manière la plus simple de contourner le problème est celle que nous avons employé pour les petits exemples précédents de ce chapitre: avant d'accéder à un module, on vérifie qu'il est en ligne avec la méthode isOnline() et on suppose ensuite qu'il va y rester pendant la fraction de seconde nécessaire à exécuter les lignes de code suivantes. Ce n'est pas parfait, mais ça peut suffire dans certains cas. Il faut toutefois être conscient qu'on ne peut pas totalement exclure une erreur se produisant après le isOnline(), qui pourrait faire planter le programme. La seule manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites ci-dessous.

La méthode recommandée par la plupart des langages de programmation pour la gestion des erreurs imprévisibles est l'utilisation d'exceptions. C'est le comportement par défaut de la librairie Yoctopuce. Si une erreur se produit alors qu'on essaie d'accéder à un module, la librairie va lancer une exception. Dans ce cas, de trois choses l'une:

Comme cette dernière situation n'est pas la plus souhaitable, la librairie Yoctopuce offre une autre alternative pour la gestion des erreurs, permettant de faire un programme robuste sans devoir attraper les exceptions à chaque ligne de code. Il suffit d'appeler la fonction YAPI.DisableExceptions() pour commuter la librairie dans un mode où les exceptions de chaque fonction sont systématiquement remplacées par des valeurs de retour particulières, qui peuvent être testées par l'appelant lorsque c'est pertinent. Le nom de la valeur de retour en cas d'erreur pour chaque fonction est systématiquement documenté dans la référence de la librairie. Il suit toujours la même logique: une méthode get_state() retournera une valeur NomDeClasse.STATE_INVALID, une méthode get_currentValue retournera une valeur NomDeClasse.CURRENTVALUE_INVALID, etc. Dans tous les cas, la valeur retournée sera du type attendu, et ne sera pas un pointeur nul qui risquerait de faire crasher votre programme. Au pire, si vous affichez la valeur sans la tester, elle sera hors du cadre attendu pour la valeur retournée. Dans le cas de fonctions qui ne retournent à priori pas d'information, la valeur de retour sera YAPI.SUCCESS si tout va bien, et un code d'erreur différent en cas d'échec.

Quand vous travaillez sans les exceptions, il est possible d'obtenir un code d'erreur et un message expliquant l'origine de l'erreur en le demandant à l'objet qui a retourné une erreur à l'aide des méthodes errType() et errMessage(). Ce sont les même informations qui auraient été associées à l'exception si elles avaient été actives.

20. Utilisation avec des langages non supportés

Les modules Yoctopuce peuvent être contrôlés depuis la plupart des langages de programmation courants. De nouveaux langages sont ajoutés régulièrement en fonction de l'intérêt exprimé par les utilisateurs de produits Yoctopuce. Cependant, certains langages ne sont pas et ne seront jamais supportés par Yoctopuce, les raisons peuvent être diverses: compilateurs plus disponibles, environnements inadaptés, etc...

Il existe cependant des méthodes alternatives pour accéder à des modules Yoctopuce depuis un langage de programmation non supporté.

20.1. Utilisation en ligne de commande

Le moyen le plus simple pour contrôler des modules Yoctopuce depuis un langage non supporté consiste à utiliser l'API en ligne de commande à travers des appels système. L'API en ligne de commande se présente en effet sous la forme d'un ensemble de petits exécutables qu'il est facile d'appeler et dont la sortie est facile à analyser. La plupart des langages de programmation permettant d'effectuer des appels système, cela permet de résoudre le problème en quelques lignes.

Cependant, si l'API en ligne de commande est la solution la plus facile, ce n'est pas la plus rapide ni la plus efficace. A chaque appel, l'exécutable devra initialiser sa propre API et faire l'inventaire des modules USB connectés. Il faut compter environ une seconde par appel.

20.2. Assembly .NET

Un Assembly .NET permet de partager un ensemble de classes précompilées pour offrir un service, en annonçant des points d'entrées qui peuvent être utilisés par des applications tierces. Dans notre cas, c'est toute la librairie Yoctopuce qui est disponible dans l'Assembly .NET, de sorte à pouvoir être utilisée dans n'importe quel environnement qui supporte le chargement dynamique d'Assembly .NET.

La librairie Yoctopuce sous forme d'Assembly .NET ne contient pas uniquement la librairie Yoctopuce standard pour C#, car cela n'aurait pas permis une utilisation optimale dans tous les environnements. En effet, on ne peut pas attendre forcément des applications hôtes d'offrir un système de threads ou de callbacks, pourtant très utiles pour la gestion du plug-and-play et des capteurs à taux de rafraîchissements élevé. De même, on ne peut pas attendre des applications externes un comportement transparent dans le cas où un appel de fonction dans l'Assembly cause un délai en raison de communication réseau.

Nous y avons donc ajouté une surcouche, appelée librairie .NET Proxy. Cette surcouche offre une interface très similaire à la librairie standard mais un peu simplifiée, car elle gère en interne tous les mécanismes de callbacks. A la place, cette librairie offre des objets miroirs, appelés Proxys, qui publient par le biais de Propriétés les principaux attributs des fonctions Yoctopuce tels que la mesure courante, les paramètres de configuration, l'état, etc.


Architecture de l'Assembly .NET

Les propriétés des objets Proxys sont automatiquement mises à jour en tâche de fond par le mécanisme de callbacks, sans que l'application hôte n'ait à s'en soucier. Celle-ci peut donc à tout moment et sans aucun risque de latence afficher la valeur de toutes les propriétés des objets Proxys Yoctopuce.

Notez bien que la librairie de communication de bas niveau yapi.dll n'est pas inclue dans l'Assembly .NET. Il faut donc bien penser à la garder toujours avec DotNetProxyLibrary.dll. La version 32 bits doit être dans le même répertoire que DotNetProxyLibrary.dll, tandis que la version 64 bits doit être dans un sous-répertoire nommé amd64.

Exemple d'utilisation avec MATLAB

Voici comment charger notre Assembly .NET Proxy dans MATLAB et lire la valeur du premier capteur branché par USB trouvé sur la machine :


NET.addAssembly("C:/Yoctopuce/DotNetProxyLibrary.dll");
import YoctoProxyAPI.*

errmsg = YAPIProxy.RegisterHub("usb");
sensor = YSensorProxy.FindSensor("");
measure = sprintf('%.3f %s', sensor.CurrentValue, sensor.Unit);

Exemple d'utilisation en PowerShell

Les commandes en PowerShell sont un peu plus étranges, mais on reconnaît le même schéma :


Add-Type -Path "C:/Yoctopuce/DotNetProxyLibrary.dll"

$errmsg = [YoctoProxyAPI.YAPIProxy]::RegisterHub("usb")
$sensor = [YoctoProxyAPI.YSensorProxy]::FindSensor("")
$measure = "{0:n3} {1}" -f $sensor.CurrentValue, $sensor.Unit

Particularités de la librairie .NET Proxy

Par rapport aux librairies Yoctopuce classiques, on notera en particulier les différences suivantes.

Pas de méthode FirstModule/nextModule

Pour obtenir un objet se référant au premier module trouvé, on appelle un YModuleProxy.FindModule(""). Si aucun module n'est connecté, cette méthode retournera un objet avec la propriété module.IsOnline à False. Dès le branchement d'un module, la propriété passera à True et l'identifiant matériel du module sera mis à jour.

Pour énumérer les modules, on peut appeler la méthode module.GetSimilarFunctions() qui retourne un tableau de chaînes de caractères contenant les identifiants de tous les module trouvés.

Pas de fonctions de callback

Les fonctions de callback sont implémentées en interne et mettent à jour les propriétés des objets. Vous pouvez donc simplement faire du polling sur les propriétés, sans pénalité significative de performance. Prenez garde au fait que si vous utilisez l'une des méthodes qui désactive les callbacks, le rafraichissement automatique des propriétés des objets en sera altéré.

Une nouvelle méthode YAPIProxy.GetLog permet de récupérer les logs de diagnostiques de bas niveau sans recourir à l'utilisation de callbacks.

Types énumérés

Pour maximiser la compatibilité avec les applications hôte, la librairie .NET Proxy n'utilise pas de véritables types énumérés .NET, mais des simples entiers. Pour chaque type énuméré, la librairie publie des constantes entières nommées correspondant aux valeurs possibles. Contrairement aux librairies Yoctopuce classiques, les valeurs utiles commencent toujours à 1, la valeur 0 étant réservée pour signifier une valeur invalide, par exemple lorsque le module est débranché.

Valeurs numériques invalides

Pour toutes les grandeurs numériques, plutôt qu'une constante arbitraire, la valeur invalide retournée en cas d'erreur est NaN. Il faut donc utiliser la fonction isNaN() pour détecter cette valeur.

Utilisation de l'Assembly .NET sans la librairie Proxy

Si pour une raison ou une autre vous ne désirez pas utiliser la librairie Proxy, et que votre environnement le permet, vous pouvez utiliser l'API C# standard puisqu'elle se trouve dans l'Assembly, sous le namespace YoctoLib. Attention toutefois à ne pas mélanger les deux utilisations: soit vous passez par la librairie Proxy, soit vous utilisez directement la version YoctoLib, mais pas les deux !

Compatibilité

Pour que la librairie .NET Proxy fonctionne correctement avec vos modules Yoctopuce, ces derniers doivent avoir au moins le firmware 37120.

Afin d'être compatible avec un maximum de version de Windows, y compris Windows XP, la librairie DotNetProxyLibrary.dll est compilée en .NET 3.5, qui est disponible par défaut sur toutes les versions de Windows depuis XP. A ce jour nous n'avons pas trouvé d'environnement hormis Windows qui supporte le chargement d'Assemblys, donc seules les dll de bas niveau pour Windows sont distribuées avec l'Assembly.

20.3. Virtual Hub et HTTP GET

Le Virtual Hub est disponible pour presque toutes les plateformes actuelles, il sert généralement de passerelle pour permettre l'accès aux modules Yoctopuce depuis des langages qui interdisent l'accès direct aux couches matérielles d'un ordinateur (Javascript, PHP, Java...).

Il se trouve que le Virtual Hub est en fait un petit serveur Web qui est capable de router des requêtes HTTP vers les modules Yoctopuce. Ce qui signifie que si vous pouvez faire une requête HTTP depuis votre langage de programmation, vous pouvez contrôler des modules Yoctopuce, même si ce langage n'est pas officiellement supporté.

Interface REST

A bas niveau, les modules sont pilotés à l'aide d'une API REST. Ainsi pour contrôler un module, il suffit de faire les requêtes HTTP appropriées sur le Virtual Hub. Par défaut le port HTTP du Virtual Hub est 4444.

Un des gros avantages de cette technique est que les tests préliminaires sont très faciles à mettre en œuvre, il suffit d'un Virtual Hub et d'un simple browser Web. Ainsi, si vous copiez l'URL suivante dans votre browser favori, alors que le Virtual Hub est en train de tourner, vous obtiendrez la liste des modules présents.


http://127.0.0.1:4444/api/services/whitePages.txt

Remarquez que le résultat est présenté sous forme texte, mais en demandant whitePages.xml vous auriez obtenu le résultat en XML. De même, whitePages.json aurait permis d'obtenir le résultat en JSON. L'extension html vous permet même d'afficher une interface sommaire vous permettant de changer les valeurs en direct. Toute l'API REST est disponible dans ces différents formats.

Contrôle d'un module par l'interface REST

Chaque module Yoctopuce a sa propre interface REST disponible sous différentes formes. Imaginons un Yocto-MaxiKnob avec le numéro de de série YMXBTN01-12345 et le nom logique monModule. l'URL suivante permettra de connaître l'état du module.


http://127.0.0.1:4444/bySerial/YMXBTN01-12345/api/module.txt

Il est bien entendu possible d'utiliser le nom logique des modules plutôt que leur numéro de série.


http://127.0.0.1:4444/byName/monModule/api/module.txt

Vous pouvez retrouver la valeur d'une des propriétés d'un module, il suffit d'ajouter le nom de la propriété en dessous de module. Par exemple, si vous souhaitez connaître la luminosité des LEDs de signalisation, il vous suffit de faire la requête suivante:


http://127.0.0.1:4444/bySerial/YMXBTN01-12345/api/module/luminosity

Pour modifier la valeur d'une propriété, il vous suffit de modifier l'attribut correspondant. Ainsi, pour modifier la luminosité il vous suffit de faire la requête suivante:


http://127.0.0.1:4444/bySerial/YMXBTN01-12345/api/module?luminosity=100

Contrôle des différentes fonctions du module par l'interface REST

Les fonctionnalités des modules se manipulent de la même manière. Pour connaître l'état de la fonction anButton1, il suffit de construire l'URL suivante.


http://127.0.0.1:4444/bySerial/YMXBTN01-12345/api/anButton1.txt

En revanche, si vous pouvez utiliser le nom logique du module en lieu et place de son numéro de série, vous ne pouvez pas utiliser les noms logiques des fonctions, seuls les noms hardware sont autorisés pour les fonctions.

Vous pouvez retrouver un attribut d'une fonction d'un module d'une manière assez similaire à celle utilisée avec les modules, par exemple:


http://127.0.0.1:4444/bySerial/YMXBTN01-12345/api/anButton1/logicalName

Assez logiquement, les attributs peuvent être modifiés de la même manière.


http://127.0.0.1:4444/bySerial/YMXBTN01-12345/api/anButton1?logicalName=maFonction

Vous trouverez la liste des attributs disponibles pour votre Yocto-MaxiKnob au début du chapitre Programmation, concepts généraux.

Accès aux données enregistrées sur le datalogger par l'interface REST

Cette section s'applique uniquement aux modules dotés d'un enregistreur de donnée.

La version résumée des données enregistrées dans le datalogger peut être obtenue au format JSON à l'aide de l'URL suivante:


http://127.0.0.1:4444/bySerial/YMXBTN01-12345/dataLogger.json

Le détail de chaque mesure pour un chaque tranche d'enregistrement peut être obtenu en ajoutant à l'URL l'identifiant de la fonction désirée et l'heure de départ de la tranche:


http://127.0.0.1:4444/bySerial/YMXBTN01-12345/dataLogger.json?id=anButton1&utc=1389801080

20.4. Utilisation des librairies dynamiques

L'API Yoctopuce bas niveau est disponible sous différents formats de librairie dynamiques écrites en C, dont les sources sont disponibles avec l'API C++. Utiliser une de ces librairies bas niveau vous permettra de vous passer du Virtual Hub.

FilenamePlateforme
libyapi.dylibMax OS X
libyapi-amd64.soLinux Intel (64 bits)
libyapi-armel.soLinux ARM EL (32 bits)
libyapi-armhf.soLinux ARM HL (32 bits)
libyapi-aarch64.soLinux ARM (64 bits)
libyapi-i386.soLinux Intel (32 bits)
yapi64.dllWindows (64 bits)
yapi.dllWindows (32 bits)

Ces librairies dynamiques contiennent toutes les fonctionnalités nécessaires pour reconstruire entièrement toute l'API haut niveau dans n'importe quel langage capable d'intégrer ces librairies. Ce chapitre se limite cependant à décrire une utilisation de base des modules.

Contrôle d'un module

Les trois fonctions essentielles de l'API bas niveau sont les suivantes:


int yapiInitAPI(int connection_type, char *errmsg);
int yapiUpdateDeviceList(int forceupdate, char *errmsg);
int yapiHTTPRequest(char *device, char *request, char* buffer,int buffsize,int *fullsize, char *errmsg);

La fonction yapiInitAPI permet d'initialiser l'API et doit être appelée une fois en début du programme. Pour une connection de type USB, le paramètre connection_type doit prendre la valeur 1. errmsg est un pointeur sur un buffer de 255 caractères destiné à récupérer un éventuel message d'erreur. Ce pointeur peut être aussi mis à NULL. La fonction retourne un entier négatif en cas d'erreur, ou zéro dans le cas contraire.

La fonction yapiUpdateDeviceList gère l'inventaire des modules Yoctopuce connectés, elle doit être appelée au moins une fois. Pour pouvoir gérer le hot plug, et détecter d'éventuels nouveaux modules connectés, cette fonction devra être apellée à intervalles réguliers. Le paramètre forceupdate devra être à la valeur 1 pour forcer un scan matériel. Le paramètre errmsg devra pointer sur un buffer de 255 caractères pour récupérer un éventuel message d'erreur. Ce pointeur peut aussi être à null.Cette fonction retourne un entier négatif en cas d'erreur, ou zéro dans le cas contraire.

Enfin, la fonction yapiHTTPRequest permet d'envoyer des requêtes HTTP à l'API REST du module. Le paramètre device devra contenir le numéro de série ou le nom logique du module que vous cherchez à atteindre. Le paramètre request doit contenir la requête HTTP complète (y compris les sauts de ligne terminaux). buffer doit pointer sur un buffer de caractères suffisamment grand pour contenir la réponse. buffsize doit contenir la taille du buffer. fullsize est un pointeur sur un entier qui sera affecté à la taille effective de la réponse. Le paramètre errmsg devra pointer sur un buffer de 255 caractères pour récupérer un éventuel message d'erreur. Ce pointeur peut aussi être à null. Cette fonction retourne un entier négatif en cas d'erreur, ou zéro dans le cas contraire.

Le format des requêtes est le même que celui décrit dans la section Virtual Hub et HTTP GET. Toutes les chaînes de caractères utilisées par l'API sont des chaînes constituées de caractères 8 bits: l'Unicode et l'UTF8 ne sont pas supportés.

Le résultat retourné dans la variable buffer respecte le protocole HTTP, il inclut donc un header HTTP . Ce header se termine par deux lignes vides, c'est-à-dire une séquence de quatre caractères ASCII 13, 10, 13, 10.

Voici un programme d'exemple écrit en pascal qui utilise la DLL yapi.dll pour lire puis changer la luminosité d'un module.


// Dll functions import
function  yapiInitAPI(mode:integer;
                      errmsg : pansichar):integer;cdecl;
                      external 'yapi.dll' name 'yapiInitAPI';
function  yapiUpdateDeviceList(force:integer;errmsg : pansichar):integer;cdecl;
                      external 'yapi.dll' name 'yapiUpdateDeviceList';
function  yapiHTTPRequest(device:pansichar;url:pansichar; buffer:pansichar;
                      buffsize:integer;var fullsize:integer;
                      errmsg : pansichar):integer;cdecl;
                      external 'yapi.dll' name 'yapiHTTPRequest';

var
 errmsgBuffer  : array [0..256] of ansichar;
 dataBuffer    : array [0..1024] of ansichar;
 errmsg,data   : pansichar;
 fullsize,p    : integer;

const
  serial      = 'YMXBTN01-12345';
  getValue = 'GET /api/module/luminosity HTTP/1.1'#13#10#13#10;
  setValue = 'GET /api/module?luminosity=100 HTTP/1.1'#13#10#13#10;

begin
  errmsg  :=  @errmsgBuffer;
  data    :=  @dataBuffer;
  // API  initialization
  if(yapiInitAPI(1,errmsg)<0) then
   begin
    writeln(errmsg);
    halt;
  end;

  // forces a device inventory
  if( yapiUpdateDeviceList(1,errmsg)<0) then
    begin
     writeln(errmsg);
     halt;
   end;

  // requests the  module luminosity
  if (yapiHTTPRequest(serial,getValue,data,sizeof(dataBuffer),fullsize,errmsg)<0) then
   begin
     writeln(errmsg);
     halt;
   end;

  // searches for the HTTP header end
  p := pos(#13#10#13#10,data);

  // displays the response minus the HTTP header
  writeln(copy(data,p+4,length(data)-p-3));

  // change the luminosity
  if (yapiHTTPRequest(serial,setValue,data,sizeof(dataBuffer),fullsize,errmsg)<0) then
   begin
     writeln(errmsg);
     halt;
   end;

end.

Inventaire des modules

Pour procéder à l'inventaire des modules Yoctopuce, deux fonctions de la librairie dynamique sont nécessaires


 int yapiGetAllDevices(int *buffer,int maxsize,int *neededsize,char *errmsg);
 int yapiGetDeviceInfo(int devdesc,yDeviceSt *infos, char *errmsg);

La fonction yapiGetAllDevices permet d'obtenir la liste des modules connectés sous la forme d'une liste de handles. buffer pointe sur un tableau d'entiers 32 bits qui contiendra les handles retournés. Maxsize est la taille en bytes du buffer. neededsize contiendra au retour la taille nécessaire pour stocker tous les handles. Cela permet d'en déduire le nombre de module connectés, ou si le buffer passé en entrée est trop petit. Le paramètre errmsg devra pointer sur un buffer de 255 caractères pour récupérer un éventuel message d'erreur. Ce pointeur peut aussi être à null. Cette fonction retourne un entier négatif en cas d'erreur, ou zéro dans le cas contraire.

La fonction yapiGetDeviceInfo permet de récupérer les informations relatives à un module à partir de son handle. devdesc est un entier 32bit qui représente le module, et qui a été obtenu grâce à yapiGetAllDevices. infos pointe sur une structure de données dans laquelle sera stocké le résultat. Le format de cette structure est le suivant:

Nom TypeTaille (bytes)Description
vendorid int4ID USB de Yoctopuce
deviceid int4ID USB du module
devrelease int4Version du module
nbinbterfaces int4Nombre d'interfaces USB utilisée par le module
manufacturer char[]20Yoctopuce (null terminé)
productname char[]28Modèle (null terminé)
serial char[]20Numéro de série (null terminé)
logicalname char[]20Nom logique (null terminé)
firmware char[]22Version du firmware (null terminé)
beacon byte1Etat de la balise de localisation (0/1)

Le paramètre errmsg devra pointer sur un buffer de 255 caractères pour récupérer un éventuel message d'erreur.

Voici un programme d'exemple écrit en pascal qui utilise la DLL yapi.dll pour lister les modules connectés.


// device description structure
type yDeviceSt = packed record
   vendorid        : word;
   deviceid        : word;
   devrelease      : word;
   nbinbterfaces   : word;
   manufacturer    : array [0..19] of ansichar;
   productname     : array [0..27] of ansichar;
   serial          : array [0..19] of ansichar;
   logicalname     : array [0..19] of ansichar;
   firmware        : array [0..21] of ansichar;
   beacon          : byte;
 end;

// Dll function import
function  yapiInitAPI(mode:integer;
                      errmsg : pansichar):integer;cdecl;
                      external 'yapi.dll' name 'yapiInitAPI';

function  yapiUpdateDeviceList(force:integer;errmsg : pansichar):integer;cdecl;
                      external 'yapi.dll' name 'yapiUpdateDeviceList';

function  yapiGetAllDevices( buffer:pointer;
                             maxsize:integer;
                             var neededsize:integer;
                             errmsg : pansichar):integer; cdecl;
                             external 'yapi.dll' name 'yapiGetAllDevices';

function  apiGetDeviceInfo(d:integer; var infos:yDeviceSt;
                             errmsg : pansichar):integer;  cdecl;
                             external 'yapi.dll' name 'yapiGetDeviceInfo';


var
 errmsgBuffer  : array [0..256] of ansichar;
 dataBuffer    : array [0..127] of integer;   // max of 128 USB devices
 errmsg,data   : pansichar;
 neededsize,i  : integer;
 devinfos      : yDeviceSt;

begin
  errmsg  :=  @errmsgBuffer;

  // API  initialisation
  if(yapiInitAPI(1,errmsg)<0) then
   begin
    writeln(errmsg);
    halt;
  end;

   // forces a device inventory
  if( yapiUpdateDeviceList(1,errmsg)<0) then
    begin
     writeln(errmsg);
     halt;
   end;

  // loads all device handles into dataBuffer
  if yapiGetAllDevices(@dataBuffer,sizeof(dataBuffer),neededsize,errmsg)<0 then
    begin
     writeln(errmsg);
     halt;
    end;

  // gets device info from each handle
  for i:=0 to  neededsize div sizeof(integer)-1 do
   begin
     if (apiGetDeviceInfo(dataBuffer[i], devinfos, errmsg)<0) then
       begin
         writeln(errmsg);
         halt;
       end;
     writeln(pansichar(@devinfos.serial)+' ('+pansichar(@devinfos.productname)+')');
   end;

end.

VB6 et yapi.dll

Chaque point d'entrée de la DLL yapi.dll est disponible en deux versions, une classique C-decl, et un seconde compatible avec Visual Basic 6 préfixée avec vb6_.

20.5. Port de la librairie haut niveau

Toutes les sources de l'API Yoctopuce étant fournies dans leur intégralité, vous pouvez parfaitement entreprendre le port complet de l'API dans le langage de votre choix. Sachez cependant qu'une grande partie du code source de l'API est généré automatiquement.

Ainsi, il n'est pas nécessaire de porter la totalité de l'API, il suffit de porter le fichier yocto_api et un de ceux correspondant à une fonctionnalité, par exemple yocto_relay. Moyennant un peu de travail supplémentaire, Yoctopuce sera alors en mesure de générer tous les autres fichiers. C'est pourquoi il est fortement recommandé de contacter le support Yoctopuce avant d'entreprendre le port de la librairie Yoctopuce dans un autre langage. Un travail collaboratif sera profitable aux deux parties.

21. Programmation avancée

Les chapitres précédents vous ont présenté dans chaque language disponible les fonctions de programmation de base utilisables avec votre module Yocto-MaxiKnob. Ce chapitre présente de façon plus générale une utilisation plus avancée de votre module. Les exemples sont donnés dans le language le plus populaire auprès des clients de Yoctopuce, à savoir C#. Néanmoins, vous trouverez dans les librairies de programmation pour chaque language des exemples complets illustrant les concepts présentés ici.

Afin de rester le plus concis possible, les exemples donnés dans ce chapitre ne font aucune gestion d'erreur. Ne les copiez pas tels-quels dans une application de production.

21.1. Programmation par événements

Les méthodes de gestion des modules Yoctopuce qui vous ont été présentées dans les chapitres précédents sont des fonctions de polling, qui consistent à demander en permanence à l'API si quelque chose a changé. Facile à appréhender, cette technique de programmation est n'est pas la plus efficace ni la plus réactive. C'est pourquoi l'API de programmation Yoctopuce propose aussi un modèle de programmation par événements. Cette technique consiste à demander à l'API de signaler elle-même les changements importants dès qu'ils sont détectés. A chaque fois qu'un paramètre clé change, l'API appelle une fonction de callback que vous avez prédéfinie.

Détecter l'arrivée et le départ des modules

La gestion du hot-plug est importante lorsque l'on travaille avec des modules USB, car tôt ou tard vous serez amené à brancher et débrancher un module après le lancement de votre programme. L'API a été conçue pour gérer l'arrivée et le départ inopinés des modules de manière transparente, mais votre application doit en général en tenir compte si elle veut éviter de prétendre utiliser un module qui a été débranché.

La programmation par événements est particulièrement utile pour détecter les branchements/débranchements de modules. Il est en effet plus simple de se faire signaler les branchements, que de devoir lister en permanence les modules branchés pour en déduire ceux qui sont arrivés et ceux qui sont partis. Pour pouvoir être prévenu dès qu'un module arrive, vous avez besoin de trois morceaux de code.

Le callback

Le callback est la fonction qui sera appelée à chaque fois qu'un nouveau module Yoctopuce sera branché. Elle prend en paramètre le module concerné.


 static void deviceArrival(YModule m)
 {
     Console.WriteLine("Nouveau module  : " + m.get_serialNumber());
 }

L'initialisation

Vous devez ensuite signaler à l'API qu'il faut appeler votre callback quand un nouveau module est branché.


  YAPI.RegisterDeviceArrivalCallback(deviceArrival);

Notez que si des modules sont déjà branchés lorsque le callback est enregistré, le callback sera appelé pour chacun de ces modules déjà branchés.

Déclenchement des callbacks

Un problème classique de la programmation par callbacks est que ces callbacks peuvent être appelés n'importe quand, y compris à des moments où le programme principal n'est pas prêt à les recevoir, ce qui peut avoir des effets de bords indésirables comme des dead-locks et autres conditions de course. C'est pourquoi dans l'API Yoctopuce, les callbacks d'arrivée/départs de modules ne sont appelés que pendant l'exécution de la fonction UpdateDeviceList(). Il vous suffit d'appeler UpdateDeviceList() à intervalle régulier depuis un timer ou un thread spécifique pour controller précisément quand les appels à ces callbacks auront lieu:


// boucle d'attente gérant les callback
while (true)
{  
    // callback d'arrivée / départ de modules
    YAPI.UpdateDeviceList(ref errmsg);
    // attente non active gérant les autres callbacks
    YAPI.Sleep(500, ref errmsg);
}

De manière similaire, il est possible d'avoir un callback quand un module est débranché. Vous trouverez un exemple concret démontrant toutes ces techniques dans la librairie de programmation Yoctopuce de chaque langage. L'exemple se trouve dans le répertoire Examples/Prog-EventBased.

Attention: dans la plupart des langages, les callbacks doivent être des procédures globales, et non pas des méthodes. Si vous souhaitez que le callback appelle une méthode d'un objet, définissez votre callback sous la forme d'une procédure globale qui ensuite appellera votre méthode.

22. Mise à jour du firmware

Il existe plusieurs moyens de mettre à jour le firmware des modules Yoctopuce.

22.1. Le VirtualHub ou le YoctoHub

Il est possible de mettre à jour un module directement depuis l'interface web du VirutalHub ou du YoctoHub. Il suffit d'accéder à la fenêtre de configuration du module que à mettre à jour et de cliquer sur le bouton "upgrade". Le VirtualHub démarre un assistant qui vous guidera durant la procédure de mise à jour.

Si pour une raison ou une autre, la mise à jour venait à échouer et que le module de fonctionnait plus, débranchez puis rebranchez le module en maintenant sur le Yocto-bouton appuyé. Le module va démarrer en mode "mise à jour" et sera listé en dessous des modules connectés.

22.2. La librairie ligne de commandes

Tous les outils en lignes de commandes ont la possibilité de mettre à jour les modules Yoctopuce grâce à la commande downloadAndUpdate. Le mécanisme de sélection des modules fonctionne comme pour une commande traditionnelle. La [cible] est le nom du module qui va être mis à jour. Vous pouvez aussi utiliser les alias "any" ou "all", ou encore une liste de noms, séparés par des virgules, sans espace.


C:\>Executable [options] [cible] commande [paramètres]

L'exemple suivant met à jour tous les modules Yoctopuce connectés en USB.


C:\>YModule all downloadAndUpdate
ok: Yocto-PowerRelay RELAYHI1-266C8(rev=15430) is up to date.
ok: 0 / 0 hubs in 0.000000s.
ok: 0 / 0 shields in 0.000000s.
ok: 1 / 1 devices in 0.130000s 0.130000s per device.
ok: All devices are now up to date.
C:\>

22.3. L'application Android Yocto-Firmware

Il est possible de mettre à jour le firmware de vos modules depuis votre téléphone ou tablette Android avec l'application Yocto-Firmware. Cette application liste tous les modules Yoctopuce branchés en USB et vérifie si un firmware plus récent est disponible sur www.yoctopuce.com. Si un firmware plus récent est disponible, il est possible de mettre à jour le module. L'application se charge de télécharger et d'installer le nouveau firmware en préservant les paramètres du module.

Attention, pendant la mise à jour du firmware, le module redémarre plusieurs fois. Android interprète le reboot d'un périphérique USB comme une déconnexion et reconnexion du périphérique USB, et demande à nouveau l'autorisation d'utiliser le port USB. L'utilisateur est obligé de cliquer sur OK pour que la procédure de mise à jour se termine correctement.

22.4. La librairie de programmation

Si vous avez besoin d'intégrer la mise à jour de firmware dans votre application, les librairies proposent une API pour mettre à jour vos modules.

Sauvegarder et restaurer les paramètres

La méthode get_allSettings() retourne un buffer binaire qui permet de sauvegarder les paramètres persistants d'un module. Cette fonction est très utile pour sauvegarder la configuration réseau d'un YoctoHub par exemple.


YWireless wireless = YWireless.FindWireless("reference");
YModule m = wireless.get_module();
byte[] default_config =  m.get_allSettings();
saveFile("default.bin", default_config);
...

Ces paramètres peuvent être appliqués sur d'autres modules à l'aide de la méthode set_allSettings().


byte[] default_config = loadFile("default.bin");
YModule m = YModule.FirstModule();
while (m != null) {
  if (m.get_productName() == "YoctoHub-Wireless") {
    m.set_allSettings(default_config);
  }
  m = m.next();
}

Chercher le bon firmware

La première étape pour mettre à jour un module Yoctopuce est de trouver quel firmware il faut utiliser, c'est le travail de la méthode checkFirmware(path, onlynew) de l'objet YModule. Cette méthode vérifie que le firmware passé en argument (path) est compatible avec le module. Si le paramètre onlynew est vrai, cette méthode vérifie si le firmware est plus récent que la version qui est actuellement utilisée par le module. Quand le fichier n'est pas compatible (ou si le fichier est plus vieux que la version installée), cette méthode retourne une chaîne vide. Si au contraire le fichier est valide, la méthode retourne le chemin d'accès d'un fichier.

Le code suivant vérifie si le fichier c:\tmp\METEOMK1.17328.byn est compatible avec le module stocké dans la variable m.


YModule m = YModule.FirstModule();
...
...
string path = "c:\\tmp\METEOMK1.17328.byn";
string newfirm = m.checkFirmware(path, false);
if (newfirm != "") {
  Console.WriteLine("firmware " + newfirm + " is compatible");
}
...

Il est possible de passer un répertoire en argument (au lieu d'un fichier). Dans ce cas la méthode va parcourir récursivement tous les fichiers du répertoire et retourner le firmware compatible le plus récent. Le code suivant vérifie s'il existe un firmware plus récent dans le répertoire c:\tmp\.


YModule m = YModule.FirstModule();
...
...
string path = "c:\\tmp";
string newfirm = m.checkFirmware(path, true);
if (newfirm != "") {
  Console.WriteLine("firmware " + newfirm + " is compatible and newer");
}
...

Il est aussi possible de passer la chaîne "www.yoctopuce.com" en argument pour vérifier s'il existe un firmware plus récent publié sur le site web de Yoctopuce. Dans ce cas, la méthode retournera l'URL du firmware. Vous pourrez soit utiliser cette URL pour télécharger le firmware sur votre disque, soit utiliser cette URL lors de la mise à jour du firmware (voir ci-dessous). Bien évidemment, cette possibilité ne fonctionne que si votre machine est reliée à Internet.


YModule m = YModule.FirstModule();
...
...
string url = m.checkFirmware("www.yoctopuce.com", true);
if (url != "") {
  Console.WriteLine("new firmware is available at " + url );
}
...

Mettre à jour le firmware

La mise à jour du firmware peut prendre plusieurs minutes, c'est pourquoi le processus de mise à jour est exécuté par la librairie en arrière plan et est contrôlé par le code utilisateur à l'aide de la classe YFirmwareUdpate.

Pour mettre à jour un module Yoctopuce, il faut obtenir une instance de la classe YFirmwareUpdate à l'aide de la méthode updateFirmware d'un objet YModule. Le seul paramètre de cette méthode est le path du firmware à installer. Cette méthode ne démarre pas immédiatement la mise à jour, mais retourne un objet YFirmwareUpdate configuré pour mettre à jour le module.


string newfirm = m.checkFirmware("www.yoctopuce.com", true);
.....
YFirmwareUpdate fw_update = m.updateFirmware(newfirm);

La méthode startUpdate() démarre la mise à jour en arrière plan. Ce processus en arrière plan se charge automatiquement de:

  1. sauvegarder des paramètres du module,
  2. redémarrer le module en mode "mise à jour"
  3. mettre à jour le firmware
  4. démarrer le module avec la nouvelle version du firmware
  5. restaurer les paramètres

Les méthodes get_progress() et get_progressMessage() permettent de suivre la progression de la mise à jour. get_progress()retourne la progression sous forme de pourcentage (100 = mise à jour terminée). get_progressMessage() retourne une chaîne de caractères décrivant l'opération en cours (effacement, écriture, reboot,...). Si la méthode get_progress() retourne une valeur négative, c'est que le processus de mise à jour à échoué. Dans ce cas la méthode get_progressMessage() retourne le message d'erreur.

Le code suivant démarre la mise à jour et affiche la progression sur la sortie standard.


YFirmwareUpdate fw_update = m.updateFirmware(newfirm);
....
int status = fw_update.startUpdate();
while (status < 100 && status >= 0) {
  int newstatus = fw_update.get_progress();
  if (newstatus != status) {
    Console.WriteLine(status + "% "
      + fw_update.get_progressMessage());
  }
  YAPI.Sleep(500, ref errmsg);
  status = newstatus;
}

if (status < 0) {
  Console.WriteLine("Firmware Update failed: "
    + fw_update.get_progressMessage());
} else {
  Console.WriteLine("Firmware Updated Successfully!");
}

Particularité d'Android

Il est possible de mettre à jour un firmware d'un module en utilisant la librairie Android. Mais pour les modules branchés en USB, Android va demander à l'utilisateur d'autoriser l'application à accéder au port USB.

Pendant la mise à jour du firmware, le module redémarre plusieurs fois. Android interprète le reboot d'un périphérique USB comme une déconnexion et reconnexion du port USB, et interdit tout accès USB tant que l'utilisateur n'a pas fermé le pop-up. L'utilisateur est obligé de cliquer sur OK pour que la procédure de mise à jour puisse continuer correctement. Il n'est pas possible de mettre à jour un module branché en USB à un appareil Android sans que l'utilisateur ne soit obligé d'interagir avec l'appareil.

22.5. Le mode "mise à jour"

Si vous désirez effacer tous les paramètres du module ou que votre module ne démarre plus correctement, il est possible d'installer un firmware depuis le mode "mise à jour".

Pour forcer le module à fonctionner dans le mode "mis à jour", débranchez-le, attendez quelques secondes, et rebranchez-le en maintenant le Yocto-Bouton appuyé. Cela a pour effet de faire démarrer le module en mode "mise à jour". Ce mode de fonctionnement est protégé contre les corruptions et est toujours accessible.

Dans ce mode, le module n'est plus détecté par les objets YModules. Pour obtenir la liste des modules connectés en mode "mise à jour", il faut utiliser la fonction YAPI.GetAllBootLoaders(). Cette fonction retourne un tableau de chaînes de caractères avec le numéro de série des modules en le mode "mise à jour".


List<string> allBootLoader = YAPI.GetAllBootLoaders();

La procédure de mise à jour est identique au cas standard (voir section précédente), mais il faut instancier manuellement l'objet YFirmwareUpdate au lieu d'appeler module.updateFirmware(). Le constructeur prend en argument trois paramètres: le numéro de série du module, le path du firmware à installer, et un tableau de bytes avec les paramètres à restaurer à la fin de la mise à jour (ou null pour restaurer les paramètres d'origine).


YFirmwareUpdateupdate fw_update;
fw_update = new YFirmwareUpdate(allBootLoader[0], newfirm, null);
int status = fw_update.startUpdate();
.....

23. Référence de l'API de haut niveau

Ce chapitre résume les fonctions de l'API de haut niveau pour commander votre Yocto-MaxiKnob. La syntaxe et les types précis peuvent varier d'un langage à l'autre mais, sauf avis contraire toutes sont disponibles dans chaque language. Pour une information plus précise sur les types des arguments et des valeurs de retour dans un langage donné, veuillez vous référer au fichier de définition pour ce langage (yocto_api.* ainsi que les autres fichiers yocto_* définissant les interfaces des fonctions).

Dans les langages qui supportent les exceptions, toutes ces fonctions vont par défaut générer des exceptions en cas d'erreur plutôt que de retourner la valeur d'erreur documentée pour chaque fonction, afin de faciliter le déboguage. Il est toutefois possible de désactiver l'utilisation d'exceptions à l'aide de la fonction yDisableExceptions(), si l'on préfère travailler avec des valeurs de retour d'erreur.

Ce chapitre ne reprend pas en détail les concepts de programmation décrits plus tôt, afin d'offrir une référence plus concise. En cas de doute, n'hésitez pas à retourner au chapitre décrivant en détail de chaque attribut configurable.

23.1. La classe YAPI

Fonctions générales

Ces quelques fonctions générales permettent l'initialisation et la configuration de la librairie Yoctopuce. Dans la plupart des cas, un appel à yRegisterHub() suffira en tout et pour tout. Ensuite, vous pourrez appeler la fonction globale yFind...() ou yFirst...() correspondant à votre module pour pouvoir interagir avec lui.

Pour utiliser les fonctions décrites ici, vous devez inclure:

java
import com.yoctopuce.YoctoAPI.YAPI;
dnp
import YoctoProxyAPI.YAPIProxy
cp
#include "yocto_api_proxy.h"
ml
import YoctoProxyAPI.YAPIProxy"
js
<script type='text/javascript' src='yocto_api.js'></script>
cpp
#include "yocto_api.h"
m
#import "yocto_api.h"
pas
uses yocto_api;
vb
yocto_api.vb
cs
yocto_api.cs
uwp
import com.yoctopuce.YoctoAPI.YModule;
py
from yocto_api import *
php
require_once('yocto_api.php');
ts
in HTML: import { YAPI, YErrorMsg, YModule, YSensor } from '../../dist/esm/yocto_api_browser.js';
in Node.js: import { YAPI, YErrorMsg, YModule, YSensor } from 'yoctolib-cjs/yocto_api_nodejs.js';
es
in HTML: <script src="../../lib/yocto_api.js"></script>
in node.js: require('yoctolib-es2017/yocto_api.js');
vi
YModule.vi
Fonction globales
YAPI.AddUdevRule(force)

Ajoute une règle UDEV qui autorise tous les utilisateurs à accéder aux modules Yoctopuce connectés sur les ports USB.

YAPI.CheckLogicalName(name)

Vérifie si un nom donné est valide comme nom logique pour un module ou une fonction.

YAPI.ClearHTTPCallbackCacheDir(removeFiles)

Désactive le cache de callback HTTP.

YAPI.DisableExceptions()

Désactive l'utilisation d'exceptions pour la gestion des erreurs.

YAPI.EnableExceptions()

Réactive l'utilisation d'exceptions pour la gestion des erreurs.

YAPI.EnableUSBHost(osContext)

Cette fonction est utilisée uniquement sous Android.

YAPI.FreeAPI()

Attends que toutes les communications en cours avec les modules Yoctopuce soient terminées puis libère les ressources utilisées par la librairie Yoctopuce.

YAPI.GetAPIVersion()

Retourne la version de la librairie Yoctopuce utilisée.

YAPI.GetCacheValidity()

Retourne la durée de validité des données chargée par la libraire.

YAPI.GetDeviceListValidity()

Retourne le délai entre chaque énumération forcée des YoctoHubs utilisés.

YAPI.GetDllArchitecture()

Retourne l'architecture du binaire de la librairie de communication Yoctopuce utilisée.

YAPI.GetDllPath()

Retourne l'emplacement sur le disque des librairies Yoctopuce utilisées.

YAPI.GetLog(lastLogLine)

Récupère les messages de logs de la librairie de communication Yoctopuce.

YAPI.GetNetworkTimeout()

Retourne le délai de connexion réseau pour yRegisterHub() et yUpdateDeviceList().

YAPI.GetTickCount()

Retourne la valeur du compteur monotone de temps (en millisecondes).

YAPI.HandleEvents(errmsg)

Maintient la communication de la librairie avec les modules Yoctopuce.

YAPI.InitAPI(mode, errmsg)

Initialise la librairie de programmation de Yoctopuce explicitement.

YAPI.PreregisterHub(url, errmsg)

Alternative plus tolérante à yRegisterHub().

YAPI.RegisterDeviceArrivalCallback(arrivalCallback)

Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est branché.

YAPI.RegisterDeviceRemovalCallback(removalCallback)

Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est débranché.

YAPI.RegisterHub(url, errmsg)

Configure la librairie Yoctopuce pour utiliser les modules connectés sur une machine donnée.

YAPI.RegisterHubDiscoveryCallback(hubDiscoveryCallback)

Enregistre une fonction de callback qui est appelée chaque fois qu'un hub réseau s'annonce avec un message SSDP.

YAPI.RegisterHubWebsocketCallback(ws, errmsg, authpwd)

Variante de la fonction yRegisterHub() destinée à initialiser l'API Yoctopuce sur une session Websocket existante, dans le cadre d'un callback WebSocket entrant.

YAPI.RegisterLogFunction(logfun)

Enregistre une fonction de callback qui sera appellée à chaque fois que l'API a quelque chose à dire.

YAPI.SelectArchitecture(arch)

Sélectionne manuellement l'architecture de la libraire dynamique à utiliser pour accéder à USB.

YAPI.SetCacheValidity(cacheValidityMs)

Change la durée de validité des données chargées par la librairie.

YAPI.SetDelegate(object)

(Objective-C uniquement) Enregistre un objet délégué qui doit se conformer au protocole YDeviceHotPlug.

YAPI.SetDeviceListValidity(deviceListValidity)

Change le délai entre chaque énumération forcée des YoctoHub utilisés.

YAPI.SetHTTPCallbackCacheDir(directory)

Active le cache du callback HTTP.

YAPI.SetNetworkTimeout(networkMsTimeout)

Change le délai de connexion réseau pour yRegisterHub() et yUpdateDeviceList().

YAPI.SetTimeout(callback, ms_timeout, args)

Appelle le callback spécifié après un temps d'attente spécifié.

YAPI.SetUSBPacketAckMs(pktAckDelay)

Active la quittance des paquets USB reçus par la librairie Yoctopuce.

YAPI.Sleep(ms_duration, errmsg)

Effectue une pause dans l'exécution du programme pour une durée spécifiée.

YAPI.TestHub(url, mstimeout, errmsg)

Test si un hub est joignable.

YAPI.TriggerHubDiscovery(errmsg)

Relance une détection des hubs réseau.

YAPI.UnregisterHub(url)

Configure la librairie Yoctopuce pour ne plus utiliser les modules connectés sur une machine préalablement enregistrer avec RegisterHub.

YAPI.UpdateDeviceList(errmsg)

Force une mise-à-jour de la liste des modules Yoctopuce connectés.

YAPI.UpdateDeviceList_async(callback, context)

Force une mise-à-jour de la liste des modules Yoctopuce connectés.

23.2. La classe YModule

Interface de contrôle des paramètres généraux des modules Yoctopuce

La classe YModule est utilisable avec tous les modules USB de Yoctopuce. Elle permet de contrôler les paramètres généraux du module, et d'énumérer les fonctions fournies par chaque module.

Pour utiliser les fonctions décrites ici, vous devez inclure:

js
<script type='text/javascript' src='yocto_api.js'></script>
cpp
#include "yocto_api.h"
m
#import "yocto_api.h"
pas
uses yocto_api;
vb
yocto_api.vb
cs
yocto_api.cs
java
import com.yoctopuce.YoctoAPI.YModule;
uwp
import com.yoctopuce.YoctoAPI.YModule;
py
from yocto_api import *
php
require_once('yocto_api.php');
ts
in HTML: import { YAPI, YErrorMsg, YModule, YSensor } from '../../dist/esm/yocto_api_browser.js';
in Node.js: import { YAPI, YErrorMsg, YModule, YSensor } from 'yoctolib-cjs/yocto_api_nodejs.js';
es
in HTML: <script src="../../lib/yocto_api.js"></script>
in node.js: require('yoctolib-es2017/yocto_api.js');
dnp
import YoctoProxyAPI.YModuleProxy
cp
#include "yocto_module_proxy.h"
vi
YModule.vi
ml
import YoctoProxyAPI.YModuleProxy"
Fonction globales
YModule.FindModule(func)

Permet de retrouver un module d'après son numéro de série ou son nom logique.

YModule.FindModuleInContext(yctx, func)

Permet de retrouver un module d'après un identifiant donné dans un Context YAPI.

YModule.FirstModule()

Commence l'énumération des modules accessibles par la librairie.

Propriétés des objets YModuleProxy
module→Beacon [modifiable]

état de la balise de localisation.

module→FirmwareRelease [lecture seule]

Version du logiciel embarqué du module.

module→FunctionId [lecture seule]

Identifiant matériel de la nième fonction du module.

module→HardwareId [lecture seule]

Identifiant unique du module.

module→IsOnline [lecture seule]

Vérifie si le module est joignable.

module→LogicalName [modifiable]

Nom logique du module.

module→Luminosity [modifiable]

Luminosité des leds informatives du module (valeur entre 0 et 100).

module→ProductId [lecture seule]

Identifiant USB du module, préprogrammé en usine.

module→ProductName [lecture seule]

Nom commercial du module, préprogrammé en usine.

module→ProductRelease [lecture seule]

Numéro uméro de révision du module hardware, préprogrammé en usine.

module→SerialNumber [lecture seule]

Numéro de série du module, préprogrammé en usine.

Méthodes des objets YModule
module→addFileToHTTPCallback(filename)

Ajoute un fichier aux données uploadées lors du prochain callback HTTP.

module→checkFirmware(path, onlynew)

Teste si le fichier byn est valide pour le module.

module→clearCache()

Invalide le cache.

module→describe()

Retourne un court texte décrivant le module.

module→download(pathname)

Télécharge le fichier choisi du module et retourne son contenu.

module→functionBaseType(functionIndex)

Retourne le type de base de la nième fonction du module.

module→functionCount()

Retourne le nombre de fonctions (sans compter l'interface "module") existant sur le module.