MSRS Code Page Home      MSRS Maze Simulator

Documentation for Maze Simulator

Background

The Maze Simulator creates simple block worlds in the MSRS Simulator using a bitmap image as the template. This template effectively specifies both the height and the colour or texture of the walls or other rectangular objects in your maze. In addition, in the October version, you can have spherical objects.

NOTE: If you are interested in using the Maze Simulator for Line Following, see the Line Following Documentation. However, you need to set up the Maze Simulator first, so you need to continue reading this page.

This page contains basic instructions for using the Maze Simulator 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.

Marking the Walls in the Bitmap Image Template

The background colour in the image is the floor, and other objects are mapped by default to the 16 basic colours that are used in a Windows Paint (BMP) 16-colour image: Black, Red, Lime Green, Yellow, Blue, Magenta, Cyan, White, Light Grey, Dark Grey, Maroon, Dark Green, Olive, Navy, Purple, Cobalt. It is not necessary to use exactly these colours (as you will see from the example below). They just need to be close to the respective colours.

When the Maze Simulator reads the bitmap, it assumes that the top-left pixel is part of the floor and uses this colour to identify the rest of the floor. This pixel does not have to be one of the standard colours, and in fact it should be different from them so that you have all 16 colours available for use.

Your walls cannot go all the way to the edge in the top corner because the top-left pixel identifies the floor colour. However, this is not a problem because the maze will be centered on the origin in the simulated world, so you can put a border around the maze using the floor colour and you won't even notice!

Note that the image can be in any of the standard formats: BMP, GIF, JPG. You can use Microsoft Paint, for example, to draw your maze. In particular, you might want to use the 16-colour mode in Paint. However, in this case, you will lose one colour as the floor colour, i.e. you will only have 15 available for walls.

If you want to change the maze, you can of course edit the program. However, most of the parameters for the program are now available in the saved state file (config file). This allows you to completely reconfigure the maze by just editing an XML file. To use this, copy the file called MazeSimulator.Config.xml (included in the ZIP) to the MSRS "store" directory. (This is under the location where you installed MSRS.)

Colour Mapping

With the default settings, the colours are mapped directly as you would expect, i.e. red becomes red! However, you can change the colour mapping in two different ways: change the values in the config file; or edit the program and recompile. (They are defined in the MazeSimulatorTypes.cs file as part of the MazeSimulatorState class.)

To change the colours using the config file, look for the section called WallColors. This contains a list of 16 Vector3 items. Each of these has X, Y and Z values which actually correspond to Red, Green and Blue (RGB). You can set these values between 0 and 255. So for example, Cobalt Blue is 0, 128, 128.

NOTE: Colour mapping is overridden by Texture Mapping (explained below). You must leave a "blank" in the list of texture files if you want to use a colour instead.

Texture Mapping

A set of texture files is supplied in the images subdirectory under the MazeSimulator directory. You must copy these to your store\media directory under your MSRS root directory.

