| .. _module-pw_i2c: |
| |
| ------ |
| pw_i2c |
| ------ |
| |
| .. warning:: |
| This module is under construction, not ready for use, and the documentation |
| is incomplete. |
| |
| pw_i2c contains interfaces and utility functions for using I2C. |
| |
| Features |
| ======== |
| |
| pw::i2c::Initiator |
| ------------------ |
| .. inclusive-language: disable |
| |
| 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". |
| |
| .. inclusive-language: enable |
| |
| pw::i2c::Device |
| --------------- |
| 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. |
| |
| pw::i2c::RegisterDevice |
| ----------------------- |
| 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. |
| |
| pw::i2c::MockInitiator |
| ---------------------- |
| 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: |
| |
| .. code-block:: cpp |
| |
| 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()); |
| |
| pw::i2c::GmockInitiator |
| ----------------------- |
| gMock of Initiator used for testing and mocking out the Initiator. |