Pcal95555Handler.h File Reference

Unified handler for the PCA9555 / PCAL9555A 16-bit I2C GPIO expander. More...

#include <atomic>
#include <cstdint>
#include <memory>
#include <array>
#include <functional>
#include "base/BaseGpio.h"
#include "base/BaseI2c.h"
#include "core/hf-core-drivers/external/hf-pcal95555-driver/inc/pcal95555.hpp"
#include "RtosMutex.h"

Include dependency graph for Pcal95555Handler.h:

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

Go to the source code of this file.

Classes
class	HalI2cPcal95555Comm
	Concrete I2C communication adapter for PCAL95555 using BaseI2c. More...
class	Pcal95555GpioPin
	BaseGpio adapter for a single PCAL95555 GPIO expander pin. More...
class	Pcal95555Handler
	Unified, non-templated handler for a single PCA9555 / PCAL9555A device. More...

Detailed Description

Unified handler for the PCA9555 / PCAL9555A 16-bit I2C GPIO expander.

This file provides the complete HAL-level integration for a single PCA9555 / PCAL9555A GPIO expander device. It bridges the HardFOC base interfaces (BaseI2c, BaseGpio) with the templated pcal95555::PCAL95555<I2cType> driver from the hf-pcal95555-driver library.

Architecture Overview

The file contains three layers:

1. CRTP I2C Communication Adapter (HalI2cPcal95555Comm): Bridges the HardFOC BaseI2c device-centric interface (where the I2C address is pre-configured on the device object) with the PCAL95555 driver's CRTP-based pcal95555::I2cInterface (which passes the address as a parameter). Includes address validation, thread-safe I2C operations, and optional interrupt handler registration.
2. Pcal95555Handler (main class): Non-templated facade that owns a typed driver instance. Provides:
   • Lazy initialization with automatic chip variant detection
   • Per-pin GPIO operations (direction, read, write, toggle, pull mode)
   • Batch pin operations via 16-bit masks
   • Interrupt management (hardware INT pin + per-pin callbacks)
   • PCAL9555A "Agile I/O" features (drive strength, input latch, output mode)
   • Error flag access and diagnostics
   • Pin factory for creating BaseGpio-compatible wrappers
3. Pcal95555GpioPin (per-pin wrapper): Implements BaseGpio for a single expander pin, delegating all operations to the parent handler. Supports direction, level, pull mode, output mode, polarity inversion, and interrupt configuration.

Ownership Model

The handler owns all its internal resources:

• One HalI2cPcal95555Comm (I2C communication adapter)
• One typed pcal95555::PCAL95555<HalI2cPcal95555Comm> driver instance
• Up to 16 Pcal95555GpioPin wrappers (created on demand via pin registry)

External managers (GpioManager) obtain shared_ptr<BaseGpio> references to pins via CreateGpioPin(). The handler and pin registry co-own the pin objects.

Initialization Sequence

// 1. Obtain a BaseI2c device reference (address pre-configured)
// 2. Construct the handler (optionally with an interrupt pin)
Pcal95555Handler handler(i2c_device, &interrupt_gpio);
 
// 3. Initialize (lazy -- happens automatically on first use, or explicitly)
if (!handler.EnsureInitialized()) { return; }
 
// 4. Create pin wrappers and use them
auto pin0 = handler.CreateGpioPin(0, HF_GPIO_DIRECTION_OUTPUT);
pin0->SetPinLevel(HF_GPIO_LEVEL_HIGH);
 
// 5. Use handler-level operations
handler.SetDirection(5, HF_GPIO_DIRECTION_INPUT);
handler.SetPullMode(5, HF_GPIO_PULL_MODE_UP);

Thread Safety

The handler uses RtosMutex for thread-safe access to:

• I2C communication (in the adapter's i2c_mutex_)
• All handler-level operations including pin registry and interrupts (handler_mutex_)

A single handler_mutex_ protects all state because all hardware access is serialized through I2C anyway, making finer-grained locking unnecessary overhead.

See also

GpioManager Manager that creates and owns handler + pins

pcal95555::PCAL95555 Templated driver from hf-pcal95555-driver

Author

HardFOC Team

Date

2025