Unified, non-templated handler for a single PCA9555 / PCAL9555A device. More...

#include <Pcal95555Handler.h>

Public Types
Type Aliases
using	Pcal95555Driver = pcal95555::PCAL95555< HalI2cPcal95555Comm >
	Typed PCAL95555 driver using our I2C adapter.

Public Member Functions
Construction and Destruction
	Pcal95555Handler (BaseI2c &i2c_device, BaseGpio *interrupt_pin=nullptr) noexcept
	Construct a handler for a PCAL95555 device.

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

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

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

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

Pcal95555Handler &	operator= (Pcal95555Handler &&)=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.

Basic GPIO Operations
Per-pin operations using pin numbers (0-15).
hf_gpio_err_t	SetDirection (uint8_t pin, hf_gpio_direction_t direction) noexcept
	Set the direction of a single pin.

hf_gpio_err_t	SetOutput (uint8_t pin, bool active) noexcept
	Write a logical level to an output pin.

hf_gpio_err_t	ReadInput (uint8_t pin, bool &active) noexcept
	Read the physical level of a pin.

hf_gpio_err_t	Toggle (uint8_t pin) noexcept
	Toggle the output state of a pin.

hf_gpio_err_t	SetPullMode (uint8_t pin, hf_gpio_pull_mode_t pull_mode) noexcept
	Set the pull resistor mode for a single pin.

hf_gpio_err_t	GetPullMode (uint8_t pin, hf_gpio_pull_mode_t &pull_mode) noexcept
	Get the pull resistor mode for a single pin (tracked internally).

Batch GPIO Operations
Operations on multiple pins using 16-bit masks.
hf_gpio_err_t	SetDirections (uint16_t pin_mask, hf_gpio_direction_t direction) noexcept
	Set direction for multiple pins at once.

hf_gpio_err_t	SetOutputs (uint16_t pin_mask, bool active) noexcept
	Write output level for multiple pins at once.

hf_gpio_err_t	SetOutputsVerified (uint16_t pin_mask, bool active) noexcept
	Write output level for multiple pins in one transaction, then read the latch back and retry (up to 3×) until every selected bit matches.

hf_gpio_err_t	SetPullModes (uint16_t pin_mask, hf_gpio_pull_mode_t pull_mode) noexcept
	Set pull mode for multiple pins at once.

PCAL9555A Advanced Features (Agile I/O)
These features require a PCAL9555A chip. They return false on PCA9555.
bool	HasAgileIO () const noexcept
	Check if the detected chip supports Agile I/O features.

pcal95555::ChipVariant	GetChipVariant () const noexcept
	Get the detected chip variant.

hf_gpio_err_t	SetPolarityInversion (hf_pin_num_t pin, bool invert) noexcept
	Set input polarity inversion for a pin.

hf_gpio_err_t	SetMultiplePolarityInversion (uint16_t pin_mask, bool invert) noexcept
	Batch-set input polarity inversion for a pin mask.

hf_gpio_err_t	SetInterruptMask (hf_pin_num_t pin, bool mask) noexcept
	Set the per-pin interrupt mask.

hf_gpio_err_t	GetInterruptStatus (hf_pin_num_t pin, bool &status) noexcept
	Get interrupt status for a single pin.

hf_gpio_err_t	SetDriveStrength (hf_pin_num_t pin, pcal95555::DriveStrength level) noexcept
	Set output drive strength for a pin.

hf_gpio_err_t	EnableInputLatch (hf_pin_num_t pin, bool enable) noexcept
	Enable or disable input latch for a pin.

hf_gpio_err_t	SetOutputMode (bool port0_open_drain, bool port1_open_drain) noexcept
	Configure per-port output mode (push-pull or open-drain).

hf_gpio_err_t	ResetToDefault () noexcept
	Reset all registers to power-on default state.

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.

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

hf_gpio_err_t	Initialize () noexcept
	Internal initialization (called by EnsureInitialized under mutex).

hf_gpio_err_t	Deinitialize () noexcept
	Internal deinitialization.

bool	ValidatePin (uint8_t pin) const noexcept
	Validate pin number is in range 0-15.

hf_gpio_err_t	RegisterPinInterrupt (hf_pin_num_t pin, hf_gpio_interrupt_trigger_t trigger, InterruptCallback callback, void *user_data) noexcept
	Register a per-pin interrupt callback (called by Pcal95555GpioPin).

hf_gpio_err_t	UnregisterPinInterrupt (hf_pin_num_t pin) noexcept
	Unregister a per-pin interrupt callback.

hf_gpio_err_t	ConfigureHardwareInterrupt () noexcept
	Configure the hardware interrupt pin (falling edge, active-low).

void	ProcessInterrupts () noexcept
	Process pending interrupts by reading status and dispatching callbacks.

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

const Pcal95555Driver *	GetDriver () const noexcept

Static Private Member Functions
static void	HardwareInterruptCallback (BaseGpio gpio, hf_gpio_interrupt_trigger_t trigger, void user_data) noexcept
	Static ISR callback for the hardware interrupt pin.

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

std::unique_ptr< HalI2cPcal95555Comm >	i2c_adapter_
	I2C adapter (created in Initialize).

std::unique_ptr< Pcal95555Driver >	pcal95555_driver_
	Typed driver (created in Initialize).

bool	initialized_ = false
	Initialization state.

RtosMutex	handler_mutex_
	Thread safety for handler operations.

Pin Registry
std::array< Pcal95555GpioPin *, 16 >	pin_registry_ {}
	Non-owning registry slots.

std::array< std::unique_ptr< Pcal95555GpioPin >, 16 >	owned_pins_ {}
	Heap pins from CreateGpioPin.

Internal Pull Mode Tracking
Tracks pull mode per-pin since the driver doesn't provide readback.
std::array< hf_gpio_pull_mode_t, 16 >	pull_mode_cache_

Edge Detection State
Tracks previous input state for rising/falling edge filtering.
uint16_t	prev_input_state_ = 0
	Last-read pin input levels (bitmask).

Port shadows (absolute write path)
Avoid read-modify-write when register readback is untrustworthy.
uint16_t	output_shadow_ {0xFFFFU}
	PCA POR default OUTPUT.

uint16_t	config_shadow_ {0xFFFFU}
	PCA POR default CONFIG (all input)

uint16_t	polarity_shadow_ {0}
	POLARITY_INV.

bool	port_shadow_valid_ {false}

Friends
class	Pcal95555GpioPin
	Allow Pcal95555GpioPin to access private interrupt methods.

Interrupt Management
BaseGpio *	interrupt_pin_
	Hardware INT pin (optional, not owned).

bool	interrupt_configured_
	Whether hardware interrupt is active.

std::atomic< bool >	interrupt_pending_ {false}
	Deferred interrupt flag (set in ISR, cleared in task context).

bool	HasInterruptSupport () const noexcept
	Check if hardware interrupt support is available.

bool	IsInterruptConfigured () const noexcept
	Check if hardware interrupt is configured and enabled.

bool	DrainPendingInterrupts () noexcept
	Drain any pending interrupt that was deferred from ISR context.

hf_gpio_err_t	GetAllInterruptMasks (uint16_t &mask) noexcept
	Get the interrupt mask for all 16 pins.

hf_gpio_err_t	GetAllInterruptStatus (uint16_t &status) noexcept
	Get the interrupt status for all 16 pins.

Pin Factory
Create and manage BaseGpio-compatible pin wrapper instances.
uint8_t	GetI2cAddress () const noexcept
	Get the I2C address of the underlying device.

bool	AttachStaticPin (Pcal95555GpioPin &pin) noexcept
	Register a caller-owned pin wrapper (no heap allocation).

std::shared_ptr< BaseGpio >	CreateGpioPin (hf_pin_num_t pin, hf_gpio_direction_t direction=hf_gpio_direction_t::HF_GPIO_DIRECTION_INPUT, hf_gpio_active_state_t active_state=hf_gpio_active_state_t::HF_GPIO_ACTIVE_HIGH, hf_gpio_output_mode_t output_mode=hf_gpio_output_mode_t::HF_GPIO_OUTPUT_MODE_PUSH_PULL, hf_gpio_pull_mode_t pull_mode=hf_gpio_pull_mode_t::HF_GPIO_PULL_MODE_FLOATING, bool allow_existing=true, bool configure_hardware=true) noexcept
	Create or retrieve an existing BaseGpio pin wrapper (heap).

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

Pcal95555GpioPin *	GetGpioPinRaw (hf_pin_num_t pin) noexcept
	Raw pointer to a registered pin (no shared_ptr control block).

hf_gpio_err_t	ReadAllInputLevels (uint16_t &levels) noexcept
	Read both INPUT_PORT registers in one dual-port transaction.

hf_gpio_err_t	ProgramPortsAbsolute (uint16_t config, uint16_t output, uint16_t out_check_mask) noexcept
	Absolute program POL=0, OUTPUT latch, and CONFIG (no RMW).

hf_gpio_err_t	ReadConfigAndOutputPorts (uint16_t &config, uint16_t &output) noexcept
	Read CONFIG (1=input) and OUTPUT latch port pairs (PCA pin bits).

hf_gpio_err_t	ReadOutputLatchFromWire (uint16_t &output) noexcept
	Read OUTPUT_PORT_0/1 from the chip (never the CM4 shadow).

hf_gpio_err_t	ReadStandardRegisterBank (uint16_t &input, uint16_t &output, uint16_t &polarity, uint16_t &config) noexcept
	Read the full standard PCA9555 bank (0x00..0x07) as four 16-bit ports.

