Unified, non-templated handler for a single PCA9685 PWM controller. More...

#include <Pca9685Handler.h>

Collaboration diagram for Pca9685Handler:

Public Types
Type Aliases
using	Pca9685Driver = pca9685::PCA9685<HalI2cPca9685Comm>
	Typed PCA9685 driver using our I2C adapter.

Public Member Functions
Construction and Destruction
	Pca9685Handler (BaseI2c &i2c_device) noexcept
	Construct a handler for a PCA9685 device.

	~Pca9685Handler () noexcept=default
	Destructor. Releases driver, adapter, and all wrappers.

	Pca9685Handler (const Pca9685Handler &)=delete
	Non-copyable.

Pca9685Handler &	operator= (const Pca9685Handler &)=delete
	Non-copyable.

	Pca9685Handler (Pca9685Handler &&)=delete
	Non-movable.

Pca9685Handler &	operator= (Pca9685Handler &&)=delete
	Non-movable.

Initialization and Lifecycle
bool	EnsureInitialized () noexcept
	Ensure the handler is initialized (lazy initialization).

bool	EnsureDeinitialized () noexcept
	Deinitialize the handler and release resources.

bool	IsInitialized () const noexcept
	Check if the handler has been initialized.

Error Management
uint16_t	GetErrorFlags () const noexcept
	Get the driver's error flags.

void	ClearErrorFlags (uint16_t mask=0xFFFF) noexcept
	Clear driver error flags.

Diagnostics
void	DumpDiagnostics () const noexcept
	Dump comprehensive diagnostics to the system log.

Direct Driver Access
Pca9685Driver *	GetDriver () noexcept
	Get the underlying PCA9685 driver for advanced register-level operations.

const Pca9685Driver *	GetDriver () const noexcept

Private Member Functions
bool	ensureInitializedLocked () noexcept
	Check init under already-held handler_mutex_.

hf_pwm_err_t	initializeInternal () noexcept
	Internal initialization (called under mutex).

hf_pwm_err_t	deinitializeInternal () noexcept
	Internal deinitialization.

bool	validateChannel (uint8_t channel) const noexcept
	Validate channel number (0-15).

bool	SetFrequency (float freq_hz) noexcept

bool	SetDuty (uint8_t channel, float duty) noexcept

bool	SetPwm (uint8_t channel, uint16_t on_time, uint16_t off_time) noexcept

bool	SetAllPwm (uint16_t on_time, uint16_t off_time) noexcept

bool	SetChannelFullOn (uint8_t channel) noexcept

bool	SetChannelFullOff (uint8_t channel) noexcept

bool	Sleep () noexcept

bool	Wake () noexcept

bool	SetOutputInvert (bool invert) noexcept

bool	SetOutputDriverMode (bool totem_pole) noexcept

Private Attributes
Core Components
BaseI2c &	i2c_device_
	I2C device reference (not owned).

std::unique_ptr< HalI2cPca9685Comm >	i2c_adapter_
	I2C adapter (created in init).

std::unique_ptr< Pca9685Driver >	pca9685_driver_
	Typed driver (created in init).

bool	initialized_ = false
	Initialization state.

RtosMutex	handler_mutex_
	Thread safety for all operations.

Wrapper Registry
std::shared_ptr< Pca9685PwmAdapter >	pwm_adapter_
	PWM adapter (lazy).

std::array< std::shared_ptr< Pca9685GpioPin >, 16 >	gpio_registry_
	GPIO pin registry.

Friends
class	Pca9685PwmAdapter
	Allow wrapper classes to access private driver.

class	Pca9685GpioPin

Wrapper Factories
Create BasePwm and BaseGpio wrappers for manager-layer usage.
uint8_t	GetI2cAddress () const noexcept
	Get the I2C address of the underlying device.

std::shared_ptr< BasePwm >	GetPwmAdapter () noexcept
	Get or create the BasePwm adapter for all 16 channels.

