Pca9685Handler.h File Reference

Unified handler for the PCA9685 16-channel 12-bit PWM controller. More...

#include <cstdint>
#include <memory>
#include <array>
#include <cmath>
#include "base/BaseGpio.h"
#include "base/BasePwm.h"
#include "base/BaseI2c.h"
#include "core/hf-core-drivers/external/hf-pca9685-driver/inc/pca9685.hpp"
#include "RtosMutex.h"

Include dependency graph for Pca9685Handler.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	HalI2cPca9685Comm
	Concrete I2C communication adapter for PCA9685 using BaseI2c. More...
class	Pca9685PwmAdapter
	BasePwm adapter for all 16 PCA9685 PWM channels. More...
class	Pca9685GpioPin
	BaseGpio adapter for a single PCA9685 channel used as a digital output. More...
class	Pca9685Handler
	Unified, non-templated handler for a single PCA9685 PWM controller. More...

Detailed Description

Unified handler for the PCA9685 16-channel 12-bit PWM controller.

This file provides the complete HAL-level integration for a single PCA9685 PWM controller device. It bridges the HardFOC base interfaces (BaseI2c, BasePwm, BaseGpio) with the templated pca9685::PCA9685<I2cType> driver from the hf-pca9685-driver library.

Architecture Overview

The file contains four layers:

1. CRTP I2C Communication Adapter (HalI2cPca9685Comm): Bridges the HardFOC BaseI2c device-centric interface (where the I2C address is pre-configured on the device object) with the PCA9685 driver's CRTP-based pca9685::I2cInterface (which passes the address as a parameter). Includes address validation and thread-safe I2C operations.
2. Pca9685Handler (main class): Non-templated facade that owns a typed driver instance. Provides:
   • Lazy initialization with automatic device reset
   • Per-channel PWM control (duty cycle, raw tick values)
   • Global frequency control (24-1526 Hz)
   • Power management (sleep/wake)
   • Output configuration (invert, open-drain/totem-pole)
   • Error flag access and diagnostics
   • Factory methods for BasePwm and BaseGpio wrappers
3. Pca9685PwmAdapter (multi-channel BasePwm): Implements BasePwm for all 16 PWM channels, delegating to the parent handler. Supports duty cycle, frequency, phase shift (via on-time offset), and per-channel enable/disable (via full-on/full-off bits).
4. Pca9685GpioPin (per-pin BaseGpio wrapper): Implements BaseGpio for a single PCA9685 channel used as a digital output. HIGH = full-on, LOW = full-off. Output only (PCA9685 has no input capability).

Ownership Model

The handler owns all its internal resources:

• One HalI2cPca9685Comm (I2C communication adapter)
• One typed pca9685::PCA9685<HalI2cPca9685Comm> driver instance
• One Pca9685PwmAdapter (created on demand)
• Up to 16 Pca9685GpioPin wrappers (created on demand via pin registry)

External managers (PwmManager, GpioManager) obtain shared_ptr references via GetPwmAdapter() and CreateGpioPin().

Initialization Sequence

// 1. Obtain a BaseI2c device reference (address pre-configured, e.g. 0x40)
// 2. Construct the handler
Pca9685Handler handler(i2c_device);
 
// 3. Initialize (lazy -- happens automatically on first use, or explicitly)
if (!handler.EnsureInitialized()) { return; }
 
// 4. Set PWM frequency (affects all channels)
handler.SetFrequency(50);  // 50 Hz for servos
 
// 5a. Use as PWM via the adapter
auto pwm = handler.GetPwmAdapter();
pwm->SetDutyCycle(0, 0.5f);  // 50% duty on channel 0
 
// 5b. Or use as digital GPIO
auto pin = handler.CreateGpioPin(15);
pin->SetState(HF_GPIO_STATE_ACTIVE);  // Channel 15 fully on

Thread Safety

The handler uses RtosMutex for thread-safe access to:

• I2C communication (in the adapter's i2c_mutex_)
• All handler-level operations (handler_mutex_)

See also

GpioManager Manager that can own GPIO pin wrappers

pca9685::PCA9685 Templated driver from hf-pca9685-driver

Author

HardFOC Team

Date

2025