MojoScale Studio Docs
API Reference

pca9685

PCA9685 16-channel PWM driver module.

All modules Open Studio
Studio Docs Sensors & I/O

import pca9685

The pca9685 module controls a PCA9685 over I2C. It provides 16 independent 12-bit PWM outputs and is commonly used for servo banks, LED dimming, motor driver PWM inputs, and other low-frequency PWM expansion.

Quick example

import pca9685

driver = pca9685.PCA9685(sda=21, scl=22)
driver.set_servo(0, 90)
driver.set_servo(1, 30, min_us=1000, max_us=2000)

leds = pca9685.PCA9685(sda=21, scl=22, address=0x41, pwm_frequency=1000)
leds.set_duty(0, 0.25)
leds.set_value(1, 2048)

importpca9685

PCA9685 16-channel PWM driver module.

The pca9685 module controls a PCA9685 over I2C. It provides 16 independent 12-bit PWM outputs and is commonly used for servo banks, LED dimming, motor driver PWM inputs, and other low-frequency PWM expansion.

API 34 available

pca9685.PCA9685(sda: int, scl: int, address: int = None, i2c_frequency: any = None, pwm_frequency: any = None, port: int = None, oscillator_hz: any = None, open_drain: bool = None, invert: bool = None) -> pca9685_controller

Create and initialize an independent PCA9685 PWM controller.

Use one PCA9685 object for each physical controller. Multiple controllers can share one I2C bus when each board has a unique address.

Parameters
Name Type Pass as Required Description
sda int positional or keyword Yes GPIO connected to I2C SDA.
scl int positional or keyword Yes GPIO connected to I2C SCL.
address int positional or keyword No Optional 7-bit I2C address. Defaults to 0x40.
i2c_frequency any positional or keyword No Optional I2C bus frequency in hertz. Defaults to 400000.
pwm_frequency any positional or keyword No Optional PWM output frequency in hertz. Defaults to 50, which is typical for hobby servos.
port int positional or keyword No Optional ESP-IDF I2C port. Defaults to 0.
oscillator_hz any positional or keyword No Optional PCA9685 oscillator frequency. Defaults to 25000000.
open_drain bool positional or keyword No Optional output driver mode. Defaults to False.
invert bool positional or keyword No Optional output polarity inversion. Defaults to False.
Returns

pca9685_controller pca9685_controller object.

pca9685.PCA9685().set_pwm_frequency(frequency, oscillator_hz=None) -> bool

Set the shared PWM frequency for all channels on this controller.

Parameters
Name Type Pass as Required Description
frequency int positional or keyword Yes Required value.
oscillator_hz any positional or keyword No Optional value. Defaults to None.

pca9685.PCA9685().set_pwm(channel, on, off) -> bool

Write raw 12-bit on/off ticks for one channel.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
on any positional or keyword Yes Required value.
off any positional or keyword Yes Required value.

pca9685.PCA9685().set_all_pwm(on, off) -> bool

Write raw on/off ticks to all channels.

Parameters
Name Type Pass as Required Description
on any positional or keyword Yes Required value.
off any positional or keyword Yes Required value.

pca9685.PCA9685().set_duty(channel, duty) -> bool

Set one channel by normalized duty cycle from 0.0 through 1.0.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
duty any positional or keyword Yes Required value.

pca9685.PCA9685().set_value(channel, value) -> bool

Set one channel by raw 12-bit value from 0 through 4095.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
value any positional or keyword Yes Required value.

pca9685.PCA9685().set_pulse_us(channel, pulse_us) -> bool

Set one channel by pulse width in microseconds.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
pulse_us int positional or keyword Yes Required value.

pca9685.PCA9685().set_servo(channel, angle, min_us=None, max_us=None, min_angle=None, max_angle=None) -> bool

Set a servo-style channel by angle.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
angle float positional or keyword Yes Required value.
min_us int positional or keyword No Optional value. Defaults to None.
max_us int positional or keyword No Optional value. Defaults to None.
min_angle any positional or keyword No Optional value. Defaults to None.
max_angle any positional or keyword No Optional value. Defaults to None.

pca9685.PCA9685().full_on(channel) -> bool

Force one channel fully on.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.

pca9685.PCA9685().full_off(channel) -> bool

Force one channel fully off.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.

pca9685.PCA9685().all_off() -> bool

Force every channel fully off.

pca9685.PCA9685().sleep(enabled=None) -> bool

Enter or leave sleep mode.

Parameters
Name Type Pass as Required Description
enabled bool positional or keyword No Optional value. Defaults to None.

pca9685.PCA9685().restart() -> bool

Restart PWM output after sleep or frequency changes.

pca9685.PCA9685().read_pwm(channel) -> dict

Read one channel's PWM registers.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.

pca9685.PCA9685().info() -> dict

Return controller configuration and register state.

pca9685.PCA9685().deinit() -> bool

Release this PCA9685 I2C device and bus.

pca9685.PCA9685().close() -> bool

Release this PCA9685 handle.

pca9685.PCA9685().Example

driver = pca9685.PCA9685(sda=21, scl=22) driver.set_servo(0, 90)

