IndexNextUpPreviousUrbi SDK 2.7.5

Chapter 29
Gostai Open Jazz

PIC

 29.1 Getting started
  29.1.1 Documentation and Support
  29.1.2 Requirements
  29.1.3 Embedded Software
  29.1.4 Connecting Jazz to your Local Area Network
  29.1.5 Connecting to Jazz from your Computer
  29.1.6 Jazz internal website
  29.1.7 Uploading and loading your code on Jazz
  29.1.8 Updating Jazz Software
  29.1.9 Restarting Jazz Software
  29.1.10 Changing Software Profile
  29.1.11 Using the Examples
 29.2 urbiscript API
  29.2.1 Eye leds
  29.2.2 Docking
  29.2.3 Head Motors
  29.2.4 Microphone
  29.2.5 Network
  29.2.6 Playing Sound
  29.2.7 Text to Speech
  29.2.8 Video Camera
  29.2.9 Movement
  29.2.10 Screen Display
  29.2.11 Sonars
  29.2.12 IRs
  29.2.13 Laser
 29.3 urbiscript Library
  29.3.1 AlsaMicrophone
  29.3.2 AlsaSpeaker
  29.3.3 EchoCanceller
 29.4 urbiscript Interfaces
 29.5 Troubleshooting
  29.5.1 Get Jazz Version
  29.5.2 Access Jazz Logs
  29.5.3 Debug your Urbi Code
  29.5.4 Enable Core Dump
  29.5.5 Monitor Jazz Processor and Memory Load
  29.5.6 Monitor Jazz Hard-Drive Space
  29.5.7 I/O Issues when Powering Robot Off
 29.6 ROS support
  29.6.1 About ROS
  29.6.2 ROS support in Jazz
  29.6.3 Enabling and configuring ROS service
  29.6.4 Predefined topics
  29.6.5 Using the navigation stack with ROS

Disclaimer

The information contained in this chapter is subject to change without notice. Gostai makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Gostai shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damage in connection with the furnishing, performance, or use of this material.

This chapter contains information which is protected by copyright. All rights are reserved. Reproduction, adaptation, or translation without prior written permission is prohibited, except as allowed under the copyright laws. Use of this manual is restricted to this product only. Additional copies of the programs may be made for security and back-up purposes only. Resale of the programs in its present form or with alterations, is expressly prohibited.

29.1 Getting started

29.1.1 Documentation and Support

29.1.1.1 Jazz User Manual

Jazz User Manual contains all the information needed to set up your robot, and daily use it: control it with its joystick, control it remotely through Internet (Jazz Connect), set up watch for your premises and configure alerts (Jazz Security), or launch special behaviors (Jazz Connect).

29.1.1.2 Getting Support