std::shared_ptr< BaseGpio >	CreateGpioPin (hf_pin_num_t channel, hf_gpio_active_state_t active_state=hf_gpio_active_state_t::HF_GPIO_ACTIVE_HIGH, bool allow_existing=true) noexcept
	Create or retrieve a BaseGpio pin wrapper for a channel.

std::shared_ptr< BaseGpio >	GetGpioPin (hf_pin_num_t channel) noexcept
	Get an existing GPIO pin wrapper by channel number.

bool	IsPinCreated (hf_pin_num_t channel) const noexcept
	Check if a GPIO pin wrapper has been created for a channel.

static constexpr uint8_t	ChannelCount () noexcept
	Total number of PWM channels.

Detailed Description

Unified, non-templated handler for a single PCA9685 PWM controller.

Pca9685Handler is the primary interface that application and manager code uses to interact with a PCA9685 PWM controller. It hides the template complexity of pca9685::PCA9685<I2cType> behind a clean public API.

Design Decisions

Non-templated: The handler owns a concrete typed driver instance (pca9685::PCA9685<HalI2cPca9685Comm>) internally. Since only one I2C communication type is used per handler, no dispatch mechanism is needed.
Lazy initialization: The driver and adapter are created in Initialize(), not in the constructor.
Dual-purpose channels: Each channel can be used as either:
- A PWM output (via the Pca9685PwmAdapter / BasePwm interface)
- A digital output (via Pca9685GpioPin / BaseGpio interface) Using both simultaneously for the same channel is allowed but the last write wins.

See also: HalI2cPca9685Comm I2C communication adapter; Pca9685PwmAdapter Multi-channel BasePwm wrapper; Pca9685GpioPin Per-channel BaseGpio wrapper

Member Typedef Documentation

◆ Pca9685Driver

using Pca9685Handler::Pca9685Driver = pca9685::PCA9685<HalI2cPca9685Comm>

Typed PCA9685 driver using our I2C adapter.

Constructor & Destructor Documentation

◆ Pca9685Handler() [1/3]

Pca9685Handler::Pca9685Handler ( BaseI2c & i2c_device )

explicitnoexcept

Construct a handler for a PCA9685 device.

The I2C adapter and driver are not created until EnsureInitialized() or the first operation that requires them.

Parameters

i2c_device Reference to a BaseI2c device with address pre-configured (typically 0x40-0x7F). Must outlive the handler.

◆ ~Pca9685Handler()

Pca9685Handler::~Pca9685Handler ( )

defaultnoexcept

Destructor. Releases driver, adapter, and all wrappers.

◆ Pca9685Handler() [2/3]

Pca9685Handler::Pca9685Handler ( const Pca9685Handler & )

delete

Non-copyable.

◆ Pca9685Handler() [3/3]

Pca9685Handler::Pca9685Handler ( Pca9685Handler && )

delete

Non-movable.

Member Function Documentation

◆ ChannelCount()

static constexpr uint8_t Pca9685Handler::ChannelCount ( )

inlinestaticconstexprnoexcept

Total number of PWM channels.

◆ ClearErrorFlags()

void Pca9685Handler::ClearErrorFlags ( uint16_t mask = 0xFFFF )

noexcept

Clear driver error flags.

Parameters

mask	Bitmask of flags to clear (default: all).

◆ CreateGpioPin()

std::shared_ptr< BaseGpio > Pca9685Handler::CreateGpioPin	(	hf_pin_num_t	channel,
		hf_gpio_active_state_t	active_state = hf_gpio_active_state_t::HF_GPIO_ACTIVE_HIGH,
		bool	allow_existing = true )

noexcept

Create or retrieve a BaseGpio pin wrapper for a channel.

Uses the channel as a digital output (fully on / fully off). If a wrapper for the channel already exists and allow_existing is true, the existing instance is returned.

Parameters

channel	Channel number (0-15).
active_state	Active polarity (default: active high).
allow_existing	If true, returns existing wrapper; if false, fails if exists.

Returns: shared_ptr<BaseGpio> or nullptr on failure.

◆ deinitializeInternal()

