Skip to content

Configuration

Every setting the driver writes, where it comes from, and how menuconfig sets it.

Datasheet sections this page relies on
  • Power-up value of every register: NXP PCAL9555A Rev. 2, Table 4 Command byte (power-up default), p. 6
  • Open-drain ports and the 0x4F write order: NXP PCAL9555A Rev. 2, 6.2.12 Output port configuration register (4Fh), p. 12
  • Registers, command bytes and power-up values: NXP PCA9555 Rev. 10, 6.2 Registers; 6.2.1 Command byte (Table 4), p. 6

All of them, with the driver API for each: Datasheet map.

Config

One pcal9555::Config holds every register the driver writes. Pass it to the constructor; EnsureInitialized() writes it and reads it back, and ApplyConfig() replaces it later. Its defaults are the power-up values of the registers (PCAL9555A data sheet table 4), so Config{} changes nothing on a freshly powered chip.

constexpr pcal9555::Config BoardConfig() {
  pcal9555::Config c{};                     // power-up values: every pin an input
  c.variant = pcal9555::Variant::Pcal9555a; // the part fitted has Agile I/O
  c.output_high_mask = 0x0000;              // port 0 starts low...
  c.input_mask = 0xFF00;                    // ...and drives; port 1 stays inputs
  c.pull_enable_mask = 0xFF00;              // pull resistors on port 1 only
  c.interrupt_mask = 0x00FF;                // port 1 raises INT, port 0 does not
  c.port0_mode = pcal9555::OutputMode::OpenDrain;
  return c;
}
static_assert(pcal9555::Validate(BoardConfig()) == pcal9555::Error::Ok); // checked at build time

pcal9555::Error StartBoard(MyPort& port) {
  static pcal9555::PCAL9555<MyPort> io(port, 0x20, BoardConfig()); // stored, no I/O
  return io.EnsureInitialized().error;                             // written and read back
}

Bit n of each mask is pin n (P0_0 to P0_7 are pins 0 to 7, P1_0 to P1_7 pins 8 to 15).

Field Register Power-up Meaning
variant (driver side) Variant::Pca9555 Which part is fitted; Pcal9555a enables the fields below the line
output_high_mask Output port 0x02, 0x03 0xFFFF 1 drives the pin high when it is an output
polarity_invert_mask Polarity inversion 0x04, 0x05 0x0000 1 inverts how the input pin reads
input_mask Configuration 0x06, 0x07 0xFFFF 1 = input, 0 = output
drive_strength_codes Drive strength 0x40 to 0x43 0xFFFFFFFF Two bits per pin (DriveStrength), pin n at bits 2n+1..2n
input_latch_mask Input latch 0x44, 0x45 0x0000 1 latches input changes until the port is read
pull_enable_mask Pull enable 0x46, 0x47 0xFFFF 1 connects the pin's 100 kΩ resistor
pull_up_mask Pull selection 0x48, 0x49 0xFFFF 1 = pull-up, 0 = pull-down
interrupt_mask Interrupt mask 0x4A, 0x4B 0xFFFF 1 = the pin raises no interrupt
port0_mode, port1_mode Output port configuration 0x4F PushPull OpenDrain for a whole port

The fields from drive_strength_codes down exist on the PCAL9555A only. With variant = Variant::Pca9555 they must keep their power-up values:

constexpr pcal9555::Config PlainPca9555() {
  pcal9555::Config c{}; // variant = Pca9555: the registers both parts share
  c.input_mask = 0xFFF0;
  c.pull_up_mask = 0; // an Agile I/O field: Validate() and EnsureInitialized() say Unsupported
  return c;
}
static_assert(pcal9555::Validate(PlainPca9555()) == pcal9555::Error::Unsupported);

Write order

EnsureInitialized() and ApplyConfig() write the Agile I/O bank first (drive strength, input latch, pull selection, pull enable, interrupt mask, then 0x4F), then the output port, the polarity inversion and last the configuration registers. The output stage and the output levels are therefore in place before any pin becomes an output, as the data sheet recommends for 0x4F (section 6.2.12), and no pin glitches to the power-up level.

Validate

pcal9555::Validate(config) checks a configuration without touching the chip, and is constexpr, so a configuration built at compile time can be checked with static_assert. It returns InvalidArgument when an enum holds a value that is not an enumerator, and Unsupported when variant is Pca9555 and an Agile I/O field differs from its power-up value. EnsureInitialized() and ApplyConfig() run it before any I/O. Every mask value is legal.

Change it at run time

pcal9555::Error Reconfigure(pcal9555::PCAL9555<MyPort>& io) {
  pcal9555::Config c = io.GetConfig(); // the driver's copy, pin changes included
  c.interrupt_mask = 0x0000;           // every pin raises INT from now on
  return io.ApplyConfig(c).error;      // running: written and read back; else stored
}

GetConfig() is the driver's copy of the registers: the configuration passed in, updated by every successful pin call. ApplyConfig() on a running driver writes every register and reads each back (DeviceIdMismatch if one does not hold its value); before the start it only stores the configuration. The variant of a running driver cannot change (InvalidArgument): Deinitialize() first. The pin calls (API guide) change one register pair each and are cheaper for a few pins.

Kconfig

Under ESP-IDF, idf.py menuconfig shows PCA9555 / PCAL9555A GPIO expander when the driver is a component of the project (Installation); the menu is _config/Kconfig. The options reach the code only through inc/pcal9555_kconfig.hpp, never through a driver signature:

pcal9555::Error StartFromMenuconfig(MyPort& port) {
  static pcal9555::PCAL9555<MyPort> io(port, 0x20, pcal9555::KconfigDefaults());
  return io.EnsureInitialized().error;
}
Option Default Config field
CONFIG_PCAL9555_VARIANT_PCA9555, _PCAL9555A (a choice) PCA9555 variant
CONFIG_PCAL9555_OUTPUT_HIGH_MASK (hex) 0xFFFF output_high_mask
CONFIG_PCAL9555_INPUT_MASK (hex) 0xFFFF input_mask

The I2C address is a constructor argument, not a Config field, so it is not a Kconfig option. Without Kconfig (plain CMake, other platforms) KconfigDefaults() returns Config{}. Both cases are host tests.

Next: Porting.