Changelog¶
What changed in each release of the driver. Entries under Breaking need source changes in code that used the affected API.
[Unreleased]¶
Changed¶
- The repository moved to kokeb-labs-drivers; URLs follow.
- Hardware page: the pinout, the block diagram and the application circuit are now figures drawn from
docs/hardware.yml, which also generates the pin table (replacing the hand-written one) and the parts table. Every pin, block and part cites the datasheet section and page; values the datasheet does not give are marked as not confirmed.kokeb-docs hardware --kicad-netlistexports the circuit. - Synced with the driver template:
tools/preflight.shruns clang-tidy over every file CI lints, as CI does, and the hardware-lessons review adds the switch-off, channel-in-doubt and fuzz-skip lessons.
[0.1.0] - 2026-11-09¶
Breaking¶
-
Error::DeviceReset(18) is new. AswitchoverErrorwithoutdefault:must add it (-Wswitch).SetDirection()andApplyConfig()now return it, and so does a setter about to rewrite the register the reset check reads, when the expander went through a power-on reset since the start; the driver is then uninitialised, so callEnsureInitialized()again. Since v0.1.0-rc.1: -
Config::verify_writesis removed. Read-back is now chosen per call: every pin and Agile I/O setter (SetDirection(),SetOutputs(),WriteOutputs(),ToggleOutputs(),SetPolarityInversion(),SetDriveStrength(),SetPull(),SetInputLatch(),SetInterruptEnabled(),SetOutputMode()) takes a last argumentVerify verify = Verify::None, a new enum inpcal9555_types.hpp. Code that setverify_writes = falsedrops that line; code that wants the read-back passesVerify::ReadBackto the calls that need it. A value that is not an enumerator returnsInvalidArgumentwith no I/O. Errorisenum class [[nodiscard]] Error: a call whoseErroris dropped (for exampleValidate(config);as a statement) now warns, and fails a-Werrorbuild. Use the value, or cast it tovoidon purpose.Error::NoDevice(17) is new. AswitchoverErrorwithoutdefault:must add it (-Wswitch). It is returned only with a port that has the new optionalGetLastFailure()hook; a port without it seesBusas before.GetConfig()on a temporary driver (an rvalue) is deleted, since the reference it returned would dangle; call it on a named driver.reg::kDriveBitsPerPinis auint32_t(wasuint8_t).
The port hooks keep their signatures: EnsureInitialized(), Write() and WriteRead() are unchanged, and the
new hook is optional, so an existing port compiles as it is. A port whose hooks were not noexcept, or took
another length type than std::size_t, no longer satisfies I2cPort (it broke the documented contract before).
Added¶
CheckForReset(): finds a power-on reset (section 6.4) by reading one register whose copy differs from its power-up value; one read, none when the copy is all power-up values, plus one per register whose last write failed when no other register is left to read.- The bus requirements as
constexprvalues inpcal9555_i2c_interface.hpp, with their data sheet sections:kI2cAddress(0x20, section 6.1),kMaxClockHz(400 kHz, section 13 table 33) andkRepeatedStart(section 7.2). The host and ESP32 example ports check their clock, their address and the repeated START against them withstatic_assert.kDefaultI2cAddressstays, with the same value. - The optional port hook
bool GetLastFailure(I2cFailure& failure) noexceptandenum class I2cFailure(Other,AddressNack,DataNack). When a transfer fails and the port reportsAddressNack, every call returnsError::NoDeviceinstead ofBus, so an absent or unpowered chip is told apart from a bus fault. The host example port implements it; the ESP32 port does not, becausei2c_masterdoes not say which byte was NACKed. - Raw access and diagnostics:
ReadRegister(command)(one read, no retry, any command byte the configured part implements,reg::IsImplemented()),GetLastInputs(),GetLastOutput()and an interrupt latch,GetLatchedInterrupts()andClearLatchedInterrupts(), which keeps every interrupt status the driver read after the input read that clears it. None of the accessors does I/O, and the hot path gains two compares per read and no transfer. Config::operator==(every field is an integer or an enumeration).- Tests: a model independent of the driver's headers, with its own register map and data sheet sections, and
tests/test_model.cpp, which compares the two maps at compile time; bus line modes (SDA floating or stuck low) and a deaf device against the start-up and every read;NoDevicewith and without the hook; compile-fail tests for a narrowed hook parameter, a hook withoutnoexceptand misdeclared optional hooks. The fuzzer also chooses address NACKs and whether the port can tell them, and checks thatNoDeviceappears only after one. - Strict-dialect header checks (
pcal9555_header_checks): every public header compiled alone as ISO C++20 with-pedantic-errorson GCC and Clang, in the Cortex-M cross-build, and in the ESP-IDF build throughexamples/esp32/main/pcal9555_cxx20_check.cpp. -
The review skills
cpp20-profile,misra-reviewandhardware-lessons-review, and a read-only reviewer definition, from the driver template. -
First version of the driver for the NXP PCA9555 and PCAL9555A 16-bit I2C GPIO expanders, written on the Kokeb Labs driver template.
pcal9555::PCAL9555<Port>with the configuration in the constructor and one start-up call,EnsureInitialized(): presence check by reading the input ports, every register written and read back as the identity check, and on a PCAL9555A the reserved bits of 0x4F checked before any write.ApplyConfig(),Deinitialize()(every pin an input).- Pin calls by mask, each one register-pair transfer from the driver's copy of the registers:
SetDirection(),SetOutputs(),WriteOutputs(),ToggleOutputs(),SetPolarityInversion(),ReadInputs(),ReadPin(). - PCAL9555A Agile I/O:
SetDriveStrength(),SetPull(),SetInputLatch(),SetInterruptEnabled(),ReadInterruptStatus(),SetOutputMode();Config::variantselects the part and the Agile I/O calls returnUnsupportedon a PCA9555. Configwith the power-up value of every register, aconstexprValidate(),PinMask(),AddressFromPins()andDriveStrengthAll(); Kconfig options for the variant, the output levels and the directions.- Host tests over a protocol model of both parts, with every transfer of every operation failed in turn; the host and ESP32 examples. Not verified on hardware.
- clang-tidy runs the CERT C++ checks (
cert-*) as well; the library code had no finding. - The
Log()hook is documented asvoid Log(LogLevel, const char* message): the message is plain text, and the examples print it with"%s"instead of using it as a format string (no C variadic function, CERT DCL50-CPP; no format string from data). A port with the old variadic signature still compiles. - After
WriteMismatchevery setter's copy holds what was asked for,SetDriveStrength()included; retry an absolute call as it was, and afterToggleOutputs()resend withWriteOutputs(GetConfig().output_high_mask)(a repeated toggle would undo it). ReadOutputLatch(),ReadInputMask()andReadPolarityInversion()read what the chip holds, not the driver's copy; the Output Port registers read back the output latch, not the pin, so a lost write shows there.Config::verify_writes(default on): once started, every write is read back, and a register that did not keep its value returnsError::WriteMismatch(16), the driver's first chip-specific error. An I2C acknowledge carries no checksum, and the data sheet allows for data corruption (PCAL9555A section 8.3). A register that does not keep its value after the start isWriteMismatch;DeviceIdMismatchnow means only "another part answers", at start-up.- Three chip figures drawn from the source: the register map with each pair's owner and power-up value
(Hardware), what one pin call does with
verify_writesand how a handler retries (API guide), and theEnsureInitialized()steps with the error each one returns (Contract). - A libFuzzer target over failed, lost and replaced transfers (
tests/fuzz/,-DPCAL9555_BUILD_FUZZERS=ON); its corpus replays as a CTest on every compiler, and CI fuzzes every pull request. - API guide: "Read back what the chip holds" and "Use it from a handler" (start-up, retries, recovery, locks, timeouts).
docs/datasheets.yml(handbook ADR-0019): the PCAL9555A (Rev. 2) and PCA9555 (Rev. 10) data sheets with their SHA-256, and every topic the driver takes from them.kokeb-docs genbuilds from it the README card, the Datasheet map page (docs/datasheet.md) and a box of the sections each page relies on. The README is restructured as the front door: at a glance, wiring, port, first code, what it does, and which page to read for what.- Documentation site with the Doxygen API reference: https://kokeb-labs-drivers.github.io/driver-pcal9555/.
- Releases carry a source archive, an SPDX SBOM, one zip per example firmware build,
SHA256SUMS, and signed build provenance for every file (check a download withgh attestation verify).
Changed¶
- The
misra-review,cpp20-profileandnew-driver-from-templateskills anddocs/repo-setup.mdfollow the template: reading the MISRA report, the known tool misfires, enumeration ranges without a sentinel, and the settings tool. tools/preflight.shand theverifyandhardware-lessons-reviewskills follow the template: every check CI runs that a workstation can run, in one command, and the rules for device resets, faults the chip clears itself, dropped writes, switch-offs that no uncertainty refuses and a model that changes state on its own.- Follows the driver template's portable ownership: copyright belongs to
The driver-pcal9555 authors(LICENSE, every source header,driver.ymlauthors, the docs footer).tools/check_standalone.pyruns in the Handbook source checks job and keeps the code and docs about this chip only.AGENTS.mdfollows the template's structure; the issue and PR templates ask for the board, MCU and port in one field. - The port concepts match each hook's address against exactly one
noexceptsignature withdetail::ExactHook<Port, Sig>::Take(&Port::Hook)instead of probing it with a convertingdetail::Exactly<T>: no conversion operator is left. A misdeclared hook is still a compile error.kAlwaysFalsetakes a class and the enumeration helpers an enumeration (ClassType,Enumeration), each with a compile-fail test.HasGetLastFailurematchesbool GetLastFailure(I2cFailure&) noexceptthe same way. - Both datasheets are listed with the kind
Datasheet, so the generated cards and the Datasheet map name the datasheet on every line that carries its revision date. - Include guards (
#ifndef PCAL9555_..._HPP) replace#pragma oncein every header, the.ippand the test and example headers. - Every target builds as ISO C++20 (
CMAKE_CXX_EXTENSIONS OFF,-pedantic-errors, the C++20 deprecation warnings as errors), the tests and fuzzers with the standard library's bounds checks. - The port concept checks the hooks exactly: each argument's type,
noexceptand theboolresult. The optional hooks are detected by named concepts in one place, and one declared with another signature is a compile error. - Narrow operands are widened to
uint32_tbefore every shift and bitwise operation, enumerations are checked with one helper before use, and the bus helpers take spans with the size fixed at compile time; a zero-length transfer is refused before any I/O. Validate()compares the wholeConfigwith its power-up value for a PCA9555, so an Agile I/O field added later is covered without a change there.- Behaviour change: the start-up identity check writes
reg::kIdentityPattern(0x55AA) to the polarity inversion pair and reads it back before any configured value is written (two more transfers; at most 24 for a PCAL9555A start-up). A floating or stuck line, or a device that acknowledges everything and reads a fixed byte, now fails withDeviceIdMismatchwhatever theConfig; before, aConfigwhose registers matched that byte passed. The polarity pair changes only how inputs read, so no pin is driven before the identity is confirmed. - A first drive strength pair that reads back differently no longer marks pins 8 to 15 as changed in
GetConfig(): their pair was never sent. - An optional hook declared with any other parameter list (
GetLastFailure()with no argument or an rvalue reference,Log()without the level) is a compile error instead of being ignored. Deinitialize()clearsGetLastInputs(),GetLastOutput()and the interrupt latch.- The presence check's input read is documented as clearing an interrupt left pending from before the start.
- The documentation describes only this driver against its data sheets: the Status page explains each design choice (read-back on request, the identity pattern, outputs before directions, no waits) by data sheet section, and the API guide, Testing and Porting pages give bench steps as procedures.
-
The source checks job runs the handbook's
checks/source_checks.pyat its C++20-profile commit; the managed files (skills,_config/.clang-tidy,ci-repo-checks.yml) follow driver template a4a1056. -
CI runs fewer jobs, from the driver template: the host tests build GCC and Clang in one job; DCO, the org standard, Markdown and YAML lint, the handbook rules, template drift and cppcheck are steps of one
Repository checksjob (ci-repo-checks.yml, replacingci-handbook.yml,ci-cpp-analysis.yml,ci-markdown-lint.ymlandci-yaml-lint.yml); cross-compile and host quality use ci-tools' one-job layouts. No check is dropped. The workflows have no manual (workflow_dispatch) trigger any more. - Behaviour change: a pin call no longer reads its write back by default (it did with the old
verify_writes, which defaulted to on). A timing-critical call now makes only the transfer the data sheet needs, and a write the chip acknowledged but lost is no longer reported unless the call passesVerify::ReadBack, which costs one more I2C read per register written and returnsWriteMismatchon a difference.EnsureInitialized()andApplyConfig()still read every register back, unconditionally. - The README and the Testing page link to the handbook, which is now public.
- MISRA C++:2023 conformance: parentheses make operator precedence explicit (Rule 8.0.1); the compile-time
test vectors pass arguments of the parameter's exact type through the new
detailliterals_u8,_u16and_u32, which do not compile for a value out of range (Rule 7.0.6); everyif ... else ifchain ends with anelse(Rule 9.4.1);ToString(Error)ends itsswitchwithdefault:and the host tests build with-Wswitch-enum, so a new enumerator still warns (Rule 9.4.2); the register write loop has a constant bound (Rule 9.5.1); the privatewriteAll()andverifyAll()declarations use the definitions' parameter names (Rule 13.3.3);Config::operator==is a[[nodiscard]]hidden friend (Rule 16.6.1); and the.ippinclude at the end ofpcal9555.hppcarries the deviation markerMD-CPP-009(Rule 19.0.3). Behaviour is unchanged.
Fixed¶
- After a power-on reset of the expander,
SetDirection()on any pin turned the old outputs back on, high and push-pull (table 4), andVerify::ReadBackpassed: it wrote only the configuration pair. It now checks for a reset first (DeviceReset, nothing written) and writes 0x4F, the output pair and the configuration pair from the copy, in the data sheet's order (section 6.2.12). Cost: one read plus one write pair on a PCA9555, plus a 1-byte write on a PCAL9555A. - On a PCAL9555A with an unmasked input,
ReadInputs()andReadPin()cleared the interrupt status before the interrupt latch saw it (sections 6.2.11, 6.5). They now read the status pair intoGetLatchedInterrupts()first: one more read per input read while an input is unmasked. - A write whose transfer failed with
Buscould still have reached the chip (a NACK or a lost ACK after the bytes), but the copy kept the old value and later setters built on it: a failedSetDirection(..., Input)left the pin an output while the copy said input, and a followingToggleOutputs()inverted a stale level. The copy now takes the riskier of the old and the asked value (configuration: output if either; output port: the written level; drive strength: the stronger code; 0x4F: push-pull if either; the other pairs: the written value), the register is marked unknown, and the next call that builds on it reads it first (one more read, only after a failure). A successful write of the pair,ReadOutputLatch(),ReadInputMask(),ReadPolarityInversion(),ApplyConfig()andEnsureInitialized()make it known again; the reset check never reads an unknown register.NoDevice(an address NACK) leaves the copy unchanged. An unknown register read back at its power-up value isDeviceReset(falsely, once, when the failed write's old or new value was the power-up value); with no other register to check, the reset check reads the unknown ones. A failedApplyConfig()now leaves the new values of the registers written before the failure, the failed one unknown and the rest at their old values, instead of the previous configuration. SetDirection(..., Direction::Input)that leaves every pin an input writes only the configuration pair, with no reset check; releasing while other outputs remain writes the configuration pair before 0x4F and the output pair, so a failure after it leaves the pins released.- The chip model can go through a power-on reset on its own in the middle of a session (
reset_after), and the fuzzer chooses resets between calls.