Introduction to liburbi-matlab

for Urbi 1.x

(book compiled from Revision exported)

David Filliat

Traduction de l'anglais Antoine 'Zelig' Hue

This document is released under the Attribution-NonCommercial-NoDerivs 2.0 Creative Commons licence (http://creativecommons.org/licenses/by-nc-nd/2.0/deed.en).


Table of Contents

1. Introduction
2. Démarrage
Installation
Connexion
Envoyer des commandes URBI
Obtenir les messages Urbi
3. opérations synchrones
Obtenir les valeurs des variables
Images et sons
4. Opérations asynchrones
5. Quelques exemples de mise en oeuvre
A. Copyright

Chapter 1. Introduction

Liburbi-matlab est une library créée pour encapsuler une connection URBI pour une utilisation dans MATLAB. Elle gère la connexion TCP avec le serveur URBI et la gestion des messages venant du serveur. Elle est compatible avec Urbi servers version 1.0 et 1.5. Les exemples dans la documentation sont pour la version 1.5.

La library consiste en quelques fonction pour gérer une connexion, envoyer et recevoir des messages et créer des fonctions de callback qui sont appelées après que des messages particuliers ait été reçu. Une documentation html décrivant toutes les fonctions est disponible dans le dossier doc/ se trouvant dans l'archive de la liburbi-matlab. Quelques exemples sont aussi fournis dans le dossier examples/.

Nous supposerons que le lecteur est familiarisé avec la syntax URBI. Référez vous au website de Gostai et aux tutoriels Urbi.

Chapter 2. Démarrage

Installation

Décompactez liburbi-matlab et ajoutez le dossier lib/ et tous ses sous-dossiers vers le chemin de matlab.

Connexion

Pour se connecter à un serveur URBI URBI, appelez urbiConnect avec le nom ou l'adresse IP du robot ou de l'ordinateur faisant tourner le serveur Urbi et optionnellement le port comme second paramètre. Cette fonction retourne une structure qui identifie la connexion et retiens quelques informations à propos du serveur Urbi:

>> myrobot = urbiConnect('myrobot.example.com',54000);

Cette connexion peut être fermée avec urbiDisconnect:

>> urbiDisconnect(myrobot);

Envoyer des commandes URBI

La fonction urbiSend envoie simplement la chaine donnée en argument au serveur Urbi:

>> urbiSend(myrobot,'var x=1+1;');

La fonction urbiInteract envoie aussi des commandes au serveur, mais affiche la réponse du serveur:

>> urbiInteract(myrobot,'x;');
[59619492] 2

Note

Notez que lors de l'utilisation de urbiInteract, le message en retour ne peut pas être traité plus tard dans matlab. Cette fonction devra par conséquent être utilisée pour des fin de débogage.

Si vous écrivez un script Urbi dans un fichier .u, il peut être envoyé avec urbiSendScript

>> urbiSendFile(myrobot,'myscript.u');

Obtenir les messages Urbi

La fonction urbiGet reçoie le message non lu suivant du serveur Urbi, le traite, et affiche le contenu dans une structure umessage:

>> urbiSend(myrobot,'mytag << 1+1;')
>> urbiGet(myrobot)

ans = 

    timeStamp: 103453
          tag: 'mytag'
         type: 'numeric'
        value: 2

La structure umessage contiens les champs suivants:

 umessage.timeStamp  : the time stamp of the message
 umessage.tag        : the tag of the message
 umessage.type       : the type of the message: 'numeric', 'string',
                       'list', 'system', 'object', 'image', 'sound',
                        or 'otherBIN'
 umessage.value      : message content:
                          numeric         if type == numeric
                          character array if type == string
                          cell array      if type == list
                          character array if type == system
                          character array if type == object
                          character array if type == image
                          struct          if type == sound
                               (with fields samples, Fs, nbits, length)
                          bytes array     if type == otherBIN

Warning

Parser dans le liburbi-matlab courant souffre de quelques limitations. Habituellement, les valeurs binaires ne sont pas supportées lorsquelles sont dans une liste ou dans un message de type 'object'. Si un tel message est rencontré, le buffer d'entrée sera corrompu et en conséquence les opérations de liburbi-matlab seront compromises. Pour revenir à un état normal du buffer d'entrée, utilisez la fonction urbiClearConnection:

>> urbiClearConnection(myrobot)

Chapter 3. opérations synchrones

Dans les opérations synchrones, les intéractions avec le serveur Urbi sont contrôlées par les appels des fonctions matlab. Ces fonctions envoie des commandes Urbi et attendent la réponse du serveur avant de quitter.

Note

Ces fonctions bloquent la connexion quand elles sont appelées. Si le serveur Urbi envoie des messages durant l'exécution de la fonction, ces message seront perdus. En robotique, une meilleur approche est souvent d'utiliser une opération asynchrone comme décrit dans la section suivante, ceci rends possible de traiter tous les messages entrants et d'exécuter les fonctions référentes.

Obtenir les valeurs des variables

De même vous devriez utiliser simplement urbiSend suivi de urbiGet pour récupérer toute valeur de variable, quelques fonctions pratiques sont fournies qui encapsules les appels à ces fonctions.

urbiGetVariable peut être utilisée pour récupérer toute valeur de variable. La première valeur en retour est le champ value du umessage correspondant et par conséquent varie avec le type de la variable. Le time stamp et le type du message sont aussi retournés par la fonction:

>> [x,ts,type]=urbiGetVariable(myrobot,'x')
x =
     2

ts =
    60802173

type =
numeric

Images et sons

Des fonctions sont aussi fournies pour travailler avec des images et des sons.

urbiGetImage retourne une image prise par le robot utilisant la variable camera.val par défaut. La fonction envoie une matrice contenant l'image. Cette image peut être affichée par la fonction imshow:

>> imshow(urbiGetImage(myrobot));

urbiGetSound enregistre le son venant du serveur Urbi, et retourne une structure avec les data et quelques paramètres associés, utilisant la variable micro.val par défaut. La durée du son devra être spécifiée en millisacondes:

>> snd = urbiGetSound(myrobot,5000)
snd = 
     samples: [1x319488 char]
          Fs: 16000
       nbits: 16
      length: 319488
     channel: 2
    duration: 4992

La structure du son peut être sauvée dans un fichier wav avec la fonction urbiSound2Wav:

>> urbiSound2Wav(snd,'recordedSound.wav'); 

Les sons peuvent aussi être envoyés à une variable sur le serveur Urbi avec les fonctions urbiSendSound ou urbiSendWav. Par défaut, les sons sont envoyés à la variable speaker.val pour être émis.

>> urbiSendSound(myrobot,snd);
>> urbiSendWav(myrobot,'recordedSound.wav'); 

Chapter 4. Opérations asynchrones

La plupart des messages reçus du serveur URBI sont le résultat de commandes envoyées précédements et peuvent être émis à tout moment, par exemple comme réaction à une configuration particulière d'un capteur. Le fonctionnement des tags Urbi rends possible d'associer un tag avec chaque commande qui est répétée dans le message en réponse. Les retours de fonctions peuvent être alors lancées automatiquement quand un message avec un tag donné est reçu.

La fonction urbiSetCallback associe une fonction à un tag: chaque fois qu'un message avec ce tag sera reçu du serveur, le retour de fonction sera appellé avec une structure de umessage comme paramètre. La fonction urbiSetCallback retourne un id qui peut être utilisé ultérieurement pour enlever le callback (retour) avec la fonction urbiDeleteCallback.

>>urbiSetCallback(myrobot,@callbackfct,'callbacktag')
ans =
     0

Où la fonction callbackfct devra traité le umessage correspondant au message reçu. Si la fonction retourne 0, le retour de la fonction s'exécutera seulement une fois puis le callback sera effacé. Si la fonction retourne 1, la fonction de retour sera exécutée pour chaque message. Voici le code sauvé dans le fichier callbackfct.m:

function cont=callbackfct(umessage)

x = umessage.value ;
disp(['I got the value : ' num2str(x)]) ;
cont = 1 ;

Une fois que tous les callback nécessaires seont enregistrés, le code Urbi qui émet les messages qui commanderont les callbacks seront envoyés au serveur. Par exemple:

>> urbiSend(myrobot,'callbacktag << time(); wait(1s);callbacktag << time();');

Puis, la fonction urbiProcessEvents devra être appelée, ceci traitera les messages venant du serveur Urbi et lancera les fonctions callback appropriées. Le premier paramètre spécifie une limite haute du nombre de messages qui peuvent être traités en un appel du processEvents (ceci pour autoriser à redonner le contrôle si il y a trop de messages). Le second paramètre spécifie le nombre de millisecondes durant lesquelles la fonction attends avant de retourner quand il n'y a pas de messages en entrée. Si il est réglé à -1 et qu'il n'y a pas de messages, , alors la fonction retourne immédiatement et retourne le nombre de callbacks qui ont été appellés. Si il est réglé à -2, la fonction ne retourne jamais.

>> urbiProcessEvents(2,-1)
I got the value : 64892240
I got the value : 64893240
ans =
     2

Le système de callback peut être réinitialisé avec la fonction urbiResetCallbacks.

Chapter 5. Quelques exemples de mise en oeuvre

Consultez les exemples, dans le dossier "examples" de la distribution liburbi-matlab. Il contient:

  • urbiAiboDemoCallback(aiboIP): Affiche le flux d'images venant d'aibo, et les messages quand des images sont détectées.

  • urbiAiboDemoSynchronous(aiboIP): Petite séquence lisant les valeurs, bougeant la tête, captant une image et jouant des sons.

Appendix A. Copyright


THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE
TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR
"LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE
LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE
OR COPYRIGHT LAW IS PROHIBITED.

BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND
AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS
YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF
SUCH TERMS AND CONDITIONS.

1. Definitions

   1. "Collective Work" means a work, such as a periodical issue,
   anthology or encyclopedia, in which the Work in its entirety in
   unmodified form, along with a number of other contributions,
   constituting separate and independent works in themselves, are
   assembled into a collective whole. A work that constitutes a
   Collective Work will not be considered a Derivative Work (as
   defined below) for the purposes of this License.  2. "Derivative
   Work" means a work based upon the Work or upon the Work and other
   pre-existing works, such as a translation, musical arrangement,
   dramatization, fictionalization, motion picture version, sound
   recording, art reproduction, abridgment, condensation, or any other
   form in which the Work may be recast, transformed, or adapted,
   except that a work that constitutes a Collective Work will not be
   considered a Derivative Work for the purpose of this License. For
   the avoidance of doubt, where the Work is a musical composition or
   sound recording, the synchronization of the Work in timed-relation
   with a moving image ("synching") will be considered a Derivative
   Work for the purpose of this License.  3. "Licensor" means the
   individual or entity that offers the Work under the terms of this
   License.  4. "Original Author" means the individual or entity who
   created the Work.  5. "Work" means the copyrightable work of
   authorship offered under the terms of this License.  6. "You" means
   an individual or entity exercising rights under this License who
   has not previously violated the terms of this License with respect
   to the Work, or who has received express permission from the
   Licensor to exercise rights under this License despite a previous
   violation.

2. Fair Use Rights. Nothing in this license is intended to reduce,
limit, or restrict any rights arising from fair use, first sale or
other limitations on the exclusive rights of the copyright owner under
copyright law or other applicable laws.

3. License Grant. Subject to the terms and conditions of this License,
Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
perpetual (for the duration of the applicable copyright) license to
exercise the rights in the Work as stated below:

   1. to reproduce the Work, to incorporate the Work into one or more
   Collective Works, and to reproduce the Work as incorporated in the
   Collective Works; 2. to distribute copies or phonorecords of,
   display publicly, perform publicly, and perform publicly by means
   of a digital audio transmission the Work including as incorporated
   in Collective Works;

The above rights may be exercised in all media and formats whether now
known or hereafter devised. The above rights include the right to make
such modifications as are technically necessary to exercise the rights
in other media and formats, but otherwise you have no rights to make
Derivative Works. All rights not expressly granted by Licensor are
hereby reserved, including but not limited to the rights set forth in
Sections 4(d) and 4(e).

4. Restrictions.The license granted in Section 3 above is expressly
made subject to and limited by the following restrictions:

   1. You may distribute, publicly display, publicly perform, or
   publicly digitally perform the Work only under the terms of this
   License, and You must include a copy of, or the Uniform Resource
   Identifier for, this License with every copy or phonorecord of the
   Work You distribute, publicly display, publicly perform, or
   publicly digitally perform. You may not offer or impose any terms
   on the Work that alter or restrict the terms of this License or the
   recipients' exercise of the rights granted hereunder. You may not
   sublicense the Work. You must keep intact all notices that refer to
   this License and to the disclaimer of warranties. You may not
   distribute, publicly display, publicly perform, or publicly
   digitally perform the Work with any technological measures that
   control access or use of the Work in a manner inconsistent with the
   terms of this License Agreement. The above applies to the Work as
   incorporated in a Collective Work, but this does not require the
   Collective Work apart from the Work itself to be made subject to
   the terms of this License. If You create a Collective Work, upon
   notice from any Licensor You must, to the extent practicable,
   remove from the Collective Work any reference to such Licensor or
   the Original Author, as requested.  2. You may not exercise any of
   the rights granted to You in Section 3 above in any manner that is
   primarily intended for or directed toward commercial advantage or
   private monetary compensation. The exchange of the Work for other
   copyrighted works by means of digital file-sharing or otherwise
   shall not be considered to be intended for or directed toward
   commercial advantage or private monetary compensation, provided
   there is no payment of any monetary compensation in connection with
   the exchange of copyrighted works.  3. If you distribute, publicly
   display, publicly perform, or publicly digitally perform the Work,
   You must keep intact all copyright notices for the Work and give
   the Original Author credit reasonable to the medium or means You
   are utilizing by conveying the name (or pseudonym if applicable) of
   the Original Author if supplied; the title of the Work if supplied;
   and to the extent reasonably practicable, the Uniform Resource
   Identifier, if any, that Licensor specifies to be associated with
   the Work, unless such URI does not refer to the copyright notice or
   licensing information for the Work. Such credit may be implemented
   in any reasonable manner; provided, however, that in the case of a
   Collective Work, at a minimum such credit will appear where any
   other comparable authorship credit appears and in a manner at least
   as prominent as such other comparable authorship credit.  4.

      For the avoidance of doubt, where the Work is a musical
         composition: 1. Performance Royalties Under Blanket
         Licenses. Licensor reserves the exclusive right to collect,
         whether individually or via a performance rights society
         (e.g. ASCAP, BMI, SESAC), royalties for the public
         performance or public digital performance (e.g. webcast) of
         the Work if that performance is primarily intended for or
         directed toward commercial advantage or private monetary
         compensation.  2. Mechanical Rights and Statutory
         Royalties. Licensor reserves the exclusive right to collect,
         whether individually or via a music rights agency or
         designated agent (e.g. Harry Fox Agency), royalties for any
         phonorecord You create from the Work ("cover version") and
         distribute, subject to the compulsory license created by 17
         USC Section 115 of the US Copyright Act (or the equivalent in
         other jurisdictions), if Your distribution of such cover
         version is primarily intended for or directed toward
         commercial advantage or private monetary compensation.
         5. Webcasting Rights and Statutory Royalties. For the
         avoidance of doubt, where the Work is a sound recording,
         Licensor reserves the exclusive right to collect, whether
         individually or via a performance-rights society
         (e.g. SoundExchange), royalties for the public digital
         performance (e.g. webcast) of the Work, subject to the
         compulsory license created by 17 USC Section 114 of the US
         Copyright Act (or the equivalent in other jurisdictions), if
         Your public digital performance is primarily intended for or
         directed toward commercial advantage or private monetary
         compensation.

5. Representations, Warranties and Disclaimer

UNLESS OTHERWISE MUTUALLY AGREED BY THE PARTIES IN WRITING, LICENSOR
OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR
OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE,
MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR
THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF
ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO
NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY
NOT APPLY TO YOU.

6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY
APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY
LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR
EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK,
EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. Termination

   1. This License and the rights granted hereunder will terminate
   automatically upon any breach by You of the terms of this
   License. Individuals or entities who have received Collective Works
   from You under this License, however, will not have their licenses
   terminated provided such individuals or entities remain in full
   compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will
   survive any termination of this License.  2. Subject to the above
   terms and conditions, the license granted here is perpetual (for
   the duration of the applicable copyright in the
   Work). Notwithstanding the above, Licensor reserves the right to
   release the Work under different license terms or to stop
   distributing the Work at any time; provided, however that any such
   election will not serve to withdraw this License (or any other
   license that has been, or is required to be, granted under the
   terms of this License), and this License will continue in full
   force and effect unless terminated as stated above.

8. Miscellaneous

   1. Each time You distribute or publicly digitally perform the Work
   or a Collective Work, the Licensor offers to the recipient a
   license to the Work on the same terms and conditions as the license
   granted to You under this License.  2. If any provision of this
   License is invalid or unenforceable under applicable law, it shall
   not affect the validity or enforceability of the remainder of the
   terms of this License, and without further action by the parties to
   this agreement, such provision shall be reformed to the minimum
   extent necessary to make such provision valid and enforceable.
   3. No term or provision of this License shall be deemed waived and
   no breach consented to unless such waiver or consent shall be in
   writing and signed by the party to be charged with such waiver or
   consent.  4. This License constitutes the entire agreement between
   the parties with respect to the Work licensed here. There are no
   understandings, agreements or representations with respect to the
   Work not specified here. Licensor shall not be bound by any
   additional provisions that may appear in any communication from
   You. This License may not be modified without the mutual written
   agreement of the Licensor and You.