/home/runner/work/hf-pcal95555-driver/hf-pcal95555-driver/inc/pcal95555.hpp

Construct a new PCAL95555 driver instance using address pin levels.

Construct a new PCAL95555 driver instance using address pin levels.

Parameters

bus	Pointer to a user-implemented I2C interface (must inherit from pcal95555::I2cInterface<I2cType>).
a0_level	Initial state of A0 pin: true = HIGH (VDD), false = LOW (GND)
a1_level	Initial state of A1 pin: true = HIGH (VDD), false = LOW (GND)
a2_level	Initial state of A2 pin: true = HIGH (VDD), false = LOW (GND)
variant	Optional chip variant override. If ChipVariant::Unknown (default), the driver auto-detects during initialization. Set to ChipVariant::PCA9555 or ChipVariant::PCAL9555A to skip detection.

The constructor uses lazy initialization:

1. Calculates the I2C address from A2-A0 levels (base 0x20 + bits)
2. Stores pin levels for later initialization
3. No I2C communication happens in constructor

Initialization happens automatically on first method call, or explicitly via EnsureInitialized(). Initialization includes setting address pins, verifying I2C communication, and auto-detecting the chip variant.

// Auto-detect chip variant (default) PCAL95555 driver(bus, false, false, false);

// Force PCA9555 mode (skip Agile I/O detection) PCAL95555 driver(bus, false, false, false, ChipVariant::PCA9555);

// Force PCAL9555A mode PCAL95555 driver(bus, true, false, false, ChipVariant::PCAL9555A);

 
#pragma once
#include <array>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <initializer_list>
#include <utility>
#include <stdio.h> // NOLINT(modernize-deprecated-headers) - For FILE* used by ESP-IDF headers
#include <string.h> // NOLINT(modernize-deprecated-headers) - For C string functions (must be before namespace)
 
#include "pcal95555_i2c_interface.hpp"
 
#include "pcal95555_kconfig.hpp"
#include "pcal95555_version.h"
 
namespace pcal95555 {
 
enum class Pcal95555Reg : uint8_t {
  // === Standard PCA9555 registers (0x00-0x07) — PCA9555 + PCAL9555A ===
  INPUT_PORT_0 = 0x00,     
  INPUT_PORT_1 = 0x01,     
  OUTPUT_PORT_0 = 0x02,    
  OUTPUT_PORT_1 = 0x03,    
  POLARITY_INV_0 = 0x04,   
  POLARITY_INV_1 = 0x05,   
  CONFIG_PORT_0 = 0x06,    
  CONFIG_PORT_1 = 0x07,    
 
  // === PCAL9555A Agile I/O registers (0x40-0x4F) — PCAL9555A only ===
  DRIVE_STRENGTH_0 = 0x40, 
  DRIVE_STRENGTH_1 = 0x41, 
  DRIVE_STRENGTH_2 = 0x42, 
  DRIVE_STRENGTH_3 = 0x43, 
  INPUT_LATCH_0 = 0x44,    
  INPUT_LATCH_1 = 0x45,    
  PULL_ENABLE_0 = 0x46,    
  PULL_ENABLE_1 = 0x47,    
  PULL_SELECT_0 = 0x48,    
  PULL_SELECT_1 = 0x49,    
  INT_MASK_0 = 0x4A,       
  INT_MASK_1 = 0x4B,       
  INT_STATUS_0 = 0x4C,     
  INT_STATUS_1 = 0x4D,     
  OUTPUT_CONF = 0x4F       
};
 
enum class GPIODir : uint8_t { Input = 1, Output = 0 };
 
enum class Polarity : uint8_t { Normal = 0, Inverted = 1 };
 
enum class DriveStrength : uint8_t { Level0 = 0, Level1 = 1, Level2 = 2, Level3 = 3 };
 
enum class OutputMode : uint8_t { PushPull = 0, OpenDrain = 1 };
 
enum class InterruptEdge : uint8_t {
  Rising = 1,   
  Falling = 2, 
  Both = 3     
};
 
enum class InterruptState : uint8_t {
  Enabled = 0,  
  Disabled = 1  
};
 
// NOLINTNEXTLINE(performance-enum-size) - uint16_t allows for future error code expansion
enum class Error : uint16_t {
  None = 0,
  InvalidPin = 1 << 0,          
  InvalidMask = 1 << 1,         
  I2CReadFail = 1 << 2,         
  I2CWriteFail = 1 << 3,        
  UnsupportedFeature = 1 << 4,  
  InvalidAddress = 1 << 5       
};
 
inline constexpr Error operator|(Error lhs, Error rhs) noexcept {
  return static_cast<Error>(static_cast<uint16_t>(lhs) | static_cast<uint16_t>(rhs));
}
inline constexpr Error operator&(Error lhs, Error rhs) noexcept {
  return static_cast<Error>(static_cast<uint16_t>(lhs) & static_cast<uint16_t>(rhs));
}
inline constexpr Error operator~(Error e) noexcept {
  return static_cast<Error>(~static_cast<uint16_t>(e));
}
 
struct PinReadResult {
  static constexpr uint8_t kMaxPins = 16;
 
  std::array<std::pair<uint8_t, bool>, kMaxPins> data{};
 
  uint8_t count = 0;
 
  // -- Container-like API --------------------------------------------------
 
  [[nodiscard]] uint8_t size() const noexcept { return count; }
 
  [[nodiscard]] bool empty() const noexcept { return count == 0; }
 
  [[nodiscard]] const std::pair<uint8_t, bool>& operator[](uint8_t i) const noexcept {
    return data[i];
  }
 
  void push_back(uint8_t pin, bool value) noexcept {
    if (count < kMaxPins) {
      data[count++] = {pin, value};
    }
  }
 
  // -- Lookup API ----------------------------------------------------------
 
  [[nodiscard]] bool contains(uint8_t pin) const noexcept {
    for (uint8_t i = 0; i < count; ++i) {
      if (data[i].first == pin) return true;
    }
    return false;
  }
 
  [[nodiscard]] const std::pair<uint8_t, bool>* find(uint8_t pin) const noexcept {
    for (uint8_t i = 0; i < count; ++i) {
      if (data[i].first == pin) return &data[i];
    }
    return nullptr;
  }
 
  // -- Iterator support for range-based for --------------------------------
  using iterator       = typename std::array<std::pair<uint8_t, bool>, kMaxPins>::const_iterator;
  [[nodiscard]] iterator begin() const noexcept { return data.begin(); }
  [[nodiscard]] iterator end()   const noexcept { return data.begin() + count; }
};
 
enum class ChipVariant : uint8_t {
  Unknown = 0,    
  PCA9555 = 1,    
  PCAL9555A = 2   
};
 
template <typename I2cType>
class PCAL95555 {
public:
  PCAL95555(I2cType* bus, bool a0_level, bool a1_level, bool a2_level,
            ChipVariant variant = ChipVariant::Unknown);
 
  explicit PCAL95555(I2cType* bus, uint8_t address,
                     ChipVariant variant = ChipVariant::Unknown);
 
  // ---- Version Information (compile-time, static) ----
 
  static constexpr const char* GetDriverVersion() noexcept {
    return HF_PCAL95555_VERSION_STRING;
  }
 
  static constexpr uint8_t GetDriverVersionMajor() noexcept {
    return HF_PCAL95555_VERSION_MAJOR;
  }
 
  static constexpr uint8_t GetDriverVersionMinor() noexcept {
    return HF_PCAL95555_VERSION_MINOR;
  }
 
  static constexpr uint8_t GetDriverVersionPatch() noexcept {
    return HF_PCAL95555_VERSION_PATCH;
  }
 
  void SetRetries(int retries) noexcept;
 
  [[nodiscard]] uint16_t GetErrorFlags() const noexcept;
 
  [[nodiscard]] bool HasError(Error e) const noexcept;
 
  [[nodiscard]] bool HasAnyError() const noexcept;
 
  void ClearError(Error e) noexcept;
 
  void ClearErrorFlags(uint16_t mask = 0xFFFF) noexcept;
 
  void ResetToDefault() noexcept;
 
  void InitFromConfig() noexcept;
 
  bool SetPinDirection(uint8_t pin, GPIODir dir) noexcept;
 
  bool SetMultipleDirections(uint16_t mask, GPIODir dir) noexcept;
 
  bool SetDirections(std::initializer_list<std::pair<uint8_t, GPIODir>> configs) noexcept;
 
  bool ReadPin(uint8_t pin) noexcept;
 
