# CircuitPython Hardware: PCA9685 PWM & Servo Driver

## Overview

Danger: 

![](https://cdn-learn.adafruit.com/assets/assets/000/046/548/medium800/micropython_IMG_5575.jpg?1505499839)

https://youtu.be/v_CTNAetcng

Info: 

Servo motors are one way to make projects come to life with exciting movements like steering robots, flipping switches, and more.  To control a servo you need to generate a special PWM, or pulse-width modulation, signal.  Most development boards can generate a few basic PWM signals, but what if you need to control a lot of servos or don't have a board with PWM support?  The PCA9685 PWM driver board comes to the rescue!  This driver board can generate up to 16-channels (or 8-channels in FeatherWing form) of PWM signals--perfect for driving many servos!

This guide explores how to use the PCA9685 PWM & Servo driver with CircuitPython and MicroPython.  You'll learn how to connect the PCA9685 to a board and use it to control LED brightness and move servos from Python code.

For more background check out these guides on servo motors:

- [Adafruit Motor Selection Guide: Servos](../../../../adafruit-motor-selection-guide/rc-servos)
- [Arduino Lesson 14: Servos](../../../../adafruit-arduino-lesson-14-servo-motors/overview) (focus on the general servo information, less on the Arduino details)

# CircuitPython Hardware: PCA9685 PWM & Servo Driver

## Hardware

Danger: 

# Parts

You'll need the following parts to follow this guide:

 **CircuitPython board.**   This guide focuses on the [ESP8266](https://www.adafruit.com/product/2821) and [Feather M0/SAMD21-based boards](https://www.adafruit.com/products/2772), but any CircuitPython board that supports I2C should work.

 

If your board doesn't come with CircuitPython running on it already then check out your board's guide for how to load CircuitPython firmware.  For example the [Feather M0 express guide](../../../../adafruit-feather-m0-express-designed-for-circuit-python-circuitpython/circuitpython) is a good reference.

 

If you're using a Feather board and FeatherWing you probably want a [Feather female header set](https://www.adafruit.com/products/2886) or [Feather stacking female header set](https://www.adafruit.com/products/2830).

![micropython_3403-00.jpg](https://cdn-learn.adafruit.com/assets/assets/000/046/551/medium640/micropython_3403-00.jpg?1505500138)

 **PCA9685 PWM & Servo Driver Board.**   If you're using a Feather the [8-channel PWM & Servo FeatherWing](https://www.adafruit.com/products/2928) is the perfect option.  If you need more channels or aren't using a Feather grab the [16-channel PCA9685 breakout board](https://www.adafruit.com/products/815) or even [16-channel PCA9685 Arduino shield](https://www.adafruit.com/products/1411).

![micropython_2928-10.jpg](https://cdn-learn.adafruit.com/assets/assets/000/046/553/medium640/micropython_2928-10.jpg?1505500196)

 **5V Power Supply.**   To power servos you almost always need an external 5V power supply.  Servos can pull a lot of power and could damage your board if powered directly from it!  A simple power option is a [4x AA battery pack](https://www.adafruit.com/products/830) or a [5V power supply](https://www.adafruit.com/products/276) and [barrel jack screw terminal connector](https://www.adafruit.com/products/368).

![micropython_830-03.jpg](https://cdn-learn.adafruit.com/assets/assets/000/046/554/medium640/micropython_830-03.jpg?1505500256)

 **Servos or LEDs.**   You'll want something to drive with the PCA9685, like [servos](https://www.adafruit.com/categories/34) you can move or [LEDs](https://www.adafruit.com/categories/90) you can dim.  Remember the PCA9685 only drives  **servos** , not stepper or other motors.

![micropython_169-06.jpg](https://cdn-learn.adafruit.com/assets/assets/000/046/558/medium640/micropython_169-06.jpg?1505500327)

**[Breadboard ](https://www.adafruit.com/products/64)**and **[jumper wires](https://www.adafruit.com/products/153)**.  If you aren't using a Feather and FeatherWing you'll need a breadboard and jumper wires to connect the components.

 

**[Soldering tools](https://www.adafruit.com/products/136)**.  You'll need to solder headers to the boards  Check out the [guide to excellent soldering](../../../../adafruit-guide-excellent-soldering/tools) if you're new to soldering.

![micropython_136-01.jpg](https://cdn-learn.adafruit.com/assets/assets/000/046/560/medium640/micropython_136-01.jpg?1505500377)

Make sure to follow the board and PCA9685 driver board product guides to assemble and verify they work before continuing.

# Wiring

If you're using a Feather and the PCA9685 FeatherWing just slide the wing into the Feather's headers and you're done!  The wing will use an I2C connection to talk to the Feather board.

If you're using a PCA9685 breakout you'll need to connect its I2C and power pins as follows:

![](https://cdn-learn.adafruit.com/assets/assets/000/046/564/medium800/micropython-pca9685-esp_bb.png?1505500434)

[Fritzing Source](https://cdn-learn.adafruit.com/assets/assets/000/046/565/original/micropython-pca9685-esp.fzz?1505500468)
- **Board SCL / I2C clock**  to  **PCA9685 SCL**.
- **Board SDA / I2C**   **data**  to  **PCA9685 SDA**.
- **Board 3.3V power**  to  **PCA9685 VCC**.
- **Board GND / ground**  to  **PCA9685 GND / ground**.

Once your board is wired to the PCA9685 continue on to learn how to use a MicroPython module to control servos and LEDs!

# CircuitPython Hardware: PCA9685 PWM & Servo Driver

## CircuitPython

Danger: 

# Adafruit CircuitPython Module Install

To use the PCA9685 with your [Adafruit CircuitPython](https://blog.adafruit.com/2017/01/09/welcome-to-the-adafruit-circuitpython-beta/) board you'll need to install the [Adafruit\_CircuitPython\_PCA9685](https://github.com/adafruit/Adafruit_CircuitPython_PCA9685) module on your board.  **Remember this module is for Adafruit CircuitPython firmware and not MicroPython.org firmware!**

First make sure you are running the [latest version of Adafruit CircuitPython](https://github.com/adafruit/circuitpython/releases) for your board.  Next you'll need to install the necessary libraries to use the hardware--read below and carefully follow the referenced steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle) with a version 20180110 or newer. 

## Bundle Install

For express boards that have extra flash storage, like the Feather/Metro M0 express and Circuit Playground express, you can easily install the necessary libraries with [Adafruit's CircuitPython bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle).  This is an all-in-one package that includes the necessary libraries to use the PCA9685 with CircuitPython.  To install the bundle follow the steps in your board's guide, like [these steps for the Feather M0 express board](../../../../adafruit-feather-m0-express-designed-for-circuit-python-circuitpython/installing-libraries).

Remember for non-express boards like the Trinket M0, Gemma M0, and Feather/Metro M0 basic you'll need to manually install the necessary libraries from the bundle:

- **adafruit\_pca9685**
- **adafruit\_bus\_device**
- **adafruit\_register**
- **adafruit\_motor**

If your board supports USB mass storage, like the M0-based boards, then simply drag the files to the board's file system. **Note on boards without external SPI flash, like a Feather M0 or Trinket/Gemma M0, you might run into issues on Mac OSX with hidden files taking up too much space when drag and drop copying, [see this page for a workaround](../../../../micropython-for-samd21/usb-mass-storage#mac-osx-file-copy-issues).**

If your board doesn't support USB mass storage, like the ESP8266, then [use a tool like ampy to copy the file to the board](../../../../micropython-basics-load-files-and-run-code). You can use the latest version of ampy and its [new directory copy command](../../../../micropython-basics-load-files-and-run-code/file-operations#copy-directories-to-board) to easily move module directories to the board.

Before continuing make sure your board's lib folder or root filesystem has the  **adafruit\_pca9685** ,  **adafruit\_bus\_device** , **adafruit\_register** and **adafruit\_motor** folders/modules copied over.

Info: 

![](https://cdn-learn.adafruit.com/assets/assets/000/049/978/medium800/micropython_pca_tutorial.png?1515619327)

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

First [connect to the board's serial REPL ](../../../../micropython-basics-how-to-load-micropython-on-a-board/serial-terminal)so you are at the CircuitPython  **\>\>\>**  prompt.

## I2C Initialization

First you'll need to initialize the I2C bus for your board. First import the necessary modules:

```auto
import board
import busio
```

Now for either board run this command to create the I2C instance using the default SCL and SDA pins (which will be marked on the boards pins if using a Feather or similar Adafruit board):

```auto
i2c = busio.I2C(board.SCL, board.SDA)
```

After initializing the I2C interface you need to import the PCA9685 module to use it in your own code:

```auto
import adafruit_pca9685
```

# Dimming LED's

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:

![](https://cdn-learn.adafruit.com/assets/assets/000/046/572/medium800/micropython-pca9685-led_bb.png?1505501172)

[Fritzing Source](https://cdn-learn.adafruit.com/assets/assets/000/046/573/original/micropython-pca9685-led.fzz?1505501187)
- **LED cathode / shorter leg**  to  **PCA9685 channel GND / ground**.
- **LED anode / longer leg**  to  **PCA9685 channel PWM**.

Now in the Python REPL you can create an instance of the basic PCA9685 class which provides low-level PWM control of the board's channels:

```auto
pca = adafruit_pca9685.PCA9685(i2c)
```

The PCA9685 class provides control of the PWM frequency and each channel's duty cycle.  Check out the [PCA9685 class documentation](https://circuitpython.readthedocs.io/projects/pca9685/en/latest/api.html) 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:

```auto
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**.

```auto
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:

```auto
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:

```auto
led_channel.duty_cycle = 0
```

Try an in-between value like 1000:

```auto
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:

```auto
# 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.

# Control Servos

Servo motors use a PWM signal to control the position of their arm or horn.  Using the PCA9685 and the [Motor library](https://circuitpython.readthedocs.io/projects/motor/en/latest/) you can easily plug in servos and control them with Python.  If you aren't familiar with servos be sure to first read this [intro to servos page](../../../../adafruit-arduino-lesson-14-servo-motors/servo-motors) and this [in-depth servo guide page](../../../../adafruit-motor-selection-guide/rc-servos).

First connect the servo to a channel on the PCA9685.  Be sure to plug the servo connector in the correct way!  Check your servo's datasheet to be sure, but typically the brown wire is connected to ground, the red wire is connected to 5V power, and the yellow pin is connected to PWM:

![](https://cdn-learn.adafruit.com/assets/assets/000/046/574/medium800/micropython_IMG_5572.jpg?1505501433)

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

Now in the Python REPL as above with the led, save a variable for its channel:

```auto
servo_channel = pca.channels[0]
```

Servos typically operate at a frequency of 50 hz so update pca accordingly.

```auto
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](https://circuitpython.readthedocs.io/projects/motor/en/latest/api.html#adafruit_motor.servo.Servo) for more details on extra parameters to customize the signal generated for your servos.

```auto
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:

```auto
servo.angle = 180
```

Or to sweep back to the minimum 0 degree position:

```auto
servo.angle = 0
```

Often the range an individual servo recognizes varies a bit from other servos. If the servo didn't sweep the full expected range, then try adjusting min\_pulse and max\_pulse. Lower min\_pulse until the servo stops moving or moves irregularly when angle is changed to 0. Raise max\_pulse util the servo stops moving or moves irregularly when angle is change to the actuation range.

```auto
servo = adafruit_motor.servo.Servo(servo_channel, min_pulse=800, max_pulse=2200)
```

That's all there is to controlling servos with the PCA9685 and CircuitPython!  Using the **angle** attribute you can sweep and move servos in any way.  This is perfect for building robots, actuating switches, or other fun mechanical projects!

# CircuitPython Hardware: PCA9685 PWM & Servo Driver

## MicroPython

Danger: 

Warning: 

In addition to CircuitPython there's an older MicroPython version of the PCA9685 library that you can use with some MicroPython boards.  Before you get started it will help to be familiar with these guides for working with MicroPython:

- [MicroPython Basics: What is MicroPython?](../../../../micropython-basics-what-is-micropython)
- [MicroPython Basics: How to Load MicroPython on a Board](../../../../micropython-basics-how-to-load-micropython-on-a-board)
- [MicroPython Basics: Load Files & Run Code](../../../../micropython-basics-load-files-and-run-code)
- [MicroPython Hardware: Analog I/O](../../../../micropython-hardware-analog-i-o/overview) (see the [PWM page](../../../../micropython-hardware-analog-i-o/pulse-width-modulation) specifically)

See [all the MicroPython guides in the learning system](../../../../category/micropython) for more information.

# MicroPython Module Install

To use the PCA9685 with your MicroPython board you'll need to install the [micropython-adafruit-pca9685 MicroPython module](https://github.com/adafruit/micropython-adafruit-pca9685) on your board.   **Remember this module is for MicroPython.org firmware and not Adafruit CircuitPython!**

First make sure you are running the latest version of MicroPython for your board.  If you're using the  **ESP8266 MicroPython**  port you  **must**  be running version **[1.8.5 or higher](http://micropython.org/download#esp8266)** as earlier versions do not support using .mpy modules as shown in this guide.  

Next download the latest  **pca9685.mpy, servo.mpy,****  motor.mpy, and stepper.mpy** file from the [releases page](https://github.com/adafruit/micropython-adafruit-pca9685/releases) of the [micropython-adafruit-pca9685 GitHub repository](https://github.com/adafruit/micropython-adafruit-pca9685).  You'll need to copy **all **of the files to your MicroPython board's file system and can [use a tool like ampy to copy the files to the board](../../../../micropython-basics-load-files-and-run-code/overview).

# Usage

The following section will show how to control the PCA9685 from the board's Python prompt / REPL.   First [connect to the board's serial REPL ](../../../../micropython-basics-how-to-load-micropython-on-a-board/serial-terminal)so you are at the MicroPython  **\>\>\>**  prompt.

## I2C Initialization

First you'll need to initialize the I2C bus for your board.  On MicroPython.org firmware which uses the machine API you can initialize I2C like [the MicroPython I2C guide mentions](../../../../micropython-hardware-i2c-devices).  For example on a board like the ESP8266 you can run (assuming you're using the default SDA gpio #4 and SCL gpio #5 pins like on a Feather & PCA9685 FeatherWing):

```auto
import machine
i2c = machine.I2C(scl=machine.Pin(5), sda=machine.Pin(4))
```

Then import the PCA9685 module as follows:

```auto
import pca9685
```

# LED & Servo Control

At this point you're ready to use the PCA9685 module to dim LEDs and controls servos.  Using the module with MicroPython is exactly the same as with CircuitPython so check out the [CircuitPython usage section](../../../../micropython-hardware-pca9685-pwm-and-servo-driver/circuitpython#dim-leds) to see details on using the board.


## Featured Products

### 8-Channel PWM or Servo FeatherWing Add-on For All Feather Boards

[8-Channel PWM or Servo FeatherWing Add-on For All Feather Boards](https://www.adafruit.com/product/2928)
A Feather board without ambition is a Feather board without FeatherWings! This is the **8-Channel PWM or Servo​ FeatherWing** , you can add 8 x 12-bit PWM outputs to your Feather board. Using our [Feather Stacking...](https://www.adafruit.com/products/2830)

Out of Stock
[Buy Now](https://www.adafruit.com/product/2928)
[Related Guides to the Product](https://learn.adafruit.com/products/2928/guides)
### Adafruit 16-Channel 12-bit PWM/Servo Driver - I2C interface

[Adafruit 16-Channel 12-bit PWM/Servo Driver - I2C interface](https://www.adafruit.com/product/815)
You want to make a cool robot, maybe a hexapod walker, or maybe just a piece of art with a lot of moving parts. Or maybe you want to drive a lot of LEDs with precise PWM output. Then you realize that your microcontroller has a limited number of PWM outputs! What now? You could give up OR you...

Out of Stock
[Buy Now](https://www.adafruit.com/product/815)
[Related Guides to the Product](https://learn.adafruit.com/products/815/guides)
### Adafruit 16-Channel 12-bit PWM/Servo Shield - I2C interface

[Adafruit 16-Channel 12-bit PWM/Servo Shield - I2C interface](https://www.adafruit.com/product/1411)
You want to make a cool Arduino robot, maybe a hexapod walker, or maybe just a piece of art with a lot of moving parts. Or maybe you want to drive a lot of LEDs with precise PWM output. Then you realize that the Arduino has only a few PWM outputs, and maybe those outputs are conflicting with...

In Stock
[Buy Now](https://www.adafruit.com/product/1411)
[Related Guides to the Product](https://learn.adafruit.com/products/1411/guides)
### 4 x AA Battery Holder with On/Off Switch

[4 x AA Battery Holder with On/Off Switch](https://www.adafruit.com/product/830)
Make a nice portable power pack with this 4 x AA battery holder. It fits any alkaline or rechargeable AA batteries in series. There's a snap on cover and an on/off switch which can be handy when wiring to something without a switch.

**New**! We now have 0.1" headers...

In Stock
[Buy Now](https://www.adafruit.com/product/830)
[Related Guides to the Product](https://learn.adafruit.com/products/830/guides)
### 5V 2A (2000mA) switching power supply - UL Listed

[5V 2A (2000mA) switching power supply - UL Listed](https://www.adafruit.com/product/276)
This is an 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 any country. The plugs are "US 2-prong" style so you may need a plug adapter, but you can pick one...

In Stock
[Buy Now](https://www.adafruit.com/product/276)
[Related Guides to the Product](https://learn.adafruit.com/products/276/guides)
### Female DC Power adapter - 2.1mm jack to screw terminal block

[Female DC Power adapter - 2.1mm jack to screw terminal block](https://www.adafruit.com/product/368)
If you need to connect a DC power wall wart to a board that doesn't have a DC jack - this adapter will come in very handy! There is a 2.1mm DC jack on one end, and a screw terminal block on the other. The terminals are labeled with positive/negative assuming a positive-tip configuration...

In Stock
[Buy Now](https://www.adafruit.com/product/368)
[Related Guides to the Product](https://learn.adafruit.com/products/368/guides)
### Adafruit METRO M0 Express - designed for CircuitPython

[Adafruit METRO M0 Express - designed for CircuitPython](https://www.adafruit.com/product/3505)
Metro is our series of microcontroller boards for use with the Arduino IDE. This new **Metro M0 Express** board looks a whole lot like our [original Metro 328](https://www.adafruit.com/product/2488), but with a huge upgrade. Instead of the ATmega328, this Metro...

Out of Stock
[Buy Now](https://www.adafruit.com/product/3505)
[Related Guides to the Product](https://learn.adafruit.com/products/3505/guides)
### Adafruit Feather M0 Express

[Adafruit Feather M0 Express](https://www.adafruit.com/product/3403)
At the Feather M0's heart is an ATSAMD21G18 ARM Cortex M0+ processor, clocked at 48 MHz and at 3.3V logic, the same one used in the new [Arduino Zero](https://www.adafruit.com/products/2843). This chip has a whopping 256K of FLASH (8x more than the Atmega328 or 32u4) and...

In Stock
[Buy Now](https://www.adafruit.com/product/3403)
[Related Guides to the Product](https://learn.adafruit.com/products/3403/guides)

## Related Guides

- [Adafruit Feather M0 Adalogger](https://learn.adafruit.com/adafruit-feather-m0-adalogger.md)
- [Adafruit Feather M0 Bluefruit LE](https://learn.adafruit.com/adafruit-feather-m0-bluefruit-le.md)
- [Adafruit Feather M0 Express](https://learn.adafruit.com/adafruit-feather-m0-express-designed-for-circuit-python-circuitpython.md)
- [Adafruit Metro M0 Express](https://learn.adafruit.com/adafruit-metro-m0-express.md)
- [Adafruit Trinket M0](https://learn.adafruit.com/adafruit-trinket-m0-circuitpython-arduino.md)
- [Adafruit Circuit Playground Express](https://learn.adafruit.com/adafruit-circuit-playground-express.md)
- [Pushrod Garage](https://learn.adafruit.com/pushrod-garage.md)
- [DAC Hacks for Circuit Playground Express & other ATSAMD21 Boards](https://learn.adafruit.com/circuit-playground-express-dac-hacks.md)
- [Digital Fidget Spinner](https://learn.adafruit.com/digital-fidget-spinner.md)
- [MicroPython Basics: How to Load MicroPython on a Board](https://learn.adafruit.com/micropython-basics-how-to-load-micropython-on-a-board.md)
- [AM Radio Morse Code Paddle](https://learn.adafruit.com/am-radio-morse-code-paddle.md)
- [Adafruit AirLift Shield - ESP32 WiFi Co-Processor](https://learn.adafruit.com/adafruit-airlift-shield-esp32-wifi-co-processor.md)
- [Android GBoard Morse Code Control with Circuit Playground Express](https://learn.adafruit.com/android-gboard-morse-code-at-with-circuitplayground-express.md)
- [CircuitPython Hardware: ILI9341 TFT & FeatherWing](https://learn.adafruit.com/micropython-hardware-ili9341-tft-and-featherwing.md)
- [CPU Temperature Logging with CircuitPython](https://learn.adafruit.com/cpu-temperature-logging-with-circuit-python.md)
- [Using Piezo Buzzers with CircuitPython & Arduino](https://learn.adafruit.com/using-piezo-buzzers-with-circuitpython-arduino.md)
- [Hanukkah MakeCode Menorah Sweater](https://learn.adafruit.com/hanukkah-menorah-sweater.md)
- [Sparkle Skirt Playground](https://learn.adafruit.com/sparkle-skirt-playground.md)
- [Building the Assistive Technology Ultimate Remote](https://learn.adafruit.com/building-the-assistive-technology-ultimate-remote.md)
- [50 Cent CPI Tracker for MagTag](https://learn.adafruit.com/50-cent-cpi-tracker-for-magtag.md)