Python & CircuitPython

It's easy to use the PCA9685 sensor with Python or CircuitPython and the Adafruit CircuitPython PCA9685 module.  This module allows you to easily write Python code that control servos and PWM with this breakout.

You can use this sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.

CircuitPython Microcontroller Wiring

First wire up a PCA9685 to your board exactly as shown on the previous pages for Arduino. Here's an example of wiring a Feather M0 to the sensor with I2C:

  • Board 3V to sensor VCC
  • Board GND to sensor GND
  • Board SCL to sensor SCL
  • Board SDA to sensor SDA

Python Computer Wiring

Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported

Here's the Raspberry Pi wired with I2C:

  • Pi 3V3 to sensor VCC
  • Pi GND to sensor GND
  • Pi SCL to sensor SCL
  • Pi SDA to sensor SDA
Don't try to power your servos from the RasPi or Linux board's 5V power, you can easily cause a power supply brown-out and mess up your Pi! Use a separate 5v 2A or 4A adapter

5V 2A (2000mA) switching power supply - UL Listed

PRODUCT ID: 276
This is a FCC/CE certified and UL listed power supply. Need a lot of 5V power? This switching supply gives a clean regulated 5V output at up to 2000mA. 110 or 240 input, so it works in...
$7.95
IN STOCK

5V 4A (4000mA) switching power supply - UL Listed

PRODUCT ID: 1466
Need a lot of 5V power? This switching supply gives a clean regulated 5V output at up to 4 Amps (4000mA). 110 or 240 input, so it works in any country. The plugs are "US...
OUT OF STOCK

CircuitPython Installation of PCA9685 and ServoKit Libraries

You'll need to install the Adafruit CircuitPython PCA9685 library on your CircuitPython board.

First make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle.  Our CircuitPython starter guide has a great page on how to install the library bundle.

For non-express boards like the Trinket M0 or Gemma M0, you'll need to manually install the necessary libraries from the bundle:

  • adafruit_pca9685.mpy
  • adafruit_bus_device
  • adafruit_register
  • adafruit_motor
  • adafruit_servokit

Before continuing make sure your board's lib folder or root filesystem has the adafruit_pca9685.mpy, adafruit_register, adafruit_servokit, adafruit_motor and adafruit_bus_device files and folders copied over.

Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.

Python Installation of PCA9685 and ServoKit Libraries

You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!

Once that's done, from your command line run the following commands:

  • sudo pip3 install adafruit-circuitpython-pca9685
  • sudo pip3 install adafruit-circuitpython-servokit

If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!

CircuitPython & Python Usage

The following section will show how to control the PCA9685 from the board's Python prompt / REPL. You'll learn how to interactively control servos and dim LEDs by typing in the code below. 

Dimming LEDs

Run the following code to import the necessary modules and initialize the I2C connection with the sensor:

Download: file
import board
import busio
import adafruit_pca9685
i2c = busio.I2C(board.SCL, board.SDA)
pca = adafruit_pca9685.PCA9685(i2c)

Each channel of the PCA9685 can be used to control the brightness of an LED.  The PCA9685 generates a high-speed PWM signal which turns the LED on and off very quickly.  If the LED is turned on longer than turned off it will appear brighter to your eyes.

First wire a LED to the board as follows.  Note you don't need to use a resistor to limit current through the LED as the PCA9685 will limit the current to around 10mA:

  • LED cathode / shorter leg to PCA9685 channel GND / ground.
  • LED anode / longer leg to PCA9685 channel PWM.

The PCA9685 class provides control of the PWM frequency and each channel's duty cycle.  Check out the PCA9685 class documentation for more details.

For dimming LEDs you typically don't need to use a fast PWM signal frequency and can set the board's PWM frequency to 60hz by setting the frequency attribute:

Download: file
pca.frequency = 60

The PCA9685 supports 16 separate channels that share a frequency but can have independent duty cycles. That way you could dim 16 LEDs separately!

The PCA9685 object has a channels attribute which has an object for each channel that can control the duty cycle. To get the individual channel use the [] to index into channels.

Download: file
led_channel = pca.channels[0]

Now control the LED brightness by controlling the duty cycle of the channel connected to the LED. The duty cycle value should be a 16-bit value, i.e. 0 to 0xffff, which represents what percent of the time the signal is on vs. off.  A value of 0xffff is 100% brightness, 0 is 0% brightness, and in-between values go from 0% to 100% brightness.

For example set the LED completely on with a duty cycle of 0xffff:

Download: file
led_channel.duty_cycle = 0xffff

After running the command above you should see the LED light up at full brightness!

Now turn the LED off with a duty cycle of 0:

Download: file
led_channel.duty_cycle = 0

Try an in-between value like 1000:

Download: file
led_channel.duty_cycle = 1000

You should see the LED dimly lit.  Try experimenting with other duty cycle values to see how the LED changes brightness!

For example make the LED glow on and off by setting duty_cycle in a loop:

Download: file
# Increase brightness:
for i in range(0xffff):
    led_channel.duty_cycle = i
     
# Decrease brightness:
for i in range(0xffff, 0, -1):
    led_channel.duty_cycle = i

These for loops take a while because 16-bits is a lot of numbers. CTRL-C to stop the loop from running and return to the REPL.

