Copyright © 2008
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
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.
Décompactez liburbi-matlab et ajoutez le dossier lib/ et tous ses sous-dossiers vers le chemin de matlab.
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);
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
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');
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
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)
Table of Contents
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.
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
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');
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.
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.
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.