1.. _module-pw_i2c: 2 3------ 4pw_i2c 5------ 6 7.. warning:: 8 This module is under construction, not ready for use, and the documentation 9 is incomplete. 10 11pw_i2c contains interfaces and utility functions for using I2C. 12 13Features 14======== 15 16pw::i2c::Initiator 17------------------ 18.. inclusive-language: disable 19 20The common interface for initiating transactions with devices on an I2C bus. 21Other documentation sources may call this style of interface an I2C "master", 22"central" or "controller". 23 24.. inclusive-language: enable 25 26pw::i2c::Device 27--------------- 28The common interface for interfacing with generic I2C devices. This object 29contains ``pw::i2c::Address`` and wraps the ``pw::i2c::Initiator`` API. 30Common use case includes streaming arbitrary data (Read/Write). Only works 31with devices with a single device address. 32 33pw::i2c::RegisterDevice 34----------------------- 35The common interface for interfacing with register devices. Contains methods 36to help read and write registers from and to the device. Users should have a 37understanding of the capabilities of their device such as register address 38sizes, register data sizes, byte addressability, bulk transactions, etc in 39order to effectively use this interface. 40 41pw::i2c::MockInitiator 42---------------------- 43A generic mocked backend for for pw::i2c::Initiator. This is specifically 44intended for use when developing drivers for i2c devices. This is structured 45around a set of 'transactions' where each transaction contains a write, read and 46a timeout. A transaction list can then be passed to the MockInitiator, where 47each consecutive call to read/write will iterate to the next transaction in the 48list. An example of this is shown below: 49 50.. code-block:: cpp 51 52 using pw::i2c::Address; 53 using pw::i2c::MakeExpectedTransactionlist; 54 using pw::i2c::MockInitiator; 55 using pw::i2c::WriteTransaction; 56 using std::literals::chrono_literals::ms; 57 58 constexpr Address kAddress1 = Address::SevenBit<0x01>(); 59 constexpr auto kExpectWrite1 = pw::bytes::Array<1, 2, 3, 4, 5>(); 60 constexpr auto kExpectWrite2 = pw::bytes::Array<3, 4, 5>(); 61 auto expected_transactions = MakeExpectedTransactionArray( 62 {WriteTransaction(pw::OkStatus(), kAddress1, kExpectWrite1, 1ms), 63 WriteTransaction(pw::OkStatus(), kAddress2, kExpectWrite2, 1ms)}); 64 MockInitiator i2c_mock(expected_transactions); 65 66 // Begin driver code 67 ConstByteSpan write1 = kExpectWrite1; 68 // write1 is ok as i2c_mock expects {1, 2, 3, 4, 5} == {1, 2, 3, 4, 5} 69 Status status = i2c_mock.WriteFor(kAddress1, write1, 2ms); 70 71 // Takes the first two bytes from the expected array to build a mismatching 72 // span to write. 73 ConstByteSpan write2 = std::span(kExpectWrite2).first(2); 74 // write2 fails as i2c_mock expects {3, 4, 5} != {3, 4} 75 status = i2c_mock.WriteFor(kAddress2, write2, 2ms); 76 // End driver code 77 78 // Optionally check if the mocked transaction list has been exhausted. 79 // Alternatively this is also called from MockInitiator::~MockInitiator(). 80 EXPECT_EQ(mocked_i2c.Finalize(), OkStatus()); 81 82pw::i2c::GmockInitiator 83----------------------- 84gMock of Initiator used for testing and mocking out the Initiator. 85