Yoctopuce Yocto-Servo module servo Mode d'emploi
Annonce
Annonce
Yocto-Servo, Mode d'emploi
Table des matières
1. Introduction
..............................................................................................................................
1
..............................................................................................................................
.........................................................................................................
2. Présentation
.............................................................................................................................
5
........................................................................................................
.....................................................................................................
3. Premiers pas
............................................................................................................................
9
...........................................................................................................................
.....................................................................................................................
......................................................................................................................
4. Montage et connectique
.................................................................................................
13
...............................................................................................................................
................................................................................................................................
4.3. Utilisation d'un variateur de modélisme
..............................................................................
4.4. Contraintes d'alimentation par USB
....................................................................................
5. Programmation, concepts généraux
.......................................................................
17
5.1. Paradigme de programmation
............................................................................................
......................................................................................................
5.3. Interface de contrôle du module
.........................................................................................
5.4. Interface de contrôle de l'alimentation
................................................................................
5.5. Interface de la fonction Servo
.............................................................................................
5.6. Quelle interface: Native, DLL ou Service?
..........................................................................
5.7. Programmation, par où commencer?
.................................................................................
6. Utilisation du Yocto-Servo en ligne de commande
.........................................
27
...........................................................................................................................
6.2. Utilisation: description générale
..........................................................................................
6.3. Contrôle de la fonction Servo
.............................................................................................
6.4. Contrôle de la partie module
...............................................................................................
...........................................................................................................................
7. Utilisation du Yocto-Servo en Javascript
..............................................................
31
.........................................................................................................................
7.2. Contrôle de la fonction Servo
.............................................................................................
7.3. Contrôle de la partie module
...............................................................................................
............................................................................................................
8. Utilisation du Yocto-Servo en PHP
...........................................................................
39
.........................................................................................................................
8.2. Contrôle de la fonction Servo
.............................................................................................
8.3. Contrôle de la partie module
...............................................................................................
8.4. API par callback HTTP et filtres NAT
..................................................................................
............................................................................................................
9. Utilisation du Yocto-Servo en C++
............................................................................
49
9.1. Contrôle de la fonction Servo
.............................................................................................
9.2. Contrôle de la partie module
...............................................................................................
............................................................................................................
9.4. Intégration de la librairie Yoctopuce en C++
.......................................................................
10. Utilisation du Yocto-Servo en Objective-C
........................................................
57
10.1. Contrôle de la fonction Servo
...........................................................................................
10.2. Contrôle de la partie module
.............................................................................................
..........................................................................................................
11. Utilisation du Yocto-Servo en VisualBasic .NET
............................................
63
.........................................................................................................................
11.2. Utilisation l'API yoctopuce dans un projet Visual Basic
....................................................
11.3. Contrôle de la fonction Servo
...........................................................................................
11.4. Contrôle de la partie module
.............................................................................................
..........................................................................................................
12. Utilisation du Yocto-Servo en C#
............................................................................
71
.........................................................................................................................
12.2. Utilisation l'API yoctopuce dans un projet Visual C#
........................................................
12.3. Contrôle de la fonction Servo
...........................................................................................
12.4. Contrôle de la partie module
.............................................................................................
..........................................................................................................
13. Utilisation du Yocto-Servo en Delphi
....................................................................
79
.......................................................................................................................
13.2. Contrôle de la fonction Servo
...........................................................................................
13.3. Contrôle de la partie module
.............................................................................................
..........................................................................................................
14. Utilisation du Yocto-Servo en Python
..................................................................
85
................................................................................................................
..........................................................................................................
14.3. Contrôle de la fonction Servo
...........................................................................................
14.4. Contrôle de la partie module
.............................................................................................
..........................................................................................................
15. Utilisation du Yocto-Servo en Java
........................................................................
91
.......................................................................................................................
15.2. Contrôle de la fonction Servo
...........................................................................................
15.3. Contrôle de la partie module
.............................................................................................
..........................................................................................................
16. Utilisation du Yocto-Servo avec Android
...........................................................
97
16.1. Accès Natif et Virtual Hub.
................................................................................................
.......................................................................................................................
.....................................................................................................................
16.4. Activer le port USB sous Android
......................................................................................
16.5. Contrôle de la fonction Servo
.........................................................................................
16.6. Contrôle de la partie module
...........................................................................................
........................................................................................................
17. Programmation avancée
...........................................................................................
109
17.1. Programmation par événements
.....................................................................................
18. Utilisation avec des langages non supportés
...............................................
111
.......................................................................................................
...............................................................................................
18.3. Utilisation des librairies dynamiques
...............................................................................
18.4. Port de la librairie haut niveau
........................................................................................
19. Référence de l'API de haut niveau
.......................................................................
117
.......................................................................................................
19.2. Interface de contrôle du module
.....................................................................................
19.3. Interface de la fonction Servo
.........................................................................................
19.4. Interface de contrôle de l'alimentation
............................................................................
20. Problèmes courants
.....................................................................................................
249
...................................................................................................................
20.2. Plateformes ARM: HF et EL
............................................................................................
21. Caractéristiques
.............................................................................................................
251
...................................................................................................................................
Index
.............................................................................................................................................
255
1. Introduction
Le module Yocto-Servo est un module de 45x20mm qui permet de commander jusqu'à cinq servomoteurs de modélisme. Le module peut être alimenté par un alimentation externe, mais il supporte aussi de ne fonctionner qu'avec le bus USB, ce qui lui permet de piloter un petit servo sans connexion supplémentaire. Le module est capable de mesurer la tension fournie par l'alimention externe et de la couper automatiquement s'il détecte que sa tension devient trop basse. Ce manuel décrit essentiellement comment piloter des servo-moteurs de modélisme avec votre module Yocto-
Servo, mais il va de soit que vous pouvez parfaitement utiliser votre module pour piloter d'autres dispositifs couramment utilisés en modélisme comme des variateurs de vitesse, des contrôleurs de lumières... etc.
Le module Yocto-Servo
Yoctopuce vous remercie d'avoir fait l'acquisition de ce Yocto-Servo et espère sincèrement qu'il vous donnera entière satisfaction. Les ingénieurs Yoctopuce se sont donnés beaucoup de mal pour que votre Yocto-Servo 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 n'hésitez pas à contacter le support Yoctopuce
1
.
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 des fonctions du module.
www.yoctopuce.com
1
1. Introduction
1.1. Prérequis
Pour pouvoir profiter pleinement de votre module Yocto-Servo, 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 besoin, à 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, Mac OS X, Linux et Android. Les modules Yoctopuce ne nécessitent pas l'installation de driver (ou pilote) spécifiques, car ils utilisent le driver HID
2
fourni en standard dans tous les systèmes d'exploitation.
Les versions de Windows actuellement supportées sont Windows XP, Windows 2003, Windows
Vista et Windows 7. Les versions 32 bit et 64 bit sont supportées. Yoctopuce teste régulièrement le bon fonctionnement des modules sur Windows XP et Windows 7.
Les versions de Mac OS X actuellement supportées sont Mac OS X 10.6 (Snow Leopard), 10.7
(Lion) et 10.8 (Mountain Lion). Yoctopuce teste régulièrement le bon fonctionnement des modules sur Mac OS X 10.6 et 10.7.
Les versions de Linux supportées sont les kernels 2.6 et 3.0. D'autre versions du kernel et même d'autres variantes d'Unix sont très susceptibles d'être utilisées sans problème, puisque le support de
Linux est fait via l'API standard de la libusb, disponible aussi pour FreeBSD par exemple. Yoctopuce teste régulièrement le bon fonctionnement des modules sur un kernel Linux 2.6.
Les versions de Android actuellement supportées sont 3.1 et suivantes. De plus, il est nécessaire que la tablette ou le téléphone supporte le mode USB Host. Yoctopuce teste régulièrement le bon fonctionnement des modules avec Android 4.0 sur un Nexus 7 et un Samsung Galaxy S3 avec la librairie Java pour Android.
Un cable USB de type A-micro B
Il existe trois tailles de connecteurs USB, la taille "normale" que vous utilisez probablement pour brancher votre imprimante, la taille mini encore très courante et enfin la taille micro, souvent utilisée pour raccorder les téléphones portables, pour autant qu'ils n'arborent pas une pomme. Les modules de Yoctopuce sont tous équipés d'une connectique au format micro-USB.
Les connecteurs USB 2 les plus courants: A, B, Mini B, Micro A, Micro B.
3
2
2
Le driver HID est celui qui gère les périphériques tels que la souris, le clavier, etc.
3
Le connecteur Mini A a existé quelque temps, mais a été retiré du standard USB http://www.usb.org/developers/
Deprecation_Announcement_052507.pdf
www.yoctopuce.com
1. Introduction
Pour connecter votre module Yocto-Servo à un ordinateur, vous avez besoin d'un cable USB 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-Servo à l'aide d'un cable USB de type A - micro B
Si vous branchez un hub USB entre l'ordinateur et le module Yocto-Servo, 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étail à ce sujet dans le chapitre concernant le montage et la connectique.
1.2. Accessoires optionnels
Les accessoires ci-dessous ne sont pas nécessaires à l'utilisation du module Yocto-Servo, 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-Servo à un support, vous pouvez placer des petites vis de 2.5mm avec une tête de 4.5mm 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étail, consulter la fiche produit du micro-hub USB.
YoctoHub-Ethernet et YoctoHub-Wireless
Vous pouvez ajouter une connectivité réseau à votre Yocto-Servo grâce aux hubs YoctoHub-
Ethernet et YoctoHub-Wireless. Le premier offre une connectivité Ethernet, le second offre une connectivité Wifi. Chacun de ces hubs peut piloter jusqu'à trois modules Yoctopuce et se comporte exactement comme un ordinateur normal qui ferait tourner un VirtualHub.
Cable nappe mono-brin
Si vous désirez souder le module Yocto-Servo directement à un micro-hub USB pour éviter l'encombrement d'un vrai cable USB, utilisez de préférence du cable nappe étamé mono-brin: c'est le plus facile à souder. Dans tous les cas, il vous faudra 4 fils espacés de 1.27mm.
www.yoctopuce.com
3
1. Introduction
Bornier d'alimentation externe
Il est prévu que vous puissiez souder directement le cable d'alimentation externe sur le module.
Néanmoins vous pouvez utiliser un bornier
4
pour rendre le tout un peu plus démontable.
Utilisation d'un bornier pour l'alimentation externe.
Boîtier
Votre Yocto-Servo 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. Ces boîtiers sont munis de pattes de fixation amovibles et d'aimants de fixation. Vous trouverez plus d'informations à propos de ces boîtiers sur le site de Yoctopuce
5
. Le boîtier recommandé pour votre
Yocto-Servo est le modèle YoctoBox-Short-Thick-Black
Vous pouvez installer votre Yocto-Servo dans un boîtier optionnel.
4
4 vous pouvez utiliser le bornier Ref MPT 0.5/2-2,54 de Phoenix Contact
5 http://www.yoctopuce.com/EN/products/category/enclosures
www.yoctopuce.com
2. Présentation
1: Prise USB micro-B 6: Canal servo 3
2: Yocto-bouton 7: Canal servo 4
3: Yocto-led 8: Canal servo 5
4: Canal servo 1
5: Canal servo 2
9: Led alimentation par USB
10: Led alimentation externe
11: Connecteur alimentation externe
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 au format micro-USB. Les câbles correspondants ne sont pas forcément les plus faciles à trouver, mais ces connecteurs ont l'avantage d'occuper un minimum de place.
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.
www.yoctopuce.com
5
2. Présentation
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éthodelà 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 si 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 morse
1
. 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 Yoctopuce
2
.
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-Servo ce numéro commence par SERVORC1. 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 chaine de caractère 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 exemplaire du même projet sans avoir à modifier le logiciel de pilotage. Il suffit de programmer les même noms logique 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 cinq canaux
Le module Yocto-Servo dispose de cinq sorties capable de piloter chacune un servo. Ces sorties peuvent être alimentées soit par le bus UBS, soit par une alimentation externe.
6
1 court-court-court long-long-long court-court-court
www.yoctopuce.com
2. Présentation
Il est possible de brancher jusqu'à cinq servos
Le module est essentiellement prévu pour faire fonctionner des servos moteurs de modélisme, mais il peut parfaitement faire fonctioner d'autre dispositifs: en fait si pouvez faire fonctionner un dispositif en le branchant sur un récepteur de modélisme, vous pouvez aussi le faire piloter avec le Yocto-
Servo, cela inclut les variateurs de vitesse, brushless ou non.
Un port USB ne pouvant officiellement pas fournir plus de 500mA, et de toutes manière pas plus de
2 ampères, vous ne pourrez faire fonctionnent que des tout petits servo en n'utilisant que le port
USB. C'est pourquoi le module Yocto-Servo peut être alimenter avec une alimentation externe.
Le port d'alimentation externe
Vous pouvez brancher une alimentation externe sur votre module, cette alimentation sert alimenter les servos. La tension appliquée au connecteur d'alimentation externe sera directement transmise aux servos. Cela signifie que si vous appliquez du 5V, les servos seront alimentés en 5V, si vous appliquer du 6V, les servos seront alimentés en 6V... Vérifiez que vous utiliser une tension compatible avec vos servos.
Le module supporte quatre modes d'alimentation
Eteint
Dans ce mode, La logique du module fonctionne mais les servos ne sont tout simplement pas alimentés, et ne peuvent pas fonctionner
USB
De ce mode, les servos ne sont alimentés que par le port USB, cela signifie qu'il ne dispose que de
500mA si on décide de se conformer aux spécification USBs, 2A si on est un peu joueur. Dans tout les cas c'est très peu pour un servo, mais largement suffisant pour contrôler un variateur par exemple. Rapellez-vous que si port USB se voit débiter plus de 2 ampères, soit l'ordinateur qui le contrôle est bien conçu et il désactivera le port en question, soit il ne l'est pas et l'électronique de contrôle du port risque de griller.
En pratique, cela signifie si votre module Yocto-Servo n'est alimenté que par USB, vous ne pourrez probablement pas faire fonctionner plusieurs servos à la fois, sous peine de voir le module de déconnecter. Il est difficile de prévoir avec certitude comment se comportera votre module avec plusieurs servos s'il n'est alimenté que par USB, car cela dépend à la fois du modèle de servo et de l'alimentation USB de votre ordinateur. Le plus simple consiste à essayer. Notez que la consommation en pic d'un servo moteur peut être bien plus élevée que sa consommation moyenne.
Ces pics de consommation apparaissent lorsque le servo se met en mouvement, ou lorsqu'il force.
Externe
Dans ce mode les servos ne sont alimentés que si il y a une alimentation externe avec une tension supérieure à 4V.
Automatique
Dans ce mode, les servo sont normalement alimentés par USB. Si la tension de l'alimentation externe passe de 0V a plus de 5V, l'alimentation externe est choisie. Si la tension de l'alimentation
www.yoctopuce.com
7
2. Présentation
externe passe en dessous de 4V les servos ne sont plus alimentés: l'alimentation ne repasse pas automatiquement sur l'USB.
Les leds d'état de alimentation
L'état logique de l'alimentation du module est reflété par les deux leds placées à côté du connecteur de servos. Lorsque les servos sont alimentés par le port USB la led intérieure est allumée, lorsque les servos sont alimenté grâce a l'alimentation externe, la led externe est alimenté. Si cette dernière se mets a clignoter cela signifie que la tension de l'alimentation externe devient anormalement basse
(<4.5v) et qu'elle va bientôt être coupée.
8 www.yoctopuce.com
3. Premiers pas
Arrivé à ce chapitre votre Yocto-Servo 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 Virtual Hub
1
, Il est disponible pour Windows, Linux et Mac OS X. En temps normal le programme Virtual Hub 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
2
. Lancez le Virtual
Hub 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.1. 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 Yoctobouton d'un module.
3.2. 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-Servo.
1 www.yoctopuce.com/FR/virtualhub.php
2
L'interface a été testée avec FireFox 3+, IE 6+, Safari et Chrome, elle ne fonctionne pas avec Opéra
www.yoctopuce.com
9
3. Premiers pas
Propriétés du module Yocto-Servo.
Cette fenêtre vous permet entre autres de jouer avec votre module Yocto-Servo et d'en vérifier le fonctionnement, vous pouvez bouger les curseur correspondant aux différents canaux, et ce qui pour effet de bouger les servo correspondant. Vous remarquerez que la consommation du module augmente fortement lorsqu'un servo bouge et qu'il est alimenté par USB, alors qu'elle reste stable si les servos sont alimentés avec une alimentation externe.
3.3. Configuration
Si, dans la liste de modules, vous cliquez sur le bouton configure correspondant à votre module, la fenêtre de configuration apparaît.
10
Configuration du module Yocto-Servo.
Firmware
Le firmware du module peut être facilement être mis à jour à l'aide de l'interface. Pour ce faire, vous devez au préalable disposer du firmware adéquat sur votre disque local. Les firmwares destinés aux
www.yoctopuce.com
3. Premiers pas
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 ne sera plus listé dans l'interface. Mais il sera toujours possible de le reprogrammer correctement en utilisant le programme Virtual Hub
3
en ligne de commande
4
.
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 matiè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 plus un peu 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
Le module Yocto-Servo fournit deux fonctions: "Servo" dont il existe cinq instances: servo1..servo5, et dualPower dont il existe une seule instance.
Servo1..Servo5
Il s'agit de la fonction de pilotage des servo-moteurs, vous pouvez leur affecter un nom logique en cliquant sur le bouton rename.
Dual power
Il s'agit de la fonction qui permet de piloter la double alimentation USB / externe. Vous pouvez donner un nom logique à cette fonction et choisir son mode de fonctionnement: éteint, USB, externe ou automatique.
3 www.yoctopuce.com/FR/virtualhub.php
4
Consultez la documentation du virtual hub pour plus de détails
www.yoctopuce.com
11
12 www.yoctopuce.com
4. Montage et connectique
Ce chapitre fournit des explications importantes pour utiliser votre module Yocto-Servo 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-Servo dispose de trous de montage 2.5mm. 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 4.5mm, 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
www.yoctopuce.com
13
4. Montage et connectique
existe d'autres. Rien ne vous empêche de le fixer au pistolet à colle; ça ne sera très joli mais ça tiendra.
Si vous comptez visser votre module directement contre une paroi conductrice, un chassis métallique par exemple, intercalez une couche isolante entre les deux. Sinon vous aller à coup sûr provoquer un court-circuit: il y a des pads à nu sous votre module. Du simple ruban adhésif d'emballage devrait faire l'affaire.
4.2. Polarité
Vous devez brancher des fiches de manière à ce que le fil de signal soit branché à la broche supérieure. Notez que si vous branchez la prise d'un servo à l'envers, vous ne risquez pas grand chose: il ne fonctionnera tout simplement pas.
Sens de branchement des servos
Les couleurs des cables de servos varient d'une marque à l'autre vous trouverez ci-dessous les codes de couleurs les plus courants
Marque
Multiplex
Futaba / Robbe
JR / Hitec / Graupner
Signal
jaune blanc orange
(+)
rouge rouge rouge
(-)
Noir
Noir
Marron
4.3. Utilisation d'un variateur de modélisme
Vous pouvez parfaitement utiliser le module Yocto-Servo pour piloter un variateur de moteur, mais cela nécessite une petite précaution. La plupart des variateurs utilisés en modélisme sont prévus pour alimenter le récepteur par l'intermédiaire du fil rouge. Si vous branchez un variateur sur le module Yocto-Servo vous devez impérativement couper ce fil, il n'est pas du tout souhaitable que le variateur injecte du courant dans le module par l'intermédiaire des connecteurs de servos. En revanche vous pouvez parfaitement raccorder ce fil rouge au pole positif du connecteur d'alimentation externe: le variateur servira alors d'alimentation externe.
14
Si vous désirez piloter un variateur, le fil rouge doit soit être coupé, soit être utilisé comme alimentation externe.
www.yoctopuce.com
4. Montage et connectique
4.4. 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 si 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 ou 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 sousalimenté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.
www.yoctopuce.com
15
16 www.yoctopuce.com
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-Servo 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.
www.yoctopuce.com
Structure de l'API Yoctopuce.
17
5. Programmation, concepts généraux
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-Servo 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
18 www.yoctopuce.com
5. Programmation, concepts généraux
d'un certain nombre de méthodes permettant d'énumérer les fonctionnalités disponibles sur un module.
5.2. Le module Yocto-Servo
Le module Yocto-Servo offre une interface de contrôle de l'alimentation de puissance, et cinq instances de la fonction Servo, correspondant aux cinq controlleurs de servo-moteur du module.
module : Module attribut
productName serialNumber logicalName productId productRelease firmwareRelease persistentSettings luminosity beacon upTime usbCurrent rebootCountdown usbBandwidth
type
Texte
Texte
Texte
Entier (hexadécimal)
Entier (hexadécimal)
Texte
Type énuméré
0..100%
On/Off
modifiable ?
lecture seule lecture seule modifiable lecture seule lecture seule lecture seule modifiable modifiable modifiable
Temps lecture seule
Courant consommé (en mA) lecture seule
Nombre entier modifiable
Type énuméré modifiable
dualPower : DualPower attribut
logicalName
type
Texte
modifiable ?
modifiable advertisedValue powerState
Texte lecture seule
Type énuméré lecture seule powerControl
Type énuméré modifiable extVoltage
Nombre entier lecture seule
servo1 : Servo servo2 : Servo servo3 : Servo servo4 : Servo servo5 : Servo attribut type modifiable ?
logicalName advertisedValue position
Texte
Texte modifiable lecture seule
Nombre entier modifiable range neutral move
0..100%
0..65000 [us]
Agrégat modifiable modifiable modifiable
5.3. Interface de contrôle du module
Cette interface est la même pour 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
Chaine de caractères contenant le numéro de série, unique et préprogrammé en usine. Pour un module Yocto-Servo, ce numéro de série commence toujours par SERVORC1. Il peut servir comme point de départ pour accéder par programmation à un module particulier.
www.yoctopuce.com
19
5. Programmation, concepts généraux
logicalName
Chaine 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 18 en usine.
productRelease
Numéro de révision du module hardware, preprogrammed at the factory.
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.
usbBandwidth
Nombre d'interfaces utilisé par USB. L'option DOUBLE permet de doubler le débit USB mais peut saturer un hub USB. N'oubliez pas d'appeler la méthode saveToFlash()
et de redémarrer le module pour que le paramètre soit appliqué.
5.4. Interface de contrôle de l'alimentation
La librairie de programmation Yoctopuce permet de contrôler la source d'alimentation qui doit être utilisée pour les fonctions du module consommant beaucoup de courant. Le module est par ailleurs capable de couper automatiquement l'alimentation externe lorsqu'il détecte que la tension a trop chuté (batterie épuisée).
20 www.yoctopuce.com
5. Programmation, concepts généraux
logicalName
Chaîne de caractères contenant le nom logique du contrôle d'alimentation, 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 à le contrôle d'alimentation. Si deux contrôles d'alimentation 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 contrôle d'alimentation, et qui sera publiée automatiquement jusqu'au hub parent. Pour un contrôle d'alimentation, la valeur publiée est la source d'alimentation actuellement active: OFF, FROM_USB, FROM_EXT.
powerState
Source d'alimentation active pour les fonctions du module consommant beaucoup de courant: OFF
(si aucune alimentation n'est active), FROM_USB (si les fonctions sont alimentées par USB) et
FROM_EXT (si les fonctions sont alimentées par une source externe). Cet attribut est automatiquement mis à jour en particulier lorsque le contrôle de l'alimentation de puissance est en mode automatique.
powerControl
Mode d'alimentation choisi pour les fonctions du module consommant beaucoup de courant: OFF pour tout éteindre, FROM_USB pour forcer l'alimentation par USB, FROM_EXT pour forcer l'alimentation externe et AUTO pour activer le mode de contrôle automatique de l'alimentation de puissance.
extVoltage
Tension mesurée sur l'alimentation de puissance externe, en millivolts.
5.5. Interface de la fonction Servo
La librairie de programmation Yoctopuce permet non seulement de déplacer le servo vers une position donnée, mais aussi de spécifier l'interval de temps dans lequel le mouvement doit être fait, de sorte à pouvoir synchroniser un mouvement sur plusieurs servos.
logicalName
Chaîne de caractères contenant le nom logique du servo, 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 à le servo. Si deux servo 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 servo, et qui sera publiée automatiquement jusqu'au hub parent. Pour un servo, la valeur publiée est sa position actuelle (un nombre entre -1000 et 1000 compris).
position
Position actuelle du servo, ramenée par convention dans l'intervalle -1000 et 1000 compris. Lorsque la valeur 0 correspond à la position médiane du servo.
range
Plage d'utilisation du servo. La valeur 100% correspond à un signal de commande standard, variant de 1 [ms] à 2 [ms]. Pour les servos supportent une plage double, de 0.5 [ms] à 2.5 [ms], vous pouvez
www.yoctopuce.com
21
5. Programmation, concepts généraux
utiliser une plage allant jusqu'à 200%. Attention, l'utilisation d'une plage supérieure aux caractéristiques du servo risque fortement d'endommager le servo.
neutral
Durée en microsecondes de l'impulsion correspondant au neutre du servo. La valeur standard est de
1500 [us], mais certains servos utilisent une autre valeur afin d'exploiter un plage plus grande.
Attention, l'utilisation d'une valeur incorrecte risque fortement d'endommager le servo.
move
Permet de faire bouger le servo d'une position à l'autre en un temps précis. La valeur est un agrégat comprenant la position cible (un entier) et une durée en millisecondes.
5.6. Quelle interface: Native, DLL ou Service?
Il y existe plusieurs méthodes pour contrôler un module 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érence: il faut simplement être sur que la DLL sera installée sur son ordinateur en même temps que le programme principal.
22 www.yoctopuce.com
5. Programmation, concepts généraux
L'application utilise la DLL pour contrôler nativement le module connecté en local
Contrôle par un service
Certain 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 programme, appelé Hub Virtuel 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 hub virtuel. L'utilisateur final se verra obligé de lancer le hub virtuel avant de lancer le programme de contrôle du projet proprement dit, à moins qu'il ne décide d'installer le hub sous la forme d'un service/démon, auquel cas le hub virtuel se lancera automatiquement au démarrage de la machine..
L'application se connecte au virtual hub 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é 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 module. De plus les librairie natives et DLL évoquées plus haut sont aussi capables de se connecter à distance à un ou plusieurs hub virtuels
www.yoctopuce.com
23
5. Programmation, concepts généraux
Lorsqu'on utilise un hub virtuel, 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
C++
Objective-C
Delphi
Python
VisualBasic .Net
C# .Net
Javascript
Node.js
PHP
Natif Natif avec .DLL/.so Hub virtuel
-
•
•
-
-
-
-
-
-
•
•
•
•
•
-
-
-
-
•
•
•
•
•
•
•
•
•
Java
Java pour Android
-
• -
-
Ligne de commande • -
Méthode de support pour les différents langages.
•
•
•
Limitation des librairies Yoctopuce
Les librairies Natives et DLL ont une limitation technique. Sur une même machine, vous ne pouvez pas faire tourner en même temps plusieurs applications qui accèdent nativement aux modules
Yoctopuce. Si vous désirez contrôler plusieurs projets depuis la même machine, codez vos applications pour qu'elle accèdent aux modules via un VirtualHub plutôt que nativement. Le changement de mode de fonctionnement est trivial: il suffit de changer un paramètre dans l'appel à yRegisterHub()
.
5.7. Programmation, par où commencer?
Arrivé à ce point du manuel, vous devriez connaître l'essentiel de la théorie à propos de votre Yocto-
Servo. 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 Yoctopuce
1
. 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.
24
1 http://www.yoctopuce.com/FR/libraries.php
www.yoctopuce.com
5. Programmation, concepts généraux
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-Servo.
www.yoctopuce.com
25
26 www.yoctopuce.com
6. Utilisation du Yocto-Servo en ligne de commande
Lorsque vous désirez effectuer une opération ponctuelle sur votre Yocto-Servo, comme la lecture d'une valeur, le changement d'un nom logique, etc.. vous pouvez bien sur utiliser le Virtual Hub, 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 fournies
1
.
6.1. Installation
Téléchargez l'API en ligne de commande
2
. 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-Servo, ouvrir un shell et commencer à travailler en tapant par exemple:
C:\> YServo any move 1000 2000
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 la 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.
1
Si vous souhaitez recompiler l'API en ligne de commande, vous aurez aussi besoin de l'API C++
2 http://www.yoctopuce.com/FR/libraries.php
www.yoctopuce.com
27
6. Utilisation du Yocto-Servo en ligne de commande
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 Servo
Pour contrôler la fonction Servo de votre Yocto-Servo, vous avez besoin de l'exécutable YServo.
Vous pouvez par exemple lancer:
C:\> YServo any move 1000 2000
Cet exemple utilise la cible "any" pour signifier que l'on désire travailler sur la première fonction
Servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "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:\> YServo SERVORC1-123456.servo1 describe
C:\> YServo SERVORC1-123456.MaFonction describe
C:\> YServo MonModule.servo1 describe
C:\> YServo MonModule.MaFonction describe
C:\> YServo MaFonction describe
Pour travailler sur toutes les fonctions Servo à la fois, utilisez la cible "all".
C:\> YServo all describe
Pour plus de détails sur les possibilités de l'exécutable
YServo
, utilisez:
C:\> YServo
/help
28
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 exemple, pour obtenir la liste de tous les modules connectés, utilisez:
YModule
. Par
www.yoctopuce.com
6. Utilisation du Yocto-Servo en ligne de commande
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 SERVORC1-12346 set_logicalName MonPremierModule
C:\> YModule SERVORC1-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 SERVORC1-12346 set_logicalName MonPremierModule
C:\> YModule SERVORC1-12346 saveToFlash
Notez que vous pouvez faire la même chose en seule fois à l'aide de l'option
-s
C:\> YModule -s SERVORC1-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 un Virtual Hub: il suffit de faire tourner le
VirtualHub
3
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 un virtual hub et que vous lancez votre commande sous la forme:
C:\> YModule -r 127.0.0.1 inventory
3 http://www.yoctopuce.com/FR/virtualhub.php
www.yoctopuce.com
29
6. Utilisation du Yocto-Servo en ligne de commande
cela marchera parce que la commande ne sera plus exécutée nativement, mais à travers le Virtual
Hub. Notez que le Virtual Hub compte comme une application native.
30 www.yoctopuce.com
7. Utilisation du Yocto-Servo en Javascript
Javascript n'est probablement pas le premier langage qui vous serait venu à l'esprit pour contrôler du matériel, mais il présente l'immense avantage d'être très facile à mettre en oeuvre: avec Javascript, il ne vous faudra qu'un éditeur de texte et un browser internet pour réaliser vos premiers essais.
Au moment de l'écriture de ce manuel, la librairie Javascript fonctionne avec n'importe quel browser récent... sauf Opera. Il est probable que qu'Opera finira un jour par fonctionner avec la librairie
Yoctopuce
1
, mais pour l'instant ce n'est pas le cas.
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 vous devrez faire tourner la passerelle de
Yoctopuce appelée VirtualHub sur la machine à laquelle sont branchés les modules
7.1. Préparation
Connectez vous sur le site de Yoctopuce et téléchargez les éléments suivants:
• La librairie de programmation pour Javascript
2
• Le programme VirtualHub
3
pour Windows, Mac OS X ou Linux selon l'OS que vous utilisez
Décompressez les fichiers de la librairie dans un répertoire de votre choix, branchez vos modules, lancez le programme VirtualHub,et vous pouvez commencer vos premiers test. Vous n'avez pas besoin d'installer de driver.
7.2. Contrôle de la fonction Servo
Il suffit de quelques lignes de code pour piloter un Yocto-Servo. Voici le squelette d'un fragment de code JavaScript qui utilise la fonction Servo.
<SCRIPT type= "text/javascript" src= "yocto_api.js" >;</SCRIPT>
<SCRIPT type= "text/javascript" src= "yocto_servo.js" ></SCRIPT>
// On récupère l'objet représentant le module, à travers le VirtualHub local
yRegisterHub ( 'http://127.0.0.1:4444/' ) ; var servo = yFindServo ( "SERVORC1-123456.servo1" ) ;
// Pour gérer le hot-plug, on vérifie que le module est là
1
En fait dès qu'Opera implémentera le support pour le header HTTP Access-Control-Allow-Origin
2 www.yoctopuce.com/FR/libraries.php
3 www.yoctopuce.com/FR/virtualhub.php
www.yoctopuce.com
31
7. Utilisation du Yocto-Servo en Javascript
if( servo.
isOnline ())
{
// Utiliser servo.set_position(), ...
}
Voyons maintenant en détail ce que font ces quelques lignes.
yocto_api.js et yocto_servo.js
Ces deux includes Javascript permettent d'avoir accès aux fonctions permettant de gérer les modules Yoctopuce. yocto_api.js
doit toujours être inclus, yocto_servo.js
est nécessaire pour gérer les modules contenant un servo, comme le Yocto-Servo.
yRegisterHub
La fonction yRegisterHub
permet d'indiquer sur quelle machine se trouve 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.
yFindServo
La fonction yFindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté): var servo = yFindServo ( "SERVORC1-123456.servo1" ) ; var servo = yFindServo ( "SERVORC1-123456.MaFonction" ) ; var servo = yFindServo ( "MonModule.servo1" ) ; var servo = yFindServo ( "MonModule.MaFonction" ) ; var servo = yFindServo ( "MaFonction" ) ;
</ yFindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
isOnline
La méthode isOnline()
de l'objet renvoyé par correspondant est présent et en état de marche.
yFindServo
permet de savoir si le module
set_position
La méthode set_position()
de l'objet renvoyé par yFindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur 0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par yFindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
Un exemple réel
Ouvrez votre éditeur de texte préféré
4
, recopiez le code ci-dessous, sauvez-le dans le même répertoire que les fichiers de la librairie, et ouvrez-le avec votre browser favori (sauf Opera). Vous trouverez aussi ce code dans le répertoire Examples/Doc-GettingStarted-Yocto-Servo 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.
32
4
Si vous n'avez pas d'éditeur de texte, utilisez Notepad plutôt que Microsoft Word.
www.yoctopuce.com
7. Utilisation du Yocto-Servo en Javascript
L'exemple est codé pour être utilisé soit depuis un serveur web, soit en ouvrant directement le fichier localement sur la machine. Notez que cette dernière solution n'est pas possible avec certaines versions de Internet Explorer (en particulier IE 9 de Windows 7), qui refuse d'ouvrir des connections réseau lorsqu'il travaille sur un fichier local. Pour utiliser Internet Explorer, vous devez donc mettre les pages sur un serveur web. Aucun problème par contre avec Chrome, Firefox ou Safari.
Si le Yocto-Servo 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-Servo et où vous avez lancé le VirtualHub.
<HTML>
<HEAD>
<TITLE>Hello World</TITLE>
<SCRIPT type= "text/javascript" src= "yocto_api.js" ></SCRIPT>
<SCRIPT type= "text/javascript" src= "yocto_servo.js" ></SCRIPT>
<SCRIPT language= 'javascript1.5' type= 'text/JavaScript' >
<!--
// Setup the API to use the VirtualHub on local machine
if( yRegisterHub ( 'http://127.0.0.1:4444/' ) != YAPI_SUCCESS ) { alert ( "Cannot contact VirtualHub on 127.0.0.1" ) ;
} var s1, s5; function refresh ()
{ var serial = document .
getElementById ( 'serial' ) .
value ; if( serial == '' ) {
// Detect any conected module suitable for the demo
s1 = yFirstServo () ; if( s1 ) {
serial = s1.
module () .
get_serialNumber () ; document .
getElementById ( 'serial' ) .
value = serial;
}
}
s1 = yFindServo ( serial+ ".servo1" ) ;
s5 = yFindServo ( serial+ ".servo5" ) ; if( s1.
isOnline ()) { document .
getElementById ( 'msg' ) .
value = '' ;
} else { document .
getElementById ( 'msg' ) .
value = 'Module not connected' ;
} setTimeout ( 'refresh()' , 500 ) ;
} function moveTo ( pos )
{
// Show two different types of move
s1.
set_position ( pos ) ;
// move as fast as possible
s5.
move ( pos, 3000 ) ;
// move in 3 seconds
}
-->
</SCRIPT>
</HEAD>
<BODY onload= 'refresh();' >
Module to use: <input id= 'serial' >
<input id= 'msg' style= 'color:red;border:none;' readonly><br>
<a href= 'javascript:moveTo(-1000);' >Move to position 1000 </a><br>
<a href= 'javascript:moveTo(-500);' >Move to position 500 </a><br>
<a href= 'javascript:moveTo(0);' >Move to center position</a><br>
<a href= 'javascript:moveTo(500);' >Move to position + 500 </a><br>
<a href= 'javascript:moveTo(1000);' >Move to position + 1000 </a><br>
</BODY>
</HTML>
7.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.
www.yoctopuce.com
33
7. Utilisation du Yocto-Servo en Javascript
34
<HTML>
<HEAD>
<TITLE>Module Control</TITLE>
<SCRIPT type= "text/javascript" src= "yocto_api.js" ></SCRIPT>
<SCRIPT language= 'javascript1.5' type= 'text/JavaScript' >
<!--
// Use explicit error handling rather than exceptions
yDisableExceptions () ;
// Setup the API to use the VirtualHub on local machine
if( yRegisterHub ( 'http://127.0.0.1:4444/' ) != YAPI_SUCCESS ) { alert ( "Cannot contact VirtualHub on 127.0.0.1" ) ;
} var module; function refresh ()
{ var serial = document .
getElementById ( 'serial' ) .
value ; if( serial == '' ) {
// Detect any conected module suitable for the demo
module = yFirstModule () .
nextModule () ; if( module ) {
serial = module.
get_serialNumber () ; document .
getElementById ( 'serial' ) .
value = serial;
}
}
module = yFindModule ( serial ) ; if( module.
isOnline ()) { document .
getElementById ( 'msg' ) .
value = '' ; var html = 'serial: ' +module.
get_serialNumber () + '<br>' ;
html += 'logical name: ' +module.
get_logicalName () + '<br>' ;
html += 'luminosity:' +module.
get_luminosity () + '%<br>' ;
html += 'beacon:' ; if ( module.
get_beacon () ==Y_BEACON_ON )
html+= "ON <a href='javascript:beacon(Y_BEACON_OFF)'>switch off</a><br>" ; else
html+= "OFF <a href='javascript:beacon(Y_BEACON_ON)'>switch on</a><br>" ;
html += 'upTime: ' + parseInt ( module.
get_upTime () / 1000 ) + ' sec<br>' ;
html += 'USB current: ' +module.
get_usbCurrent () + ' mA<br>' ;
html += 'logs:<br><pre>' +module.
get_lastLogs () + '</pre><br>' ; document .
getElementById ( 'data' ) .
innerHTML = html;
} else { document .
getElementById ( 'msg' ) .
value = 'Module not connected' ;
} setTimeout ( 'refresh()' , 1000 ) ;
} function beacon ( state )
{
module.
set_beacon ( state ) ;
refresh () ;
}
-->
</SCRIPT>
</HEAD>
<BODY onload= 'refresh();' >
Module to use: <input id= 'serial' >
<input id= 'msg' style= 'color:red;border:none;' readonly><br>
<span id= 'data' ></span>
</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
www.yoctopuce.com
7. Utilisation du Yocto-Servo en Javascript
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>Change module settings</TITLE>
<SCRIPT type= "text/javascript" src= "yocto_api.js" ></SCRIPT>
<SCRIPT language= 'javascript1.5' type= 'text/JavaScript' >
<!--
// Use explicit error handling rather than exceptions
yDisableExceptions () ;
// Setup the API to use the VirtualHub on local machine
if( yRegisterHub ( 'http://127.0.0.1:4444/' ) != YAPI_SUCCESS ) { alert ( "Cannot contact VirtualHub on 127.0.0.1" ) ;
} var module; function refresh ()
{ var serial = document .
getElementById ( 'serial' ) .
value ; if( serial == '' ) {
// Detect any conected module suitable for the demo
module = yFirstModule () .
nextModule () ; if( module ) {
serial = module.
get_serialNumber () ; document .
getElementById ( 'serial' ) .
value = serial;
}
}
module = yFindModule ( serial ) ; if( module.
isOnline ()) { document .
getElementById ( 'msg' ) .
value = '' ; document .
getElementById ( 'curName' ) .
value = module.
get_logicalName () ;
} else { document .
getElementById ( 'msg' ) .
value = 'Module not connected' ;
} setTimeout ( 'refresh()' , 1000 ) ;
} function save ()
{ var newname = document .
getElementById ( 'newName' ) .
value ; if ( !yCheckLogicalName
( newname )) { alert ( 'invalid logical name' ) ; return ;
}
module.
set_logicalName ( newname ) ;
module.
saveToFlash () ;
}
-->
</SCRIPT>
</HEAD>
<BODY onload= 'refresh();' >
Module to use: <input id= 'serial' >
<input id= 'msg' style= 'color:red;border:none;' readonly><br>
Current name: <input id= 'curName' readonly><br>
New logical name: <input id= 'newName' >
<a href= 'javascript:save();' >Save</a>
</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.
www.yoctopuce.com
35
7. Utilisation du Yocto-Servo en Javascript
É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 exemple listant les module connectés
NULL
. Ci-dessous un petit
<HTML>
<HEAD>
<TITLE>Modules inventory</TITLE>
<SCRIPT type= "text/javascript" src= "yocto_api.js" ></SCRIPT>
<SCRIPT language= 'javascript1.5' type= 'text/JavaScript' >
<!--
// Use explicit error handling rather than exceptions
yDisableExceptions () ;
// Setup the API to use the VirtualHub on local machine
if( yRegisterHub ( 'http://127.0.0.1:4444/' ) != YAPI_SUCCESS ) { alert ( "Cannot contact VirtualHub on 127.0.0.1" ) ;
} function refresh ()
{
yUpdateDeviceList () ; var htmlcode = '' ; var module = yFirstModule () ; while( module ) {
htmlcode += module.
get_serialNumber ()
+ '(' +module.
get_productName () + ")<br>" ;
module = module.
nextModule () ;
} document .
getElementById ( 'list' ) .
innerHTML =htmlcode; setTimeout ( 'refresh()' , 500 ) ;
}
-->
</SCRIPT>
</HEAD>
<BODY onload= 'refresh();' >
<H1>Device list</H1>
<tt><span id= 'list' ></span></tt>
</BODY>
</HTML>
7.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 cidessous.
36 www.yoctopuce.com
7. Utilisation du Yocto-Servo en Javascript
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:
• Si votre code attrape l'exception au vol et la gère, et tout se passe bien.
• Si votre programme tourne dans le debugger, vous pourrez relativement facilement déterminer où le problème s'est produit, et voir le message explicatif lié à l'exception.
• Sinon... l'exception va crasher votre programme, boum!
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 yDisableExceptions()
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 méthode get_state() get_currentValue
retournera une valeur
retournera une valeur
Y_STATE_INVALID
Y_CURRENTVALUE_INVALID
, une
, 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.
www.yoctopuce.com
37
38 www.yoctopuce.com
8. Utilisation du Yocto-Servo 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 un hub virtuel sur la machine à laquelle sont branchés les modules
Pour démarrer vos essais en PHP, vous allez avoir besoin d'un serveur PHP 5.3 ou plus
1
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.
8.1. Préparation
Connectez vous sur le site de Yoctopuce et téléchargez les éléments suivants:
• La librairie de programmation pour PHP
2
• Le programme VirtualHub
3
pour Windows, Mac OS X ou Linux selon l'OS que vous utilisez
Décompressez les fichiers de la librairie dans un répertoire de votre choix accessible à votre serveur web, branchez vos modules, lancez le programme VirtualHub, et vous pouvez commencer vos premiers test. Vous n'avez pas besoin d'installer de driver.
8.2. Contrôle de la fonction Servo
Il suffit de quelques lignes de code pour piloter un Yocto-Servo. Voici le squelette d'un fragment de code PHP qui utilise la fonction Servo.
include( 'yocto_api.php' ) ; include( 'yocto_servo.php' ) ;
1
Quelques serveurs PHP gratuits: easyPHP pour windows, MAMP pour Mac Os X
2 www.yoctopuce.com/FR/libraries.php
3 www.yoctopuce.com/FR/virtualhub.php
www.yoctopuce.com
39
8. Utilisation du Yocto-Servo en PHP
// On récupère l'objet représentant le module, à travers le VirtualHub local
yRegisterHub ( 'http://127.0.0.1:4444/' ,$errmsg ) ;
$servo = yFindServo ( "SERVORC1-123456.servo1" ) ;
// Pour gérer le hot-plug, on vérifie que le module est là
if( servo-> isOnline ())
{
// Utiliser servo->set_position(), ...
}
Voyons maintenant en détail ce que font ces quelques lignes.
yocto_api.php et yocto_servo.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_servo.php
est nécessaire pour gérer les modules contenant un servo, comme le Yocto-Servo.
yRegisterHub
La fonction yRegisterHub
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.
yFindServo
La fonction yFindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):
$servo = yFindServo ( "SERVORC1-123456.servo1" ) ;
$servo = yFindServo ( "SERVORC1-123456.MaFonction" ) ;
$servo = yFindServo ( "MonModule.servo1" ) ;
$servo = yFindServo ( "MonModule.MaFonction" ) ;
$servo = yFindServo ( "MaFonction" ) ; yFindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
isOnline
La méthode isOnline()
de l'objet renvoyé par correspondant est présent et en état de marche.
yFindServo
permet de savoir si le module
set_position
La méthode set_position()
de l'objet renvoyé par yFindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur 0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par yFindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
Un exemple réel
Ouvrez votre éditeur de texte préféré
4
, 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
40
4
Si vous n'avez pas d'éditeur de texte, utilisez Notepad plutôt que Microsoft Word.
www.yoctopuce.com
8. Utilisation du Yocto-Servo en PHP
browser favori. Vous trouverez aussi ce code dans le répertoire Examples/Doc-GettingStarted-
Yocto-Servo 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.
<HTML>
<HEAD>
<TITLE>Hello World</TITLE>
</HEAD>
<BODY>
<FORM method='get'>
<?php
include( 'yocto_api.php' ) ; include( 'yocto_servo.php' ) ;
// Use explicit error handling rather than exceptions
yDisableExceptions () ;
// Setup the API to use the VirtualHub on local machine
if( yRegisterHub ( '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
$servo1 = yFindServo ( " $serial .servo1" ) ;
$servo5 = yFindServo ( " $serial .servo5" ) ; if ( !$servo1-> isOnline ()) { die ( "Module not connected (check serial and USB cable)" ) ;
}
} else {
// or use any connected module suitable for the demo
$servo1 = yFirstServo () ; if( is_null ( $servo1 )) { die ( "No module connected (check USB cable)" ) ;
} else {
$serial = $servo1-> module () -> get_serialnumber () ;
$servo1 = yFindServo ( " $serial .servo1" ) ;
$servo5 = yFindServo ( " $serial .servo5" ) ;
}
}
Print( "Module to use: <input name='serial' value=' $serial '><br>" ) ; if( isset ( $_GET [ 'pos' ])) {
$pos = $_GET [ 'pos' ] ;
$servo1-> set_position ( $pos ) ;
// move as fast as possible
$servo5-> move ( $pos, 3000 ) ;
// move in 3 seconds
}
?>
<input type='radio' name='pos' value='-1000'>Move to -1000<br>
<input type='radio' name='pos' value='-500'>Move to -500<br>
<input type='radio' name='pos' value='0'>Move to center<br>
<input type='radio' name='pos' value='500'>Move to 500<br>
<input type='radio' name='pos' value='1000'>Move to 1000<br>
<input type='submit'>
</FORM>
</BODY>
</HTML>
8.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>
www.yoctopuce.com
41
8. Utilisation du Yocto-Servo en PHP
42
<FORM method='get'>
<?php
include( 'yocto_api.php' ) ;
// Use explicit error handling rather than exceptions
yDisableExceptions () ;
// Setup the API to use the VirtualHub on local machine
if( yRegisterHub ( '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 = yFindModule ( " $serial " ) ; if ( !$module-> isOnline ()) { die ( "Module not connected (check serial and USB cable)" ) ;
}
} else {
// or use any connected module suitable for the demo
$module = yFirstModule () ; 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 ()) ;
?>
<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.
www.yoctopuce.com
8. Utilisation du Yocto-Servo en PHP
<HTML>
<HEAD>
<TITLE>save settings</TITLE>
<BODY>
<FORM method='get'>
<?php
include( 'yocto_api.php' ) ;
// Use explicit error handling rather than exceptions
yDisableExceptions () ;
// Setup the API to use the VirtualHub on local machine
if( yRegisterHub ( '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 = yFindModule ( " $serial " ) ; if ( !$module-> isOnline ()) { die ( "Module not connected (check serial and USB cable)" ) ;
}
} else {
// or use any connected module suitable for the demo
$module = yFirstModule () ; 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>" ) ;
?>
<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 exemple listant les module connectés
NULL
. Ci-dessous un petit
<HTML>
<HEAD>
<TITLE>inventory</TITLE>
</HEAD>
<BODY>
<H1>Device list</H1>
<TT>
<?php
www.yoctopuce.com
43
8. Utilisation du Yocto-Servo en PHP
include( 'yocto_api.php' ) ;
yRegisterHub ( "http://127.0.0.1:4444/" ) ;
$module = yFirstModule () ; while ( !
is_null ( $module )) { printf ( " %s ( %s )<br>" , $module-> get_serialNumber () ,
$module-> get_productName ()) ;
$module=$module-> nextModule () ;
}
?>
</TT>
</BODY>
</HTML>
8.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.
44
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.
www.yoctopuce.com
8. Utilisation du Yocto-Servo en PHP
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.
www.yoctopuce.com
L'API par callback HTTP utilise le VirtualHub, et c'est lui qui initie les requêtes.
45
8. Utilisation du Yocto-Servo en PHP
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.
46
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
www.yoctopuce.com
8. Utilisation du Yocto-Servo en PHP
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 et Node.JS.
8.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
www.yoctopuce.com
47
8. Utilisation du Yocto-Servo en PHP
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 cidessous.
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:
• Si votre code attrape l'exception au vol et la gère, et tout se passe bien.
• Si votre programme tourne dans le debugger, vous pourrez relativement facilement déterminer où le problème s'est produit, et voir le message explicatif lié à l'exception.
• Sinon... l'exception va crasher votre programme, boum!
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 yDisableExceptions()
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
Y_STATE_INVALID
, une méthode get_currentValue
retournera une valeur
Y_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.
48 www.yoctopuce.com
9. Utilisation du Yocto-Servo 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, tous les exemples et les modèles de projet sont testés avec Microsoft Visual Studio 2010 Express, disponible gratuitement sur le site de Microsoft
1
. Sous Mac OS X, tous les exemples et les modèles de projet sont testés avec XCode 4, disponible sur l'App Store. Par ailleurs, aussi bien sous Mac OS
X 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
pour permet de compiler les exemples en ligne de commande, et en pleine connaissance des arguments de compilation et link.
Les librairies Yoctopuce
2
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.
9.1. Contrôle de la fonction Servo
Il suffit de quelques lignes de code pour piloter un Yocto-Servo. Voici le squelette d'un fragment de code C++ qui utilise la fonction Servo.
#include "yocto_api.h"
#include "yocto_servo.h"
[ ...
]
String errmsg;
YServo *servo;
1 http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express
2 www.yoctopuce.com/FR/libraries.php
www.yoctopuce.com
49
9. Utilisation du Yocto-Servo en C++
50
// On récupère l'objet représentant le module (ici connecté en local sur USB)
yRegisterHub ( "usb" , errmsg ) ; servo = yFindServo ( "SERVORC1-123456.servo1" ) ;
// Pour gérer le hot-plug, on vérifie que le module est là
if( servo-> isOnline ())
{
// Utiliser servo->set_position(), ...
}
Voyons maintenant en détail ce que font ces quelques lignes.
yocto_api.h et yocto_servo.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_servo.h
est nécessaire pour gérer les modules contenant un servo, comme le Yocto-Servo.
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.
yFindServo
La fonction yFindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):
YServo *servo = yFindServo ( "SERVORC1-123456.servo1" ) ;
YServo *servo = yFindServo ( "SERVORC1-123456.MaFonction" ) ;
YServo *servo = yFindServo ( "MonModule.servo1" ) ;
YServo *servo = yFindServo ( "MonModule.MaFonction" ) ;
YServo *servo = yFindServo ( "MaFonction" ) ; yFindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
isOnline
La méthode isOnline()
de l'objet renvoyé par correspondant est présent et en état de marche.
yFindServo
permet de savoir si le module
set_position
La méthode set_position()
de l'objet renvoyé par yFindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur 0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par yFindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
Un exemple réel
Lancez votre environnement C++ et ouvrez le projet exemple correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-Servo 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.
www.yoctopuce.com
9. Utilisation du Yocto-Servo en C++
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_servo.h"
#include <iostream>
#include <stdlib.h> using namespace std; static void usage (void)
{ cout << "usage: demo <serial_number> [ -1000 | ... | 1000 ]" << endl ; cout << " demo <logical_name> [ -1000 | ... | 1000 ]" << endl ; cout << " demo any [ -1000 | ... | 1000 ] (use any discovered device)" << endl ; u64 now = yGetTickCount () ;
// dirty active wait loop
while ( yGetTickCount () -now< 3000 ) ; exit ( 1 ) ;
} int main ( int argc, const char * argv [])
{ string errmsg; string target;
YServo *servo1;
YServo *servo5; int pos; if ( argc < 3 ) {
usage () ;
}
target = ( string ) argv [ 1 ] ;
pos = ( int ) atol ( argv [ 2 ]) ;
// Setup the API to use local USB devices
if ( yRegisterHub ( "usb" , errmsg ) != YAPI_SUCCESS ) { cerr << "RegisterHub error: " << errmsg << endl ; return 1 ;
} if ( target == "any" ) {
YServo *servo = yFirstServo () ; if ( servo== NULL ) { cout << "No module connected (check USB cable)" << endl ; return 1 ;
}
target = servo-> module () -> get_serialNumber () ;
}
servo1 = yFindServo ( target + ".servo1" ) ;
servo5 = yFindServo ( target + ".servo5" ) ; if ( servo1-> isOnline ()) {
servo1-> set_position ( pos ) ;
// immediate switch
servo5-> move ( pos, 3000 ) ;
// smooth transition
} else { cout << "Module not connected (check identification and USB cable)" << endl ;
} return 0 ;
}
9.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"
www.yoctopuce.com
51
9. Utilisation du Yocto-Servo en C++
52
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( yRegisterHub ( "usb" , errmsg ) != YAPI_SUCCESS ) { cerr << "RegisterHub error: " << errmsg << endl ; return 1 ;
} if( argc < 2 )
usage ( argv [ 0 ]) ;
YModule *module = yFindModule ( 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 ;
} 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 )
www.yoctopuce.com
9. Utilisation du Yocto-Servo en C++
{ 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( yRegisterHub ( "usb" , errmsg ) != YAPI_SUCCESS ) { cerr << "RegisterHub error: " << errmsg << endl ; return 1 ;
} if( argc < 2 )
usage ( argv [ 0 ]) ;
YModule *module = yFindModule ( 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 ;
} 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 exemple listant les module connectés
NULL
. Ci-dessous un petit
#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( yRegisterHub ( "usb" , errmsg ) != YAPI_SUCCESS ) { cerr << "RegisterHub error: " << errmsg << endl ; return 1 ;
} cout << "Device list: " << endl ;
YModule *module = yFirstModule () ; while ( module != NULL ) { cout << module-> get_serialNumber () << " " ; cout << module-> get_productName () << endl ;
www.yoctopuce.com
53
9. Utilisation du Yocto-Servo en C++
}
module = module-> nextModule () ;
} return 0 ;
9.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 cidessous.
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:
• Si votre code attrape l'exception au vol et la gère, et tout se passe bien.
• Si votre programme tourne dans le debugger, vous pourrez relativement facilement déterminer où le problème s'est produit, et voir le message explicatif lié à l'exception.
• Sinon... l'exception va crasher votre programme, boum!
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 yDisableExceptions()
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
Y_STATE_INVALID
, une méthode get_currentValue
retournera une valeur
Y_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.
9.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.
54 www.yoctopuce.com
9. Utilisation du Yocto-Servo en C++
Intégration au format source
L'intégration de toutes les sources de la librairie dans vos projets a plusieurs avantages:
• Elle garanti le respect des conventions de compilation de votre projet (32/64 bits, inclusion des symboles de debug, caractères unicode ou ASCII, etc.);
• Elle facilite le déboggage si vous cherchez la cause d'un problème lié à la librairie Yoctopuce
• Elle réduit les dépendances sur des composants tiers, par exemple pour parer au cas où vous pourriez être mené à recompiler ce projet pour une architecture différente dans de nombreuses années.
• Elle ne requiert pas l'installation d'une librairie dynamique spécifique à Yoctopuce sur le système final, tout est dans l'exécutable.
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:
• Pour Windows: les librairies sont mises automatiquement
• Pour Mac OS X: IOKit.framework et CoreFoundation.framework
• Pour Linux: libm, libpthread, libusb1.0 et libstdc++
Intégration en librairie statique
L'intégration de de la librairie Yoctopuce sous forme de librairie statique est une manière plus simple de construire un petit exécutable utilisant des modules Yoctopuce. Elle 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 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 correspondant à votre système d'exploitation à votre LibPath.
Binaries/...
Ensuite, pour que votre projet se construise ensuite correctement, il faudra linker avec votre projet la librairie Yoctopuce et les librairies systèmes requises:
• Pour Windows: yocto-static.lib
• Pour Mac OS X: libyocto-static.a. IOKit.framework et CoreFoundation.framework
• Pour Linux: libyocto-static.a, libm, libpthread, libusb1.0 et libstdc++.
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
Mac OS X et Linux).
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.
www.yoctopuce.com
55
9. Utilisation du Yocto-Servo en C++
Ensuite, pour que votre projet se construise ensuite correctement, il faudra linker avec votre projet la librairie dynamique Yoctopuce et les librairies systèmes requises:
• Pour Windows: yocto.lib
• Pour Mac OS X: libyocto, IOKit.framework et CoreFoundation.framework
• Pour Linux: libyocto, libm, libpthread, libusb1.0 et libstdc++.
Avec GCC, la ligne de commande de compilation est simplement: gcc (...) -lyocto -lm -lpthread -lusb-1.0 -lstdc++
56 www.yoctopuce.com
10. Utilisation du Yocto-Servo en Objective-C
Objective-C est le langage de prédilection pour programmer sous Mac OS X, en raison de son intégration avec le générateur d'interfaces Cocoa. Pour pouvoir utiliser la libraire Objective-C vous aurez impérativement besoin de XCode 4.2, qui est disponible gratuitement sous Lion. Si vous êtes encore sous Snow Leopard il vous faudra être enregistré comme développeur auprès d'Apple pour pourvoir télécharger XCode 4.2. 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 Yoctopuce
1
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é
2
avec des séquences vidéo montrant comment intégrer les fichiers de la librairie à vos projets.
10.1. Contrôle de la fonction Servo
Lancez Xcode 4.2 et ouvrez le projet exemple correspondant, fourni dans le répertoire Examples/
Doc-GettingStarted-Yocto-Servo de la librairie Yoctopuce.
#import <Foundation/Foundation.h>
#import "yocto_api.h"
#import "yocto_servo.h" static void usage (void)
{
NSLog ( @"usage: demo <serial_number> [ -1000 | ... | 1000 ]" ) ;
NSLog ( @" demo <logical_name> [ -1000 | ... | 1000 ]" ) ;
NSLog ( @" demo any [ -1000 | ... | 1000 ] (use any discovered device)" ) ;
1 www.yoctopuce.com/FR/libraries.php
2 www.yoctopuce.com/FR/article/nouvelle-librairie-objective-c-pour-mac-os-x
www.yoctopuce.com
57
10. Utilisation du Yocto-Servo en Objective-C
58
exit ( 1 ) ;
} int main ( int argc, const char * argv [])
{
NSError *error; if ( argc < 3 ) {
usage () ;
}
@autoreleasepool{
// 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 ]] ; if ([ target isEqualToString: @"any" ]) {
YServo *servo = [ YServo FirstServo ] ; if ( servo== NULL ) {
NSLog ( @"No module connected (check USB cable)" ) ; return 1 ;
}
target = [[ servo module ] serialNumber ] ;
}
YServo *servo1 = [ YServo FindServo: [ target stringByAppendingString: @".servo1" ]] ;
YServo *servo5 = [ YServo FindServo: [ target stringByAppendingString: @".servo5" ]] ; int pos = ( int ) atol ( argv [ 2 ]) ; if ([ servo1 isOnline ]) {
[ servo1 set_position:pos ] ;
// immediate switch
[ servo5 move:pos: 3000 ] ;
// smooth transition
} else {
NSLog ( @"Module not connected (check identification and USB cable)
\n"
) ;
}
} return 0 ;
}
Il n'y a que peu de lignes véritablement importantes dans le code précédent. Nous allons les expliquer en détail.
yocto_api.h et yocto_servo.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_servo.h
est nécessaire pour gérer les modules contenant un servo, comme le Yocto-Servo.
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.
yFindServo
La fonction yFindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):
YServo *servo = yFindServo ( @"SERVORC1-123456.servo1" ) ;
YServo *servo = yFindServo ( @"SERVORC1-123456.MaFonction" ) ;
www.yoctopuce.com
10. Utilisation du Yocto-Servo en Objective-C
YServo *servo = yFindServo ( @"MonModule.servo1" ) ;
YServo *servo = yFindServo ( @"MonModule.MaFonction" ) ;
YServo *servo = yFindServo ( @"MaFonction" ) ; yFindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
isOnline
La méthode isOnline()
de l'objet renvoyé par correspondant est présent et en état de marche.
yFindServo
permet de savoir si le module
set_position
La méthode set_position()
de l'objet renvoyé par yFindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur 0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par yFindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
10.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 ]] ;
YModule *module = [ YModule FindModule:serial_or_name ] ;
// use serial or logical 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: %d sec \n" , [ module upTime ] / 1000 ) ;
NSLog ( @"USB current: %d mA \n" , [ module usbCurrent ]) ;
NSLog ( @"logs: %@ \n" , [ module get_lastLogs ]) ;
} else {
www.yoctopuce.com
59
10. Utilisation du Yocto-Servo en Objective-C
60
NSLog ( @"%@ not connected (check identification and USB cable) \n" ,serial_or_name
) ;
}
} 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( yRegisterHub ( @"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 ]] ;
YModule *module = yFindModule ( serial_or_name ) ;
// use serial or logical name
if ( module.isOnline
) { if ( argc >= 3 ){
NSString *newname = [ NSString stringWithUTF8String:argv [ 2 ]] ; if ( !yCheckLogicalName
( 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
) ;
}
} 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
www.yoctopuce.com
10. Utilisation du Yocto-Servo en Objective-C
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() trouver les modules suivants, et ce tant que la réponse n'est pas un
NULL
de cet objet pour
. 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( yRegisterHub ( @"usb" , &error ) != YAPI_SUCCESS ) {
NSLog ( @"RegisterHub error: %@
\n"
, [ error localizedDescription ]) ; return 1 ;
}
NSLog ( @"Device list: \n" ) ;
YModule *module = yFirstModule () ; while ( module != nil ) {
NSLog ( @"%@ %@" ,module.serialNumber, module.productName
) ;
module = [ module nextModule ] ;
}
} return 0 ;
}
10.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 cidessous.
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:
• Si votre code attrape l'exception au vol et la gère, et tout se passe bien.
• Si votre programme tourne dans le debugger, vous pourrez relativement facilement déterminer où le problème s'est produit, et voir le message explicatif lié à l'exception.
• Sinon... l'exception va crasher votre programme, boum!
www.yoctopuce.com
61
10. Utilisation du Yocto-Servo en Objective-C
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 yDisableExceptions()
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 méthode get_state() get_currentValue
retournera une valeur
retournera une valeur
Y_STATE_INVALID
Y_CURRENTVALUE_INVALID
, une
, 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.
62 www.yoctopuce.com
11. Utilisation du Yocto-Servo 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#. Tous les exemples et les modèles de projet sont testés avec Microsoft Visual Basic 2010 Express, disponible gratuitement sur le site de Microsoft
1
.
11.1. Installation
Téléchargez la librairie Yoctopuce pour Visual Basic depuis le site web de Yoctopuce
2
. 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.
11.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 modules
3
. 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.
1 http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-basic-express
2 www.yoctopuce.com/FR/libraries.php
3
Les sources de cette DLL sont disponibles dans l'API C++
www.yoctopuce.com
63
11. Utilisation du Yocto-Servo en VisualBasic .NET
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 dll
4 yapi.dll
, qui se trouve dans le répertoire
Sources/
. 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.
11.3. Contrôle de la fonction Servo
Il suffit de quelques lignes de code pour piloter un Yocto-Servo. Voici le squelette d'un fragment de code VisualBasic .NET qui utilise la fonction Servo.
[ ...
]
Dim errmsg As String
Dim servo As YServo
REM On récupère l'objet représentant le module (ici connecté en local sur USB)
yRegisterHub ( "usb" , errmsg ) servo = yFindServo ( "SERVORC1-123456.servo1" )
REM Pour gérer le hot-plug, on vérifie que le module est là
If ( servo.
isOnline ()) Then
REM Utiliser servo.set_position(), ...
End If
Voyons maintenant en détail ce que font ces quelques lignes.
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.
yFindServo
La fonction yFindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté): servo = yFindServo ( "SERVORC1-123456.servo1" ) servo = yFindServo ( "SERVORC1-123456.MaFonction" ) servo = yFindServo ( "MonModule.servo1" ) servo = yFindServo ( "MonModule.MaFonction" ) servo = yFindServo ( "MaFonction" ) yFindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
64
4
Pensez à changer le filtre de la fenêtre de sélection de fichiers, sinon la DLL n'apparaîtra pas
www.yoctopuce.com
11. Utilisation du Yocto-Servo en VisualBasic .NET
isOnline
La méthode isOnline()
de l'objet renvoyé par correspondant est présent et en état de marche.
yFindServo
permet de savoir si le module
set_position
La méthode set_position()
de l'objet renvoyé par yFindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur 0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par yFindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
Un exemple réel
Lancez Microsoft VisualBasic et ouvrez le projet exemple correspondant, fourni dans le répertoire
Examples/Doc-GettingStarted-Yocto-Servo 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> [ -1000 | ... | 1000 ]" )
Console .
WriteLine ( execname+ " <logical_name> [ -1000 | ... | 1000 ]" )
Console .
WriteLine ( execname+ " any [ -1000 | ... | 1000 ]" )
System.
Threading .
Thread .
Sleep ( 2500 )
End
End Sub
Sub Main ()
Dim argv () As String = System .
Environment .
GetCommandLineArgs ()
Dim errmsg As String = ""
Dim target As String
Dim servo1 As YServo
Dim servo5 As YServo
Dim pos As Integer
If argv.
Length < 3 Then Usage ()
target = argv ( 1 )
pos = CInt ( argv ( 2 ))
REM Setup the API to use local USB devices
If ( yRegisterHub ( "usb" , errmsg ) <> YAPI_SUCCESS ) Then
Console .
WriteLine ( "RegisterHub error: " + errmsg )
End
End If
If target = "any" Then
servo1 = yFirstServo ()
If servo1 Is Nothing Then
Console .
WriteLine ( "No module connected (check USB cable) " )
End
End If
target = servo1.
get_Module () .
get_serialNumber ()
End If
servo1 = yFindServo ( target + ".servo1" )
servo5 = yFindServo ( target + ".servo5" )
If ( servo1.
isOnline ()) Then
servo1.
set_position ( pos )
servo5.
move ( pos, 3000 )
Else
Console .
WriteLine ( "Module not connected (check identification and USB cable)" )
End If
www.yoctopuce.com
65
11. Utilisation du Yocto-Servo en VisualBasic .NET
End Sub
End Module
11.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 ( yRegisterHub ( "usb" , errmsg ) <> YAPI_SUCCESS ) Then
Console .
WriteLine ( "RegisterHub error:" + errmsg )
End
End If
If argv.
Length < 2 Then usage ()
m = yFindModule ( 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
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
66 www.yoctopuce.com
11. Utilisation du Yocto-Servo en VisualBasic .NET
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 yRegisterHub ( "usb" , errmsg ) <> YAPI_SUCCESS Then
Console .
WriteLine ( "RegisterHub error: " + errmsg )
End
End If
m = yFindModule ( argv ( 1 ))
REM use serial or logical name
If m.
isOnline () Then
newname = argv ( 2 )
If (Not yCheckLogicalName ( 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
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 exemple listant les module connectés
Nothing
. Ci-dessous un petit
Module Module1
www.yoctopuce.com
67
11. Utilisation du Yocto-Servo en VisualBasic .NET
68
Sub Main ()
Dim M As ymodule
Dim errmsg As String = ""
REM Setup the API to use local USB devices
If yRegisterHub ( "usb" , errmsg ) <> YAPI_SUCCESS Then
Console .
WriteLine ( "RegisterHub error: " + errmsg )
End
End If
Console .
WriteLine ( "Device list" )
M = yFirstModule ()
While M IsNot Nothing
Console .
WriteLine ( M.
get_serialNumber () + " (" + M.
get_productName () + ")" )
M = M.
nextModule ()
End While
End Sub
End Module
11.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 cidessous.
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:
• Si votre code attrape l'exception au vol et la gère, et tout se passe bien.
• Si votre programme tourne dans le debugger, vous pourrez relativement facilement déterminer où le problème s'est produit, et voir le message explicatif lié à l'exception.
• Sinon... l'exception va crasher votre programme, boum!
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 yDisableExceptions()
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
Y_STATE_INVALID
, une méthode get_currentValue
retournera une valeur
Y_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.
www.yoctopuce.com
11. Utilisation du Yocto-Servo en VisualBasic .NET
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.
www.yoctopuce.com
69
70 www.yoctopuce.com
12. Utilisation du Yocto-Servo 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. Tous les exemples et les modèles de projet sont testés avec Microsoft C#
2010 Express, disponible gratuitement sur le site de Microsoft
1
.
12.1. Installation
Téléchargez la librairie Yoctopuce pour Visual C# depuis le site web de Yoctopuce
2
. 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.
12.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 modules
3
. 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.
1 http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-csharp-express
2 www.yoctopuce.com/FR/libraries.php
3
Les sources de cette DLL sont disponibles dans l'API C++
www.yoctopuce.com
71
12. Utilisation du Yocto-Servo en C#
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 dll
4 yapi.dll
, qui se trouve dans le répertoire
Sources/
. 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.
12.3. Contrôle de la fonction Servo
Il suffit de quelques lignes de code pour piloter un Yocto-Servo. Voici le squelette d'un fragment de code C# qui utilise la fonction Servo.
[ ...
] string errmsg = "" ;
YServo servo;
// On récupère l'objet représentant le module (ici connecté en local sur USB)
YAPI.
RegisterHub ( "usb" , errmsg ) ; servo = YServo.
FindServo ( "SERVORC1-123456.servo1" ) ;
// Pour gérer le hot-plug, on vérifie que le module est là
if ( servo.
isOnline ())
{
// Utiliser servo.set_position(): ...
}
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.
YServo.FindServo
La fonction
YServo.FindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents
(pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté): servo = YServo.
FindServo ( "SERVORC1-123456.servo1" ) ; servo = YServo.
FindServo ( "SERVORC1-123456.MaFonction" ) ; servo = YServo.
FindServo ( "MonModule.servo1" ) ; servo = YServo.
FindServo ( "MonModule.MaFonction" ) ; servo = YServo.
FindServo ( "MaFonction" ) ;
YServo.FindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
72
4
Pensez à changer le filtre de la fenêtre de sélection de fichiers, sinon la DLL n'apparaîtra pas
www.yoctopuce.com
12. Utilisation du Yocto-Servo en C#
isOnline
La méthode
YServo.isOnline()
de l'objet renvoyé par module correspondant est présent et en état de marche.
FindServo
permet de savoir si le
set_position
La méthode set_position()
de l'objet renvoyé par
YServo.FindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur
0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par
YServo.FindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
Un exemple réel
Lancez Visual C# et ouvrez le projet exemple correspondant, fourni dans le répertoire Examples/
Doc-GettingStarted-Yocto-Servo 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 ; 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_number> [ -1000 | ... | 1000 ]" ) ;
Console .
WriteLine ( execname+ " <logical_name> [ -1000 | ... | 1000 ]" ) ;
Console .
WriteLine ( execname+ " any [ -1000 | ... | 1000 ]" ) ;
System.
Threading .
Thread .
Sleep ( 2500 ) ;
Environment .
Exit ( 0 ) ;
} static void Main ( string [] args )
{ string errmsg = "" ; string target;
YServo servo1;
YServo servo5; int pos; if ( args.
Length < 2 ) usage () ;
target = args [ 0 ] .
ToUpper () ;
pos = Convert.
ToInt32 ( args [ 1 ]) ; if ( YAPI.
RegisterHub ( "usb" , ref errmsg ) != YAPI.
SUCCESS )
{
Console .
WriteLine ( "RegisterHub error: " + errmsg ) ;
Environment .
Exit ( 0 ) ;
} if ( target == "ANY" )
{
servo1 = YServo.
FirstServo () ; if ( servo1 == null )
{
Console .
WriteLine ( "No module connected (check USB cable) " ) ;
Environment .
Exit ( 0 ) ;
}
target = servo1.
get_module () .
get_serialNumber () ;
}
servo1 = YServo.
FindServo ( target + ".servo1" ) ;
www.yoctopuce.com
73
12. Utilisation du Yocto-Servo en C#
servo5 = YServo.
FindServo ( target + ".servo5" ) ; if ( servo1.
isOnline ())
{
servo1.
set_position ( pos ) ;
servo5.
move ( pos, 3000 ) ;
} else
Console .
WriteLine ( "Module not connected (check identification and USB cable)" ) ;
}
}
}
12.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 ()) ;
74 www.yoctopuce.com
12. Utilisation du Yocto-Servo en C#
} else
Console .
WriteLine ( args [ 0 ] + " not connected (check identification and USB cable)" ) ;
}
}
}
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
www.yoctopuce.com
75
12. Utilisation du Yocto-Servo en C#
}
Console .
Write ( "not connected (check identification and USB cable" ) ;
}
}
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 () ;
}
}
}
}
12.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
76 www.yoctopuce.com
12. Utilisation du Yocto-Servo en C#
manière de l'éviter est d'implémenter une des deux techniques de gestion des erreurs décrites cidessous.
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:
• Si votre code attrape l'exception au vol et la gère, et tout se passe bien.
• Si votre programme tourne dans le debugger, vous pourrez relativement facilement déterminer où le problème s'est produit, et voir le message explicatif lié à l'exception.
• Sinon... l'exception va crasher votre programme, boum!
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 yDisableExceptions()
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
Y_STATE_INVALID
, une méthode get_currentValue
retournera une valeur
Y_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.
www.yoctopuce.com
77
78 www.yoctopuce.com
13. Utilisation du Yocto-Servo en Delphi
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 payant
1
.
Les librairies pour Delphi sont fournies non pas sous forme de composants VCL, mais directement sous forme de fichiers source. Ces fichiers sont compatibles avec la plupart des version de Delphi
2
.
Afin des 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 VCL.
Vous allez rapidement vous rendre compte que l'API Delphi défini 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.
13.1. Préparation
Connectez-vous sur le site de Yoctopuce et téléchargez la la librairie Yoctopuce pour Delphi
3
.
Décompressez le tout dans le répertoire de votre choix, et ajoutez le sous-répertoire sources de l'archive dans la liste des répertoires des librairies de Delphi
4
.
Par défaut la librairie Yoctopuce pour Delphi utilise une DLL yapi.dll, toutes les applications que vous créerez avec Delphi devront avoir accès à cette DLL. Le plus simple est de faire en sorte qu'elle soit présente dans le même répertoire que l'exécutable de votre application.
13.2. Contrôle de la fonction Servo
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.
program helloworld;
{$APPTYPE CONSOLE} uses
1
En fait, Borland a diffusé des versions gratuites (pour usage personnel) de Delphi 2006 et Delphi 2007, en cherchant un peu sur internet il est encore possible de les télécharger.
2
3
Les librairies Delphi sont régulièrement testées avec Delphi 5 et Delphi XE2
4 www.yoctopuce.com/FR/libraries.php
Utilisez le menu outils / options d'environement
www.yoctopuce.com
79
13. Utilisation du Yocto-Servo en Delphi
80
SysUtils,
yocto_api,
yocto_servo; procedure usage () ; var
execname: string ; begin
execname := ExtractFileName ( paramstr ( 0 )) ;
WriteLn ( 'Usage:' ) ;
WriteLn ( execname + ' <serial_number> <channel> position' ) ;
WriteLn ( execname + ' <logical_name> <channel> position' ) ;
WriteLn ( execname + ' any <channel> position' ) ;
WriteLn ( 'Example:' ) ;
WriteLn ( execname + ' any 2 1000' ) ; sleep ( 2500 ) ; halt ; end ; var
errmsg,target,channel: string ;
position: integer ;
servo:TYservo;
m : TYModule; begin if ( paramcount< 3 ) then usage () ;
target := UpperCase ( paramstr ( 1 )) ;
channel := paramstr ( 2 ) ;
position := StrToInt ( paramstr ( 3 )) ; if ( YRegisterHub ( 'usb' , errmsg ) <> YAPI_SUCCESS ) then begin writeln ( 'RegisterHub error: ' + errmsg ) ; halt ; end ; if ( target= 'ANY' ) then begin
servo := YFirstServo () ; if ( servo = nil ) then begin writeln ( 'No module connected (check USB cable)' ) ; halt ; end ;
m := servo.
get_module () ;
target := m. get_serialNumber () ; end ;
Writeln ( 'using ' + target ) ;
servo := YFindServo ( target + '.servo' +channel ) ; if ( servo.
isOnline ()) then servo.
move ( position, 1500 ) else writeln ( 'Module not connected (check identification and USB cable)' ) ; end .
Il n'y a que peu de lignes véritablement importantes dans le code précédent. Nous allons les expliquer en détail.
yocto_api et yocto_servo
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_servo
est nécessaire pour gérer les modules contenant un servo, comme le Yocto-Servo.
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.
www.yoctopuce.com
13. Utilisation du Yocto-Servo en Delphi
yFindServo
La fonction yFindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté): servo := yFindServo ( "SERVORC1123456 .
servo1 " ) ; servo := yFindServo ( "SERVORC1123456 .
MaFonction " ) ; servo := yFindServo ( "MonModule.
servo1 " ) ; servo := yFindServo ( "MonModule.
MaFonction " ) ; servo := yFindServo ( "MaFonction" ) ; yFindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
isOnline
La méthode isOnline()
de l'objet renvoyé par yFindServo
permet de savoir si le module correspondant est présent et en état de marche.
set_position
La méthode set_position()
de l'objet renvoyé par yFindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur 0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par yFindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
13.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 = 'SERVORC1-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 ;
www.yoctopuce.com
81
13. Utilisation du Yocto-Servo en Delphi
82
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' ; 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 = 'SERVORC1-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)' ) ;
www.yoctopuce.com
13. Utilisation du Yocto-Servo en Delphi
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 () ;
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() trouver les modules suivants, et ce tant que la réponse n'est pas un nil
de cet objet pour
. 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 ; end .
13.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.
www.yoctopuce.com
83
13. Utilisation du Yocto-Servo en Delphi
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 cidessous.
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:
• Si votre code attrape l'exception au vol et la gère, et tout se passe bien.
• Si votre programme tourne dans le debugger, vous pourrez relativement facilement déterminer où le problème s'est produit, et voir le message explicatif lié à l'exception.
• Sinon... l'exception va crasher votre programme, boum!
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 yDisableExceptions()
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
Y_STATE_INVALID
, une méthode get_currentValue
retournera une valeur
Y_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.
84 www.yoctopuce.com
14. Utilisation du Yocto-Servo 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.6+ et 3+. Elle fonctionne sous Windows, Max OS X et Linux tant Intel qu'ARM. La librairie a été testée avec Python 2.6 et Python 3.2. Les interpréteurs Python sont disponibles sur le site de Python
1
.
14.1. Fichiers sources
Les classes de la librairie Yoctopuce
2
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.
14.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 Mac OS X. 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.
1 http://www.python.org/download/
2 www.yoctopuce.com/FR/libraries.php
www.yoctopuce.com
85
14. Utilisation du Yocto-Servo en Python
86
14.3. Contrôle de la fonction Servo
Il suffit de quelques lignes de code pour piloter un Yocto-Servo. Voici le squelette d'un fragment de code Python qui utilise la fonction Servo.
[ ...
] errmsg=YRefParam ()
#On récupère l'objet représentant le module (ici connecté en local sur USB)
YAPI.
RegisterHub ( "usb" ,errmsg ) servo = YServo.
FindServo ( "SERVORC1-123456.servo1" )
#Pour gérer le hot-plug, on vérifie que le module est là
if servo.
isOnline () :
#Use servo.set_position()
...
[ ...
]
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.
YServo.FindServo
La fonction
YServo.FindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents
(pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté): servo = YServo.
FindServo ( "SERVORC1-123456.servo1" ) servo = YServo.
FindServo ( "SERVORC1-123456.MaFonction" ) servo = YServo.
FindServo ( "MonModule.servo1" ) servo = YServo.
FindServo ( "MonModule.MaFonction" ) servo = YServo.
FindServo ( "MaFonction" )
YServo.FindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
isOnline
La méthode
YServo.isOnline()
de l'objet renvoyé par
FindServo
permet de savoir si le module correspondant est présent et en état de marche.
set_position
La méthode set_position()
de l'objet renvoyé par
YServo.FindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur
0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par
YServo.FindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
Un exemple réel
Lancez votre interpréteur Python et ouvrez le script correspondant, fourni dans le répertoire
Examples/Doc-GettingStarted-Yocto-Servo de la librairie Yoctopuce.
www.yoctopuce.com
14. Utilisation du Yocto-Servo en Python
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 from yocto_api import * from yocto_servo import * def usage () :
scriptname = os .
path .
basename ( sys .
argv [ 0 ]) print( "Usage:" ) print( scriptname + ' <serial_number> <channel> position' ) print( scriptname + ' <logical_name> <channel> position' ) print( scriptname + ' any <channel> position' ) print( 'Example:' ) print( scriptname + ' any 2 500' ) sys .
exit () def die ( msg ) : sys .
exit ( msg+ ' (check USB cable)' ) if len ( sys .
argv ) < 3 : usage () target= sys .
argv [ 1 ] .
upper () channel= sys .
argv [ 2 ] position= int ( sys .
argv [ 3 ])
# 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' :
# retreive any servo then find its serial #
servo = YServo.
FirstServo () if servo is None : die ( 'No module connected' )
m=servo.
get_module ()
target = m.
get_serialNumber () print( 'using ' + target ) servo = YServo.
FindServo ( target + '.servo' +channel ) if not( servo.
isOnline ()) :die ( 'device not connected' ) servo.
move ( position, 1000 )
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.
#!/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 () :
www.yoctopuce.com
87
14. Utilisation du Yocto-Servo en Python
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)" )
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() vous permet changer le nom logique d'un module.
. Ce petit exemple ci-dessous
#!/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" )
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.
88 www.yoctopuce.com
14. Utilisation du Yocto-Servo en Python
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 ()
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 cidessous.
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:
• Si votre code attrape l'exception au vol et la gère, et tout se passe bien.
• Si votre programme tourne dans le debugger, vous pourrez relativement facilement déterminer où le problème s'est produit, et voir le message explicatif lié à l'exception.
• Sinon... l'exception va crasher votre programme, boum!
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 yDisableExceptions()
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
Y_STATE_INVALID
, une méthode get_currentValue
retournera une valeur
Y_CURRENTVALUE_INVALID
, etc. Dans
www.yoctopuce.com
89
14. Utilisation du Yocto-Servo en Python
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.
90 www.yoctopuce.com
15. Utilisation du Yocto-Servo 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 d'un VirtualHub pour pouvoir communiquer avec les modules Yoctopuce.
15.1. Préparation
Connectez vous sur le site de Yoctopuce et téléchargez les éléments suivants:
• La librairie de programmation pour Java
• Le programme VirtualHub
2
1
pour Windows, Mac OS X ou Linux selon l'OS que vous utilisez
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 le programme VirtualHub, et vous pouvez commencer vos premiers test. 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.
15.2. Contrôle de la fonction Servo
Il suffit de quelques lignes de code pour piloter un Yocto-Servo. Voici le squelette d'un fragment de code Java qui utilise la fonction Servo.
[ ...
]
// On récupère l'objet représentant le module (ici connecté en local sur USB)
YAPI.
RegisterHub ( "127.0.0.1" ) ; servo = YServo.
FindServo ( "SERVORC1-123456.servo1" ) ;
//Pour gérer le hot-plug, on vérifie que le module est là
if ( servo.
isOnline ())
{
//Use servo.set_position()
...
1 www.yoctopuce.com/FR/libraries.php
2 www.yoctopuce.com/FR/virtualhub.php
www.yoctopuce.com
91
15. Utilisation du Yocto-Servo en Java
92
}
[ ...
]
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.
YServo.FindServo
La fonction
YServo.FindServo
, permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents
(pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté): servo = YServo.
FindServo ( "SERVORC1-123456.servo1" ) servo = YServo.
FindServo ( "SERVORC1-123456.MaFonction" ) servo = YServo.
FindServo ( "MonModule.servo1" ) servo = YServo.
FindServo ( "MonModule.MaFonction" ) servo = YServo.
FindServo ( "MaFonction" )
YServo.FindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
isOnline
La méthode
YServo.isOnline()
de l'objet renvoyé par module correspondant est présent et en état de marche.
FindServo
permet de savoir si le
set_position
La méthode set_position()
de l'objet renvoyé par
YServo.FindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur
0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
move
La méthode move()
de l'objet renvoyé par
YServo.FindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
Un exemple réel
Lancez votre environnement java et ouvrez le projet correspondant, fourni dans le répertoire
Examples/Doc-GettingStarted-Yocto-Servo 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.* ; 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 ) ;
}
www.yoctopuce.com
15. Utilisation du Yocto-Servo en Java
String serial = "" ; if ( args.
length > 0 ) {
serial = args [ 0 ] ;
} else {
YServo tmp = YServo.
FirstServo () ; if ( tmp == null ) {
System .
out .
println ( "No module connected (check USB cable)" ) ;
System .
exit ( 1 ) ;
} try {
serial = tmp.
module () .
get_serialNumber () ;
} catch ( YAPI_Exception ex ) {
System .
out .
println ( "No module connected (check USB cable)" ) ;
System .
exit ( 1 ) ;
}
}
YServo servo1 = YServo.
FindServo ( serial + ".servo1" ) ;
YServo servo5 = YServo.
FindServo ( serial + ".servo5" ) ; int pos [] = { 1000 , 1000 , 0 } ; for( int p : pos ) { try {
System .
out .
println ( String .
format ( "Change postition to %d" , p )) ;
servo1.
set_position ( p ) ;
//imediat transition
servo5.
move ( p, 1000 ) ;
// smooth transition
YAPI.
Sleep ( 1000 ) ;
} catch ( YAPI_Exception ex ) {
System .
out .
println ( "Module not connected (check identification and USB cable)" ) ; break ;
}
}
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.
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 ) ;
}
www.yoctopuce.com
93
15. Utilisation du Yocto-Servo en Java
} 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() vous permet changer le nom logique d'un module.
. Ce petit exemple ci-dessous 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
94 www.yoctopuce.com
15. Utilisation du Yocto-Servo en Java
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 () ;
}
}
www.yoctopuce.com
95
15. Utilisation du Yocto-Servo en Java
15.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.
96 www.yoctopuce.com
16. Utilisation du Yocto-Servo 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.
16.1. Accès Natif et Virtual Hub.
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 à un VirtualHub tournant sur un autre OS.
16.2. Préparation
Connectez-vous sur le site de Yoctopuce et téléchargez la librairie de programmation pour Java pour
Android
1
. 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.
16.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.
1 www.yoctopuce.com/FR/libraries.php
www.yoctopuce.com
97
16. Utilisation du Yocto-Servo avec Android
Android 4.x
Android 4.0 (api 14) et suivants sont officiellement supportés. Théoriquement le support USB host fonctionne depuis Android 3.1. Mais sachez que Yoctopuce ne teste régulièrement l'API Java pour
Android qu'à partir de Android 4.
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.
Matériel supporté
La librairie est testée et validée sur les machines suivantes:
• Samsung Galaxy S3
• Samsung Galaxy Note 2
• Google Nexus 5
• Google Nexus 7
• Acer Iconia Tab A200
• Asus Tranformer Pad TF300T
• Kurio 7
Si votre machine Android n'est pas capable de faire fonctionner nativement des modules Yoctopuce, il vous reste tout de même la possibilité de contrôler à distance des modules pilotés par un
VirtualHub sur un autre OS ou un YoctoHub
2
.
16.4. Activer le port USB sous Android
Par défaut Android nautorise 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" />;
...
98
2
Les YoctoHub sont un moyen simple et efficace d'ajouter une connectivité réseau à vos modules Yoctopuce. http:// www.yoctopuce.com/FR/products/category/extensions-et-reseau
www.yoctopuce.com
16. Utilisation du Yocto-Servo avec Android
</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 laccè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
Comme la classe Activity est une sous-classe de
Context
(ou d'une sous-classe).
, 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>
www.yoctopuce.com
99
16. Utilisation du Yocto-Servo avec Android
16.5. Contrôle de la fonction Servo
Il suffit de quelques lignes de code pour piloter un Yocto-Servo. Voici le squelette d'un fragment de code Java qui utilise la fonction Servo.
[ ...
]
// On récupère l'objet représentant le module (ici connecté en local sur USB)
YAPI.
EnableUSBHost (this) ;
YAPI.
RegisterHub ( "usb" ) ; servo = YServo.
FindServo ( "SERVORC1-123456.servo1" ) ;
//Pour gérer le hot-plug, on vérifie que le module est là
if ( servo.
isOnline ())
{
//Use servo.set_position()
...
}
[ ...
]
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 sousclasse). 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.
YServo.FindServo
La fonction
YServo.FindServo
permet de retrouver un servo 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-Servo avec le numéros de série SERVORC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction servo1 "MaFonction", les cinq appels suivants seront strictement équivalents
(pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté): servo = YServo.
FindServo ( "SERVORC1-123456.servo1" ) servo = YServo.
FindServo ( "SERVORC1-123456.MaFonction" ) servo = YServo.
FindServo ( "MonModule.servo1" ) servo = YServo.
FindServo ( "MonModule.MaFonction" ) servo = YServo.
FindServo ( "MaFonction" )
YServo.FindServo
renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler le servo.
isOnline
La méthode
YServo.isOnline()
de l'objet renvoyé par module correspondant est présent et en état de marche.
FindServo
permet de savoir si le
set_position
La méthode set_position()
de l'objet renvoyé par
YServo.FindServo
permet de déplacer le plus rapidement possible le servo vers la position spécifiée. Le point milieu correspond à la valeur
0, et les deux extrémités correspondent aux valeurs -1000 et 1000.
100 www.yoctopuce.com
16. Utilisation du Yocto-Servo avec Android
move
La méthode move()
de l'objet renvoyé par
YServo.FindServo
permet d'effectuer le déplacement vers une position désirée en un intervalle de temps contrôlé, spécifié en millisecondes.
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.SeekBar
; import android.widget.Spinner
; import com.yoctopuce.YoctoAPI.YAPI
; import com.yoctopuce.YoctoAPI.YAPI_Exception
; import com.yoctopuce.YoctoAPI.YServo
; public class GettingStarted_Yocto_Servo extends Activity implements OnItemSelectedListener
{ private YServo servo = null ; private ArrayAdapter<String> aa;
@Override public void onCreate ( Bundle savedInstanceState )
{ super .
onCreate ( savedInstanceState ) ;
setContentView ( R.
layout .
gettingstarted_yocto_servo ) ;
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 () ;
aa.
clear () ; try {
YAPI.
EnableUSBHost (this) ;
YAPI.
RegisterHub ( "usb" ) ;
YServo s = YServo.
FirstServo () ; while ( s != null ) {
String hwid = s.
get_hardwareId () ;
aa.
add ( hwid ) ;
s = s.
nextServo () ;
}
} catch ( YAPI_Exception e ) {
e.
printStackTrace () ;
}
aa.
notifyDataSetChanged () ;
}
@Override protected void onStop ()
{ super .
onStop () ;
YAPI.
FreeAPI () ;
}
@Override public void onItemSelected ( AdapterView<?> parent, View view, int pos, long id )
{
www.yoctopuce.com
101
16. Utilisation du Yocto-Servo avec Android
String hwid = parent.
getItemAtPosition ( pos ) .
toString () ;
servo = YServo.
FindServo ( hwid ) ;
}
@Override public void onNothingSelected ( AdapterView<?> arg0 )
{
}
/** Called when the user touches the button State A */
public void updatePos ( View view )
{ if ( servo == null ) return ;
SeekBar bar = ( SeekBar ) findViewById ( R.
id .
seekBarPos ) ; int newpow = bar.
getProgress () * 2000 / bar.
getMax () - 1000 ; switch ( view.
getId ()) { case R.
id .
movePosButton : try {
servo.
move ( newpow, 1000 ) ;
} catch ( YAPI_Exception e ) {
e.
printStackTrace () ;
} break ; case R.
id .
setPosButton : try {
servo.
set_position ( newpow ) ;
} catch ( YAPI_Exception e ) {
e.
printStackTrace () ;
} break ;
}
}
}
16.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.util.Log
; 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 ) ;
102 www.yoctopuce.com
16. Utilisation du Yocto-Servo avec Android
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 ) ;
Log.
d ( "switch" , "beacon" + module.
get_beacon ()) ;
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 () ;
www.yoctopuce.com
103
16. Utilisation du Yocto-Servo avec Android
} 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() vous permet changer le nom logique d'un module.
. Ce petit exemple ci-dessous 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 ()
104 www.yoctopuce.com
16. Utilisation du Yocto-Servo avec Android
{ 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 () ;
}
www.yoctopuce.com
105
16. Utilisation du Yocto-Servo avec Android
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.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 ) ;
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 () ;
106 www.yoctopuce.com
16. Utilisation du Yocto-Servo avec Android
}
}
16.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.
www.yoctopuce.com
107
108 www.yoctopuce.com
17. 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-Servo. 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.
17.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 )
www.yoctopuce.com
109
17. Programmation avancée
{
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 suffit d'appeler
UpdateDeviceList()
UpdateDeviceList()
. Il vous
à 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.
110 www.yoctopuce.com
18. 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é.
18.1. 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.
18.2. 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.
www.yoctopuce.com
111
18. Utilisation avec des langages non supportés
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-Servo avec le numéro de de série SERVORC1-12345 et le nom logique
monModule. l'URL suivante permettra de connaître l'état du module.
http://127.0.0.1:4444/bySerial/SERVORC1-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/SERVORC1-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/SERVORC1-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 servo1, il suffit de construire l'URL suivante.
http://127.0.0.1:4444/bySerial/SERVORC1-12345/api/servo1.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/SERVORC1-12345/api/servo1/logicalName
Assez logiquement, les attributs peuvent être modifiés de la même manière.
http://127.0.0.1:4444/bySerial/SERVORC1-12345/api/servo1?logicalName=maFonction
Vous trouverez la liste des attributs disponibles pour votre Yocto-Servo au début du chapitre
Programmation, concepts généraux.
112 www.yoctopuce.com
18. Utilisation avec des langages non supportés
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/SERVORC1-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/SERVORC1-12345/dataLogger.json?id=servo1 &utc=1389801080
18.3. 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.
Filename
libyapi.dylib
libyapi-amd64.so
libyapi-armel.so
libyapi-armhf.so
libyapi-i386.so
Plateforme
Max OS X
Linux Intel (64 bits)
Linux ARM EL
Linux ARM HL
Linux Intel (32 bits) yapi64.dll
yapi.dll
Windows (64 bits)
Windows (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
www.yoctopuce.com
113
18. Utilisation avec des langages non supportés
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 = 'SERVORC1-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 ) -p3 )) ;
// change the luminosity
if ( yapiHTTPRequest ( serial,setValue,data, sizeof ( dataBuffer ) ,fullsize,errmsg ) < 0 ) then begin writeln ( errmsg ) ; halt ; end ; end .
114 www.yoctopuce.com
18. Utilisation avec des langages non supportés
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
vendorid deviceid devrelease
Type
int int int
Taille
(bytes)
Description
4
4
4
ID USB de Yoctopuce
ID USB du module
Version du module nbinbterfaces int 4 Nombre d'interfaces USB utilisée par le module manufacturer char[] 20 Yoctopuce (null terminé) productname char[] 28 Modèle (null terminé) serial char[] 20 Numéro de série (null terminé) logicalname char[] 20 Nom logique (null terminé) firmware char[] 22 Version du firmware (null terminé) beacon byte 1 Etat 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' ;
www.yoctopuce.com
115
18. Utilisation avec des langages non supportés
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 .
18.4. 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.
116 www.yoctopuce.com
19. 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-Servo. 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.
www.yoctopuce.com
117
19. Référence de l'API de haut niveau
19.1. 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: js nodejs php cpp m
<script type='text/javascript' src='yocto_api.js'></script> var yoctolib = require('yoctolib'); var YAPI = yoctolib.YAPI; var YModule = yoctolib.YModule; require_once('yocto_api.php');
#include "yocto_api.h"
#import "yocto_api.h" pas vb cs java py uses yocto_api; yocto_api.vb
yocto_api.cs
import com.yoctopuce.YoctoAPI.YModule; from yocto_api import *
Fonction globales
name
)
Vérifie si un nom donné est valide comme nom logique pour un module ou une fonction.
Désactive l'utilisation d'exceptions pour la gestion des erreurs.
Réactive l'utilisation d'exceptions pour la gestion des erreurs.
osContext
)
Cette fonction est utilisée uniquement sous Android.
Libère la mémoire dynamique utilisée par la librairie Yoctopuce.
Retourne la version de la librairie Yoctopuce utilisée.
Retourne la valeur du compteur monotone de temps (en millisecondes).
errmsg
)
Maintient la communication de la librairie avec les modules Yoctopuce.
mode
,
errmsg
)
Initialise la librairie de programmation de Yoctopuce explicitement.
url
,
errmsg
)
Alternative plus tolerante à RegisterHub().
yRegisterDeviceArrivalCallback(
arrivalCallback
)
Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est branché.
yRegisterDeviceRemovalCallback(
removalCallback
)
Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est débranché.
url
,
errmsg
)
Configure la librairie Yoctopuce pour utiliser les modules connectés sur une machine donnée.
yRegisterHubDiscoveryCallback(
callback
)
118 www.yoctopuce.com
19. Référence de l'API de haut niveau
Enregistre une fonction de callback qui sera appelée à chaque fois qu'un Hub réseau ou un VirtualHub est détecté sur le réseau local.
logfun
)
Enregistre une fonction de callback qui sera appellée à chaque fois que l'API a quelque chose à dire.
arch
)
Sélectionne manuellement l'architecture de la libraire dynamique à utiliser pour accéder à USB.
object
)
(Objective-C uniquement) Enregistre un objet délégué qui doit se conformer au procole
YDeviceHotPlug .
callback
,
ms_timeout
,
arguments
)
Appelle le callback spécifié après un temps d'attente spécifié.
ms_duration
,
errmsg
)
Effectue une pause dans l'exécution du programme pour une durée spécifiée.
url
)
Configure la librairie Yoctopuce pour ne plus utiliser les modules connectés sur une machine préalablement enregistrer avec RegisterHub.
errmsg
)
Force une mise-à-jour de la liste des modules Yoctopuce connectés.
callback
,
context
)
Force une mise-à-jour de la liste des modules Yoctopuce connectés.
www.yoctopuce.com
119
19. Référence de l'API de haut niveau
YAPI.CheckLogicalName() yCheckLogicalName()
YAPI
Vérifie si un nom donné est valide comme nom logique pour un module ou une fonction.
js function yCheckLogicalName(
name
) nodejs function CheckLogicalName(
name
) php cpp m pas function yCheckLogicalName(
$name
) bool yCheckLogicalName( const string&
name
)
BOOL yCheckLogicalName( NSString *
name
) function yCheckLogicalName(
name
: string): boolean vb cs java py function yCheckLogicalName( ByVal
name
As String) As Boolean bool CheckLogicalName( string
name
) boolean CheckLogicalName( String
name
) def CheckLogicalName(
name
)
Un nom logique valide est formé de 19 caractères au maximum, choisis parmi
A..Z
, a..z
,
0..9
,
_
et
-
. Lorsqu'on configure un nom logique avec une chaîne incorrecte, les caractères invalides sont ignorés.
Paramètres : name
une chaîne de caractères contenant le nom vérifier.
Retourne :
true si le nom est valide, false dans le cas contraire.
120 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.DisableExceptions() yDisableExceptions()
YAPI
Désactive l'utilisation d'exceptions pour la gestion des erreurs.
js nodejs function yDisableExceptions( ) function DisableExceptions( ) php cpp function yDisableExceptions( ) void yDisableExceptions( ) m pas vb cs py void yDisableExceptions( ) procedure yDisableExceptions( ) procedure yDisableExceptions( ) void DisableExceptions( ) def DisableExceptions( )
Lorsque les exceptions sont désactivées, chaque fonction retourne une valeur d'erreur spécifique selon son type, documentée dans ce manuel de référence.
www.yoctopuce.com
121
19. Référence de l'API de haut niveau
YAPI.EnableExceptions() yEnableExceptions()
YAPI
Réactive l'utilisation d'exceptions pour la gestion des erreurs.
js function yEnableExceptions( ) nodejs function EnableExceptions( ) php cpp m pas function yEnableExceptions( ) void yEnableExceptions( ) void yEnableExceptions( ) procedure yEnableExceptions( ) vb cs py procedure yEnableExceptions( ) void EnableExceptions( ) def EnableExceptions( )
Attention, lorsque les exceptions sont activées, tout appel à une fonction de la librairie qui échoue déclenche une exception. Dans le cas où celle-ci n'est pas interceptée correctement par le code appelant, soit le debugger se lance, soit le programme de l'utilisateur est immédiatement stoppé
(crash).
122 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.EnableUSBHost() yEnableUSBHost()
YAPI
Cette fonction est utilisée uniquement sous Android.
java synchronized static void EnableUSBHost( Object
osContext
)
Avant d'appeler yRegisterHub("usb")
il faut activer le port USB host du systeme. Cette fonction prend en argument un objet de la classe android.content.Context (ou d'une sous-classe). Il n'est pas nécessaire d'appeler cette fonction pour accéder au modules à travers le réseau.
Paramètres : osContext
un objet de classe android.content.Context (ou une sous-classe)
www.yoctopuce.com
123
19. Référence de l'API de haut niveau
YAPI.FreeAPI() yFreeAPI()
YAPI
Libère la mémoire dynamique utilisée par la librairie Yoctopuce.
js function yFreeAPI( ) nodejs function FreeAPI( ) php cpp m pas function yFreeAPI( ) void yFreeAPI( ) void yFreeAPI( ) procedure yFreeAPI( ) vb cs java py procedure yFreeAPI( ) void FreeAPI( ) synchronized static void FreeAPI( ) def FreeAPI( )
Il n'est en général pas nécessaire d'appeler cette fonction, sauf si vous désirez libérer tous les blocs de mémoire alloués dynamiquement dans le but d'identifier une source de blocs perdus par exemple. Vous ne devez plus appeler aucune fonction de la librairie après avoir appelé yFreeAPI()
, sous peine de crash.
124 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.GetAPIVersion() yGetAPIVersion()
YAPI
Retourne la version de la librairie Yoctopuce utilisée.
js nodejs function yGetAPIVersion( ) function GetAPIVersion( ) php cpp function yGetAPIVersion( ) string yGetAPIVersion( ) m pas vb cs java py
NSString* yGetAPIVersion( ) function yGetAPIVersion( ): string function yGetAPIVersion( ) As String
String GetAPIVersion( )
String GetAPIVersion( ) def GetAPIVersion( )
L a v e r s i o n e s t r e t o u r n é e s o u s f o r m e d ' u n e c h a î n e d e c a r a c t è r e s a u f o r m a t
"Majeure.Mineure.NoBuild"
, par exemple
"1.01.5535"
. Pour les langages utilisant une DLL externe (par exemple C#, VisualBasic ou Delphi), la chaîne contient en outre la version de la DLL au même format, par exemple "1.01.5535 (1.01.5439)" .
Si vous désirez vérifier dans votre code que la version de la librairie est compatible avec celle que vous avez utilisé durant le développement, vérifiez que le numéro majeur soit strictement égal et que le numéro mineur soit égal ou supérieur. Le numéro de build n'est pas significatif par rapport à la compatibilité de la librairie.
Retourne :
une chaîne de caractères décrivant la version de la librairie.
www.yoctopuce.com
125
19. Référence de l'API de haut niveau
YAPI.GetTickCount() yGetTickCount()
YAPI
Retourne la valeur du compteur monotone de temps (en millisecondes).
js function yGetTickCount( ) nodejs function GetTickCount( ) php cpp m pas function yGetTickCount( ) u64 yGetTickCount( ) u64 yGetTickCount( ) function yGetTickCount( ): u64 vb cs java py function yGetTickCount( ) As Long ulong GetTickCount( ) long GetTickCount( ) def GetTickCount( )
Ce compteur peut être utilisé pour calculer des délais en rapport avec les modules Yoctopuce, dont la base de temps est aussi la milliseconde.
Retourne :
un long entier contenant la valeur du compteur de millisecondes.
126 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.HandleEvents() yHandleEvents()
YAPI
Maintient la communication de la librairie avec les modules Yoctopuce.
js nodejs function yHandleEvents(
errmsg
) function HandleEvents(
errmsg
) php cpp function yHandleEvents(
&$errmsg
)
YRETCODE yHandleEvents( string&
errmsg
) m pas vb cs java py
YRETCODE yHandleEvents( NSError**
errmsg
) function yHandleEvents( var
errmsg
: string): integer function yHandleEvents( ByRef
errmsg
As String) As YRETCODE
YRETCODE HandleEvents( ref string
errmsg
) int HandleEvents( ) def HandleEvents(
errmsg
=None)
Si votre programme inclut des longues boucles d'attente, vous pouvez y inclure un appel à cette fonction pour que la librairie prenne en charge les informations mise en attente par les modules sur les canaux de communication. Ce n'est pas strictement indispensable mais cela peut améliorer la réactivité des la librairie pour les commandes suivantes.
Cette fonction peut signaler une erreur au cas à la communication avec un module Yoctopuce ne se passerait pas comme attendu.
Paramètres : errmsg
une chaîne de caractères passée par référence, dans laquelle sera stocké un éventuel message d'erreur.
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
127
19. Référence de l'API de haut niveau
YAPI.InitAPI() yInitAPI()
YAPI
Initialise la librairie de programmation de Yoctopuce explicitement.
js function yInitAPI(
mode
,
errmsg
) nodejs function InitAPI(
mode
,
errmsg
) php cpp m pas function yInitAPI(
$mode
,
&$errmsg
)
YRETCODE yInitAPI( int
mode
, string&
errmsg
)
YRETCODE yInitAPI( int
mode
, NSError**
errmsg
) function yInitAPI(
mode
: integer, var
errmsg
: string): integer vb cs java py function yInitAPI( ByVal
mode
As Integer, ByRef
errmsg
As String) As Integer int InitAPI( int
mode
, ref string
errmsg
) synchronized static int InitAPI( int
mode
) def InitAPI(
mode
,
errmsg
=None)
Il n'est pas indispensable d'appeler yInitAPI()
, la librairie sera automatiquement initialisée de toute manière au premier appel à yRegisterHub()
.
Lorsque cette fonctin est utilisée avec comme mode
la valeur
Y_DETECT_NONE
, il faut explicitement appeler yRegisterHub()
pour indiquer à la librairie sur quel VirtualHub les modules sont connectés, avant d'essayer d'y accéder.
Paramètres : mode
un entier spécifiant le type de détection automatique de modules à utiliser. Les valeurs possibles sont
Y_DETECT_NONE
,
Y_DETECT_USB
,
Y_DETECT_NET
et
Y_DETECT_ALL
.
errmsg
une chaîne de caractères passée par référence, dans laquelle sera stocké un éventuel message d'erreur.
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
128 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.PreregisterHub() yPreregisterHub()
YAPI
Alternative plus tolerante à RegisterHub().
js nodejs function yPreregisterHub(
url
,
errmsg
) function PreregisterHub(
url
,
errmsg
) php cpp function yPreregisterHub(
$url
,
&$errmsg
)
YRETCODE yPreregisterHub( const string&
url
, string&
errmsg
) m pas vb
YRETCODE yPreregisterHub( NSString *
url
, NSError**
errmsg
) function yPreregisterHub(
url
: string, var
errmsg
: string): integer function yPreregisterHub( ByVal
url
As String,
ByRef
errmsg
As String) As Integer cs java py int PreregisterHub( string
url
, ref string
errmsg
) synchronized static int PreregisterHub( String
url
) def PreregisterHub(
url
,
errmsg
=None)
Cette fonction a le même but et la même paramètres que la fonction RegisterHub , mais contrairement à celle-ci
PreregisterHub()
ne déclanche pas d'erreur si le hub choisi n'est pas joignable au moment de l'appel. Il est ainsi possible d'enregistrer un hub réseau indépendemment de la connectivité, afin de tenter de ne le contacter que lorsqu'on cherche réellement un module.
Paramètres : url
une chaîne de caractères contenant "usb","callback", ou l'URL racine du VirtualHub à utiliser.
errmsg
une chaîne de caractères passée par référence, dans laquelle sera stocké un éventuel message d'erreur.
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
129
19. Référence de l'API de haut niveau
YAPI.RegisterDeviceArrivalCallback() yRegisterDeviceArrivalCallback()
YAPI
Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est branché.
js function yRegisterDeviceArrivalCallback(
arrivalCallback
) nodejs function RegisterDeviceArrivalCallback(
arrivalCallback
) php cpp m pas function yRegisterDeviceArrivalCallback(
$arrivalCallback
) void yRegisterDeviceArrivalCallback( yDeviceUpdateCallback
arrivalCallback
) void yRegisterDeviceArrivalCallback( yDeviceUpdateCallback
arrivalCallback
) procedure yRegisterDeviceArrivalCallback(
arrivalCallback
: yDeviceUpdateFunc) vb cs java py procedure yRegisterDeviceArrivalCallback( ByVal
arrivalCallback
As yDeviceUpdateFunc) void RegisterDeviceArrivalCallback( yDeviceUpdateFunc
arrivalCallback
) synchronized static void RegisterDeviceArrivalCallback( DeviceArrivalCallback
arrivalCallback
) def RegisterDeviceArrivalCallback(
arrivalCallback
)
Le callback sera appelé pendant l'éxecution de la fonction yHandleDeviceList
, que vous devrez appeler régulièrement.
Paramètres : arrivalCallback
une procédure qui prend un
YModule
en paramètre, ou null
130 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.RegisterDeviceRemovalCallback() yRegisterDeviceRemovalCallback()
YAPI
Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est débranché.
js nodejs function yRegisterDeviceRemovalCallback(
removalCallback
) function RegisterDeviceRemovalCallback(
removalCallback
) php cpp function yRegisterDeviceRemovalCallback(
$removalCallback
) void yRegisterDeviceRemovalCallback( yDeviceUpdateCallback
removalCallback
) m pas vb cs java py void yRegisterDeviceRemovalCallback( yDeviceUpdateCallback
removalCallback
) procedure yRegisterDeviceRemovalCallback(
removalCallback
: yDeviceUpdateFunc) procedure yRegisterDeviceRemovalCallback( ByVal
removalCallback
As yDeviceUpdateFunc) void RegisterDeviceRemovalCallback( yDeviceUpdateFunc
removalCallback
) synchronized static void RegisterDeviceRemovalCallback( DeviceRemovalCallback
removalCallback
) def RegisterDeviceRemovalCallback(
removalCallback
)
Le callback sera appelé pendant l'éxecution de la fonction yHandleDeviceList
, que vous devrez appeler régulièrement.
Paramètres : removalCallback
une procédure qui prend un
YModule
en paramètre, ou null
www.yoctopuce.com
131
19. Référence de l'API de haut niveau
YAPI.RegisterHub() yRegisterHub()
Configure la librairie Yoctopuce pour utiliser les modules connectés sur une machine donnée.
js function yRegisterHub(
url
,
errmsg
) nodejs function RegisterHub(
url
,
errmsg
) php cpp m pas vb function yRegisterHub(
$url
,
&$errmsg
)
YRETCODE yRegisterHub( const string&
url
, string&
errmsg
)
YRETCODE yRegisterHub( NSString *
url
, NSError**
errmsg
) function yRegisterHub(
url
: string, var
errmsg
: string): integer function yRegisterHub( ByVal
url
As String,
ByRef
errmsg
As String) As Integer cs java py int RegisterHub( string
url
, ref string
errmsg
) synchronized static int RegisterHub( String
url
) def RegisterHub(
url
,
errmsg
=None)
Le premier paramètre détermine le fonctionnement de l'API, il peut prendre les valeurs suivantes:
YAPI
usb: Si vous utilisez le mot-clé usb, l'API utilise les modules Yoctopuce connectés directement par
USB. Certains languages comme PHP, Javascript et Java ne permettent pas un accès direct aux couches matérielles, usb ne marchera donc pas avec ces languages. Dans ce cas, utilisez un
VirtualHub ou un YoctoHub réseau (voir ci-dessous).
x.x.x.x ou hostname: L'API utilise les modules connectés à la machine dont l'adresse IP est x.x.x.x, ou dont le nom d'hôte DNS est hostname. Cette machine peut être un ordinateur classique faisant tourner un VirtualHub, ou un YoctoHub avec réseau (YoctoHub-Ethernet / YoctoHub-Wireless). Si vous désirez utiliser le VirtualHub tournant sur votre machine locale, utilisez l'adresse IP 127.0.0.1.
callback Le mot-clé callback permet de faire fonctionnner l'API dans un mode appélé "callback HTTP".
C'est un mode spécial permettant, entre autres, de prendre le contrôle de modules Yoctopuce à travers un filtre NAT par l'intermédiaire d'un VirtualHub ou d'un Hub Yoctopuce. Il vous suffit de configuer le hub pour qu'il appelle votre script à intervalle régulier. Ce mode de fonctionnement n'est disponible actuellement qu'en PHP et en Node.JS.
Attention, seule une application peut fonctionner à la fois sur une machine donnée en accès direct à
USB, sinon il y aurait un conflit d'accès aux modules. Cela signifie en particulier que vous devez stopper le VirtualHub avant de lancer une application utilisant l'accès direct à USB. Cette limitation peut
être contournée en passant par un VirtualHub plutôt que d'utiliser directement USB.
Si vous désirez vous connecter à un Hub, virtuel ou non, sur lequel le controle d'accès a été activé, vous devez donner le paramètre url sous la forme: http://nom:mot_de_passe@adresse:port
Vous pouvez appeller RegisterHub plusieurs fois pour vous connecter à plusieurs machines différentes.
Paramètres : url
une chaîne de caractères contenant "usb","callback", ou l'URL racine du VirtualHub à utiliser.
errmsg
une chaîne de caractères passée par référence, dans laquelle sera stocké un éventuel message d'erreur.
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
132 www.yoctopuce.com
19. Référence de l'API de haut niveau
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
133
19. Référence de l'API de haut niveau
YAPI.RegisterHubDiscoveryCallback() yRegisterHubDiscoveryCallback()
YAPI
Enregistre une fonction de callback qui sera appelée à chaque fois qu'un Hub réseau ou un
VirtualHub est détecté sur le réseau local.
java void RegisterHubDiscoveryCallback( NewHubCallback
callback
)
Paramètres : callback
une procédure qui prend en paramètre deux chaîne de caractères ou null
134 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.RegisterLogFunction() yRegisterLogFunction()
YAPI
Enregistre une fonction de callback qui sera appellée à chaque fois que l'API a quelque chose à dire.
cpp m pas vb cs java py void yRegisterLogFunction( yLogFunction
logfun
) void yRegisterLogFunction( yLogCallback
logfun
) procedure yRegisterLogFunction(
logfun
: yLogFunc) procedure yRegisterLogFunction( ByVal
logfun
As yLogFunc) void RegisterLogFunction( yLogFunc
logfun
) void RegisterLogFunction( LogCallback
logfun
) def RegisterLogFunction(
logfun
)
Utile pour débugger le fonctionnement de l'API.
Paramètres : logfun
une procedure qui prend une chaîne de caractère en paramètre,
www.yoctopuce.com
135
19. Référence de l'API de haut niveau
YAPI.SelectArchitecture() ySelectArchitecture()
YAPI
Sélectionne manuellement l'architecture de la libraire dynamique à utiliser pour accéder à USB.
py def SelectArchitecture(
arch
)
Par défaut, la libraire Python détecte automatiquement la version de la libraire dynamique à utiliser pour accéder au port USB. Sous Linux ARM il n'est pas possible de détecter de manière fiable si il s'agit d'une installation Soft float (armel) ou Hard float (armhf). Dans ce cas, il est donc recommendé d'appeler SelectArchitecture() avant tout autre appel à la librairie pour forcer l'utilisation d'une architecture spécifiée.
Paramètres : arch
une chaîne de caractère spécifiant l'architecture à utiliser. Les valeurs possibles sont
"armhf"
,
"armel"
,
"i386"
,
"x86_64"
,
"32bit"
,
"64bit"
Retourne :
rien. En cas d'erreur, déclenche une exception.
136 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.SetDelegate() ySetDelegate()
YAPI
(Objective-C uniquement) Enregistre un objet délégué qui doit se conformer au procole
YDeviceHotPlug
.
m void ySetDelegate( id
object
)
Les methodes yDeviceArrival
et yDeviceRemoval
seront appelées pendant l'éxecution de la fonction yHandleDeviceList , que vous devrez appeler régulièrement.
Paramètres : object
un objet qui soit se conformer au procol YAPIDelegate , ou nil
www.yoctopuce.com
137
19. Référence de l'API de haut niveau
YAPI.SetTimeout() ySetTimeout()
YAPI
Appelle le callback spécifié après un temps d'attente spécifié.
js function ySetTimeout(
callback
,
ms_timeout
,
arguments
) nodejs function SetTimeout(
callback
,
ms_timeout
,
arguments
)
Cette fonction se comporte plus ou moins comme la fonction Javascript setTimeout
, mais durant le temps d'attente, elle va appeler yHandleEvents et yUpdateDeviceList périodiquement pour maintenir l'API à jour avec les modules connectés.
Paramètres : callback
la fonction à appeler lorsque le temps d'attente est écoulé. Sous Microsoft Internet Explorer, le callback doit être spécifié sous forme d'une string à évaluer.
ms_timeout
un entier correspondant à la durée de l'attente, en millisecondes
arguments
des arguments supplémentaires peuvent être fournis, pour être passés à la fonction de callback si nécessaire (pas supporté sous Microsoft Internet Explorer).
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
138 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.Sleep() ySleep()
YAPI
Effectue une pause dans l'exécution du programme pour une durée spécifiée.
js nodejs function ySleep(
ms_duration
,
errmsg
) function Sleep(
ms_duration
,
errmsg
) php cpp function ySleep(
$ms_duration
,
&$errmsg
)
YRETCODE ySleep( unsigned
ms_duration
, string&
errmsg
) m pas vb
YRETCODE ySleep( unsigned
ms_duration
, NSError **
errmsg
) function ySleep(
ms_duration
: integer, var
errmsg
: string): integer function ySleep( ByVal
ms_duration
As Integer,
ByRef
errmsg
As String) As Integer cs java py int Sleep( int
ms_duration
, ref string
errmsg
) int Sleep( long
ms_duration
) def Sleep(
ms_duration
,
errmsg
=None)
L'attente est passive, c'est-à-dire qu'elle n'occupe pas significativement le processeur, de sorte à le laisser disponible pour les autres processus fonctionnant sur la machine. Durant l'attente, la librairie va néanmoins continuer à lire périodiquement les informations en provenance des modules Yoctopuce en appelant la fonction yHandleEvents()
afin de se maintenir à jour.
Cette fonction peut signaler une erreur au cas à la communication avec un module Yoctopuce ne se passerait pas comme attendu.
Paramètres : ms_duration
un entier correspondant à la durée de la pause, en millisecondes
errmsg
une chaîne de caractères passée par référence, dans laquelle sera stocké un éventuel message d'erreur.
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
139
19. Référence de l'API de haut niveau
YAPI.UnregisterHub() yUnregisterHub()
YAPI
Configure la librairie Yoctopuce pour ne plus utiliser les modules connectés sur une machine préalablement enregistrer avec RegisterHub.
js function yUnregisterHub(
url
) nodejs function UnregisterHub(
url
) php cpp m pas function yUnregisterHub(
$url
) void yUnregisterHub( const string&
url
) void yUnregisterHub( NSString *
url
) procedure yUnregisterHub(
url
: string) vb cs java py procedure yUnregisterHub( ByVal
url
As String) void UnregisterHub( string
url
) synchronized static void UnregisterHub( String
url
) def UnregisterHub(
url
)
Paramètres : url
une chaîne de caractères contenant "usb" ou
140 www.yoctopuce.com
19. Référence de l'API de haut niveau
YAPI.UpdateDeviceList() yUpdateDeviceList()
YAPI
Force une mise-à-jour de la liste des modules Yoctopuce connectés.
js nodejs function yUpdateDeviceList(
errmsg
) function UpdateDeviceList(
errmsg
) php cpp function yUpdateDeviceList(
&$errmsg
)
YRETCODE yUpdateDeviceList( string&
errmsg
) m pas vb cs java py
YRETCODE yUpdateDeviceList( NSError**
errmsg
) function yUpdateDeviceList( var
errmsg
: string): integer function yUpdateDeviceList( ByRef
errmsg
As String) As YRETCODE
YRETCODE UpdateDeviceList( ref string
errmsg
) int UpdateDeviceList( ) def UpdateDeviceList(
errmsg
=None)
La librairie va vérifier sur les machines ou ports USB précédemment enregistrés en utilisant la fonction yRegisterHub
si un module a été connecté ou déconnecté, et le cas échéant appeler les fonctions de callback définies par l'utilisateur.
Cette fonction peut être appelée aussi souvent que désiré, afin de rendre l'application réactive aux
événements de hot-plug.
Paramètres : errmsg
une chaîne de caractères passée par référence, dans laquelle sera stocké un éventuel message d'erreur.
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
141
19. Référence de l'API de haut niveau
YAPI.UpdateDeviceList_async() yUpdateDeviceList_async()
YAPI
Force une mise-à-jour de la liste des modules Yoctopuce connectés.
js function yUpdateDeviceList_async(
callback
,
context
) nodejs function UpdateDeviceList_async(
callback
,
context
)
La librairie va vérifier sur les machines ou ports USB précédemment enregistrés en utilisant la fonction yRegisterHub
si un module a été connecté ou déconnecté, et le cas échéant appeler les fonctions de callback définies par l'utilisateur.
Cette fonction peut être appelée aussi souvent que désiré, afin de rendre l'application réactive aux
événements de hot-plug.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la VM Javascript de Firefox, qui n'implémente pas le passage de contrôle entre threads durant les appels d'entrée/sortie bloquants.
Paramètres : callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit deux arguments: le contexte fourni par l'appelant et le code de retour (
YAPI_SUCCESS
si l'opération se déroule sans erreur).
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
142 www.yoctopuce.com
19. Référence de l'API de haut niveau
19.2. Interface de contrôle du module
Cette interface est la même pour 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 nodejs php cpp m pas vb cs java py
<script type='text/javascript' src='yocto_api.js'></script> var yoctolib = require('yoctolib'); var YAPI = yoctolib.YAPI; var YModule = yoctolib.YModule; require_once('yocto_api.php');
#include "yocto_api.h"
#import "yocto_api.h" uses yocto_api; yocto_api.vb
yocto_api.cs
import com.yoctopuce.YoctoAPI.YModule; from yocto_api import *
Fonction globales
func
)
Permet de retrouver un module d'après son numéro de série ou son nom logique.
Commence l'énumération des modules accessibles par la librairie.
Méthodes des objets
YModule
Retourne un court texte décrivant le module.
pathname
)
Télécharge le fichier choisi du module et retourne son contenu.
Retourne le nombre de fonctions (sans compter l'interface "module") existant sur le module.
functionIndex
)
Retourne l'identifiant matériel de la nième fonction du module.
functionIndex
)
Retourne le nom logique de la nième fonction du module.
functionIndex
)
Retourne la valeur publiée par la nième fonction du module.
Retourne l'état de la balise de localisation.
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation de l'objet module.
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation de l'objet module.
Retourne la version du logiciel embarqué du module.
Retourne l'identifiant unique du module.
www.yoctopuce.com
143
19. Référence de l'API de haut niveau
Retourne l'icône du module.
Retourne une chaine de charactère contenant les derniers logs du module.
Retourne le nom logique du module.
Retourne la luminosité des leds informatives du module (valeur entre 0 et 100).
Retourne l'état courant des réglages persistents du module.
Retourne l'identifiant USB du module, préprogrammé en usine.
Retourne le nom commercial du module, préprogrammé en usine.
Retourne le numéro de version matériel du module, préprogrammé en usine.
Retourne le nombre de secondes restantes avant un redémarrage du module, ou zéro si aucun redémarrage n'a été agendé.
Retourne le numéro de série du module, préprogrammé en usine.
Retourne le numbre de millisecondes écoulées depuis la mise sous tension du module
Retourne le nombre d'interface USB utilisé par le module.
Retourne le courant consommé par le module sur le bus USB, en milliampères.
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData
.
Vérifie si le module est joignable, sans déclencher d'erreur.
callback
,
context
)
Vérifie si le module est joignable, sans déclencher d'erreur.
msValidity
)
Met en cache les valeurs courantes du module, avec une durée de validité spécifiée.
msValidity
,
callback
,
context
)
Met en cache les valeurs courantes du module, avec une durée de validité spécifiée.
Continue l'énumération des modules commencée à l'aide de yFirstModule() .
secBeforeReboot
)
Agende un simple redémarrage du module dans un nombre donné de secondes.
Recharge les réglages stockés dans le mémoire non volatile du module, comme à la mise sous tension du module.
Sauve les réglages courants dans la mémoire non volatile du module.
newval
)
144 www.yoctopuce.com
19. Référence de l'API de haut niveau
Allume ou éteint la balise de localisation du module.
newval
)
Change le nom logique du module.
newval
)
Modifie la luminosité des leds informatives du module.
newval
)
Modifie le nombre d'interface USB utilisé par le module.
data
)
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData .
secBeforeReboot
)
Agende un redémarrage du module en mode spécial de reprogrammation du logiciel embarqué.
callback
,
context
)
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre.
www.yoctopuce.com
145
19. Référence de l'API de haut niveau
YModule.FindModule() yFindModule()
YModule
Permet de retrouver un module d'après son numéro de série ou son nom logique.
js function yFindModule(
func
) nodejs function FindModule(
func
) php cpp m pas function yFindModule(
$func
)
YModule* yFindModule( string
func
)
+(YModule*) yFindModule : (NSString*)
func
function yFindModule(
func
: string): TYModule vb cs java py function yFindModule( ByVal
func
As String) As YModule
YModule FindModule( string
func
)
YModule FindModule( String
func
) def FindModule(
func
)
Cette fonction n'exige pas que le module soit en ligne au moment ou elle est appelée, l'objet retourné sera néanmoins valide. Utiliser la méthode
YModule.isOnline()
pour tester si le module est utilisable à un moment donné. En cas d'ambiguïté lorsqu'on fait une recherche par nom logique, aucune erreur ne sera notifiée: la première instance trouvée sera renvoyée. La recherche se fait d'abord par nom matériel, puis par nom logique.
Paramètres : func
une chaîne de caractères contenant soit le numéro de série, soit le nom logique du module désiré
Retourne :
un objet de classe
YModule
qui permet ensuite de contrôler le module ou d'obtenir de plus amples informations sur le module.
146 www.yoctopuce.com
YModule.FirstModule() yFirstModule()
19. Référence de l'API de haut niveau
YModule
Commence l'énumération des modules accessibles par la librairie.
js nodejs function yFirstModule( ) function FirstModule( ) php cpp function yFirstModule( )
YModule* yFirstModule( ) m pas vb cs java py
YModule* yFirstModule( ) function yFirstModule( ): TYModule function yFirstModule( ) As YModule
YModule FirstModule( )
YModule FirstModule( ) def FirstModule( )
Utiliser la fonction
YModule.nextModule()
pour itérer sur les autres modules.
Retourne :
un pointeur sur un objet YModule , correspondant au premier module accessible en ligne, ou null si aucun module n'a été trouvé.
www.yoctopuce.com
147
19. Référence de l'API de haut niveau
module
→
describe()
Retourne un court texte décrivant le module.
js function describe( ) nodejs function describe( ) php function describe( ) cpp m pas vb cs java py string describe( )
-(NSString*) describe function describe( ): string function describe( ) As String string describe( )
String describe( ) def describe( )
Ce texte peut contenir soit le nom logique du module, soit son numéro de série.
Retourne :
une chaîne de caractères décrivant le module
YModule
148 www.yoctopuce.com
module
→
download()
Télécharge le fichier choisi du module et retourne son contenu.
js function download(
pathname
) nodejs function download(
pathname
) php function download(
$pathname
) cpp m pas vb py cmd string download( string
pathname
)
-(NSData*) download : (NSString*)
pathname
function download(
pathname
: string): TByteArray function download( ) As Byte def download(
pathname
)
YModule
target
download
pathname
Paramètres : pathname
nom complet du fichier
Retourne :
le contenu du fichier chargé
En cas d'erreur, déclenche une exception ou retourne un contenu vide.
19. Référence de l'API de haut niveau
YModule
www.yoctopuce.com
149
19. Référence de l'API de haut niveau
module
→
functionCount() YModule
Retourne le nombre de fonctions (sans compter l'interface "module") existant sur le module.
js function functionCount( ) nodejs function functionCount( ) php function functionCount( ) cpp m pas vb cs py int functionCount( )
-(int) functionCount function functionCount( ): integer function functionCount( ) As Integer int functionCount( ) def functionCount( )
Retourne :
le nombre de fonctions sur le module
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
150 www.yoctopuce.com
module
→
functionId()
Retourne l'identifiant matériel de la nième fonction du module.
js function functionId(
functionIndex
) nodejs function functionId(
functionIndex
) php function functionId(
$functionIndex
) cpp m pas vb cs py string functionId( int
functionIndex
)
-(NSString*) functionId : (int)
functionIndex
function functionId(
functionIndex
: integer): string function functionId( ByVal
functionIndex
As Integer) As String string functionId( int
functionIndex
) def functionId(
functionIndex
)
19. Référence de l'API de haut niveau
YModule
Paramètres : functionIndex
l'index de la fonction pour laquelle l'information est désirée, en commençant à 0 pour la première fonction.
Retourne :
une chaîne de caractères correspondant à l'identifiant matériel unique de la fonction désirée
En cas d'erreur, déclenche une exception ou retourne un chaîne vide.
www.yoctopuce.com
151
19. Référence de l'API de haut niveau
module
→
functionName()
Retourne le nom logique de la nième fonction du module.
js function functionName(
functionIndex
) nodejs function functionName(
functionIndex
) php function functionName(
$functionIndex
) cpp m pas vb cs py string functionName( int
functionIndex
)
-(NSString*) functionName : (int)
functionIndex
function functionName(
functionIndex
: integer): string function functionName( ByVal
functionIndex
As Integer) As String string functionName( int
functionIndex
) def functionName(
functionIndex
)
YModule
Paramètres : functionIndex
l'index de la fonction pour laquelle l'information est désirée, en commençant à 0 pour la première fonction.
Retourne :
une chaîne de caractères correspondant au nom logique de la fonction désirée
En cas d'erreur, déclenche une exception ou retourne un chaîne vide.
152 www.yoctopuce.com
module
→
functionValue()
Retourne la valeur publiée par la nième fonction du module.
js function functionValue(
functionIndex
) nodejs function functionValue(
functionIndex
) php function functionValue(
$functionIndex
) cpp m pas vb cs py string functionValue( int
functionIndex
)
-(NSString*) functionValue : (int)
functionIndex
function functionValue(
functionIndex
: integer): string function functionValue( ByVal
functionIndex
As Integer) As String string functionValue( int
functionIndex
) def functionValue(
functionIndex
)
19. Référence de l'API de haut niveau
YModule
Paramètres : functionIndex
l'index de la fonction pour laquelle l'information est désirée, en commençant à 0 pour la première fonction.
Retourne :
une chaîne de caractères correspondant à la valeur publiée par la fonction désirée
En cas d'erreur, déclenche une exception ou retourne un chaîne vide.
www.yoctopuce.com
153
19. Référence de l'API de haut niveau
module
→
get_beacon() module
→
beacon()
Retourne l'état de la balise de localisation.
js function get_beacon( ) nodejs function get_beacon( ) php cpp m pas function get_beacon( )
Y_BEACON_enum get_beacon( )
-(Y_BEACON_enum) beacon function get_beacon( ): Integer vb cs java py cmd function get_beacon( ) As Integer int get_beacon( ) int get_beacon( ) def get_beacon( )
YModule
target
get_beacon
Retourne :
soit Y_BEACON_OFF , soit Y_BEACON_ON , selon l'état de la balise de localisation
En cas d'erreur, déclenche une exception ou retourne
Y_BEACON_INVALID
.
YModule
154 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
get_errorMessage() module
→
errorMessage()
YModule
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation de l'objet module.
js nodejs function get_errorMessage( ) function get_errorMessage( ) php cpp function get_errorMessage( ) string get_errorMessage( ) m pas vb cs java py
-(NSString*) errorMessage function get_errorMessage( ): string function get_errorMessage( ) As String string get_errorMessage( )
String get_errorMessage( ) def get_errorMessage( )
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
une chaîne de caractères correspondant au message de la dernière erreur qui s'est produit lors de l'utilisation du module
www.yoctopuce.com
155
19. Référence de l'API de haut niveau
module
→
get_errorType() module
→
errorType()
YModule
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation de l'objet module.
js function get_errorType( ) nodejs function get_errorType( ) php cpp pas vb function get_errorType( )
YRETCODE get_errorType( ) function get_errorType( ): YRETCODE function get_errorType( ) As YRETCODE cs java py
YRETCODE get_errorType( ) int get_errorType( ) def get_errorType( )
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
un nombre correspondant au code de la dernière erreur qui s'est produit lors de l'utilisation du module
156 www.yoctopuce.com
module
→
get_firmwareRelease() module
→
firmwareRelease()
Retourne la version du logiciel embarqué du module.
js nodejs function get_firmwareRelease( ) function get_firmwareRelease( ) php cpp function get_firmwareRelease( ) string get_firmwareRelease( ) m pas vb cs
-(NSString*) firmwareRelease function get_firmwareRelease( ): string function get_firmwareRelease( ) As String string get_firmwareRelease( ) java py cmd
String get_firmwareRelease( ) def get_firmwareRelease( )
YModule
target
get_firmwareRelease
19. Référence de l'API de haut niveau
YModule
Retourne :
une chaîne de caractères représentant la version du logiciel embarqué du module
En cas d'erreur, déclenche une exception ou retourne Y_FIRMWARERELEASE_INVALID .
www.yoctopuce.com
157
19. Référence de l'API de haut niveau
module
→
get_hardwareId() module
→
hardwareId()
Retourne l'identifiant unique du module.
js function get_hardwareId( ) nodejs function get_hardwareId( ) php cpp m vb function get_hardwareId( ) string get_hardwareId( )
-(NSString*) hardwareId function get_hardwareId( ) As String cs java py string get_hardwareId( )
String get_hardwareId( ) def get_hardwareId( )
L'identifiant unique est composé du numéro de série du module suivi de la chaîne ".module".
YModule
Retourne :
une chaîne de caractères identifiant la fonction
158 www.yoctopuce.com
module
→
get_icon2d() module
→
icon2d()
Retourne l'icône du module.
js nodejs function get_icon2d( ) function get_icon2d( ) php cpp function get_icon2d( ) string get_icon2d( ) m pas vb py cmd
-(NSData*) icon2d function get_icon2d( ): TByteArray function get_icon2d( ) As Byte def get_icon2d( )
YModule
target
get_icon2d
L'icone est au format PNG et a une taille maximale de 1536 octets.
Retourne :
un buffer binaire contenant l'icone, au format png.
19. Référence de l'API de haut niveau
YModule
www.yoctopuce.com
159
19. Référence de l'API de haut niveau
module
→
get_lastLogs() module
→
lastLogs()
Retourne une chaine de charactère contenant les derniers logs du module.
js function get_lastLogs( ) nodejs function get_lastLogs( ) php cpp m pas function get_lastLogs( ) string get_lastLogs( )
-(NSString*) lastLogs function get_lastLogs( ): string vb cs java py cmd function get_lastLogs( ) As String string get_lastLogs( )
String get_lastLogs( ) def get_lastLogs( )
YModule
target
get_lastLogs
Cette methode retourne les derniers logs qui sont encore stocké dans le module.
Retourne :
une chaine de charactère contenant les derniers logs du module.
YModule
160 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
get_logicalName() module
→
logicalName()
Retourne le nom logique du module.
js nodejs function get_logicalName( ) function get_logicalName( ) php cpp function get_logicalName( ) string get_logicalName( ) m pas vb cs
-(NSString*) logicalName function get_logicalName( ): string function get_logicalName( ) As String string get_logicalName( ) java py cmd
String get_logicalName( ) def get_logicalName( )
YModule
target
get_logicalName
Retourne :
une chaîne de caractères représentant le nom logique du module
En cas d'erreur, déclenche une exception ou retourne Y_LOGICALNAME_INVALID .
YModule
www.yoctopuce.com
161
19. Référence de l'API de haut niveau
module
→
get_luminosity() module
→
luminosity()
Retourne la luminosité des leds informatives du module (valeur entre 0 et 100).
js function get_luminosity( ) nodejs function get_luminosity( ) php cpp m pas function get_luminosity( ) int get_luminosity( )
-(int) luminosity function get_luminosity( ): LongInt vb cs java py cmd function get_luminosity( ) As Integer int get_luminosity( ) int get_luminosity( ) def get_luminosity( )
YModule
target
get_luminosity
Retourne :
un entier représentant la luminosité des leds informatives du module (valeur entre 0 et 100)
En cas d'erreur, déclenche une exception ou retourne Y_LUMINOSITY_INVALID .
YModule
162 www.yoctopuce.com
module
→
get_persistentSettings() module
→
persistentSettings()
Retourne l'état courant des réglages persistents du module.
js nodejs function get_persistentSettings( ) function get_persistentSettings( ) php cpp function get_persistentSettings( )
Y_PERSISTENTSETTINGS_enum get_persistentSettings( ) m pas vb cs
-(Y_PERSISTENTSETTINGS_enum) persistentSettings function get_persistentSettings( ): Integer function get_persistentSettings( ) As Integer int get_persistentSettings( ) java py cmd int get_persistentSettings( ) def get_persistentSettings( )
YModule
target
get_persistentSettings
19. Référence de l'API de haut niveau
YModule
Retourne :
une valeur parmi Y_PERSISTENTSETTINGS_LOADED , Y_PERSISTENTSETTINGS_SAVED et
Y_PERSISTENTSETTINGS_MODIFIED représentant l'état courant des réglages persistents du module
En cas d'erreur, déclenche une exception ou retourne Y_PERSISTENTSETTINGS_INVALID .
www.yoctopuce.com
163
19. Référence de l'API de haut niveau
module
→
get_productId() module
→
productId()
Retourne l'identifiant USB du module, préprogrammé en usine.
js function get_productId( ) nodejs function get_productId( ) php cpp m pas function get_productId( ) int get_productId( )
-(int) productId function get_productId( ): LongInt vb cs java py cmd function get_productId( ) As Integer int get_productId( ) int get_productId( ) def get_productId( )
YModule
target
get_productId
Retourne :
un entier représentant l'identifiant USB du module, préprogrammé en usine
En cas d'erreur, déclenche une exception ou retourne Y_PRODUCTID_INVALID .
YModule
164 www.yoctopuce.com
module
→
get_productName() module
→
productName()
Retourne le nom commercial du module, préprogrammé en usine.
js nodejs function get_productName( ) function get_productName( ) php cpp function get_productName( ) string get_productName( ) m pas vb cs
-(NSString*) productName function get_productName( ): string function get_productName( ) As String string get_productName( ) java py cmd
String get_productName( ) def get_productName( )
YModule
target
get_productName
19. Référence de l'API de haut niveau
YModule
Retourne :
une chaîne de caractères représentant le nom commercial du module, préprogrammé en usine
En cas d'erreur, déclenche une exception ou retourne Y_PRODUCTNAME_INVALID .
www.yoctopuce.com
165
19. Référence de l'API de haut niveau
module
→
get_productRelease() module
→
productRelease()
Retourne le numéro de version matériel du module, préprogrammé en usine.
js function get_productRelease( ) nodejs function get_productRelease( ) php cpp m pas function get_productRelease( ) int get_productRelease( )
-(int) productRelease function get_productRelease( ): LongInt vb cs java py cmd function get_productRelease( ) As Integer int get_productRelease( ) int get_productRelease( ) def get_productRelease( )
YModule
target
get_productRelease
Retourne :
un entier représentant le numéro de version matériel du module, préprogrammé en usine
En cas d'erreur, déclenche une exception ou retourne Y_PRODUCTRELEASE_INVALID .
YModule
166 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
get_rebootCountdown() module
→
rebootCountdown()
YModule
Retourne le nombre de secondes restantes avant un redémarrage du module, ou zéro si aucun redémarrage n'a été agendé.
js nodejs function get_rebootCountdown( ) function get_rebootCountdown( ) php cpp function get_rebootCountdown( ) int get_rebootCountdown( ) m pas vb cs
-(int) rebootCountdown function get_rebootCountdown( ): LongInt function get_rebootCountdown( ) As Integer int get_rebootCountdown( ) java py cmd int get_rebootCountdown( ) def get_rebootCountdown( )
YModule
target
get_rebootCountdown
Retourne :
un entier représentant le nombre de secondes restantes avant un redémarrage du module, ou zéro si aucun redémarrage n'a été agendé
En cas d'erreur, déclenche une exception ou retourne
Y_REBOOTCOUNTDOWN_INVALID
.
www.yoctopuce.com
167
19. Référence de l'API de haut niveau
module
→
get_serialNumber() module
→
serialNumber()
Retourne le numéro de série du module, préprogrammé en usine.
js function get_serialNumber( ) nodejs function get_serialNumber( ) php cpp m pas function get_serialNumber( ) string get_serialNumber( )
-(NSString*) serialNumber function get_serialNumber( ): string vb cs java py cmd function get_serialNumber( ) As String string get_serialNumber( )
String get_serialNumber( ) def get_serialNumber( )
YModule
target
get_serialNumber
Retourne :
une chaîne de caractères représentant le numéro de série du module, préprogrammé en usine
En cas d'erreur, déclenche une exception ou retourne Y_SERIALNUMBER_INVALID .
YModule
168 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
get_upTime() module
→
upTime()
Retourne le numbre de millisecondes écoulées depuis la mise sous tension du module js nodejs function get_upTime( ) function get_upTime( ) php cpp function get_upTime( ) s64 get_upTime( ) m pas vb cs
-(s64) upTime function get_upTime( ): int64 function get_upTime( ) As Long long get_upTime( ) java py cmd long get_upTime( ) def get_upTime( )
YModule
target
get_upTime
YModule
Retourne :
un entier représentant le numbre de millisecondes écoulées depuis la mise sous tension du module
En cas d'erreur, déclenche une exception ou retourne Y_UPTIME_INVALID .
www.yoctopuce.com
169
19. Référence de l'API de haut niveau
module
→
get_usbBandwidth() module
→
usbBandwidth()
Retourne le nombre d'interface USB utilisé par le module.
js function get_usbBandwidth( ) nodejs function get_usbBandwidth( ) php cpp m pas function get_usbBandwidth( )
Y_USBBANDWIDTH_enum get_usbBandwidth( )
-(Y_USBBANDWIDTH_enum) usbBandwidth function get_usbBandwidth( ): Integer vb cs java py cmd function get_usbBandwidth( ) As Integer int get_usbBandwidth( ) int get_usbBandwidth( ) def get_usbBandwidth( )
YModule
target
get_usbBandwidth
YModule
Retourne :
soit Y_USBBANDWIDTH_SIMPLE , soit Y_USBBANDWIDTH_DOUBLE , selon le nombre d'interface
USB utilisé par le module
En cas d'erreur, déclenche une exception ou retourne
Y_USBBANDWIDTH_INVALID
.
170 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
get_usbCurrent() module
→
usbCurrent()
Retourne le courant consommé par le module sur le bus USB, en milliampères.
js nodejs function get_usbCurrent( ) function get_usbCurrent( ) php cpp function get_usbCurrent( ) int get_usbCurrent( ) m pas vb cs
-(int) usbCurrent function get_usbCurrent( ): LongInt function get_usbCurrent( ) As Integer int get_usbCurrent( ) java py cmd int get_usbCurrent( ) def get_usbCurrent( )
YModule
target
get_usbCurrent
YModule
Retourne :
un entier représentant le courant consommé par le module sur le bus USB, en milliampères
En cas d'erreur, déclenche une exception ou retourne Y_USBCURRENT_INVALID .
www.yoctopuce.com
171
19. Référence de l'API de haut niveau
module
→
get_userData() module
→
userData()
YModule
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData
.
js function get_userData( ) nodejs function get_userData( ) php function get_userData( ) cpp m pas vb cs java py void * get_userData( )
-(void*) userData function get_userData( ): Tobject function get_userData( ) As Object object get_userData( )
Object get_userData( ) def get_userData( )
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Retourne :
l'objet stocké précédemment par l'appelant.
172 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
isOnline() YModule
Vérifie si le module est joignable, sans déclencher d'erreur.
js function isOnline( ) nodejs function isOnline( ) php function isOnline( ) cpp m pas vb cs java py bool isOnline( )
-(BOOL) isOnline function isOnline( ): boolean function isOnline( ) As Boolean bool isOnline( ) boolean isOnline( ) def isOnline( )
Si les valeurs des attributs du module en cache sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Retourne :
true
si le module est joignable, false
sinon
www.yoctopuce.com
173
19. Référence de l'API de haut niveau
module
→
isOnline_async() YModule
Vérifie si le module est joignable, sans déclencher d'erreur.
js function isOnline_async(
callback
,
context
) nodejs function isOnline_async(
callback
,
context
)
Si les valeurs des attributs du module en cache sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la VM Javascript de Firefox, qui n'implémente pas le passage de contrôle entre threads durant les appels d'entrée/sortie bloquants.
Paramètres : callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet module concerné et le résultat booléen
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
174 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
load() YModule
Met en cache les valeurs courantes du module, avec une durée de validité spécifiée.
js function load(
msValidity
) nodejs function load(
msValidity
) php function load(
$msValidity
) cpp m pas vb cs java py
YRETCODE load( int
msValidity
)
-(YRETCODE) load : (int)
msValidity
function load(
msValidity
: integer): YRETCODE function load( ByVal
msValidity
As Integer) As YRETCODE
YRETCODE load( int
msValidity
) int load( long
msValidity
) def load(
msValidity
)
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Paramètres : msValidity
un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
175
19. Référence de l'API de haut niveau
module
→
load_async() YModule
Met en cache les valeurs courantes du module, avec une durée de validité spécifiée.
js function load_async(
msValidity
,
callback
,
context
) nodejs function load_async(
msValidity
,
callback
,
context
)
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la VM Javascript de Firefox, qui n'implémente pas le passage de contrôle entre threads durant les appels d'entrée/sortie bloquants.
Paramètres : msValidity
un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes
callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet module concerné et le code d'erreur (ou YAPI_SUCCESS )
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
176 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
nextModule()
Continue l'énumération des modules commencée à l'aide de yFirstModule()
.
js nodejs function nextModule( ) function nextModule( ) php cpp function nextModule( )
YModule * nextModule( ) m pas vb cs java py
-(YModule*) nextModule function nextModule( ): TYModule function nextModule( ) As YModule
YModule nextModule( )
YModule nextModule( ) def nextModule( )
YModule
Retourne :
un pointeur sur un objet
YModule
accessible en ligne, ou null
lorsque l'énumération est terminée.
www.yoctopuce.com
177
19. Référence de l'API de haut niveau
module
→
reboot()
Agende un simple redémarrage du module dans un nombre donné de secondes.
js function reboot(
secBeforeReboot
) nodejs function reboot(
secBeforeReboot
) php function reboot(
$secBeforeReboot
) cpp m pas vb cs java py cmd int reboot( int
secBeforeReboot
)
-(int) reboot : (int)
secBeforeReboot
function reboot(
secBeforeReboot
: LongInt): LongInt function reboot( ) As Integer int reboot( int
secBeforeReboot
) int reboot( int
secBeforeReboot
) def reboot(
secBeforeReboot
)
YModule
target
reboot
secBeforeReboot
YModule
Paramètres : secBeforeReboot
nombre de secondes avant de redémarrer
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
178 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
revertFromFlash() YModule
Recharge les réglages stockés dans le mémoire non volatile du module, comme à la mise sous tension du module.
js function revertFromFlash( ) nodejs function revertFromFlash( ) php function revertFromFlash( ) cpp m pas vb cs java py cmd int revertFromFlash( )
-(int) revertFromFlash function revertFromFlash( ): LongInt function revertFromFlash( ) As Integer int revertFromFlash( ) int revertFromFlash( ) def revertFromFlash( )
YModule
target
revertFromFlash
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
179
19. Référence de l'API de haut niveau
module
→
saveToFlash() YModule
Sauve les réglages courants dans la mémoire non volatile du module.
js function saveToFlash( ) nodejs function saveToFlash( ) php function saveToFlash( ) cpp m pas vb cs java py cmd int saveToFlash( )
-(int) saveToFlash function saveToFlash( ): LongInt function saveToFlash( ) As Integer int saveToFlash( ) int saveToFlash( ) def saveToFlash( )
YModule
target
saveToFlash
Attention le nombre total de sauvegardes possibles durant la vie du module est limité (environ 100000 cycles). N'appelez pas cette fonction dans une boucle.
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
180 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
set_beacon() module
→
setBeacon()
Allume ou éteint la balise de localisation du module.
js nodejs function set_beacon(
newval
) function set_beacon(
newval
) php cpp function set_beacon(
$newval
) int set_beacon( Y_BEACON_enum
newval
) m pas vb cs
-(int) setBeacon : (Y_BEACON_enum)
newval
function set_beacon(
newval
: Integer): integer function set_beacon( ByVal
newval
As Integer) As Integer int set_beacon( int
newval
) java py cmd int set_beacon( int
newval
) def set_beacon(
newval
)
YModule
target
set_beacon
newval
Paramètres : newval
soit
Y_BEACON_OFF
, soit
Y_BEACON_ON
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
YModule
www.yoctopuce.com
181
19. Référence de l'API de haut niveau
module
→
set_logicalName() module
→
setLogicalName()
Change le nom logique du module.
js function set_logicalName(
newval
) nodejs function set_logicalName(
newval
) php cpp m pas function set_logicalName(
$newval
) int set_logicalName( const string&
newval
)
-(int) setLogicalName : (NSString*)
newval
function set_logicalName(
newval
: string): integer vb cs java py cmd function set_logicalName( ByVal
newval
As String) As Integer int set_logicalName( string
newval
) int set_logicalName( String
newval
) def set_logicalName(
newval
)
YModule
target
set_logicalName
newval
YModule
Vous pouvez utiliser yCheckLogicalName()
pour vérifier si votre paramètre est valide. N'oubliez pas d'appeler la méthode saveToFlash()
du module si le réglage doit être préservé.
Paramètres : newval
une chaîne de caractères
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
182 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
set_luminosity() module
→
setLuminosity()
Modifie la luminosité des leds informatives du module.
js nodejs function set_luminosity(
newval
) function set_luminosity(
newval
) php cpp function set_luminosity(
$newval
) int set_luminosity( int
newval
) m pas vb cs
-(int) setLuminosity : (int)
newval
function set_luminosity(
newval
: LongInt): integer function set_luminosity( ByVal
newval
As Integer) As Integer int set_luminosity( int
newval
) java py cmd int set_luminosity( int
newval
) def set_luminosity(
newval
)
YModule
target
set_luminosity
newval
YModule
Le paramêtre est une valeur entre 0 et 100. N'oubliez pas d'appeler la méthode saveToFlash()
du module si le réglage doit être préservé.
Paramètres : newval
un entier représentant la luminosité des leds informatives du module
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
183
19. Référence de l'API de haut niveau
module
→
set_usbBandwidth() module
→
setUsbBandwidth()
Modifie le nombre d'interface USB utilisé par le module.
js function set_usbBandwidth(
newval
) nodejs function set_usbBandwidth(
newval
) php cpp m pas function set_usbBandwidth(
$newval
) int set_usbBandwidth( Y_USBBANDWIDTH_enum
newval
)
-(int) setUsbBandwidth : (Y_USBBANDWIDTH_enum)
newval
function set_usbBandwidth(
newval
: Integer): integer vb cs java py cmd function set_usbBandwidth( ByVal
newval
As Integer) As Integer int set_usbBandwidth( int
newval
) int set_usbBandwidth( int
newval
) def set_usbBandwidth(
newval
)
YModule
target
set_usbBandwidth
newval
Vous devez redémarrer le module après avoir changé ce réglage.
YModule
Paramètres : newval
soit
Y_USBBANDWIDTH_SIMPLE
, soit
Y_USBBANDWIDTH_DOUBLE
, selon le nombre d'interface USB utilisé par le module
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
184 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
set_userData() module
→
setUserData()
YModule
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData
.
js function set_userData(
data
) nodejs function set_userData(
data
) php function set_userData(
$data
) cpp m pas vb cs java py void set_userData( void*
data
)
-(void) setUserData : (void*)
data
procedure set_userData(
data
: Tobject) procedure set_userData( ByVal
data
As Object) void set_userData( object
data
) void set_userData( Object
data
) def set_userData(
data
)
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Paramètres : data
objet quelconque à mémoriser
www.yoctopuce.com
185
19. Référence de l'API de haut niveau
module
→
triggerFirmwareUpdate() YModule
Agende un redémarrage du module en mode spécial de reprogrammation du logiciel embarqué.
js function triggerFirmwareUpdate(
secBeforeReboot
) nodejs function triggerFirmwareUpdate(
secBeforeReboot
) php function triggerFirmwareUpdate(
$secBeforeReboot
) cpp m pas vb cs java py cmd int triggerFirmwareUpdate( int
secBeforeReboot
)
-(int) triggerFirmwareUpdate : (int)
secBeforeReboot
function triggerFirmwareUpdate(
secBeforeReboot
: LongInt): LongInt function triggerFirmwareUpdate( ) As Integer int triggerFirmwareUpdate( int
secBeforeReboot
) int triggerFirmwareUpdate( int
secBeforeReboot
) def triggerFirmwareUpdate(
secBeforeReboot
)
YModule
target
triggerFirmwareUpdate
secBeforeReboot
Paramètres : secBeforeReboot
nombre de secondes avant de redémarrer
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
186 www.yoctopuce.com
19. Référence de l'API de haut niveau
module
→
wait_async() YModule
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre.
js function wait_async(
callback
,
context
) nodejs function wait_async(
callback
,
context
)
La fonction callback peut donc librement utiliser des fonctions synchrones ou asynchrones, sans risquer de bloquer la machine virtuelle Javascript.
Paramètres : callback
fonction de callback qui sera appelée dès que toutes les commandes en cours d'exécution sur le module seront terminées La fonction callback reçoit deux arguments: le contexte fourni par l'appelant et l'objet fonction concerné.
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout :
www.yoctopuce.com
187
19. Référence de l'API de haut niveau
19.3. Interface de la fonction Servo
La librairie de programmation Yoctopuce permet non seulement de déplacer le servo vers une position donnée, mais aussi de spécifier l'interval de temps dans lequel le mouvement doit être fait, de sorte à pouvoir synchroniser un mouvement sur plusieurs servos.
Pour utiliser les fonctions décrites ici, vous devez inclure: js nodejs php cpp m
<script type='text/javascript' src='yocto_servo.js'></script> var yoctolib = require('yoctolib'); var YServo = yoctolib.YServo; require_once('yocto_servo.php');
#include "yocto_servo.h"
#import "yocto_servo.h" pas vb cs java py uses yocto_servo; yocto_servo.vb
yocto_servo.cs
import com.yoctopuce.YoctoAPI.YServo; from yocto_servo import *
Fonction globales
func
)
Permet de retrouver un servo d'après un identifiant donné.
Commence l'énumération des servo accessibles par la librairie.
Méthodes des objets
YServo
Retourne un court texte décrivant le servo au format TYPE(NAME)=SERIAL.FUNCTIONID
.
Retourne la valeur courante du servo (pas plus de 6 caractères).
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation du servo.
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation du servo.
Retourne un identifiant global du servo au format
NOM_MODULE.NOM_FONCTION
.
Retourne un identifiant unique de type
YFUN_DESCR
correspondant à la fonction.
Retourne l'identifiant matériel du servo, sans référence au module.
Retourne l'identifiant matériel unique du servo au format SERIAL.FUNCTIONID
.
Retourne le nom logique du servo.
Retourne l'objet
YModule
correspondant au module Yoctopuce qui héberge la fonction.
callback
,
context
)
Retourne l'objet
YModule
correspondant au module Yoctopuce qui héberge la fonction.
188 www.yoctopuce.com
19. Référence de l'API de haut niveau
Retourne la durée en microsecondes de l'impulsion correspondant au neutre du servo.
Retourne la position courante du servo.
Retourne la plage d'utilisation du servo.
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData
.
Vérifie si le module hébergeant le servo est joignable, sans déclencher d'erreur.
callback
,
context
)
Vérifie si le module hébergeant le servo est joignable, sans déclencher d'erreur.
msValidity
)
Met en cache les valeurs courantes du servo, avec une durée de validité spécifiée.
msValidity
,
callback
,
context
)
Met en cache les valeurs courantes du servo, avec une durée de validité spécifiée.
target
,
ms_duration
)
Déclenche un mouvement à vitesse constante vers une position donnée.
Continue l'énumération des servo commencée à l'aide de yFirstServo()
.
callback
)
Enregistre la fonction de callback qui est appelée à chaque changement de la valeur publiée.
newval
)
Modifie le nom logique du servo.
newval
)
Modifie la durée de l'impulsion correspondant à la position neutre du servo.
newval
)
Modifie immédiatement la consigne de position du servo.
newval
)
Modifie la plage d'utilisation du servo, en pourcents.
data
)
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData
.
callback
,
context
)
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre.
www.yoctopuce.com
189
19. Référence de l'API de haut niveau
YServo.FindServo() yFindServo()
Permet de retrouver un servo d'après un identifiant donné.
js function yFindServo(
func
) nodejs function FindServo(
func
) php cpp m pas function yFindServo(
$func
)
YServo* yFindServo( const string&
func
)
YServo* yFindServo( NSString*
func
) function yFindServo(
func
: string): TYServo vb cs java py function yFindServo( ByVal
func
As String) As YServo
YServo FindServo( string
func
)
YServo FindServo( String
func
) def FindServo(
func
)
L'identifiant peut être spécifié sous plusieurs formes:
YServo
●
NomLogiqueFonction
●
NoSerieModule.IdentifiantFonction
●
NoSerieModule.NomLogiqueFonction
●
NomLogiqueModule.IdentifiantMatériel
●
NomLogiqueModule.NomLogiqueFonction
Cette fonction n'exige pas que le servo soit en ligne au moment ou elle est appelée, l'objet retourné sera néanmoins valide. Utiliser la méthode YServo.isOnline() pour tester si le servo est utilisable
à un moment donné. En cas d'ambiguïté lorsqu'on fait une recherche par nom logique, aucune erreur ne sera notifiée: la première instance trouvée sera renvoyée. La recherche se fait d'abord par nom matériel, puis par nom logique.
Paramètres : func
une chaîne de caractères qui référence le servo sans ambiguïté
Retourne :
un objet de classe
YServo
qui permet ensuite de contrôler le servo.
190 www.yoctopuce.com
YServo.FirstServo() yFirstServo()
19. Référence de l'API de haut niveau
YServo
Commence l'énumération des servo accessibles par la librairie.
js nodejs function yFirstServo( ) function FirstServo( ) php cpp function yFirstServo( )
YServo* yFirstServo( ) m pas vb cs java py
YServo* yFirstServo( ) function yFirstServo( ): TYServo function yFirstServo( ) As YServo
YServo FirstServo( )
YServo FirstServo( ) def FirstServo( )
Utiliser la fonction
YServo.nextServo()
pour itérer sur les autres servo.
Retourne :
un pointeur sur un objet YServo , correspondant à le premier servo accessible en ligne, ou null si il n'y a pas de servo disponibles.
www.yoctopuce.com
191
19. Référence de l'API de haut niveau
servo
→
describe() YServo
Retourne un court texte décrivant le servo au format
TYPE(NAME)=SERIAL.FUNCTIONID
.
js function describe( ) nodejs function describe( ) php cpp m pas function describe( ) string describe( )
-(NSString*) describe function describe( ): string vb cs java py function describe( ) As String string describe( )
String describe( ) def describe( )
Plus précisément,
TYPE
correspond au type de fonction,
NAME
correspond au nom utilsé lors du premier accès a la fonction,
SERIAL
correspond au numéro de série du module si le module est connecté, ou
"unresolved"
sinon, et
FUNCTIONID
correspond à l'identifiant matériel de la fonction s i l e m o d u l e e s t c o n n e c t é . P a r e x e m p l e , L a m e t h o d e v a r e t o u r n e r
Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1
si le module est déjà connecté ou
Relay(BadCustomeName.relay1)=unresolved
si le module n'est pas déjà connecté. Cette methode ne declenche aucune transaction USB ou TCP et peut donc être utilisé dans un debuggeur.
Retourne :
u n e c h a î n e d e c a r a c t è r e s d é c r i v a n t l e s e r v o ( e x :
R e l a y ( M y C u s t o m N a m e . r e l a y 1 ) = R E L A Y L O 1 - 1 2 3 4 5 6 . r e l a y 1 )
192 www.yoctopuce.com
servo
→
get_advertisedValue() servo
→
advertisedValue()
Retourne la valeur courante du servo (pas plus de 6 caractères).
js nodejs function get_advertisedValue( ) function get_advertisedValue( ) php cpp function get_advertisedValue( ) string get_advertisedValue( ) m pas vb cs
-(NSString*) advertisedValue function get_advertisedValue( ): string function get_advertisedValue( ) As String string get_advertisedValue( ) java py cmd
String get_advertisedValue( ) def get_advertisedValue( )
YServo
target
get_advertisedValue
19. Référence de l'API de haut niveau
YServo
Retourne :
une chaîne de caractères représentant la valeur courante du servo (pas plus de 6 caractères). En cas d'erreur, déclenche une exception ou retourne
Y_ADVERTISEDVALUE_INVALID
.
www.yoctopuce.com
193
19. Référence de l'API de haut niveau
servo
→
get_errorMessage() servo
→
errorMessage()
YServo
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation du servo.
js function get_errorMessage( ) nodejs function get_errorMessage( ) php cpp m pas function get_errorMessage( ) string get_errorMessage( )
-(NSString*) errorMessage function get_errorMessage( ): string vb cs java py function get_errorMessage( ) As String string get_errorMessage( )
String get_errorMessage( ) def get_errorMessage( )
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
une chaîne de caractères correspondant au message de la dernière erreur qui s'est produit lors de l'utilisation du servo.
194 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
get_errorType() servo
→
errorType()
YServo
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation du servo.
js nodejs function get_errorType( ) function get_errorType( ) php cpp function get_errorType( )
YRETCODE get_errorType( ) pas vb cs java py function get_errorType( ): YRETCODE function get_errorType( ) As YRETCODE
YRETCODE get_errorType( ) int get_errorType( ) def get_errorType( )
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
un nombre correspondant au code de la dernière erreur qui s'est produit lors de l'utilisation du servo.
www.yoctopuce.com
195
19. Référence de l'API de haut niveau
servo
→
get_friendlyName() servo
→
friendlyName()
YServo
Retourne un identifiant global du servo au format
NOM_MODULE.NOM_FONCTION
.
js function get_friendlyName( ) nodejs function get_friendlyName( ) php function get_friendlyName( ) cpp m cs java py string get_friendlyName( )
-(NSString*) friendlyName string get_friendlyName( )
String get_friendlyName( ) def get_friendlyName( )
Le chaîne retournée utilise soit les noms logiques du module et du servo si ils sont définis, soit respectivement le numéro de série du module et l'identifant matériel du servo (par exemple:
MyCustomName.relay1
)
Retourne :
u n e c h a î n e d e c a r a c t è r e s i d e n t i f i a n t l e s e r v o e n u t i l i s a n t l e s n o m s l o g i q u e s ( e x :
MyCustomName.relay1
) En cas d'erreur, déclenche une exception ou retourne
Y_FRIENDLYNAME_INVALID
.
196 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
get_functionDescriptor() servo
→
functionDescriptor()
YServo
Retourne un identifiant unique de type
YFUN_DESCR
correspondant à la fonction.
js function get_functionDescriptor( ) nodejs function get_functionDescriptor( ) php function get_functionDescriptor( ) cpp m pas vb cs java py
YFUN_DESCR get_functionDescriptor( )
-(YFUN_DESCR) functionDescriptor function get_functionDescriptor( ): YFUN_DESCR function get_functionDescriptor( ) As YFUN_DESCR
YFUN_DESCR get_functionDescriptor( )
String get_functionDescriptor( ) def get_functionDescriptor( )
Cet identifiant peut être utilisé pour tester si deux instance de
YFunction
référencent physiquement la même fonction sur le même module.
Retourne :
un identifiant de type YFUN_DESCR . Si la fonction n'a jamais été contactée, la valeur retournée sera
Y_FUNCTIONDESCRIPTOR_INVALID
www.yoctopuce.com
197
19. Référence de l'API de haut niveau
servo
→
get_functionId() servo
→
functionId()
Retourne l'identifiant matériel du servo, sans référence au module.
js function get_functionId( ) nodejs function get_functionId( ) php cpp m vb function get_functionId( ) string get_functionId( )
-(NSString*) functionId function get_functionId( ) As String cs java py string get_functionId( )
String get_functionId( ) def get_functionId( )
Par example relay1
.
YServo
Retourne :
une chaîne de caractères identifiant le servo (ex: relay1 ) En cas d'erreur, déclenche une exception ou retourne
Y_FUNCTIONID_INVALID
.
198 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
get_hardwareId() servo
→
hardwareId()
YServo
Retourne l'identifiant matériel unique du servo au format
SERIAL.FUNCTIONID
.
js function get_hardwareId( ) nodejs function get_hardwareId( ) php function get_hardwareId( ) cpp m vb cs java py string get_hardwareId( )
-(NSString*) hardwareId function get_hardwareId( ) As String string get_hardwareId( )
String get_hardwareId( ) def get_hardwareId( )
L'identifiant unique est composé du numéro de série du module et de l'identifiant matériel du servo (par example
RELAYLO1-123456.relay1
).
Retourne :
une chaîne de caractères identifiant le servo (ex:
RELAYLO1-123456.relay1
) En cas d'erreur, déclenche une exception ou retourne Y_HARDWAREID_INVALID .
www.yoctopuce.com
199
19. Référence de l'API de haut niveau
servo
→
get_logicalName() servo
→
logicalName()
Retourne le nom logique du servo.
js function get_logicalName( ) nodejs function get_logicalName( ) php cpp m pas function get_logicalName( ) string get_logicalName( )
-(NSString*) logicalName function get_logicalName( ): string vb cs java py cmd function get_logicalName( ) As String string get_logicalName( )
String get_logicalName( ) def get_logicalName( )
YServo
target
get_logicalName
YServo
Retourne :
une chaîne de caractères représentant le nom logique du servo. En cas d'erreur, déclenche une exception ou retourne
Y_LOGICALNAME_INVALID
.
200 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
get_module() servo
→
module()
YServo
Retourne l'objet
YModule
correspondant au module Yoctopuce qui héberge la fonction.
js function get_module( ) nodejs function get_module( ) php function get_module( ) cpp m pas vb cs java py
YModule * get_module( )
-(YModule*) module function get_module( ): TYModule function get_module( ) As YModule
YModule get_module( )
YModule get_module( ) def get_module( )
Si la fonction ne peut être trouvée sur aucun module, l'instance de
YModule
retournée ne sera pas joignable.
Retourne :
une instance de YModule
www.yoctopuce.com
201
19. Référence de l'API de haut niveau
servo
→
get_module_async() servo
→
module_async()
YServo
Retourne l'objet
YModule
correspondant au module Yoctopuce qui héberge la fonction.
js function get_module_async(
callback
,
context
) nodejs function get_module_async(
callback
,
context
)
Si la fonction ne peut être trouvée sur aucun module, l'instance de
YModule
retournée ne sera pas joignable.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la VM Javascript de Firefox, qui n'implémente pas le passage de contrôle entre threads durant les appels d'entrée/sortie bloquants.
Paramètres : callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et l'instance demandée de
YModule
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
202 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
get_neutral() servo
→
neutral()
Retourne la durée en microsecondes de l'impulsion correspondant au neutre du servo.
js nodejs function get_neutral( ) function get_neutral( ) php cpp function get_neutral( ) int get_neutral( ) m pas vb cs
-(int) neutral function get_neutral( ): LongInt function get_neutral( ) As Integer int get_neutral( ) java py cmd int get_neutral( ) def get_neutral( )
YServo
target
get_neutral
YServo
Retourne :
un entier représentant la durée en microsecondes de l'impulsion correspondant au neutre du servo
En cas d'erreur, déclenche une exception ou retourne Y_NEUTRAL_INVALID .
www.yoctopuce.com
203
19. Référence de l'API de haut niveau
servo
→
get_position() servo
→
position()
Retourne la position courante du servo.
js function get_position( ) nodejs function get_position( ) php cpp m pas function get_position( ) int get_position( )
-(int) position function get_position( ): LongInt vb cs java py cmd function get_position( ) As Integer int get_position( ) int get_position( ) def get_position( )
YServo
target
get_position
Retourne :
un entier représentant la position courante du servo
En cas d'erreur, déclenche une exception ou retourne Y_POSITION_INVALID .
YServo
204 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
get_range() servo
→
range()
Retourne la plage d'utilisation du servo.
js nodejs function get_range( ) function get_range( ) php cpp function get_range( ) int get_range( ) m pas vb cs
-(int) range function get_range( ): LongInt function get_range( ) As Integer int get_range( ) java py cmd int get_range( ) def get_range( )
YServo
target
get_range
Retourne :
un entier représentant la plage d'utilisation du servo
En cas d'erreur, déclenche une exception ou retourne Y_RANGE_INVALID .
YServo
www.yoctopuce.com
205
19. Référence de l'API de haut niveau
servo
→
get_userData() servo
→
userData()
YServo
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData
.
js function get_userData( ) nodejs function get_userData( ) php function get_userData( ) cpp m pas vb cs java py void * get_userData( )
-(void*) userData function get_userData( ): Tobject function get_userData( ) As Object object get_userData( )
Object get_userData( ) def get_userData( )
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Retourne :
l'objet stocké précédemment par l'appelant.
206 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
isOnline() YServo
Vérifie si le module hébergeant le servo est joignable, sans déclencher d'erreur.
js function isOnline( ) nodejs function isOnline( ) php function isOnline( ) cpp m pas vb cs java py bool isOnline( )
-(BOOL) isOnline function isOnline( ): boolean function isOnline( ) As Boolean bool isOnline( ) boolean isOnline( ) def isOnline( )
Si les valeurs des attributs en cache du servo sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Retourne :
true
si le servo est joignable, false
sinon
www.yoctopuce.com
207
19. Référence de l'API de haut niveau
servo
→
isOnline_async() YServo
Vérifie si le module hébergeant le servo est joignable, sans déclencher d'erreur.
js function isOnline_async(
callback
,
context
) nodejs function isOnline_async(
callback
,
context
)
Si les valeurs des attributs en cache du servo sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la machine virtuelle Javascript avec une attente active.
Paramètres : callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et le résultat booléen
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
208 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
load() YServo
Met en cache les valeurs courantes du servo, avec une durée de validité spécifiée.
js function load(
msValidity
) nodejs function load(
msValidity
) php function load(
$msValidity
) cpp m pas vb cs java py
YRETCODE load( int
msValidity
)
-(YRETCODE) load : (int)
msValidity
function load(
msValidity
: integer): YRETCODE function load( ByVal
msValidity
As Integer) As YRETCODE
YRETCODE load( int
msValidity
) int load( long
msValidity
) def load(
msValidity
)
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Paramètres : msValidity
un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
209
19. Référence de l'API de haut niveau
servo
→
load_async() YServo
Met en cache les valeurs courantes du servo, avec une durée de validité spécifiée.
js function load_async(
msValidity
,
callback
,
context
) nodejs function load_async(
msValidity
,
callback
,
context
)
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la machine virtuelle Javascript avec une attente active.
Paramètres : msValidity
un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes
callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et le code d'erreur (ou YAPI_SUCCESS )
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
210 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
move()
Déclenche un mouvement à vitesse constante vers une position donnée.
js function move(
target
,
ms_duration
) nodejs function move(
target
,
ms_duration
) php function move(
$target
,
$ms_duration
) cpp m pas vb int move( int
target
, int
ms_duration
)
-(int) move : (int)
target
: (int)
ms_duration
function move(
target
: LongInt,
ms_duration
: LongInt): integer function move( ByVal
target
As Integer,
ByVal
ms_duration
As Integer) As Integer cs java py cmd int move( int
target
, int
ms_duration
) int move( int
target
, int
ms_duration
) def move(
target
,
ms_duration
)
YServo
target
move
target ms_duration
YServo
Paramètres : target
nouvelle position à la fin du mouvement
ms_duration
durée totale du mouvement, en millisecondes
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
211
19. Référence de l'API de haut niveau
servo
→
nextServo()
Continue l'énumération des servo commencée à l'aide de yFirstServo()
.
js function nextServo( ) nodejs function nextServo( ) php cpp m pas function nextServo( )
YServo * nextServo( )
-(YServo*) nextServo function nextServo( ): TYServo vb cs java py function nextServo( ) As YServo
YServo nextServo( )
YServo nextServo( ) def nextServo( )
Retourne :
un pointeur sur un objet
YServo
accessible en ligne, ou null
lorsque l'énumération est terminée.
YServo
212 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
registerValueCallback() YServo
Enregistre la fonction de callback qui est appelée à chaque changement de la valeur publiée.
js function registerValueCallback(
callback
) nodejs function registerValueCallback(
callback
) php function registerValueCallback(
$callback
) cpp m pas vb cs java py int registerValueCallback( YServoValueCallback
callback
)
-(int) registerValueCallback : (YServoValueCallback)
callback
function registerValueCallback(
callback
: TYServoValueCallback): LongInt function registerValueCallback( ) As Integer int registerValueCallback( ValueCallback
callback
) int registerValueCallback( UpdateCallback
callback
) def registerValueCallback(
callback
)
Ce callback n'est appelé que durant l'exécution de ySleep
ou yHandleEvents
. Cela permet à l'appelant de contrôler quand les callback peuvent se produire. Il est important d'appeler l'une de ces deux fonctions périodiquement pour garantir que les callback ne soient pas appelés trop tard. Pour désactiver un callback, il suffit d'appeler cette méthode en lui passant un pointeur nul.
Paramètres : callback
la fonction de callback à rappeler, ou un pointeur nul. La fonction de callback doit accepter deux arguments: l'object fonction dont la valeur a changé, et la chaîne de caractère décrivant la nouvelle valeur publiée.
www.yoctopuce.com
213
19. Référence de l'API de haut niveau
servo
→
set_logicalName() servo
→
setLogicalName()
Modifie le nom logique du servo.
js function set_logicalName(
newval
) nodejs function set_logicalName(
newval
) php cpp m pas function set_logicalName(
$newval
) int set_logicalName( const string&
newval
)
-(int) setLogicalName : (NSString*)
newval
function set_logicalName(
newval
: string): integer vb cs java py cmd function set_logicalName( ByVal
newval
As String) As Integer int set_logicalName( string
newval
) int set_logicalName( String
newval
) def set_logicalName(
newval
)
YServo
target
set_logicalName
newval
YServo
Vous pouvez utiliser yCheckLogicalName()
pour vérifier si votre paramètre est valide. N'oubliez pas d'appeler la méthode saveToFlash()
du module si le réglage doit être préservé.
Paramètres : newval
une chaîne de caractères représentant le nom logique du servo.
Retourne :
YAPI_SUCCESS si l'appel se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
214 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
set_neutral() servo
→
setNeutral()
YServo
Modifie la durée de l'impulsion correspondant à la position neutre du servo.
js nodejs function set_neutral(
newval
) function set_neutral(
newval
) php cpp function set_neutral(
$newval
) int set_neutral( int
newval
) m pas vb cs
-(int) setNeutral : (int)
newval
function set_neutral(
newval
: LongInt): integer function set_neutral( ByVal
newval
As Integer) As Integer int set_neutral( int
newval
) java py cmd int set_neutral( int
newval
) def set_neutral(
newval
)
YServo
target
set_neutral
newval
La durée est spécifiée en microsecondes, et la valeur standard est 1500 [us]. Ce réglage permet de décaler la plage d'utilisation du servo. Attention, l'utilisation d'une plage supérieure aux caractéristiques du servo risque fortement d'endommager le servo.
Paramètres : newval
un entier représentant la durée de l'impulsion correspondant à la position neutre du servo
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
215
19. Référence de l'API de haut niveau
servo
→
set_position() servo
→
setPosition()
Modifie immédiatement la consigne de position du servo.
js function set_position(
newval
) nodejs function set_position(
newval
) php cpp m pas function set_position(
$newval
) int set_position( int
newval
)
-(int) setPosition : (int)
newval
function set_position(
newval
: LongInt): integer vb cs java py cmd function set_position( ByVal
newval
As Integer) As Integer int set_position( int
newval
) int set_position( int
newval
) def set_position(
newval
)
YServo
target
set_position
newval
Paramètres : newval
un entier représentant immédiatement la consigne de position du servo
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
YServo
216 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
set_range() servo
→
setRange()
YServo
Modifie la plage d'utilisation du servo, en pourcents.
js nodejs function set_range(
newval
) function set_range(
newval
) php cpp function set_range(
$newval
) int set_range( int
newval
) m pas vb cs
-(int) setRange : (int)
newval
function set_range(
newval
: LongInt): integer function set_range( ByVal
newval
As Integer) As Integer int set_range( int
newval
) java py cmd int set_range( int
newval
) def set_range(
newval
)
YServo
target
set_range
newval
La valeur 100% correspond à un signal de commande standard, variant de 1 [ms] à 2 [ms]. Pour les servos supportent une plage double, de 0.5 [ms] à 2.5 [ms], vous pouvez utiliser une valeur allant jusqu'à 200%. Attention, l'utilisation d'une plage supérieure aux caractéristiques du servo risque fortement d'endommager le servo.
Paramètres : newval
un entier représentant la plage d'utilisation du servo, en pourcents
Retourne :
YAPI_SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
217
19. Référence de l'API de haut niveau
servo
→
set_userData() servo
→
setUserData()
YServo
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData
.
js function set_userData(
data
) nodejs function set_userData(
data
) php function set_userData(
$data
) cpp m pas vb cs java py void set_userData( void*
data
)
-(void) setUserData : (void*)
data
procedure set_userData(
data
: Tobject) procedure set_userData( ByVal
data
As Object) void set_userData( object
data
) void set_userData( Object
data
) def set_userData(
data
)
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Paramètres : data
objet quelconque à mémoriser
218 www.yoctopuce.com
19. Référence de l'API de haut niveau
servo
→
wait_async() YServo
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre.
js function wait_async(
callback
,
context
) nodejs function wait_async(
callback
,
context
)
La fonction callback peut donc librement utiliser des fonctions synchrones ou asynchrones, sans risquer de bloquer la machine virtuelle Javascript.
Paramètres : callback
fonction de callback qui sera appelée dès que toutes les commandes en cours d'exécution sur le module seront terminées La fonction callback reçoit deux arguments: le contexte fourni par l'appelant et l'objet fonction concerné.
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout :
www.yoctopuce.com
219
19. Référence de l'API de haut niveau
19.4. Interface de contrôle de l'alimentation
La librairie de programmation Yoctopuce permet de contrôler la source d'alimentation qui doit être utilisée pour les fonctions du module consommant beaucoup de courant. Le module est par ailleurs capable de couper automatiquement l'alimentation externe lorsqu'il détecte que la tension a trop chuté
(batterie épuisée).
Pour utiliser les fonctions décrites ici, vous devez inclure: js nodejs php cpp m
<script type='text/javascript' src='yocto_dualpower.js'></script> var yoctolib = require('yoctolib'); var YDualPower = yoctolib.YDualPower; require_once('yocto_dualpower.php');
#include "yocto_dualpower.h"
#import "yocto_dualpower.h" pas vb cs java py uses yocto_dualpower; yocto_dualpower.vb
yocto_dualpower.cs
import com.yoctopuce.YoctoAPI.YDualPower; from yocto_dualpower import *
Fonction globales
func
)
Permet de retrouver un contrôle d'alimentation d'après un identifiant donné.
Commence l'énumération des contrôles d'alimentation accessibles par la librairie.
Méthodes des objets
YDualPower
R e t o u r n e u n c o u r t t e x t e d é c r i v a n t l e c o n t r ô l e d ' a l i m e n t a t i o n a u f o r m a t
T Y P E ( N A M E ) = S E R I A L . F U N C T I O N I D .
Retourne la valeur courante du contrôle d'alimentation (pas plus de 6 caractères).
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation du contrôle d'alimentation.
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation du contrôle d'alimentation.
Retourne la tension mesurée sur l'alimentation de puissance externe, en millivolts.
Retourne un identifiant global du contrôle d'alimentation au format
NOM_MODULE.NOM_FONCTION
.
Retourne un identifiant unique de type
YFUN_DESCR
correspondant à la fonction.
Retourne l'identifiant matériel du contrôle d'alimentation, sans référence au module.
Retourne l'identifiant matériel unique du contrôle d'alimentation au format SERIAL.FUNCTIONID
.
220 www.yoctopuce.com
19. Référence de l'API de haut niveau
Retourne le nom logique du contrôle d'alimentation.
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction.
callback
,
context
)
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction.
Retourne le mode d'alimentation choisi pour les fonctions du module consommant beaucoup de courant.
Retourne la source d'alimentation active pour les fonctions du module consommant beaucoup de courant.
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData .
Vérifie si le module hébergeant le contrôle d'alimentation est joignable, sans déclencher d'erreur.
callback
,
context
)
Vérifie si le module hébergeant le contrôle d'alimentation est joignable, sans déclencher d'erreur.
msValidity
)
Met en cache les valeurs courantes du contrôle d'alimentation, avec une durée de validité spécifiée.
msValidity
,
callback
,
context
)
Met en cache les valeurs courantes du contrôle d'alimentation, avec une durée de validité spécifiée.
Continue l'énumération des contrôles d'alimentation commencée à l'aide de yFirstDualPower()
.
callback
)
Enregistre la fonction de callback qui est appelée à chaque changement de la valeur publiée.
newval
)
Modifie le nom logique du contrôle d'alimentation.
newval
)
Modifie le mode d'alimentation choisi pour les fonctions du module consommant beaucoup de courant.
data
)
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData
.
callback
,
context
)
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre.
www.yoctopuce.com
221
19. Référence de l'API de haut niveau
YDualPower.FindDualPower() yFindDualPower()
Permet de retrouver un contrôle d'alimentation d'après un identifiant donné.
js function yFindDualPower(
func
) nodejs function FindDualPower(
func
) php cpp m pas function yFindDualPower(
$func
)
YDualPower* yFindDualPower( const string&
func
)
YDualPower* yFindDualPower( NSString*
func
) function yFindDualPower(
func
: string): TYDualPower vb cs java py function yFindDualPower( ByVal
func
As String) As YDualPower
YDualPower FindDualPower( string
func
)
YDualPower FindDualPower( String
func
) def FindDualPower(
func
)
L'identifiant peut être spécifié sous plusieurs formes:
YDualPower
●
NomLogiqueFonction
●
NoSerieModule.IdentifiantFonction
●
NoSerieModule.NomLogiqueFonction
●
NomLogiqueModule.IdentifiantMatériel
●
NomLogiqueModule.NomLogiqueFonction
Cette fonction n'exige pas que le contrôle d'alimentation soit en ligne au moment ou elle est appelée, l'objet retourné sera néanmoins valide. Utiliser la méthode YDualPower.isOnline() pour tester si le contrôle d'alimentation est utilisable à un moment donné. En cas d'ambiguïté lorsqu'on fait une recherche par nom logique, aucune erreur ne sera notifiée: la première instance trouvée sera renvoyée.
La recherche se fait d'abord par nom matériel, puis par nom logique.
Paramètres : func
une chaîne de caractères qui référence le contrôle d'alimentation sans ambiguïté
Retourne :
un objet de classe
YDualPower
qui permet ensuite de contrôler le contrôle d'alimentation.
222 www.yoctopuce.com
19. Référence de l'API de haut niveau
YDualPower.FirstDualPower() yFirstDualPower()
YDualPower
Commence l'énumération des contrôles d'alimentation accessibles par la librairie.
js nodejs function yFirstDualPower( ) function FirstDualPower( ) php cpp function yFirstDualPower( )
YDualPower* yFirstDualPower( ) m pas vb cs java py
YDualPower* yFirstDualPower( ) function yFirstDualPower( ): TYDualPower function yFirstDualPower( ) As YDualPower
YDualPower FirstDualPower( )
YDualPower FirstDualPower( ) def FirstDualPower( )
Utiliser la fonction
YDualPower.nextDualPower()
pour itérer sur les autres contrôles d'alimentation.
Retourne :
un pointeur sur un objet
YDualPower
, correspondant à le premier contrôle d'alimentation accessible en ligne, ou null si il n'y a pas de contrôles d'alimentation disponibles.
www.yoctopuce.com
223
19. Référence de l'API de haut niveau
dualpower
→
describe() YDualPower
R e t o u r n e u n c o u r t t e x t e d é c r i v a n t l e c o n t r ô l e d ' a l i m e n t a t i o n a u f o r m a t
T Y P E ( N A M E ) = S E R I A L . F U N C T I O N I D
.
js function describe( ) nodejs function describe( ) php cpp m pas function describe( ) string describe( )
-(NSString*) describe function describe( ): string vb cs java py function describe( ) As String string describe( )
String describe( ) def describe( )
Plus précisément,
TYPE
correspond au type de fonction,
NAME
correspond au nom utilsé lors du premier accès a la fonction,
SERIAL
correspond au numéro de série du module si le module est connecté, ou
"unresolved"
sinon, et
FUNCTIONID
correspond à l'identifiant matériel de la fonction s i l e m o d u l e e s t c o n n e c t é . P a r e x e m p l e , L a m e t h o d e v a r e t o u r n e r
Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1
si le module est déjà connecté ou
Relay(BadCustomeName.relay1)=unresolved
si le module n'est pas déjà connecté. Cette methode ne declenche aucune transaction USB ou TCP et peut donc être utilisé dans un debuggeur.
Retourne :
u n e c h a î n e d e c a r a c t è r e s d é c r i v a n t l e c o n t r ô l e d ' a l i m e n t a t i o n ( e x :
R e l a y ( M y C u s t o m N a m e . r e l a y 1 ) = R E L A Y L O 1 - 1 2 3 4 5 6 . r e l a y 1 )
224 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
get_advertisedValue() dualpower
→
advertisedValue()
Retourne la valeur courante du contrôle d'alimentation (pas plus de 6 caractères).
js nodejs function get_advertisedValue( ) function get_advertisedValue( ) php cpp function get_advertisedValue( ) string get_advertisedValue( ) m pas vb cs
-(NSString*) advertisedValue function get_advertisedValue( ): string function get_advertisedValue( ) As String string get_advertisedValue( ) java py cmd
String get_advertisedValue( ) def get_advertisedValue( )
YDualPower
target
get_advertisedValue
YDualPower
Retourne :
une chaîne de caractères représentant la valeur courante du contrôle d'alimentation (pas plus de 6 caractères). En cas d'erreur, déclenche une exception ou retourne
Y_ADVERTISEDVALUE_INVALID
.
www.yoctopuce.com
225
19. Référence de l'API de haut niveau
dualpower
→
get_errorMessage() dualpower
→
errorMessage()
YDualPower
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation du contrôle d'alimentation.
js function get_errorMessage( ) nodejs function get_errorMessage( ) php cpp m pas function get_errorMessage( ) string get_errorMessage( )
-(NSString*) errorMessage function get_errorMessage( ): string vb cs java py function get_errorMessage( ) As String string get_errorMessage( )
String get_errorMessage( ) def get_errorMessage( )
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
une chaîne de caractères correspondant au message de la dernière erreur qui s'est produit lors de l'utilisation du contrôle d'alimentation.
226 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
get_errorType() dualpower
→
errorType()
YDualPower
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation du contrôle d'alimentation.
js nodejs function get_errorType( ) function get_errorType( ) php cpp function get_errorType( )
YRETCODE get_errorType( ) pas vb cs java py function get_errorType( ): YRETCODE function get_errorType( ) As YRETCODE
YRETCODE get_errorType( ) int get_errorType( ) def get_errorType( )
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
un nombre correspondant au code de la dernière erreur qui s'est produit lors de l'utilisation du contrôle d'alimentation.
www.yoctopuce.com
227
19. Référence de l'API de haut niveau
dualpower
→
get_extVoltage() dualpower
→
extVoltage()
Retourne la tension mesurée sur l'alimentation de puissance externe, en millivolts.
js function get_extVoltage( ) nodejs function get_extVoltage( ) php cpp m pas function get_extVoltage( ) int get_extVoltage( )
-(int) extVoltage function get_extVoltage( ): LongInt vb cs java py cmd function get_extVoltage( ) As Integer int get_extVoltage( ) int get_extVoltage( ) def get_extVoltage( )
YDualPower
target
get_extVoltage
YDualPower
Retourne :
un entier représentant la tension mesurée sur l'alimentation de puissance externe, en millivolts
En cas d'erreur, déclenche une exception ou retourne Y_EXTVOLTAGE_INVALID .
228 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
get_friendlyName() dualpower
→
friendlyName()
YDualPower
R e t o u r n e u n i d e n t i f i a n t g l o b a l d u c o n t r ô l e d ' a l i m e n t a t i o n a u f o r m a t
N O M _ M O D U L E . N O M _ F O N C T I O N
.
js function get_friendlyName( ) nodejs function get_friendlyName( ) php function get_friendlyName( ) cpp m cs java py string get_friendlyName( )
-(NSString*) friendlyName string get_friendlyName( )
String get_friendlyName( ) def get_friendlyName( )
Le chaîne retournée utilise soit les noms logiques du module et du contrôle d'alimentation si ils sont définis, soit respectivement le numéro de série du module et l'identifant matériel du contrôle d'alimentation (par exemple: MyCustomName.relay1
)
Retourne :
une chaîne de caractères identifiant le contrôle d'alimentation en utilisant les noms logiques (ex:
MyCustomName.relay1
) En cas d'erreur, déclenche une exception ou retourne
Y_FRIENDLYNAME_INVALID
.
www.yoctopuce.com
229
19. Référence de l'API de haut niveau
dualpower
→
get_functionDescriptor() dualpower
→
functionDescriptor()
YDualPower
Retourne un identifiant unique de type
YFUN_DESCR
correspondant à la fonction.
js function get_functionDescriptor( ) nodejs function get_functionDescriptor( ) php function get_functionDescriptor( ) cpp m pas vb cs java py
YFUN_DESCR get_functionDescriptor( )
-(YFUN_DESCR) functionDescriptor function get_functionDescriptor( ): YFUN_DESCR function get_functionDescriptor( ) As YFUN_DESCR
YFUN_DESCR get_functionDescriptor( )
String get_functionDescriptor( ) def get_functionDescriptor( )
Cet identifiant peut être utilisé pour tester si deux instance de
YFunction
référencent physiquement la même fonction sur le même module.
Retourne :
un identifiant de type YFUN_DESCR . Si la fonction n'a jamais été contactée, la valeur retournée sera
Y_FUNCTIONDESCRIPTOR_INVALID
230 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
get_functionId() dualpower
→
functionId()
Retourne l'identifiant matériel du contrôle d'alimentation, sans référence au module.
js nodejs function get_functionId( ) function get_functionId( ) php cpp function get_functionId( ) string get_functionId( ) m vb cs java py
-(NSString*) functionId function get_functionId( ) As String string get_functionId( )
String get_functionId( ) def get_functionId( )
YDualPower
Par example relay1
.
Retourne :
une chaîne de caractères identifiant le contrôle d'alimentation (ex: relay1 ) En cas d'erreur, déclenche une exception ou retourne
Y_FUNCTIONID_INVALID
.
www.yoctopuce.com
231
19. Référence de l'API de haut niveau
dualpower
→
get_hardwareId() dualpower
→
hardwareId()
YDualPower
Retourne l'identifiant matériel unique du contrôle d'alimentation au format
SERIAL.FUNCTIONID
.
js function get_hardwareId( ) nodejs function get_hardwareId( ) php function get_hardwareId( ) cpp m vb cs java py string get_hardwareId( )
-(NSString*) hardwareId function get_hardwareId( ) As String string get_hardwareId( )
String get_hardwareId( ) def get_hardwareId( )
L'identifiant unique est composé du numéro de série du module et de l'identifiant matériel du contrôle d'alimentation (par example
RELAYLO1-123456.relay1
).
Retourne :
une chaîne de caractères identifiant le contrôle d'alimentation (ex:
RELAYLO1-123456.relay1
) En cas d'erreur, déclenche une exception ou retourne Y_HARDWAREID_INVALID .
232 www.yoctopuce.com
dualpower
→
get_logicalName() dualpower
→
logicalName()
Retourne le nom logique du contrôle d'alimentation.
js nodejs function get_logicalName( ) function get_logicalName( ) php cpp function get_logicalName( ) string get_logicalName( ) m pas vb cs
-(NSString*) logicalName function get_logicalName( ): string function get_logicalName( ) As String string get_logicalName( ) java py cmd
String get_logicalName( ) def get_logicalName( )
YDualPower
target
get_logicalName
19. Référence de l'API de haut niveau
YDualPower
Retourne :
une chaîne de caractères représentant le nom logique du contrôle d'alimentation. En cas d'erreur, déclenche une exception ou retourne
Y_LOGICALNAME_INVALID
.
www.yoctopuce.com
233
19. Référence de l'API de haut niveau
dualpower
→
get_module() dualpower
→
module()
YDualPower
Retourne l'objet
YModule
correspondant au module Yoctopuce qui héberge la fonction.
js function get_module( ) nodejs function get_module( ) php function get_module( ) cpp m pas vb cs java py
YModule * get_module( )
-(YModule*) module function get_module( ): TYModule function get_module( ) As YModule
YModule get_module( )
YModule get_module( ) def get_module( )
Si la fonction ne peut être trouvée sur aucun module, l'instance de
YModule
retournée ne sera pas joignable.
Retourne :
une instance de YModule
234 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
get_module_async() dualpower
→
module_async()
YDualPower
Retourne l'objet
YModule
correspondant au module Yoctopuce qui héberge la fonction.
js function get_module_async(
callback
,
context
) nodejs function get_module_async(
callback
,
context
)
Si la fonction ne peut être trouvée sur aucun module, l'instance de
YModule
retournée ne sera pas joignable.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la VM Javascript de Firefox, qui n'implémente pas le passage de contrôle entre threads durant les appels d'entrée/sortie bloquants.
Paramètres : callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et l'instance demandée de
YModule
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
www.yoctopuce.com
235
19. Référence de l'API de haut niveau
dualpower
→
get_powerControl() dualpower
→
powerControl()
YDualPower
Retourne le mode d'alimentation choisi pour les fonctions du module consommant beaucoup de courant.
js function get_powerControl( ) nodejs function get_powerControl( ) php cpp m pas function get_powerControl( )
Y_POWERCONTROL_enum get_powerControl( )
-(Y_POWERCONTROL_enum) powerControl function get_powerControl( ): Integer vb cs java py cmd function get_powerControl( ) As Integer int get_powerControl( ) int get_powerControl( ) def get_powerControl( )
YDualPower
target
get_powerControl
Retourne :
u n e v a l e u r p a r m i Y_POWERCONTROL_AUTO , Y_POWERCONTROL_FROM_USB ,
Y_POWERCONTROL_FROM_EXT et Y_POWERCONTROL_OFF représentant le mode d'alimentation choisi pour les fonctions du module consommant beaucoup de courant
En cas d'erreur, déclenche une exception ou retourne
Y_POWERCONTROL_INVALID
.
236 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
get_powerState() dualpower
→
powerState()
YDualPower
Retourne la source d'alimentation active pour les fonctions du module consommant beaucoup de courant.
js nodejs function get_powerState( ) function get_powerState( ) php cpp function get_powerState( )
Y_POWERSTATE_enum get_powerState( ) m pas vb cs
-(Y_POWERSTATE_enum) powerState function get_powerState( ): Integer function get_powerState( ) As Integer int get_powerState( ) java py cmd int get_powerState( ) def get_powerState( )
YDualPower
target
get_powerState
Retourne :
u n e v a l e u r p a r m i Y _ P O W E R S T A T E _ O F F , Y _ P O W E R S T A T E _ F R O M _ U S B e t
Y_POWERSTATE_FROM_EXT représentant la source d'alimentation active pour les fonctions du module consommant beaucoup de courant
En cas d'erreur, déclenche une exception ou retourne
Y_POWERSTATE_INVALID
.
www.yoctopuce.com
237
19. Référence de l'API de haut niveau
dualpower
→
get_userData() dualpower
→
userData()
YDualPower
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData
.
js function get_userData( ) nodejs function get_userData( ) php function get_userData( ) cpp m pas vb cs java py void * get_userData( )
-(void*) userData function get_userData( ): Tobject function get_userData( ) As Object object get_userData( )
Object get_userData( ) def get_userData( )
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Retourne :
l'objet stocké précédemment par l'appelant.
238 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
isOnline() YDualPower
Vérifie si le module hébergeant le contrôle d'alimentation est joignable, sans déclencher d'erreur.
js function isOnline( ) nodejs function isOnline( ) php function isOnline( ) cpp m pas vb cs java py bool isOnline( )
-(BOOL) isOnline function isOnline( ): boolean function isOnline( ) As Boolean bool isOnline( ) boolean isOnline( ) def isOnline( )
Si les valeurs des attributs en cache du contrôle d'alimentation sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Retourne :
true
si le contrôle d'alimentation est joignable, false
sinon
www.yoctopuce.com
239
19. Référence de l'API de haut niveau
dualpower
→
isOnline_async() YDualPower
Vérifie si le module hébergeant le contrôle d'alimentation est joignable, sans déclencher d'erreur.
js function isOnline_async(
callback
,
context
) nodejs function isOnline_async(
callback
,
context
)
Si les valeurs des attributs en cache du contrôle d'alimentation sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la machine virtuelle Javascript avec une attente active.
Paramètres : callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et le résultat booléen
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
240 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
load() YDualPower
Met en cache les valeurs courantes du contrôle d'alimentation, avec une durée de validité spécifiée.
js function load(
msValidity
) nodejs function load(
msValidity
) php function load(
$msValidity
) cpp m pas vb cs java py
YRETCODE load( int
msValidity
)
-(YRETCODE) load : (int)
msValidity
function load(
msValidity
: integer): YRETCODE function load( ByVal
msValidity
As Integer) As YRETCODE
YRETCODE load( int
msValidity
) int load( long
msValidity
) def load(
msValidity
)
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Paramètres : msValidity
un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
241
19. Référence de l'API de haut niveau
dualpower
→
load_async() YDualPower
Met en cache les valeurs courantes du contrôle d'alimentation, avec une durée de validité spécifiée.
js function load_async(
msValidity
,
callback
,
context
) nodejs function load_async(
msValidity
,
callback
,
context
)
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la machine virtuelle Javascript avec une attente active.
Paramètres : msValidity
un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes
callback
fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et le code d'erreur (ou YAPI_SUCCESS )
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
242 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
nextDualPower() YDualPower
Continue l'énumération des contrôles d'alimentation commencée à l'aide de yFirstDualPower()
.
js nodejs function nextDualPower( ) function nextDualPower( ) php cpp function nextDualPower( )
YDualPower * nextDualPower( ) m pas vb cs java py
-(YDualPower*) nextDualPower function nextDualPower( ): TYDualPower function nextDualPower( ) As YDualPower
YDualPower nextDualPower( )
YDualPower nextDualPower( ) def nextDualPower( )
Retourne :
un pointeur sur un objet YDualPower accessible en ligne, ou null lorsque l'énumération est terminée.
www.yoctopuce.com
243
19. Référence de l'API de haut niveau
dualpower
→
registerValueCallback() YDualPower
Enregistre la fonction de callback qui est appelée à chaque changement de la valeur publiée.
js function registerValueCallback(
callback
) nodejs function registerValueCallback(
callback
) php function registerValueCallback(
$callback
) cpp m pas vb cs java py int registerValueCallback( YDualPowerValueCallback
callback
)
-(int) registerValueCallback : (YDualPowerValueCallback)
callback
function registerValueCallback(
callback
: TYDualPowerValueCallback): LongInt function registerValueCallback( ) As Integer int registerValueCallback( ValueCallback
callback
) int registerValueCallback( UpdateCallback
callback
) def registerValueCallback(
callback
)
Ce callback n'est appelé que durant l'exécution de ySleep
ou yHandleEvents
. Cela permet à l'appelant de contrôler quand les callback peuvent se produire. Il est important d'appeler l'une de ces deux fonctions périodiquement pour garantir que les callback ne soient pas appelés trop tard. Pour désactiver un callback, il suffit d'appeler cette méthode en lui passant un pointeur nul.
Paramètres : callback
la fonction de callback à rappeler, ou un pointeur nul. La fonction de callback doit accepter deux arguments: l'object fonction dont la valeur a changé, et la chaîne de caractère décrivant la nouvelle valeur publiée.
244 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
set_logicalName() dualpower
→
setLogicalName()
Modifie le nom logique du contrôle d'alimentation.
js nodejs function set_logicalName(
newval
) function set_logicalName(
newval
) php cpp function set_logicalName(
$newval
) int set_logicalName( const string&
newval
) m pas vb cs
-(int) setLogicalName : (NSString*)
newval
function set_logicalName(
newval
: string): integer function set_logicalName( ByVal
newval
As String) As Integer int set_logicalName( string
newval
) java py cmd int set_logicalName( String
newval
) def set_logicalName(
newval
)
YDualPower
target
set_logicalName
newval
YDualPower
Vous pouvez utiliser yCheckLogicalName()
pour vérifier si votre paramètre est valide. N'oubliez pas d'appeler la méthode saveToFlash()
du module si le réglage doit être préservé.
Paramètres : newval
une chaîne de caractères représentant le nom logique du contrôle d'alimentation.
Retourne :
YAPI_SUCCESS si l'appel se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
www.yoctopuce.com
245
19. Référence de l'API de haut niveau
dualpower
→
set_powerControl() dualpower
→
setPowerControl()
YDualPower
Modifie le mode d'alimentation choisi pour les fonctions du module consommant beaucoup de courant.
js function set_powerControl(
newval
) nodejs function set_powerControl(
newval
) php cpp m pas function set_powerControl(
$newval
) int set_powerControl( Y_POWERCONTROL_enum
newval
)
-(int) setPowerControl : (Y_POWERCONTROL_enum)
newval
function set_powerControl(
newval
: Integer): integer vb cs java py cmd function set_powerControl( ByVal
newval
As Integer) As Integer int set_powerControl( int
newval
) int set_powerControl( int
newval
) def set_powerControl(
newval
)
YDualPower
target
set_powerControl
newval
Paramètres : newval
une valeur parmi
Y_POWERCONTROL_AUTO
,
Y_POWERCONTROL_FROM_USB
,
Y_POWERCONTROL_FROM_EXT et Y_POWERCONTROL_OFF représentant le mode d'alimentation choisi pour les fonctions du module consommant beaucoup de courant
Retourne :
YAPI_SUCCESS
si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
246 www.yoctopuce.com
19. Référence de l'API de haut niveau
dualpower
→
set_userData() dualpower
→
setUserData()
YDualPower
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData
.
js function set_userData(
data
) nodejs function set_userData(
data
) php function set_userData(
$data
) cpp m pas vb cs java py void set_userData( void*
data
)
-(void) setUserData : (void*)
data
procedure set_userData(
data
: Tobject) procedure set_userData( ByVal
data
As Object) void set_userData( object
data
) void set_userData( Object
data
) def set_userData(
data
)
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Paramètres : data
objet quelconque à mémoriser
www.yoctopuce.com
247
19. Référence de l'API de haut niveau
dualpower
→
wait_async() YDualPower
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre.
js function wait_async(
callback
,
context
) nodejs function wait_async(
callback
,
context
)
La fonction callback peut donc librement utiliser des fonctions synchrones ou asynchrones, sans risquer de bloquer la machine virtuelle Javascript.
Paramètres : callback
fonction de callback qui sera appelée dès que toutes les commandes en cours d'exécution sur le module seront terminées La fonction callback reçoit deux arguments: le contexte fourni par l'appelant et l'objet fonction concerné.
context
contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback
Retourne :
rien du tout :
248 www.yoctopuce.com
20. Problèmes courants
20.1. Linux et USB
Pour fonctionner correctement sous Linux la librairie a besoin d'avoir accès en écriture à tous les périphériques USB Yoctopuce. Or, par défaut, sous Linux les droits d'accès des utilisateurs non-root
à USB sont limités à la lecture. Afin d'éviter de devoir lancer les exécutables en tant que root, il faut créer une nouvelle règle udev pour autoriser un ou plusieurs utilisateurs à accéder en écriture aux périphériques Yoctopuce.
Pour ajouter une règle udev à votre installation, il faut ajouter un fichier avec un nom au format "
##nomArbitraire.rules
" dans le répertoire "
/etc/udev/rules.d
". Lors du démarrage du système, udev va lire tous les fichiers avec l'extension "
.rules
" de ce répertoire en respectant l'ordre alphabétique (par exemple, le fichier "
51-custom.rules
" sera interprété APRES le fichier
"
50-udev-default.rules
").
Le fichier "
50-udev-default
" contient les règles udev par défaut du système. Pour modifier le comportement par défaut du système, il faut donc créer un fichier qui commence par un nombre plus grand que 50, qui définira un comportement plus spécifique que le défaut du système. Notez que pour ajouter une règle vous aurez besoin d'avoir un accès root sur le système.
Dans le répertoire udev_conf
de l'archive du VirtualHub exemples de règles qui vous éviterons de devoir partir de rien.
1
pour Linux, vous trouverez deux
Exemple 1: 51-yoctopuce.rules
Cette règle va autoriser tous les utilisateurs à accéder en lecture et en écriture aux périphériques
Yoctopuce USB. Les droits d'accès pour tous les autres périphériques ne seront pas modifiés. Si ce scénario vous convient il suffit de copier le fichier "
51-yoctopuce_all.rules
" dans le répertoire "
/etc/udev/rules.d
" et de redémarrer votre système.
# udev rules to allow write access to all users
# for Yoctopuce USB devices
SUBSYSTEM=="usb", ATTR{idVendor}=="24e0", MODE="0666"
Exemple 2: 51-yoctopuce_group.rules
Cette règle va autoriser le groupe "yoctogroup" à accéder en lecture et écriture aux périphériques
Yoctopuce USB. Les droits d'accès pour tous les autres périphériques ne seront pas modifiés. Si ce
1 http://www.yoctopuce.com/EN/virtualhub.php
www.yoctopuce.com
249
20. Problèmes courants
scénario vous convient il suffit de copier le fichier "
51-yoctopuce_group.rules
" dans le répertoire "
/etc/udev/rules.d
" et de redémarrer votre système.
# udev rules to allow write access to all users of "yoctogroup"
# for Yoctopuce USB devices
SUBSYSTEM=="usb", ATTR{idVendor}=="24e0", MODE="0664", GROUP="yoctogroup"
20.2. Plateformes ARM: HF et EL
Sur ARM il existe deux grandes familles d'executables: HF (Hard Float) et EL (EABI Little Endian).
Ces deux familles ne sont absolument pas compatibles entre elles. La capacité d'une machine ARM
à faire tourner des exécutables de l'une ou l'autre de ces familles dépend du hardware et du système d'exploitation. Les problèmes de compatibilité entre ArmHL et ArmEL sont assez difficiles à diagnostiquer, souvent même l'OS se révèle incapable de distinguer un exécutable HF d'un exécutable EL.
Tous les binaires Yoctopuce pour ARM sont fournis pré-compilée pour ArmHF et ArmEL, si vous ne savez à quelle famille votre machine ARM apartient, essayez simplement de lancer un exécutable de chaque famille.
250 www.yoctopuce.com
21. Caractéristiques
Vous trouverez résumées ci dessous les principales caractéristiques techniques de votre module
Yocto-Servo
Largeur
Longueur
Poids
Connecteur USB
Canaux
Sytème d'exploitation supportés
Drivers
API / SDK / Librairie (USB+TCP)
API / SDK / Librairie (seul.TCP)
RoHS
USB Vendor ID
USB Device ID
Boîter recommandé
20 mm
45 mm
5 g micro-B
5
Windows, Linux (Intel + ARM), Mac OS X, Android
Fonctionne sans driver
C++, Objective-C, C#, VB .NET, Delphi, Python, Java/Android
Javascript, Node.js, PHP, Java oui
0x24E0
0x0012
YoctoBox-Short-Thick-Black
www.yoctopuce.com
251
21. Caractéristiques
252 www.yoctopuce.com
Index
A
B
C
Contrôle 19, 20, 28, 31, 33, 39, 41, 49, 51, 57,
59, 64, 66, 72, 74, 79, 81, 86, 87, 91, 93, 100,
D
E
Erreurs 36, 47, 54, 61, 68, 76, 83, 89, 96, 107
F
FirstDualPower, YDualPower 222
G
get_advertisedValue, YDualPower 224
get_advertisedValue, YServo 192
get_errorMessage, YDualPower 225
get_extVoltage, YDualPower 227
get_firmwareRelease, YModule 156
get_friendlyName, YDualPower 228
get_functionDescriptor, YDualPower 229
get_functionDescriptor, YServo 196
get_functionId, YDualPower 230
get_hardwareId, YDualPower 231
get_logicalName, YDualPower 232
get_module_async, YDualPower 234
get_persistentSettings, YModule 162
get_powerControl, YDualPower 235
get_powerState, YDualPower 236
get_productRelease, YModule 165
get_rebootCountdown, YModule 166
H
I
isOnline_async, YDualPower 239
J
L
M
Module 9, 19, 28, 33, 41, 51, 59, 66, 74, 81, 87,
N
O
P
Préparation 31, 39, 79, 91, 97
R
RegisterDeviceArrivalCallback, YAPI 129
RegisterDeviceRemovalCallback, YAPI 130
RegisterHubDiscoveryCallback, YAPI 133
registerValueCallback, YDualPower 243
registerValueCallback, YServo 212
S
Servo 21, 28, 31, 39, 49, 57, 64, 72, 79, 86, 91,
set_logicalName, YDualPower 244
set_powerControl, YDualPower 245
T
triggerFirmwareUpdate, YModule 185
U
UpdateDeviceList_async, YAPI 141
V
W
Y
Yocto-Servo 19, 27, 31, 39, 49, 57, 63, 71, 79,
yRegisterDeviceArrivalCallback 129
yRegisterDeviceRemovalCallback 130
Download
Offentligt link opdateret
Det offentlige link til din chat er blevet opdateret. You may view and manage your chat links after registration here.
Dokument offentligt link
Annonce