hf_gpio_err_t	VerifyOutputPinEffect (uint8_t pin, uint16_t &latch_high, uint16_t &input_high, uint16_t &latch_low, uint16_t &input_low) noexcept
	Drive one pin and verify OUTPUT latch + INPUT pad follow.

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

uint16_t	GetCreatedPinMask () const noexcept
	Get a bitmask of all created pin numbers.

static constexpr uint8_t	PinCount () noexcept
	Total number of GPIO pins on the expander.

Detailed Description

Unified, non-templated handler for a single PCA9555 / PCAL9555A device.

Pcal95555Handler is the primary interface that application and manager code uses to interact with a PCAL95555 GPIO expander. It hides the template complexity of pcal95555::PCAL95555<I2cType> behind a clean public API.

Design Decisions

Non-templated: The handler owns a concrete typed driver instance (pcal95555::PCAL95555<HalI2cPcal95555Comm>) internally. Since only one I2C communication type is used per handler, no dispatch mechanism is needed (unlike the TMC9660Handler which supports SPI or UART).
Lazy initialization: The driver and adapter are created in Initialize(), not in the constructor. The driver itself also uses lazy initialization (auto-detecting chip variant on first I2C access).
Pin factory pattern: Pins are created on demand via CreateGpioPin() and stored in a shared_ptr registry. Multiple calls for the same pin return the same instance.
Chip variant awareness: After initialization, HasAgileIO() reports whether PCAL9555A features (pull resistors, drive strength, interrupts, input latch, output mode) are available. Methods requiring Agile I/O gracefully fail on standard PCA9555.

See also: HalI2cPcal95555Comm I2C communication adapter; Pcal95555GpioPin Per-pin BaseGpio wrapper; GpioManager Manager that creates and owns handler instances

Member Typedef Documentation

◆ Pcal95555Driver

using Pcal95555Handler::Pcal95555Driver = pcal95555::PCAL95555<HalI2cPcal95555Comm>

Typed PCAL95555 driver using our I2C adapter.

Constructor & Destructor Documentation

◆ Pcal95555Handler() [1/3]

Pcal95555Handler::Pcal95555Handler	(	BaseI2c &	i2c_device,
		BaseGpio *	interrupt_pin = `nullptr`
	)

explicitnoexcept

Construct a handler for a PCAL95555 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. Must outlive the handler.
interrupt_pin	Optional BaseGpio pin connected to the expander's INT output. Pass nullptr for polling mode (no hardware interrupts).

◆ ~Pcal95555Handler()

Pcal95555Handler::~Pcal95555Handler ( )

defaultnoexcept

Destructor. Releases driver, adapter, and all pin wrappers.

◆ Pcal95555Handler() [2/3]

Pcal95555Handler::Pcal95555Handler ( const Pcal95555Handler & )

delete

Non-copyable.

◆ Pcal95555Handler() [3/3]

Pcal95555Handler::Pcal95555Handler ( Pcal95555Handler && )

delete

Non-movable.

Member Function Documentation

◆ AttachStaticPin()

bool Pcal95555Handler::AttachStaticPin ( Pcal95555GpioPin & pin )

noexcept

Register a caller-owned pin wrapper (no heap allocation).

Prefer for static/.bss pin maps: place Pcal95555GpioPin in fixed storage, batch-program directions, then attach with configure_hardware=false in the pin ctor.

Returns: true if registered (or already the same object at that index).

◆ ClearErrorFlags()

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

noexcept

Clear driver error flags.

Parameters

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

◆ ConfigureHardwareInterrupt()

hf_gpio_err_t Pcal95555Handler::ConfigureHardwareInterrupt ( )

privatenoexcept

Configure the hardware interrupt pin (falling edge, active-low).

Returns: GPIO error code.

◆ CreateGpioPin()

std::shared_ptr< BaseGpio > Pcal95555Handler::CreateGpioPin	(	hf_pin_num_t	pin,
		hf_gpio_direction_t	direction = `hf_gpio_direction_t::HF_GPIO_DIRECTION_INPUT`,
		hf_gpio_active_state_t	active_state = `hf_gpio_active_state_t::HF_GPIO_ACTIVE_HIGH`,
		hf_gpio_output_mode_t	output_mode = `hf_gpio_output_mode_t::HF_GPIO_OUTPUT_MODE_PUSH_PULL`,
		hf_gpio_pull_mode_t	pull_mode = `hf_gpio_pull_mode_t::HF_GPIO_PULL_MODE_FLOATING`,
		bool	allow_existing = `true`,
		bool	configure_hardware = `true`
	)

noexcept

Create or retrieve an existing BaseGpio pin wrapper (heap).

