ProMRDS Home Page Maze Simulator

Professional
   Microsoft Robotics Developer Studio
Home Page Book Contents This Chapter

Documentation for Maze Simulator

Background

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

This page contains basic instructions for using the Maze Simulator program. Please read through the whole page before you attempt to use it. Most of your questions should be answered by this page.

To change the way that the Maze Simulator works, you edit the config file which is:
ProMRDS\Config\MazeSimulator.Config.xml
Most of the settings should be self-explanatory. However, the following sections describe them in more detail.

Marking the Walls in the Bitmap Image Template

The default maze bitmap is called ModelLarge.bmp and should look basically like the picture below.

Default Model

The dark grey background color in the image is the floor, and other objects are mapped by default to the 16 basic colors that are used in a Windows Paint (BMP) 16-color 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 colors (as you can see from the example above). They just need to be close to the respective colors.

When the Maze Simulator reads the bitmap, it assumes that the top-left pixel is part of the floor and uses this color to identify the rest of the floor. This pixel does not have to be one of the standard colors, and in fact it should be different from them so that you have all 16 colors 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 color. 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 color 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-color mode in Paint. However, in this case, you will lose one color as the floor color, 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 available in the saved state file (config file). This allows you to completely reconfigure the maze by just editing an XML file. The file called MazeSimulator.Config.xml (included in the package) is located in the ProMRDS\Config folder. (This is under the location where you installed MRDS.)

The name of of the maze bitmap file is in the Maze attribute, e.g.
<Maze>\ProMRDS\Chapter9\MazeSimulator\ModelLarge.bmp</Maze>
Notice that the path starts with a backslash. This means that the path begins in the <MRDS> root directory.

Alternatively, you can just enter a filename and then place the file in the <MRDS>\store\media\Maze_Textures folder. (In this case, the filename must not begin with a backslash.)

Ground Texture

The texture filename that is used for the ground can be specified. Note that this file must be in the store\media folder, or a subdirectory of this.

Color Mapping

With the default settings, the colors are mapped directly as you would expect, i.e. red becomes red! However, you can change the color 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 colors 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: Color 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 color 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 MRDS root directory.

These texture files give you 16 basic solid colors (although you don't need them because these are the default colors!) If you don't like them, open them in Paint and change the colors. You do not need to use texture files if you only want solid colors -- See the previous section on Color 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 Color 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 color 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 color.

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. (See the Line Following example). You can also set up a really, really tall blocks, e.g. with a height of 1,000,000.

There is an overall scale factor applied to the heights called HeightScale.

The blue area in the corner of the default model is 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 the Simulator can 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.

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 colors. 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 color will be used to create spheres instead of walls (blocks).

"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.

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.

Spheres have their own scaling factor called SphereScale.

NOTE: If you want your spheres to bounce like balls, then you might have to adjust the Bounce Threshold (see below).

Camera Pose

The camera on the simulated Pioneer can be moved and tilted. The position of the camera is specified relative to the center of the robot. The camera tilt is given as an angle of rotation about the X axis. The following example is for line following and has the camera moved forwards (Z = -0.5) and tilted down (-85 degrees):
<CameraPosition>
  <X xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html">0</X>
  <Y xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html">0.5</Y>
  <Z xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html">-0.5</Z>
</CameraPosition>
<CameraTiltAngle>-85</CameraTiltAngle>

NOTE: If you inadvertently wipe the config, then the position will default to all zeros. When you look at the robocam you will have a strange view from out underneath the robot.

Grid Size

There are two parameters that affect the grid that is used for the walls: WallBoxSize and GridSpacing. The WallBoxSize is usually set to 0.98 or 0.99. This means that a pixel in the bitmap occupies almost an entire cell. If you make it much smaller than this, then the walls will not join at the corners. However, if you set it to 1.0 then the walls might blow apart when the simulation begins due to small roundoff errors that make the Simulator think the walls have collided.

The GridSpacing is a scale factor that adjusts the size of the cells. Each pixel in the bitmap is a cell, so typically the GridSpacing might be 0.1 (100cm) or even 0.01 (10cm).

Bounce Threshold

The BounceThreshold parameter specifies the "bounciness" of surfaces in the simulation. Unfortunately, if you wipe the config this will default to zero, which is VERY bouncy. The actual default in the Simulator is -2, which is pretty dead. To get a reasonable bounce, try -0.25.

Robot Starting Position

The initial position of the robot can be specified in terms of the grid cells that make up the maze. There are two parameters: RobotStartCellRow and RobotStartCellCol.

Each pixel in the bitmap corresponds to a cell, scaled by the GridSpacing parameter. The origin is in the middle of the bitmap, so usually a setting of (0,0) will be OK.

NOTE: If you put the robot inside a wall, when the simulation starts it will be explosively expelled from the wall! It might go flying up in the air, and almost certainly will land on its side.

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 package from the ProMRDS web site. It is a DssDeploy self-extracting executable file. When you run it, it will automatically copy all the files into your MRDS root directory. This will create a folder:
<MRDS>\ProMRDS\Chapter9\MazeSimulator
where <MRDS> is the directory that your copy of MRDS was installed into. The default is "C:\Microsoft Robotics Studio (1.5)" which corresponds to the Version 1.5 release. Notice that MRDS 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.

IMPORTANT NOTE: In the explanations that follow it is assumed that the Maze Simulator is installed into <MRDS>\ProMRDS\Chapter9\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 package and they will be copied to your bin directory during installation.

As with all MRDS programs, you need to start the Maze Simulator from a MRDS 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 MRDS Service

When you installed MRDS, 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:"ProMRDS/Config/MazeSimulator.manifest.xml"
A batch file, called RunMazeSimulator.cmd, is included in the package to help make this easier. It is located in the <MRDS>\bin folder.
IMPORTANT NOTE: dsshost.exe is the main control program for MRDS. It is responsible for starting services, i.e. programs like the Maze Simulator. You must run it from the MRDS 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 MRDS 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 ProMRDS\Chapter9\MazeSimulator
devenv MazeSimulator.sln

To open the program using Windows Explorer, locate the .sln file which is in the <MRDS>\ProMRDS\Chapter9\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 MRDS installation is not on the C: drive.

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 colored 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 Webcam View

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 the modified version of the Dashboard remembers these settings so you only have to enter them once and then save them.

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 Explorer Simulation program.

You should open the Maze Simulator in Visual Studio and look through it. A lot of comments have been added to 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, we suggest that you do the Microsoft Simulation Tutorials.

[ Overview ] | [ Tutorial ]