https://github.com/mackorone/mms

A Micromouse simulator: write and test maze-solving code without a physical robot
https://github.com/mackorone/mms

algorithm ieee maze micromouse micromouse-simulator robot simulator

Last synced: 26 days ago
JSON representation

A Micromouse simulator: write and test maze-solving code without a physical robot

Host: GitHub
URL: https://github.com/mackorone/mms
Owner: mackorone
License: mit
Created: 2013-11-29T22:36:30.000Z (over 11 years ago)
Default Branch: main
Last Pushed: 2024-01-06T21:13:26.000Z (over 1 year ago)
Last Synced: 2024-08-01T22:44:55.895Z (9 months ago)
Topics: algorithm, ieee, maze, micromouse, micromouse-simulator, robot, simulator
Language: C++
Homepage:
Size: 14.1 MB
Stars: 368
Watchers: 25
Forks: 82
Open Issues: 11
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

# mms

![](img/mms.gif)

## Table of Contents

1. [Introduction](https://github.com/mackorone/mms#introduction)
1. [Download](https://github.com/mackorone/mms#download)
1. [Quick Start](https://github.com/mackorone/mms#quick-start)
1. [Mouse API](https://github.com/mackorone/mms#mouse-api)
1. [Scorekeeping](https://github.com/mackorone/mms#scorekeeping)
1. [Cell Walls](https://github.com/mackorone/mms#cell-walls)
1. [Cell Color](https://github.com/mackorone/mms#cell-color)
1. [Cell Text](https://github.com/mackorone/mms#cell-text)
1. [Reset Button](https://github.com/mackorone/mms#reset-button)
1. [Maze Files](https://github.com/mackorone/mms#maze-files)
1. [Building From Source](https://github.com/mackorone/mms#building-from-source)
1. [Related Projects](https://github.com/mackorone/mms#related-projects)
1. [Citations](https://github.com/mackorone/mms#citations)
1. [Acknowledgements](https://github.com/mackorone/mms#acknowledgements)

## Introduction

*mms* is a Micromouse simulator.

It makes it easy to write and test maze-solving code without a physical robot.

With it, you can:

* Test how your robot would behave in a real maze
* Visualize what your robot is thinking
* Show known/unknown walls
* Set the color of the cells
* Display ASCII text on the cells
* Simulate a crash-and-reset scenario
* Test your algorithm on custom maze files
* Write code in any language you want

Previous versions of *mms* exist in the `old/` directory.

For information about Micromouse, see the [Micromouse Wikipedia page](http://en.wikipedia.org/wiki/Micromouse).

## Download

You can download pre-compiled binaries from the
[releases](https://github.com/mackorone/mms/releases) page.

- Linux: Download and unzip `linux.zip` and run `mms-x86_64.AppImage`
- macOS: Download and unzip `macos.zip` and run `mms.app`
- Windows: Download and unzip `windows.zip` and run `mms/mms.exe`

If pre-compiled binaries for your platform are unavailable, you'll have to
[build from source](https://github.com/mackorone/mms#building-from-source).

> [!IMPORTANT]
> The macOS version fails with the following error:
> > "mms.app" is damaged and can’t be opened. You should move it to the Trash.
>
> To get past the error, manually remove the quarantine attribute:
> ```
> xattr -d com.apple.quarantine mms.app
> ```

> [!NOTE]
> On Windows, you may get a warning like:
> > Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk.
>
> To get past that warning, click "More info" and then "Run anyway."

## Quick Start

Writing a Micromouse algorithm is easy! Here are some available templates:

If a template for a particular language is missing, don't fret! Writing your
own template is as easy as writing to stdout, reading from stdin, and
implementing the [mouse API](https://github.com/mackorone/mms#mouse-api) below.
If you have a template you'd like to share, please make a pull request!

## Mouse API

Algorithms communicate with the simulator via stdin/stdout. To issue a command,
simply print to stdout. To read a response, simply read from stdin. All valid
commands are listed below. Invalid commands are simply ignored.

For commands that return a response, it's recommended to wait for the response
before issuing additional commands.

#### Summary

```c++
int mazeWidth();
int mazeHeight();

bool wallFront(int numHalfSteps = 1);
bool wallRight(int numHalfSteps = 1);
bool wallLeft(int numHalfSteps = 1);
bool wallBack(int numHalfSteps = 1);

// Both of these commands can result in "crash"
void moveForward(int distance = 1);
void moveForwardHalf(int numHalfSteps = 1);

void turnRight();
void turnLeft();
void turnRight45();
void turnLeft45();

void setWall(int x, int y, char direction);
void clearWall(int x, int y, char direction);

void setColor(int x, int y, char color);
void clearColor(int x, int y);
void clearAllColor();

void setText(int x, int y, string text);
void clearText(int x, int y);
void clearAllText();

bool wasReset();
void ackReset();

int/float getStat(string stat);
```

#### `mazeWidth`
* **Args:** None
* **Action:** None
* **Response:** The height of the maze

#### `mazeHeight`
* **Args:** None
* **Action:** None
* **Response:** The width of the maze

#### `wallFront [N]`
* **Args:**
* `N` - (optional) Check for a wall this many half-steps away, default `1`
* **Action:** None
* **Response:** `true` if there is a wall, else `false`

#### `wallRight [N]`
* **Args:** None
* `N` - (optional) Check for a wall this many half-steps away, default `1`
* **Action:** None
* **Response:** `true` if there is a wall, else `false`

#### `wallLeft [N]`
* **Args:** None
* `N` - (optional) Check for a wall this many half-steps away, default `1`
* **Action:** None
* **Response:** `true` if there is a wall, else `false`

#### `wallBack [N]`
* **Args:** None
* `N` - (optional) Check for a wall this many half-steps away, default `1`
* **Action:** None
* **Response:** `true` if there is a wall, else `false`

#### `moveForward [N]`
* **Args:**
* `N` - (optional) The number of full steps to move forward, default `1`
* **Action:** Move the robot forward the specified number of full-steps
* **Response:**
* `crash` if `N < 1` or the mouse cannot complete the movement
* else `ack` once the movement completes

#### `moveForwardHalf [N]`
* **Args:**
* `N` - (optional) The number of half steps to move forward, default `1`
* **Action:** Move the robot forward the specified number of half-steps
* **Response:**
* `crash` if `N < 1` or the mouse cannot complete the movement
* else `ack` once the movement completes

#### `turnRight` or `turnRight90`
* **Args:** None
* **Action:** Turn the robot ninty degrees to the right
* **Response:** `ack` once the movement completes

#### `turnLeft` or `turnLeft90`
* **Args:** None
* **Action:** Turn the robot ninty degrees to the left
* **Response:** `ack` once the movement completes

#### `turnRight45`
* **Args:** None
* **Action:** Turn the robot forty-five degrees to the right
* **Response:** `ack` once the movement completes

#### `turnLeft45`
* **Args:** None
* **Action:** Turn the robot forty-five degrees to the left
* **Response:** `ack` once the movement completes

#### `setWall X Y D`
* **Args:**
* `X` - The X coordinate of the cell
* `Y` - The Y coordinate of the cell
* `D` - The direction of the wall: `n`, `e`, `s`, or `w`
* **Action:** Display a wall at the given position
* **Response:** None

#### `clearWall X Y D`
* **Args:**
* `X` - The X coordinate of the cell
* `Y` - The Y coordinate of the cell
* `D` - The direction of the wall: `n`, `e`, `s`, or `w`
* **Action:** Clear the wall at the given position
* **Response:** None

#### `setColor X Y C`
* **Args:**
* `X` - The X coordinate of the cell
* `Y` - The Y coordinate of the cell
* `C` - The character of the desired [color](https://github.com/mackorone/mms#cell-color)
* **Action:** Set the color of the cell at the given position
* **Response:** None

#### `clearColor X Y`
* **Args:**
* `X` - The X coordinate of the cell
* `Y` - The Y coordinate of the cell
* **Action:** Clear the color of the cell at the given position
* **Response:** None

#### `clearAllColor`
* **Args:** None
* **Action:** Clear the color of all cells
* **Response:** None

#### `setText X Y TEXT`
* **Args:**
* `X` - The X coordinate of the cell
* `Y` - The Y coordinate of the cell
* `TEXT` - The desired [text](https://github.com/mackorone/mms#cell-text), max length 10
* **Action:** Set the text of the cell at the given position
* **Response:** None

#### `clearText X Y`
* **Args:**
* `X` - The X coordinate of the cell
* `Y` - The Y coordinate of the cell
* **Action:** Clear the text of the cell at the given position
* **Response:** None

#### `clearAllText`
* **Args:** None
* **Action:** Clear the text of all cells
* **Response:** None

#### `wasReset`
* **Args:** None
* **Action:** None
* **Response:** `true` if the reset button was pressed, else `false`

#### `ackReset`
* **Args:** None
* **Action:** Allow the mouse to be moved back to the start of the maze
* **Response:** `ack` once the movement completes

#### `getStat`
* **Args:**
* `stat`: A string representing the stat to query. Available stats are:
* `total-distance (int)`
* `total-turns (int)`
* `best-run-distance (int)`
* `best-run-turns (int)`
* `current-run-distance (int)`
* `current-run-turns (int)`
* `total-effective-distance (float)`
* `best-run-effective-distance (float)`
* `current-run-effective-distance (float)`
* `score (float)`
* **Action:** None
* **Response:** The value of the stat, or `-1` if no value exists yet. The value will either be a float or integer, according to the types listed above.

#### Example

```c++
Algorithm Request (stdout) Simulator Response (stdin)
-------------------------- --------------------------
mazeWidth 16
mazeWidth 16
wallLeft true
setWall 0 0 w
wallFront false
moveForward ack
turnLeft ack
wallFront true
moveForward crash
setColor 0 1 r
setText 0 1 whoops
wasReset false
...
wasReset true
clearAllColor
clearAllText
ackReset ack
```

## Scorekeeping

The Stats tab displays information that can be used to score an algorithm's
efficiency. This tab displays stats such as the total distance and total number
of turns. It also displays the distance and number of turns for the algorithm's
best start-to-finish run, if the algorithm makes multiple runs from the start
tile to the goal. The distance and number of turns for the current
start-to-finish run is also displayed.

There is another value displayed, called Effective Distance. This number may
differ from Distance if `moveForward` is called with the optional distance
parameter. If `moveForward` is called with an integer greater than 2, each tile
after the second tile will add only half a point to the effective distance. This
simulates a mouse driving faster if it can drive in a straight line for more
than a few tiles. For example, `moveForward(5)` will increase the distance by 5
but will increase the effective distance by only 3.5. A mouse will incur a
15-point penalty on its next run's Effective Distance if it uses `ackReset` to
return to the start tile.

A final score is computed for the algorithm after it terminates. A lower score
is better. The final score depends on the best start-to-finish run and on the
overall run, according to the following equation.

`score = best run turns + best run effective distance + 0.1 * (total turns +
total effective distance)`

The mouse must reach the goal to receive a score. If the mouse never reaches the
goal, the score will be 2000.

## Cell Walls

Cell walls allow the robot to diplay where it thinks walls exist, and where it
thinks they don't. At the beginning of each run, all walls are assumed
non-existent. By default, the simulator will display walls that haven't been
discovered as dark red. As the robot explores the maze, it should set walls
as it discovers them.

## Cell Color

The available colors are as follows:

| Char | Color |
|------|-------------|
| k | Black |
| b | Blue |
| a | Gray |
| c | Cyan |
| g | Green |
| o | Orange |
| r | Red |
| w | White |
| y | Yellow |
| B | Dark Blue |
| C | Dark Cyan |
| A | Dark Gray |
| G | Dark Green |
| R | Dark Red |
| Y | Dark Yellow |

## Cell Text

[All printable ASCII characters](http://facweb.cs.depaul.edu/sjost/it212/documents/ascii-pr.htm),
except for ``, can be used as cell text. Any invalid characters, such as a
newline or tab, will be replaced with `?`.

When no algorithm is running, the simulator displays the distance of each cell
from the center of the maze.

## Reset Button

The reset button makes it possible to test crash handling code. Press the
button to simulate a crash. Your algorithm should periodically check if the
button was pressed via `wasReset`. If so, your algorithm should reset any
internal state and then call `ackReset` to send the robot back to the beginning
of the maze.

## Maze Files

The simulator supports a few different maze file formats, as specified below.
If your format isn't supported, feel free to put up a pull request.

Note that, in order to use a maze in the simulator, it must be:

* Nonempty
* Rectangular
* Fully enclosed

Also note that official Micromouse mazes have additional requirements:

* No inaccessible locations
* Exactly three starting walls
* Only one entrance to the center
* Has a hollow center, i.e., the center peg has no walls attached to it
* Has walls attached to every peg except the center peg
* Is unsolvable by a wall-following robot

Here are some links to collections of maze files:
* [micromouseonline/mazefiles](https://github.com/micromouseonline/mazefiles)
* http://www.tcp4me.com/mmr/mazes/

#### Map format

Example:

+---+---+---+
| | |
+ + + +
| | |
+---+---+---+

* Each cell is 5 spaces wide and 3 spaces tall
* All characters besides spaces count as walls
* Walls are determined by checking the locations marked with an "x":

```
+ x +
x x
+ x +
```

#### Num format

Format:

X Y N E S W

* **X:** The X coordinate of the cell
* **Y:** The Y coordinate of the cell
* **N:** `1` if there is a wall on the north side, else `0`
* **S:** `1` if there is a wall on the east side, else `0`
* **E:** `1` if there is a wall on the south side, else `0`
* **W:** `1` if there is a wall on the west side, else `0`

Example:

0 0 0 1 1 1
0 1 1 0 0 1
1 0 0 0 1 1
1 1 1 1 0 0
2 0 0 1 1 0
2 1 1 1 0 1

Result:

+---+---+---+
| | |
+ + + +
| | |
+---+---+---+

## Building From Source

If you want to write code for the simulator itself, you'll need to build the
project from source. Below are some OS-specific instructions. If instructions
for your platform are unavailable, you can probably still run the simulator,
you'll just have to figure it out on your own for now.

#### Windows

Install Qt:

1. Download the Qt open source installer: https://www.qt.io/download-qt-installer-oss
1. If you don't already have a Qt account, you'll need to make one
1. When prompted to select components, [choose "MinGW"](https://github.com/mackorone/mms/blob/master/img/qt-install-windows-1.png)

Build the project using QtCreator:

1. Download or clone *mms*
1. Run QtCreator and open `mms/src/mms.pro`
1. Configure the project to [use "MinGW"](https://github.com/mackorone/mms/blob/master/img/qt-install-windows-2.png)
1. Build and run the project

#### macOS

Install Xcode: https://developer.apple.com/xcode/

Install Qt:

1. Download the Qt open source installer: https://www.qt.io/download-qt-installer-oss
1. If you don't already have a Qt account, you'll need to make one
1. When prompted to select components, [choose "macOS"](https://github.com/mackorone/mms/blob/master/img/qt-install-macos-1.png)

Build the project using QtCreator:

1. Download or clone *mms*
1. Run QtCreator and open `mms/src/mms.pro`
1. Configure the project to [use "clang 64bit"](https://github.com/mackorone/mms/blob/master/img/qt-install-macos-2.png)
1. Build and run the project

#### Linux (Ubuntu)

Install Qt:

1. Download the Qt open source installer: https://www.qt.io/download-qt-installer-oss
1. Make the installer executable: `chmod +x qt-unified-linux-x64-3.0.6-online.run`
1. Run the installer executable: `./qt-unified-linux-x64-3.0.6-online.run`
1. If you don't already have a Qt account, you'll need to make one
1. When prompted to select components, [choose "Desktop gcc 64-bit"](https://github.com/mackorone/mms/blob/master/img/qt-install-ubuntu.png)
1. Once the installer finishes, the `qmake` binary can be found in the installation directory

Clone, build, and run the project:

```bash
# Clone the repo
git clone [email protected]:mackorone/mms.git

# Build the simulator
cd mms/src
qmake && make

# Run the simulator
../../bin/mms
```

## Related Works

Feel free to open a pull request if you want your work listed here!

#### Projects

- [@zdasaro](https://github.com/zdasaro) wrote a proxy for the Priceton University Robotics Club: [mms-competition-proxy](https://github.com/zdasaro/mms-competition-proxy)
- [@P1n3appl3](https://github.com/P1n3appl3) created an Arch Linux package: [mms-git](https://aur.archlinux.org/packages/mms-git/)

#### Papers

-
-
-

#### Posts

-
-
-
-
-

#### Videos

-
-
-

#### Repos

-
-
-
-
-
-
-

## Acknowledgements

| Name | Author | Used For |
|---------------------------------------------------------------|-------------------|-----------------------|
| [polypartition](https://github.com/ivanfratric/polypartition) | Ivan Fratric | Polygon Triangulation |
| [Qt](https://www.qt.io/) | The Qt Company | Framework and GUI |

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/mackorone/mms

Awesome Lists containing this project

README