Prefer AttachStaticPin when bring-up must avoid heap. This factory remains for tests and ad-hoc tools.

Parameters

configure_hardware If false, Initialize() skips I2C direction/pull (caller must have batched SetDirections).

Returns: shared_ptr that does not own the object (handler unique_ptr does); nullptr on failure.

◆ Deinitialize()

hf_gpio_err_t Pcal95555Handler::Deinitialize ( )

privatenoexcept

Internal deinitialization.

Returns: GPIO error code.

◆ DrainPendingInterrupts()

bool Pcal95555Handler::DrainPendingInterrupts ( )

noexcept

Drain any pending interrupt that was deferred from ISR context.

This method should be called from task context (e.g., a polling loop or a dedicated worker task). It checks the atomic interrupt_pending_ flag, and if set, performs the I2C reads and user callback dispatch safely.

Returns: true if an interrupt was processed, false if none was pending.

◆ DumpDiagnostics()

void Pcal95555Handler::DumpDiagnostics ( ) const

noexcept

Dump comprehensive diagnostics to the system log.

Logs initialization status, I2C address, chip variant, pin registry, interrupt configuration, and error flags at INFO level.

◆ EnableInputLatch()

hf_gpio_err_t Pcal95555Handler::EnableInputLatch	(	hf_pin_num_t	pin,
		bool	enable
	)

noexcept

Enable or disable input latch for a pin.

Parameters

pin	Pin number (0-15).
enable	true to enable input latch, false to disable.

Returns: GPIO_ERR_OK on success, or a specific hf_gpio_err_t error code.

Note: Requires PCAL9555A.

◆ EnsureDeinitialized()

bool Pcal95555Handler::EnsureDeinitialized ( )

noexcept

Deinitialize the handler and release resources.

Disables hardware interrupt, clears the pin registry, and releases the driver and I2C adapter.

Returns: true if already deinitialized or deinitialization succeeded.

◆ EnsureInitialized()

bool Pcal95555Handler::EnsureInitialized ( )

noexcept

Ensure the handler is initialized (lazy initialization).

On first call, creates the I2C adapter and driver, runs the driver's EnsureInitialized() (which auto-detects chip variant), and optionally configures the hardware interrupt pin.

Returns: true if already initialized or initialization succeeded.

◆ EnsureInitializedLocked()

bool Pcal95555Handler::EnsureInitializedLocked ( )

inlineprivatenoexcept

Check init state under already-held handler_mutex_.

Check initialization under an already-held handler_mutex_.

Returns: true if initialized or initialization succeeds.

◆ GetAllInterruptMasks()

hf_gpio_err_t Pcal95555Handler::GetAllInterruptMasks ( uint16_t & mask )

noexcept

Get the interrupt mask for all 16 pins.

Parameters

[out] mask 16-bit mask (0=enabled, 1=masked per PCAL9555A convention).

Returns: GPIO_SUCCESS or error code.

Note: Requires PCAL9555A.

◆ GetAllInterruptStatus()

hf_gpio_err_t Pcal95555Handler::GetAllInterruptStatus ( uint16_t & status )

noexcept

Get the interrupt status for all 16 pins.

Reading the status clears the interrupt condition on the device.

Parameters

[out] status 16-bit mask (bit N set = pin N has pending interrupt).

Returns: GPIO_SUCCESS or error code.

Note: Requires PCAL9555A.

◆ GetChipVariant()

pcal95555::ChipVariant Pcal95555Handler::GetChipVariant ( ) const

noexcept

Get the detected chip variant.

Returns: ChipVariant enum (Unknown, PCA9555, or PCAL9555A).

◆ GetCreatedPinMask()

uint16_t Pcal95555Handler::GetCreatedPinMask ( ) const

noexcept

Get a bitmask of all created pin numbers.

Returns: 16-bit mask where bit N is set if pin N has been created.

◆ GetDriver() [1/2]

const Pcal95555Handler::Pcal95555Driver * Pcal95555Handler::GetDriver ( ) const

privatenoexcept

◆ GetDriver() [2/2]

Pcal95555Handler::Pcal95555Driver * Pcal95555Handler::GetDriver ( )

privatenoexcept

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

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

◆ GetErrorFlags()

uint16_t Pcal95555Handler::GetErrorFlags ( ) const

noexcept

Get the driver's error flags.

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

◆ GetGpioPin()

std::shared_ptr< BaseGpio > Pcal95555Handler::GetGpioPin ( hf_pin_num_t pin )

noexcept

Get an existing GPIO pin wrapper by number.

Returns: non-owning shared_ptr, or nullptr if not registered.

◆ GetGpioPinRaw()

Pcal95555GpioPin * Pcal95555Handler::GetGpioPinRaw ( hf_pin_num_t pin )

noexcept

Raw pointer to a registered pin (no shared_ptr control block).