Gostai provides commercial support and services, in the form of support packs that you can purchase (http://gostai.com/support/support_packs/). Gostai experts can help you master the Jazz SDK, and assist you with your with Jazz development. To contact Gostai support: support@gostai.com.

29.1.2 Requirements

In order to communicate with, and program Jazz, you need

29.1.3 Embedded Software

29.1.4 Connecting Jazz to your Local Area Network

Please refer to Jazz user manual to know how to setup Jazz on your LAN.

29.1.5 Connecting to Jazz from your Computer

29.1.5.1 Obtaining Jazz IP Address

Turn on your robot with the power button. If you have correctly configured your robot to connect on your LAN (see Jazz user manual), it will say its IP address upon start-up. You will use this IP address to access Jazz on your LAN.

If Jazz cannot access LAN, it will start in ad-hoc mode and won’t say its IP address. Please refer to Jazz user manual to know how to setup Jazz on your LAN.

If DNS is activated on your Local Area Network, then you can also access Jazz using his host name instead of its IP address. In this documentation A1111FRPA001001 is the Jazz host name.

29.1.5.2 Gostai Suite

Gostai Studio Please refer to http://gostai.com/products/studio/gostai_studio/ to get more information about Gostai Studio.

Gostai Lab Please refer to http://gostai.com/products/studio/gostai_lab/ to get more information about Gostai Lab.

29.1.5.3 Telnet Connection to Urbi on Jazz

Jazz runs the Urbi software platform which exposes all the interfaces you need to program your Jazz robot. From a separate computer, you can connect through the network to the Urbi runtime running in the robot and directly send commands written in urbiscript.

By default, when your Jazz robot is powered on, the Urbi runtime listen to TCP connections established on port 54000. You have to use a telnet client to establish such a connection.

From a GNU/Linux or Mac OS X computer, we recommend that you use netcat (nc) in combination with the rlwrap tool (add nice editing capabilities to your netcat connection, keep a commands history).

 
$ rlwrap nc A1111FRPA001001 54000 
[00732235] *** ******************************************************** 
[00732235] *** Jazz version 2.10.2 rev. a2aa56e 
[00732235] *** Copyright (C) 2004-2011 Gostai S.A.S. 
[00732235] *** 
[00732235] *** Urbi SDK version 2.7.2 rev. 7a6a48f 
[00732235] *** Copyright (C) 2004-2011 Gostai S.A.S. 
[00732235] *** 
[00732235] *** This program comes with ABSOLUTELY NO WARRANTY.  It can 
[00732235] *** be used under certain conditions.  Type ‘license;’, 
[00732235] *** ‘authors;’, or ‘copyright;’ for more information. 
[00732235] *** 
[00732235] *** Check our community site: http://www.urbiforge.org. 
[00732235] *** ******************************************************** 
21+21;        // Then type urbiscript commands 
[10421607] 42 // Urbi runtime sends you returns value if available  

PIC

Figure 29.1: A Gostai Console session.

From a Windows computer, we recommend that you use Gostai Console (http://www.gostai.com/download/gostai_console/, see Listing 29.1), a dedicated tool to connect to the Urbi engine running on your Jazz robot.

Specify the host name and port to use (‘A1111FRPA001001:54000’) in the text field in the top of the window and click on the right to start the connection.

29.1.5.4 Ssh Access to Jazz Filesystem

You can use ssh to connect to Jazz and access its filesystem. If you are using Windows you have to install Putty (http://www.putty.org). On Mac OS X or GNU/Linux use the ssh built-in client. To connect through ssh you have to specify in your ssh client:

For example, if Jazz IP address on your LAN is ‘192.168.1.3’, then under GNU/Linux you would have to type in a shell:

 
$ gostai@192.168.1.3 
Login in 
gostai@A1111FRPA001001:# Now you are logged in Jazz, you can type shell commands  

If Jazz host name is ‘A1111FRPA001001’ and you have DNS resolution activated in your LAN, type:

 
$ ssh gostai@A1111FRPA001001 
Login in 
gostai@A1111FRPA001001:# Now you are logged in Jazz, you can type shell commands  

Once you are connected with ssh to your Jazz robot, you arrive in a Bash shell which gives you complete access to Jazz filesystem. If you are not familiar with GNU/Linux and the Bash shell, we advise that you read some Bash tutorial on the Internet to familiarize with Bash basic commands.

It is not mandatory to use ssh to program your Jazz robot. It will only becomes useful if you want to use advanced features like embedding your code in Jazz and have it load at robot start up.

29.1.6 Jazz internal website

Jazz embed a website that allows you to configure and control it. To access this website, just enter Jazz IP address in your browser (Internet explorer, Firefox, Chrome, ...).


PIC

Figure 29.2: Jazz Internal Website.

Click on the Control menu category to access Jazz local control interface, or click on the Configuration menu to access Jazz configuration pages (WiFi, services launched, ...).

29.1.7 Uploading and loading your code on Jazz

29.1.7.1 The User Services web page

In Jazz internal website (Section 29.1.6), we provide a page you can use to upload your own urbiscript services to Jazz, and made it execute them at startup. To access this page, click on the Configuration menu, then click on the User services sub-menu.


PIC

Figure 29.3: User services web page.

From this page you can change the folder where Jazz will search for your code (by default it’s /home/gostai/user). To change it, edit the text field after the label Path to your service folder, then press the Update button below.

You can also upload urbiscript source file to this folder. Click on the Browse button next to the Upload a file to your service folder label. Then choose a file on your computer. It will be automatically uploaded to the robot service folder when you press the Upload button. Once your file was uploaded, it will be listed on the web page.


PIC

Figure 29.4: User services web page: test.u service was uploaded.

If you want Jazz to automatically load your urbiscript file at startup, check the check-box next to your file name, and click on the Update button.


PIC

Figure 29.5: User services web page: test.u service loaded at startup.

29.1.7.2 Uploading Files on Jazz Filesystem using scp

In order to upload files on Jazz filesystem you need to have a client supporting the scp protocol.

Under GNU/Linux or similar Unix system, you can use the scp command line tool.

 
# Copy ’myfile.u’ to Jazz home folder: 
$ scp myfile.u gostai@A1111FRPA001001:/home/gostai/myfile.u  

Under windows you can use WinSCP (http://winscp.net/eng/docs/lang:fr) or Pscp, the scp client that comes with Putty (http://www.chiark.greenend.org.uk/ sgtatham/putty/download.html).

You can then verify with ssh that your file is in the robot:

 
$ ssh gostai@A1111FRPA001001 
Login in 
gostai@A1111FRPA001001:$ ls /home/gostai/myfile.u 
/home/gostai/myfile.u  

29.1.8 Updating Jazz Software

Gostai provides updates to Jazz software. To verify if updates are available and automatically install them, go to Jazz internal website (Section 29.1.6), click on the Configuration menu, then click on the System sub-menu.


PIC

Figure 29.6: System page: display Jazz software information and allow updates.

Jazz will check if updates are available, and in case there are, it will display a button that allows you to start the update process. Please do not shutdown Jazz while updating. At the end of the update Jazz will display a message in it’s website and automatically restart.

If no updates are available, the message “No updates available” will be displayed instead of the update button.

29.1.9 Restarting Jazz Software

To start, stop or restart Jazz software (the Urbi runtime plus Jazz Urbi software), you can use the script /etc/init.d/jazz:

 
gostai@A1111FRPA001001:# shutdown Jazz 
gostai@A1111FRPA001001:$ /etc/init.d/jazz stop 
gostai@A1111FRPA001001:# start Jazz 
gostai@A1111FRPA001001:$ /etc/init.d/jazz start 
gostai@A1111FRPA001001:# restart Jazz 
gostai@A1111FRPA001001:$ /etc/init.d/jazz restart  

29.1.10 Changing Software Profile

The functionality described here is an advanced functionality. Do not use it without first asking advises to Gostai. Misuse can result in Jazz instability or breakage.

Gostai Jazz robot software is modular, and can operate with different software profiles in function of how you want to use the robot: you can activate all its functionalities, or only part of them. We provide an interface that allow to fine tune Jazz in function of your use cases.

To access this interface go to Jazz internal web interface (Section 29.1.6), and choose the Configuration menu, then click on the Services sub-menu.

You can use the shortcut button to set Jazz predefined default configuration, or directly fine tune Jazz activating only the functionalities you need. Please be cautious when doing so, some services have dependencies between each other, some combinations of services might result in Jazz instability. Always request advises from Gostai.

Press the send button when your are done to save the new configuration. Jazz will automatically restart it’s software using the new configuration.


PIC

Figure 29.7: Service activation page: tune Jazz software profile.

29.1.11 Using the Examples

With the descriptions of Jazz modules API, we include urbiscript as well as UObjects examples to help you understand how to use the modules.

29.1.11.1 urbiscript Examples

To play with urbiscript on Jazz, you can open a telnet connection to your robot (use netcat or Gostai Console), and copy and paste the example to evaluate the code.

 
$ rlwrap nc A1111FRPA001001 54000 
[00732235] *** ******************************************************** 
[00732235] *** Jazz version 2.10.2 rev. a2aa56e 
[00732235] *** Copyright (C) 2004-2011 Gostai S.A.S. 
[00732235] *** 
[00732235] *** Urbi SDK version 2.7.2 rev. 7a6a48f 
[00732235] *** Copyright (C) 2004-2011 Gostai S.A.S. 
[00732235] *** 
[00732235] *** This program comes with ABSOLUTELY NO WARRANTY.  It can 
[00732235] *** be used under certain conditions.  Type ‘license;’, 
[00732235] *** ‘authors;’, or ‘copyright;’ for more information. 
[00732235] *** 
[00732235] *** Check our community site: http://www.urbiforge.org. 
[00732235] *** ******************************************************** 
echo("hello world"); 
[00138887] *** hello world  

Alternatively, you can also write the urbiscript code to a file, upload this file on Jazz filesystem using scp, and then load the code from a telnet connection.

 
cat test.u 
echo("hello world"); 
$ scp test.u gostai@A1111FRPA001001:/home/gostai/test.u 
$ rlwrap nc A1111FRPA001001 54000 
[00732235] *** ******************************************************** 
[00732235] *** Jazz version 2.10.2 rev. a2aa56e 
[00732235] *** Copyright (C) 2004-2011 Gostai S.A.S. 
[00732235] *** 
[00732235] *** Urbi SDK version 2.7.2 rev. 7a6a48f 
[00732235] *** Copyright (C) 2004-2011 Gostai S.A.S. 
[00732235] *** 
[00732235] *** This program comes with ABSOLUTELY NO WARRANTY.  It can 
[00732235] *** be used under certain conditions.  Type ‘license;’, 
[00732235] *** ‘authors;’, or ‘copyright;’ for more information. 
[00732235] *** 
[00732235] *** Check our community site: http://www.urbiforge.org. 
[00732235] *** ******************************************************** 
load("/home/gostai/test.u"); 
[00138887] *** hello world  

29.1.11.2 UObjects examples

See the Urbi SDK documentation to know how to compile UObjects with Urbi SDK (using either umake-shared (Section 21.10.2) or Visual Studio templates).

Once you have compiled your UObject, you can run it remotely from your computer, or embed it in the robot (you have to compile your UObject with GNU/Linux for it to be usable on the robot).

Compiling on Jazz Compiling on Jazz can be very slow and inconvenient, however it frees you from the need of installing the Urbi SDK on your computer. To compile on Jazz, first verify that umake-shared is available in your PATH.

 
gostai@A1111FRPA001001:$ which umake-shared 
/usr/local/stow/urbi-sdk/bin//umake-shared  

In case umake-shared is not found, update the PATH variable.

 
gostai@A1111FRPA001001:$ which umake-shared 
gostai@A1111FRPA001001:export PATH=/usr/local/stow/urbi-sdk/bin:$PATH 
gostai@A1111FRPA001001:$ which umake-shared 
/usr/local/stow/urbi-sdk/bin//umake-shared  

Then stop Jazz runtime to free the processor for your compilation.

 
gostai@A1111FRPA001001:$ /etc/init.d/jazz stop  

Upload some UObject code to your robot using scp.

 
gostai@A1111FRPA001001:cd myuob 
gostai@A1111FRPA001001:/myuob$ ls 
test.cc 
gostai@A1111FRPA001001:/myuob$ cat test.cc 
#include <urbi/uobject.hh> 
 
class Test : public urbi::UObject 

public: 
  Test(const std::string& s) 
    : urbi::UObject(s) 
  { 
    UBindFunction(Test, init); 
  } 
 
  int init() 
  { 
    UBindFunction(Test, foo); 
    return 0; 
  } 
 
  std::string foo() 
  { 
    return "Hello world"
  } 
}; 
 
UStart(Test);  

Now you can compile your UObjects.

 
gostai@A1111FRPA001001:/myuob$ umake-shared -q -o test 
gostai@A1111FRPA001001:/myuob$ ls test.so 
test.so  

You obtain a shared library containing your UObject binary code, that you can load and use from urbiscript.

 
loadLibrary("/home/gostai/myuob/test.so"); 
Test; 
[00711192] Test 
var t = Test.new; 
[00718330] Test_0xffffffffb33ab028 
t.foo; 
[00713182] "Hello world"  

Compiling on your Computer See the Urbi SDK documentation to compile on your computer. Use the same version of Urbi SDK that the one used in Jazz for compatibility. To get the version of Urbi used in Jazz see Section 29.5.1.

29.2 urbiscript API

29.2.1 Eye leds

You can change the color of the leds located in the eyes.

29.2.1.1 robot.body.head.eye

The eyes led objects are available using the Gostai Standard Robotics API compliant name robot.body.head.eye[left] and robot.body.head.eye[right].

29.2.1.2 Example

 
// Set the color of the leds in Jazz eyes to green 
function green_eyes() 

  do (robot.body.head) 
  { 
    eye[left].r = 0  & eye[left].g = 255  & eye[left].b = 0 & 
    eye[right].r = 0 & eye[right].g = 255 & eye[right].b = 0 
  }; 
}|; 
 
// Call the function: Jazz eyes becomes green 
green_eyes;  

29.2.2 Docking

Jazz robot have automatic docking to its charging station capabilities. The function to launch the algorithm is, of course, Gostai Standard Robotics API compliant. For a description of Jazz docking API please refer to ??.

29.2.3 Head Motors

Jazz’s head has two degrees of liberty: horizontal (jazz.body.head.yaw) and vertical (jazz.body.head.pitch).

29.2.3.1 robot.body.head

29.2.3.2 Example

 
// Makes Jazz head oscillate horizontally, as if it was saying "no". 
// The function stops after the specified duration. 
function sayNo(duration) 

  timeout (duration) { 
    // Here we assign a sinusoidal trajectory to the head yaw motor: 
    robot.body.head.yaw.val = sin:2s ampli:0.7; 
  }; 
}; 
 
// Make Jazz say "no" for 10 seconds. 
sayNo(10s);  

29.2.4 Microphone

29.2.4.1 Quickly Record the Audio Stream

To quickly record your robot audio microphone stream from your computer, you can use the command line tool urbi-sound (Section 21.9).

For example to record 20 seconds of audio, ssh on the robot and do:

 
gostai@A1111FRPA001001:$ urbi-sound -h 
usage: urbi-sound [options] 
    record and play (or save) sound from a robot 
 
Options: 
  -h, --help               display this message and exit successfully 
      --version            display version information 
  -H, --host=HOST          address to connect to 
  -P, --port=PORT          port to connect to 
      --port-file=FILE     read port number in FILE 
  -d, --device=DEVICE      query sound on DEVICE.val (default: micro) 
  -D, --duration=DURATION  recording duration in seconds 
  -o, --output=FILE        save sound in FILE (/dev/dsp) 
  -n, --no-headers         do not include the headers when saving the sound 
gostai@A1111FRPA001001:$ urbi-sound -H localhost -D 20 -o sample.wav 
gostai@A1111FRPA001001:$ aplay sample.wav  

29.2.4.2 robot.body.head.micro

The microphone device has the following slots:

The microphone object is available using the Gostai Standard Robotics API compliant name robot.body.head.micro or directly typing the shortcut name micro.

29.2.4.3 Example

 
// Calculate the microphone refresh rate by counting the number of time the 
// microphone value is refreshed during 5 seconds, then dividing this count 
// by 5. 
var count = 0 | 
var lnk = micro.&val.notifyChange(closure (){count++}) | 
sleep(5s) | 
micro.&val.removeNotifyChange(lnk) | 
var refresh_rate = count / 5 | 
// Retrieve sound information in the value header 
var keys = micro.val.keywords.split(" ") | 
// Display all the information 
echo("Micro information:"); 
echo(" format: %s" % keys[0]); 
echo(" sample format: %s" % keys[1]); 
echo(" rate: %s" % keys[2]); 
echo(" sample size: %s" % keys[3]); 
echo(" channels: %s" % keys[4]); 
echo(" micro.val is refreshed %s times per second" % refresh_rate); 
[19281072] *** Micro information: 
[19281073] ***  format: raw 
[19281074] ***  sample format: 1 
[19281076] ***  rate: 16000 
[19281077] ***  sample size: 16 
[19281080] ***  channels: 1 
[19281086] ***  micro.val is refreshed 25 times per second  

 
// Let’s record 5 seconds of the micro sound: 
// - create the file where we’ll save the sound, and open it in an output stream 
var o = OutputStream.new(File.create("/tmp/sound.pcm")); 
// - every time the micro value change, append the sound chunk to the file 
var lnk = micro.&val.notifyChange(closure() { o << micro.val.data ; }); 
sleep(5s); 
// - stop recording 
micro.&val.removeNotifyChange(lnk); 
// - close the output stream 
o.close; 
// Now you can play the recorded sound with the shell command: 
//   aplay -f S16_LE -r 16000 -c 1 -t raw /tmp/sound.pcm  

29.2.5 Network

Network object provides methods and attributes to configure and get the current state of the WiFi.

29.2.5.1 robot.network

29.2.5.2 Example

To connect your Jazz robot to your LAN, use the web interface as describe in the Jazz User Manual. It is also possible to specify the network on which Jazz connects. However be careful, Jazz save the network information you provide, and will reuse them for all its future connections. To connect to a WiFi network with ESSID myNetwork and key myHiddenKey.

 
network.essid="myNetwork"
network.key="myHiddenKey"
// Tell network to connect with current parameters and save them. 
network.submit;  

You can also provide a static IP. Let say we want IP 192.168.0.3, net-mask 255.255.255.0, DNS and gateway 192.168.0.1. Using do to factor network:

 
do (network) 

  essid="myNetwork"
  key="myHiddenKey"
  ipAddress="192.168.0.3"
  netMask="255.255.255.0"
  dnsAddress="192.168.0.1"
  gatewayAddress="192.168.0.1"
  // Tell network to connect with current parameters and save them. 
  submit; 
};  

