Troubleshooting¶
Symptoms, causes and fixes, cheapest check first.
Datasheet sections this page relies on
- Address pins and the 7-bit address: NXP PCAL9555A Rev. 2, 6.1 Device address, p. 5
- Input latch: NXP PCAL9555A Rev. 2, 6.2.7 Input latch register pair, p. 9
- Pull-up and pull-down resistors: NXP PCAL9555A Rev. 2, 6.2.8 Pull-up/pull-down enable register pair; 6.2.9 Pull-up/pull-down selection register pair, p. 10
- Interrupt mask: NXP PCAL9555A Rev. 2, 6.2.10 Interrupt mask register pair, p. 11
- Open-drain ports and the 0x4F write order: NXP PCAL9555A Rev. 2, 6.2.12 Output port configuration register (4Fh), p. 12
- Power-on reset: NXP PCAL9555A Rev. 2, 6.4 Power-on reset; 8.3 Power-on reset requirements, p. 13
- Interrupt output (INT): NXP PCAL9555A Rev. 2, 6.5 Interrupt output, p. 14
- Power-on reset: NXP PCA9555 Rev. 10, 6.3 Power-on reset, p. 8
All of them, with the driver API for each: Datasheet map.
EnsureInitialized returns NoDevice¶
Nothing acknowledged the address: the port's GetLastFailure() saw the address byte NACKed. Check the supply of
the expander, then A2, A1 and A0 against the address you passed (AddressFromPins(a2, a1, a0)). A port without
GetLastFailure() reports the same fault as Bus.
EnsureInitialized returns Bus¶
The port reported a failure: its EnsureInitialized() returned false, or a transfer did. Without the optional
GetLastFailure() hook the driver cannot tell a NACK from a bus error, so the first transfer failing usually
means that nothing answers at the address; with it, Bus means the bus itself failed (a stuck line, lost
arbitration, a timeout) or the part refused a command byte.
- Check that your port's
EnsureInitialized()returnstrueon its own (log it). - Check A2, A1 and A0 against the address you passed:
AddressFromPins(a2, a1, a0). The pins must be tied to VDD or VSS, never left open. - Check the pull-ups on SDA and SCL (to the expander's VDD) and the supply.
- Read input port 0 at the address with your SDK (one write of 0x00, a repeated START, a one-byte read): an address that answers here and not in the driver points at the port's address handling (7-bit, not shifted). Avoid zero-length "scan" transfers; the driver never sends one (handbook KB-CPP-130).
- With
Variant::Pcal9555a: a failure at the second transfer (the 0x4F read) means the part NACKs the Agile I/O bank, so it is a PCA9555. UseVariant::Pca9555.
EnsureInitialized returns DeviceIdMismatch¶
Something answers at the address, but a register did not read back what was written, or a reserved bit of 0x4F read 1 on a driver configured for the PCAL9555A.
| Symptom | Likely cause | Fix |
|---|---|---|
Only with Variant::Pcal9555a |
A PCA9555 that does not NACK 0x4F | Use Variant::Pca9555, or fit a PCAL9555A |
| With either variant | Another part at the address (a different I/O expander, an EEPROM page, a sensor) | Check the part number and the address pins |
| Now and then | Corrupted bytes on the bus | Lower the clock; check the pull-ups and the wiring length |
EnsureInitialized returns Unsupported¶
An Agile I/O field of Config differs from its power-up value while variant is Pca9555. Set
variant = Variant::Pcal9555a if a PCAL9555A is fitted, or leave the field at its default.
EnsureInitialized returns InvalidArgument¶
The address is outside 0x20 to 0x27 (an 8-bit address such as 0x40 is the 7-bit 0x20 shifted), or a Config
field holds a value that is not an enumerator. Nothing was sent.
A call returns DeviceReset¶
The driver found a register back at its power-up value while its copy says otherwise: the expander went through a
power-on reset (a supply dip below the power-on reset voltage, section 6.4), or the chip dropped a write to that
register. Nothing was written, and the driver is uninitialised: call EnsureInitialized(), which writes every
register again with the outputs before the directions.
- Now and then: check the expander's supply (decoupling, a load that pulls it down when outputs switch, the ramp in section 8.3), then the bus.
- After every output change: the outputs draw more current than the supply gives; check the total current limits (Hardware).
An output does not change¶
- A call returned
WriteMismatch: the chip acknowledged the write but did not keep it. Retry (afterToggleOutputs(), withWriteOutputs(GetConfig().output_high_mask)); if it keeps happening, check the pull-ups, the bus length and noise near the lines, and compareReadOutputLatch()withGetConfig().output_high_mask. - The pin is still an input:
SetDirection(mask, Direction::Output). - The port is open-drain (PCAL9555A,
SetOutputMode()): a "high" output floats and needs an external pull-up. - A call returned
Bus: the write may or may not have arrived.GetConfig()shows the riskier value (a pin that may be an output counts as one, outputs at the written level); the next call reads the register first, andReadOutputLatch()/ReadInputMask()show what the chip holds. - The chip lost power since the start: it is back at its power-up state, every pin an input.
CheckForReset()returnsDeviceReset;EnsureInitialized()then writes the driver's copy again.
An input reads the wrong level¶
- Polarity inversion is on for the pin (
GetConfig().polarity_invert_mask). - On a PCAL9555A the input is latched (
input_latch_mask): the read shows the level that raised the interrupt, and the next read shows the pin. - A floating input: on the PCAL9555A check
pull_enable_maskandpull_up_mask.
INT stays low or never falls¶
| Symptom | Likely cause | Fix |
|---|---|---|
| Never falls on a PCAL9555A | Every pin is masked at power-up | SetInterruptEnabled(mask, true) |
GetLatchedInterrupts() is empty though INT fell |
The input port was read with ReadRegister(), which clears the status without latching it |
Use ReadInputs() or ReadPin(), which latch the status first while an input is unmasked |
| Stays low | The input port of the pin that raised it was not read | ReadInputs() (reads both ports); ReadPin() releases only its own port |
| Falls when a pin becomes an input | The data sheet's false interrupt: the pin level differs from the input register | Read the inputs once after changing directions |
| Never falls on either part | No pull-up on INT, or the pin is an output | INT is open-drain; only inputs raise it |
Bench checks¶
Hardware-dependent behaviour is not verified on hardware yet. With a PCAL9555A (or PCA9555) at 0x20 on an MCU port, run the ESP32 example or your own code:
EnsureInitialized()returnsOk; a logic analyser shows a read of 0x00 (and of 0x4F for a PCAL9555A), the register writes and their read-backs, each pair in one transfer.- An LED on P0_0 follows
ToggleOutputs(PinMask(0)). ReadPin(8)follows a button on P1_0; INT falls on a press and rises afterReadInputs().- A PCA9555 driven with
Variant::Pcal9555afails withBus(orDeviceIdMismatch) and the analyser shows no write: this checks the data sheets' silence about unimplemented command bytes. - With the address pins at another level,
EnsureInitialized()with the default address returnsBus, orNoDevicewith a port that hasGetLastFailure()(the host example port does; the ESP32 one cannot). GetLatchedInterrupts()keeps a pin afterReadInputs()has released INT, untilClearLatchedInterrupts().- Power-on reset: configure P0_0 as an open-drain output driven low into a load (an LED to VDD through a resistor),
then pull the expander's VDD below the power-on reset voltage for longer than the section 8.3 minimum while the
MCU keeps running.
ReadInputMask()reads 0xFFFF;CheckForReset()returnsDeviceReset, andSetDirection(PinMask(8), Direction::Output)returnsDeviceResetwith the analyser showing one read and no write, and the LED stays off.EnsureInitialized()brings P0_0 back low and open-drain. This checks that a real dip reloads table 4 as the model does.