◆ GetI2cAddress()

uint8_t Pcal95555Handler::GetI2cAddress ( ) const

noexcept

Get the I2C address of the underlying device.

Returns: 7-bit I2C address (0x20-0x27), or 0 if driver not created.

◆ GetInterruptStatus()

hf_gpio_err_t Pcal95555Handler::GetInterruptStatus	(	hf_pin_num_t	pin,
		bool &	status
	)

noexcept

Get interrupt status for a single pin.

Parameters

	pin	Pin number (0-15).
[out]	status	true if pin has pending interrupt.

Returns: GPIO_ERR_OK on success, or a specific hf_gpio_err_t error code.

Note: Reading status clears the interrupt. Requires PCAL9555A.

◆ GetPullMode()

hf_gpio_err_t Pcal95555Handler::GetPullMode	(	uint8_t	pin,
		hf_gpio_pull_mode_t &	pull_mode
	)

noexcept

Get the pull resistor mode for a single pin (tracked internally).

Parameters

	pin	Pin number (0-15).
[out]	pull_mode	Current pull mode.

Returns: GPIO_SUCCESS or error code.

◆ HardwareInterruptCallback()

void Pcal95555Handler::HardwareInterruptCallback	(	BaseGpio *	gpio,
		hf_gpio_interrupt_trigger_t	trigger,
		void *	user_data
	)

staticprivatenoexcept

Static ISR callback for the hardware interrupt pin.

Parameters

gpio	The GPIO pin that triggered.
trigger	Trigger type.
user_data	Pointer to Pcal95555Handler instance.

◆ HasAgileIO()

bool Pcal95555Handler::HasAgileIO ( ) const

noexcept

Check if the detected chip supports Agile I/O features.

Returns: true if PCAL9555A detected, false if PCA9555 or not yet initialized.

Note: Call after EnsureInitialized() for accurate results.

◆ HasInterruptSupport()

bool Pcal95555Handler::HasInterruptSupport ( ) const

inlinenoexcept

Check if hardware interrupt support is available.

Returns: true if an interrupt pin was provided at construction.

◆ Initialize()

hf_gpio_err_t Pcal95555Handler::Initialize ( )

privatenoexcept

Internal initialization (called by EnsureInitialized under mutex).

Returns: GPIO error code.

◆ IsInitialized()

bool Pcal95555Handler::IsInitialized ( ) const

inlinenoexcept

Check if the handler has been initialized.

Returns: true if initialized, false otherwise.

◆ IsInterruptConfigured()

bool Pcal95555Handler::IsInterruptConfigured ( ) const

inlinenoexcept

Check if hardware interrupt is configured and enabled.

Returns: true if interrupt pin is actively monitoring.

◆ IsPinCreated()

bool Pcal95555Handler::IsPinCreated ( hf_pin_num_t pin ) const

noexcept

Check if a pin wrapper has been created.

Parameters

pin	Pin number (0-15).

Returns: true if the pin exists in the registry.

◆ operator=() [1/2]

Pcal95555Handler & Pcal95555Handler::operator= ( const Pcal95555Handler & )

delete

Non-copyable.

◆ operator=() [2/2]

Pcal95555Handler & Pcal95555Handler::operator= ( Pcal95555Handler && )

delete

Non-movable.

◆ PinCount()

static constexpr uint8_t Pcal95555Handler::PinCount ( )

inlinestaticconstexprnoexcept

Total number of GPIO pins on the expander.

◆ ProcessInterrupts()

void Pcal95555Handler::ProcessInterrupts ( )

privatenoexcept

Process pending interrupts by reading status and dispatching callbacks.

◆ ProgramPortsAbsolute()

hf_gpio_err_t Pcal95555Handler::ProgramPortsAbsolute	(	uint16_t	config,
		uint16_t	output,
		uint16_t	out_check_mask
	)

noexcept

Absolute program POL=0, OUTPUT latch, and CONFIG (no RMW).

Seeds the handler port shadow used by SetOutput / SetDirections. Verifies via latch readback when distinct, else INPUT pad follow on driven-high output bits (datasheet: INPUT mirrors pad for outputs).

Parameters

config	CONFIG mask (bit=1 → input)
output	OUTPUT latch mask
out_check_mask	bits of OUTPUT that must match for verify

◆ ReadAllInputLevels()

hf_gpio_err_t Pcal95555Handler::ReadAllInputLevels ( uint16_t & levels )

noexcept

Read both INPUT_PORT registers in one dual-port transaction.

Parameters

[out] levels Bit N = physical HIGH on PCA pin N.

◆ ReadConfigAndOutputPorts()

hf_gpio_err_t Pcal95555Handler::ReadConfigAndOutputPorts	(	uint16_t &	config,
		uint16_t &	output
	)

noexcept

Read CONFIG (1=input) and OUTPUT latch port pairs (PCA pin bits).

◆ ReadInput()

hf_gpio_err_t Pcal95555Handler::ReadInput	(	uint8_t	pin,
		bool &	active
	)

noexcept

Read the physical level of a pin.

Output pins (CONFIG bit clear) return the OUTPUT latch shadow — Mid I2C0 INPUT_PORT is not used for driven lines. Input pins sample the wire via the driver.

Parameters

	pin	Pin number (0-15).
[out]	active	true if HIGH, false if LOW.

Returns: GPIO_SUCCESS or error code (checks driver error flags).

◆ ReadOutputLatchFromWire()

hf_gpio_err_t Pcal95555Handler::ReadOutputLatchFromWire ( uint16_t & output )

noexcept

Read OUTPUT_PORT_0/1 from the chip (never the CM4 shadow).

Use after SetOutput to confirm the chip latch actually updated. Must run before any INPUT_PORT read on this bus.

◆ ReadStandardRegisterBank()

hf_gpio_err_t Pcal95555Handler::ReadStandardRegisterBank	(	uint16_t &	input,
		uint16_t &	output,
		uint16_t &	polarity,
		uint16_t &	config
	)

noexcept

Read the full standard PCA9555 bank (0x00..0x07) as four 16-bit ports.

Per NXP datasheet: INPUT reflects pad levels even when the pin is an output; OUTPUT readback is the latch flip-flop; CONFIG bit=1 means input. Use after a write to confirm the latch took effect.

◆ RegisterPinInterrupt()

hf_gpio_err_t Pcal95555Handler::RegisterPinInterrupt	(	hf_pin_num_t	pin,
		hf_gpio_interrupt_trigger_t	trigger,
		InterruptCallback	callback,
		void *	user_data
	)

privatenoexcept

Register a per-pin interrupt callback (called by Pcal95555GpioPin).

Parameters

pin	Pin number (0-15).
trigger	Trigger type.
callback	Callback function.
user_data	User data for callback.

Returns: GPIO error code.

◆ ResetToDefault()

hf_gpio_err_t Pcal95555Handler::ResetToDefault ( )

noexcept

Reset all registers to power-on default state.

Returns: GPIO_ERR_OK on success, or a specific hf_gpio_err_t error code.

◆ SetDirection()

hf_gpio_err_t Pcal95555Handler::SetDirection	(	uint8_t	pin,
		hf_gpio_direction_t	direction
	)

noexcept

Set the direction of a single pin.

Parameters

pin	Pin number (0-15).
direction	Input or output.

Returns: GPIO_SUCCESS or error code.

◆ SetDirections()

hf_gpio_err_t Pcal95555Handler::SetDirections	(	uint16_t	pin_mask,
		hf_gpio_direction_t	direction
	)

noexcept

Set direction for multiple pins at once.

Parameters

pin_mask	16-bit mask (bit N = pin N).
direction	Common direction for all selected pins.

Returns: GPIO_SUCCESS or error code.

◆ SetDriveStrength()

hf_gpio_err_t Pcal95555Handler::SetDriveStrength	(	hf_pin_num_t	pin,
		pcal95555::DriveStrength	level
	)

noexcept

Set output drive strength for a pin.

Parameters

pin	Pin number (0-15).
level	Drive strength (Level0=25%, Level1=50%, Level2=75%, Level3=100%).

Returns: GPIO_ERR_OK on success, or a specific hf_gpio_err_t error code.

Note: Requires PCAL9555A.

◆ SetInterruptMask()

hf_gpio_err_t Pcal95555Handler::SetInterruptMask	(	hf_pin_num_t	pin,
		bool	mask
	)

noexcept

Set the per-pin interrupt mask.

Parameters

pin	Pin number (0-15).
mask	true to mask (disable) interrupt, false to unmask (enable).

Returns: GPIO_ERR_OK on success, or a specific hf_gpio_err_t error code.

Note: Requires PCAL9555A.

◆ SetMultiplePolarityInversion()

hf_gpio_err_t Pcal95555Handler::SetMultiplePolarityInversion	(	uint16_t	pin_mask,
		bool	invert
	)

noexcept

Batch-set input polarity inversion for a pin mask.

Parameters

pin_mask	Bits set select pins 0..15.
invert	true to invert, false for normal (typical clear: mask=0xFFFF).

Returns: GPIO_ERR_OK on success, or a specific hf_gpio_err_t error code.

◆ SetOutput()

hf_gpio_err_t Pcal95555Handler::SetOutput	(	uint8_t	pin,
		bool	active
	)

noexcept

Write a logical level to an output pin.

Parameters

pin	Pin number (0-15).
active	true for HIGH, false for LOW.

Returns: GPIO_SUCCESS or error code.

◆ SetOutputMode()

hf_gpio_err_t Pcal95555Handler::SetOutputMode	(	bool	port0_open_drain,
		bool	port1_open_drain
	)

noexcept

Configure per-port output mode (push-pull or open-drain).

Parameters

port0_open_drain	true for open-drain on port 0 (pins 0-7).
port1_open_drain	true for open-drain on port 1 (pins 8-15).

Returns: GPIO_ERR_OK on success, or a specific hf_gpio_err_t error code.

Note: Requires PCAL9555A.

◆ SetOutputs()

hf_gpio_err_t Pcal95555Handler::SetOutputs	(	uint16_t	pin_mask,
		bool	active
	)

noexcept

Write output level for multiple pins at once.

Parameters

pin_mask	16-bit mask (bit N = pin N).
active	Common level for all selected pins.

Returns: GPIO_SUCCESS or error code.

◆ SetOutputsVerified()

hf_gpio_err_t Pcal95555Handler::SetOutputsVerified	(	uint16_t	pin_mask,
		bool	active
	)

noexcept

Write output level for multiple pins in one transaction, then read the latch back and retry (up to 3×) until every selected bit matches.

The verified single-pin path costs a write + read per pin; parking several control straps one by one (TMC EN + nRST, re-asserted) held the motor thread ~30 ms (desk 2026-10-15). One dual-port write + one read-back covers them all.

Returns: GPIO_SUCCESS, or GPIO_ERR_WRITE_FAILURE when the latch never matched.

◆ SetPolarityInversion()

hf_gpio_err_t Pcal95555Handler::SetPolarityInversion	(	hf_pin_num_t	pin,
		bool	invert
	)

noexcept

Set input polarity inversion for a pin.

Parameters

pin	Pin number (0-15).
invert	true to invert input polarity, false for normal.

Returns: GPIO_ERR_OK on success, or a specific hf_gpio_err_t error code.

◆ SetPullMode()

hf_gpio_err_t Pcal95555Handler::SetPullMode	(	uint8_t	pin,
		hf_gpio_pull_mode_t	pull_mode
	)

noexcept

Set the pull resistor mode for a single pin.

Maps HardFOC pull modes to PCAL9555A SetPullEnable/SetPullDirection:

FLOATING: disable pull
UP: enable pull, direction = up
DOWN: enable pull, direction = down
UP_DOWN: not supported, defaults to pull-up

Parameters

pin	Pin number (0-15).
pull_mode	Desired pull mode.

Returns: GPIO_SUCCESS or error code.

Note: Requires PCAL9555A. Returns GPIO_ERR_UNSUPPORTED_OPERATION on PCA9555.

◆ SetPullModes()

hf_gpio_err_t Pcal95555Handler::SetPullModes	(	uint16_t	pin_mask,
		hf_gpio_pull_mode_t	pull_mode
	)

noexcept

Set pull mode for multiple pins at once.

Parameters

pin_mask	16-bit mask (bit N = pin N).
pull_mode	Common pull mode for all selected pins.

Returns: GPIO_SUCCESS or error code.

Note: Requires PCAL9555A.

◆ Toggle()

hf_gpio_err_t Pcal95555Handler::Toggle ( uint8_t pin )

noexcept

Toggle the output state of a pin.

Parameters

pin	Pin number (0-15).

Returns: GPIO_SUCCESS or error code.

◆ UnregisterPinInterrupt()

hf_gpio_err_t Pcal95555Handler::UnregisterPinInterrupt ( hf_pin_num_t pin )

privatenoexcept

Unregister a per-pin interrupt callback.

Parameters

pin	Pin number (0-15).

Returns: GPIO error code.

◆ ValidatePin()

bool Pcal95555Handler::ValidatePin ( uint8_t pin ) const

inlineprivatenoexcept

Validate pin number is in range 0-15.

◆ VerifyOutputPinEffect()

hf_gpio_err_t Pcal95555Handler::VerifyOutputPinEffect	(	uint8_t	pin,
		uint16_t &	latch_high,
		uint16_t &	input_high,
		uint16_t &	latch_low,
		uint16_t &	input_low
	)

noexcept

Drive one pin and verify OUTPUT latch + INPUT pad follow.

Parameters

	pin	PCA pin 0..15 (prefer an unused pad for bench integrity tests).
[out]	latch_high	OUTPUT bank after writing HIGH
[out]	input_high	INPUT bank after writing HIGH
[out]	latch_low	OUTPUT bank after writing LOW
[out]	input_low	INPUT bank after writing LOW

Returns: GPIO_SUCCESS when latch followed both edges; pad follow is best-effort (external shorts may still make INPUT disagree — check the out masks).

Friends And Related Symbol Documentation

◆ Pcal95555GpioPin

friend class Pcal95555GpioPin

friend

