Tutorial UObject pour Urbi 1.0

L'API définit la classe UObject. Chaque instance d'une classe dérivée de votre code C++ correspondra à un objet URBI partageant certaines de ses méthodes et de ses attributs. L'API fournit des méthodes pour déclarer quels éléments de votre objet seront partagés. Pour partager une variable avec URBI,Vous devez lui donner le type UVar. Ce type est un container qui fournis des opérateurs de tous les types connus à URBI: double, string et char*, et la structure de gestion des binaires UBinary, USound et UImage. Ce type peut aussi lire et écrire dans la classe liburbi UValue. L'API fournie des méthodes pour initialiser les retours de fonctions qui seront notifiés quand une variable sera modifiée ou lue par du code URBI. Les méthode d'instance de tout prototype peuvent être rendu accessible à partir d'Urbi, fournissant tous les types de paramètres et le type en retour peut être converti vers/à partir de UValue.

Le prochain chapitre couvre tous les aspects de l'API UObject, et le reste du document décrit plusieurs cas d'utilisation en détail.

Illustrons ces concepts en définissant un objet simple: adder. Cet objet a une variable v, et une méthode add qui retourne la somme de cette variable et de son paramètre.

En premier le include requis et le namespace.

#include <uobject.hh>
using namespace urbi;

puis nous déclarons notre classe adder:

class adder : public UObject //doit hériter de UObject
     {
     public:
     //la classe doit avoir un seul constructeur avec un paramètre string
        adder(string);

        UVar v; //notre variable

        double add(double ); //notre méthode
     };

Enfin l'implantation du constructeur et notre méthode add

//le constructeur défini ce qui est disponible venant d'Urbi
     adder::adder(string s): UObject(s) { //requis

        UBindVar(adder,v); //macro utilisée pour lier les variables
        UBindFunction(adder, add); //macro utilisée pour lier les méthodes
     }

     double adder::add(double secondValue) {
        return v+secondValue;
     }

     //register your class to the URBI kernel
     UStart(adder); //this line registers your class to URBI

Pour résumer:

Quand vous lancez un serveur URBI, un objet de chaque classe enregistrée avec UStart est créé avec le même nom que la classe. De nouvelles instances peuvent être créées d'Urbi en utilisant la commande new. Pour chaque instance créée dans URBI, l'instance correspondante de l'objet C++ est créée. Vous pouvez obtenir les paramètres passés au constructeur en définissant et liant une méthode nommée init avec les paramètres appropriés.

Vous pouvez enregistrer une fonction qui serra appelée à chaque accès ou modification d'une variable (uniquement pour les composants locaux) en appelant UNotifyChange et UNotifyAccess, en passant aussi bien une UVar ou un nom de variable name comme premier paramètre, et une fonction membre de votre UObject comme second paramètre. Cette fonction peut avoir zéro ou un paramètre: une UVar & pointant vers la UVar qui est accédée ou modifiée. Le retour de la fonction notifyChange est appelé après que la valeur de la variable est changée, Attendu que le retour de notifyAccess est appelé avant que la variable soit accédée, vous donne la possibilité de mettre à jour sa valeur.

L'API vous donne deux méthodes pour appeler une fonction périodiquement:

Dans URBI, une variable peut avoir différents sens dépendant de si on est en lecture ou en écriture: vous pouvez utiliser la même variable pour représenter la valeur cible d'un actionneur et la valeur courante mesurée par un capteur associé. Ce mode spécial est activé par le UObject définissant la variable en appelant USensor après avoir appelé UBindVar. Cet appel à l'effet suivant

Si USensor n'est pas appelée, alors la variable a seulement une valeur associée qui est écrite et lue par tous les modules et code URBI.

Vous pouvez lire ou écrire chaque variable URBI en créant une UVar et en passant son nom au constructeur. La valeur est changée en écrivant n'importe quel type compatible à la UVar, et accéder à sa valeur en recopiant l'uvar dans n'importe quel type compatible. Toutefois, des précautions doivent être prisent en mode remote: les changements sur les variables venant de code Urbi ou d'autres modules sont visibles seulement si vous avez appelé UNotifyChange pour cette variable. Autrement l'UVar n'est pas synchronisée. Sinon, en mode remote, vous pouvez obtenir la valeur sur demande en appelant UNotifyOnRequest(variable,fonction). Puis pour obtenir une valeur mise à jour, appelez la méthode requestValue pour la UVar, et votre fonction callback sera appelée dés que la valeur sera disponible. Vous pouvez lire et écrire toutes les propriétés URBI d'une UVar en lisant et écrivant l'objet UProp approprié dans l'UVar.