To reset the robot in ad-hoc mode:

 
// The robot will take IP 192.168.0.1 and start a DHCP server. 
network.setAdHoc;  

29.2.6 Playing Sound

Jazz can play mp3 files with its speaker. The files must be available on Jazz filesystem, or hosted on a web server.

29.2.6.1 Example

 
mp3.play("/usr/local/stow/jazz/share/mp3/jazz_startup.mp3"); 
sleep(1s); 
mp3.stop; 
mp3.play("http://example.com/sound/sound.mp3");  

29.2.7 Text to Speech

Jazz integrate text to speech. It must be connected to Internet to use text to speech). Only french language is currently supported.

29.2.7.1 Example

For Jazz to say the sentence: “Bonjour, je suis Jazz le robot”, run:

 
voice.say("Bonjour, je suis Jazz le robot");  

Note: the function can fail in case Jazz network connection timeout.

29.2.8 Video Camera

You have access to Jazz video camera device: you can request the raw images, and process them using urbiscript/UObject.

29.2.8.1 Visualize the Video Stream

To quickly visualize your robot video camera stream from your computer, you can use Gostai Lab or the command line tool urbi-image (Section 21.4).

urbi-image opens a graphic windows rendering the live stream from the video camera. Its usage is:

 
$ urbi-image -h 
usage: urbi-image [options] 
Display images from an urbi server, or save one image if -o is given 
 
