As quick as a start as we can give

It will take longer than you think, but less time than you expect.

Overview

The RoboDeb VMWare virtual machine was developed for use in the classroom at the University of Kent in Canterbury, England. In particular, we wanted to provision a complete Player/Stage environment for simulating the Pioneer3 autonomous robotics platform. The requirements for Player/Stage preclude its deployment in a typical university computing environment (eg. Windows XP machines with limited user permissions); as a simulation framework, it has too many dependancies on open-source software only available on the Linux platform.

With the free release of VMWare Player, we realized a mechanism by which we could provide a complete Linux environment to our students in a Windows-only computing laboratory. We built a Debian virtual machine, installed Player/Stage, and support for running our language of choice for robotics control, the Transterpreter.

This document describes how to obtain VMWare Player, the RoboDeb virtual machine, and the basics for writing and running a simple occam program for controlling the (virtual) Pioneer3. Happily, if you own a real Pioneer3, these programs will run, unmodified, on the actual hardware.

Obtaining the software

You will need two critical pieces of software to run the RoboDeb virtual machine.

VMWare Player

VMWare makes their virtual machine player application, Player, freely available for download on both Windows and Linux (x86). You can stop reading now if you don't have a computer running Windows or Linux. We assume, at some point, that VMWare will provide a version of Player for Mac OS X running on Intel hardware; for now, Mac users (like ourselves) are out of luck.

This document will not tell you how to install VMWare Player. Documentation is provided by VMWare Corp.; we recommend you take advantage of that documentation if you feel you need it.

The RoboDeb Virtual Machine

VMWare Player does not do much on its own; someone must provide an image of a virtual machine for the player to run. This allows you to (say) boot a Linux computer, in a window, inside the Windows operating system. Or, to run a Windows virtual machine on top of Linux.

We provide a Debian GNU/Linux virtual machine with Player/Stage pre-installed, plus a significant amount of support software for programming it in occam. The virtual machine is 320MB in size (compressed) and 1.2GB uncompressed; While you may not need it, the root password of this VM is "tvm".

"Installing" the RoboDeb image

The RoboDeb image is packaged as a ".tar.bz2" file. You will probably handle this file differently on Linux than you will on Windows.

Linux installation

In order to use RoboDeb on Linux you will need to have the tar and bzip2 programs installed on your machine. These are generally available with all linux distributions so you should either already have them, or be able to install them in a simple manner. To install RoboDeb you need to download the RoboDeb image and put it somewhere where you can get at it and have enough space (1.2gb).

Find where you downloaded the RoboDeb image, and decompress the file:

prompt> bunzip2 RoboDeb007.tar.bz2

The exact name of the RoboDeb image may be slightly different. After unzipping the file, you must then un-tar the image as well.

prompt> tar -xvf RoboDeb007.tar

Once you have performed these two operations, you will have a RoboDeb directory containing an assortment of files. You can place this directory anywhere you wish on your drive. The users executing the image must have write permissions to the files contained therein.

Windows installation

In order to use RoboDeb in Windows you will need a decompression tool that supports the bz2 compression format (also known as bzip2). In order to decompress the RoboDeb image, we recommend that you use 7 Zip. Using 7-Zip you should be able to open the RoboDeb archive by double-clicking on it, or possibly have it open the image as soon as you begin your download.

When you have obtained an apropriate decompression tool, download the RoboDeb image and decompress it. Once decompressed you will find a directory called RoboDeb007 (or a higher number). Inside this directory there are a bunch of files, one of which will be called something along the lines of RoboDeb007.vmx. If your VMWare player installation and the decompression went according to plan, you should be able to just double click on the .vmx file to start the virtual machine.

The Transterpreter mailing list

If you are interested in new RoboDeb images and related developments, please drop an email to matt at transterpreter dot org and ask to be placed on the tvm-discuss mailing list. It is low traffic, and we would be more than happy to hear about your experiences with the VM there (it becomes part of our archive). We are looking forward to hearing from you.

Thanks, and enjoy.

RoboDeb VM Basics

About the VM

The RoboDeb virtual machine is a full installation of Debian GNU Linux. On this virtual machine we have provided a significant number of tools to aid in the development of programs against the Player/Stage libraries. These include, but are not limited to:

While it isn't exactly a piece of software, we have provided a mechanism for updating all the components critical to doing robotic simulation on the virtual machine through a double-clickable icon on the desktop. This includes the Player/Stage libraries, the Transterpreter and supporting occam tools, JEdit, and many other aspects of the system. Because the VM is a full Debian installation, any software not present on the VM can easily be installed by the end user using the command-line apt-get tools.

What you see is what you get

From the desktop, you can do a few things quite simply:

In truth, you rarely need to power down the virtual machine; you should be able to "close" VMWare Player, and it will "suspend" the virtual machine. This will allow you to quickly restart the VM from a suspended state---this is much faster and quite convenient.

Advanced VM Usage...

As we noted before, it is possible to install Debian packages on the VM using apt-get, as well as anything else that is possible on a computer Debian GNU Linux. However, if you are behind a firewall, or otherwise proxied, you may find that both apt-get and our automatic updater will not work. We will never be providing support for users who modify their VM to their liking using apt-get, or who download and build their own software. However, if you do find that the automatic updater (or Firefox, etc.) does not work in your particular context, please drop a note to the tvm-discuss mailing list, and we will do what we can to help. In particular, if you are attempting to provide this virtual machine in a University or other school context, we have some experience from our deployment at University Kent that may be of value to you.

Using the Transterpreter & Player/Stage

The occam programming language provides powerful abstractions for developing programs that must manage hundreds, thousands, and even tens of thousands of concurrent processes. The occam programming language is especially well suited to the world of robotics, as robots fundamentally need to manage input, output, and computation all at once. This section is not a tutorial on the occam programming language, but instead provides you with a robotic "Hello, World!" program that you can use to test your VM and Player/Stage setup with.

Hello, Robot!

occam is a language of processes. In occam, almost every line of code is considered a process. Now, we typically think of UNIX "processes," in which we have "threads" (this is what we have in Java, too). Using this terminology, it might help to think of occam processes as "fibers"; they're incredibly lightweight things that are juggled around with insane efficiency.

After launching JEdit, you'll need to open the occPlug. Go to the "Plugins" menu, and down to occPlug. Then, select "Start occPlug" from the menu. This will give you a new, floating window (or, it might be docked... it's a mystery) that includes a number of tools. It might look something like this:

occplug-float.png

The occPlug has a few critical buttons: "Compile" (the loopy arrow), "Run" (the little person, running), and "Stop" (the big, black square). "Clear" (which clears the terminal) is the swooshy-looking stick thing to the right of "Stop".

In the main window, insert this code: 

#USE "course.lib"

#INCLUDE "player.inc"

-- The "print.middle.value" process takes in the 
-- array of laser data, and outputs the value 
-- at the middle of the array. The process
-- "out.string" comes from the course library.
PROC print.middle.value (CHAN LASER sick?, CHAN BYTE scr!)
  WHILE TRUE
    LASER data:
    SEQ
      sick ? data
      out.int(data[90], 0, scr!)
      out.string("*c*n", 0, scr!)
:

-- The main process binds to the top-level channels
-- for reading from the keyboard and outputting to the
-- screen and the standard error channel. Then, in
-- parallel, we run the three processes "brain.stem.ML",
-- which comes from the "pioneer.inc" library, 
-- "print.middle.value", which we define above, and 
-- a simple process that sends a command to the motors,
-- which sets the Pioneer rolling forwards.
PROC main (CHAN BYTE kyb?, scr!, err!)
  CHAN LASER sick:
  CHAN MOTORS commands:
  PAR
    brain.stem.ML(commands?, sick!)
    print.middle.value(sick?, scr!)
    commands ! 10 ; 0 ; 0
:

Note that occam is indentation sensitive, just like Python; the compiler will yell at you if your copy-paste from this documentation fails to preserve the indentation correctly. After pasting this into JEdit, you should be able to compile the program. Then, if you have a Stage world running (we recommend "big-circle"), you should be able to execute the program, and it will trundle the Pioneer forward, all the while printing the value read at the center of the laser sensor's sweep.

That's it!

Well, that isn't all there is to it. However, you now have a robot that is running code concurrently, shuffling data between those processes, and you have no fear that your concurrency will go wrong. No polling loops, no threading, no worries about shared data causing a race hazard of one sort or another. Really, it's pretty good.

From this point forward, you need to develop more of an understanding of the CSP model of concurrency, the occam programming language, and the libraries we've provided for accessing the Pioneer.

Using Java/JCSP & Player/Stage

You can do this. We just haven't written any documentation for it yet.