API Reference

qwiic_pca9685

Python module for the [SparkFun Pi Servo HAT](https://www.sparkfun.com/products/14328) and [SparkFun Servo pHAT for Raspberry Pi](https://www.sparkfun.com/products/15316) This package should be used in conjunction with the i2c_driver package contained in the [SparkFun qwiic Python Package](https://github.com/sparkfun/Qwiic_Py)

class qwiic_pca9685.QwiicPCA9685(address=None, debug=None, i2c_driver=None)[source]

SparkFunPCA9685 Initialise the PCA9685 chip at address with i2c_driver.

param address

The I2C address to use for the device. If not provided, the default address is used.

param i2c_driver

An existing i2c driver object. If not provided a driver object is created.

return

Constructor Initialization True- Successful False- Issue loading I2C driver

rtype

Bool

begin()[source]

This method checks if there is an I2C connection then enables the Auto-Increment bit for the writing/reading of words (for the output timing).

Returns

Function Operation True- Successful False- Issue in Execution

Return type

Bool

clear_restart_bit()[source]

If RESTART bit is a logic 1, it clears RESTART bit in MODE 1 register by writing a logic 1.

Returns

Value of RESTART bit after changes. 0- Restart Disabled (Default) 1- Restart Enabled

Return type

Integer

NOTE: Other actions that will clear the RESTART bit are:

  1. Power cycle.

  2. I2C Software Reset command.

  3. If the MODE2 OCH bit is logic 0, write to any PWM register then issue an I2C-bus STOP.

  4. If the MODE2 OCH bit is logic 1, write to all four PWM registers in any PWM channel.

Likewise, if the user does an orderly shutdown [1] of all the PWM channels before setting the SLEEP bit, the RESTART bit will be cleared. If this is done the contents of all PWM registers are invalidated and must be reloaded before reuse.

[1] Two methods can be used to do an orderly shutdown. The fastest is to write a logic 1 to bit 4 in register ALL_LED_OFF_H. The other method is to write logic 1 to bit 4 in each active PWM channel LEDn_OFF_H register.

enable_extclock_bit()[source]

Changes value of EXTCLK bit in MODE 1 register to enable EXTCLK pin. Once enabled, it allows for an external clock signal. It also affects the refresh rate:

EXTCLK

refresh_rate = ———————-

4096 x (prescale +1)

NOTE: This EXTCLK bit is a “sticky bit”, that is, it cannot be cleared by writing a logic 0 to it. The EXTCLK can only be cleared by a power cycle or software reset.

get_addr_bit(addr_bit=None)[source]

Reads value of specified address bit in MODE 1 register.

Parameters

addr_bit – Specify address bit. 0- ALLCALL Bit (Default) 1- SUB1 Bit 2- SUB2 Bit 3- SUB3 Bit

Returns

Value of specified address bit. 0- Normal Mode 1- Low Power Mode; Oscillator Off.

(Default)

Return type

Integer

get_auto_increment_bit()[source]

Reads value of AI bit in MODE 1 register. When enabled, it allows users to write of multiple bytes (i.e. words).

Returns

Value of AI bit. 0- Auto-Increment Disabled (Default) 1- Auto-Increment Enabled

Return type

Integer

get_channel_word(channel=None, on_off=None)[source]

Reads the ON/OFF timing for the specified PWM channel.

Parameters
  • channel – PWM channel. 0 to 16

  • on_off

    On or Off setting. 0- OFF Start timing (end of ON timing) 1- ON Start timing (anything greater than 0 is

    considered a delay)

Returns

Word (2 bytes)

NOTE: There are two 12-bit registers per LED output. Both registers will hold a value from 0 to 4095. One 12-bit register will hold a value for the ON time and the other 12-bit register will hold the value for the OFF time.

The ON and OFF times are compared with the value of a 12-bit counter that will be running continuously from 0000h to 0FFFh (0 to 4095 decimal).

get_extclock_bit()[source]

Reads value of EXTCLK bit in MODE 1 register. When enabled, it allows for an external clock signal. It also affects the refresh rate:

EXTCLK

refresh_rate = ———————-

4096 x (prescale +1)

Returns

Value of EXTCLK bit. 0- Use Internal Clock (Default) 1- Use EXTCLK Pin Clock.

Return type

Integer

NOTE: This bit is a “sticky bit”, that is, it cannot be cleared by writing a logic 0 to it. The EXTCLK can only be cleared by a power cycle or software reset.

get_invrt_bit()[source]

Reads value of INVRT bit in MODE 2 register. Determines how the outputs are driven. See Section 7.7 “Using the PCA9685 with and without external drivers” of the datasheet.

Returns

Value of INVRT bits. 0- Outputs change on STOP command. 1- Outputs change on ACK.

Return type

Integer

get_och_bit()[source]

Reads value of OCH bit in MODE 2 register. Determines when the outputs change.

Returns

Value of OCH bits. 0- Outputs change on STOP command.

NOTE: Change of the outputs at the STOP command allows synchronizing outputs of more than one PCA9685. Applicable to registers from 06h (LED0_ON_L) to 45h (LED15_OFF_H) only. 1 or more registers can be written, in any order, before STOP.

1- Outputs change on ACK.

NOTE: Update on ACK requires all 4 PWM channel registers to be loaded before outputs will change on the last ACK.

Return type

Integer

get_outdrv_bit()[source]

Reads value of OUTDRV bit in MODE 2 register. Determines how the outputs are driven.

Returns

Value of OUTDRV bits. 0- Outputs are configured with an open-drain

structure

1- Outputs are configured with a totem-pole

structure

Return type

Integer

get_outne_bits()[source]

Reads value of OUTNE bits in MODE 2 register. When the active LOW output (OE pin) is enabled, this setting allows users to enable or disable all the LED outputs at the same time.

Returns

Value of OUTNE bits. When OE = 1: 0- LEDn = 0 1- If OUTDRV = 1 then LEDn = 1

If OUTDRV = 0 then LEDn = high-impedence

(same as OUTNE[1:0] = b’10’)

2 to 3- LEDn = high-impedence

Return type

Integer

get_pre_scale()[source]

Reads the frequency at which the output are modulated. The prescale value is determined by Eq 1 (below).

Eq 1:

osc_clock

prescale value = round(———————-) - 1

(4096 * update_rate)

Returns

prescale_value

Return type

Integer

NOTE: Range: 24 Hz to 1526 Hz or (0x03 to 0xFF, Default: 0x1E = 200Hz).

get_restart_bit()[source]

Reads value of RESTART bit in MODE 1 register.

Returns

Value of Restart Mode bit. 0- Restart Disabled (Default) 1- Restart Enabled

Return type

Integer

get_sleep_bit()[source]

Reads value of SLEEP bit in MODE 1 register. When enabled, it the chip there is no PWM control.

Returns

Value of SLEEP bit. 0- Normal Mode 1- Low Power Mode; Oscillator Off. (Default)

Return type

Integer

is_connected()[source]

This method checks if the “i2c_driver” can connect to the device at the specified or default address.

Returns

Device Connection True- Successful False- Can’t find device

Return type

Bool

restart()[source]

Restarts the PCA9685 after the soft reset. (Clears MODE1 register.)

restart_pwm_channels()[source]

Restarts all of the previously active PWM channels with a few I2C-bus cycles.

Returns

Value of RESTART bit after changes. 0- Restart Disabled (Default) 1- Restart Enabled

Return type

Integer

NOTE: Only if the PCA9685 was operating and the user put the chip to sleep (setting MODE1 bit 4) without stopping any of the PWM channels, the RESTART bit (MODE1 bit 7) will be set to logic 1 at the end of the PWM refresh cycle. The contents of each PWM register are held valid when the clock is off.

Uses the following steps:

  1. Read MODE1 register.

  2. Check that bit 7 (RESTART) is a logic 1. If it is, clear bit 4 (SLEEP). Allow time for oscillator to stabilize (500us).

  3. Write logic 1 to bit 7 of MODE1 register. All PWM channels will restart and the RESTART bit will clear.

Remark: The SLEEP bit must be logic 0 for at least 500us, before a logic 1 is written into the RESTART bit.

set_addr_bit(addr_bit, value)[source]

Writes value to specified address bit in MODE 1 register.

Parameters
  • addr_bit – Specify address bit. 0- ALLCALL Bit 1- SUB1 Bit 2- SUB2 Bit 3- SUB3 Bit

  • value

    Specify address bit. 0- Disables specified address (Default on

    SUB1, SUB2, SUB3)

    1- Enables specified address (Default on

    ALLCALL)

set_auto_increment_bit(value=None)[source]

Changes value of AI bit in MODE 1 register. When enabled, it allows users to write of multiple bytes (i.e. words).

Parameters

value – Value to set AI bit. 0- Auto-Increment Disabled (Default) 1- Auto-Increment Enabled

set_channel_word(channel=None, on_off=None, value=None)[source]

Configures the on/off timing for the specified PWM channel.

Parameters
  • channel – PWM channel. 0 to 16

  • on_off

    ON/OFF setting. 0- OFF Start timing (end of ON timing) 1- ON Start timing (anything greater than 0 is

    considered a delay)

  • value – Value to be entered into the ON/OFF 12-bit register for the specified LED output. Word (2 bytes)

Returns

Function Operation True- Successful False- Issue in Execution

Return type

Bool

NOTE: There are two 12-bit registers per LED output. Both registers will hold a value from 0 to 4095. One 12-bit register will hold a value for the ON time and the other 12-bit register will hold the value for the OFF time.

The ON and OFF times are compared with the value of a 12-bit counter that will be running continuously from 0000h to 0FFFh (0 to 4095 decimal).

set_invrt_bit(value=None)[source]

Configures value of INVRT bits in MODE 2 register. Configures how the outputs are driven. See Section 7.7 “Using the PCA9685 with and without external drivers” of the datasheet.

Parameters

value – Value of INVRT bits. 0- Outputs change on STOP command. 1- Outputs change on ACK.

set_och_bit(value=None)[source]

Reads value of OCH bits in MODE 2 register. Configures when the outputs change.

Parameters

value

Value of OCH bits. 0- Outputs change on STOP command.

NOTE: Change of the outputs at the STOP command allows synchronizing outputs of more than one PCA9685. Applicable to registers from 06h (LED0_ON_L) to 45h (LED15_OFF_H) only. 1 or more registers can be written, in any order, before STOP.

1- Outputs change on ACK.

NOTE: Update on ACK requires all 4 PWM channel registers to be loaded before outputs will change on the last ACK.

set_outdrv_bit(value=None)[source]

Reads value of OUTDRV bits in MODE 2 register. Configures how the outputs are driven.

Parameters

value

Value of OUTDRV bits. 0- Outputs are configured with an open-drain

structure

1- Outputs are configured with a totem-pole

structure

set_outne_bit(value=None)[source]

Reads value of OUTNE bits in MODE 2 register. When the active LOW output (OE pin) is enabled, this setting allows users to enable or disable all the LED outputs at the same time.

Parameters

value

Value of OUTNE bits. When OE = 1: 0- LEDn = 0 1- If OUTDRV = 1 then LEDn = 1

If OUTDRV = 0 then LEDn = high-impedence

(same as OUTNE[1:0] = b’10’)

2 to 3- LEDn = high-impedence

Returns

Function Operation True- Successful False- Issue in Execution

Return type

Bool

set_pre_scale(frequency=None, ext=None)[source]

Configures the ‘prescale_value’, which defines the frequency at which the output are modulated. The prescale value is determined by Eq 1 (below). Additionally, the hardware enforces a minimum value that can be loaded into this register is ‘3’.

Eq 1:

osc_clock

prescale value = round(———————-) - 1

(4096 * update_rate)

Parameters
  • frequency – PWM Frequency (Hz) Range: 24 to 1526 Hz

  • ext – External Clock Frequency (Hz) Default = None; uses internal clock frequency (25 MHz)

Returns

Function Operation True- Successful False- Issue in Execution

Return type

Bool

PWM Frequency Range: 24 Hz to 1526 Hz or (0x03 to 0xFF, Default: 0x1E = 200Hz) Internal Clock: 25 MHz (Default)

set_sleep_bit(value=None)[source]

Changes value of SLEEP bit in MODE 1 register.

Parameters

value – Value to set SLEEP bit. 0- Normal Mode 1- Low Power Mode; Oscillator Off. (Default)

soft_reset()[source]

Software Resset Call: Allows all the devices in the I2C bus to be reset to the power-up state value through a specific formatted I2C bus command.

General Call Address
SWRST data byte 1
Start | | Stop
| | |
[S][0000 0000][A][0000 0110][A][P]
Acknowldege from Slave |

Acknowldege from Slave

PCA9685 then resets to the default value (power-up value) and is ready to be addressed again within the specified bus free time. A falure or non-acknowledge from the PCA9685 (at any time) should be interpreted as a “SWRST Call Abort”.

write_restart_bit(value=None)[source]

Writes values to RESTART bit in MODE 1 register.

Parameters

value – Value to write to Restart Mode bit. 0 or 1

Returns

Value of RESTART bit after changes. 0- Restart Disabled (Default) 1- Restart Enabled

Return type

Integer

NOTE: Value aren’t set, just written. The bit is set by the state of the chip and its current operation.