Device driver for the NXP PCA9685. More...

Detailed Description

Device driver for the NXP PCA9685.

Overview

The driver supports the NXP PCA9685 16-channel, 12-bit PWM LED controller connected to I2C. Although the controller is optimized for LED control, the 12-bit resolution also allows the control of servos with a resolution of 4 us at 60 Hz refresh signal.

The following features of the PCA9685 are supported by the driver:

Usage

The driver interface is kept as compatible as possible with the peripheral PWM interface. The only differences are that

Please refer the test application in tests/driver_pca9685 for an example on how to use the driver.

SAUL Capabilities

The driver provides SAUL capabilities that are compatible to the SAUL actuators of type SAUL_ACT_SERVO.

Each PCA9685 channel can be mapped directly to SAUL by defining an according entry in PCA9685_SAUL_PWM_PARAMS. Please refer file $RIOTBASE/drivers/pca9685/include/pca9685_params.h for an example.

 pca9685_saul_pwm_params_t pca9685_saul_pwm_params[] = {
     {
         .name = "PCA9685-0:0",
         .dev = 0,
         .channel = 0,
         .initial = (PCA9685_PARAM_RES >> 1),
      },
     {
         .name = "PCA9685-0:1",
         .dev = 0,
         .channel = 1,
         .initial = (PCA9685_PARAM_RES >> 2),
      },
     {
         .name = "PCA9685-0:2",
         .dev = 0,
         .channel = 2,
         .initial = (PCA9685_PARAM_RES >> 3),
      },
 };

For each PWM channel that should be used with SAUL, an entry with a name, the device, the channel, and the initial value has to be defined as shown above.

Author
Gunar Schorcht gunar.nosp@m.@sch.nosp@m.orcht.nosp@m..net

Files

file  pca9685.h
 
file  pca9685_params.h
 Default configuration for the PCA9685 I2C PWM controller.
 
file  pca9685_regs.h
 Register definitions for the PCA9685 I2C PWM controller.
 

Data Structures

struct  pca9685_params_t
 PCA9685 device initialization parameters. More...
 
struct  pca9685_t
 PCA9685 PWM device data structure type. More...
 
struct  pca9685_saul_pwm_params_t
 PCA9685 configuration structure for mapping PWM channels to SAUL. More...
 

Macros

#define PCA9685_CHANNEL_NUM   (16U)
 Number of PWM channels provided by PCA9685.
 
#define PCA9685_RESOLUTION   (1 << 12)
 Internal PCA9685 channel resolution is 12-bit.
 
#define PCA9685_OSC_FREQ   (25000000)
 Internal PCA9685 oscilator frequency is 25 MHz.
 
#define PCA9685_EXT_FERQ_MAX   (50000000)
 Maximum external clock frequency is 50 MHz.
 

Enumerations

enum  pca9685_error_t { PCA9685_OK = 0, PCA9685_ERROR_I2C = 1 }
 PCA9685 driver error codes. More...
 
enum  pca9685_out_drv_t { PCA9685_OPEN_DRAIN = 0, PCA9685_TOTEM_POLE = 1 }
 PCA9685 output driver mode. More...
 
enum  pca9685_out_ne_t { PCA9685_OFF = 0, PCA9685_OUT_DRV = 1, PCA9685_HIHGH_Z = 2 }
 PCA9685 output-not-enabled mode. More...
 

Functions

int pca9685_init (pca9685_t *dev, const pca9685_params_t *params)
 Initialize the PCA9685 PWM device driver. More...
 
uint32_t pca9685_pwm_init (pca9685_t *dev, pwm_mode_t mode, uint32_t freq, uint16_t res)
 Initialize the PCA9685 PWM device. More...
 
void pca9685_pwm_set (pca9685_t *dev, uint8_t channel, uint16_t value)
 Set the duty-cycle for a given channel or all channels of the given PCA9685 PWM device. More...
 
void pca9685_pwm_poweron (pca9685_t *dev)
 Resume PWM generation on the given PCA9685 device. More...
 
void pca9685_pwm_poweroff (pca9685_t *dev)
 Stop the PWM generation on the given PCA9685 device. More...
 
static uint8_t pca9685_pwm_channels (pca9685_t *dev)
 Get the number of available channels of the given PCA9685 device. More...
 

PCA9685 I2C slave addresses

PCA9685 offers 64 possible hardware-programmable I2C slave addresses.

Therefore the I2C slave address is defined as an offset in the range from 0 to 63 to a base address PCA9685_I2C_BASE_ADDR. PCA9685 I2C slave addresses are then in the range from PCA9685_I2C_BASE_ADDR + 0 to PCA9685_I2C_BASE_ADDR + 63

Four I2C slave addresses have special meaning when they are enabled, the All Call address (enabled by default) and three Sub Call addresses disabled by default). These addresses can be used to address either all or sub groups of PCF9695 controllers at the same time.

#define PCA9685_I2C_BASE_ADDR   (0x40)
 I2C slave base address.
 
#define PCA9685_I2C_ALLCALLADDR   (0x70)
 Default All Call address.
 