Options: 
  -h, --help                   display this message and exit successfully 
      --version                display version information 
  -H, --host=HOST              address to connect to 
  -P, --port=PORT              port to connect to 
      --port-file=FILE         read port number in FILE 
  -p, --period=PERIOD          query images at given period (in milliseconds) 
  -F, --format=FORMAT          select format of the image (rgb, ycrcb, jpeg, ppm) 
  -r, --reconstruct            use reconstruct mode (for aibo) 
  -j, --jpeg=FACTOR            jpeg compression factor (from 0 to 100, def 70) 
  -d, --device=DEVICE          query image on DEVICE.val (default: camera) 
  -o, --output=FILE            query and save one image to FILE 
  -R, --resolution=RESOLUTION  select resolution of the image (0=biggest) 
  -s, --scale=FACTOR           rescale image with given FACTOR (display only) 
 
transfer Format : jpeg=transfer jpeg, raw=transfer raw 
save     Format : rgb , ycrcb, jpeg, ppm 
$ urbi-image -H A1111FRPA001001  

To visualize the stream with Gostai Lab, connect Gostai Lab to your robot, and enter camera.val in the variable field. The live stream of the video camera will automatically get displayed.

29.2.8.2 robot.camera

The camera device is represented by the urbiscript object whose slots are:

