There is a number of environment variables that alter the behavior of the Urbi tools.
Some variables define search-paths, i.e., colon-separated lists of directories in which library files (urbiscript programs, UObjects and so forth) are looked for.
The tools have predefined values for these variables which are tailored for your installation — so that Urbi tools can be run without any special adjustment. In order to provide the user with a means to override or extend these built-in values, the path variables support a special syntax: a lone colon specifies where the standard search path must be inserted. See the following examples about URBI_PATH.
# Completely override the system path. First look for files in
# /home/jessie/urbi, then in /usr/local/urbi.
export URBI_PATH=/home/jessie/urbi:/usr/local/urbi
# Prepend the previous path to the default path. This is dangerous as
# it may result in some standard files being hidden.
export URBI_PATH=/home/jessie/urbi:/usr/local/urbi:
# First look in Jessie’s directory, then the default location, and
# finally in /usr/local/urbi.
export URBI_PATH=/home/jessie/urbi::/usr/local/urbi
# Extend the default path, i.e., files that are not found in the
# default path will be looked for in Jessie’s place, and then in
# /usr/local/urbi
export URBI_PATH=:/home/jessie/urbi:/usr/local/urbi
On Windows too directories are separated by colons, but backslashes are used instead of forward-slashes. For instance
The following variables control the way the log messages are displayed. They are meant for developers.
If set, force the use of colors in the logs, even if the output device does not seem to support them. See also GD_NO_COLOR.
If set, a comma-separated list of category patterns with optional modifiers ‘+’ or ‘-’; for instance, ‘-Urbi.*,Urbi.UObject’. See Logger.set for a more precise description of syntax, and Section 21.36.2 for a description of the categories used by Urbi SDK.
If set, a comma-separated list of categories or globs (e.g., ‘UValue’, ‘Urbi.*’) to display. All the others will be discarded. See also GD_DISABLE_CATEGORY.
If set, a comma-separated list of categories or globs (e.g., ‘UValue’, ‘Urbi.*’) not to display. See also GD_ENABLE_CATEGORY.
Set the verbosity level of traces. This environment variable is meant for the developers of Urbi SDK, yet it is very useful when tracking problems such as a UObject that fails to load properly. Valid values are, in increasing verbosity order:
If set, display the location (file, line, function name) from which the log message was issued.
If set, forbid the use of colors in the logs, even if the output device seems to support them, or if GD_COLOR is set.
If set, display the PID (Process Identity).
If set, display the thread identity.
If set, display timestamps.
If set, display timestamps in microseconds.
The following variables control more high-level features, typically to override the default behavior.
The search-path for urbiscript source files (i.e., ‘*.u’ files).
Urbi SDK is relocatable: its components know the relative location of each other. Yet they need to “guess” the urbi-root, i.e., the path to the directory that contains all the files. This variable permits to override that guess. Do not use it unless you know exactly what you are doing.
If set in the environment of a remote urbi-launch, disable binary protocol and force using urbiscript messages.
The search-path for UObjects files. This is used by urbi-launch, by System.loadModule and System.loadLibrary.
There are also very special environment variables, meant to be used only by Urbi developers, see Section 18.2.
This is the obsolete name for ‘global.u’.
If found in the URBI_PATH (see Section 19.1), this file is loaded by Urbi server upon start-up. It is the appropriate place to install features you mean to provide to all the users of the server. It is will be loaded via a special system connection, with its own private lobby. Therefore, purely local definitions will not be reachable from users; global modifications should be made in globally visible objects, say Global.
If found in the URBI_PATH (see Section 19.1), this file is loaded by every connection established with an Urbi server. This is the appropriate place for enhancements local to a lobby.
This is the obsolete name for ‘global.u’.
The urbi program launches an Urbi server, for either batch, interactive, or network-based executions. It is subsumed by, but simpler to use than, urbi-launch (Section 19.5).
The ‘--fast’ flag makes the kernel run the program in “simulated time”, as fast as possible. A System.sleep in fast mode will not actually wait (from the wall-clock point of view), but the kernel will internally increase its simulated time.
For instance, the following session behaves equally in fast and non-fast mode:
{ sleep(2s); echo("after") } & { sleep(1s); echo("before") };
[00000463] *** before
[00001463] *** after
However, in non fast mode the execution will take two seconds (wall clock time), while it be instantaneous in fast mode. This option was designed for testing purpose; it does not preserve the program semantics.
This option should not be needed unless you have “stack exhausted” messages from urbi in which case you should try ‘--stack-size=512’ or more.
Alternatively you can define the environment variable URBI_STACK_SIZE. The option ‘--stack-size’ has precedence over the URBI_STACK_SIZE.
Defaults to 0.0.0.0.
Enabled if no input was provided (i.e., none of ‘-e’/‘--expression’, ‘-f’/‘--file’, ‘-P’/‘--port’ was given).
The options ‘-e’, ‘-f’ accumulate, and are run in the same Lobby as ‘-i’ if used. In other words, the following session is valid:
# Create a file "two.u".
$ echo "var two = 2;" >two.u
$ urbi -q -e ’var one = 1;’ -f two.u -i
[00000000] 1
[00000000] 2
one + two;
[00000000] 3
To exit urbi, use the command System.shutdown.
If you are in interactive mode, you can also use the shortcut sequence C-d in the server lobby. The command Lobby.quit does not shutdown the server, it only closes the current lobby which closes the connection while in remote mode (using telnet for example), but only closes the interactive mode if performed on the server lobby.
On Unix systems, urbi handles the SIGINT signal (action performed when C-c is pressed). If you are in interactive mode, a first C-c kills the foreground job (or does nothing if no job is running on foreground).
For example consider the following piece of code:
If you try to execute this code, you will notice that you can no longer execute commands, since the every job is foreground (because of the semicolon). Now if you press C-c, the every job is killed, all the pending commands you may have typed are cleared from the execution queue, and you get back with a working interactive mode.
every (1s) echo("Hello world!");
[00010181] *** Hello world!
[00011181] *** Hello world!
// This command is entered while the foreground job blocks the evaluation.
// It waits to be executed.
echo("done");
[00012181] *** Hello world!
[00013181] *** Hello world!
// Pressing Control-C here:
[00014100:error] !!! received interruption, killing foreground job.
// Note that the "echo" is not run, the command queue is flushed.
// New commands are honored.
echo("interrupted");
[00019709] *** interrupted
A second C-c (or SIGINT) within the 1.5s after the first one tries to execute System.shutdown. This can take a while, in particular if you have remote UObjects, since a clean shutdown will first take care of disconnecting them cleanly.
// Two Control-C in a row.
[00493865:error] !!! received interruption, killing foreground job.
[00494672:error] !!! received interruption, shutting down.
Pressing C-c a third time triggers the default behavior: killing the program in emergency, by-passing all the cleanups.
In non-interactive mode (after a Lobby.quit on the server lobby for example), the first C-c executes System.shutdown, and the second one triggers the default behavior.
Connect to an Urbi server, and fetch images from it, for instance from its camera.
The urbi-launch program launches an Urbi system. It is more general than urbi (Section 19.3): everything urbi can do, urbi-launch can do it too.
urbi-launch launches UObjects, either in plugged-in mode, or in remote mode. Since UObjects can also accept options, the command line features two parts, separated by ‘--’:
The modules are looked for in the URBI_UOBJECT_PATH. The module extension (‘.so’, or ‘.dll’) does not need to be specified.
Networking urbi-launch supports the same networking options (‘--host’, ‘--port’, ‘--port-file’) as urbi, see Section 19.3.
To launch a fresh server in an interactive session with the UMachine UObject compiled as the file ‘test/machine.so’ (or ‘test/machine.dll’ plugged in, run:
To start an Urbi server accepting connections on the local port 54000 from any remote host, with UMachine plugged in, run:
Since urbi-launch in server mode is basically the same as running the urbi program, both programs are quit the same way (see Section 19.3.2).
Being a program that runs programs urbi-launch is also providing access to the options supported by the UObject middleware: pass them after ‘--’ in plugin mode. For instance:
The options supporting by the UObject middleware are described below.
Networking Beside the usual options (‘--host’, ‘--port’, ‘--port-file’, see Section 19.3), the following options are supported.
Java UObjects can only be run remotely, they cannot be “plugged”. So, while urbi-launch-java is really alike urbi-launch, it is not the same either. See also Section 26.1.2 for a more tutorial-like introduction to urbi-launch-java.
urbi-launch-java launches Java UObjects, either in plugged-in mode, or in remote mode. Since UObjects can also accept options, the command line features two parts, separated by ‘--’:
The modules are looked for in the URBI_UOBJECT_PATH. The module extension (‘.so’, or ‘.dll’) does not need to be specified.
Networking urbi-launch-java supports the same networking options (‘--host’, ‘--port’, ‘--port-file’) as urbi, see Section 19.3.
Send “ping”s to an Urbi server, and report how long it took for “pong”s to come back.
Connect to an Urbi server, and send commands or file contents to it. Stay connected, until server disconnection, or user interruption (such as C-c under a Unix terminal).
Without this option, urbi-send prompts the user to hit C-c to end the connection.
Connect to an Urbi server, and record sounds from it, and play them on ‘/dev/dsp’. This is only supported on GNU/Linux. If ‘[’o]output is specified, the recording is saved instead of being played.
The umake programs builds loadable modules, UObjects, to be later run using urbi-launch (Section 19.5). Using it is not mandatory: users familiar with their compilation tools will probably prefer using them directly. Yet umake makes things more uniform and simpler, at the cost of less control.
Usage:
Compile the file. The files can be of different kinds:
There are several environment variables that umake reads:
Options passed to the preprocessor.
Options passed to the C++ compiler.
Options passed to the linker.
The arguments of umake may also include assignments, i.e., arguments of the type ‘var=val ’. The behavior depends on var, the name of the variable:
Appended to the options passed to the preprocessor.
Appended to the options passed to the C++ compiler.
Appended to the options passed to the linker.
Appended to the VPATH, i.e., the list of directories in which the sources are looked for.
Otherwise, the argument is passed as is to make.
As a convenience for common umake usages, some wrappers are provided: