pcal95555.hpp

Go to the documentation of this file.

 
#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