Introduction to libURBI

Liburbi-c++ is a library designed to encapsulate an URBI connection. It handles the TCP connection with the URBI server, and the dispatching of messages it sends. The library is thread-safe and reentrant.

The library consists of two C++ classes, UClient and USyncClient, and a few helpful functions.

We expect the reader to be a bit familiar with the URBI syntax.

Most of the messages received from the URBI server are the results of a previously sent command. The mechanism of URBI tags enables to link a message to its reply: with each command is associated a tag, and this tag is repeated in the reply message. The UClient class handles the reception of those messages in the independant thread created by the constructor, parses them and fills a UMessage structure. Callback functions with an associated tag can be registered with the method registerCallback: each time a message with this tag is sent by the server, the callback function will be called with a UMessage structure as a parameter. The two basic forms of registerCallback are:

typedef UCallbackAction (*UCallback)             (const UMessage &msg);
typedef UCallbackAction (*UCustomCallback)       (void * callbackData, const UMessage &msg);

UCallbackID 	setCallback (UCallback cb, const char *tag)
UCallbackID 	setCallback (UCustomCallback cb, void *callbackData, const char *tag)

The first parameter is always a pointer to the function to call. callbackData is a pointer that will be given back to the callback function each time it is called. The callback function must return URBI_CONTINUE, or URBI_REMOVE, in which case the function will be unregistered.

A few examples:

UCallbackAction onImage(const UMessage &msg) {
  if (msg.binaryType != BINARYMESSAGE_IMAGE)
    return URBI_CONTINUE;
  msg.client.printf("Image of size (%d,%d) received from server at %d\n",msg.image.width, msg.image.height, msg.timestamp);

  unsigned char *image = new unsigned char[msg.image.width*msg.image.height*3];
  int sz = msg.image.width*msg.image.height*3;

  if (msg.image.imageFormat == IMAGE_JPEG) 
    convertJPEGtoRGB((const byte *) msg.image.data, msg.image.size, (byte *) image, sz); //provided by liburbi
  if (msg.image.imageFormat == IMAGE_YCbCr)
    convertYCrCbtoRGB((const byte *) msg.image.data, msg.image.size, (byte *) image);  //provided by liburbi

  myDisplayRGBImage(image, msg.image.width, msg.image.height);
  delete image;
  return URBI_CONTINUE;
}

UCallbackAction onSound(const UMessage &msg) {
  if (msg.binaryType != BINARYMESSAGE_SOUND)
    return URBI_CONTINUE;

  //convert the sound to a wav 16KHz 16bit.
  USound snd;
  snd.soundFormat = SOUND_WAV;
  snd.rate = 16000;
  snd.sampleSize = 16;
  snd.sampleFormat = SAMPLE_SIGNED;
  snd.channels = 0; //take the value from source
  snd.data = 0;
  snd.size = 0;
  convert(msg.sound, snd); //this function is provided by liburbi
  myPlayWAV(snd.data, snd.size);
  return URBI_CONTINUE;
}

UCallbackAction onJoint(const UMessage &msg) {
  if (msg.type != MESSAGE_DOUBLE)
    return URBI_CONTINUE;
  msg.client.printf("The joint value si %lf\n", msg.doubleValue);
  return URBI_CONTINUE;
}

int main(int argc, const char * argv[]) {
  UClient * cl = new UClient(argv[1]);
  if (cl->error()) urbi::exit(1); //portability call explaned below
  cl->setCallback(&onImage, "img");
  cl->setCallback(&onSound, "snd");
  cl->setCallback(&onJoint, "joint");
  cl->send("img: camera.val;");
  cl->send("loop snd: micro.val,");
  cl->send("joint: headPan.val;");
  urbi::execute();  //portability call explaned below
}

The UMessage structure is capable of storing the informations contained in any kind of URBI message by using a "type" field and a union of type-dependant structures. It is defined as follows:

class UMessage {
 public:  
  UAbstractClient    &client;   // connection from which originated the message
  int                timestamp;     // server-side timestamp
  char               *tag;          // associated tag
  
  UMessageType       type;          // type of the message
  UBinaryMessageType binaryType;    // type of binary message
  
