The software for this project is actually included in the motor HAT 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.  As a quick summary you'll need to connect to a terminal on the Pi and first enable I2C on the Pi.  Then run the following commands to download dependencies and install the motor HAT software & examples:

Download: file
sudo apt-get update
sudo apt-get install build-essential python-dev python-smbus git
cd ~
git clone
cd Adafruit-Motor-HAT-Python-Library
sudo python install

After the software is installed the robot code will be in the examples subdirectory, change to that folder by running:

Download: file
cd examples

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 forward a few inches, turn to the left, move forward again a few inches, turn to the left etc.  Then it will spin in place to the right for a few seconds, and finally move backwards, turn right, move backwards, etc. a few times.  When you've ensured the path of the robot is clear run the following command to run the robot code:

Download: file
sudo python

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.

You can edit the script to control how the robot moves.  This is just a very simple script that moves the robot in a fixed pattern.  You can add much more complex logic to control your robot however you desire.

Open the script in the nano text editor by running:

Download: file

I'll walk through the code and explain it in more detail below.

Download: file
# Simple two DC motor robot class usage example.
# Author: Tony DiCola
# License: MIT License
import time

# Import the file (must be in the same directory as this file!).
import Robot

First the script imports a few Python dependencies.  The time library has a useful sleep function that can pause the execution of the script (kind of like the delay function in Arduino).  

The import Robot line tells the script to import a Python module called Robot.  This module is located in the same directory as the script and is called  You can look at the code later to see how it interfaces with the motor HAT.  For the example code here we'll use the class inside to control our robot.

Note that if you want to write your own script that uses the class make sure to copy into the same folder as your script!

Download: file
# Set the trim offset for each motor (left and right).  This is a value that
# will offset the speed of movement of each motor in order to make them both
# move at the same desired speed.  Because there's no feedback the robot doesn't
# know how fast each motor is spinning and the robot can pull to a side if one
# motor spins faster than the other motor.  To determine the trim values move the
# robot forward slowly (around 100 speed) and watch if it veers to the left or
# right.  If it veers left then the _right_ motor is spinning faster so try
# setting RIGHT_TRIM to a small negative value, like -5, to slow down the right
# motor.  Likewise if it veers right then adjust the _left_ motor trim to a small
# negative value.  Increase or decrease the trim value until the bot moves
# straight forward/backward.

Next the code sets a left and right trim variable to a default zero value.  The comments for the code explain what the trim value means.  This is a small offset you can use to adjust the speed of each motor.  This is important to get perfectly straight movement as the motors can spin at slightly different speeds (and the robot has no knowledge of how fast the motors move).  You can ignore setting the trim for now and come back later to adjust it by instructing the robot to move  forward and watching which way it veers.

Download: file
# Create an instance of the robot with the specified trim values.
# Not shown are other optional parameters:
#  - addr: The I2C address of the motor HAT, default is 0x60.
#  - left_id: The ID of the left motor, default is 1.
#  - right_id: The ID of the right motor, default is 2.
robot = Robot.Robot(left_trim=LEFT_TRIM, right_trim=RIGHT_TRIM)

An instance of the Robot class is created and the trim values are passed in to its initializer.  There are a few other optional parameters that aren't shown and generally don't need to be changed (see the comments for more info on them).

Download: file
# Now move the robot around!
# Each call below takes two parameters:
#  - speed: The speed of the movement, a value from 0-255.  The higher the value
#           the faster the movement.  You need to start with a value around 100
#           to get enough torque to move the robot.
#  - time (seconds):  Amount of time to perform the movement.  After moving for
#                     this amount of seconds the robot will stop.  This parameter
#                     is optional and if not specified the robot will start moving
#                     forever.
robot.forward(150, 1.0)   # Move forward at speed 150 for 1 second.
robot.left(200, 0.5)      # Spin left at speed 200 for 0.5 seconds.
robot.forward(150, 1.0)   # Repeat the same movement 3 times below...
robot.left(200, 0.5)
robot.forward(150, 1.0)
robot.left(200, 0.5)
robot.forward(150, 1.0)
robot.right(200, 0.5)

Now the fun starts with the code to move the robot!  You can see the robot class instance has simple functions to move the robot forward, turn it left, turn it right, move backwards, and stop.  

Each of these functions takes up to 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.

Download: file
# 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.

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

Download: file
# Now move backwards and spin right a few times.
robot.backward(150, 1.0)
robot.right(200, 0.5)
robot.backward(150, 1.0)
robot.right(200, 0.5)
robot.backward(150, 1.0)
robot.right(200, 0.5)
robot.backward(150, 1.0)

Finally the robot code will demonstrate moving backwards and spinning right a few times.

That's all there is to the robot code!  You can see it's a very simple robot that has no sensors or other knowledge of the world.  The robot will blindly follow the instructions given to it.  You can use this as a base for building your own amazing robot projects with a Raspberry Pi, good luck!

This guide was first published on Jan 08, 2016. It was last updated on Jan 08, 2016.
This page (Software) was last updated on Jul 14, 2020.