hf_pwm_err_t Pca9685Handler::deinitializeInternal ( )

privatenoexcept

Internal deinitialization.

Here is the caller graph for this function:

◆ DumpDiagnostics()

void Pca9685Handler::DumpDiagnostics ( ) const

noexcept

Dump comprehensive diagnostics to the system log.

Here is the call graph for this function:

◆ EnsureDeinitialized()

bool Pca9685Handler::EnsureDeinitialized ( )

noexcept

Deinitialize the handler and release resources.

Returns: true if already deinitialized or deinitialization succeeded.

Here is the call graph for this function:

◆ EnsureInitialized()

bool Pca9685Handler::EnsureInitialized ( )

noexcept

Ensure the handler is initialized (lazy initialization).

On first call, creates the I2C adapter and driver, runs the driver's EnsureInitialized() (which resets the device).

Returns: true if already initialized or initialization succeeded.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ensureInitializedLocked()

bool Pca9685Handler::ensureInitializedLocked ( )

privatenoexcept

Check init under already-held handler_mutex_.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetDriver() [1/2]

const Pca9685Handler::Pca9685Driver * Pca9685Handler::GetDriver ( ) const

noexcept

Here is the call graph for this function:

◆ GetDriver() [2/2]

Pca9685Handler::Pca9685Driver * Pca9685Handler::GetDriver ( )

noexcept

Get the underlying PCA9685 driver for advanced register-level operations.

Returns: Pointer to the CRTP driver, or nullptr if not initialized.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetErrorFlags()

uint16_t Pca9685Handler::GetErrorFlags ( ) const

noexcept

Get the driver's error flags.

Returns: 16-bit error flag bitmask (see pca9685::PCA9685::Error enum).

◆ GetGpioPin()

std::shared_ptr< BaseGpio > Pca9685Handler::GetGpioPin ( hf_pin_num_t channel )

noexcept

Get an existing GPIO pin wrapper by channel number.

Parameters

channel Channel number (0-15).

Returns: shared_ptr<BaseGpio> or nullptr if not created.

◆ GetI2cAddress()

uint8_t Pca9685Handler::GetI2cAddress ( ) const

noexcept

Get the I2C address of the underlying device.

Returns: 7-bit I2C address, or 0 if driver not created.

◆ GetPwmAdapter()

std::shared_ptr< BasePwm > Pca9685Handler::GetPwmAdapter ( )

noexcept

Get or create the BasePwm adapter for all 16 channels.

The adapter is created on first call and cached. Subsequent calls return the same shared_ptr.

Returns: shared_ptr<BasePwm> or nullptr on failure.

Here is the call graph for this function:

◆ initializeInternal()

hf_pwm_err_t Pca9685Handler::initializeInternal ( )

privatenoexcept

Internal initialization (called under mutex).

Here is the caller graph for this function:

◆ IsInitialized()

bool Pca9685Handler::IsInitialized ( ) const

inlinenoexcept

Check if the handler has been initialized.

Returns: true if initialized, false otherwise.

Here is the caller graph for this function:

◆ IsPinCreated()

bool Pca9685Handler::IsPinCreated ( hf_pin_num_t channel ) const

noexcept

Check if a GPIO pin wrapper has been created for a channel.

Parameters

channel Channel number (0-15).

Returns: true if the wrapper exists in the registry.

◆ operator=() [1/2]

Pca9685Handler & Pca9685Handler::operator= ( const Pca9685Handler & )

delete

Non-copyable.

◆ operator=() [2/2]

Pca9685Handler & Pca9685Handler::operator= ( Pca9685Handler && )

delete

Non-movable.

◆ SetAllPwm()

bool Pca9685Handler::SetAllPwm	(	uint16_t	on_time,
		uint16_t	off_time )

privatenoexcept

◆ SetChannelFullOff()

bool Pca9685Handler::SetChannelFullOff ( uint8_t channel )

privatenoexcept

Here is the caller graph for this function:

◆ SetChannelFullOn()

