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:

16 channels with 12-bit resolution
Refresh rates from 24 Hz to 1526 Hz with internal 25 MHz oscillator
Totem pole outputs with 25 mA as sink and 10 mA as source at 5V
Software programmable open-drain output selection
Inverted outputs
Active LOW Output Enable (OE) input pin
External clock input with max. 50 MHz

Usage

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

functions have the prefix pca9685_ and
functions require an additional parameter, the pointer to the PWM device of type pca9685_t.

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

enum 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

enum 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

enum 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]	dev	Device descriptor of the PCA9685 to be initialized
[in]	params	Configuration parameters, see pca9685_params_t

Return values

PCA9685_OK	on 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] dev Device 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]	dev	Device descriptor of the PCA9685
[in]	mode	PWM mode, left, right or center aligned
[in]	freq	PWM frequency in Hz [24...1526]
[in]	res	PWM resolution [2...4096], should be a power of two

Return values

>0	actual frequency on success
0	on 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] dev Device 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] dev Device 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]	dev	Device descriptor of the PCA9685
[in]	channel	Channel of PCA9685 to set, if PCA9685_CHANNEL_NUM all channels are set to the desired duty-cycle
[in]	value	Desired duty-cycle to set

Detailed Description

Overview

Usage

SAUL Capabilities

Files

Data Structures

Macros

Enumerations

Functions

PCA9685 I2C slave addresses

Enumeration Type Documentation

◆ pca9685_error_t

◆ pca9685_out_drv_t

◆ pca9685_out_ne_t

Function Documentation

◆ pca9685_init()

◆ pca9685_pwm_channels()

◆ pca9685_pwm_init()

◆ pca9685_pwm_poweroff()

◆ pca9685_pwm_poweron()

◆ pca9685_pwm_set()