Allow Pcal95555GpioPin to access private interrupt methods.

Member Data Documentation

◆ config_shadow_

uint16_t Pcal95555Handler::config_shadow_ {0xFFFFU}

private

PCA POR default CONFIG (all input)

◆ handler_mutex_

RtosMutex Pcal95555Handler::handler_mutex_

mutableprivate

Thread safety for handler operations.

◆ i2c_adapter_

std::unique_ptr<HalI2cPcal95555Comm> Pcal95555Handler::i2c_adapter_

private

I2C adapter (created in Initialize).

◆ i2c_device_

BaseI2c& Pcal95555Handler::i2c_device_

private

I2C device reference (not owned).

◆ initialized_

bool Pcal95555Handler::initialized_ = false

private

Initialization state.

◆ interrupt_configured_

bool Pcal95555Handler::interrupt_configured_

private

Whether hardware interrupt is active.

◆ interrupt_pending_

std::atomic<bool> Pcal95555Handler::interrupt_pending_ {false}

private

Deferred interrupt flag (set in ISR, cleared in task context).

◆ interrupt_pin_

BaseGpio* Pcal95555Handler::interrupt_pin_

private

Hardware INT pin (optional, not owned).

◆ output_shadow_

uint16_t Pcal95555Handler::output_shadow_ {0xFFFFU}

private

PCA POR default OUTPUT.

◆ owned_pins_

std::array<std::unique_ptr<Pcal95555GpioPin>, 16> Pcal95555Handler::owned_pins_ {}

private

Heap pins from CreateGpioPin.

◆ pcal95555_driver_

std::unique_ptr<Pcal95555Driver> Pcal95555Handler::pcal95555_driver_

private

Typed driver (created in Initialize).

◆ pin_registry_

std::array<Pcal95555GpioPin*, 16> Pcal95555Handler::pin_registry_ {}

private

Non-owning registry slots.

◆ polarity_shadow_

uint16_t Pcal95555Handler::polarity_shadow_ {0}

private

POLARITY_INV.

◆ port_shadow_valid_

bool Pcal95555Handler::port_shadow_valid_ {false}

private

◆ prev_input_state_

uint16_t Pcal95555Handler::prev_input_state_ = 0

private

Last-read pin input levels (bitmask).

◆ pull_mode_cache_

std::array<hf_gpio_pull_mode_t, 16> Pcal95555Handler::pull_mode_cache_

private

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

Public Types

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Interrupt Management

Pin Factory

Detailed Description

Design Decisions

Member Typedef Documentation

◆ Pcal95555Driver

Constructor & Destructor Documentation

◆ Pcal95555Handler() [1/3]

◆ ~Pcal95555Handler()

◆ Pcal95555Handler() [2/3]

◆ Pcal95555Handler() [3/3]

Member Function Documentation

◆ AttachStaticPin()

◆ ClearErrorFlags()

◆ ConfigureHardwareInterrupt()

◆ CreateGpioPin()

◆ Deinitialize()

◆ DrainPendingInterrupts()

◆ DumpDiagnostics()

◆ EnableInputLatch()

◆ EnsureDeinitialized()

◆ EnsureInitialized()

◆ EnsureInitializedLocked()

◆ GetAllInterruptMasks()

◆ GetAllInterruptStatus()

◆ GetChipVariant()

◆ GetCreatedPinMask()

◆ GetDriver() [1/2]

◆ GetDriver() [2/2]

◆ GetErrorFlags()

◆ GetGpioPin()

◆ GetGpioPinRaw()

◆ GetI2cAddress()

◆ GetInterruptStatus()

◆ GetPullMode()

◆ HardwareInterruptCallback()

◆ HasAgileIO()

◆ HasInterruptSupport()

◆ Initialize()

◆ IsInitialized()

◆ IsInterruptConfigured()

◆ IsPinCreated()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PinCount()

◆ ProcessInterrupts()

◆ ProgramPortsAbsolute()

◆ ReadAllInputLevels()

◆ ReadConfigAndOutputPorts()

◆ ReadInput()

◆ ReadOutputLatchFromWire()

◆ ReadStandardRegisterBank()

◆ RegisterPinInterrupt()

◆ ResetToDefault()

◆ SetDirection()

◆ SetDirections()

◆ SetDriveStrength()

◆ SetInterruptMask()

◆ SetMultiplePolarityInversion()

◆ SetOutput()

◆ SetOutputMode()

◆ SetOutputs()

◆ SetOutputsVerified()

◆ SetPolarityInversion()

◆ SetPullMode()

◆ SetPullModes()

◆ Toggle()

◆ UnregisterPinInterrupt()

◆ ValidatePin()

◆ VerifyOutputPinEffect()

Friends And Related Symbol Documentation

◆ Pcal95555GpioPin

Member Data Documentation

◆ config_shadow_