The Urbi Software Development Kit

No knowledge of the urbiscript language is needed. As a matter of fact, Urbi can be used as a standalone middleware architecture to orchestrate the execution of existing components.

Yet urbiscript is a feature that “comes for free”: it is easy using it to experiment, prototype, and even program fully-featured applications that orchestrate native components. The interested reader should read either the urbiscript user manual (Part II), or the reference manual (Chapter 22).

This part is not an urbiscript tutorial; it is not structured in a progressive manner and is too detailed. Think of it as a dictionary: one does not learn a foreign language by reading a dictionary. For an urbiscript Tutorial, see Part II.

This part does not aim at giving advanced programming techniques. Its only goal is to deﬁne the language and its libraries.

1.6 Documentation

Chapter 2
Getting Started

urbiscript comes with a set of tools, two of which being of particular importance:

Please, ﬁrst make sure that these tools are properly installed. If you encounter problems, please see the frequently asked questions (Chapter 17), and the detailed installation instructions (Chapter 16).

There are several means to interact with a server spawned by urbi, see Section 21.3 for details. First of all, you may use the options ‘-e’/‘--expression code ’ and ‘-f’/‘--file file ’ to send some code or the contents of some file to the newly run server. The option ‘q’/‘--quiet’ discards the banner.

You may combine any number of these options, but beware that being event-driven, the server does not “know” when a program ends. Therefore, batch programs should end by calling shutdown. Using a Unix shell:

To run an interactive session, use option ‘-i’/‘--interactive’. Like most interactive interpreters, Urbi will evaluate the given commands and print out the results.

The output from the server is preﬁxed by a number surrounded by square brackets: this is the date (in milliseconds since the server was launched) at which that line was sent by the server. This is useful at occasions, since Urbi is meant to run many parallel commands. But since these timestamps are irrelevant in most examples, they will often be ﬁlled with zeroes through this documentation.

Under Unix, the program rlwrap provides additional services (history of commands, advanced command line edition etc.); run ‘rlwrap urbi -i’.

In either case the server can also be made available for network-based interactions using option ‘--port port ’. Note that while shutdown asks the server to quit, quit only quits one interactive session. In the following example (under Unix) the server is still available for other, possibly concurrent, sessions.

Under Windows, instead of using telnet, you may use Gostai Console (part of the package), which provides a Graphical User Interface to a network-connection to an Urbi server. To launch the server, run:

and to launch the client, click on Gostai Console which is installed by the installer.

Then, the interaction proceeds in the Gostai Console windows. Specify the host name and port to use (‘127.0.0.1:54000’) in the text ﬁeld in the top of the window and click on the right to start the connection.

The program urbi-send (see Section 21.8) provides a nice interface to send batches of instructions (and/or ﬁles) to a running server.

You can now send commands to your Urbi server. If at any point you get lost, or want a fresh start, you can simply close and reopen your connection to the server to get a clean environment. In some cases, particularly if you made global changes in the environment, it is simpler to start anew: shut your current server down using the command shutdown, and spawn a new one. In interactive mode you can also use the shortcut sequence Ctrl-D, like in many other interpreters.

In case of a foreground task preventing you to execute other commands, you can use Ctrl-C to kill the foreground task, clear queued commands and restore interactive mode.

Part I
Urbi and UObjects User Manual

About This Part

No knowledge of the urbiscript language is needed. As a matter of fact, Urbi can be used as a standalone middleware architecture to orchestrate the execution of existing components.

Chapter 3
Quick Start

This chapter presents Urbi SDK with a speciﬁc focus on its middleware features. It is self-contained in order to help readers quickly grasp the potential of Urbi used as a middleware. References to other sections of this document are liberally provided to point the reader to the more complete documentation; they should be ignored during the ﬁrst reading.

3.1 UObject Basics

As a simple running example, consider a (very) basic factory. Raw material delivered to the factory is pushed into some assembly machines, which takes some time.

3.1.1 The Objects to Bind into Urbi

As a ﬁrth component of this factory, the core machine of the factory is implemented as follows. This class is pure regular C++, it uses no Urbi feature at all.

The header ‘machine.hh’, which declares Machine, is traditional. The documentation uses the Doxygen syntax.

3.1.2 Wrapping into an UObject

By binding a UObject, we mean using the UObject API to declare objects to the Urbi world. These objects have member variables (also known as attributes) and/or member functions (also known as methods) all of them or some of them being declared to Urbi.

One could modify the Machine class to make it a UObject, yet we recommend wrapping pure C++ classes into a diﬀerent, wrapping, UObject. It is strongly suggested to aggregate the native C++ objects in the UObject — rather than trying to derive from it. By convention, we prepend a “U” to the name of the base class, hence the UMachine class. This class provides a simpliﬁed interface, basically restricted to what will be exposed to Urbi. It must derive from urbi::UObject.

The implementation of UMachine is simple. It uses some of the primitives used in the binding process (Section 4.2):

Urbi relies on the prototype model for object-oriented programming, which is somewhat diﬀerent from the traditional C++ class-based model (Chapter 8). This is reﬂected by the presence of two diﬀerent constructors:

3.1.3 Running Components

As a ﬁrst beneﬁt from using the Urbi environment, this source code is already runnable! No main function is needed, the Urbi system provides one.

3.1.3.1 Compiling

Of course, beforehand, we need to compile this UObject into some loadable module. The Urbi modules are shared objects, i.e., libraries that can be loaded on demand (and unloaded) during the execution of the program. Their typical ﬁle names depend on the architecture: ‘machine.so’ on most Unix platforms (including Mac OS X), and ‘machine.dll’ on Windows. To abstract away from these diﬀerences, we will simply use the base name, ‘machine’ with the Urbi tool chain.

There are several options to compile our machine as a UObject. If you are using Microsoft Visual Studio, the Urbi SDK installer created a “UObject” project template accessible through the “New project” wizard. Otherwise, you can use directly your regular compiler tool chain. You may also use umake-shared from the ‘umake-*’ family of programs (Section 21.10.2):

3.1.3.2 Running UObjects

There are several means to toy with this simple UObject. You can use urbi-launch (Section 21.5) to plug the UMachine in an Urbi server and enter an interactive session.

You may also launch the machine UObject in the background, as a network component:

and interact with it using your favorite client (telnet, netcat, socat, …), or using the urbi-send tool (Section 21.8).

3.2 Using urbiscript

urbiscript is a programming language primarily designed for robotics. Its syntax is inspired by that of C++: if you know C, C++, Java or C#, writing urbiscript programs is easy. It’s a dynamic object-oriented (Chapter 11) scripting language, which makes it well suited for high-level application. It supports and emphasizes parallel (Chapter 13) and event-based programming (Chapter 14), which are very popular paradigms in robotics, by providing core primitives and language constructs.

Thanks to its client/server approach, one can easily interact with a robot, to monitor it, or to experiment live changes in the urbiscript programs.

Courtesy of the UObject architecture, urbiscript is fully integrated with C++. As already seen in the above examples (Section 3.1.3), you can bind C++ classes in urbiscript seamlessly. urbiscript is also integrated with many other languages such as Java (Chapter 5), MatLab or Python. The UObject framework also naturally provides urbiscript with support for distributed architectures: objects can run in diﬀerent processes, possibly on remote computers.

3.2.1 The urbiscript Scripting Language

The following example shows how one can easily interface UObjects into the urbiscript language. The following simple class (actually, a genuine object, in urbiscript “classes are objects”, see Chapter 11) aggregates two assembly machines, a fast one, and a slow one. This class demonstrates usual object-oriented, sequential, features.

3.2.2 Concurrency

Why should we wait for the slow job to ﬁnish if we have a fast machine available? To do so, we must stop requesting a sequential composition between both calls. We did that by using the sequential operator, ‘;’. In urbiscript, there exists its concurrent counter-part: ‘,’. Indeed, running a, b means “launch the program a and then launch the program b”. The urbiscript Manual contains a whole section devoted to explaining these operators (Chapter 13).

3.2.2.1 First Attempt

Since Urbi cannot expect that your code is thread-safe, by default all calls to UObject features are synchronous, or blocking: the whole Urbi system is suspended until the function returns. There is a single thread of execution for Urbi, and when calling a function from a (plugged) UObject, that thread of execution is devoted to evaluated the code.

See for instance below that, in even though f.assemble is slow and launched in background, the almost instantaneous display of ping is not performed immediately.

There are several means to address this unintended behavior. If the base library provides a threaded API (in our example, the Machine class, not the UMachine UObject wrapper), then you could use it. Yet we don’t recommend it, as it takes away from Urbi the possibility to really control concurrency issues (for instance it cannot turn non-blocking functions into blocking functions).

A better option is to ask Urbi to turn blocking function calls into non-blocking ones.

3.2.2.2 Second Attempt: Threaded Functions

If you read carefully the body of the UMachine::init function, you will ﬁnd the following piece of code:

Both calls bind the function UMachine::assemble, but the second one will run the call in a separate thread. Since multiple calls to a single function (or diﬀerent functions of a single object etc.) are likely to fail, a locking model must be provided. Here, urbi::LOCK_FUNCTION means that concurrent calls to UMachine::assemble must be serialized: one at a time.

To use this threaded version of assemble, we can simply patch our TwoMachineFactory class:

You may have noticed that the result is no longer reported. Indeed, the urbiscript interactive shell only displays the result of synchronous expressions (i.e., those ending with a ‘;’): asynchronous answers are confusing (see the inversion here).

3.3 Conclusion

This section gave only a quick glance to all the power that Urbi provides to support concurrency. Actually, it makes plenty of sense to embed an Urbi engine in a native C++ program, and to delegate the concurrency issues to it. Thanks to its middleware and client/server architecture, it is then possible to connect it to remote components of diﬀerent kinds, such as using ROS for instance.

Then, a host of features are at hand, ready to be used when you need them: event-driven programming, automatic monitoring of expressions, interactive sessions, …and, last but not least, the urbiscript programming language.

Chapter 4
The UObject API

The UObject API can be used to add new objects written in C++ to the urbiscript language, and to interact from C++ with the objects that are already deﬁned. We cover the use cases of controlling a physical device (servomotor, speaker, camera…), and interfacing higher-lever components (voice recognition, object detection…) with Urbi.

The C++ API deﬁnes the UObject class. To each instance of a C++ class deriving from UObject will correspond an urbiscript object sharing some of its methods and attributes. The API provides methods to declare which elements of your object are to be shared. To share a variable with Urbi, you have to give it the type UVar. This type is a container that provides conversion and assignment operators for all types known to Urbi: double, std::string and char*, and the binary-holding structures UBinary, USound and UImage. This type can also read from and write to the liburbi UValue class. The API provides methods to set up callbacks functions that will be notiﬁed when a variable is modiﬁed or read from Urbi code. Instance methods of any prototype can be rendered accessible from urbiscript, providing all the parameters types and the return type can be converted to/from UValue.

4.1 Compiling UObjects

UObjects can be compiled easily directly with any regular compiler. Nevertheless, Urbi SDK provides two tools to compile UObject seamlessly.

In the following sections, we will try to compile a shared library named ‘factory.so’ (or ‘factory.dll’ on Windows platforms) from a set of four ﬁles (‘factory.hh’, ‘factory.cc’, ‘ufactory.hh’, ‘ufactory.cc’). These ﬁles are stored in a ‘factory.uob’ directory; its name bares no importance, yet the ‘*.uob’ extension makes clear that it is a UObject.

In what follows, urbi-root denotes the top-level directory of your Urbi SDK package, see Section 16.2.

4.1.1 Compiling by hand

4.1.2 The umake-* family of tools

or ﬁnally, if you give no argument at all, the sources in the current directory:

4.1.3 Using the Visual C++ Wizard

If you installed Urbi SDK using its installer, and if you had Visual C++ installed, then the UObject wizard was installed. Use it to create your UObject code:

4.2 Creating a class, binding variables and functions

Let’s illustrate those concepts by deﬁning a simple object: adder. This object has one variable v, and a method add that returns the sum of this variable and its argument.

4.3 Creating new instances

When you start an Urbi server, an object of each class registered with UStart is created with the same name as the class. New instances can be created from Urbi using the new method. For each instance created in Urbi, a corresponding instance of the C++ object is created. You can get the arguments passed to the constructor by deﬁning and binding a method named init with the appropriate number of arguments.

4.4 Binding functions

4.4.1 Simple binding

The procedure to register new types to this system is explained in Section 4.18.

4.4.2 Multiple bindings

If you have multiple functions to bind, you can use the UBindFunctions macro to bind multiple functions at once:

4.4.3 Asynchronous binding

Functions bound using UBindFunction are called synchronously, and thus block everything until they return.

If you wish to bind a function that requires a non-negligible amount of time to execute, you can have it execute in a separate thread by calling

The function code will be executed in a separate thread without breaking the urbiscript execution semantics.

The lock-mode argument can be used to prevent parallel execution of multiple bound functions if your code is not thread-safe. It can be any of the following values.

Other queue sizes can be used by passing LockSpec(LOCK_FUNCTION, my-queue-size) as lock-mode.

There is a restriction to the locking mechanism: you cannot mix multiple locking modes. For instance a function bound with LOCK_FUNCTION mode will not prevent another function bound with LOCK_INSTANCE from executing in parallel.

You can perform your own locking using semaphores if your code needs a more complex locking model.

You can limit the maximum number of threads that can run in parallel by using the setThreadLimit function.

4.5 Notiﬁcation of a variable change or access

You can register a function that will be called each time a variable is modiﬁed by calling UNotifyChange(var, func).

The function can take 0 or 1 argument. If the argument is of type UVar&, then the function will receive the UVar that was passed to UNotifyChange. If it is of any other type, then the new value in the UVar will be converted to this type and passed to the function.

In plugin mode, there is a similar mechanism to create a getter function that will be called each time an UVar is accessed: the UNotifyAccess function. It has the same signature as UNotifyChange, and calls the given function each time someone tries to access the UVar. The function can update the value in the UVar before the access takes place. Usage of UNotifyAccess should be reserved to infrequently used UVar that take a long time to update, as it disrupts the data ﬂow between UObject.

You can remove all notiﬁes associated to any given UVar by calling its unnotify function.

4.5.1 Threaded notiﬁcation

In a manner similar to UBindThreadedFunction, you can request your callback function to be called in a separate thread by using UNotifyThreadedChange(var, func, lock-mode).

There is one restriction: the callback function must not take a UVar& as argument. This restriction is here to ensure that each invocation of your callback will receive the correct value that the source UVar had at call time.

4.6 Data-ﬂow based programming: exchanging UVars

The UNotifyChange and UNotifyAccess features can be used to link multiple UObjects together, and perform data-ﬂow based programming: the UNotifyChange can be called to monitor UVars from other UObjects. Those UVars can be transmitted through bound function calls.

One possible pattern is to have each data-processing UObject take its input from monitored UVars, given in its constructor, and output the result of its processing in other UVars. Consider the following example of an object-tracker:

The following urbiscript code would be used to initialize an ObjectTracker given a camera:

Using this model, chains of processing elements can be created. Each time the UObject at the start of the chain updates, all the notifyChange will be called synchronously in cascade to update the state of the intermediate components.

4.7 Data-ﬂow based programming: InputPort

Urbi provides a second and more standard way to perform data-ﬂow programming. In this approach, inputs of a component are declared as local InputPort, and the binding between this InputPort and the output of another component is done in urbiscript using the >> operator between two UVar:

4.7.1 Customizing data-ﬂow links

The >> operator to establish a data-ﬂow link between two UVar returns an object of type UConnection that can be used to customize the link.

The function uobjects.connectionStats() can be used to display the statistics of all the connections, and uobjects.resetConnectionStats() can be called to reset all statistics.

4.8 Timers

4.9 The special case of sensor/actuator variables

In Urbi, a variable can have a diﬀerent meaning depending on whether you are reading or writing it: you can use the same variable to represent the target value of an actuator and the current value measured by an associated sensor. This special mode is activated by the UObject deﬁning the variable by calling UOwned after calling UBindVar. This call has the following eﬀects:

4.10 Using Urbi variables

