GearsBot Tutorial

A beginners' guide to programming with gearsbot

By MINT Genie Team (https://mintgenie.de)

Table of contents

How to: Get Started

Visit https://gears.aposteriori.com.sg/

This is a programming environment we can use to prepare for the competition.

File types:

We will be working with different types of files here and we will learn about them as we go along:

  • Programs - XML file

  • Robots - JSON file

  • Worlds/Mats - JSON file

How to: Use the “Blocks” tab

This is very similar to makecode block programming. However some of the features are limited. We will learn how to use it during our sessions.

To save and load programs:

  • Give a proper name to the program

  • Once you make changes, you can save blocks to your computer (it is not saved online). The file is saved as an XML file

  • To Load your programs again or to load sample programs, click on “Load blocks…” and select the xml file.

  • Use this xml file to share assignments

How to: The “Simulator” tab

  • If you click on the “Simulator” tab, you should see the view as this:

  • The “Follow” option on the right corner controls the camera (this should be default)

  • The “Sensors” options lists the values read by the sensors and also the shows which ports the sensors are connected to.

  • Reset” option places the robot back on the default location and stops everything

  • World” option is the choose the table type. The default here is “Grid”

  • Play” icon option on the left most side of the screen is used for running the program. Note: Stopping it will not stop the robot if it is moving

  • Scale” icon option shows the measurements and also position of cursor on the screen

  • To change the viewing angle: Place the mouse cursor somewhere near the Click and hold left mouse button and move the mouse:

    • moving left/right will change the view in sideways direction

    • Moving up/down will change view from above or under the table.

Download Learning Package

Download all the files needed with this userguide

How to: Load Custom Worlds

To Change the world:

  • Click on the “World” option in simulator

  • Choose different listed worlds and challenges (these are built-in options)

  • Click “Ok” to load it

To load custom worlds

  • Download the json-file provided by the MINT Genie Team (do not copy text, download it by clicking on the download icon or the 3 dots at top right corner.)

  • These have “Mat” in the filename for reference.

  • Select “Generate from Image” in the Select World menu

  • Click on “Load”, select the downloaded json-file

  • Click “Ok

How to: Robot setup

Load built-in Robots:

  • Click on the “Robot” menu option and click “Select Robot

  • Choose different listed Robots (these are built-in options)

  • Click “Ok” to load it

Load Custom Robots:

  • Download the Robot file with a .JSON extension to your computer

    • Example: RoboCompete_MainRobot.json

  • Click on the “Robot” Menu icon, click “Load from file” and select the downloaded “RoboCompete_MainRobot.json” and open it.

Robot features:

In the “Simulator” tab, click on “Sensors” to check where the motors and sensors are connected

  • All available sensors are connected to some input port and named with “in#” - where # is the port number.

  • All Motors are connected to Output ports and named with “outX” - where X is the port letter.

  • Note that when using an electromagnet, the motor is not listed in the sensor list. (it is the next available Out-port). However, this can still be verified in the Python tab.

How to: Move around

Robot (built-in): “Single Sensor Line Follower” - Default

World (built-in): “Grid”

Sensor/Actuator port: OutA, OutB - Motors


The Wheel motors can be moved together as a tank or separately.

  • The blocks in “Motion” group is used to control both the left and right wheel motors together.

  • The blocks in “Motor” group is used to control individual motors and also read the current speed and position of motors

  • Unless you specify the amount of rotation, the motors will keep running. You will have to stop it with the Stop block

  • Watch the reading of Motors/Actuator in the sensor window to see the how many degrees it has rotated.

  • We will learn usage of Motor group in upcoming examples.

How to: Draw and Print

Robot (built-in): “Single Sensor Line Follower” - Default

World (built-in): “Grid”


Drawing with Pen:

A pen can be added to draw where the robot is moving.

  • Just add the pen block into the program, start and stop drawing using the blocks in “Pen” group.

  • The color of the ink can also be changed.

Print Text :

Information can be printed to show value of variables in the console.

  • Text can be manipulated using blocks in the “Text” group.

  • Use the “Print” block to print variables, messages, or sensor values.

How to: Move, Draw and Print example

GearsBot - Motor_draw_print.mp4

How to: Rotation using Gyro

Robot (built-in): “Double Sensor Line Follower”

World (built-in): “Grid”

Sensor port: In4 - Gyro sensor


The Gyro sensor gives the orientation of the Robot.

  • It is possible to check if the robot has turned by a certain amount.

  • When drawing a square with a Pen on the Robot, it is necessary to keep reading the gyro when turning to make sure, we are not deviating too much.

    • We start by moving forward for 4 seconds

    • Now we determine how much we should turn - thats 90 deg for a square

    • Till the gyro angle is less than the target angle we SLOWLY turn the robot

    • The repeat block exits as soon as the gyro value is more than target, so we stop immediately and print the value.

    • We repeat the above steps 4 times as we want to draw a square

  • It is ok to deviate a little - this is normal.

  • Watch the reading of Gyro sensor in the sensor window to see the orientation.

GearsBot - Gyro test.mp4

How to: Avoid obstacles

Robot (built-in): “Double Sensor Line Follower”

World JSON file:Practice_mat_Obstacles.json

Sensor port: In3 - Ultrasonic sensor


The ultrasonic sensor is used to detect obstacles

  • Read the sensor continuously in a loop and when there is an obstacle close by then, move robot in a different direction

  • Also note the use of “Move Steering” block, the direction can be between -100 and +100 and the speed in percent.

  • Try different values for sensor and check behavior.

  • Watch the reading of distance in the sensor window to see the how far away the obstacle is.

How to: Follow a line

Robot (built-in): “Double Sensor Line Follower”

World (built-in): Line following Challenges - Simple Curves

Sensor port: In1, In2 - Color and Line Sensors


The color sensor can recognize both lines and colors.

  • Here sensor 1 is on the left and sensor 2 is on the right

  • If the intensity of sensor 1 reduces below 85; it means that left sensor is closer to the line

    • We should move the right motor forward and left motor backward to center the robot on the line again.

  • If the intensity of sensor 2 reduces below 85, it means that the right sensor is closer to the line

    • We should move the left motor forward and right motor backward to center the robot on to the line again.

  • If neither sensors are reporting less intensity, it means that they are seeing the white area and can continue.

  • Watch the reading of color sensor intensity in the sensor window.

  • Try to move slowly to get it working, also try with other challenges in this world (click select challenges in “World”

GearsBot - Line follow.mp4

How to: Recognize colors

Robot JSON file:RoboCompete_MainRobot.json

World JSON file:Practice_mat_colors.json

Sensor port: In1, In2 - Color and Line sensors

  • The color sensor can recognize both lines and colors.

  • It can also detect a few colors by name

    • (Red, White, Blue, Black, Green & Yellow)

  • In our example here,

    • Create and variable called “Color_found” and initialize it to“Null”

    • Set the Robot to move with 15% speed

    • In a loop keep checking if the color changed and if yes then try to recognize the color.

    • The first color it sees will be different so it will go into the “if” block

    • Save that color name to “Color_found” variable and print it

    • Stop the motor and also the program if Black is found.

    • If not Black then on next time it checks if the color sensors reports same or different - if same, then does nothing

  • Some colors have unique numbers, find them using this block and print them:

    • Note that you have to initialize “Color_found” to a number if you want to show the color number instead of name

GearsBot - Color detect.mp4

How to: Swing the Arm

Robot JSON file:RoboCompete_MainRobot.json

Sensor/Actuator port: OutC - Swivel Actuator


The arm of the robot can be made to swing left or right or even go around

  • Control the individual motor by using blocks in the “Motor” block group.

  • Note: The blocks in the “Motion” group usually control only wheel motors only.

  • Our program just moves the ARM to a specific position, waits for a second and moves to another position and keeps repeating.

  • Try different values for degrees. 360 moves the Arm for 1 full circle. Giving values more than 360 will make the arm turn multiple times.

  • Try to make it turn 2.5 circles.

  • Watch the position value of the motor in the sensor window to see the current position.

GearsBot - Swivel Arm test.mp4

How to: Lifting the Arm

Robot JSON file:RoboCompete_MainRobot.json

Sensor/Actuator port: OutD - Arm Actuator


The arm of the robot can be made to go up and down (0 - 180 degrees)

  • Control the individual motor by using blocks in the “Motor” block group.

  • Our program just moves the ARM to a specific position, waits for a second and moves to another position at a different speed, returns back at different speed and keeps repeating.

  • Try different values for degrees and speed. Give values between 0 and 180 only

  • Watch the position value of the motor in the sensor window to see the current position.

GearsBot - Lift arm test.mp4

How to: Pick up objects

Robot JSON file: RoboCompete_MainRobot.json

World JSON file:Practice_mat_magnets.json

Sensor/Actuator port: OutE - Electromagnet


An electromagnet can be turned off and on with different strengths (in our case motor % - 100% is max power and 0 is OFF)

  • This mat has some magnetic objects added.

  • Control the individual motor by using blocks in the “Motor” block group.

  • Our program moves ARM near an object, enables electromagnet, lifts arm, moves arm to different position, turns off electromagnet to drop the object and returns the arm starting position

  • Try different values for electromagnet power %.

  • Move closer to different objects and pick them up. Try to drop them outside the table for Fun!!!

  • Moving arm very fast can throw magnetic objects, so try to move arm slowly

GearsBot - Electromagnet.mp4