Tutoriel Référence de l'API Objective-C

Participez au vote ☆☆☆☆☆★★★★★

Référence de l'API Objective-C

Table des matières

Introduction 3

Utilisation du Yocto Demo en Objective-C 4

Contrôle de la fonction Led 4

Contrôle de la partie module 6

Gestion des erreurs 8

Reference 9

Fonctions générales 9

Interface de la fonction AnButton 15

Interface de la fonction CarbonDioxide 25

Interface de la fonction ColorLed 33

Interface de la fonction Current 42

Interface de la fonction DataLogger 50

Séquence de données mise en forme 60

Séquence de données enregistrées 62

Interface de contrôle de l'alimentation 65

Interface d'un port de Yocto-hub 72

Interface de la fonction Humidity 79

Interface de la fonction Led 88

Interface de la fonction LightSensor 95

Interface de contrôle du module 104

Interface de la fonction Network 115

Interface de la fonction Pressure 128

Interface de la fonction Relay 136

Interface de la fonction Servo 144

Interface de la fonction Temperature 152

Interface de la fonction Voltage 161

Interface de la fonction Source de tension 169

Interface de la fonction Wireless 179

Index 187

Introduction

Ce manuel est votre référence pour l'utilisation de la librairie Objective-C de Yoctopuce pour interfacer vos senseurs et contrôleurs USB.

Le chapitre suivant reprend un chapitre du manuel du module USB gratuit Yocto?Demo, afin d'illustrer l'utilisation de la librairie sur des exemples concrets.

Le reste du manuel documente chaque fonction, classe et méthode de l'API. La première section décrit les fonctions globales d'ordre général, et les sections décrivent les différentes classes, utiles selon le module Yoctopuce utilisé. Pour plus d'informations sur la signification et l'utilisation d'un attribut particulier d'un module, il est recommandé de se référer à la documentation spécifique du module, qui contient plus de détails.

Utilisation du Yocto?Demo 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 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é avec des séquences vidéo montrant comment intégrer les fichiers de la librairie à vos projets.

2.1. Contrôle de la fonction Led

Lancez Xcode 4.2 et ouvrez le projet exemple correspondant, fourni dans le répertoire Examples/Doc-GettingStarted-Yocto-Demo de la librairie Yoctopuce.

NSError *error; if(argc < 3) { usage();

}

@autoreleasepool {

NSString *target = [NSString stringWithUTF8String:argv[1]];

NSString *on_off = [NSString stringWithUTF8String:argv[2]];

YLed *led;

if(yRegisterHub(@"usb", &error) != YAPI_SUCCESS) {

NSLog(@"RegisterHub error: %@", [error localizedDescription]); return 1;

}

if([target isEqualToString:@"any"]){ led = yFirstLed();

}else{

led = yFindLed([target stringByAppendingString:@".led"]);

}

if ([led isOnline]) {

if ([on_off isEqualToString:@"on"]) [led set_power:Y_POWER_ON]; else

[led set_power:Y_POWER_OFF];

} 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_led.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_led.h est nécessaire pour gérer les modules contenant une led, comme le Yocto?Demo.

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.

yFindLed

La fonction yFindLed, permet de retrouver une led 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?Demo avec le numéros de série YCTOPOC1-123456 que vous auriez appelé "MonModule" et dont vous auriez nommé la fonction led "MaFonction", les cinq appels suivants seront strictement équivalents (pour autant que MaFonction ne soit définie qu'une fois, pour éviter toute ambiguïté):

YLed *led = yFindLed(@"");

YLed *led = yFindLed(@"YCTOPOC1-123456.MaFonction");

YLed *led = yFindLed(@"");

YLed *led = yFindLed(@"MonModule.MaFonction"); YLed *led = yFindLed(@"MaFonction"); yFindLed renvoie un objet que vous pouvez ensuite utiliser à loisir pour contrôler la led.

isOnline

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

set_power

La fonction set_power() de l'objet renvoyé par yFindLed permet d'allumer et d'éteindre la led. L'argument est Y_POWER_ON ou Y_POWER_OFF. Vous trouverez dans la référence de l'interface de programmation d'autres méthodes permettant de contrôler précisément la luminosité et de faire clignoter automatiquement la led.

2.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 [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(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 > 2) {

if (strcmp(argv[2], "ON")==0) module.beacon = Y_BEACON_ON; else

module.beacon = 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);

} else {

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 \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 cycles. Pour résumer vous ne pouvez employer la fonction saveToFlash que 100000 fois au cours de la vie du module. Veillez donc à ne pas appeler cette fonction depuis l'intérieur d'une boucle.

Enumeration des modules

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

2.3. Gestion des erreurs

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

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

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

• 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.

Reference

3.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:

Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est débranché.

yRegisterHub(url, errmsg)

Configure la librairie Yoctopuce pour utiliser les modules connectés sur une machine donnée.

yRegisterLogFunction(logfun)

Enregistre une fonction de callback qui sera appellée à chaque fois que l'API a quelque chose à dire.

ySetDelegate(object)

(Objective-C uniquement) Enregistre un objet délégué qui doit se conformer au procole

YDeviceHotPlug.

ySetTimeout(callback, ms_timeout, optional_arguments)

Appelle le callback spécifié après un temps d'attente spécifié.

ySleep(ms_duration, errmsg)

Effectue une pause dans l'exécution du programme pour une durée spécifiée.

yUnregisterHub(url)

Configure la librairie Yoctopuce pour ne plus utiliser les modules connectés sur une machine préalablement enregistrer avec RegisterHub.

yUpdateDeviceList(errmsg)

Force une mise-à-jour de la liste des modules Yoctopuce connectés.

yUpdateDeviceList_async(callback, context)

Force une mise-à-jour de la liste des modules Yoctopuce connectés.

yCheckLogicalName()

Vérifie si un nom donné est valide comme nom logique pour un module ou une fonction.

BOOL yCheckLogicalName( NSString * 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.

yDisableExceptions()

Désactive l'utilisation d'exceptions pour la gestion des erreurs.

void yDisableExceptions( )

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.

yEnableExceptions()

Réactive l'utilisation d'exceptions pour la gestion des erreurs.

void yEnableExceptions( )

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).

Cette fonction est utilisée uniquement sous Android.

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 sousclasse). 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) En cas d'erreur, déclenche une exception

yFreeAPI()

Libère la mémoire dynamique utilisée par la librairie Yoctopuce.

void yFreeAPI( )

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.

yGetAPIVersion()

Retourne la version de la librairie Yoctopuce utilisée.

NSString* yGetAPIVersion( )

La version est retournée sous forme d'une chaîne de caractères au format "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.

yGetTickCount()

Retourne la valeur du compteur monotone de temps (en millisecondes).

u64 yGetTickCount( )

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.

yHandleEvents()

Maintient la communication de la librairie avec les modules Yoctopuce.

YRETCODE yHandleEvents( NSError** errmsg)

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.

yInitAPI()

Initialise la librairie de programmation de Yoctopuce explicitement.

YRETCODE yInitAPI( int mode, NSError** errmsg)

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.

yRegisterDeviceArrivalCallback()

Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est branché.

void yRegisterDeviceArrivalCallback( yDeviceUpdateCallback 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

pour supprimer un callback déja enregistré.

yRegisterDeviceRemovalCallback()

Enregistre une fonction de callback qui sera appelée à chaque fois qu'un module est débranché.

void yRegisterDeviceRemovalCallback( yDeviceUpdateCallback 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

pour supprimer un callback déja enregistré.

yRegisterHub()

Configure la librairie Yoctopuce pour utiliser les modules connectés sur une machine donnée.

YRETCODE yRegisterHub( NSString * url, NSError** errmsg)

Dans le cas d'une utilisation avec la passerelle VirtualHub, vous devez donner en paramètre l'adresse de la machine où tourne le VirtualHub (typiquement "http:// 127.0.0.1:4444", qui désigne la machine locale). Si vous utilisez un langage qui a un accès direct à USB, vous pouvez utiliser la pseudo-adresse "usb" à la place.

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 VirtualHub 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

Paramètres :

url une chaîne de caractères contenant "usb" 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.

yRegisterLogFunction()

Enregistre une fonction de callback qui sera appellée à chaque fois que l'API a quelque chose à dire.

void yRegisterLogFunction( yLogCallback 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,

ou null pour supprimer un callback déja enregistré.

ySetDelegate()

(Objective-C uniquement) Enregistre un objet délégué qui doit se conformer au procole

YDeviceHotPlug.

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

pour supprimer un objet déja enregistré.

Appelle le callback spécifié après un temps d'attente spécifié.

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.