The C++ class UVar is used to represent any Urbi slot in C++. To bind the UVar to a speciﬁc slot, pass its name to the UVar constructor, or its init method. Once the UVar is bound, you can write any compatible type to it, and the new value will be visible in urbiscript. Similarly, you can cast the UVar (or use the as() method) to convert the current urbiscript value held to any compatible type.

Some care must be taken in remote mode: changes on the variable coming from Urbi code or an other module can take time to propagate to the UVar. By default, all changes to the value will be sent to the remote UObject. To have more control on the bandwidth used, you can disable the automatic update by calling unnotify(). Then you can get the value on demand by calling UVar::syncValue().

You can read and write all the Urbi properties of an UVar by reading and writing the appropriate UProp object in the UVar.

4.11 Emitting events

The UEvent class can be used to create and emit urbiscript events. Instances are created and initialized exactly as UVar: either by using the UBindEvent macro, or by calling one of its constructors or the init function.

Once initialized, the emit function will trigger the emission of the associated urbiscript event. It can be called with any number of arguments, of any compatible type.

4.12 UObject and Threads

The UObject API is thread-safe in both plugin and remote mode: All API calls including operations on UVar can be performed from any thread.

4.13 Using binary types

Urbi can store binary objects of any type in a generic container, and provides speciﬁc structures for sound and images. The generic containers is called UBinary and is deﬁned in the ‘urbi/ubinary.hh’ header. It contains an enum ﬁeld type giving the type of the binary (UNKNOWN, SOUND or IMAGE), and an union of a USound and UImage struct containing a pointer to the data, the size of the data and type-speciﬁc meta-information.

4.13.1 UVar conversion and memory management

The UBinary manages its memory: when destroyed (or going out-of-scope), it frees all its allocated data. The USound and UImage do not.

Reading an UBinary from a UVar, and writing a UBinary, USound or UImage to an UVar performs a deep-copy of the data (by default, see below).

Reading a USound or UImage from an UVar directly will perform a shallow copy from the internal data. The structure content is only guaranteed to be valid until the function returns, and should not be modiﬁed.

4.13.2 Binary conversion

To convert between various sound and image formats, two functions are provided in the header ‘urbi/uconversion.hh’:

4.13.3 0-copy mode

In plugin mode, you can setup any UVar in 0-copy mode by calling setBypass(true). In this mode, binary data written to the UVar is not copied, but a reference is kept. As a consequence, the data is only available from within registered notifyChange callbacks. Those callbacks can use UVar::val() or cast the UVar to a UBinary & to retrieve the reference. Attempts to read the UVar from outside notifyChange will block until the UVar is updated again, and copy the value at this time.

An example will certainly clarify: Let us ﬁrst declare an UObject that will generate binary data using 0-copy mode.

Let us then declare an other component that will access this binary data without any copy:

Typing OptimizedImageSource.val in urbiscript will wait for the next update from OptimizedImageSource::update and copy the data at this point.

4.14 Direct Communication between UObjects

For modularity reasons, all interactions between UObjects should go through the various middleware communication mechanisms, mainly InputPort and UNotifyChange. But it is possible to access directly the C++ instance of an UObject:

4.15 Using hubs to group objects

Sometimes, you need to perform actions for a group of UObjects, for instance devices that need to be updated together. The API provides the UObjectHub class for this purpose. To create a hub, simply declare a subclass of UObjectHub, and register it by calling once the macro UStartHub (class-name). A single instance of this class will then be created upon server start-up. UObject instances can then register to this hub by calling URegister (hub-class-name). Timers can be attached to UObjectHub the same way as to UObject (see Section 4.8). A hub instance can be retrieved by calling getUObjectHub (string class-name). The hub also holds the list of registered UObject in its members attribute.

4.16 Sending urbiscript code

If you need to send urbiscript code to the server, the URBI() macro is available, as well as the send() function. You can either pass it a string, or directly Urbi code inside a double pair of parentheses:

4.17 Using RTP transport in remote mode

By default, Urbi uses TCP connections for all communications between the engine and remote UObjects. Urbi also supports the UDP-based RTP protocol for more eﬃcient transmission of updated variable values. RTP will provide a lower latency at the cost of possible packet loss, especially in bad wireless network conditions.

4.17.1 Enabling RTP

To enable RTP connections, both the engine and the remote-mode urbi-launch containing your remote UObject must load the RTP UObject. This can be achieved by passing urbi/rtp as an extra argument to both urbi-launch command lines (one for the engine, the other for your remote UObject).

Once done, all binary data transfer (like sound and image) in both directions will by default use a RTP connection.

4.17.2 Per-UVar control of RTP mode

You can control whether a speciﬁc UVar uses RTP mode by calling its useRTP(bool) function. Each binary-type UVar will have its own RTP connection, and all non-binary UVar will share one.

From urbiscript, you can also write to the rtp slot of each UVar. Existing notiﬁes will be modiﬁed to use rtp if you set it to true.

4.18 Extending the cast system

4.18.1 Principle

The same cast system is used both for bound function’s arguments and return values, and for reading/writing UVar.

Should you want to add new type MyType to the system you must deﬁne two functions:

4.18.2 Casting simple structures

The system provides facilities to serialize simple structures by value between C++ and urbiscript. This system uses two declarations of each structure, one in C++ and the other in Urbi, and maps between the two.

Here is a complete commented example to map a simple Point structure between urbiscript and C++.

Once done, you can call bound functions taking a C++ Point by passing them an urbiscript Point and exchange Point between both worlds through UVar read/write:

Chapter 5
The UObject Java API

The UObject Java API can be used to add new remote objects written in Java to the urbiscript language, and to interact from Java with the objects that are already deﬁned. We cover the use cases of interfacing higher-level components (voice recognition, object detection…) with Urbi using Java.

The Java API deﬁnes the UObject class. To each instance of a Java class deriving from UObject will correspond an urbiscript object sharing some of its methods and attributes. The API provides methods to declare which elements of your object are to be shared. To share a variable with Urbi, you have to give it the type UVar. This type is a container that provides conversion and setter member functions for all types known to Urbi: double, java.lang.String, the binary-holding structures urbi.UBinary, urbi.USound and urbi.UImage, list types urbi.UList and dictionaries urbi.Dictionary. This type can also read from and write to the urbi.UValue class. The API provides methods to set up callbacks functions that will be notiﬁed when a variable is modiﬁed or read from urbiscript code. Instance methods of any prototype can be made accessible from urbiscript, providing all the parameter types and the return type can be converted to/from urbi.UValue.

5.1 Compiling and running UObjects

UObjects can be compiled easily directly with the javac compiler, then you can create JAR archives using the jar tool.