Full Example Code

# This simple test outputs a 50% duty cycle PWM single on the 0th channel. Connect an LED and
# resistor in series to the pin to visualize duty cycle changes and its impact on brightness.

from board import SCL, SDA
import busio

# Import the PCA9685 module.
from adafruit_pca9685 import PCA9685

# Create the I2C bus interface.
i2c_bus = busio.I2C(SCL, SDA)

# Create a simple PCA9685 class instance.
pca = PCA9685(i2c_bus)

# Set the PWM frequency to 60hz.
pca.frequency = 60

# Set the PWM duty cycle for channel zero to 50%. duty_cycle is 16 bits to match other PWM objects
# but the PCA9685 will only actually give 12 bits of resolution.
pca.channels[0].duty_cycle = 0x7fff

Controlling Servos

We've written a handy CircuitPython library for the various PWM/Servo kits called Adafruit CircuitPython ServoKit that handles all the complicated setup for you. All you need to do is import the appropriate class from the library, and then all the features of that class are available for use. We're going to show you how to import the ServoKit class and use it to control servo motors with the Adafruit 16-channel breakout.

If you aren't familiar with servos be sure to first read this intro to servos page and this in-depth servo guide page.

First connect the servo to channel 0 on the PCA9685. Here is an example of a servo connected to channel 0:

 

  • Servo orange wire to breakout PWM on channel 0
  • Servo red wire to breakout V+ on channel 0
  • Servo brown wire to breakout Gnd on channel 0

Check your servo data sheet to verify how to connect it!

 

Be sure you've turned on or plugged in the external 5V power supply to the PCA9685 board too!

First you'll need to import and initialize the ServoKit class. You must specify the number of channels available on your board. The breakout has 16 channels, so when you create the class object, you will specify 16.

Download: file
from adafruit_servokit import ServoKit
kit = ServoKit(channels=16)

Now you're ready to control both standard and continuous rotation servos.

Standard Servos

To control a standard servo, you need to specify the channel the servo is connected to. You can then control movement by setting angle to the number of degrees.

For example to move the servo connected to channel 0 to 180 degrees:

Download: file
pca.frequency = 50

Now that the PCA9685 is set up for servos lets make a Servo object so that we can adjust the servo based on angle instead of duty_cycle.

By default the Servo class will use actuation range, minimum pulse-width, and maximum pulse-width values that should work for most servos.  However check the Servo class documentation for more details on extra parameters to customize the signal generated for your servos.

Download: file
import adafruit_motor.servo
servo = adafruit_motor.servo.Servo(servo_channel)

With Servo, you specify a position as an angle.  The angle will always be between 0 and the actuation range given when Servo was created.  The default is 180 degrees but your servo might have a smaller sweep--change the total angle by specifying the actuation_angle parameter in the Servo class initializer above.

Now set the angle to 180, one extreme of the range:

Download: file
    kit.servo[0].angle = 180
  

To return the servo to 0 degrees:

Download: file
kit.servo[0].angle = 0

With a standard servo, you specify the position as an angle. The angle will always be between 0 and the actuation range. The default is 180 degrees but your servo may have a smaller sweep. You can change the total angle by setting actuation_range.

For example, to set the actuation range to 160 degrees:

Download: file
servokit.servo[0].actuation_range = 160

Often the range an individual servo recognises varies a bit from other servos. If the servo didn't sweep the full expected range, then try adjusting the minimum and maximum pulse widths using set_pulse_width_range(min_pulse, max_pulse).

To set the pulse width range to a minimum of 1000 and a maximum of 2000:

Download: file
kit.servo[0].set_pulse_width_range(1000, 2000)

That's all there is to controlling standard servos with the PCA9685 breakout, Python and ServoKit!

Continuous Rotation Servos

To control a continuous rotation servo, you must specify the channel the servo is on. Then you can control movement using throttle.

For example, to start the continuous rotation servo connected to channel 1 to full throttle forwards:

Download: file
kit.continuous_servo[1].throttle = 1

To start the continuous rotation servo connected to channel 1 to full reverse throttle:

Download: file
kit.continuous_servo[1].throttle = -1

To set half throttle, use a decimal:

Download: file
kit.continuous_servo[1].throttle = 0.5

And, to stop continuous rotation servo movement set throttle to 0:

Download: file
kit.continuous_servo[1].throttle = 0

That's all there is to controlling continuous rotation servos with the the PCA9685 16-channel breakout, Python and ServoKit!

Full Example Code

"""Simple test for a standard servo on channel 0 and a continuous rotation servo on channel 1."""
import time
from adafruit_servokit import ServoKit

# Set channels to the number of servo channels on your kit.
# 8 for FeatherWing, 16 for Shield/HAT/Bonnet.
kit = ServoKit(channels=8)

kit.servo[0].angle = 180
kit.continuous_servo[1].throttle = 1
time.sleep(1)
kit.continuous_servo[1].throttle = -1
time.sleep(1)
kit.servo[0].angle = 0
kit.continuous_servo[1].throttle = 0
This guide was first published on Oct 16, 2012. It was last updated on Oct 16, 2012. This page (Python & CircuitPython) was last updated on Jul 17, 2019.