The camera object is available using the Gostai Standard Robotics API compliant name robot.body.head.camera or directly typing the shortcut name camera.

29.2.8.3 Example

Here some urbiscript example code manipulating the camera object:

 
echo("Acquired image size: %sx%s" % [camera.width, camera.height]); 
[00237095] *** Acquired image size: 320x240 
var e = watch(camera.val); 
var t = Timeout.new(5s); 
try 

  var count = 0 | 
  t:at(e?) count++ & 
  t:every(1s) { 
    echo("camera.val was refreshed %s times" % count); 
    count = 0; 
  }; 

catch (var e) 

  echo("timed out"); 
}; 
[00238639] Event_0xffffffffb4dc3728 
[00238641] Timeout_0xffffffffb4dd8928 
[00238643] *** camera.val was refreshed 0 times 
[00239647] *** camera.val was refreshed 14 times 
[00240647] *** camera.val was refreshed 15 times 
[00241647] *** camera.val was refreshed 15 times 
[00242647] *** camera.val was refreshed 15 times 
[00243647] *** camera.val was refreshed 15 times 
[00243650] *** timed out  

If you want to process the video camera raw image data, you can only do it from C++ or Java, using the UObject component API.

 
#include <urbi/uobject.hh> 
 
// ProcessCamera is an UObject that does video processing with the 
// camera stream. 
class ProcessCamera : public urbi::UObject 

public
  ProcessCamera(const std::string& s) 
    : urbi::UObject(s) 
  { 
    UNotifyChange("camera.val", &ProcessCamera::process); 
  } 
 
  // Each time camera.val urbiscript variable is refreshed, your 
  // function will get called with the new video camera image. 
  void process(urbi::UVar& val) 
  { 
    urbi::UImage i = val; 
    // Do processing. See Urbi SDK documentation to know more about UImage. 
  } 
};  

29.2.9 Movement

We provide high level API to move Jazz.

29.2.9.1 urbiscript interface

The following slots of the robot object control the movement.

29.2.9.2 Example

 
var watchdogGoTag = Tag.new|; 
 
function goDuring(duration, speed) 

  disown({ 
    watchdogGoTag.stop | 
    watchdogGoTag:{ 
      robot.xSpeed = speed; 
      sleep(duration); 
      robot.stop(); 
    }; 
  }); 
  true; 
}|; 
 
goDuring(2s, 1); 
robot.go(2s);  

29.2.10 Screen Display