  union {
    double        doubleValue;
    char          *stringValue;
    char          *systemValue;
    char          *message;        // filled if type is unknown (MESSAGE_UNKNOWN)
    USound        sound;           // filled if binary data is of the sound type
    UImage        image;           // filled if binary data is of the image type
    UBinary       binary;          // filled if binary data is of an unrecognised type
  }; 


class USound {
 public:
 char                  *data;            // pointer to sound data
 int                   size;             // total size in byte
 int                   channels;         // number of audio channels
 int                   rate;             // rate in Hertz
 int                   sampleSize;       // sample size in bit
 USoundFormat          soundFormat;      // format of the sound data (SOUND_RAW, SOUND_WAV, SOUDN_MP3...)
 USoundSampleFormat    sampleFormat;     // sample format
};

class UImage {
 public:
  char                  *data;            // pointer to image data
  int                   size;             // image size in byte
  int                   width, height;    // size of the image
  UImageFormat          imageFormat;      // IMAGE_RGB, IMAGE_YCbCr, IMAGE_JPEG...
};

The type field can be MESSAGE_DOUBLE, MESSAGE_STRING, MESSAGE_SYSTEM, MESSAGE_BINARY or MESSAGE_UNKNOWN. Depending of this field, the corresponding value in the union will be set. If the message is of the binary type, binaryType will give additional informations on the type of data (BINARYMESSAGE_SOUND, BINARYMESSAGE_IMAGE or BINARYMESSAGE_UNKNOWN), and the appropriate sound or image structure will be filled.

Template versions of registerCallback are also defined. They allow to set callbacks on member functions, with from 0 to 4 custom parameters of any type (including pointers and references). The only constraint on the function signature is that it must return a UCallbackAction, and take a const UMessage& as its last parameter. A few examples:

class Test {
   public:
     UCallbackAction onJoint(int value, const UMessage &msg);
}:

UCallbackAction  Test::onJoint(int value, const UMessage &msg) {
  msg.client.printf("got a message at %d with tag %s, our int is %d\n",msg.timestamp, msg.tag, value);
  return URBI_REMOVE;  //unregister ourself
}

int main(int argc, const char * argv[]) {
  Test *a = new Test();
  UClient * cl= new UClient(argv[1]);
  if (cl->error()) urbi::exit(1);
  cl->setCallback(*a, &Test::onJoint, 12, "tag");
  cl->send("tag: headPan.val;");
  urbi::execute();
}

The derived class USyncClient implements methods to synchronously get the result of URBI commands. You must be aware that these functions are less efficient, and that they will not work in the OPEN-R version of the liburbi, for instance.

double neckVal;
syncClient->syncGetDevice("neck",neckVal):

client->send("camera.resolution = 0;camera.gain = 2;");
int width, height;
client->syncGetImage("camera", myBuffer, myBufferSize, URBI_RGB, URBI_TRANSMIT_JPEG, width, height);

client->syncGetSound("micro", duration, sound);

We also have included a few functions to convert between different image and sound formats. The usage of the image conversion functions is pretty straightforward:

int convertRGBtoYCrCb(const byte* source, int sourcelen, byte* dest);
int convertYCrCbtoRGB(const byte* source, int sourcelen, byte* dest);
int convertJPEGtoYCrCb(const byte* source, int sourcelen, byte* dest, int &size);
int convertJPEGtoRGB(const byte* source, int sourcelen, byte* dest, int &size);

The size parameter must be set to the size of the destination buffer. On return it will be set to the size of the output data.

To convert between different sound formats, the function convert can be used. It takes two USound structures as its parameters. The two audio formats currently supported are SOUND_RAW and SOUND_WAV, but support for compressed sound formats such as Ogg Vorbis and MP3 is planned.. If any field is set to zero in the destination structure, the corresponding value from the source sound will be used.

Have a look at the examples, in the "example" or "utils" directory of the liburbi distribution. It currently contains:

Each program when invoked with no option will display its command line syntax and additional informations when apropriate.

When other versions of the liburbi will be available, (in particular an OPEN-R version that will allow programs to run on the robot), it will be possible to compile the same code for both libraries, if a few rules are respected: