Examples

This guide provides complete, working examples demonstrating various use cases for the PCAL95555 driver.

Example 1: Basic GPIO Control

This example shows basic input/output operations.

#include "pcal95555.hpp"
 
// Implement I2C interface (see platform_integration.md)
class MyI2c : public pcal95555::I2cInterface<MyI2c> {
    // ... implement Write() and Read()
};
 
MyI2c i2c;
// Option 1: Using address directly (recommended)
pcal95555::PCAL95555<MyI2c> gpio(&i2c, 0x20); // Address 0x20 (default)
 
// Option 2: Using pin levels
// pcal95555::PCAL95555<MyI2c> gpio(&i2c, false, false, false);
 
void app_main(void) {
    // Initialize driver (lazy initialization happens automatically, but explicit is clearer)
    if (!gpio.EnsureInitialized()) {
        ESP_LOGE("APP", "Failed to initialize PCAL95555");
        return;
    }
    
    gpio.ResetToDefault();
    
    // Configure pin 0 as output
    gpio.SetPinDirection(0, pcal95555::PCAL95555<MyI2c>::GPIODir::Output);
    gpio.WritePin(0, true);
    
    // Configure pin 1 as input
    gpio.SetPinDirection(1, pcal95555::PCAL95555<MyI2c>::GPIODir::Input);
    bool value = gpio.ReadPin(1);
}

Explanation

1. Reset: Put device in known state
2. Configure: Set pin directions
3. Use: Read and write pin states

Example 3: Interrupt Handling

This example shows how to use interrupts with per-pin callbacks.

// Configure pin 8 as input with interrupt
gpio.SetPinDirection(8, pcal95555::PCAL95555<MyI2c>::GPIODir::Input);
gpio.SetPullEnable(8, true);
gpio.SetPullDirection(8, true); // Pull-up
gpio.EnableInputLatch(8, true);
gpio.ConfigureInterrupt(8, InterruptState::Enabled); // Enable interrupt
 
// Register per-pin callback for rising edge
gpio.RegisterPinInterrupt(8, InterruptEdge::Rising, [](uint16_t pin, bool state) {
    printf("Pin %d interrupt: went HIGH\n", pin);
});
 
// Register interrupt handler with I2C interface (for hardware INT pin)
gpio.RegisterInterruptHandler(); // Sets up INT pin handling
 
// In your main loop or ISR (if using polling)
gpio.HandleInterrupt();

Configure Multiple Interrupts

// Configure interrupts for multiple pins at once
gpio.ConfigureInterrupts({
    {0, InterruptState::Enabled},   // Enable on pin 0
    {5, InterruptState::Enabled},   // Enable on pin 5
    {10, InterruptState::Enabled},  // Enable on pin 10
    {3, InterruptState::Disabled}   // Disable on pin 3
});

Global Interrupt Callback

// Set global callback for all interrupts
gpio.SetInterruptCallback([](uint16_t status) {
    printf("Interrupt on pins: 0x%04X\n", status);
    // Handle interrupt
});

Example 5: Drive Strength (PCAL9555A only)

This example shows drive strength configuration. Requires PCAL9555A.

if (gpio.HasAgileIO()) {
    // Set pin as output with reduced drive strength
    gpio.SetPinDirection(0, pcal95555::PCAL95555<MyI2c>::GPIODir::Output);
    gpio.SetDriveStrength(0, pcal95555::PCAL95555<MyI2c>::DriveStrength::Level1); // 50% strength
}

Example 8: Chip Variant Detection

This example shows how to check which chip is connected and conditionally use features.

// After initialization (auto or explicit)
gpio.EnsureInitialized();
 
// Method 1: Boolean check
if (gpio.HasAgileIO()) {
    printf("PCAL9555A detected -- full feature set available\n");
    gpio.SetPullEnable(0, true);
    gpio.SetDriveStrength(0, DriveStrength::Level3);
} else {
    printf("PCA9555 detected -- standard GPIO only\n");
    // Use external pull-up resistors instead
}
 
// Method 2: Variant enum
auto variant = gpio.GetChipVariant();
switch (variant) {
    case pcal95555::ChipVariant::PCA9555:
        printf("Standard PCA9555\n");
        break;
    case pcal95555::ChipVariant::PCAL9555A:
        printf("Enhanced PCAL9555A with Agile I/O\n");
        break;
    default:
        printf("Unknown variant (detection may have failed)\n");
        break;
}

Running the Examples

ESP32

Two example applications are available in examples/esp32:

cd examples/esp32
 
# Comprehensive test suite (tests all 43 API methods)
./scripts/build_app.sh pcal95555_comprehensive_test Debug
./scripts/flash_app.sh flash_monitor pcal95555_comprehensive_test Debug
 
# LED animation demo (16-LED patterns)
./scripts/build_app.sh pcal95555_led_animation Debug
./scripts/flash_app.sh flash_monitor pcal95555_led_animation Debug

Other Platforms

Adapt the I2C interface implementation for your platform (see Platform Integration) and compile with your platform's toolchain.

Next Steps

• Review the API Reference for method details
• Check Troubleshooting if you encounter issues
• Explore the examples directory for more examples