|
PCAL9555 Driver 0.1.0
API reference
|
Driver for one PCA9555 or PCAL9555A on a platform port. More...
#include <pcal9555.hpp>
Public Member Functions | |
| PCAL9555 (Port &port, uint8_t address=kI2cAddress, const Config &config={}) noexcept | |
Bind the driver to a port, a 7-bit I2C address and a configuration. No I/O, no checks: EnsureInitialized() validates both. | |
| PCAL9555 (const PCAL9555 &)=delete | |
| One driver object per chip. | |
| PCAL9555 & | operator= (const PCAL9555 &)=delete |
| One driver object per chip. | |
Lifecycle | |
| Result< void > | EnsureInitialized () noexcept |
Start the chip on the first call; Ok at once, with no I/O, once it has succeeded. | |
| bool | IsInitialized () const noexcept |
| Result< void > | Deinitialize () noexcept |
| Make every pin a high-impedance input (the power-up direction), the safe state, and mark the driver uninitialised. | |
Configuration | |
| Result< void > | ApplyConfig (const Config &config) noexcept |
Replace the configuration. When initialised, check for a reset (one read, see CheckForReset()), then write every register and read each back; otherwise only store it for the next EnsureInitialized() (no I/O). | |
| const Config & | GetConfig () const &noexcept |
| void | GetConfig () const &&=delete |
| Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044). | |
| uint8_t | GetAddress () const noexcept |
| Result< void > | CheckForReset () noexcept |
| Find out whether the chip went through a power-on reset since the start. | |
Pins (PCA9555 and PCAL9555A) | |
| Result< void > | SetDirection (uint16_t mask, Direction direction, Verify verify=Verify::None) noexcept |
Set the direction of the pins in mask (configuration registers). | |
| Result< void > | SetOutputs (uint16_t mask, bool high, Verify verify=Verify::None) noexcept |
Drive the pins in mask high or low (output port registers). Pins configured as inputs keep the value for when they become outputs. | |
| Result< void > | WriteOutputs (uint16_t high_mask, Verify verify=Verify::None) noexcept |
| Write both output port registers at once. | |
| Result< void > | ToggleOutputs (uint16_t mask, Verify verify=Verify::None) noexcept |
Invert the output value of the pins in mask. | |
| Result< void > | SetPolarityInversion (uint16_t mask, bool invert, Verify verify=Verify::None) noexcept |
Invert (or stop inverting) how the input pins in mask read (polarity inversion). | |
| Result< uint16_t > | ReadInputs () noexcept |
| Read both input ports: the level of every pin, inputs and outputs, after polarity inversion. Reading clears the interrupt of both ports. | |
| Result< bool > | ReadPin (uint8_t pin) noexcept |
Read the level of one pin. Reads its port's input register only, which clears that port's interrupt. With an unmasked input on a PCAL9555A it first reads the interrupt status pair into GetLatchedInterrupts(), as ReadInputs() does. | |
Agile I/O (PCAL9555A only) | |
| Result< void > | SetDriveStrength (uint16_t mask, DriveStrength level, Verify verify=Verify::None) noexcept |
Set the output drive strength of the pins in mask. Writes both drive strength pairs. | |
| Result< void > | SetPull (uint16_t mask, Pull pull, Verify verify=Verify::None) noexcept |
Connect a pull-up or pull-down to the pins in mask, or disconnect it. Writes the selection pair, then the enable pair. A port in open-drain mode disconnects its resistors whatever this says. | |
| Result< void > | SetInputLatch (uint16_t mask, bool latch, Verify verify=Verify::None) noexcept |
Latch (or stop latching) input changes of the pins in mask: a latched pin keeps the level that raised the interrupt until the input port is read. | |
| Result< void > | SetInterruptEnabled (uint16_t mask, bool enable, Verify verify=Verify::None) noexcept |
Let the input pins in mask raise INT on a change, or mask them (interrupt mask registers; every pin is masked at power-up). | |
| Result< uint16_t > | ReadInterruptStatus () noexcept |
| Read which pins raised the interrupt (interrupt status registers). Masked pins read 0. Reading the status does not clear the interrupt; reading the input ports does. | |
| Result< void > | SetOutputMode (Bank bank, OutputMode mode, Verify verify=Verify::None) noexcept |
| Select push-pull or open-drain outputs for a whole port (output port configuration). | |
Read-back: what the chip holds, as opposed to <tt>GetConfig()</tt>, what was asked for | |
| Result< uint16_t > | ReadOutputLatch () noexcept |
| Read both output port registers: the level each pin is told to drive. | |
| Result< uint16_t > | ReadInputMask () noexcept |
| Read both configuration registers. | |
| Result< uint16_t > | ReadPolarityInversion () noexcept |
| Read both polarity inversion registers. | |
Diagnostics: raw access, the last values read and the interrupt latch | |
| Result< uint8_t > | ReadRegister (uint8_t command) noexcept |
| Read one register, once: one 1-byte write-read, no retry, no check of the value (handbook KB-CPP-129). For bring-up and diagnostics. | |
| uint16_t | GetLastInputs () const noexcept |
| uint16_t | GetLastOutput () const noexcept |
| uint16_t | GetLatchedInterrupts () const noexcept |
The pins any read of the interrupt status registers has reported since ClearLatchedInterrupts(), ORed together (handbook KB-CPP-119). No I/O. | |
| void | ClearLatchedInterrupts () noexcept |
Empty the latch of GetLatchedInterrupts(). No I/O; the chip is not touched. | |
Driver for one PCA9555 or PCAL9555A on a platform port.
Lifecycle: construct with the configuration (no I/O), EnsureInitialized() (bus up, presence check, every register written and read back), use, optionally Deinitialize() (every pin back to an input). Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded; no call starts the chip implicitly.
Pins are numbered 0 to 15: 0 to 7 are P0_0 to P0_7, 8 to 15 are P1_0 to P1_7. Calls that change pins take a mask (bit n = pin n, PinMask() builds one); a mask of 0 is InvalidArgument. The driver keeps a copy of every register it wrote (GetConfig()): a pin call computes the new register pair from that copy and writes it in one transfer, without reading it first. Nothing is read back unless the call's last argument is Verify::ReadBack (Verify::None by default); only then can a pin call return WriteMismatch.
Every call listed below as returning Bus returns NoDevice instead when the port's optional GetLastFailure() hook reports that nothing acknowledged the address (the chip was removed or lost power). The chip NACKs no transfer the driver sends by design (handbook KB-CPP-130).
Neither part has a reset pin or a reset flag, but a supply dip below the power-on reset voltage reloads every register with its power-up value (section 6.4, table 4). The driver finds that by reading one register whose copy differs from its power-up value (detail::FindResetSentinel()): in CheckForReset(), SetDirection(), ApplyConfig(), and in a setter about to rewrite that register (so a setter returns DeviceReset only when it would have rewritten the evidence; the others send their one write as before). A call that finds it writes nothing, marks the driver uninitialised and returns DeviceReset; EnsureInitialized() then writes the copy again in the datasheet's order.
A write whose transfer failed with Bus may still have reached the chip (a NACK or an ACK lost after the bytes were clocked in). The copy then takes the riskier of the old and the asked value (detail::Riskier(): an output rather than an input, the written level, the stronger drive, push-pull) and the register is unknown: the next call that builds on it reads it into the copy first (one more read), a successful write or a read-back call makes it known again, and the reset check never reads it. NoDevice, an address NACK, proves nothing arrived: the copy stays.
The Agile I/O calls (drive strength, pull resistors, input latch, interrupt mask and status, output mode) need Config::variant == Variant::Pcal9555a; on a driver configured for the PCA9555 they return Unsupported without I/O.
Optional port hooks, found at compile time:
| Hook | Used for | Without it |
|---|---|---|
void Log(LogLevel, const char* message) noexcept | One line per lifecycle event or failure | Nothing is logged |
bool GetLastFailure(I2cFailure& failure) noexcept | Telling an address NACK (NoDevice) from other bus failures | Every failed transfer is Bus |
A hook declared with the wrong signature (for example void GetLastFailure(...)) is a compile error. The chip needs no wait between transfers, so the port has no DelayUs() hook, and it has no reset pin, so there is no GpioSet() hook.
| Port | Your class derived from I2cInterface<Port>. |
|
inlineexplicitnoexcept |
Bind the driver to a port, a 7-bit I2C address and a configuration. No I/O, no checks: EnsureInitialized() validates both.
| port | The port; it must outlive the driver. |
| address | 7-bit I2C address, 0x20 to 0x27 (kI2cAddress plus the address pins, AddressFromPins()); EnsureInitialized() rejects any other with InvalidArgument. |
| config | What EnsureInitialized() writes. |
|
noexcept |
Replace the configuration. When initialised, check for a reset (one read, see CheckForReset()), then write every register and read each back; otherwise only store it for the next EnsureInitialized() (no I/O).
| config | Checked with Validate() before any I/O. Once initialised its variant must stay the same (Deinitialize() first to change it). |
Ok, InvalidArgument (including a changed variant), Unsupported, Bus, DeviceReset (nothing written, the configuration not stored, the driver uninitialised) or WriteMismatch (a register did not keep its value; the full configuration is always read back).
|
noexcept |
Find out whether the chip went through a power-on reset since the start.
Neither part has a reset flag (section 6.4). The driver reads one register whose copy differs from its power-up value (table 4), preferring the Agile I/O pairs and the polarity pair, then 0x4F, the configuration pair and the output pair (detail::FindResetSentinel()); if it reads its power-up value, the chip reset. When every register of the copy is at its power-up value nothing is sent: a reset then leaves the chip as the driver believes it to be. Call it where a supply dip is possible, for example once per control period or before a critical output change: one 2-byte read (one 1-byte read when 0x4F is the register), 113 µs at 400 kHz. A register whose last write failed is never the one read; when no other is left, the check reads the unknown ones instead (one read each), and one back at its power-up value is a reset. When the failed write's old or new value was itself the power-up value, that is a false DeviceReset: one time, recovered by EnsureInitialized().
A write to that register that the chip acknowledged but dropped reads the same way; the recovery is the same. SetDirection(), ApplyConfig() and a setter about to rewrite the checked register run the same check first.
Ok, NotInitialized, Bus or DeviceReset (the driver is now uninitialised: call EnsureInitialized(), which writes every register again in the datasheet's order).
|
noexcept |
Make every pin a high-impedance input (the power-up direction), the safe state, and mark the driver uninitialised.
All inputs is the power-up direction: nothing is driven, the PCAL9555A pull resistors stay as configured. The driver is uninitialised afterwards even if the write failed. GetConfig() keeps the configuration (with the pin changes made since), so the next EnsureInitialized() writes it again. On an uninitialised driver it does nothing and returns Ok.
Ok or Bus.
|
noexcept |
Start the chip on the first call; Ok at once, with no I/O, once it has succeeded.
Checks the stored configuration with Validate() and the address, brings the bus up, checks that the part answers, writes every register of the configuration and reads each back. The chip has no reset pin and no software reset, so instead of a reset every register the driver owns is written, which also undoes whatever a previous run left behind. The presence check reads the input ports, which also clears an interrupt left pending from before the start (an address NACK is NoDevice with a port that has GetLastFailure(), otherwise Bus); on a PCAL9555A it also reads the output port configuration register, whose reserved bits 7..2 read 0. The identity check then writes reg::kIdentityPattern to the polarity inversion pair and reads it back, which no floating, stuck or deaf line can echo, before any configured value is written; the read-back of every register after the writes confirms it: a register that does not hold what was written means another part answers. After a failure the driver stays uninitialised and the next call starts again from the beginning.
Ok, InvalidArgument (the configuration or the address; no I/O), Unsupported (an Agile I/O field for a PCA9555; no I/O), NoDevice, Bus or DeviceIdMismatch.
|
inlinenoexcept |
|
inlinenoexcept |
After a write that failed with Bus the register is unknown: the chip may hold the old value, the written one or (a pair) one byte of each. The copy then shows the riskier of old and written for the direction (an output), the drive strength (the stronger) and 0x4F (push-pull), and the written value for every other field, the output levels included: not necessarily what the pins do. The driver reads an unknown register from the chip before it builds on it; to see the chip now, call ReadOutputLatch(), ReadInputMask() or ReadPolarityInversion(), which also make the register known again.
|
inlinenoexcept |
ReadInputs(), ReadPin(), a raw read or the start-up presence check), bit n = pin n; 0 before the first read. No I/O.
|
inlinenoexcept |
ReadOutputLatch(), a Verify::ReadBack of an output write, the start-up read-back or a raw read), bit n = 1 when pin n is set to drive high. Compare it with GetConfig().output_high_mask, what was asked for, to see a lost write without I/O. The power-up value 0xFFFF before the first read. No I/O.
|
inlinenoexcept |
The pins any read of the interrupt status registers has reported since ClearLatchedInterrupts(), ORed together (handbook KB-CPP-119). No I/O.
Reading the input ports clears the chip's interrupt and its status (section 6.5), so a status the driver has read is kept here until the caller clears it. PCAL9555A only; always 0 on a driver configured for the PCA9555, which has no status register.
|
inlinenoexcept |
EnsureInitialized() and before Deinitialize(). No I/O.
|
noexcept |
Read both configuration registers.
NotInitialized / Bus.
|
noexcept |
Read both input ports: the level of every pin, inputs and outputs, after polarity inversion. Reading clears the interrupt of both ports.
Reading an input port clears its interrupt and its interrupt status (sections 6.2.11, 6.5). So on a PCAL9555A with an unmasked input (input_mask & ~interrupt_mask not 0) the call first reads the interrupt status pair into GetLatchedInterrupts(): one more 2-byte read. If that read fails, the inputs are not read and nothing is cleared.
NotInitialized / Bus.
|
noexcept |
Read which pins raised the interrupt (interrupt status registers). Masked pins read 0. Reading the status does not clear the interrupt; reading the input ports does.
NotInitialized, Unsupported or Bus.
|
noexcept |
Read both output port registers: the level each pin is told to drive.
For an output pin this is the truth ReadInputs() cannot give: on a loaded or shared line the pin level may differ from the latch. Compare it with GetConfig().output_high_mask to find a lost write.
NotInitialized / Bus.
|
noexcept |
Read the level of one pin. Reads its port's input register only, which clears that port's interrupt. With an unmasked input on a PCAL9555A it first reads the interrupt status pair into GetLatchedInterrupts(), as ReadInputs() does.
| pin | 0 to 15. |
NotInitialized, InvalidArgument or Bus.
|
noexcept |
Read both polarity inversion registers.
NotInitialized / Bus.
|
noexcept |
Read one register, once: one 1-byte write-read, no retry, no check of the value (handbook KB-CPP-129). For bring-up and diagnostics.
Side effects are the chip's own: reading an input port (0x00, 0x01) clears that port's interrupt (section 6.5), without the status read ReadInputs() does first. The value also updates GetLastInputs(), GetLastOutput() or the interrupt latch, as the same register read by any other call would.
| command | The command byte: 0x00 to 0x07, and on a driver configured for the PCAL9555A also 0x40 to 0x4D and 0x4F (reg::IsImplemented()). Any other is InvalidArgument with no I/O: the PCA9555 data sheet does not say how the part answers it. |
NotInitialized, InvalidArgument, NoDevice or Bus.
|
noexcept |
Set the direction of the pins in mask (configuration registers).
To avoid a glitch, set the output level with SetOutputs() before making a pin an output.
A pin that becomes an output drives its output latch through its port's output stage at once, and a power-on reset sets the latch high and the stage push-pull (table 4). So the call first checks for a reset (CheckForReset(), one read) and then writes, from the driver's copy, in the datasheet's order (section 6.2.12): 0x4F (PCAL9555A), the output pair, the configuration pair. When pins become outputs, even a reset that the check missed makes no pin an output at the reset latch level or stage. The one exception is a partial release (below): a reset in the microseconds between its check and its configuration write leaves the pins that stay outputs at the power-up level until the 0x4F and output writes after it land. Cost: one read and two write pairs on a PCA9555, one read, one 1-byte write and two write pairs on a PCAL9555A (no read when the copy is all power-up values).
Releasing pins (Direction::Input) is the safe direction. When every pin ends up an input, the configuration pair is the only transfer, with no check: nothing can be driven. When other pins stay outputs: the check, then the configuration pair first (the pins are released by the first write), then 0x4F and the output pair for the remaining outputs.
| mask | Pins to change; not 0. |
| direction | The direction. |
| verify | Verify::ReadBack to read the configuration pair back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, InvalidArgument, Bus, DeviceReset (nothing written) or WriteMismatch.
|
noexcept |
Set the output drive strength of the pins in mask. Writes both drive strength pairs.
| mask | Pins to change; not 0. |
| level | The drive strength. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, Unsupported, InvalidArgument, Bus, DeviceReset or WriteMismatch.
|
noexcept |
Latch (or stop latching) input changes of the pins in mask: a latched pin keeps the level that raised the interrupt until the input port is read.
| mask | Pins to change; not 0. |
| latch | true to latch. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, Unsupported, InvalidArgument, Bus, DeviceReset or WriteMismatch.
|
noexcept |
Let the input pins in mask raise INT on a change, or mask them (interrupt mask registers; every pin is masked at power-up).
| mask | Pins to change; not 0. |
| enable | true to unmask. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, Unsupported, InvalidArgument, Bus, DeviceReset or WriteMismatch.
|
noexcept |
Select push-pull or open-drain outputs for a whole port (output port configuration).
| bank | The port. |
| mode | The output stage. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, Unsupported, InvalidArgument (not an enumerator), Bus, DeviceReset or WriteMismatch.
|
noexcept |
Drive the pins in mask high or low (output port registers). Pins configured as inputs keep the value for when they become outputs.
| mask | Pins to change; not 0. |
| high | true for high. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, InvalidArgument, Bus, DeviceReset or WriteMismatch.
|
noexcept |
Invert (or stop inverting) how the input pins in mask read (polarity inversion).
| mask | Pins to change; not 0. |
| invert | true to invert. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, InvalidArgument, Bus, DeviceReset or WriteMismatch.
|
noexcept |
Connect a pull-up or pull-down to the pins in mask, or disconnect it. Writes the selection pair, then the enable pair. A port in open-drain mode disconnects its resistors whatever this says.
| mask | Pins to change; not 0. |
| pull | The resistor. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, Unsupported, InvalidArgument, Bus, DeviceReset or WriteMismatch.
|
noexcept |
Invert the output value of the pins in mask.
The new value is computed from GetConfig(). After WriteMismatch the copy already holds the toggled value, so do not retry with ToggleOutputs() (it would toggle back): resend with WriteOutputs(GetConfig().output_high_mask).
| mask | Pins to toggle; not 0. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, InvalidArgument, Bus, DeviceReset or WriteMismatch.
|
noexcept |
Write both output port registers at once.
| high_mask | Bit n = 1 drives pin n high. |
| verify | Verify::ReadBack to read the written register back (one more read); a value that is not an enumerator is InvalidArgument. |
Ok, NotInitialized, Bus, DeviceReset or WriteMismatch.