The Open Jazz does not provide yet any Urbi API to manage the display. However you can launch GNU/Linux graphical commands which will use the display. An X server (Xorg see http://www.x.org/wiki/) is installed in Jazz to manage the display.

29.2.10.1 From urbiscript

You can launch any GNU/Linux application from urbiscript by using the Process object. You can try to launch the xeyes application to test the display. To do so, connect to the Urbi runtime and create an xeyes process, then run it.

 
var p = Process.new("xeyes", ["-geometry""800x500"]); 
[00059674] Process xeyes 
p.run; 
// Two eyes get displayed on the screen. 
sleep(10s); 
p.kill; 
// The two eyes disappeared. 
p.join;  

All GNU/Linux graphical application can be launched in the same way. You can also display images using the display command. First upload some image to Jazz filesystem using scp.

 
$ scp myimage.jpg gostai@A1111FRPA001001:  

then display the image from urbiscript:

 
var p = Process.new("display"
                    ["-geometry""800x480+-1+24""/home/gostai/myimage.jpg"]); 
[00897748] Process display 
p.run; 
sleep(10s); 
p.kill; 
p.join;  

29.2.10.2 Command Line

You can also launch graphical commands directly from shell session, but you must first set the DISPLAY environment variable as follow:

 
gostai@A1111FRPA001001:export DISPLAY=:0.0 
gostai@A1111FRPA001001:$ xeyes -geometry 800x500  

29.2.11 Sonars

Jazz robot includes 8 sonars sensors. are located in front of the robot with a constant spacing in order to detect any obstacle. One is located in the torso of the robot to detect desk and the last one is located in the back of the robot. You can access those sensors using an array containing every values with this order: [left1, left2, left3, torso, right3, right2, right1, back]

29.2.11.1 urbiscript Interface

 
robot.body.sonars.val; 
[00030042] [4.45448, 4.87494, 2.4531, 5.31701, 2.4292, 1.61747, 1.15333, 0.133563]  

29.2.11.2 Example

 
/* 
 * Stop the robot when sonar sensor values are less than 45 centimeters. 
 */
 
at (watch (robot.body.sonars.val)?) 

  var i = 0; 
  for (var d in robot.body.sonars.val) 
  { 
    if (i <= 6 && d <= 0.45) 
      robot.stop(); 
    i++; 
  }; 
};  

29.2.12 IRs

The robot includes 4 IR sensors designed specifically to detect desk and stairs that it have to avoid. Two of them are pointing to the ground so when the distance grow you should be able to know there is a hole in front of the robot. And the last two are pointing to the sky so when their value become short you can assume that there is an obstacle in front (like a chair or a desk that sometimes are too close to be detected with the sonars).

You can access an array containing the 4 sensors’ values in this order: [upLeft, upRight, floorLeft, floorRight].

29.2.12.1 urbiscript Interface

 
robot.body.irs.val; 
[00914315] [0.645662, 0.61491, 1.5, 1.5]  

29.2.12.2 Example

 
/* 
 * stop the robot when IR sensors value are above (or under) 1 meter 
 */
 
at (watch (robot.body.irs.val)?) 

  var i = 0; 
  for (var d in robot.body.irs.val) 
  { 
    if (i <= 1 && d >= 1 
        || i >= 1 && d <= 1) 
      robot.stop(); 
    i++; 
  }; 
};  

29.2.13 Laser

Jazz has an Hokuyo laser (not available in all version of Open Jazz) accessible with “robot.body.laser”.

29.2.13.1 robot.body.laser

29.3 urbiscript Library

29.3.1 AlsaMicrophone

The AlsaMicrophone uobject is a driver UObject that can be used to communicate from urbiscript to the microphone device thanks to the ALSA (Advanced Linux Sound Architecture) library. The AlsaMicrophone prototype has only one slot available:

Using new you create child instances of AlsaMicrophone. These new prototypes have the following slots:

29.3.2 AlsaSpeaker

The AlsaSpeaker uobject is a driver UObject that can be used to communicate from urbiscript to the speaker device thanks to the ALSA (Advanced Linux Sound Architecture) library. The AlsaSpeaker prototype has only one slot available:

Using new you create child instances of AlsaSpeaker. These new prototypes have the following slots:

29.3.3 EchoCanceller

This UObject remove the sound signal played by the speaker, from the sound signal captured by the microphone. The EchoCanceller prototype has only one slot available:

Using new you create child instances of EchoCanceller. These new prototypes have the following slots:

29.4 urbiscript Interfaces

An interface describes some aspects of a type of device, by specifying the slots and methods that implementations must provide. Each child node of the component hierarchy should implement at least one interface.

In short, interfaces are standard Urbi objects that components can inherit from to declare that they have some functionalities.

The following pages describe interfaces defined for Jazz and used by some of Jazz objects.

29.4.0.1 AutomaticGainControl

Interface for Automatic Gain Control (AGC) algorithm.

29.4.0.2 Denoiser

Interface for Denoiser (remove noise from a sound signal) algorithm.

29.5 Troubleshooting

29.5.1 Get Jazz Version

The version of Jazz software which is installed on your robot is displayed when you connect to your robot using netcat, Gostai Console or Gostai Lab.

 
$ rlwrap nc A1111FRPA001001 54000 
[00732235] *** ******************************************************** 
[00732235] *** Jazz version 2.10.2 rev. a2aa56e 
[00732235] *** Copyright (C) 2004-2011 Gostai S.A.S. 
[00732235] *** 
[00732235] *** Urbi SDK version 2.7.2 rev. 7a6a48f 
[00732235] *** Copyright (C) 2004-2011 Gostai S.A.S. 
[00732235] *** 
[00732235] *** This program comes with ABSOLUTELY NO WARRANTY.  It can 
[00732235] *** be used under certain conditions.  Type ‘license;’, 
[00732235] *** ‘authors;’, or ‘copyright;’ for more information. 
[00732235] *** 
[00732235] *** Check our community site: http://www.urbiforge.org. 
[00732235] *** ********************************************************  

Here we see that Jazz version is ‘2.10.2 rev. a2aa56e’ and Urbi SDK version is ‘2.7.2 rev. 7a6a48f’.

29.5.2 Access Jazz Logs