pca9685.begin(sda: int, scl: int, address: int = None, i2c_frequency: any = None, pwm_frequency: any = None, port: int = None, oscillator_hz: any = None, open_drain: bool = None, invert: bool = None) -> bool

Legacy: initialize the module-level default PCA9685 controller.

Prefer ``driver = pca9685.PCA9685(...)`` for new projects. The legacy wrapper keeps older singleton-style scripts working.

Parameters
Name Type Pass as Required Description
sda int positional or keyword Yes GPIO connected to I2C SDA.
scl int positional or keyword Yes GPIO connected to I2C SCL.
address int positional or keyword No Optional 7-bit I2C address. Defaults to 0x40.
i2c_frequency any positional or keyword No Optional I2C bus frequency in hertz. Defaults to 400000.
pwm_frequency any positional or keyword No Optional PWM output frequency in hertz. Defaults to 50, which is typical for hobby servos.
port int positional or keyword No Optional ESP-IDF I2C port. Defaults to 0.
oscillator_hz any positional or keyword No Optional PCA9685 oscillator frequency. Defaults to 25000000.
open_drain bool positional or keyword No Optional output driver mode. Defaults to False, which uses totem-pole output mode.
invert bool positional or keyword No Optional output polarity inversion. Defaults to False.
Returns

bool True when the controller is configured.

pca9685.set_pwm_frequency(frequency: int, oscillator_hz: float = None) -> bool

Set the shared PWM frequency for all channels.

Parameters
Name Type Pass as Required Description
frequency int positional or keyword Yes Output PWM frequency in hertz. Valid range is about 24 through 1526.
oscillator_hz float positional or keyword No Optional oscillator frequency used for prescale math. Defaults to the current oscillator setting.
Returns

bool True when the PRE_SCALE register was updated.

pca9685.set_pwm(channel: int, on: any, off: any) -> bool

Write raw 12-bit on/off ticks for one channel.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes PCA9685 channel from 0 through 15.
on any positional or keyword Yes Tick where the output turns on. Values are clamped to 0 through 4096.
off any positional or keyword Yes Tick where the output turns off. Values are clamped to 0 through 4096.
Returns

bool True when the channel registers were written.

pca9685.set_all_pwm(on: any, off: any) -> bool

Write raw on/off ticks to all channels.

Parameters
Name Type Pass as Required Description
on any positional or keyword Yes Tick where all outputs turn on.
off any positional or keyword Yes Tick where all outputs turn off.
Returns

bool True when the all-channel registers were written.

pca9685.set_duty(channel: int, duty: any) -> bool

Set one channel by normalized duty cycle.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes PCA9685 channel from 0 through 15.
duty any positional or keyword Yes Duty cycle from 0.0 through 1.0.
Returns

bool True when the channel output was updated.

pca9685.set_value(channel: int, value: any) -> bool

Set one channel by raw 12-bit PWM value.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes PCA9685 channel from 0 through 15.
value any positional or keyword Yes PWM value from 0 through 4095.
Returns

bool True when the channel output was updated.

pca9685.set_pulse_us(channel: int, pulse_us: int) -> bool

Set one channel by pulse width in microseconds.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes PCA9685 channel from 0 through 15.
pulse_us int positional or keyword Yes Pulse width in microseconds.
Returns

bool True when the pulse was converted to ticks and written.

pca9685.set_servo(channel: int, angle: float, min_us: int = None, max_us: int = None, min_angle: any = None, max_angle: any = None) -> bool

Set a servo-style channel by angle.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes PCA9685 channel from 0 through 15.
angle float positional or keyword Yes Requested angle in degrees.
min_us int positional or keyword No Optional pulse width for min_angle. Defaults to 500.
max_us int positional or keyword No Optional pulse width for max_angle. Defaults to 2500.
min_angle any positional or keyword No Optional minimum angle. Defaults to 0.
max_angle any positional or keyword No Optional maximum angle. Defaults to 180.
Returns

bool True when the servo pulse was written.

pca9685.full_on(channel: int) -> bool

Force one channel fully on.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes PCA9685 channel from 0 through 15.
Returns

bool True when the full-on bit was written.

pca9685.full_off(channel: int) -> bool

Force one channel fully off.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes PCA9685 channel from 0 through 15.
Returns

bool True when the full-off bit was written.

pca9685.all_off() -> bool

Force every channel fully off.

Returns

bool True when all channels were disabled.

pca9685.sleep(enabled: bool = None) -> bool

Enter or leave PCA9685 sleep mode.

Parameters
Name Type Pass as Required Description
enabled bool positional or keyword No Optional boolean. Defaults to True.
Returns

bool True when MODE1 was updated.

pca9685.restart() -> bool

Restart PWM output after sleep or frequency changes.

Returns

bool True when the restart bit was written.

pca9685.read_pwm(channel: int) -> dict

Read one channel's PWM registers.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes PCA9685 channel from 0 through 15.
Returns

dict Dict with ok, channel, on, off, duty, full_on, and full_off fields.

pca9685.info() -> dict

Return PCA9685 configuration and register state.

Returns

dict Dict with initialized, address, sda, scl, i2c_frequency, pwm_frequency, oscillator_hz, channels, mode1, mode2, and prescale.

pca9685.deinit() -> bool

Release the PCA9685 I2C device and bus.

Returns

bool True when resources were released.