Spin a Wheel

In the previous tutorial we used some simple functions to turn a light on and off. Lets use some more advanced code to now control a motor. In this program we'll make use of a VEX MC-29 motor controller. These motor controllers use a Pulse Width Modulation (PWM) signal to determine direction and magnitude of the motor rotation they control.

For this program, we're going to use two new modules: pwmio and adafruit_motor.

The pwmio Module

PWM is a simple way to send an analog signal over a digital pin. It is commonly used for controlling motors, servos, and other actuators. The pwmio module provides the PWMOut class to efficiently generate PWM signals on a pin using our microcontroller's built-in timers. A timer is a dedicated piece of hardware that accurately keeps track of time without the main processor having to think about it. Most microcontrollers use timers to get very accurate PWM signals while the main code can work on other tasks. There are two important values for us to control with a PWMOut object: frequency and duty cycle.

Frequency is the number of times each second that the signal changes from low to high and back to low. This is measured in Hertz (Hz). One Hertz means "once per second."

Duty Cycle is the fraction of the total pulse time where the signal is held high. 0% duty cycle is a signal that is always low. 100% duty cycle is a signal that is always high. 50% duty cyclce is a signal that spends an equal amount of time high and low.

While PWM is an important concept to understand in robotics, we don't need to use it directly for controlling motors. We introduce this module here because it is used by the adafruit_motor module.

API documentation for the pwmio module is available here.

The adafruit_motor Module

The adafruit_motor module provides tools for controlling a variety of types of motors. We will use the adafruit_motor.servo module specifically.

Why would we use a "servo" module for controlling our motors? In our case, it's because they use the same control interface. The Vex MC29 makes our DC gear motors behave like "continuous rotation servos" by using PWM to control them. You have probably seen servo connectors like the ones on the Vex MC29 before. This is a standard style of connector that is very popular for remote control cars and planes. The red and black wires provide power to the servo / motor and the white wire carries a PWM signal to control the servo / motor.

Servos control their position based on the signal they receive. We can control servos using the Servo class in adafruit_motor.servo. It has a property called angle that lets us set the position of the servo. Another property called actuation_range tells the Servo object how far the physical servo is able to move, so the code knows how to convert our angles into PWM signals.

For controlling motors, we can use the ContinousServo class in adafruit_motor.servo. It has a property called throttle which controls the speed of the motor. throttle can be set to any value between -1.0 and 1.0. Positive numbers will make the motor spin one direction and negative numbers will make the motor spin the other direction. Zero throttle will stop the motor.

Both of these objects are created by giving them a PWMOut object connected to a pin. Optionally, you can also tell them the minimum and maximum pulse widths in milliseconds.

API documentation for the adafruit_motor module is available here.

Looping Over Numbers

A common need in programs is looping over a range of numbers. This could be just because we need to repeat some action a certain number of times, or to loop through the elements in a list of items, for example. In Python, we can do this with a for loop and the range function.

A for loop, in Python, runs the body of its loop once for each element in a container. If you give the list of numbers [1, 2, 3, 4], the loop will run four times.

# This loop will run 4 times
for i in [1, 2, 3, 4]:
  # i holds the current element from the list
  print(i)
# This code will output:
# 1
# 2
# 3
# 4

Usually, we don't want to list out each number in the range one by one. Instead, we create a range object. A range object can be created in one of three ways:

# Create a range with the number of values it should hold
# This range will hold the numbers 0 through 9
range(10)

# Create a range with a start and stop value
# The range includes the start value, but does NOT include the stop value
# This range will hold the numbers 5 through 19
range(5,20)

# Create a range with start, stop, and step values
# step controls the difference between values in the range
# A step of 2 means each number will be the previous number plus 2
# This range will hold even numbers from 0 through 98
range(0, 100, 2)

Using a range in a for loop, we can make a loop that runs 10 times:

for i in range(10):
  print(i)

Controlling a Motor With Gizmo

Now let's write a program that controls a motor connected to our Gizmo. This program will run the motor through at different speeds. To get started, connect a motor to your Gizmo using the Vex MC29 motor controller on motor port 1.

To start our program, we'll import the modules we need to use.

import pwmio
import time
import adafruit_motor.servo
import circuitpython_gizmo

For the setup portion of our code, we just need to setup a Gizmo object and an object to control the motor. To make sure we're creating the right kinds of signals for the Vex MC29 motor controller, we need to set the PWM frequency to 50 Hz, the min pulse width to 1000 milliseconds, and the max pulse width to 2000 milliseconds. We're using 50 Hz because it is the most common frequency used for servo PWM signals, and we happen to know it's what the Vex MC29 uses. The min and max pulse widths came from the "Inputs" details on the Vex MC29 product page.

gizmo = circuitpython_gizmo.Gizmo()
motor = adafruit_motor.servo.ContinuousServo(
    pwmio.PWMOut(gizmo.MOTOR_1, frequency=50),
    min_pulse=1000,
    max_pulse=2000
)

Next, create a while loop and refresh the Gizmo object.

while True:
  gizmo.refresh()

Then, still in the while loop, create a for loop that covers the range -10 to 10. The stop value needs to be 11 here because the range stops one value before the stop value.

  for i in range(-10,11):

In the for loop, we'll set the motor throttle and use time.sleep() to let the robot run for a bit before setting the next speed. When setting the throttle, we need to change the loop variable to fit in the -1 to +1 range throttle expects.

    motor.throttle = i / 10.0
    time.sleep(0.5)

Finally, after the first for loop, add another that will loop in the opposite direction. This will cause the program to smoothly run the motor back and forth without jumping form full forward to full reverse. This loop will need to specify -1 as the step value so the loop value decreases in each iteration.

  for i in range(10,-11,-1):
    motor.throttle = i / 10.0
    time.sleep(0.5)

The full program looks like this:

import pwmio
import time
import adafruit_motor.servo
import circuitpython_gizmo

gizmo = circuitpython_gizmo.Gizmo()
motor = adafruit_motor.servo.ContinuousServo(
    pwmio.PWMOut(gizmo.MOTOR_1, frequency=50),
    min_pulse=1000,
    max_pulse=2000
)

while True:
  gizmo.refresh()

  for i in range(-10,11):
    motor.throttle = i / 10.0
    time.sleep(0.5)

  for i in range(10,-11,-1):
    motor.throttle = i / 10.0
    time.sleep(0.5)

Recap

In this tutorial, we introduced the pwmio and adafruit_motor modules. We covered how to loop over a range of numbers and put all of this together to run a Gizmo motor through its range of speeds. We're just a few steps away from writing code to control our robot with a gamepad, in the next tutorial.