Quickstart¶
Run the driver on your PC first, with no hardware; then blink an LED and read a button from your MCU: wire the chip, write a small port class, call the driver.
Datasheet sections this page relies on
From NXP PCAL9555A Rev. 2:
- Pins and package: 5 Pinning information, p. 4
- Application circuit: 8 Application design-in information, p. 20
All of them, with the driver API for each: Datasheet map.
Try it on your PC¶
examples/host/ runs the real driver against a simulated PCAL9555A, through a host
port. From the repository root, with CMake and a C++20 compiler:
cmake -S examples/host -B build-example
cmake --build build-example
./build-example/pcal9555_host_example
PCAL9555 driver 0.1.0 on the host
pcal9555: initialised
interrupt from 0x0800, inputs 0xF780, INT released
The calls in main.cpp are the ones below; only the port differs on an MCU. CI builds
and runs this example on every pull request.
1. Wire it¶
| MCU | PCA9555 / PCAL9555A | Notes |
|---|---|---|
| I2C SCL | SCL | Pull-up to VDD; 4.7 kΩ suits 100 kHz and 400 kHz |
| I2C SDA | SDA | Pull-up to VDD |
| GND | A0, A1, A2 | Address 0x20 (kI2cAddress); never leave them open |
| 3.3 V | VDD | 100 nF to GND close to the pin |
| GND | VSS | |
| P0_0 | LED and resistor to GND, for this example | |
| P1_0 | Push button to GND, and a pull-up (the PCAL9555A has one built in) |
INT is optional: leave it open for this example, or pull it up and wire it to an MCU input. The Hardware page has the full pin list.
2. Add the driver¶
Add the repository as a submodule and link the pcal9555::pcal9555 CMake target. Installation
covers CMake on any MCU, the installed package and ESP-IDF.
git submodule add https://github.com/kokeb-labs-drivers/driver-pcal9555.git external/driver-pcal9555
3. Write the port¶
The port is the only platform code: it brings the bus up and moves bytes. Replace the platform_* calls with your
SDK's.
class MyPort : public pcal9555::I2cInterface<MyPort> {
public:
// Bring the bus up once; later calls return true at once.
bool EnsureInitialized() noexcept {
if (!ready_) {
ready_ = platform_i2c_init();
}
return ready_;
}
// One write transaction: START, address + W, the bytes (command byte first), STOP.
bool Write(uint8_t addr, const uint8_t* data, std::size_t len) noexcept {
return platform_i2c_write(addr, data, len);
}
// Write then read with a repeated START in between.
bool WriteRead(uint8_t addr, const uint8_t* tx, std::size_t tx_len, uint8_t* rx,
std::size_t rx_len) noexcept {
return platform_i2c_write_read(addr, tx, tx_len, rx, rx_len);
}
private:
bool ready_ = false;
};
Porting explains each method, the optional hook and the transfer rules.
4. Blink and read¶
#include "pcal9555.hpp"
int blink_and_read(MyPort& port, bool& button_pressed) {
pcal9555::PCAL9555<MyPort> io(port, 0x20); // A2..A0 low; no I/O yet
if (auto r = io.EnsureInitialized(); !r) { // 1. bus up, presence, Config{} written, checked
return static_cast<int>(r.error); // Bus: nothing at 0x20; DeviceIdMismatch: another part
}
const uint16_t led = pcal9555::PinMask(0); // P0_0 drives an LED to ground
if (auto r = io.SetOutputs(led, true); !r) { // 2. level first, then direction: no glitch
return static_cast<int>(r.error);
}
if (auto r = io.SetDirection(led, pcal9555::Direction::Output); !r) {
return static_cast<int>(r.error);
}
const auto button = io.ReadPin(8); // 3. P1_0: a button to ground, pulled up externally
if (!button) {
return static_cast<int>(button.error);
}
button_pressed = !button.value;
return 0;
}
What each step does:
EnsureInitialized()calls your port'sEnsureInitialized(), reads the input ports to see that a chip ACKs 0x20, writesConfig{}(the power-up values: every pin an input, every output latch high) and reads each register back. A second call returnsOkat once with no I/O.SetOutputs()sets the output latch of P0_0 high first, thenSetDirection()makes it an output, so the pin never drives low in between. Each is one 3-byte write.ReadPin(8)reads input port 1 and returns P1_0; the button pulls it low when pressed.
This example is built by the host CI, so it compiles against the current headers.
If it does not work¶
| Symptom | First thing to check |
|---|---|
EnsureInitialized() returns Bus |
Nothing ACKs the address: A2..A0 levels, SDA and SCL pull-ups, VDD (Troubleshooting) |
EnsureInitialized() returns DeviceIdMismatch |
Another part answers at that address, or Config::variant names a PCAL9555A on a PCA9555 |
EnsureInitialized() returns Unsupported |
An Agile I/O field is set in Config while variant is Pca9555 |
| The LED does not light | The pin is still an input: SetDirection(..., Direction::Output) |
Next¶
- API guide: outputs, inputs, interrupts, errors.
- Agile I/O: the PCAL9555A features.
- Configuration: every
Configfield and Kconfig. - Examples: the host example and the MCU examples.