URBI peut stocker des objets binaires de tous types dans un container générique, et fournir des structures spécifiques pour les sons et les images. Le container générique est appelé UBinary et est défini dans l'en-tête uobject.h. Il contient un champ enum qui donne le type du binaire(UNKNOWN(inconnu), SOUND(son) ou IMAGE(image)), et l'union d'une stucture USound et UImage contenant un pointeur vers les données, la taille des données et les méta-informations spécifiques à ce type. Lire un UBinary à partir d'une UVar, et écrire un UBinary dans une UVar exécute un deep-copy des données. En mode plugin, vous pouvez accéder directement au buffer utilisé par le kernel en dupliquant l'UVar dans une UImage ou une USound. Vous pouvez enfin écrire dans le buffer, mais vous ne pouvez changer aucune autre information.

Parfois, vous avez besoin d'exécuter des actions sur un groupe d'UObjects, pour des périphériques d'instances qui ont besoin d'être mis à jour ensemble. L'API fournis la classe UObjectHub pour cet usage. Pour créer un hub, déclarez simplement une sousclasse de UObjectHub, et enregistrez la en appelant une fois la macro UStartHub(classname). Une seule instance de cette classe sera créée à chaque démarrage du serveur. Les instances UObject peuvent être enregistrées dans ce hub en appelant instances URegister(hubclassname). Des Timers peuvent être liés à UObjectHub de la même façon que pour UObject (voir la section timers plus haut). Le kernel appelera la méthode update() de tout UObject avant d'appeler la méthode update() du hub. Une instance hub peut être récupérée en appelant getUObjectHub(string classname). le hub contient aussi la liste des UObject enregistrés dans ses attributs de membre.

Si vous avez besoin d'envoyer du code URBI au serveur, la macro URBI() est disponible, aussi bien que la fonction unarmorAndSend(). Vous pouvez aussi bien lui passer une string, ou directement du code URBI code à l'intérieur d'une paire de parenthèses:

unarmorAndSend("tag:1+1;");
URBI((
      at (someevent(x))
      {
        sometag:echo x;
      };
    ));

Ecrivons un UObject pour un périphérique servomoteur dont l'API de sous-couche est:

Notre en-tête vient en premier. Notre périphérique servo fournit un attribut nommé val, le nom standard URBI, et deux façon de régler le gain PID: une méthode, et trois variables.

class servo : public UObject //doit hériter du UObject
     {
     public:
     //La classe doit avoir un constructeur unique prenant une string
        servo(string);

        UVar val; //notre variable de position
        UVar P; //P gain
        UVar I; //I gain
        UVar D; //D gain

        int valueChanged(UVar &v); //rappel de changement de val
        int valueAccessed(UVar &v); //rappel pour l'accès à val
        int pidChanged(UVar &v); // rappel pour le changement de PID
        void setPID(int p, int i, int d);
        int init(int id); //constructeur URBI

        int id;
     };

Le constructeur enregistre uniquement l'init, afin que notre instance par défaut ne fasse rien, et puisse seulement être utilisée pour créer de nouvelles instances.

//Le constructeur enregistre uniquement l'init
     servo::servo(string s): UObject(s) { //required
        UBindFunction(servo, init); //register init
     }

La fonction init, est appelée dans une nouvelle instance chaque fois qu'une nouvelle instance URBI est créée, enregistre les trois variables (val, P, I and D), et initialise les fonctions de retour.

int servo::init(int id) { //constructeur URBI
        this->id=id;
        if (!initialize(id)) return 1;
        UBindVar(servo,val);
        USensor(val); //val est à la fois un capteur et un actionneur
        val.blend = UMIX; //règle le mode du blend sur mix
        UBindVar(servo,P);
        UBindVar(servo,I);
        UBindVar(servo,D);
        UBindFunction(servo, setPID);
        UNotifyChange(val, &servo::valueChanged);
        UNotifyAccess(val, &servo::valueAccessed);
        UNotifyChange(P, &servo::pidChanged);
        UNotifyChange(I, &servo::pidChanged);
        UNotifyChange(D, &servo::pidChanged);
        return 0;
     }

Puis nous définissons notre méthode de retour. servo::valueChanged sera appelé chaque fois que la variable val est modifiée, juste après que la valeur est changée: nous utilisons cette méthode pour envoyer notre commande au servo. servo::valueAccessed est appelée juste avant que la valeur soit lue. Dans cette fonction nous demandons au servo la valeur courante, et nous réglons val en conséquence.

