This module is under construction, not ready for use, and the documentation is incomplete.

pw_i2c contains interfaces and utility functions for using I2C.



The common interface for initiating transactions with devices on an I2C bus. Other documentation sources may call this style of interface an I2C “master”, “central” or “controller”.


The common interface for interfacing with generic I2C devices. This object contains pw::i2c::Address and wraps the pw::i2c::Initiator API. Common use case includes streaming arbitrary data (Read/Write). Only works with devices with a single device address.


The common interface for interfacing with register devices. Contains methods to help read and write registers from and to the device. Users should have a understanding of the capabilities of their device such as register address sizes, register data sizes, byte addressability, bulk transactions, etc in order to effectively use this interface.


A generic mocked backend for for pw::i2c::Initiator. This is specifically intended for use when developing drivers for i2c devices. This is structured around a set of ‘transactions’ where each transaction contains a write, read and a timeout. A transaction list can then be passed to the MockInitiator, where each consecutive call to read/write will iterate to the next transaction in the list. An example of this is shown below:

using pw::i2c::Address;
using pw::i2c::MakeExpectedTransactionlist;
using pw::i2c::MockInitiator;
using pw::i2c::WriteTransaction;
using std::literals::chrono_literals::ms;

constexpr Address kAddress1 = Address::SevenBit<0x01>();
constexpr auto kExpectWrite1 = pw::bytes::Array<1, 2, 3, 4, 5>();
constexpr auto kExpectWrite2 = pw::bytes::Array<3, 4, 5>();
auto expected_transactions = MakeExpectedTransactionArray(
    {WriteTransaction(pw::OkStatus(), kAddress1, kExpectWrite1, 1ms),
     WriteTransaction(pw::OkStatus(), kAddress2, kExpectWrite2, 1ms)});
MockInitiator i2c_mock(expected_transactions);

// Begin driver code
ConstByteSpan write1 = kExpectWrite1;
// write1 is ok as i2c_mock expects {1, 2, 3, 4, 5} == {1, 2, 3, 4, 5}
Status status = i2c_mock.WriteFor(kAddress1, write1, 2ms);

// Takes the first two bytes from the expected array to build a mismatching
// span to write.
ConstByteSpan write2 = std::span(kExpectWrite2).first(2);
// write2 fails as i2c_mock expects {3, 4, 5} != {3, 4}
status = i2c_mock.WriteFor(kAddress2, write2, 2ms);
// End driver code

// Optionally check if the mocked transaction list has been exhausted.
// Alternatively this is also called from MockInitiator::~MockInitiator().
EXPECT_EQ(mocked_i2c.Finalize(), OkStatus());


gMock of Initiator used for testing and mocking out the Initiator.