MakerSnack: Install and Test the WaveShare Motor Driver Hat to Use CircuitPython on a Raspberry Pi

This video is part of the Let’s Build a Robot tutorial collection showing how to build a low-cost, high-quality Raspberry Pi robot and to create an iOS app to control it over Wi-Fi.

Our Raspberry Pi doesn’t know how to communicate with our robot motors out-of-the-box, so we’re going to use the WaveShare Motor Driver HAT for Raspberry Pi to help us. This is a small product, sized for use on the Pi Zero, although it will work on larger Pis, as well. The product comes assembled, so it’s a good choice for anyone who wants to avoid soldering.

Requirements:

This video assumes you have:

This tutorial was written as part of follow-along videos for building an iOS-controlled Raspberry Pi robot. The tutorial assumes you’re using a Mac (which will be needed if you’re going to use write an iOS app to control the robot).

Video:

Prefer video instruction? Use the follow-along YouTube video that covers the steps, below.

Step 1: Attach Motors to the WaveShare Motor Driver HAT

  • Take out your two DC motors. If you are using the Adafruit Mini Round Robot Chassis it comes with two yellow DC Motors in the box.
  • There are two wires coming out of each motor (red wire and black wire). Insert a jumper wire into each connector that is attached to the DC motor.
  • Using your small flat-head screwdriver, loosen the terminal screws on the Waveshare Motor Driver HAT for the MA1, MA2, MB1, MB2, and the VIN and GND terminals.
  • Select one motor, take the jumper wire coming from that motor’s red-connected wire and slide it into the MA1 terminal. Tighten the terminal screw with your screwdriver so the wire won’t come out when gently tugged (you want it to stay in while the robot moves about).
  • Take the jumper coming from that motor’s black wire and slide it into the MA2 terminal. Tighten the terminal screw so the wire remains snug inside the terminal.
  • Do the same for the two wires attached to the other motor – attaching the jumper coming from the red wire to the MB1 terminal, and the jumper coming from the black wire to the MB2 terminal. Tighten those screws, as well.
  • Take the black wire coming from the battery pack and slide it into the GND terminal. Tighten the terminal screw so the wire remains snug inside the terminal.
  • Do the same as above, connecting the red wire from the battery pack to the VIN terminal, and tighten.
  • Put batteries into the battery case that you’re using. If you are using a 4 AA battery case, use single-use Alkaline batteries. If your’e using a 6 AA battery case, use rechargeable AA batteries. Switch off the power on the battery case.
  • Turn the Motor Driver HAT over. Find the circular pin hole labeled VIN. Slide the red wire coming from the battery pack into this hole. Slide the black wire from the battery pack into the hole located next to it that is labeled GND.

Step 2: Install Additional Circuit Python Libraries to Drive DC Motors

Log into your Pi.

  • Launch the Terminal program on your Mac by pressing Command-Space to launch Spotlight, then type Terminal, and press the return key.
  • Log into your Pi using the command below replacing hostname with your Pi’s hostname, then press the return key. 
    ssh pi@hostname.local
  • Enter your Pi’s password when prompted, and press the return key.

Install the adafruit-circuitpython motorkit software:

  • Enter the line below into the Terminal’s command prompt and press enter. This may take a while before the Terminal shows progress, but you should see the installation progressing after about a minute or two. 
    sudo pip3 install adafruit-circuitpython-motorkit

Step 3: Modify CircuitPython’s adafruit-circuitpython-motorkit library to work with the Waveshare Motor Driver HAT.