These texture files give you 16 basic solid colours (although you don't need them because these are the default colours!) If you don't like them, open them in Paint and change the colours. You do not need to use texture files if you only want solid colours -- See the previous section on Colour Mapping.

In addition, there are a couple of actual textures - water, sand, wood. This can also be used to cover your walls and other objects. The CheckerBoard.bmp is a simple black and white checkerboard that is used in the sample config file as the texture for the balls (spheres).

If you want to change the textures that are used for the different colors, you can of course edit the program. However, they are also available in the config file in the WallTextures section. This is a list of nine strings which are the filenames. The default path is the store\media directory.

NOTE: You can leave a texture "blank" by entering an empty string as follows:
<string />
This will allow you to use Colour Mapping instead of a texture. If you don't want any textures, you can actually delete all of the strings in the WallTextures section. The next time you run the program, it will rewrite the file with a set of empty strings.

Height Mapping

The Maze Simulator uses a height table that maps each colour to a (possibly) different height. You can change this table if you edit the code and recompile, or you can simple edit the xml config file. The heights are in the section called HeightMap in the config file. It is a simple list of 16 float values, one for each colour.

Note that if you change the code, you can specify a "height" that is really small, as in 0.01, and the "blocks" will look like patches on the floor. You can also set up a really, really tall blocks, e.g. with a height of 1,000,000.

The updated version for the September CTP had a swimming pool (if you use the supplied config file)! Or is it a pool? Perhaps it's only a mirage. You figure it out!

Note that one of the new features added in the MSRS Simulator in the September CTP was the ability to use a greyscale image as a height field. This is much more sophisticated than this maze simulator. However, the maze simulator is much easier to get started with.

In the October version of the Maze Simulator, I have added more options in the config file that allow you to create spherical objects (see below). "Height" does not really make sense for these objects, so their size is calculated differently. You draw a square or rectangle into the bitmap image of the desired size for the sphere and the program figures out the radius.

Mass Mapping - Changing the Mass of Objects

In previous versions of the program, all the walls had infinite mass (weight). This meant that the robot could not push the walls around, and that is probably what you wanted. However, it is more fun if you can move things around, especially now that you can create spherical objects, i.e. balls! (See below for instructions on creating spheres.)

The config file now contains a section called MassMap. This is similar to the HeightMap and has one value for each of the 16 colours. The mass is in kilograms.

To create a simulation object with infinite mass you actually specify a value of zero for the mass. This is the default value. If you want to move an object around, then you can use small masses like a few kilograms. In the sample config file, the mass for the balls is set to 1 kg.

Note that if you change the mass of a wall, then if might fall over on top of the robot if the robot bumps into it!

Creating Spherical Objects

There is a section in the config file called UseSphere that contains a set of 16 boolean values. If you set one of these to true, then any pixels of the corresponding colour will be used to create spheres instead of walls (blocks).

As noted above under "Height Mapping", the size of spheres is determined by the size of the "blob" in the bitmap image. You probably want to create squares, although the program will use the diagonal size of a rectangle if you the object you create is not square. This size is used to determin the radius of the sphere and it will be placed into the simulation at the center of the square/rectangle.

Selecting a Robot Type

There are two types of simulated robots available:
Pioneer 3DX; and
Lego NXT

To select the type of robot, you need to edit the config file and change the value of RobotType to either Pioneer3DX or LegoNXT (with no spaces). Note that the Pioneer robot has a camera mounted on top, but the Lego robot does not.

Requirements and Installation

To get started, you need to install the Microsoft Robotics Studio on your PC. It is available for free for non-commercial use from Download Site. It requires the .NET 2.0 runtime, which is also available from Microsoft's download site.

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. In that case, you also have .NET 2.0 already installed.

Download the Maze Simulator code using the link on the previous page. Unzip the file into your MSRS root directory. This will create a folder:
<MSRS>\Apps\QUT\MazeSimulator
where <MSRS> is the directory that your copy of MSRS was installed into. In my case this is "C:\Microsoft Robotics Studio (1.5)" which corresponds to the Version 1.5 release. Notice that my MSRS is installed on the 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 Maze Simulator program into <MSRS>\Apps\QUT\MazeSimulator.

How to run the Maze Simulator

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 Maze Simulator 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 should have created a folder in your Start Menu that contains a shortcut for "Microsoft 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/MazeSimulator/MazeSimulator.manifest.xml"
A batch file, called RunMazeSimulator.bat, is included in the ZIP to help make this easier. However, you need to copy this batch file into the MSRS root directory prior to running it.
IMPORTANT NOTE: dsshost.exe is the main control program for MSRS. It is responsible for starting services, i.e. programs like the Maze Simulator. You must run it from the MSRS root directory because it looks for various components starting from the current directory.

Using the Visual Studio Debugger

If you want to rebuild the code, then you must open the Solution in Visual Studio. There are two ways to do this:
From a MSRS Command Prompt window; or
From Windows Explorer.

To open the program from a DOS prompt, select "Microsoft Robotics Studio Command Prompt" from the Start Menu, then start Visual Studio using the following commands:
cd Apps\QUT\MazeSimulator
devenv MazeSimulator.sln

To open the program using Windows Explorer, locate the .sln file which is in the <MSRS>\Apps\QUT\MazeSimulator directory and double-click on it.

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 Maze Simulator program

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

Simulator View - Click for larger image  Dashboard - Click for larger image

The little object in the centre of the Simulation window is the Pioneer robot. This maze world has textured walls and brightly coloured objects. None of them are moveable with the default settings, i.e. they all have infinite mass. This is something you can change in the config file later if you want to be able to push the walls around. However, there are some balls included in the sample config file and you can push them 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 by dragging on the simulation window. 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.

The Simulation Engine allows multiple cameras to be used. You can switch between cameras by pressing the F8 key in the Simulation window, or selecting a camera from the Camera menu.

The Maze Simulator has a camera located on top of the Pioneer robot (although you can't see it). If you select the "robocam" camera from the Camera menu then you will be able to see what the robot sees as it drives around. This is more fun, and it is probably easier to drive the robot this way. A sample view from the robot is shown below:

Robot View - Click for larger image

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 that I have written a modified version of the Dashboard that remembers these settings so you only have to enter them once and then save them. There is another manifest included with the files called MazeSimulator-Dashboard.manifest.xml. If you install my version of the Dashboard you can use this manifest to load it at startup.

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. Drive around for a while to get the feel of the Simulator and the Dashboard.

You can also use a joystick or a game controller to control the robot. It must be compatible with DirectX, but most joysticks are these days. I have tested it using a Logitech Attack 3 USB joystick.

You can also turn on the Laser Range Finder by double-clicking on the simulatedlrf service. You might have noticed red lines appearing on the walls as the robot moves around. This is the laser. Now you will be able to see in the Laser Range Finder panel a representation of what the robot thinks it "sees" using the laser. It does not actually see walls like in the Dashboard, this is just the way it is represented. Remember the laser scan is only in a single horizontal plane at a fixed height off the ground.

Shutting down the Maze Simulator

When you get tired of playing, you can stop the program by going back to the DOS 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.

Alternatively, you can select Exit from the File menu in the Simulator.

Where to from here?

The Maze Simulator on its own is just a toy. The real power comes when you learn how to write programs to control the simulated robot. For that you need to download and install the Intro to Autonomous Robotics program.

You should open the Maze Simulator in Visual Studio and look through it. I have put a lot of comments in the code. The dssnewservice program generated the basic structure. The basic skeleton of the code came from the Microsoft Simulation Tutorials.

Now that you have run the Simulator, I suggest doing the Microsoft Simulation Tutorials.

[ Overview ] | [ Tutorial ]