bool Pca9685Handler::SetChannelFullOn ( uint8_t channel )

privatenoexcept

Here is the caller graph for this function:

◆ SetDuty()

bool Pca9685Handler::SetDuty	(	uint8_t	channel,
		float	duty )

privatenoexcept

◆ SetFrequency()

bool Pca9685Handler::SetFrequency ( float freq_hz )

privatenoexcept

◆ SetOutputDriverMode()

bool Pca9685Handler::SetOutputDriverMode ( bool totem_pole )

privatenoexcept

◆ SetOutputInvert()

bool Pca9685Handler::SetOutputInvert ( bool invert )

privatenoexcept

◆ SetPwm()

bool Pca9685Handler::SetPwm	(	uint8_t	channel,
		uint16_t	on_time,
		uint16_t	off_time )

privatenoexcept

◆ Sleep()

bool Pca9685Handler::Sleep ( )

privatenoexcept

Here is the call graph for this function:

Here is the caller graph for this function:

◆ validateChannel()

bool Pca9685Handler::validateChannel ( uint8_t channel ) const

inlineprivatenoexcept

Validate channel number (0-15).

◆ Wake()

bool Pca9685Handler::Wake ( )

privatenoexcept

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ Pca9685GpioPin

friend class Pca9685GpioPin

friend

◆ Pca9685PwmAdapter

friend class Pca9685PwmAdapter

friend

Allow wrapper classes to access private driver.

Member Data Documentation

◆ gpio_registry_

std::array<std::shared_ptr<Pca9685GpioPin>, 16> Pca9685Handler::gpio_registry_

private

GPIO pin registry.

◆ handler_mutex_

RtosMutex Pca9685Handler::handler_mutex_

mutableprivate

Thread safety for all operations.

◆ i2c_adapter_

std::unique_ptr<HalI2cPca9685Comm> Pca9685Handler::i2c_adapter_

private

I2C adapter (created in init).

◆ i2c_device_

BaseI2c& Pca9685Handler::i2c_device_

private

I2C device reference (not owned).

◆ initialized_

bool Pca9685Handler::initialized_ = false

private

Initialization state.

◆ pca9685_driver_

std::unique_ptr<Pca9685Driver> Pca9685Handler::pca9685_driver_

private

Typed driver (created in init).

◆ pwm_adapter_

std::shared_ptr<Pca9685PwmAdapter> Pca9685Handler::pwm_adapter_

private

PWM adapter (lazy).

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Friends

Wrapper Factories

Detailed Description

Design Decisions

Member Typedef Documentation

◆ Pca9685Driver

Constructor & Destructor Documentation

◆ Pca9685Handler() [1/3]

◆ ~Pca9685Handler()

◆ Pca9685Handler() [2/3]

◆ Pca9685Handler() [3/3]

Member Function Documentation

◆ ChannelCount()

◆ ClearErrorFlags()

◆ CreateGpioPin()

◆ deinitializeInternal()

◆ DumpDiagnostics()

◆ EnsureDeinitialized()

◆ EnsureInitialized()

◆ ensureInitializedLocked()

◆ GetDriver() [1/2]

◆ GetDriver() [2/2]

◆ GetErrorFlags()

◆ GetGpioPin()

◆ GetI2cAddress()

◆ GetPwmAdapter()

◆ initializeInternal()

◆ IsInitialized()

◆ IsPinCreated()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ SetAllPwm()

◆ SetChannelFullOff()

◆ SetChannelFullOn()

◆ SetDuty()

◆ SetFrequency()

◆ SetOutputDriverMode()

◆ SetOutputInvert()

◆ SetPwm()

◆ Sleep()

◆ validateChannel()

◆ Wake()

Friends And Related Symbol Documentation

◆ Pca9685GpioPin

◆ Pca9685PwmAdapter

Member Data Documentation

◆ gpio_registry_

◆ handler_mutex_

◆ i2c_adapter_

◆ i2c_device_

◆ initialized_

◆ pca9685_driver_

◆ pwm_adapter_