In the following sections, we will try to create an uobject jar archive named ‘machine.jar’ from a set of two ﬁles (‘Machine.java’, ‘UMachine.java’.

In what follows, urbi-root denotes the top-level directory of your Urbi SDK package, see Section 16.2.

5.1.1 Compiling and running by hand

Then to run your uobject, you need to call java. We provide a main class called urbi.UMain in the liburbijava.jar archive. You can use this class to start your UObjects. This class takes the names of your uobjects jar ﬁles as argument. You also need to specify the lib folder of the urbi SDK into java.library.path:

5.1.2 The umake-java and urbi-launch-java tools

umake-java can be used to compile Java UObjects. It will produce a JAR archive that you can use with urbi-launch-java.

or ﬁnally, if you give no argument at all, the sources in the current directory:

5.2 Creating a class, binding variables and functions

Let’s illustrate those concepts by deﬁning a simple object: adder. This object has one variable v, and a method add that returns the sum of this variable and its argument.

5.3 Creating new instances

When you start an Urbi server, an object of each class registered with UStart is created with the same name as the class. New instances can be created from Urbi using the new method. For each instance created in Urbi, a corresponding instance of the Java object is created. You can get the arguments passed to the constructor by deﬁning and binding a method named init with the appropriate number of arguments.

For example let’s add an Urbi constructor to our Adder class. We rewrite it as follow:

Now ’v’ and ’add’ are bound only when instance of the Adder object are constructed. We have added an ’init’ constructor with one parameter that we use to initialize the value of v. You can run this UObject and test it in Urbi to see the diﬀerence with the previous example. Here is what it gives:

5.4 Binding functions

5.4.1 Simple binding

The ﬁrst function takes as parameter the object containing the function (for now it is only possible to bind instance method, we do not handle static methods). The second parameter is the name of the function you want to bind. The third parameter is a list of the names if the types of the arguments. For example for the function add, in the previous Adder example, we could have used:

If in your UObject you have diﬀerent names for each of your methods, then you can use the shorter versions of UBindFunction.

5.5 Notiﬁcation of a variable change or access

You can register a function that will be called each time a variable is modiﬁed by calling UNotifyChange, passing either an UVar or a variable name as ﬁrst argument, and a member function of your UObject as second argument (and optionally a String array containing the name of the types of the parameters). The prototype for UNotifyChange is:

The callback function can take zero or one argument: an UVar pointing to the UVar being modiﬁed. And the callback function must return an int (the value returned is currently ignored in the actual implementation) or nothing at all (void). The notifyChange callback function is always called after the variable value is changed.

Notify functions can be unregistered by calling the unnotify function of the UVar class.

5.6 Timers

5.7 Using Urbi variables

You can read or write any Urbi variable by creating an UVar passing the variable name to the constructor. Change the value by writing any compatible type to the UVar, and access the value by casting the UVar to any compatible type.

Note however that changes on the variable coming from Urbi code or an other module can take time to propagate to the UVar. You can read and write all the Urbi properties of an UVar by reading and writing the appropriate UProp object in the UVar.

5.8 Sending Urbi code

If you need to send Urbi code to the server, the send() function is available. You can pass it a string containing Urbi code:

5.9 Providing a main class or not

We provide a main class, containing a main function, embedded in the liburbijava.jar ﬁle. This main class, called urbi.UMain is responsible for the loading of the liburbijava native library, and also for the registering of your uobjects.

5.10 Import the examples with Eclipse

We provide a sample Eclipse project conﬁguration that you can import in Eclipse and use to create your own UObject Java.

The Java project is loaded. You can see the jar containing the liburbi (liburbijava.jar, storing the UObject Java API) which contains the urbi package, and also see the sources of the example we provide. We put them in the packages examples. You can inspire yourself from these examples to make your own UObjects. Here, we will see how to compile and run them in eclipse

NB: If Eclipse complains about errors in the source code, it can be that your compiler compliance level is two low. You have to set the compiler compliance level to Java 5 at least (Windows/Preferences/Java/Compiler).

5.11 Run the UObject Java examples

We provide a sample uobjectjava.launch ﬁles that you can load in eclipse to run the projects.

Chapter 6
Use Cases

6.1 Writing a Servomotor Device

First our header. Our servo device provides an attribute named val, the standard Urbi name, and two ways to set PID gain: a method, and three variables.

The constructor only registers init, so that our default instance servo does nothing, and can only be used to create new instances.

The init function, called in a new instance each time a new Urbi instance is created, registers the four variables (val, P, I and D), and sets up callback functions.

Then we deﬁne our callback methods. servo::valueChanged will be called each time the val variable is modiﬁed, just after the value is changed: we use this method to send our servo commands. servo::valueAccessed is called just before the value is going to be read. In this function we request the current value from the servo, and set val accordingly.

servo::pidChanged is called each time one of the PID variables is written to. The function servo::setPID can be called directly from Urbi.

The sample code above has one problem: valueAccessed and valueChanged are called each time the value is read or written from Urbi, which can happen quite often. This is a problem if sending the actual command (setPosition in our example) takes time to execute. There are two solutions to this issue.

6.1.1 Caching

One solution is to remember the last time the value was read/written, and not apply the new command before a ﬁxed time. Note that the kernel is doing this automatically for UOwned’d variables that are in a blend mode diﬀerent than normal. So the easiest solution to the above problem is likely to set the variable to the mix blending mode. The unavoidable drawback is that commands are not applied immediately, but only after a small delay.

6.1.2 Using Timers

Instead of updating/fetching the value on demand, you can chose to do it periodically based on a timer. A small diﬀerence between the two API methods comes in handy for this case: the update() virtual method called periodically after being set up by USetUpdate(interval) is called just after one pass of Urbi code execution, whereas the timers set up by USetTimer are called just before one pass of Urbi code execution. So the ideal solution is to read your sensors in the second callback, and write to your actuators in the ﬁrst. Our previous example (omitting PID handling for clarity) can be rewritten. The header becomes:

valueChanged becomes update and valueAccessed becomes getVal. Instead of being called on demand, they are now called periodically. The period of the call cannot be lower than the value returned by Object.getPeriod; so you can set it to 0 to mean “as fast as is useful”.

6.2 Using Hubs to Group Objects

Now, suppose that, for our previous example, we can speed things up by sending all the servomotor commands at the same time, using the following method that takes two arrays of ids and positions.

A hub is the perfect way to handle this task. The UObject header stays the same. We add a hub declaration:

The following line can be added to the servo init method, although it has no use in our speciﬁc example:

Periodically, the update method is called on each servo instance, which adds commands to the hub arrays, then the update method of the hub is called, actually sending the command and resetting the array.

6.2.1 Alternate Implementation

Alternatively, to demonstrate the use of the members hub variable, we can entirely remove the update method in the servo class (and the USetUpdate() call in init), and rewrite the hub update method the following way:

6.3 Writing a Camera Device

A camera device is an UObject whose val ﬁeld is a binary object. The Urbi kernel itself doesn’t make any diﬀerence between all the possible binary formats and data type, but the API provides image-speciﬁc structures for convenience. You must be careful about memory management. The UBinary structure handles its own memory: copies are deep, and the destructor frees the associated buﬀer. The UImage and USound structures do not.

The init function binds the variable, a function called on access, and sets a timer up on update. It also initializes the UBinary structure.

The getVal updates the camera value, only if it hasn’t already been called this frame, which provides a simple caching mechanism to avoid performing the potentially long operation of acquiring an image too often.

Be careful, suppose that we had created the UBinary structure inside the getVal method, our buﬀer would have been freed at the end of the function. To avoid this, set it to 0 after assigning the UBinary to the UVar.

6.3.1 Optimization in Plugin Mode

In plugin mode, it is possible to access the buﬀer used by the kernel by casting the UVar to a UImage. You can modify the content of the kernel buﬀer but no other argument.

6.4 Writing a Speaker or Microphone Device

Sound handling works similarly to image manipulation, the USound structure is provided for this purpose. The recommended way to implement a microphone is to ﬁll the UObject val variable with the sound data corresponding to one kernel period. If you do so, the Urbi code loop tag:micro.val, will produce the expected result.

6.5 Writing a Softdevice: Ball Detection

Algorithms that require intense computation can be written in C++ but still be usable within Urbi: they acquire their data using UVar referencing other modules’ variables, and output their results to other UVar. Let’s consider the case of a ball detector device that takes an image as input, and outputs the coordinates of a ball if one is found.

The init function binds the variables and a callback on update of the image variable passed as a argument.

The newImage function runs the detection algorithm on the image in its argument, and updates the variables.

Part II
urbiscript User Manual

About This Part

Chapter 7
First Steps

This section expects that you already know how to run urbi. If not, please ﬁrst see Chapter 2.

This section introduces the most basic notions to write urbiscript code. Some aspects are presented only minimally. The goal of this section is to bootstrap yourself with the urbiscript language, to be able to study more in-depth examples afterward.

7.1 Comments

Commenting your code is crucial, so let’s start by learning how to do this in urbiscript. Comments are ignored by the interpreter, and can be left as documentation, reminder, …urbiscript supports C and C++ style comments:

Chapter 2 introduced some of the conventions used in this document: frames such as the previous one denote “urbiscript sessions”, i.e., dialogs between Urbi and you. The output is preﬁxed by a number between square brackets: this is the date (in milliseconds since the server was launched) at which that line was sent by the server. This is useful at occasions, since Urbi is meant to run many parallel commands. Since these timestamps are irrelevant in documentation, they will often be ﬁlled with zeroes. More details about the typesetting of this document (and the other kinds of frames) can be found in Chapter 34.

7.2 Literal values

Several special kinds of “values” can be entered directly with a speciﬁc syntax. They are called literals, or sometimes manifest values. We just met a ﬁrst kind of literals: integers. There are several others, such as:

7.3 Function calls

Again, the result of the evaluation are printed out. You can see here that function in urbiscript can be variadic, that is, take diﬀerent number of arguments, such as the max function. Let’s now try the echo function, that prints out its argument.

The server prints out Hello world!, as expected. Note that this output is still prepended with the time stamp. Since echo returns void, no evaluation result is printed.

7.4 Variables

Variables can be introduced with the var keyword, given a name and an initial value. They can be assigned new values with the = operator.

Note that, just as in C++, assignments return the (right-hand side) value, so you can write code like “x = y = 0”. The rule for valid identiﬁers is also the same as in C++: they may contain alphanumeric characters and underscores, but they may not start with a digit.

7.5 Scopes

Scopes are introduced with curly brackets ({}). They can contain any number of statements. Variables declared in a scope only exist within this scope.

Note that the interpreter waits for the whole scope to be input to evaluate it. Also note the mandatory terminating semicolon after the closing curly bracket.

7.6 Method calls

Methods are called on objects with the dot (.) notation as in C++. Method calls can be chained. Methods with no arguments don’t require the parentheses.

In obj.method, we say that obj is the target, and that we are sending him the method message.

7.7 Function deﬁnition

You know how to call routines, let’s learn how to write some. Functions can be declared thanks to the function keyword, followed by the comma separated, parentheses surrounded list of formal arguments, and the body between curly brackets.

Note the strange output after you deﬁned the function. urbiscript seems to be printing the function you just typed in again. This is because a function deﬁnition evaluates to the freshly created function.

Functions are ﬁrst class citizen: they are values, just as 0 or "foobar". The evaluation of a function deﬁnition yields the new function, and as always, the interpreter prints out the evaluation result, thus showing you the function again:

Here you can see that f is actually a simple value. You can just evaluate it to see its value, that is, its body. By adding the parentheses, you can actually call the function. This is a diﬀerence with methods calling, where empty parentheses are optional: method are always evaluated, you cannot retrieve their functional value — of course, you can with a diﬀerent construct, but that’s not the point here.

Since this output is often irrelevant, most of the time it is hidden in this documentation using the |; trick. When a statement is “missing”, an empty statement ({}) is inserted. So code|; is actually equivalent to code | {};, which means “run code, then run {} and return its value”. Since the value of {} is void, which is not displayed, this is a means to discard the result of a computation, and avoid that something is printed. Contrast the two following function deﬁnitions.

The return keyword breaks the control ﬂow of a function (similarly to the way break interrupts a loop) and returns the control ﬂow to the caller. It accepts an optional argument, the value to return to the caller.

In urbiscript, if no return statement is executed, the value of the last expression is returned. Actually, refrained from using return when you don’t need it, it is both less readable (once you get used to this programming style), and less eﬃcient (Listing 18.1.2).

7.8 Conclusion

You’re now up and running with basic urbiscript code, and we can dive in details into advanced urbiscript code.

Chapter 8
Basic Objects, Value Model

In this section, we focus on urbiscript values as objects, and study urbiscript by-reference values model. We won’t study classes and actual objective programming yet, these points will be presented in Chapter 11.

8.1 Objects in urbiscript

An object in urbiscript is a rather simple concept: a list of slots. A slot is a value associated to a name. So an object is a list of slot names, each of which indexes a value — just like a dictionary.

You can get an object’s slot value by using the dot (.) operator on this object, followed by the name of the slot.

It’s as simple as this. The inspect method provides a convenient short-hand to discover an object (Object).

Let’s now try to build such an object. First, we want a fresh object to work on. In urbiscript, Object is the parent type of every object (in fact, since urbiscript is prototype-based, Object is the uppermost prototype of every object, but we’ll talk about prototypes later). An instance of object, is an empty, neutral object, so let’s start by instantiating one with the clone method of Object.

As you can see, we obtain an empty fresh object. Note that it still inherits from Object features that all objects share, such as the localSlotNames method.

Also note how o is printed out: Object_, followed by an hexadecimal number. Since this object is empty, its printing is quite generic: its type (Object), and its unique identiﬁer (every urbiscript object has one). Since these identiﬁers are often irrelevant and might diﬀer between two executions, they are often ﬁlled with zeroes in this document.

We’re now getting back to our empty object. We want to give it two slots, a and b, with values 42 and "foo" respectively. We can do this with the setSlot method, which takes the slot name and its value.

Here we successfully created our ﬁrst slot, a. A good shorthand for setting slot is using the var keyword.

The latter form with var is preferred, but you need to know the name of the slot at the time of writing the code. With the former one, you can compute the slot name at execution time. Likewise, you can read a slot with a run-time determined name with the getSlot method, which takes the slot name as argument. The following listing illustrates the use of getSlot and setSlot to read and write slots whose names are unknown at code-writing time.

Right, now we can create fresh objects, create slots in them and read them afterward, even if their name is dynamically computed, with getSlot and setSlot. Now, you might wonder if there’s a method to update the value of the slot. Guess what, there’s one, and it’s named…updateSlot (originality award). Getting back to our o object, let’s try to update one of its slots.

Likewise, prefer the ’=’ notation whenever possible, but you’ll need updateSlot to update a slot whose name you don’t know at code-writing time.

Note that deﬁning the same slot twice, be it with setSlot or var, is an error. The slot must be deﬁned once with setSlot, and subsequent writes must be done with updateSlot.

Here we are, now you can inspect and modify objects at will. Don’t hesitate to explore urbiscript objects you’ll encounter through this documentation like this. Last point: reading, updating or removing a slot which does not exist is, of course, an error.

8.2 Methods

Methods in urbiscript are simply object slots containing functions. We made a little simpliﬁcation earlier by saying that obj.slot is equivalent to obj.getSlot("slot"): if the fetched value is executable code such as a function, the dot form evaluates it, as illustrated below. Inside a method, this gives access to the target — as in C++. It can be omitted if there is no ambiguity with local variables.

This was designed this way so as one can replace an attribute, such as an integer, with a function that computes the value. This enables to replace an attribute with a method without changing the object interface, since the parentheses are optional.

This implies that getSlot can be a better tool for object inspection to avoid invoking slots, as shown below.

The asList function simply bounces the task to split. Let’s try getSlot’ing another method:

The size method of String is another type of object: a Primitive. These objects are executable, like functions, but they are actually opaque primitives implemented in C++.

8.3 Everything is an object

If you’re wondering what is an object and what is not, the answer is simple: every single bit of value you manipulate in urbiscript is an object, including primitive types, types themselves, functions, …

8.4 The urbiscript values model

We are now going to focus on the urbiscript value model, that is how values are stored and passed around. The whole point is to understand when variables point to the same object. For this, we introduce uid, a method that returns the target’s unique identiﬁer — the same one that was printed when we evaluated Object.clone. Since uids might vary from an execution to another, their values in this documentation are dummy, yet not null to be able to diﬀerentiate them.

Our objects have diﬀerent uids, reﬂecting the fact that they are diﬀerent objects. Note that entering the same integer twice (42 here) yields diﬀerent objects. Let’s introduce new operators before diving in this concept. First the equality operator: ==. This operator is the exact same as C or C++’s one, it simply returns whether its two operands are semantically equal. The second operator is ===, which is the physical equality operator. It returns whether its two operands are the same object, which is equivalent to having the same uid. This can seem a bit confusing; let’s have an example.

Here, the == operator reports that a and b are equal — indeed, they both evaluate to 42. Yet, the === operator shows that they are not the same object: they are two diﬀerent instances of integer objects, both equal 42.

Thanks to this operator, we can point out the fact that slots and local variables in urbiscript have a reference semantic. That is, when you deﬁning a local variable or a slot, you’re not copying any value (as you would be in C or C++), you’re only making it refer to an already existing value (as you would in Ruby or Java).

So here we see that a and c point to the same integer, while b points to a second one. This a non-trivial fact: any modiﬁcation on a will aﬀect c as well, as shown below.

Updating slots or local variables does not update the referenced value. It simply redirects the variable to the new given value.

Understanding the two latter examples is really important, to be aware of what your variable are referring to.

Finally, function and method arguments are also passed by reference: they can be modiﬁed by the function.

Beware however that arguments are passed by reference, and the behavior might not be what you may expected.

8.5 Conclusion

You should now understand the reference semantic of local variables, slots and arguments. It’s very important to keep them in mind, otherwise you will end up modifying variables you didn’t want, or change a copy of reference, failing to update the desired one.

Chapter 9
Flow Control Constructs

In this section, we’ll introduce some ﬂow control structures that will prove handy later. Most of them are inspired by C/C++.

9.1 if

The if construct is the same has C/C++’s one. The if keyword is followed by a condition between parentheses and an expression, and optionally the else keyword and another expression. If the condition evaluates to true, the ﬁrst expression is evaluated. Otherwise, the second expression is evaluated if present.

9.2 while

The while construct is, again, the same as in C/C++. The while keyword is followed by a condition between parentheses and an expression. If the condition evaluation is false, the execution jumps after the while block; otherwise, the expression is evaluated and control jumps before the while block.

9.3 for

The for keyword supports diﬀerent constructs, as in languages such as Java, C#, or even the forthcoming C++ revision.

The second construct allows to iterate over members of a collection, such as a list. The for keyword, followed by var, an identiﬁer, a colon (or in), an expression and a scope, executes the scope for every element in the collection resulting of the evaluation of the expression, with the variable named with the identiﬁer referring to the list members.

9.4 switch

The syntax of the switch construct is similar to C/C++’s one, except it works on any kind of object, not only integral ones. Comparison is done by semantic equality (operator ==). Execution will jump out of the switch-block after a case has been executed (no need to break). Also, contrary to C++, the whole construct has a value: that of the matching case.

9.5 do

The same result can be obtained with a short do scope, that redirect method calls to their target, as in the listing below. This is similar to the Pascal “with” construct. The value of the do-block is the target itself.

Chapter 10
Advanced Functions and Scoping

This section presents advanced uses of functions and scoping, as well as their combo: lexical closures, which prove to be a very powerful tool.

10.1 Scopes as expressions

Contrary to other languages from the C family, scopes are expressions: they can be used where values are expected, just as 1 + 1 or "foo". They evaluate to the value of their last expression, or void if they are empty. The following listing illustrates the use of scopes as expressions. The last semicolon inside a scope is optional.

10.2 Advanced scoping

Scopes can be nested. Variables can be redeﬁned in nested scopes. In this case, the inner variables hide the outer ones, as illustrated below.

10.3 Local functions

Functions can be deﬁned anywhere local variables can — that is, about anywhere. These functions’ visibility are limited to the scope they’re deﬁned in, like variables. This enables for instance to write local helper functions like max2 in the example below.

10.4 Lexical closures

A closure is the capture by a function of a variable external to this function. urbiscript supports lexical closure: functions can refer to outer local variables, as long as they are visible (in scope) from where the function is deﬁned.

Closure can be really powerful tools in some situations; they are even more useful when combined with functional programming, as described in Chapter 12.

Chapter 11
Objective Programming, urbiscript Object Model

This section presents object programming in urbiscript: the prototype-based object model of urbiscript, and how to deﬁne and use classes.

11.1 Prototype-Based Programming in urbiscript

You’re probably already familiar with class-based object programming, since this is the C++, Java, C# model. Classes and objects are very diﬀerent entities. Classes and types are static entities that do not exist at run-time, while objects are dynamic entities that do not exist at compile time.

Prototype-based object programming is diﬀerent: the diﬀerence between classes and objects, between types and values, is blurred. Instead, you have an object, that is already an instance, and that you might clone to obtain a new one that you can modify afterward. Prototype-based programming was introduced by the Self language, and is used in several popular script languages such as Io or JavaScript.

Class-based programming can be considered with an industrial metaphor: classes are molds, from which objects are generated. Prototype-based programming is more biological: a prototype object is cloned into another object which can be modiﬁed during its lifetime.

Consider pairs for instance (see Pair). Pairs hold two values, first and second, like an std::pair in C++. Since urbiscript is prototype-based, there is no pair class. Instead, Pair is really a pair (object).

We can see here that Pair is a pair whose two values are equal to nil — which is a reasonable default value. To get a pair of our own, we simply clone Pair. We can then use it as a regular pair.

Since Pair is a regular pair object, you can modify and use it at will. Yet this is not a good idea, since you will alter your base prototype, which alters any derivative, future and even past.

11.2 Prototypes and Slot Lookup

In prototype-based language, is-a relations (being an instance of some type) and inheritance relations (extending another type) are simpliﬁed in a single relation: prototyping. You can inspect an object prototypes with the protos method.

As expected, our fresh pair has one prototype, (nil, nil), which is how Pair displays itself. We can check this as presented below.

Prototypes are the base of the slot lookup mechanism. Slot lookup is the action of ﬁnding an object slot when the dot notation is used. So far, when we typed obj.slot, slot was always a slot of obj. Yet, this call can be valid even if obj has no slot slot, because slots are also looked up in prototypes. For instance, p, our clone of Pair, has no first or second slots. Yet, p.first and p.second work, because these slots are present in Pair, which is p’s prototype. This is illustrated below.

As shown here, the clone method simply creates an empty object, with its target as prototype. The new object has the exact same behavior as the cloned on thanks to slot lookup.

Let’s experience slot lookup by ourselves. In urbiscript, you can add and remove prototypes from an object thanks to addProto and removeProto.

The slot lookup algorithm in urbiscript in a depth-ﬁrst traversal of the object prototypes tree. Formally, when the s slot is requested from x:

Thus, slots from the last prototype added take precedence over other prototype’s slots.

You can check where in the prototype hierarchy a slot is found with the locateSlot method. This is a very handful tool when inspecting an object.

The prototype model is rather simple: creating a fresh object simply consists in cloning a model object, a prototype, that was provided to you. Moreover, you can add behavior to an object at any time with a simple addProto: you can make any object a fully functional Pair with a simple myObj.addProto(Pair).

11.3 Copy on Write

One point might be bothering you though: what if you want to update a slot value in a clone of your prototype?

Say we implement a simple prototype, with an x slot equal to 0, and clone it twice. We have three objects with an x slot, yet only one actual 0 integer. Will modifying x in one of the clone change the prototype’s x, thus altering the prototype and the other clone as well?

This work thanks to copy-on-write: slots are ﬁrst duplicated to the local object when they’re updated, as we can check below.

This is why, when we cloned Pair earlier, and modiﬁed the “ﬁrst” slot of our fresh Pair, we didn’t alter Pair one all its other clones.

11.4 Deﬁning Pseudo-Classes

Now that we know the internals of urbiscript’s object model, we can start deﬁning our own classes.

But wait, we just said there are no classes in prototype-based object-oriented languages! That is true: there are no classes in the sense of C++, i.e., compile-time entities that are not objects. Instead, prototype-based languages rely on the existence of a canonical object (the prototype) from which (pseudo) instances are derived. Yet, since the syntactic inspiration for urbiscript comes from languages such as Java, C++ and so forth, it is nevertheless the class keyword that is used to deﬁne the pseudo-classes, i.e., prototypes.

As an example, we deﬁne our own Pair class. We just have to create a pair, with its first and second slots. For this we use the do scope described in Section 9.5. The listing below deﬁnes a new Pair class. The asString function is simply used to customize pairs printing — don’t give it too much attention for now.

That’s it, we deﬁned a pair that can be cloned at will! urbiscript provides a shorthand to deﬁne classes as we did above: the class keyword.

The class keyword simply creates MyPair with Object.clone, and provides you with a do (MyPair) scope. It actually also pre-deﬁnes a few slots, but this is not the point here.

It is also possible to specify a proto for the newly created “class”, using the same syntax as Java and C++:

11.5 Constructors

As we’ve seen, we can use the clone method on any object to obtain an identical object. Yet, some classes provide more elaborate constructors, accessible by calling new instead of clone, potentially passing arguments.

While clone guarantees you obtain an empty fresh object inheriting from the prototype, new behavior is left to the discretion of the cloned prototype — although its behavior is the same as clone by default.

To deﬁne such constructors, prototypes only need to provide an init method, that will be called with the arguments given to new. For instance, we can improve our previous Pair class with a constructor.

11.6 Operators

In urbiscript, operators such as +, && and others, are regular functions that beneﬁt from a bit of syntactic sugar. To be more precise, a+b is exactly the same as a.’+’(b). The rules to resolve slot names apply too, i.e., the ’+’ slot is looked for in a, then in its prototypes.

11.7 Properties

Slots should be understood as names to values. Several names may point to the same value (a phenomenon called aliasing). Enriching values is easy: provide them with new slots. Yet it is sometimes needed to deﬁne the behavior of the slot rather than the property of the value. This is the purpose of properties in urbiscript.

11.7.1 Features of Values

In following example, we attach some random property foo to the value pointed to by the slot x.

If x is bound to a new object (e.g., 456), then the feature foo is no longer present, since it’s a feature of the value (i.e., 123), and not one of the slot (i.e., x).

Of course, y, which is still linked to the original value (123), answers to queries to foo.

11.7.2 Features of Slots

If, on the contrary you want to attach a feature to the slot-as-a-name, rather than to the value it contains, use the properties. The syntax is slotName->propertyName.

Copying the value contained by a slot does not propagate the properties of the slot:

And if you assign a new value to a slot, the properties of the slot are preserved:

Chapter 12
Functional Programming

urbiscript support functional programming through ﬁrst class functions and lambda expressions.

12.1 First class functions

urbiscript has ﬁrst class functions, i.e., functions are regular values, just like integers or strings. They can be stored in variables, passed as arguments to other functions, and so forth. For instance, you don’t need to write function object.f(){/* ... */} to insert a function in an object, you can simply use setSlot.

This enables to write powerful pieces of code, like functions that take function as argument. For instance, consider the all function: given a list and a function, it applies the function to each element of the list, and returns whether all calls returned true. This enables to check very simply if all elements in a list verify a predicate.

It turns out that all already exists: instead of all(list, predicate), use list.all(predicate), see RangeIterable.all.

12.2 Lambda functions

Another nice feature is the ability to write lambda functions, which are anonymous functions. You can create a functional value as an expression, without naming it, with the syntax shown below.

In fact, the function construct we saw earlier is only a shorthand for a variable assignment.

12.3 Lazy arguments

Most popular programming languages use strict arguments evaluation: arguments are evaluated before functions are called. Other languages use lazy evaluation: argument are evaluated by the function only when needed. In urbiscript, evaluation is strict by default, but you can ask a function not to evaluate its arguments, and do it by hand. This works by not specifying formal arguments. The function is provided with a call object that enables you to evaluate arguments.

A good example are logic operators. Although C++ is a strict language, it uses a few logic operators. For instance, the logical and (&&) does not evaluate its right operand if the left operand is false (the result will be false anyway).

urbiscript logic operator mimic this behavior. The listing below shows how one can implement such a behavior.

Chapter 13
Parallelism, Concurrent Flow Control

Parallelism is a major feature of urbiscript. So far, all we’ve seen already existed in other languages — although we tried to pick, mix and adapt features and paradigms to create a nice scripting language. Parallelism is one of the corner stones of its paradigm, and what makes it so well suited to high-level scripting of interactive agents, in ﬁelds such as robotics or AI.

13.1 Parallelism operators

For now, we’ve separated our diﬀerent commands with a semicolon (;). There are actually four statement separators in urbiscript:

The example below demonstrates the use of & to launch two functions in parallel.

That’s about all there is to say about these operators. Although they’re rather simple, they are really powerful and enables you to include parallelism anywhere at no syntactical cost.

13.2 Detach

The Control.detach function backgrounds the execution of its argument. Its behavior is the same as the comma (,) operator, except that the execution is completely detached, and not waited for at the end of the scope.

13.3 Tags for parallel control ﬂows

A Tag is a multipurpose code execution control and instrumentation feature. Any chunk of code can be tagged, by preceding it with a tag and a colon (:). Tag can be created with Tag.new(name). Naming tags is optional, yet it’s a good idea since it will be used for many features. The example below illustrates how to tag chunks of code.

You can use tags that were not declared previously, they will be created implicitly (see below). However, this is not recommended since tags will be created in a global scope, the Tag object. This feature can be used when inputting test code in the top level to avoid bothering to declare each tag, yet it is considered poor practice in regular code.

So you can tag code, yet what’s the use? One of the primary purpose of tags is to be able to control the execution of code running in parallel. Tags have a few control methods (see Tag):

13.4 Advanced example with parallelism and tags

The listing below presents how to implement a timeOut function, that takes code to execute and a timeout as arguments. It executes the code, and returns its value. However, if the code execution takes longer than the given timeout, it aborts it, prints "Timeout!" and returns void. In this example, we use:

Chapter 14
Event-based Programming

When dealing with highly interactive agent programming, sequential programming is inconvenient. We want to react to external, random events, not execute code linearly with a predeﬁned ﬂow. urbiscript has a strong support for event-based programming.

14.1 Watchdog constructs

The ﬁrst construct we will study uses the at keyword. Given a condition and a statement, at will evaluate the statement each time the condition becomes true. That is, when a rising edge occurs on the condition.

An onleave block can be appended to execute an expression when the expression becomes false — that is, on falling edges.

The whenever construct is similar to at, except the expression evaluation is systematically restarted when it ﬁnishes as long as the condition stands true.

Just like at has onleave, whenever has else: the given expression is evaluated as long as the condition is false.

14.2 Events

In addition to monitoring an expression with a watchdog, urbiscript enables you to deﬁne events that can be caught with the at and whenever constructs we saw earlier. You can create events by instantiating the Event prototype. They can then be emitted with the ! keyword.

14.2.1 Emitting Events

Both at and whenever have the same behavior on punctual events. However, if you emit an event for a given duration, whenever will keep triggering for this duration, contrary to at.

14.2.2 Emitting events with a payload

Events behave very much like “channels”: listeners use at or whenever, and producers use !. Fortunately, the messages can include a payload, i.e., something sent in the “message”. The Event then behaves very much like an identiﬁer of the message type. To send/catch the payload, just pass arguments to ! and ?:

Like functions, events have an arity, i.e., they depend on the number of arguments: at (event?(arg)) will only match emissions whose payload contain exactly one argument, i.e., event!(arg).

Event handlers that do not specify their arity (i.e., without parentheses) match event emissions of any arity.

Actually, the feature is much more powerful than this: full pattern matching applies, as with the switch/case construct.

Chapter 15
Urbi for ROS Users

This chapter extends the ROS oﬃcial tutorials ¹ . Be sure to complete this tutorial before reading this document.

15.1 Communication on topics

First we will take back examples about topics; make sure that talker and listener in the ‘beginner_tutorial’ package are compiled. You can recompile it with the following command:

15.1.1 Starting a process from Urbi

To communicate with ROS components, you need to launch them. You can do it by hand, or ask Urbi to do it for you. To launch new processes through Urbi, we will use the class Process.

Let’s say we want to start roscore, and the talker of the beginner tutorial. Open an Urbi shell by typing the command ‘rlwrap urbi -i’. Here rlwrap makes ‘urbi -i’ acts like a shell prompt, with features like line editing, history, …

At this point, the processes are launched. The ﬁrst argument of Process.new is the name of the command to launch, the second is a list of arguments.

Then you can check the status of the processes, get their stdout/stderr buﬀers, kill them in urbiscript (see Process).

15.1.2 Listening to Topics

First you need to make sure that roscore is running, and the ROS module is loaded correctly:

This returns a Dictionary with the name of the node as key, and a dictionary with topics subscribed, topics advertised, topics advertised as value.

Here we see that this node advertises ‘/rosout’ and ‘/chatter’. Let’s subscribe to ‘/chatter’:

In this code, e is a Dictionary that follows the structure of the ROS message. Here is an example of what this code produces:

To stop temporarily the Global.echo, we take advantages of tags (Section 13.3), by doing chatTag.freeze. Same thing goes with unfreeze. Of course you could also call chatter.unsubscribe, which unsubscribes you completely from this channel.

15.1.3 Advertising on Topics

15.1.3.1 Simple Talker

We have just sent our ﬁrst message to ROS, here if you launch the chatter, you will be able to get the message we have just sent.

15.1.3.2 Turtle Simulation

Now we are going to move the turtle with Urbi. First let’s launch the turtle node:

Ros.topics shows that this turtle subscribes to a topic ‘/turtle1/command_velocity’. Let’s advertise on it:

Now we want to have it moving in circle with a small sinusoid wave. This goes in two step. First, we set up the infrastructure so that changes in Urbi are seamlessly published in ROS.

In the future Urbi will provide helping functions to spare the user from the need to perform this “binding”. But once this binding done, all the features of urbiscript can be used transparently.

Alternatively, Tags could have been used to get more control over the trajectory:

We won’t cover this code in details, but the general principle is that angular is updated every 20ms with the values of a sinusoid wave trajectory with 0.3 as average value, 2 seconds for the period and 2 for the amplitude. See TrajectoryGenerator for more information. After 20 seconds the tag is frozen, pausing the trajectory generation and the at.

15.2 Using Services

Let’s take back the turtle simulation example (Section 15.1.3.2). Then we can list the available services, and ﬁlter out loggers:

The closure construct allows us to keep access to the local variables, here logger.

The new function takes the service name as ﬁrst argument, and as second argument whether the connection should be kept alive.

Since the creation of this object checks the service name, you should wait until initialized is true to use this service. You can also see the structure of the request with spawn.reqStruct, and the structure of the response with spawn.resStruct.

15.3 Image Publisher from ROS to Urbi

This section will use topics manipulation with advertising and subscription. Be sure to understand these topics before doing this tutorial.

First, we will make a ROS Publisher and subscribe to it with Urbi. Make sure that Publisher ‘learning_image_transport’ package is compiled:

We will also run urbi with a network connection opened (e.g., on port 54000) to allow urbi-image (Section 21.4) to connect to it.

Run the Publisher The Publisher is a process that will send a image and wait for a Subscriber to get it.

Using a camera to display By default, urbi-image displays the images that are available via the camera device (see Section 21.4). To simplify the setup, let’s deﬁne a pseudo camera which will store the data received:

Subscribe to the topic Now, our Publisher is running and we have a camera waiting for data. All we need to do is connecting to the Publisher with a topic, the Subscriber.

Have a look at the diﬀerent topics created by the Publisher, for instance by running rxgraph, which generates the graph in paragraph 15.1. As you can see, seven topics are available for the camera. We will use the ‘/camera/image/compressed’ topic for this example. For further information about the image format in ROS see http://www.ros.org/doc/api/sensor_msgs/html/msg/CompressedImage.html.

15.4 Image Subscriber from Urbi to ROS

Now, we want to send images to ROS using a Urbi Publisher. Make sure roscore is running and ‘learning_image_transport’ package is compiled.

Run the Subscriber The basic Subscriber in the ‘learning_image_transport’ package is expecting a ‘/camera/image’ topic. To avoid modifying the Subscriber code in ROS, we will simply ask to the Subscriber topic to accept ‘/camera/image/compressed’ topics.

Publishing images with Urbi The ‘sensor_msgs/CompressedImage’ message format provides a structure that requires a few changes.

This message contains more ﬁelds but you need only these two to send an image.

15.5 Remote communication

We have worked with a roscore running on the machine as the ROS processes but the purpose of using ROS with Urbi is to communicate with a remote machine. All you need is to setup your network conﬁguration to avoid unexpected behaviors (see NetworkSetup² ).

Make sure the ROS environment variables are well set, especially ROS_URI, ROS_HOSTNAME, ROS_IP.

Part III
Guidelines and Cook Books

About This Part

Chapter 16
Installation

16.1 Download

16.2 Install & Check

The package is relocatable, i.e., it does not need to be put at a speciﬁc location, nor does it need special environment variables to be set. It is not necessary to be a super-user to install it. The root of the package, denoted by urbi-root hereafter, is the absolute name of the directory which contains the package.

After the install, the quickest way to test your installation is to run the various programs.

16.2.1 GNU/Linux and Mac OS X

Decompress the package where you want to install it. If urbi-sdk-2.x denotes the version of Urbi SDK you downloaded (say, urbi-sdk-2.x is ‘urbi-sdk-2.3-linux-x86-gcc4’), run something like:

This directory, urbi-root, should contain ‘bin’, ‘FAQ.txt’ and so forth. Do not move things around inside this directory. In order to have an easy access to the Urbi programs, set up your PATH:

16.2.2 Windows

Execute the script ‘urbi.bat’, located at the root of the uncompressed package. It should open a terminal with an interactive Urbi session.

Chapter 17
Frequently Asked Questions

17.1 Build Issues

17.1.1 Complaints about ‘+=’

Although we tried to avoid it, there might still be shell scripts where we use ‘+=’, which Ash (aka, dash and sash) does not support. Please, use bash or zsh instead of Ash as /bin/sh.

17.1.2 error: ‘<anonymous>’ is used uninitialized in this function

then you found a problem that we don’t know how to resolved currently. Downgrade from GCC-4.4 to GCC-4.3.

17.1.3 AM_LANGINFO_CODESET

it probably means your Automake installation is incomplete. See the Automake item in Section 20.1.

17.1.4 conﬁgure: error: The Java VM java failed

You might be trying to compile Urbi SDK from a directory with non-ASCII characters in its full name (for instance ‘/home/jessy/Téléchargements/Sources’). In that case the JVM fails to decode properly the path, and configure fails with the above message.

Move you sources elsewhere, with only plain ASCII characters, such as ‘/home/jessy/Sources’.

17.1.5 ‘make check’ fails

Be sure to read Section 20.9. In particular, run ‘make check’ several times (see Section 20.9 to know why). If the failures remain, please submit the ‘test-suite.log’ ﬁle(s) (see Section 17.5.3).

17.2 Troubleshooting

17.2.1 error while loading shared libraries: libport.so

then check that ‘/proc’ is properly mounted. To make Urbi SDK relocatable, executables and libraries use a relative path to their peers. To resolve these paths into absolute paths, the loader needs to know where the program is located, a feature provided by ‘/proc’. If for instance you run Urbi SDK in a chrooted environment, then it is possible that you forgot to mount ‘/proc’. The traditional ps utility also needs ‘/proc’ to be mounted, so running it would also help checking if the setup is complete.

17.2.2 Error 1723: “A DLL required for this install to complete could not be run.”

This error is raised when you try to install a program like vcredist-x86.exe. This program use the “Windows Installer” which is probably outdated on your system.

To ﬁx this problem, update the “Windows Installer” and re-start the installation of vcredist which should no longer fail.

17.2.3 When executing a program, the message “The system cannot execute the speciﬁed program.” is raised.

This library is necessary to start running any application. Run ‘vcredist-x86.exe’ to install the missing libraries.

If you have used the Urbi SDK installer, it is ‘vcredist-x86.exe’ in your install directory. Otherwise download it from the Microsoft web site. Be sure to get the one corresponding to the right Visual C++ version.

17.2.4 When executing a program, the message “This application has failed to start” is raised.

17.2.5 The server dies with “stack exhaustion”

Your program might be deeply recursive, or use large temporary objects. Use ‘--stack-size’ to augment the stack size, see Section 21.3.

Note that one stack is allocated per “light thread”. This can explain why programs that heavily rely on concurrency might succeed where sequential programs can fail. For instance the following program is very likely to quickly exhaust the (single) stack.

But if you use & instead of |, then each recursive call to consume will be spawn with a fresh stack, and therefore none will run out of stack space:

However your machine will run out of resources: this heavily concurrent program aims at creating no less than 2⁵¹³ threads, about 2.68 × 10¹⁵⁶ (a 156-digit long number, by far larger than the number of atoms in the observable universe, estimated to 10⁸⁰).

17.2.6 ’myuobject: ﬁle not found’. What can I do?

If urbi-launch (or urbi) fails to load an UObject (a shared library or DLL) although the ﬁle exists, then the most probable cause is an undeﬁned symbol in your shared library.

17.2.6.1Getting a better diagnostic

17.2.6.2GNU/Linux

It is also useful to use ldd to check that the dependencies of your object are correct. See the documentation of ldd on your machine (‘man ldd’). The following run is successful: every request (left-hand side of =>) is satisﬁed (by the ﬁle shown on the right-hand side).

Notice the ‘not found’ message. The shared object could not be loaded because it is not found in the runtime path, which is the list of directories where the system looks for shared objects to be loaded when running a program.