Skip to main content

Servo sweep

What this example shows​

Driving a hobby servo by angle instead of raw ticks, and sweeping it back and forth across its configured range. This is the board's primary advertised use case.

The example code​

# FILE: pca9685-servoSweep.py
# AUTHOR: Fran Fodor @ Soldered
# BRIEF: Sweep a hobby servo on channel 0 back and forth using PCA9685
# LAST UPDATED: 2026-07-24

from pca9685 import PCA9685
from utime import sleep_ms

pwm = PCA9685() # sets 50Hz PWM frequency by default, suitable for hobby servos

# Adjust to match your servo's datasheet if it doesn't reach full range
pwm.setServoPulseRange(500, 2500) # microseconds
pwm.setServoAngleRange(0, 180) # degrees

while True:
for angle in range(0, 181):
pwm.setServoAngle(0, angle)
sleep_ms(15)

for angle in range(180, -1, -1):
pwm.setServoAngle(0, angle)
sleep_ms(15)

Before you run it, plug the servo into the CH1 header, which is channel 0 in the code: its signal wire on OUT, its power wire on V+ and its ground wire on GND. Then connect a supply suited to your servo to the screw terminal's V+ and GND, because the Qwiic cable does not carry servo power. Hardware Details shows the servo power connections.

Expected result:

No serial output. A hobby servo connected to channel 0 sweeps from 0 to 180 degrees and back, each direction taking a little under 3 seconds, then repeats.

Functions used​

PCA9685(i2c=None, address=PCA9685_DEFAULT_ADDRESS)returns None

Constructor. Sets the default 50 Hz PWM frequency, which is what hobby servos expect, the 500 to 2500 us pulse range and the 0 to 180 degree angle range. If you pass no i2c object, it checks the MicroPython port name (uname().sysname): on the ESP32 and ESP8266 ports it opens I2C bus 0 with SCL on pin 22 and SDA on pin 21, and on boards that report another port name it raises 'Board not recognized, enter I2C pins manually'. Pins 22 and 21 are the module's default, not a property of your board: if your board's Qwiic connector or I2C header uses other pins, create a machine.I2C object on those pins and pass it in.

ReturnsConstructor; no return value.

Parameters

TypeNameDescription
I2Ci2cInitialized machine.I2C object. Optional; without it, pins 22 (SCL) and 21 (SDA) on the ESP32 and ESP8266 ports.
intaddressI2C address of the board. Defaults to PCA9685_DEFAULT_ADDRESS (0x40).
setServoPulseRange(minPulseUs, maxPulseUs)returns None

Configures the pulse width, in microseconds, that setServoAngle() maps to the minimum and maximum angle. Match this to your servo's own datasheet if it does not reach its full mechanical range at the library's default.

ReturnsNothing.

Parameters

TypeNameDescription
intminPulseUsPulse width in microseconds mapped to the minimum angle. Library default: 500 us.
intmaxPulseUsPulse width in microseconds mapped to the maximum angle. Library default: 2500 us.
setServoAngleRange(minAngle, maxAngle)returns None

Configures the angle range, in degrees, accepted by setServoAngle().

ReturnsNothing.

Parameters

TypeNameDescription
floatminAngleAngle in degrees mapped to minPulseUs. Library default: 0.
floatmaxAngleAngle in degrees mapped to maxPulseUs. Library default: 180.
setServoAngle(channel, angle)returns bool

Drives a hobby servo on the given channel to an angle, clamped to the configured angle range. Internally converts the angle to a pulse width and calls setPWM() for you. Assumes the default 50 Hz frequency set by the constructor.

ReturnsTrue on success, False if channel is out of range.

Parameters

TypeNameDescription
intchannelChannel number, 0 to 15.
floatangleAngle in degrees, clamped to the range set by setServoAngleRange().

Putting it together​

setServoPulseRange() and setServoAngleRange() are one-time setup calls: run them once, before the first setServoAngle(). After that, setServoAngle() does the angle-to-pulse-width math and calls setPWM() for you, so you never need to compute tick counts by hand for a servo.

This example relies on the constructor's default 50 Hz frequency, which is what hobby servos expect. The PWM frequency is shared by all 16 channels: setPWMFreq() takes no channel, so a call made for an LED changes all 16 outputs too, the servo signal included. Leave the board at 50 Hz while it drives servos.