The Waveshare Motor Driver HAT product is nice and inexpensive, and requires no soldering, but it doesn’t work with CircuitPython. While Waveshare does have some python libraries on its website, I prefer to stick to the well supported CircuitPython libraries (it’ll be easy to find support for other projects). Unfortunately there are slight differences between the Waveshare HAT and the ones supported by Adafruit, but we can change two lines in the software library so the fantastic, elegant and easier-to-use CircuitPython will work with the Waveshare. If you’re new to python, this may look pretty gnarly, but we’re only performing minor surgery to the library file – just changing a portion of two lines – and the steps below will show you exactly what to do:

  • Enter nano so that you can edit the adafruit_motorkit.py library by typing the entering the command below at the terminal command prompt, then press the return key. NOTE: there is a chance the python version has been upgraded since this tutorial was written. If you try the command below & see a blank screen, Ctrl-X out of nano, then at the prompt, perform ls /usr/local/lib. This should list the latest version of python used on your machine. Substitute out your latest version # instead of the 3.7 listed below. 
    sudo nano /usr/local/lib/python3.7/dist-packages/adafruit_motorkit.py
  • If you press and hold down the arrow key on your keyboard and advance through about nine screens of code (I don’t give an exact line number because Adafruit may change this code), you’ll come to a python function named motor1 that looks like this:

    def motor1(self):

    Continue to press the down arrow to pass through about two more screens of code until you get to the return statement that looks like this:

    return self._motor(1, (8, 9, 10), 1)

  • Replace the middle three numbers, removing the 8, 9, and 10, and replacing them with 0, 1, 2 so the new statement looks like this: 
            return self._motor(1, (0, 1, 2), 1)

    Just change the numbers, don’t remove or add any spaces, don’t add or remove spaces or tabs to the beginning, or remove any of the parentheses or commas. Only the three numbers underlined above should be changed. Python is REALLY picky about things like spaces and tabs, and if things fall out of alignment, the code might not run.

  • You’ll notice that two lines after the return line that you just modified, a new python function starts that is named:

    def motor2(self):
    keep pressing the down arrow until you get to the return statement for this function. It should take about two screens full of code to get there, and it will look like this:

    return self._motor(2, (13, 11, 12), 1)

  • Replace the middle three numbers, removing the 13, 11, and 12, and replacing them with 5, 3, 4 so the new statement looks like this: 
    return self._motor(2, (5, 3, 4), 1)

    Once again, just change the numbers, don’t remove or add any spaces, don’t add or remove spaces or tabs to the beginning, or remove any of the parentheses or commas. Only the three numbers underlined above should be changed.

  • Type Control+x in nano to save these changes. Congratulations! You’ve just modified a CircuitPython library to work with the WaveShare Motor Shield!

Create a Python3 program to test the motors

  • From the command prompt, type the following command to create a blank file using nano, named pybottest.py 
    nano pibottest.py
  • Visit the URL: https://github.com/gallaugher/pibot
  • Click the link for the file named pybottest.py. A page containing python code will open.
  • Copy the python code on this page, return to the Terminal, and paste this code into nano.

The code, as listed, will work with products supported by Adafruit, but we need to make one additional change.

  • Use the down-arrow until you find the line containing the code that reads:
    kit = MotorKit()
    and modify this code so it reads like line below – you can just position your cursor between the two parentheses and type 0x40. Note, those are both zeros and not the letter o.

    kit = MotorKit(0x40)
  • Type Control-X to quit nano.
  • Type “Y” when asked if you’d like to save the file.
  • Press the return key after the file name and you’ll be returned to the command prompt.

Now you’re ready to run the program.

  • Make sure that your motor hat is properly wired up, that you have charged batteries in your battery case, and the battery case is turned on.
  • Execute the pibottest.py python program by entering the command below, followed by the return key. 
    python3 pybottest.py

    You should notice the motors running as indicated by the code. Congratulations! You’re officially bot-building! Up next, let’s build the chassis and mount the electronics so that we can really get things really moving.

Find the next document in this series and links to accompanying step-by-step YouTube videos at: https://bit.ly/iOS-Pi-Robot

? ? ? ? ?

Ready for more? Check out tutorials on Robotics, Wearables, App Development and more at: http://bit.ly/GallaugherYouTube. Please consider subscribing and do share with others who may be interested!

Want to learn to build apps? The same content I use in my semester-long online course (videos and tutorial content) is available for less than $25 via links you’ll find at https://gallaugher.com/swift.

Look for more updates at gallaugher.com as well as on Twitter @gallaugher

Back To Top