MSRS Code Page Home      MSRS Intro Program

Documentation for Intro to Autonomous Robotics

This page contains basic instructions for using the Intro program. Please read through the whole page before you attempt to install the program. Most of your questions should be answered by this page. You should also read the readme.txt file that comes with the code in the ZIP file.

Requirements and Installation

To get started, you need to install the Microsoft Robotics Studio on your PC. A download is available that is free for non-commercial use: Robotics Studio Download Site. It requires the Ageia Phyics Engine, XNA and .NET 3.0 runtimes, which will all be installed automatically.

If you want to write your own code, then you will need Visual Studio 2005, but since there is not much point in using a Robotics Software Development Kit (SDK) without a compiler, I assume that you already have Visual Studio. You can also use the Express Edition of Visual Studio which you can download for free.

Download the QUT MSRS code using the link on the previous page. Unzip the file into your MSRS root directory. It will create the following folder:
where <MSRS> is the directory that your copy of MSRS is installed in. In my case this is "C:\Microsoft Robotics Studio (1.5)" for Version 1.5.

Notice that my MSRS is installed on my C: drive. If yours is on a different drive, then you will have to modify several settings in the Visual Studio project before compiling. See the readme.txt for more information.

IMPORTANT NOTE: In the explanations that follow I have assumed that you unzipped the Intro program into <MSRS>\Apps\QUT\Intro. I have also assumed that you have installed the Maze Simulator and that it is working, as well as my modified version of the Dashboard.

How to run the Intro program

You have the option of either re-building the program yourself or just using it. If you do not want to build the code, or you don't have Microsoft Visual Studio 2005, then the executables are included in the ZIP file and there are instructions for setting it up and running it in readme.txt.

As with all MSRS programs, you need to start the Intro from a MSRS DOS command prompt window, or using the debugger in Visual Studio. Let's begin with running the program directly. Make sure you have followed the installation instructions exactly.

Starting a MSRS Service

When you installed MSRS, it would have created a folder in your Start Menu that contains a shortcut for "Robotics Studio Command Prompt". Open one of these windows now.

At the command prompt, enter the following command:
dsshost -port:50000 -tcpport:50001 -manifest:"Apps/QUT/Intro/Intro.manifest.xml"
A batch file, called RunIntro.bat, is included in the ZIP file and it contains this command to help make this easier. This batch file must be in the MSRS root directory for it to work properly.
IMPORTANT NOTE: Dsshost.exe is the main control program for MSRS. It is responsible for starting services, i.e. programs like Intro. You must run it from the MSRS root directory because it looks for various components beginning at the current directory when you run it.

Using the Visual Studio Debugger

If you want to rebuild the code, then you can open the Visual Studio Solution from a MSRS Command Prompt window. Open a window, change directories to the correct directory, and then start Visual Studio using the following commands:
cd Apps\QUT\Intro
devenv Intro.sln

Alternatively, just find the Intro.sln file in Windows Explorer and double-click on it. This should start Visual Studio 2005.

Once the solution is open in Visual Studio, you can start it with the debugger by selecting Debug \ Start Debugging or pressing F5.
IMPORTANT NOTE: Make sure that you have updated the Project settings if your MSRS installation is not on the C: drive. The instructions are in readme.txt.

Using the Intro program

When Intro starts, it will create two windows: A Simulator and a Dashboard. These are shown below. Click on the images for larger views.

Simulator ViewDashboard

The little object in the centre of the Simulation window is the Pioneer robot. This maze world has textured floor and walls and brightly coloured objects. None of them are moveable (except for the balls), i.e. they all have infinite mass. This is something you can change in the Maze Simulator later if so that the robot can push things around.

To change your viewpoint in the Simulator, click on the window and drag with the mouse. You can also use the standard gaming keys, A, S, D and W, for moving around. Note that A and D are strafe keys, not rotate. The S and W keys move forwards and backwards along the line of sight. Use the mouse to change the direction of motion. The E and Q keys can be used to move up and down. It's easy to get used to, especially if you are a gamer.

In the Dashboard, you must enter localhost as the name of the Remote Node and Port number 50001. Then click on the Connect button.
Two services will appear in the listbox. Double-click on the simulateddifferentialdrive service, then click on the Drive button. You are now ready to control the robot!

