PCA9685 - 16-Channel, 12-bit PWM Controller
Description
Library for interfacing NXP PCA9685 16-channel, 12-bit PWM controller for LED/SERVO/etc.
The PCA9685 is an I²C-bus controlled 16-channel LED controller optimized for Red/Green/Blue/Amber (RGBA) color backlighting applications. -) I2C interface with communication speed up to 1 MHz (I2C Fast Mode Plus) -) Six hardware address pins allow up to 62 devices on the same bus -) 4096 steps (12-bit PWM) of individual PWM (e.g. LED brightness) control
OVERVIEW
PCA9685_Abstract:
This library can be used to handle NXP 16-channel, 12-bit PWM controller for LED/SERVO/etc.
Interfaces: 1x I2C
The PCA9685 is an I²C-bus controlled 16-channel LED controller optimized for Red/Green/Blue/Amber (RGBA) color backlighting applications.
PCA9685_How_to_use:
/* Hardware setup */
const
{
PORT_I2C = 0, // The first I2C interface should be used.
CHIP_ADDR = PCA9685_I2C_ADR0, // I2C Address of the chip
// (depends on the logic level at the chip's A0 - A5 pins)
LED_OUTPUT = 0, // Selected LED Output
}
/* Handles for available sensors */
new hPCA[TPCA9685_Handle]; // Handle to manage the PCA9685
new ledPWM; // Current PWM duty cycle [%]
/* 1 sec. timer is used for the general program sequence */
#callback MainTimer()
{
/* toggle LED state (PWM duty cycle 0/100%) */
if(ledPWM)
ledPWM = 0; // Sets PWM duty cycle to 0% i.e. LED should be OFF
else
ledPWM = 100; // Sets PWM duty cycle to 0% i.e. LED should be always ON
catch(PCA9685_SetPWM(hPCA, LED_OUTPUT, ledPWM)); // Sets PWM output
}
main(){
// Init I2C interface
catch(rM2M_I2cInit(PORT_I2C, PCA9685_CLOCK, 0));
// Initializes i2c communication with the PCA9685 and prepares the PCA9685 for use
catch(PCA9685_Init(hPCA, PORT_I2C, CHIP_ADDR));
/* Activates the PCA9685 using the following configuration
-) Invert Output
-) Outputs change on STOP command (I2C)
-) Open-Drain output structure
-) Unused Output: high-z, OUTDRV = 0 (Open-Drain)
*/
new config2 = PCA9685_MODE2_OL_INVRT | PCA9685_MODE2_OCH_STOP | PCA9685_MODE2_OUTDRV_OD | PCA9685_MODE2_OUTNE_CFG;
catch(PCA9685_Enable(hPCA, config2));
/* turn OFF Led */
ledPWM = 0; // Sets PWM duty cycle to 0% i.e. LED should be OFF
catch(PCA9685_SetPWM(hPCA, LED_OUTPUT, ledPWM)); // Sets PWM output
// Initialisation of a cyclic sec. timer
setInterval(MainTimer, 1000);
}
BASIC
PCA9685_CLOCK -
typical I2C clock speed to be used (400kHz, I2C Fast-Mode)
PCA9685_I2C_ADRx:
Available PCA9685 I2C addresses
The corresponding I2C address must be used if the condition applies (A5 to A0) :
PCA9685_I2C_ADR0 - 0 0 0 0 0 0
PCA9685_I2C_ADR1 - 0 0 0 0 0 1
PCA9685_I2C_ADR2 - 0 0 0 0 1 0
PCA9685_I2C_ADR4 - 0 0 0 1 0 0
PCA9685_I2C_ADR5 - 0 0 0 1 0 1
PCA9685_I2C_ADR6 - 0 0 0 1 1 0
PCA9685_I2C_ADR7 - 0 0 0 1 1 1
PCA9685_I2C_ADR8 - 0 0 1 0 0 0
PCA9685_I2C_ADR9 - 0 0 1 0 0 1
PCA9685_I2C_ADR10 - 0 0 1 0 1 0
PCA9685_I2C_ADR11 - 0 0 1 0 1 1
PCA9685_I2C_ADR12 - 0 0 1 1 0 0
PCA9685_I2C_ADR13 - 0 0 1 1 0 1
PCA9685_I2C_ADR14 - 0 0 1 1 1 0
PCA9685_I2C_ADR15 - 0 0 1 1 1 1
PCA9685_I2C_ADR16 - 0 1 0 0 0 0
PCA9685_I2C_ADR17 - 0 1 0 0 0 1
PCA9685_I2C_ADR18 - 0 1 0 0 1 0
PCA9685_I2C_ADR19 - 0 1 0 0 1 1
PCA9685_I2C_ADR20 - 0 1 0 1 0 0
PCA9685_I2C_ADR21 - 0 1 0 1 0 1
PCA9685_I2C_ADR22 - 0 1 0 1 1 0
PCA9685_I2C_ADR23 - 0 1 0 1 1 1
PCA9685_I2C_ADR24 - 0 1 1 0 0 0
PCA9685_I2C_ADR25 - 0 1 1 0 0 1
PCA9685_I2C_ADR26 - 0 1 1 0 1 0
PCA9685_I2C_ADR27 - 0 1 1 0 1 1
PCA9685_I2C_ADR28 - 0 1 1 1 0 0
PCA9685_I2C_ADR29 - 0 1 1 1 0 1
PCA9685_I2C_ADR30 - 0 1 1 1 1 0
PCA9685_I2C_ADR31 - 0 1 1 1 1 1
PCA9685_I2C_ADR32 - 1 0 0 0 0 0
PCA9685_I2C_ADR33 - 1 0 0 0 0 1
PCA9685_I2C_ADR34 - 1 0 0 0 1 0
PCA9685_I2C_ADR35 - 1 0 0 0 1 1
PCA9685_I2C_ADR36 - 1 0 0 1 0 0
PCA9685_I2C_ADR37 - 1 0 0 1 0 1
PCA9685_I2C_ADR38 - 1 0 0 1 1 0
PCA9685_I2C_ADR39 - 1 0 0 1 1 1
PCA9685_I2C_ADR40 - 1 0 1 0 0 0
PCA9685_I2C_ADR41 - 1 0 1 0 0 1
PCA9685_I2C_ADR42 - 1 0 1 0 1 0
PCA9685_I2C_ADR43 - 1 0 1 0 1 1
PCA9685_I2C_ADR44 - 1 0 1 1 0 0
PCA9685_I2C_ADR45 - 1 0 1 1 0 1
PCA9685_I2C_ADR46 - 1 0 1 1 1 0
PCA9685_I2C_ADR47 - 1 0 1 1 1 1
1110 000 - reserved for PCA9685 LED All Call
PCA9685_I2C_ADR49 - 1 1 0 0 0 1
PCA9685_I2C_ADR50 - 1 1 0 0 1 0
PCA9685_I2C_ADR51 - 1 1 0 0 1 1
PCA9685_I2C_ADR52 - 1 1 0 1 0 0
PCA9685_I2C_ADR53 - 1 1 0 1 0 1
PCA9685_I2C_ADR54 - 1 1 0 1 1 0
PCA9685_I2C_ADR55 - 1 1 0 1 1 1
Do not use ADR56-ADR59 (1111 0XX) when devices that use the 10-bit addressing scheme are on the bus.
PCA9685_I2C_ADR56 - 1 1 1 0 0 0
PCA9685_I2C_ADR57 - 1 1 1 0 0 1
PCA9685_I2C_ADR58 - 1 1 1 0 1 0
PCA9685_I2C_ADR59 - 1 1 1 0 1 1
Do not use ADR60-ADR63 (1111 1XX) reserved for future use
PCA9685_I2C_ADR60 - 1 1 1 1 0 0
PCA9685_I2C_ADR61 - 1 1 1 1 0 1
PCA9685_I2C_ADR62 - 1 1 1 1 1 0
PCA9685_I2C_ADR63 - 1 1 1 1 1 1
I2C address is selected through input pins A0 to A5 (equal Bits 1 to 6 for I2C address). Bit 7 is fixed to 1, Bit 0 is R/W bit.
Not all of the possible addresses are allowed, see datasheet for more
information.
PCA9685_MODE1_x:
MODE1 configuration bits
PCA9685_MODE1_RESTART - bit7 (0x80):
Read: Shows state of RESTART logic.
Write: Write logic 1 to this bit to clear it to logic 0. Writing logic 0 will have no effect.
0 - Restart disabled (deflaut)
1 - Restart enabled
PCA9685_MODE1_EXTCLK - bit6 (0x40):
0 - Use internal clock (default)
1 - Use EXTCLK pin clock
To use the EXTCLK pin, this bit must be set by the following sequence:
- Set the SLEEP bit in MODE1. This turns off the internal oscillator.
- Write logic 1s to both the SLEEP and EXTCLK bits in MODE1. The switch is now made. The external clock can be active during the switch because the SLEEP bit is set.
This bit is a ‘sticky bit’, that is, it cannot be cleared by writing a logic 0 to it. The EXTCLK bit can only be cleared by a power cycle or software reset. EXTCLK range is DC to 50 MHz.
PCA9685_MODE1_AI - bit5 (0x20):
0 - Register Auto-Increment disabled (default)
1 - Register Auto-Increment enabled
When Auto Increment is enabled, the Control register is automatically incremented after a read or write. This allows the user to program the registers sequentially.
PCA9685_MODE1_SLEEP - bit4 (0x10):
0 - Normal mode
1 - Sleep Mode enabled (Oscillator off, default)
PCA9685_MODE1_SUB1 - bit3 (0x08):
0 - Does not respond to I2C-bus subaddress 1 (default)
1 - Respond to I2C-bus subaddress 1
PCA9685_MODE1_SUB2 - bit2 (0x04):
0 - Does not respond to I2C-bus subaddress 2 (defalut)
1 - Respond to I2C-bus subaddress 2
PCA9685_MODE1_SUB3 - bit1(0x02):
0 - Does not respond to I2C-bus subaddress 3 (defalut)
1 - Respond to I2C-bus subaddress 3
PCA9685_MODE1_ALLCALL - bit0 (0x01):
0 - Does not respond to LED All Call I2C Addresses
1 - Respond to LED All Call I2C Addresses (default)
PCA9685_MODE2_x:
MODE2 configuration bits
Output logic configuration (Bit 4):
Only when OE pin = 0
PCA9685_MODE2_OL_NORMAL - 0x00 | Output logic state not inverted (default).
Value to use when external driver used.
PCA9685_MODE2_OL_INVRT - 0x10 | Output logic state inverted.
Value to use when no external driver used.
Output change configuration (based on I2C communication) (Bit 3)
PCA9685_MODE2_OCH_STOP - 0x00 | Outputs change on STOP command (default).
Change of the outputs at the STOP command allows synchronizing outputs of more than one PCA9685. Applicable to registers from 0x06 (LED0_ON_L) to 0x45 (LED15_OFF_H) only.
1 or more registers can be written, in any order, before STOP.
PCA9685_MODE2_OCH_ACK - 0x08 | Outputs change on ACK.
Update on ACK requires all 4 PWM channel registers (LEDx_ON_L to LEDx_OFF_H) to be loaded before outputs will change on the last ACK
Output driver configuration (Bit 2)
PCA9685_MODE2_OUTDRV_OD - 0x00 | All outputs are configured with an open-drain structure.
PCA9685_MODE2_OUTDRV_TP - 0x04 | All outputs are configured with a totem pole structure (Default).
Configuration for output drivers not enabled (Bit 0-1)
Only when OE pin = 1
PCA9685_MODE2_OUTNE_LOW - 0x00 | LEDn = 0 (default)
PCA9685_MODE2_OUTNE_CFG - 0x01 | LEDn = 1 when OUTDRV = 1 (Totem Pole), high-z when OUTDRV = 0 (Open-Drain)
PCA9685_MODE2_OUTNE_HIZ - 0x02 | LEDn = high-z
PCA9685_UNIT_x:
Specifies which unit is used for the "unit" parameter of the "PCA9685_SetPWM()" function.
PCA9685_UNIT_PCT - % (default)
PCA9685_UNIT_0_1_PCT - 0.1%
PCA9685_UNIT_US - µs
PCA9685_Init(handle[TPCA9685_Handle], i2c, addr)
Initializes I2c communication with the PCA9685 and prepares the PCA9685 for use
Reads mode register 1 and 2 from the PCA9685 and stores the content of these registers in the transferred, empty device handle for a PCA9685. In addition, the default PWM frequency (f=200Hz, T=5ms) is also stored in the transferred, empty device handle.
All outputs are set to the same PWM frequency.
handle : TPCA9685_Handle - Empty device handle for a PAC9685
i2c : s32 - I2C interface where PCA9685 is connected to
The I2C interface must be initialisation before using rM2M_I2cInit().
addr : s32 - I2C Address of the chip (depends on the logic level at the chip's A0-A5 pins)
Use only the addresses specified under PCA9685_I2C_ADRx
returns : s32
OK - if successful
ERROR - if one of the following errors occurs
PCA9685_Enable(handle[TPCA9685_Handle], mode2)
Activates the PCA9685 by setting the "MODE1" and "MODE2" register
handle : TPCA9685_Handle - Device handle of a specific PCA9685 (Initialized by PCA9685_Init())
mode2 : s32 - Mode 2 configuration (Output logic / Output change / Output driver / Output drivers not enabled setting)
Use PCA9685_MODE2_x configuration bits
returns : s32
OK - if successful
ERROR - if one of the following errors occurs
PCA9685_SetPWMFreq(handle[TPCA9685_Handle], freq)
Sets PWM frequency at which all outputs modulate.
External clock is currently not supported
Since the "PRE_SCALE" register can only be set when sleep mode is active, the following sequence is executed:
handle : TPCA9685_Handle - Device handle of a specific PCA9685 (Initialized by PCA9685_Init())
freq : s32 - Desired PWM Frequency [Hz],
min. = 24Hz, max. = 1526Hzreturns : s32
OK - If successful
ERROR - if one of the following errors occurs
PCA9685_SetPWM(handle[TPCA9685_Handle], output, ton, unit=PCA9685_UNIT_PCT)
Sets PWM output i.e. controls turn-on time and duty cycle for a specific PWM output.
For all outputs the same PWM frequency is used which can be configured using PCA9685_SetPWMFreq().
handle : TPCA9685_Handle - Device handle of a specific PCA9685 (Initialized by PCA9685_Init())
output : s32 - Output, 0-15
ton : s32 - PWM ON Time (The unit used is determined via the "unit" parameter, defaul = %)
0 - Output is OFF
> 100% - Output is always ON (for unit ="%" or 0.1%)
> T - Output is always ON (for unit ="µs", default PWM freq = 200Hz)
unit - Unit used for ton (use PCA9685_UNIT_x)
returns : s32
OK - If successful
ERROR - if one of the following errors occurs
PCA9685_Disable(handle[TPCA9685_Handle])
Sets the PCA9685 into sleep mode (i.e. Oscillator is off) and thus grants minimum power consumption
The sleep mode is activated by setting the "SLEEP" bit. All other bits retain the state determined when PCA9685_Init() was called.
handle : TPCA9685_Handle - Device handle of a specific PCA9685 (Initialized by PCA9685_Init())
returns : s32
OK - If successful
ERROR - If any error occurs
EXPERT
PCA9685_CLOCK_MAX -
absolute maximum I2C clock speed (1MHz, I2C Fast-Mode Plus)
PCA9685_REG_x:
PCA9685 Register Addresses (Address | Default | Description)
PCA9685_REG_MODE1 - 0x00 | 0x11 |
Mode Register 1
PCA9685_REG_MODE2 - 0x01 | 0x04 |
Mode Register 2 (use PCA9685_Enable())
PCA9685_REG_SUBADR1 - 0x02 | 0xE2 |
I2C-bus subaddress 1 (use PCA9685_Write())
PCA9685_REG_SUBADR2 - 0x03 | 0xE4 |
I2C-bus subaddress 2 (use PCA9685_Write())
PCA9685_REG_SUBADR3 - 0x04 | 0xE8 |
I2C-bus subaddress 3 (use PCA9685_Write())
PCA9685_REG_ALLCALLADR - 0x05 | 0xE0 |
LED All Call I2C-bus address (use PCA9685_Write())
Use PCA9685_SetPWM()
PCA9685_REG_LED0_ON_L - 0x06 | 0x00 |
LED0 output and brightness control byte 0
Bit 0-7: LEDn_ON count for LED0, 8 LSBs
PCA9685_REG_LED0_ON_H - 0x07 | 0x00 |
LED0 output and brightness control byte 1
Bit 5-7: reserved
Bit 4: LED0 full ON
Bit 0-3: LEDn_ON count for LED0, 4 MSBs
PCA9685_REG_LED0_OFF_L - 0x08 | 0x00 |
LED0 output and brightness control byte 2
Bit 0-7: LEDn_OFF count for LED0, 8 LSBs
PCA9685_REG_LED0_OFF_H - 0x09 | 0x10 |
LED0 output and brightness control byte 3
Bit 5-7: reserved
Bit 4: LED0 full OFF
Bit 0-3: LEDn_OFF count for LED0, 4 MSBs
:
:
PCA9685_REG_LED15_ON_L - 0x42 | 0x00 |
LED15 output and brightness control byte 0
Bit 0-7: LEDn_ON count for LED15, 8 LSBs
PCA9685_REG_LED15_ON_H - 0x43 | 0x00 |
LED15 output and brightness control byte 1
Bit 5-7: reserved
Bit 4: LED15 full ON
Bit 0-3: LEDn_ON count for LED15, 4 MSBs
PCA9685_REG_LED15_OFF_L - 0x44 | 0x00 |
LED15 output and brightness control byte 2
Bit 0-7: LEDn_OFF count for LED15, 8 LSBs
PCA9685_REG_LED15_OFF_H - 0x45 | 0x10 |
LED15 output and brightness control byte 3
Bit 5-7: reserved
Bit 4: LED15 full OFF
Bit 0-3: LEDn_OFF count for LED15, 4 MSBs
PCA9685_REG_ALL_LED_ON_L - 0xFA | 0x00 |
load all the LEDn_ON registers, byte 0
Bit 0-7: LEDn_ON count for ALL_LED, 8 MSBs
PCA9685_REG_ALL_LED_ON_H - 0xFB | 0x10 |
load all the LEDn_ON registers, byte 1
Bit 5-7: reserved
Bit 4: ALL_LED full ON
Bit 0-3: LEDn_ON count for ALL_LED, 4 MSBs
PCA9685_REG_ALL_LED_OFF_L - 0xFC | 0x00 |
load all the LEDn_OFF registers, byte 0
Bit 0-7: LEDn_OFF count for ALL_LED, 8 MSBs
PCA9685_REG_ALL_LED_OFF_H - 0xFD | 0x10 |
load all the LEDn_OFF registers, byte 1
Bit 5-7: reserved
Bit 4: ALL_LED full OFF
Bit 0-3: LEDn_OFF count for ALL_LED, 4 MSBs
PCA9685_REG_PRE_SCALE - 0xFE | 0x1E |
Prescaler for PWM output frequency. It defines the frequency at which all outputs modulate. (use PCA9685_SetPWMFreq())
See datasheet for more information.
PCA9685_Read(handle[TPCA9685_Handle], iAddr, &iValue)
Reads the contents of a register from the PCA9685
handle : TPCA9685_Handle - Device handle of a specific PCA9685 (Initialized by PCA9685_Init())
iAddr : s32 - Register address (Use PCA9685_REG_x)
iValue : s32 - Buffer for storing the data read from the register
returns : s32
OK - If successful
ERROR - If an error occurs
PCA9685_Write(handle[TPCA9685_Handle], iAddr, iValue)
Writes the transferred data into the desired register of the PCA9685
handle : TPCA9685_Handle - Device handle of a specific PCA9685 (Initialized by PCA9685_Init())
iAddr : s32 - Register address (Use PCA9685_REG_x)
iValue : s32 - Data to be written to the register
returns : s32
OK - If successful
ERROR - If an error occurs
PCA9685_Com(handle[TPCA9685_Handle], aData{}, writeLen, readLen)
Executes an I2C communication with the PCA9685. Data is first of all sent and data is then received.
handle : TPCA9685_Handle - Device handle of a specific PCA9685 (Initialized by PCA9685_Init())
aData : {} - Array in which the data to be sent must initially be saved. Once the data has been sent, the array is used as a memory for the data to be received.
writeLen : s32 - Number of bytes to be sent
readLen : s32 - Number of bytes to be received
returns : s32
OK - if successful
ERROR - if one of the following errors occurs
PCA9685_SoftReset(iI2C)
Performs a reset of the PCA9685 using the "General Call" command through the I2C-bus, identical to the Power-On Reset (POR) that initializes the registers to their default state causing the outputs to be set LOW.
In order to be executed correctly, I2C-Bus must be functional
All devices on the same I2C bus that support the "General Call" will perform a reset.
handle : TPCA9685_Handle - Device handle of a specific PCA9685 (Initialized by PCA9685_Init())
returns : s32
OK - If successful
ERROR - If an error occurs
DEBUG
PCA9685_Debug_Config:
To configure debug mode add the following macro to the main.dde file.
/**
* Use this macro to configure the debug mode:
*
* 0: No debugging
*/
#define PCA9685_DEBUG 0