|
PCA9555 / PCAL9555A Driver
API reference
|
Driver for the PCA9555 / PCAL9555A / PCAL95555AHF I²C GPIO expander. More...
#include <pcal95555.hpp>
Classes | |
| struct | PinInterruptCallback |
| Structure to store pin interrupt callback information. More... | |
Public Member Functions | |
| PCAL95555 (I2cType *bus, bool a0_level, bool a1_level, bool a2_level, ChipVariant variant=ChipVariant::Unknown) | |
| PCAL95555 (I2cType *bus, uint8_t address, ChipVariant variant=ChipVariant::Unknown) | |
| void | SetRetries (int retries) noexcept |
| Configure retry mechanism for I2C transactions. | |
| uint16_t | GetErrorFlags () const noexcept |
| Retrieve currently latched error flags. | |
| bool | HasError (Error e) const noexcept |
| Check if a specific error flag is set. | |
| bool | HasAnyError () const noexcept |
| Check if any error flag is set. | |
| void | ClearError (Error e) noexcept |
| Clear a single error flag. | |
| void | ClearErrorFlags (uint16_t mask=0xFFFF) noexcept |
| Clear specific error flags by raw bitmask. | |
| void | ResetToDefault () noexcept |
| Reset all registers to their power-on default state. | |
| void | InitFromConfig () noexcept |
| Initialize the device using values from Kconfig. | |
| bool | SetPinDirection (uint8_t pin, GPIODir dir) noexcept |
| Set the direction of a single GPIO pin. | |
| bool | SetMultipleDirections (uint16_t mask, GPIODir dir) noexcept |
| Set the direction for multiple GPIO pins at once using a bitmask. | |
| bool | SetDirections (std::initializer_list< std::pair< uint8_t, GPIODir > > configs) noexcept |
| bool | ReadPin (uint8_t pin) noexcept |
| Read the current logical level of a GPIO pin. | |
| bool | ReadPin (uint8_t pin, bool &level) noexcept |
| Read the logical level of a GPIO pin and report whether the read worked. | |
| bool | WritePin (uint8_t pin, bool value) noexcept |
| Write a logical level to a GPIO output pin. | |
| bool | SetMultipleOutputs (uint16_t mask, bool value) noexcept |
| bool | TogglePin (uint8_t pin) noexcept |
| Toggle the output state of a GPIO pin. | |
| 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 |
| Read a dual-port register pair into a 16-bit pin mask. | |
| bool | WriteDualPortRegister (uint8_t reg0, uint8_t reg1, uint16_t value) noexcept |
| Write a dual-port register pair from a 16-bit pin mask (no readback). | |
| bool | SetPullEnable (uint8_t pin, bool enable) noexcept |
| Enable or disable the pull-up/pull-down resistor on a pin. | |
| bool | SetPullEnables (std::initializer_list< std::pair< uint8_t, bool > > configs) noexcept |
| bool | SetPullDirection (uint8_t pin, bool pull_up) noexcept |
| Select internal pull-up or pull-down resistor direction. | |
| bool | SetPullDirections (std::initializer_list< std::pair< uint8_t, bool > > configs) noexcept |
| bool | GetPullConfiguration (uint16_t &enable_mask, uint16_t &direction_mask) noexcept |
| Read the current pull resistor configuration from hardware registers. | |
| bool | SetDriveStrength (uint8_t pin, DriveStrength level) noexcept |
| Configure the output drive strength for a GPIO pin. | |
| 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 |
| Retrieve and clear the interrupt status. | |
| bool | SetOutputMode (bool port_0_open_drain, bool port_1_open_drain) noexcept |
| Configure per-port output mode (push-pull or open-drain). | |
| bool | SetPinPolarity (uint8_t pin, Polarity polarity) noexcept |
| Configure input polarity inversion for a single pin. | |
| bool | SetMultiplePolarities (uint16_t mask, Polarity polarity) noexcept |
| Configure input polarity for multiple pins using a bitmask. | |
| bool | SetPolarities (std::initializer_list< std::pair< uint8_t, Polarity > > configs) noexcept |
| bool | EnableInputLatch (uint8_t pin, bool enable) noexcept |
| Enable or disable the input latch for a single pin. | |
| bool | EnableMultipleInputLatches (uint16_t mask, bool enable) noexcept |
| Enable or disable input latch for multiple pins using a bitmask. | |
| 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 |
| Unregister callback for a specific pin interrupt. | |
| void | SetInterruptCallback (const std::function< void(uint16_t)> &callback) noexcept |
| bool | RegisterInterruptHandler () noexcept |
| void | HandleInterrupt () noexcept |
| Internal handler to process an interrupt event. | |
| uint8_t | GetAddress () const noexcept |
| Get the current I2C address of the device. | |
| uint8_t | GetAddressBits () const noexcept |
| Get the current A2-A0 address bits. | |
| bool | HasAgileIO () const noexcept |
| ChipVariant | GetChipVariant () const noexcept |
| Get the detected chip variant. | |
| 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 |
| Mark the driver initialized without the probe read. | |
Static Public Member Functions | |
| static constexpr const char * | GetDriverVersion () noexcept |
| static constexpr uint8_t | GetDriverVersionMajor () noexcept |
| Get the compiled driver major version number. | |
| static constexpr uint8_t | GetDriverVersionMinor () noexcept |
| Get the compiled driver minor version number. | |
| static constexpr uint8_t | GetDriverVersionPatch () noexcept |
| Get the compiled driver patch version number. | |
Protected Member Functions | |
| bool | readRegister (uint8_t reg, uint8_t &value) noexcept |
| Read a device register with retry logic. | |
| bool | writeRegister (uint8_t reg, uint8_t value) noexcept |
| Write a single byte to a device register with retry logic. | |
Private Member Functions | |
| uint16_t | readPinStates () noexcept |
| Read current pin states from input port registers. | |
| bool | initialize () noexcept |
| Perform actual initialization of the driver. | |
| void | setError (Error error_code) noexcept |
| void | clearError (Error error_code) noexcept |
| bool | readDualPort (uint8_t reg0, uint8_t reg1, uint8_t &val0, uint8_t &val1) noexcept |
| Read both port registers (port0 and port1) in one call. | |
| bool | writeDualPort (uint8_t reg0, uint8_t reg1, uint8_t val0, uint8_t val1) noexcept |
| Write both port registers (port0 and port1) in one call. | |
| bool | modifySinglePinRegister (uint8_t reg0, uint8_t reg1, uint8_t pin, bool bit_value) noexcept |
| Single-pin read-modify-write on a dual-port register pair. | |
| bool | modifyDualPortByMask (uint8_t reg0, uint8_t reg1, uint16_t mask, bool bit_value) noexcept |
| Batch mask read-modify-write on a dual-port register pair. | |
| bool | requireAgileIO () noexcept |
| Check that the chip supports Agile I/O, setting error if not. | |
| bool | changeAddressImpl (uint8_t new_bits) noexcept |
| Shared implementation for ChangeAddress overloads. | |
| bool | detectChipVariant () noexcept |
| Detect the chip variant by probing an Agile I/O register. | |
Static Private Member Functions | |
| static constexpr uint8_t | calculateAddress (uint8_t bits) |
| Calculate I2C address from A2-A0 bits. | |
Private Attributes | |
| I2cType * | i2c_ |
| uint8_t | dev_addr_ |
| uint8_t | address_bits_ |
| int | retries_ {1} |
| uint16_t | error_flags_ {0} |
| std::function< void(uint16_t)> | irq_callback_ |
| PinInterruptCallback | pin_callbacks_ [16] |
| uint16_t | previous_pin_states_ {0} |
| bool | initialized_ {false} |
| bool | a0_level_ |
| bool | a1_level_ |
| bool | a2_level_ |
| ChipVariant | chip_variant_ {ChipVariant::Unknown} |
| ChipVariant | user_variant_ {ChipVariant::Unknown} |
| uint8_t | xfer_byte_ {0} |
Driver for the PCA9555 / PCAL9555A / PCAL95555AHF I²C GPIO expander.
This driver supports both the standard PCA9555 and the enhanced PCAL9555A. The chip variant is auto-detected during initialization by probing the Agile I/O register bank (0x40-0x4F). Features requiring the extended register set are gracefully disabled when a standard PCA9555 is detected.
Chip Compatibility:
| Feature | PCA9555 | PCAL9555A |
|---|---|---|
| GPIO direction | Yes | Yes |
| Pin read/write/toggle | Yes | Yes |
| Polarity inversion | Yes | Yes |
| Pull-up/pull-down config | No | Yes |
| Drive strength | No | Yes |
| Input latch | No | Yes |
| Interrupt mask/status | No | Yes |
| Output mode (PP/OD) | No | Yes |
| I2cType | The I2C interface implementation type that inherits from pcal95555::I2cInterface<I2cType> |
| pcal95555::PCAL95555< I2cType >::PCAL95555 | ( | I2cType * | bus, |
| bool | a0_level, | ||
| bool | a1_level, | ||
| bool | a2_level, | ||
| ChipVariant | variant = ChipVariant::Unknown |
||
| ) |
|
explicit |
|
inlinestaticconstexprprivate |
Calculate I2C address from A2-A0 bits.
| bits | 3-bit value (0-7) representing A2, A1, A0 pins. |
|
noexcept |
|
noexcept |
|
privatenoexcept |
Shared implementation for ChangeAddress overloads.
Sets GPIO address pins, updates internal state, verifies communication, and re-detects chip variant at the new address.
| new_bits | Address bits (0-7) to set. |
|
noexcept |
Clear a single error flag.
| e | The error flag to clear. |
|
privatenoexcept |
|
noexcept |
Clear specific error flags by raw bitmask.
| mask | Bitmask of errors to clear (default: all). |
|
noexcept |
|
noexcept |
|
noexcept |
|
privatenoexcept |
Detect the chip variant by probing an Agile I/O register.
Detection sequence (3-step sandwich):
If step 1 fails the bus is broken and variant is left as Unknown. If step 2 succeeds the chip is PCAL9555A. If step 2 NACKs but step 3 succeeds the chip is a standard PCA9555. If step 3 also fails the detection is inconclusive (bus error).
|
noexcept |
Enable or disable the input latch for a single pin.
| pin | Zero-based pin index (0-15). |
| enable | true to enable latch; false to disable. |
|
noexcept |
|
noexcept |
Enable or disable input latch for multiple pins using a bitmask.
| mask | Bitmask selecting pins. |
| enable | true to enable; false to disable. |
mask is 0.
|
noexcept |
|
noexcept |
Mark the driver initialized without the probe read.
Use only when the bus/adapter path has already proven INPUT_PORT access (e.g. bring-up) and EnsureInitialized()'s first readRegister is known to misbehave on the target master. Sets variant as both user and detected chip type and seeds previous pin state to 0.
| variant | PCA9555 or PCAL9555A (not Unknown). |
variant is usable; false if Unknown.
|
noexcept |
Get the current I2C address of the device.
|
noexcept |
Get the current A2-A0 address bits.
|
noexcept |
Get the detected chip variant.
|
inlinestaticconstexprnoexcept |
|
inlinestaticconstexprnoexcept |
Get the compiled driver major version number.
|
inlinestaticconstexprnoexcept |
Get the compiled driver minor version number.
|
inlinestaticconstexprnoexcept |
Get the compiled driver patch version number.
|
noexcept |
Retrieve currently latched error flags.
|
noexcept |
Retrieve and clear the interrupt status.
|
noexcept |
Read the current pull resistor configuration from hardware registers.
Reads the PULL_ENABLE (0x46-0x47) and PULL_SELECT (0x48-0x49) registers and returns them as 16-bit bitmasks (bit N corresponds to pin N).
| [out] | enable_mask | Bitmask: bit set = pull resistor enabled on that pin. |
| [out] | direction_mask | Bitmask: bit set = pull-up, bit clear = pull-down. Only meaningful for pins where the corresponding enable_mask bit is set. |
|
noexcept |
Internal handler to process an interrupt event.
This method is called by the I2C interface when the INT pin fires. It reads the interrupt status registers, determines which pins triggered interrupts, checks edge conditions, and invokes registered callbacks.
Reading the interrupt status registers clears the interrupt condition.
|
noexcept |
|
noexcept |
Check if any error flag is set.
|
noexcept |
Check if a specific error flag is set.
| e | The error flag to test. |
|
noexcept |
Initialize the device using values from Kconfig.
This writes the configuration registers using the CONFIG_PCAL95555_INIT_* options defined at compile time.
|
privatenoexcept |
Perform actual initialization of the driver.
This private method contains all initialization logic including:
|
privatenoexcept |
Batch mask read-modify-write on a dual-port register pair.
For each bit set in mask (0-15), sets or clears the corresponding bit in the appropriate port register. Does NOT call EnsureInitialized().
|
privatenoexcept |
Single-pin read-modify-write on a dual-port register pair.
Selects the correct port register based on pin number, reads, modifies the bit, and writes back. Does NOT validate pin or call EnsureInitialized().
|
noexcept |
|
privatenoexcept |
Read both port registers (port0 and port1) in one call.
|
noexcept |
Read a dual-port register pair into a 16-bit pin mask.
| reg0 | Port-0 register (bits 0..7). | |
| reg1 | Port-1 register (bits 8..15). | |
| [out] | value | Bit N corresponds to pin N. |
|
noexcept |
Read the current logical level of a GPIO pin.
| pin | Zero-based pin index (0-15). |
|
noexcept |
Read the logical level of a GPIO pin and report whether the read worked.
| pin | Zero-based pin index (0-15). |
| level | Receives the level (true = high) on success; unchanged on failure. |
|
noexcept |
|
privatenoexcept |
Read current pin states from input port registers.
|
protectednoexcept |
Read a device register with retry logic.
| reg | Register address to read. |
| value | Reference to store the read byte. |
|
noexcept |
| bool pcal95555::PCAL95555< I2cType >::RegisterPinInterrupt | ( | uint8_t | pin, |
| InterruptEdge | edge, | ||
| std::function< void(uint8_t pin, bool state)> | callback | ||
| ) |
|
privatenoexcept |
Check that the chip supports Agile I/O, setting error if not.
|
noexcept |
Reset all registers to their power-on default state.
Available registers are set to inputs, pull-ups enabled, interrupts masked, drive strength set to full, and output mode configured as push-pull as specified by the datasheet.
|
noexcept |
|
noexcept |
Configure the output drive strength for a GPIO pin.
| pin | Zero-based pin index (0-15). |
| level | Drive strength level (Level0..Level3). |
|
noexcept |
|
privatenoexcept |
|
noexcept |
|
noexcept |
Set the direction for multiple GPIO pins at once using a bitmask.
| mask | Bitmask where each set bit indicates a pin to configure. |
| dir | Common direction for all selected pins. |
mask is 0.
|
noexcept |
|
noexcept |
Configure input polarity for multiple pins using a bitmask.
| mask | Bitmask selecting pins to configure. |
| polarity | Normal or Inverted for all selected pins. |
mask is 0.
|
noexcept |
Configure per-port output mode (push-pull or open-drain).
| port_0_open_drain | true for open-drain on port 0. |
| port_1_open_drain | true for open-drain on port 1. |
|
noexcept |
Set the direction of a single GPIO pin.
| pin | Zero-based pin index (0-15). |
| dir | Direction enum: Input or Output. |
|
noexcept |
Configure input polarity inversion for a single pin.
| pin | Zero-based pin index (0-15). |
| polarity | Polarity::Normal or Polarity::Inverted. |
|
noexcept |
|
noexcept |
Select internal pull-up or pull-down resistor direction.
| pin | Zero-based pin index (0-15). |
| pull_up | true for pull-up; false for pull-down. |
|
noexcept |
|
noexcept |
Enable or disable the pull-up/pull-down resistor on a pin.
| pin | Zero-based pin index (0-15). |
| enable | true to enable; false to disable. |
|
noexcept |
|
noexcept |
Configure retry mechanism for I2C transactions.
| retries | Maximum number of retry attempts on failure. Note: setting N will result in N+1 total attempts per transfer. |
|
noexcept |
Toggle the output state of a GPIO pin.
| pin | Zero-based pin index (0-15). |
|
noexcept |
Unregister callback for a specific pin interrupt.
| pin | Pin number (0-15) to unregister callback for. |
|
privatenoexcept |
Write both port registers (port0 and port1) in one call.
|
noexcept |
Write a dual-port register pair from a 16-bit pin mask (no readback).
Prefer this over read-modify-write when the caller maintains a shadow of the port (OUTPUT / CONFIG / POLARITY). Absolute writes avoid corrupting latches if a prior register read returned the wrong bank.
| reg0 | Port-0 register (bits 0..7). |
| reg1 | Port-1 register (bits 8..15). |
| value | Bit N corresponds to pin N. |
|
noexcept |
Write a logical level to a GPIO output pin.
| pin | Zero-based pin index (0-15). |
| value | true to drive high, false to drive low. |
|
noexcept |
|
protectednoexcept |
Write a single byte to a device register with retry logic.
| reg | Register address to write. |
| value | Byte value to write. |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
1.9.8