#define PCA9685_I2C_SUBADR1   (0x71)
 Default Sub Call address 1.
 
#define PCA9685_I2C_SUBADR2   (0x72)
 Default Sub Call address 2.
 
#define PCA9685_I2C_SUBADR3   (0x73)
 Default Sub Call address 3.
 

Enumeration Type Documentation

◆ pca9685_error_t

PCA9685 driver error codes.

Enumerator
PCA9685_OK 

Success.

PCA9685_ERROR_I2C 

I2C communication error.

Definition at line 145 of file pca9685.h.

◆ pca9685_out_drv_t

PCA9685 output driver mode.

The output driver mode defines how the outputs are configured.

Enumerator
PCA9685_OPEN_DRAIN 

Open-drain structure output.

PCA9685_TOTEM_POLE 

Totem pole structure output.

Definition at line 155 of file pca9685.h.

◆ pca9685_out_ne_t

PCA9685 output-not-enabled mode.

The output-not-enabled mode defines how the outputs behave when the active LOW output enable pin /OE is HIGH.

Enumerator
PCA9685_OFF 

If /OE pin is HIGH, outputs are LOW.

PCA9685_OUT_DRV 

Outputs depend on the output driver mode pca9685_params_t::out_drv.

If /OE pin is HIGH, it is high-impedance for PCA9685_OPEN_DRAIN, and HIGH for PCA9685_TOTEM_POLE

PCA9685_HIHGH_Z 

If /OE pin is HIGH, outputs are high-impedance.

Definition at line 166 of file pca9685.h.

Function Documentation

◆ pca9685_init()

int pca9685_init ( pca9685_t dev,
const pca9685_params_t params 
)

Initialize the PCA9685 PWM device driver.

The function initializes the driver. After calling this function, the PWM device is in low-power sleep mode (powered off), all outputs off. Before the PWM device can be used, it has to be initialized with pca9685_pwm_init.

Parameters
[in]devDevice descriptor of the PCA9685 to be initialized
[in]paramsConfiguration parameters, see pca9685_params_t
Return values
PCA9685_OKon success
PCA9685_ERROR_*a negative error code on error, see pca9685_error_t

◆ pca9685_pwm_channels()

static uint8_t pca9685_pwm_channels ( pca9685_t dev)
inlinestatic

Get the number of available channels of the given PCA9685 device.

Parameters
[in]devDevice descriptor of the PCA9685
Returns
Number of channels available

Definition at line 311 of file pca9685.h.

◆ pca9685_pwm_init()

uint32_t pca9685_pwm_init ( pca9685_t dev,
pwm_mode_t  mode,
uint32_t  freq,
uint16_t  res 
)

Initialize the PCA9685 PWM device.

The function initializes the PWM device with the given parameters that are used for all channels. After calling this function, the PWM device is operational (powered on). That is, all outputs are active with the given parameters and the same duty cycle value as before the call.

Note
  • PCA9685 works with internally with a resolution of 12 bit = 4096. Using a resolution that is not a power of two, will cause inaccuracy due to alignment errors when scaling down the internal resolution to the configured resolution.
  • Frequencies from 24 Hz to 1526 Hz can be used with PCF9865.
Parameters
[in]devDevice descriptor of the PCA9685
[in]modePWM mode, left, right or center aligned
[in]freqPWM frequency in Hz [24...1526]
[in]resPWM resolution [2...4096], should be a power of two
Return values
>0actual frequency on success
0on error

◆ pca9685_pwm_poweroff()

void pca9685_pwm_poweroff ( pca9685_t dev)

Stop the PWM generation on the given PCA9685 device.

This function switches the PCA9685 into sleep mode which turns off the internal oscillator. This disables the PWM generation on all configured. If the active LOW output enable pin /OE is used, the signal is set to HIGH. Dependent on the pca9685_params_t::out_drv and pca9685_params_t::out_ne parameters, the outputs are set 0, 1 or high-impedance. All channel duty-cycle values are preserved.

Parameters
[in]devDevice descriptor of the PCA9685

◆ pca9685_pwm_poweron()

void pca9685_pwm_poweron ( pca9685_t dev)

Resume PWM generation on the given PCA9685 device.

When this function is called, the given PWM device is powered on and continues its previously configured operation. The duty cycle of each channel will be the value that was last set.

This function must not be called before the PWM device was initialized.

Parameters
[in]devDevice descriptor of the PCA9685

◆ pca9685_pwm_set()

void pca9685_pwm_set ( pca9685_t dev,
uint8_t  channel,
uint16_t  value 
)

Set the duty-cycle for a given channel or all channels of the given PCA9685 PWM device.

The duty-cycle is set in relation to the chosen resolution of the given device. If value > resolution, value is set to resolution.

If the given channel is PCA9685_CHANNEL_NUM, all channels are set to the same duty cycle at the same time with only one I2C bus access.

Parameters
[in]devDevice descriptor of the PCA9685
[in]channelChannel of PCA9685 to set, if PCA9685_CHANNEL_NUM all channels are set to the desired duty-cycle
[in]valueDesired duty-cycle to set