  bool ReadPin(uint8_t pin, bool& level) noexcept;
 
  bool WritePin(uint8_t pin, bool value) noexcept;
 
  bool SetMultipleOutputs(uint16_t mask, bool value) noexcept;
 
  bool TogglePin(uint8_t pin) noexcept;
 
  bool WritePins(std::initializer_list<std::pair<uint8_t, bool>> configs) noexcept;
 
  PinReadResult ReadPins(std::initializer_list<uint8_t> pins) noexcept;
 
  uint16_t ReadAllInputs() noexcept;
 
  bool ReadDualPortRegister(uint8_t reg0, uint8_t reg1, uint16_t& value) noexcept;
 
  bool WriteDualPortRegister(uint8_t reg0, uint8_t reg1, uint16_t value) noexcept;
 
  bool SetPullEnable(uint8_t pin, bool enable) noexcept;
 
  bool SetPullEnables(std::initializer_list<std::pair<uint8_t, bool>> configs) noexcept;
 
  bool SetPullDirection(uint8_t pin, bool pull_up) noexcept;
 
  bool SetPullDirections(std::initializer_list<std::pair<uint8_t, bool>> configs) noexcept;
 
  bool GetPullConfiguration(uint16_t& enable_mask, uint16_t& direction_mask) noexcept;
 
  bool SetDriveStrength(uint8_t pin, DriveStrength level) noexcept;
 
  bool SetDriveStrengths(std::initializer_list<std::pair<uint8_t, DriveStrength>> configs) noexcept;
 
  bool ConfigureInterrupt(uint8_t pin, InterruptState state) noexcept;
 
  bool ConfigureInterrupts(std::initializer_list<std::pair<uint8_t, InterruptState>> configs) noexcept;
 
  bool ConfigureInterruptMask(uint16_t mask) noexcept;
  uint16_t GetInterruptStatus() noexcept;
 
  bool SetOutputMode(bool port_0_open_drain, bool port_1_open_drain) noexcept;
 
  bool SetPinPolarity(uint8_t pin, Polarity polarity) noexcept;
 
  bool SetMultiplePolarities(uint16_t mask, Polarity polarity) noexcept;
 
  bool SetPolarities(std::initializer_list<std::pair<uint8_t, Polarity>> configs) noexcept;
 
  bool EnableInputLatch(uint8_t pin, bool enable) noexcept;
 
  bool EnableMultipleInputLatches(uint16_t mask, bool enable) noexcept;
 
  bool EnableInputLatches(std::initializer_list<std::pair<uint8_t, bool>> configs) noexcept;
 
  bool RegisterPinInterrupt(uint8_t pin, InterruptEdge edge,
                            std::function<void(uint8_t pin, bool state)> callback);
 
  bool UnregisterPinInterrupt(uint8_t pin) noexcept;
 
  void SetInterruptCallback(const std::function<void(uint16_t)>& callback) noexcept;
 
  bool RegisterInterruptHandler() noexcept;
 
  void HandleInterrupt() noexcept;
 
  [[nodiscard]] uint8_t GetAddress() const noexcept;
 
  [[nodiscard]] uint8_t GetAddressBits() const noexcept;
 
  [[nodiscard]] bool HasAgileIO() const noexcept;
 
  [[nodiscard]] ChipVariant GetChipVariant() const noexcept;
 
  bool ChangeAddress(bool a0_level, bool a1_level, bool a2_level) noexcept;
 
  bool ChangeAddress(uint8_t address) noexcept;
 
  bool EnsureInitialized() noexcept;
 
  bool ForceMarkInitialized(ChipVariant variant) noexcept;
 
protected:
  bool readRegister(uint8_t reg, uint8_t& value) noexcept;
  bool writeRegister(uint8_t reg, uint8_t value) noexcept;
 
private:
  struct PinInterruptCallback {
    std::function<void(uint8_t pin, bool state)> callback;
    InterruptEdge edge;
    bool registered;
 
    PinInterruptCallback() : edge(InterruptEdge::Both), registered(false) {}
  };
 