//appelée chaque fois que la valeur est écrite
     int servo::valueChanged(UVar & v) { //v is a ref. to val
        setPosition(id, (double)val);
        return 0;

     //appelée chaque fois que la valeur est lue
     int servo::valueAccessed(UVar & v) { //v is a ref. to val
        val = getPosition(id);
        return 0;
     }

servo::pidChanged appelée chaque fois que l'une des variables PID est écrite. La fonction servo::setPID peut être appelée directement à partir d'Urbi.

int servo::pidChanged(UVar &v) {
        setPID(id, (int)P, (int)I, (int)D);
        return 1;
     }
     void servo::setPID(int p, int i, int d) {
        setPID(id, p, i, d);
        P=p;I=i;D=d;
     }
      //enregistre la classe servo dans le kernel d'Urbi
       UStart(servo);

Ca y ai, c'est fini, compilez ce module, et vous pouvez l'utiliser dans URBI:

//crée une nouvelle instance et appelle init(1)
    headPan = new servo(1);
    headPan.setPID(8,2,1); //calls setPID()
    headPan.val=13; //calls valueChanged()
    headPan.val*12; //calls valueAccessed()
    //periodically calls valueChanged()
    headPan.val = 0 sin:1s ampli:20,
    //periodically calls valueAccessed()
    at (headPan.val < 0) echo "left";

Le code d'exemple au dessus présente un problème: valueAccessed et valueChanged sont appelées chaque fois que la valeur est lue ou écrite depuis Urbi, ce qui peut arriver souvent. C'est un problème si l'envoi de la commande actuelle (setPosition dans notre exemple) prends du temps pour s'exécuter. Il y a deux solutions à cette question:

class servo : public UObject //hérite de UObject
     {
     public:
     //La classe doit avoir un constructeur unique prenant une string
        servo(string);

        UVar val; //notre variable de position

        virtual int update(); //appelée périodiquement
        int getVal(); //appelée périodiquement
        int init(int id); //constructeur URBI

        int id;
     };

int servo::init(int id) { //constructeur urbi
        this->id=id;
        if (!initialize(id)) return 0;
        UBindVar(servo,val);
        USensor(val); //val est à la fois un capteur et un actionneur
        USetUpdate(1); //appellera update() périodiquement
        USetTimer(1, &servo::getVal); //idem pour getVal()
        return 0;
     }

maintenant, supposons que, pour notre exemple précédent, nous pourrions accélérer les choses en envoyant toutes les commandes du servomoteur en même temps, en utilisant la méthode setPositions(int count, int *ids, double * positions) qui prends deux champs pour ids et positions. Le hub est le meilleur moyen de remplir cette tâche. L'en-tête UObject reste la même. Nous ajoutons une déclaration de hub:

class servohub : public UObjectHub
     {
     public:
     //La classe doit avoir un constructeur unique prenant une string
        servohub(string s);

        virtual int update(); //appelée périodiquement
        void addValue(int id, double val); //appelée par le servo
        int * ids; double * vals; int size; int count;
     };

servo::update devient un appel à la méthode addValue du hub:

int servo::update() {
     ((servohub*)getUObjectHub("servohub"))->addValue(id,
     (double)val);
     };

La ligne suivante peut être ajoutée à la méthode d'initialisation du servo, toutefois elle n'a pas d'utilité dans notre exemple:

URegister(servohub);

Finalement, l'implantation de notre méthode de hub est:

servohub::servohub(string s)
        :UObjectHub(s), ids(0),vals(0),size(0), count(0) {
        USetUpdate(1); //initialisation du timer
     }

     int servohub::update() { //appelée périodiquement
        setPositions(count, ids, vals);
        count=0; //reset le compteur de position
        return 0;
     }

     void servohub::addValue(int id, double val) {
        if (count+1<size) { //allocate more memory
            ids=(int *)realloc(ids, (count+1)*sizeof(int);
            vals=(double*)realloc(vals, (count+1)*sizeof(double);
            size = count+1;
        }
        ids[count]=id; vals[count++]=val;
     }
     UStartHub(servohub); //n'oubliez pas cette ligne

Périodiquement, la méthode update est appelée pour chaque instance de servo, qui ajoute des commandes au champs hub, puis la méthode update du hub est appelée, envoyant actuellement la commande et initialisant le champ.

int servohub::update() { //appelée périodiquement
        for (UObjectList::iterator it=members.begin();
            it!=members.end();it++) {
            addValue(((servo*)*it)->id, (double)((servo*)*it)->val);
        }
        setPositions(count, ids, vals);
        count=0; //reset le compteur de position
        return 0;
     }

Un périphérique caméra est un uobject dont le champ val est un objet binaire. Le kernel urbi lui-même ne différencie pas entre tout les formats binaire possibles et les types de données, mais l'API fournit des structures spécifiques aux images par commodité. Vous devez être prudent avec la gestion de la mémoire. La structure UBinary gère sa propre mémoire: les copies sont des deep copy, et le destructeur libère le buffer associé. Les structures UImages et Usound ne le font pas.

Supposons que nous ayons une API caméra en sous-couche avec les fonctions suivantes :

Le code de notre périphérique peut être écrit comme suit:

class Camera : public UObject //hérite de UObject
     {
     public:
     //la classe doit avoir un constructeur unique prenant une string
        Camera(string);

        UVar val; //notre variable image
        UVar width,height; //taille de l'image

        int getVal(UVar &); //appelée sur accès
        virtual int update(); //appelée périodiquement
        int init(int id); //constructeur URBI

        int frame; //compteur de frame de catching
        int accessFrame; //numéro de la frame du dernier accès
        int id; //caméra id
        UBinary bin;
     };

Initialisation des registres du constructeur:

//Initialisation des registres du constructeur
     Camera::Camera(string s): UObject(s),frame(0) { //required
        UBindFunction(Camera, init); //register init
     }

La fonction init lit la variable, une fonction appelée sur accès, et met en route un chronomètre sur update. elle initialise également la structure de UBinary.

int Camera::init(int id) { //constructeur urbi
        this->id=id;
        frame=0; accessFrame = 0;
        if (!initialize(id)) return 0;
        UBindVar(Camera,val);
        UBindVar(Camera,width);
        UBindVar(Camera,height);
        width = getWidth(id); height = getHeight(id);
        USetUpdate(1); //appellera update() periodiquement
        UNotifyAccess(val, &Camera::getVal);
        bin.type=BINARY_IMAGE;
        bin.image.width = width;
        bin.image.height=height;
        bin.image.imageFormat = IMAGE_RGB;
        bin.image.size = width*height*3;
        return 0;
     }

La fonction update met simplement à jour le compteur de frames

int Camera::update() {
        frame++;
        return 0;
     }

getVal met à jour la valeur de la caméra, seulement si elle n'a jamais été appelée par cette frame, qui prévoit un simple mécanisme de mise en cache afin d'éviter trop souvent l'exécution d'une potentiellement longue opération d'acquisition d'une image.

int Camera::getVal(UVar & ) {
      if (frame==accessFrame) return 1;
      bin.image.data = getImage(id);
      val = bin; //assign image to bin
     }
UStart(Camera);

Les données de l'image sont copiées dans le kernel quand on procède de cette façon.

Soyez prudent, supposons que nous ayons créé la structure UBinary dans la méthode getVal, notre buffer aura été libéré à la fin de la fonction. pour éviter cela, réglez le à 0 après avoir assignée la UBinary à la UVar.

La manipulation des sons est similaire à celle des images, la structure USoundest est fournies pour cette utilisation. La meilleur façon d'implémenter un microphone est de remplir la variable val du UObject avec les données du son correspondant à une période du kernel. Si vous faites ainsi, le code Urbi loop tag:micro.val produira le résultat escompté.

Les algorithmes qui nécessite une grosse puissance de calcul peuvent être écrit en C++ mais sont toujours utilisable dans Urbi: Ils récupèrent leurs données en utilisant les variables des autres modules référencés par UVar, et exporte leurs résultats dans d'autres UVar. Considérons le cas d'un périphérique de détection de balle qui reçoit une image en entrée, et envoie en sortie les coordonnées de la balle, si il y en a une de détectée.

L'en-tête est définie ainsi:

class BallTracker : public UObject //hérite de l'UObject
     {
     public:
     //la classe doit avoir un constructeur unique prenant une string
        BallTracker(string);

        UVar visible; //la balle est elle visible?
        UVar x,y; //coordonnées de la balle

        int init(string varname); //constructeur Urbi
     };

initialise seulement les registres du constructeur:

//initialise seulement les registres du constructeur
     BallTracker::BallTracker(string s): UObject(s) { //requis
        UBindFunction(BallTracker, init); //initialisation des registres
     }

La fonction d'initialisation lie les variables et un callback sur la mise à jour de la variable de l'image passée en paramètre.

int BallTracker::init(string cameraval) { //constructeur urbi
        UBindVar(BallTracker,visible);
        UBindVar(BallTracker,x);
        UBindVar(BallTracker,y);
        UNotifyChange(cameraval, &BallTracker::newImage);
        visible = 0;
        return 0;
     }

La fonction newImage fait tourner l'algorithme de détection sur l'image qui est dans ses paramètres, et met à jour les variables.

int BallTracker::newImage(UVar &v) {
        UImage i = v; //recopie dans UImage
        int px,py;
        bool found = detectBall(i.data, i.width, i.height, &px,
     &py);
        if (found) {
            visible = 1;
            x = px/i.width;
            y = py/i.height;
        } else {
            visible = 0;
        }
        return 0;
     }