Introduction to liburbi Java for Urbi 1.x

Liburbi Java est une library générée à partir de la liburbi C++ avec l'outil appelé swig. Swig génère des classes wrapper en java pour toutes les classes C++ que nous voulons exporter. Il génère aussi du code JNI pour faire le lien entre java et la library C++. Avec cela en tête, vous comprendrez mieux que pour utiliser la liburbi java, vous aurez de toutes façon charger le code C++ JNI dans votre application. Nous fournissons ce code C++ dans une library partagée appelée urbijava.dll sous Windows, liburbijava.so sous Linux, et liburbijava.dylib sous MacOs. Pour charger la library dans votre code java, utilisez la fonction système .loadLibrary. Par exemple placez cet appel dans votre classe main comme ci-dessous:

// Toutes les classes liburbi se situent dans le package liburbi
import liburbi.main.UClient;
import liburbi.main.liburbi;

public class Main {

  static {
    System.loadLibrary("urbijava");
  }

NB: Le chemin vers la library que vous chargez 'urbijava' doit être dans votre chemin pour que votre programme puisse la trouver. Sous Windows assurez vous que la variable d'environnement contiens le chemin vers la library urbijava. Sous Unix assurez vous que votre LD_LIBRARY_PATH contiens le chemin de la library urbijava.

Pour se connecter à un serveur URBI, créez simplement une nouvelle instance de liburbi.main.UClient ( ou liburbi.main.USyncClient si vous voulez utiliser les fonctions synchrones décrites plus bas), en passant le nom ou l'adresse du serveur comme premier paramètre, et optionnellement le port comme second paramètre:

  public static void main (String[] arg) {

    UClient client = new UClient("myrobot.ensta.fr");

    // un wrapper est disponible aussi dans la classe liburbi.main.liburbi:
    // UClient client = liburbi.connect("myrobot.ensta.fr");

Le constructeur debutera un thread indépendant qui sera en attente de messages venant du serveur URBI.

Vous pouvez vérifier si la connection a été établie avec succès en appellant la fonction error, qui retourne la valeur zero en cas de succès, ou un code différent d ezero en cas d'erreur.

    if (client.error() != 0)
    {
	System.err.println("Couldn't connect to the URBI server.");
	return;
    }

La méthode send est le moyen le plus simple d'envoyer des commandes au serveur URBI. Il prends une String comme paramètre:

    int sleeptime = 50;

    client.send("motoron;");

    for (float val=0; val<=1; val+=0.05)
      client->send("neck.val = " + val + ";wait (" + sleeptime ");");

Quelques fonctions statiques sont définies dans la classe liburbi.liburbi: 'getComma ()', 'getSemicolon()', 'getPipe()' et 'getParallel()' et elles retournent les caractères ',', ';', '|' et '&' respectivement.

Pour envoyer des data binaires au robot, la méthode sendBin doit être utilisée. Elle prends comme paramètres le buffer à envoyer (nous supportons uniquement le type byte[] pour le moment) et sa taille, et en option une en-tête.

    client->sendBin(soundData, soundDataSize,
                    "speaker.val = BIN " + soundDataSize + " raw 2 16000 16 1;");

De la même façon vous pouvez utiliser sendBin pour jouer un son sur le robot, une méthode spécifique et efficace a été écrite à cet effet: sendSound.

client->sendSound("speaker", sound, "endsound");

Le premier paramètre est le périphérique son auquel envoyer nous envoyons le son, le second paramètre est une classe liburbi.main.USound décrivant le son à envoyer. Le troisième est un tag optionnel qui sera utilisé par le serveur pour émettre un message système "stop" quand le son sera fini. La fonction convert (in liburbi.liburbi class) peut être utilisée pour les conversions entre les différents formats de sons.

Il n'y a aucune limite à la taille du buffer de son, celui-ci étant automatiquement découpé en tronçons par la library. Les data sont copiés par la library: le paramètre USound et ses data associés peuvent être libérés en toute sécurité dés le retour de la fonction.

La plupart des messages reçus du serveur URBI sont le résultat d'une commande envoyée précédemment. Le fonctionnement des tags URBI autorise à lier un message à sa réponse: à chaque commande est associé un tag, et ce tag est répété dans le message de réponse. La classe liburbi.main.UClient gère la réception de ces messages dans le thread indépendant créé par le constructeur, les parse et remplis une structure UMessage.

Dans votre programme java, vous pouvez avoir des extensions de classes liburbi.main.UCallbackInterface et redéfinir sa méthode onMessage. Vous pouvez enregistrer ces classes avec la méthode UClient setCallback et les associer avec un tag. puis chaque fois qu'un message avec ce tag est envoyé au serveur, la fonction redéfinie onMessage sera appelée avec une classe liburbi.main.UMessage comme paramètre.

La classe liburbi.main.UCallbackInterface est définie ainsi:

package liburbi.main;

public class UCallbackInterface {
  public UCallbackAction onMessage(UMessage msg);
}

La fonction onMessage prends comme paramètre un liburbi.main.UMessage et retourne un enum: liburbi.main.UCallbackAction qui peut avoir deux valeurs: liburbi.main.UCallbackAction.URBI_CONTINUE ou liburbi.main.UCallbackAction.URBI_REMOVE (dans un tel cas le retour est enlevé, et ne sera plus appelé, même si vous recevez un message avec le même tag).

La fonction setCallback est définie ainsi:

package liburbi.main;

public class UClient {

  [...]
  public long setCallback(UCallbackInterface ref, String tag);
}

donnez comme premier paramètre votre classe redéfinie liburbi.main.UCallbackInterface, et donnez comme second argument une String correspondant au tag auquel vous voulez associer le retour.

La structure UMessage peut stocker les informations contenues dans toutes sortes de messages URBI en utilisant une fonction "getType" et une UValue (union de classes). Ces deux classes sont définies ainsi:

package liburbi.main;

public enum UMessageType {
  MESSAGE_SYSTEM, /// Message système
  MESSAGE_ERROR,  /// Message d'erreur
  MESSAGE_DATA;   /// Message contenant des data dans la UValue
}

public class UMessage {

  /// Server-side timestamp.
  public int getTimestamp();

  /// Tag associé.
  public String getTag();

  /// Type de la UValue contenue dans le UMessage
  public UMessageType getType();

  /// UValue contenue dans le UMessage
  public UValue getValue();

  public String getMessage();

  /// Raw message sans les data binaires.
  public String getRawMessage();

  /// Client d'où provient le message.
  public UAbstractClient getClient();
}

le champ type UMessageType peut être MESSAGE_SYSTEM, MESSAGE_ERROR ou MESSAGE_DATA. Si le type est MESSAGE_DATA, le message contiens une UValue.

package liburbi.main;

public enum UDataType {
  DATA_DOUBLE,
  DATA_STRING,
  DATA_BINARY,
  DATA_LIST,
  DATA_OBJECT,
  DATA_VOID;
}

public class UValue {

  public UDataType getType();

  /// valeur si de type UDataType.DATA_STRING
  /// vérifiez que cette chaîne n'est pas null (c'est possible du côté C++,
  /// souvenez vous que liburbijava est batie au-dessus de liburbic++)
  /// avec 'isStringNull ()'
  public String getString();
  public boolean isStringNull();

  /// valeur si de type UDataType.DATA_DOUBLE
  public double getDouble();

  /// valeur si de type UDataType.DATA_BINARY
  public UBinary getUBinary();

  /// valeur si de type UDataType.DATA_LIST
  public UList getUList();

  /// utilisé pour afficher correctement la UValue
  public String toString();
}

La UValue contiens un UDataType qui peut prendre les valeurs: DATA_DOUBLE, DATA_STRING, DATA_BINARY, DATA_LIST, DATA_OBJECT, DATA_VOID. Dependant de ce champ, la valeur correspondante dans la UValue sera réglée. Si la UValue est de type binaire, elle contient une classe UBinary définie ci-après. Le UBinaryType dans la structure UBinary donnera des informations additionnelles sur le type des data (BINARY_NONE, BINARY_UNKNOWN, BINARY_IMAGE, BINARY_SOUND), et la structure de son ou d'image adaptée sera complétée.

package liburbi.main;

public enum UBinaryType {
  BINARY_NONE,
  BINARY_UNKNOWN,
  BINARY_IMAGE,
  BINARY_SOUND;
}

public class UBinary {

  public UBinaryType getType();

  /// valeur si de type BINARY_IMAGE
  public UImage getUImage();

  /// valeur si de type BINARY_SOUND
  public USound getUSound();

  /// Taille des data
  public int getSize();

  public String getMessage();
  public String getExtraHeader();
}

package liburbi.main;

public enum USoundFormat {
  SOUND_RAW,
  SOUND_WAV,
  SOUND_MP3,
  SOUND_OGG,
  SOUND_UNKNOWN;
}

public enum USoundSampleFormat {
  SAMPLE_SIGNED(1),
  SAMPLE_UNSIGNED(2);
}

public class USound {

  /// taille total en byte
  public long getSize();

  /// Nombres de canaux audio
  public int getChannels();

  /// rate en Hertz
  public int getRate();

  /// taille du sample en bit
  public int getSampleSize();

  /// format des sound data
  /// (SOUND_RAW, SOUND_WAV, SOUND_MP3...)
  public USoundFormat getSoundFormat();

  /// format du sample
  public USoundSampleFormat getSampleFormat();

  /// data du sound dans une table de byte
  public byte[] getDataAsByte();
}

package liburbi.main;

public enum UImageFormat {
  IMAGE_RGB(1),
  IMAGE_YCbCr(2),
  IMAGE_JPEG(3),
  IMAGE_PPM(4),
  IMAGE_UNKNOWN;
}

public class UImage {

  /// taille de l'image en byte
  public long getSize();

  /// largeur d'image
  public long getWidth();

  /// hauteur d'image
  public long getHeight();

  /// IMAGE_RGB, IMAGE_YCbCr, IMAGE_JPEG...
  public UImageFormat getImageFormat();

  /// data de l'image data dans une table de byte
  public byte[] getDataAsByte();
}

import liburbi.main.*;

/// Callback pour des images
class onImage extends UCallbackInterface {

  public UCallbackAction onMessage(UMessage msg) {
    if (!(UMessageType.MESSAGE_DATA == msg.getType ()))
      return UCallbackAction.URBI_CONTINUE;
    UValue value = msg.getValue ();

    if (!(UDataType.DATA_BINARY == value.getType ()))
      return UCallbackAction.URBI_CONTINUE;
    UBinary bin = value.getUBinary ();

    if (!(UBinaryType.BINARY_IMAGE == bin.getType ()))
      return UCallbackAction.URBI_CONTINUE;
    UImage img = bin.getUImage ();
    byte[] data = img.getDataAsByte ();

    System.out.println("Image of size " + img.getWidth () + "x"
                       + img.height + " received");

    /// myDisplay*Image sont des fonctions customisées qui ne font pas parties de liburbi-java
    /// replacez par votre propre code
    if (img.imageFormat == UImageFormat.IMAGE_JPEG)
      myDisplayJPEGImage (data, img.getWidth (), img.getHeight ());
    else if (img.imageFormat == UImageFormat.IMAGE_YCbCr)
      myDisplayYCbCrImage (data, img.getWidth (), img.getHeight ());
    else if (img.imageFormat == UImageFormat.IMAGE_RGB)
      myDisplayRGBImage (data, img.getWidth (), img.getHeight ());

    return UCallbackAction.URBI_CONTINUE;
  }
}

/// Callback pour un sound
class onSound extends UCallbackInterface {

  public UCallbackAction onMessage(UMessage msg) {
    if (!(UMessageType.MESSAGE_DATA == msg.getType ()))
      return UCallbackAction.URBI_CONTINUE;
    UValue value = msg.getValue ();

    if (!(UDataType.DATA_BINARY == value.getType ()))
      return UCallbackAction.URBI_CONTINUE;
    UBinary bin = value.getUBinary ();

    if (!(UBinaryType.BINARY_SOUND == bin.getType ()))
      return UCallbackAction.URBI_CONTINUE;
    USound sound = bin.getUSound ();

    byte[] data = img.getDataAsByte ();

    System.out.println("Sound received");
    return UCallbackAction.URBI_CONTINUE;
  }
}

/// Callback pour des valeurs d'articulation
class onJoint extends UCallbackInterface {

  public UCallbackAction onMessage(UMessage msg) {
    if (!(UMessageType.MESSAGE_DATA == msg.getType ()))
      return UCallbackAction.URBI_CONTINUE;
    UValue value = msg.getValue ();

    if (!(UDataType.DATA_DOUBLE == value.getType ()))
      return UCallbackAction.URBI_CONTINUE;

    System.out.println("The joint value is " + value.getDouble ());
    return UCallbackAction.URBI_CONTINUE;
  }
}

public class test {
  static {
    /// Chargez la library C++ liburbi et le code jni.
    System.loadLibrary("urbijava");
  }

  public static void main(String argv[]) {

    UClient c = new UClient(argv[1]);

    if (c.error() != 0)
    {
	System.out.println("Couldn't connect to the URBI server.");
	System.exit(1);
    }

    onImage oi = new onImage ();
    onJoint oj = new onJoint ();
    onSound os = new onSound ();

    c.setCallback (oi, "img");
    c.setCallback (oj, "snd");
    c.setCallback (os, "joint");

    c.send("img: camera.val;");
    c.send("loop snd: micro.val,");
    c.send("joint: headPan.val;");


    liburbi.execute (); /// fonction qui fait une veille infinie
  }
}

Le projet liburbi java est chargé. Vous pouvez voir les trois packages de liburbi: liburbi.main, liburbi.image et liburbi.sound. A partir de la source dans ces trois packages, nous avons fait liburbijava.jar, que vous pouvez utiliser dans vos applications. Vous pouvez voir aussi les sources des différents exemples que nous fournissons. Nous les avons déposé dans les packages examples.nameofexample. Vous pouvez vous inspirer de ces exemples dans vos applications. Ici, nous allons voir comment les compiler et les faire tourner dans Eclipse

NB: Si Eclipse se plaint d'erreurs dans le code source, ce peut être que le niveau de compliance de votre compilateur est trop bas. Vous avez à régler le niveau de compliance du compilateur au moins sur Java 5 (Windows/Preferences/Java/Compiler).