There are several scripts available to view Jazz logs: tail-outlog.sh and tail-errlog.sh allow you to monitor in live the error and output log streams, and less-outlog.sh and less-errlog.sh allow you to display and navigate through the complete error and output logs. To quit tail-*log.sh you should send a terminate signal, by pressing Ctrl+c (or Ctrl+break on certain systems). To quit less-*log.sh simply press the q key.

 
gostai@A1111FRPA001001:$ tail-errlog.sh 
Wed 2011-05-25 14:28:45 CEST    [     Jazz.parseopt     ] profile  ’teleop-rev03’ loaded 
Wed 2011-05-25 14:28:45 CEST    [ Jazz.real_devices.adl ] Loading... 
Wed 2011-05-25 14:28:45 CEST    [ Jazz.real_devices.adl ] ADL start 
Wed 2011-05-25 14:28:45 CEST    [ Jazz.real_devices.adl ] Loaded... 
Wed 2011-05-25 14:28:45 CEST    [Jazz.real_devices.shared-camera] Loading... 
^C  

29.5.3 Debug your Urbi Code

29.5.3.1 Monitor urbiscript Job Execution

To get some info on the urbiscript executing in the Urbi runtime you can use System.stats (display the cycle execution stats) and System.ps (list the urbiscript jobs).

 
// Display the cycle stats (recorded on a 10s time frame) 
System.resetStats; 
sleep(10s); 
System.stats; 
[00198274] ["cyclesStdDev" => 0.00219118, "cyclesVariance" => 4801.27, 
 "cyclesMean" => 0.00163504, "cyclesMax" => 0.014414, "cyclesMin" => 0.000171, 
 "cycles" => 2110] 
 
// Display current urbiscript jobs 
System.ps; 
[00215160] *** Job: shell 
[00215160] ***   State: idle (frozen) (side effect free) 
[00215160] ***   Time Shift: 0.026387ms 
[00215160] ***   Tags: 
[00215160] ***     Tag<Lobby_216> 
[00215160] *** Job: event_224 
[00215160] ***   State: waiting 
[00215160] ***   Tags: 
[00215160] ***     Tag<Lobby_98> 
[00215160] ***     Tag<tag_104> 
[00215160] ***     Tag<tag_102> 
[00215160] ***     Tag<tag_152> 
[00215160] ***   Backtrace: 
[00215160] ***     rewrite/desugarer.cc:324.6-23: sleep 
[00215160] ***     /jazz/share/jazz/services/urbi/fsm.u:289.15-22: emitDone 
[00215160] ***     /jazz/share/jazz/services/urbi/fsm.u:476.16-31: enter 
[00215160] ***     /usr/local/stow/urbi-sdk/share/gostai/urbi/control.u:18.5-26: spawn 
[00215160] ***     /jazz/share/jazz/services/urbi/fsm.u:476.16-31: detach 
[00215160] ***     /jazz/share/jazz/services/urbi/fsm.u:436.11-52: applyTransition 
[00215160] ***     /jazz/share/jazz/services/urbi/fsm.u:234.13-37: transit  

29.5.3.2 Monitor UObjects Execution Time

There is a statistic gathering tool available from urbiscript. Enable it with uobjects.enableStats. Reset counters by calling uobjects.clearStats. uobjects.getStats returns a Dictionary of all bound C++ functions called, including timer callbacks, along with the average, min, max call durations, and the number of calls.

 
// In this example, we display the execution time of UObjects 
// components in a 10 second time frame. 
function displayStats() 

  var sorted = getStats.asList.sort(function(obj1, obj2) { 
    obj1[1][0]*obj1[1][3] < obj2[1][0]*obj2[1][3] 
  }); 
  echo("Exec time (avg, min, max) (ms) | #calls | UObject name"); 
  for (var obj : sorted) 
    echo("%4s, %4s, %5s | %3s | %s" % (obj[1] + [obj[0]])); 
}|; 
enableStats(true); 
clearStats; 
sleep(10s); 
 
displayStats; 
[00895231] *** Exec time (avg, min, max) (ms) | #calls | UObject name 
[00895236] ***  106,  102,   115 |  10 | uob_0xb783b5d8.load --> uob_0xb783b5d8 
[00895238] ***   41,   24,   358 | 150 | VideoIn_0xb70ba2b8.valJPEG --> uob_0xb7141328 
[00895240] ***  230,  197,   423 |  40 | ifconfig_0xb70972e8 update 
[00895243] ***   26,   25,   236 | 380 | uob_0xb78548d8.sharp2 --> uob_0xb7199408 
[00895245] ***   26,   25,    95 | 380 | uob_0xb78548d8.sharp1 --> uob_0xb7199408 
[00895247] ***  248,  229,   318 |  40 | Iwconfig_0xb7827278 update 
[00895249] ***   27,   25,    65 | 380 | uob_0xb78548d8.sharp3 --> uob_0xb7199408 
[00895252] ***   34,   29,   276 | 380 | uob_0xb78548d8.sharp0 --> uob_0xb7199408 
[00895254] ***  104,   16, 11699 | 380 | uob_0xb70f2628.speedAlpha --> uob_0xb70f2628 
[00895264] ***  455,  412,   736 | 390 | uob_0xb7199408.inputSpeedAlpha --> uob_0xb7199408 
[00895266] ***  503,  456,   745 | 390 | uob_0xb7199408.inputSpeedDelta --> uob_0xb7199408 
[00895268] *** 1067,   30, 10795 | 380 | uob_0xb70f2628.speedDelta --> uob_0xb70f2628 
[00895271] *** 1406,  249, 12163 | 380 | uob_0xb78548d8.sonars --> uob_0xb7199408 
[00895272] *** 2812, 1557, 13606 | 380 | uob_0xb78548d8  

With this information you can check whether your UObjects take too long to execute.

29.5.4 Enable Core Dump

The Linux kernel is able to generate core dumps when a program crashes. These core-dump files can then be given to gdb to debug the program. To enable core dumps in the Linux kernel, ssh on the robot and do:

 
gostai@A1111FRPA001001:$ sudo ulimit -c unlimited 
gostai@A1111FRPA001001:ulimit -c unlimited 
gostai@A1111FRPA001001:echo 1 > /proc/sys/kernel/core_uses_pid  

29.5.5 Monitor Jazz Processor and Memory Load

Log in with ssh and use top or htop to view Jazz load. If your robot is overloaded the Urbi runtime cannot guarantee a normal behavior.

29.5.6 Monitor Jazz Hard-Drive Space

Log in with ssh and use ‘df -h’. It displays the amount of memory used and available (look at the ‘/dev/sda1’ line).

29.5.7 I/O Issues when Powering Robot Off

If you edit files directly on the robot (using ssh), the filesystem cannot guarantee that your changes will be effectively written to memory if you shutdown the robot with the on/off power button just after having made your changes. If you need to stop or restart your robot, either:

29.6 ROS support

29.6.1 About ROS

ROS (Robot Operating System) is a set of tools and libraries designed to provide a common framework for robotic application developers. There are already thousands of compatible applications available in various domains such as computer vision, navigation, visualization tools...

29.6.2 ROS support in Jazz

Jazz comes with complete ROS compatibility. The currently used ROS version is ’electric’. A subset of the ROS distribution is installed in the /opt/ros directory of the Jazz hard drive.

29.6.3 Enabling and configuring ROS service

ROS support in Jazz is implemented as a Jazz service and is disabled by default. Refer to section Section 29.1.10 for instructions on how to enable and disable services.

By default, a ROS master is started on the robot when the service is enabled. You can specify a different ROS master by setting the config.ros.master_uri configuration variable:

 
  config.ros.master_uri = "http://my_computer:11311"
  // Call _save to make the change persistent. 
  config.ros._save;  

29.6.4 Predefined topics

The Jazz ROS service maps each device of the robot to a ROS Topic with similar name. The following table lists the most important topics:





Urbi name ROS topic Dir ROS message type




jazz.body.irs

/robot/body/irs Pub sensor_msgs/LaserScan

jazz.body.sonars

/robot/body/sonars Pub sensor_msgs/LaserScan

jazz.body.laser

/robot/body/laser Pub sensor_msgs/LaserScan

jazz.camera

/robot/body/head/camera Pub sensor_msgs/Image

/robot/body/head/pitch_out Pub std_msgs/Float32
/robot/body/head/pitch_in Sub std_msgs/Float32

/robot/body/head/yaw_out Pub std_msgs/Float32
/robot/body/head/yaw_in Sub std_msgs/Float32

/robot_in Sub geometry_msgs/Twist
/robot_out Pub nav_msgs/Odometry
/tf Pub tf/tfMessage




The sonar array and the laser if present are accessible as standard LaserScan data. Robot odometry is available as either nav_msgs/Odometry messages in the /robot_out topic or standard tf transforms on the /tf topic.

All sensor messages with a header are given in the base_footprint frame. tf messages from the odometry are published on the standard /tf topic, performing the /base_footprint -> /odom transform.

Head yaw and pitch are mapped to two different topics, since they have a sensor part and an actuator part.

29.6.5 Using the navigation stack with ROS

If your Jazz is equipped with a laser scanner, Jazz is compatible with the ROS navigation stack.

Navigation components can run on the Jazz CPU, or as remote components.

It is recommended to run them remotely, especially if you plan to use the web control interface at the same time to avoid overloading the Jazz CPU.

29.6.5.1 Creating a map of your environment

The gmapping module can be used to create a map of your environment.

Make sure you are using the same ros-master as your Jazz. If you type rostopic list you should see all the topics advertised by the robot.

Then run:

 
rosrun gmapping slam_gmapping scan:=/robot/body/laser  

This will start gmapping. gmapping then processes odometry and laser scan data to create a map of the environment as the robot moves.

Using the joystick (preferred) or the web interface, navigate the robot around your environment. You should avoid fast rotations as it puts too much stress on the SLAM process.

When you are done, extract the map using:

 
rosrun map_server map_saver  

This will create the file map.pgm containing your map data.

You should then open the map in an image editor and crop it to remove the empty space. This will reduce CPU requirements for the localization task.

29.6.5.2 Autonomous navigation

You will find on the robot a ROS package named jazz_navigation under JAZZ_ROOT/share/vigilant/ros that contains a reasonable default configuration for the navigation.

You can copy the whole directory to an external computer (recommended) or run it on the robot:

 
# Copy the parameter files (replace myJazzName with the host name of your Jazz) 
scp -r myJazzName:/usr/local/stow/vigilant/share/vigilant/ros jazz-ros 
# Make the package visible to ros 
export ROS_PACKAGE_PACK=$PWD/jazz-ros:$ROS_PACKAGE_PATH 
# Run the navigation package 
roslaunch jazz_navigation move_base.launch  

See the ROS navigation tutorial for information about the various configuration files.

You can visualize sensor data and set navigation goals using the ROS rviz tool:

 
rosrun rviz rviz  

Then load the jazz_navigation/nav.vcg layout file in rviz, which contains the proper rviz configuration for Jazz.

29.6.5.3 Troubleshooting

Jazz does not move when setting a navigation Goal If Jazz is docked on its charging station, move commands are disabled. You must remove Jazz from its charging station manually.