NOTE: If you are using the modified Dashboard, then it will remember the Node and Port if you save the settings from the File menu. It also remembers the position of the Dashboard on the screen. This can be very handy because it saves time and makes the Dashboard easier to use.

Use the mouse to drag on the trackball with the cross-hairs (just above the Stop button). If you drag left, the robot will rotate left; if you drag upwards, the robot will move forwards; and so on. Take a while to get the hang of it. Just be aware that the robot has inertia and will not move until you drag a certain distance away from the centre. Also, it will not stop immediately when you release the mouse button.

Now comes the trick! Drive the robot towards a wall and let it run into the wall. Release the mouse button as soon as it hits the wall and the Intro program will take over. The robot will sense that a bumper has been pressed, and start executing a "behaviour" that makes it move away from walls and wander around.

While the robot is wandering, you will see log messages in the DOS command window. These tell you when the robot detects a bump, and what speed it is setting the motors to. The messages should be self-explanatory.

Changing the Configuration

The first time that you run the program it will create a configuration file in Apps\QUT\Config directory called Intro.Config.xml. You can edit this file to change several parameters that affect the behaviour of the robot.

The following parameters are currently available via the config file:

PropertyDefault Purpose
MotorOntrue Not currently used
ForwardMovesOnlytrue Robot normally drives forward
StopTimeout1500 Time that robot will stop after a collision
BackUpTimeout1000 Time spent backing up after stopping due to collision
TurnTimeout500 Time spent turning after backing up
MinimumDriveTimeout500 Minimum time spent driving forwards
MinimumPower0.2 Minimum motor power
MaximumPower0.6 Maximum motor power
BackUpPower0.4 Motor power while backing up

By adjusting these parameters, you can make the robot faster or slower. Be aware that if you make it too fast it increases the chances that the robot will knock itself over, especially the Lego NXT. Also, the Lego NXT does not have a rear bumper, so it must have ForwardMovesOnly set to true, otherwise it will simply run into a wall backwards and crash.

The timing parameters can be used to change how the robot explores. This is a matter of trial an error. All the timeouts are in milliseconds, i.e. 1000 is one second.

Additional Features

If you are using the Pioneer robot, you can also use the Laser Range Finder, but that is not discussed here. That's something you can play around with on your own. You will see red lines appearing on the walls as the robot moves around. This is the laser. Pretty cool!

The Pioneer robot also has a camera mounted on top. You can switch to the robot view using F8 or by selecting the robocam in the Camera menu. (You can also select the camera in the Dashboard to open a separate WebCam window.) This makes for interesting viewing while the robot is exploring. You will see how much it gets bumped around and also how stupid it is!

Shutting down the Intro

When you get tired of playing, or the robot has crashed, you can stop the program by going back to the DOS Command Prompt window and typing Ctrl-C, i.e. hold down Ctrl and press 'c'. This stops the Dsshost program, and with it all of the associated services that it started. Note that this might take a little while.

If you exit the Simulator or the Dashboard, this will not cause the Intro program to terminate. You must type Ctrl-c, or if you are running the program from the Visual Studio Debugger, then stop debugging.

Changing the Maze

The Intro uses the Maze Simulator. The Maze Simulator reads a bitmap (image) file to decide what the maze looks like. The maze used by default is shown below:

Refer to the Maze Simulator Documentation for details on how to change the maze.

Changing the Robot Type

There are two simulated robots that can be used:
Pioneer 3DX
Lego NXT.

To change which robot is used, you must edit the config file for the Maze Simulator. This should be in the store directory and is called MazeSimulator.Config.xml. Look towards the bottom of the file and change the RobotType to be either Pioneer3DX or LegoNXT (with no spaces in the name).


In Version 1.5 of MSRS there has been a change to the lighting in the Simulator. Consequently the obstacles in the Maze are washed out compared to previous versions. However, the shadows are not as bad now.

Also, there seems to have been a change to the collision detection behaviour. As a result, the robot appears to drive slightly inside the walls. This causes a reaction that sometimes explosively forces the robot away from the wall! I have seen it thrown so hard that it tumbled end over end for several meters. This is clearly not correct, and I have reported the problem to Microsoft.

However, because this program relies on the robot bumping into walls, it will sometimes fall over. If this happens, you can select Edit from the Mode menu and then adjust the Pose of the robot. Or if you can't be bothered, just stop the simulation and start again.

[ Overview ] | [ Tutorial ]