The software for this project is actually included in the Adafruit CircuitPython MotorKit library examples.  There's a script that tells the robot to move forward, backward, and turn in different directions.  This script uses a little helper class in that talks to the motor HAT and exposes simple functions to move the robot.

Make sure you've followed the motor HAT guide software installation.

Download Example Files

The installation of the library does not include the examples. So you will want to grab those manually. You can use the links below to download them. Be sure to save both of these into the same directory.

You can also download the files directly to your device using wget:


Run Example

To run the robot code first make sure the 4x AA battery pack connected to the motor HAT is powered on.  Then place the robot on the floor where there are no obstructions around it for a few feet.  Remember this is a simple robot that has no sensors to know if it's hitting something or about to fall off a table!  Be very careful to ensure the path of the robot is free and safe to travel!

When the script runs it will instruct the robot to move. So make sure the coast is clear. When you've ensured the path of the robot is clear run the following command to run the robot code:


Be ready to pick up the bot or flip off its motor power supply in case it comes close to hitting something or falling!

Woo hoo, you should see the robot start to move around!  If you see an error message check that you've followed all of the steps above and in the motor HAT guide to install the software.  Try testing each motor individually with the motor HAT guide DC motor test software to make sure they can spin.

Note that if the robot spins instead of moving forward you likely have the motors connected incorrectly.  Try swapping the order of the connections and testing again.  You can flip the robot over and watch the wheels move to check that they both move in the same direction when moving forward, and they move in opposite directions when turning.


The example is very simple. The real fun comes from writing code to make the robot do what YOU want. Start by making a copy of the script and open it in an editor, like nano.

Open your script in a text editor and look for these lines:

robot.left(0.5, 1)
robot.right(0.5, 1)
robot.steer(0.5, 0.2)
robot.stop()  # Stop the robot from moving.

Those are the basic move commands. You can change those up as you want. Add more, etc.

As described in the code comment above them, each takes two parameters. The first one is the speed of the movement.  Speed should be a value between 0 and 255.  The higher the value the faster the movement.  Note that you'll need to start with a value around 75-100 or so to move the motors with enough torque to get the robot started.

The second parameter is the amount of time (in seconds) to perform the action.  For example a call to robot.forward(150, 1.0) will move the robot forward at a speed of 150 for 1.0 second.

Another way to use the functions is to just pass the first parameter, the speed, to them.  This will start the robot moving and then return to your script so you can do other things. For example:

# Spin in place slowly for a few seconds.
robot.right(100)  # No time is specified so the robot will start spinning forever.
time.sleep(2.0)   # Pause for a few seconds while the robot spins (you could do
                  # other processing here though!).
robot.stop()      # Stop the robot from moving.

In the snippet above the robot will start spinning to the right at a speed of 100, then the code will sleep for 2 seconds, and finally stop the robot.  Instead of sleeping you could perform other actions though, like reading sensors, talking to web services, etc--the sky is the limit as far as what you can do with the robot & Python code!

This guide was first published on Jan 08, 2016. It was last updated on Apr 09, 2024.

This page (Software) was last updated on Apr 08, 2024.

Text editor powered by tinymce.