  I2cType* i2c_;
  uint8_t dev_addr_;
  uint8_t address_bits_;  // A2-A0 bits (0-7)
  int retries_{1};
  uint16_t error_flags_{0};
  std::function<void(uint16_t)> irq_callback_;  // Global callback for all interrupts
  PinInterruptCallback pin_callbacks_[16];      // Per-pin callbacks
  uint16_t previous_pin_states_{0};            // Previous pin states for edge detection
  bool initialized_{false};                    // Lazy initialization flag
  bool a0_level_;                              // Stored pin levels for lazy init
  bool a1_level_;
  bool a2_level_;
  ChipVariant chip_variant_{ChipVariant::Unknown};  // Detected or user-specified chip variant
  ChipVariant user_variant_{ChipVariant::Unknown};  // User-requested variant (for skipping detection)
  uint8_t xfer_byte_{0};  // Bus transfer byte: lives in the driver object, one per chip
 
  static constexpr uint8_t calculateAddress(uint8_t bits) {
    constexpr uint8_t BASE_ADDRESS = 0x20;
    constexpr uint8_t MAX_BITS = 0x07;
    return BASE_ADDRESS + (bits & MAX_BITS);
  }
 
  uint16_t readPinStates() noexcept;
 
  bool initialize() noexcept;
 
  void setError(Error error_code) noexcept;
  void clearError(Error error_code) noexcept;
 
  // ---- Internal R-M-W helpers (reduce code duplication) ----
 
  bool readDualPort(uint8_t reg0, uint8_t reg1, uint8_t& val0, uint8_t& val1) noexcept;
 
  bool writeDualPort(uint8_t reg0, uint8_t reg1, uint8_t val0, uint8_t val1) noexcept;
 
  bool modifySinglePinRegister(uint8_t reg0, uint8_t reg1, uint8_t pin, bool bit_value) noexcept;
 
  bool modifyDualPortByMask(uint8_t reg0, uint8_t reg1, uint16_t mask, bool bit_value) noexcept;
 
  bool requireAgileIO() noexcept;
 
  bool changeAddressImpl(uint8_t new_bits) noexcept;
 
  bool detectChipVariant() noexcept;
};
 
// Include template implementation
#define PCAL95555_HEADER_INCLUDED
// Source tree: inc/../src/pcal95555.ipp. Installed tree: the .ipp sits next to this header.
#if defined(__has_include)
#if __has_include("../src/pcal95555.ipp")
// NOLINTNEXTLINE(bugprone-suspicious-include) - Intentional: template implementation file
#include "../src/pcal95555.ipp"
#else
// NOLINTNEXTLINE(bugprone-suspicious-include) - Intentional: template implementation file
#include "pcal95555.ipp"
#endif
#else
// NOLINTNEXTLINE(bugprone-suspicious-include) - Intentional: template implementation file
#include "../src/pcal95555.ipp"
#endif
#undef PCAL95555_HEADER_INCLUDED
 
 
// Public API: Get driver version string
inline const char* GetDriverVersion() noexcept {
  return HF_PCAL95555_VERSION_STRING;
}
 
} // namespace pcal95555
 
// ---------------------------------------------------------------------------
// Deprecated global-scope names
// ---------------------------------------------------------------------------
// Up to 1.0.0 these types were declared in the global namespace, where names
// such as Error and Polarity collide with other libraries. They now live in
// namespace pcal95555; the aliases below keep old code compiling and will be
// removed in the next major version. Define HF_PCAL95555_NO_GLOBAL_ALIASES to
// drop them now.
#ifndef HF_PCAL95555_NO_GLOBAL_ALIASES
using Pcal95555Reg = pcal95555::Pcal95555Reg;  // deprecated: use pcal95555::Pcal95555Reg
using GPIODir = pcal95555::GPIODir;  // deprecated: use pcal95555::GPIODir
using Polarity = pcal95555::Polarity;  // deprecated: use pcal95555::Polarity
using DriveStrength = pcal95555::DriveStrength;  // deprecated: use pcal95555::DriveStrength
using OutputMode = pcal95555::OutputMode;  // deprecated: use pcal95555::OutputMode
using InterruptEdge = pcal95555::InterruptEdge;  // deprecated: use pcal95555::InterruptEdge
using InterruptState = pcal95555::InterruptState;  // deprecated: use pcal95555::InterruptState
using Error = pcal95555::Error;  // deprecated: use pcal95555::Error
using pcal95555::operator|;
using pcal95555::operator&;
using pcal95555::operator~;
#endif