Oveview

Cross-platform I2C API with interactive debugging. Main docs: https://pigweed.dev/pw_i2c.

Classes
class	pw::i2c::Address

class	pw::i2c::Device

class	pw::i2c::I2cService
	RPC service for performing I2C transactions. More...

class	pw::i2c::Initiator
	The common, base driver interface for initiating thread-safe transactions with devices on an I2C bus. Other documentation may call this style of interface an I2C "master", "central", or "controller". More...

class	pw::i2c::GmockInitiator

class	pw::i2c::MockMessage

class	pw::i2c::MockMessageTransaction

class	pw::i2c::MockMessageInitiator

class	pw::i2c::Transaction

class	pw::i2c::MockInitiator

class	pw::i2c::Message

class	pw::i2c::RegisterDevice

Typedefs
using	pw::i2c::I2cService::InitiatorSelector = pw::Function< Initiator *(size_t pos)>

Enumerations
enum class	pw::i2c::Initiator::Feature : int { kStandard = 0 , kTenBit = (1 << 0) , kNoStart = (1 << 1) }
	Defined set of supported i2c features.

enum	Direction { kMockRead , kMockWrite }

enum class	RegisterAddressSize { k1Byte = 1 , k2Bytes = 2 , k4Bytes = 4 }

Functions
template<uint16_t kAddress>
static constexpr Address	pw::i2c::Address::TenBit ()

static Address	pw::i2c::Address::TenBit (uint16_t address)

template<uint8_t kAddress>
static constexpr Address	pw::i2c::Address::SevenBit ()

static Address	pw::i2c::Address::SevenBit (uint16_t address)

	pw::i2c::Address::Address (uint16_t address)

uint8_t	pw::i2c::Address::GetSevenBit () const

uint16_t	pw::i2c::Address::GetTenBit () const

uint16_t	pw::i2c::Address::GetAddress () const

constexpr bool	pw::i2c::Address::IsTenBit () const

bool	pw::i2c::operator== (const Address &a1, const Address &a2)

constexpr	pw::i2c::Device::Device (Initiator &initiator, Address device_address)

	pw::i2c::Device::Device (const Device &)=delete

	pw::i2c::Device::Device (Device &&)=default

Status	pw::i2c::Device::TransferFor (span< const Message > messages, chrono::SystemClock::duration timeout)
	Wraps `pw::i2c::Initiator::TransferFor`.

Status	pw::i2c::Device::WriteReadFor (ConstByteSpan tx_buffer, ByteSpan rx_buffer, chrono::SystemClock::duration timeout)
	Wraps `pw::i2c::Initiator::WriteReadFor`.

Status	pw::i2c::Device::WriteReadFor (const void tx_buffer, size_t tx_size_bytes, void rx_buffer, size_t rx_size_bytes, chrono::SystemClock::duration timeout)

Status	pw::i2c::Device::WriteFor (ConstByteSpan tx_buffer, chrono::SystemClock::duration timeout)
	Wraps `pw::i2c::Initiator::WriteFor`.

Status	pw::i2c::Device::WriteFor (const void *tx_buffer, size_t tx_size_bytes, chrono::SystemClock::duration timeout)

Status	pw::i2c::Device::ReadFor (ByteSpan rx_buffer, chrono::SystemClock::duration timeout)
	Wraps `pw::i2c::Initiator::ReadFor`.

Status	pw::i2c::Device::ReadFor (void *rx_buffer, size_t rx_size_bytes, chrono::SystemClock::duration timeout)

Status	pw::i2c::Device::ProbeFor (chrono::SystemClock::duration timeout)
	Wraps `pw::i2c::Initiator::ProbeDeviceFor`.

	pw::i2c::I2cService::I2cService (InitiatorSelector &&initiator_selector)
	Creates an I2cService instance.

void	pw::i2c::I2cService::I2cWrite (const pwpb::I2cWriteRequest::Message &request, pw::rpc::PwpbUnaryResponder< pwpb::I2cWriteResponse::Message > &responder)
	Writes a message to the specified I2C device register.

void	pw::i2c::I2cService::I2cRead (const pwpb::I2cReadRequest::Message &request, pw::rpc::PwpbUnaryResponder< pwpb::I2cReadResponse::Message > &responder)
	Reads a message from the specified I2C device register.

constexpr	pw::i2c::Initiator::Initiator ()

constexpr	pw::i2c::Initiator::Initiator (Feature supported_features)

Status	pw::i2c::Initiator::WriteReadFor (Address device_address, ConstByteSpan tx_buffer, ByteSpan rx_buffer, chrono::SystemClock::duration timeout)

Status	pw::i2c::Initiator::TransferFor (span< const Message > messages, chrono::SystemClock::duration timeout)

Status	pw::i2c::Initiator::WriteReadFor (Address device_address, const void tx_buffer, size_t tx_size_bytes, void rx_buffer, size_t rx_size_bytes, chrono::SystemClock::duration timeout)

Status	pw::i2c::Initiator::WriteFor (Address device_address, ConstByteSpan tx_buffer, chrono::SystemClock::duration timeout)

Status	pw::i2c::Initiator::WriteFor (Address device_address, const void *tx_buffer, size_t tx_size_bytes, chrono::SystemClock::duration timeout)

Status	pw::i2c::Initiator::ReadFor (Address device_address, ByteSpan rx_buffer, chrono::SystemClock::duration timeout)

Status	pw::i2c::Initiator::ReadFor (Address device_address, void *rx_buffer, size_t rx_size_bytes, chrono::SystemClock::duration timeout)

Status	pw::i2c::Initiator::ProbeDeviceFor (Address device_address, chrono::SystemClock::duration timeout)

constexpr Initiator::Feature	pw::i2c::operator\| (Initiator::Feature a, Initiator::Feature b)

	pw::i2c::GmockInitiator::MOCK_METHOD (Status, DoWriteReadFor,(Address device_address, ConstByteSpan tx_buffer, ByteSpan rx_buffer, chrono::SystemClock::duration timeout),(override))

	pw::i2c::GmockInitiator::MOCK_METHOD (Status, DoTransferFor,(span< const Message > messages, chrono::SystemClock::duration timeout),(override))

constexpr	pw::i2c::MockMessage::MockMessage (Status expected_return_value, Address address, Direction direction, ConstByteSpan data_buffer)

constexpr	pw::i2c::MockMessage::MockMessage (Status expected_return_value, Address device_address)
	Alternative constructor for creating probe transactions.

Status	pw::i2c::MockMessage::return_value () const
	Gets the expected return value for the transaction.

Address	pw::i2c::MockMessage::address () const
	Gets the I2C address that the I2C transaction is targeting.

Direction	pw::i2c::MockMessage::direction () const

ConstByteSpan	pw::i2c::MockMessage::data_buffer () const
	Gets the buffer that is virtually read.

constexpr MockMessage	pw::i2c::MockReadMessage (Status expected_return_value, Address address, ConstByteSpan data_buffer)

constexpr MockMessage	pw::i2c::MockWriteMessage (Status expected_return_value, Address address, ConstByteSpan data_buffer)

constexpr MockMessage	pw::i2c::MockProbeMessage (Status expected_return_value, Address address)

template<size_t kSize>
constexpr std::array< MockMessage, kSize >	pw::i2c::MakeExpectedMessageArray (const MockMessage(&messages)[kSize])

	pw::i2c::MockMessageTransaction::MockMessageTransaction (Status expected_return_value, span< const MockMessage > test_messages, std::optional< chrono::SystemClock::duration > timeout=std::nullopt)

std::optional< chrono::SystemClock::duration >	pw::i2c::MockMessageTransaction::timeout () const
	Gets the minimum duration to wait for a blocking I2C transaction.

const std::vector< MockMessage > &	pw::i2c::MockMessageTransaction::test_messages () const

Status	pw::i2c::MockMessageTransaction::return_value () const

	pw::i2c::MockMessageInitiator::MockMessageInitiator (span< MockMessageTransaction > transaction_list)

Status	pw::i2c::MockMessageInitiator::Finalize () const

	pw::i2c::MockMessageInitiator::~MockMessageInitiator () override

template<size_t kSize>
constexpr std::array< MockMessageTransaction, kSize >	pw::i2c::MakeExpectedTransactionArray (const MockMessageTransaction(&transactions)[kSize])

constexpr	pw::i2c::Transaction::Transaction (Status expected_return_value, Address device_address, ConstByteSpan write_buffer, ConstByteSpan read_buffer, std::optional< chrono::SystemClock::duration > timeout=std::nullopt)

constexpr	pw::i2c::Transaction::Transaction (Status expected_return_value, Address device_address, std::optional< chrono::SystemClock::duration > timeout=std::nullopt)
	Alternative constructor for creating probe transactions.

ConstByteSpan	pw::i2c::Transaction::read_buffer () const
	Gets the buffer that is virtually read.

ConstByteSpan	pw::i2c::Transaction::write_buffer () const
	Gets the buffer that the I2C device should write to.

std::optional< chrono::SystemClock::duration >	pw::i2c::Transaction::timeout () const
	Gets the minimum duration to wait for a blocking I2C transaction.

Address	pw::i2c::Transaction::address () const
	Gets the I2C address that the I2C transaction is targeting.

Status	pw::i2c::Transaction::return_value () const
	Gets the expected return value for the transaction.

constexpr Transaction	pw::i2c::ReadTransaction (Status expected_return_value, Address device_address, ConstByteSpan read_buffer, std::optional< chrono::SystemClock::duration > timeout=std::nullopt)

constexpr Transaction	pw::i2c::WriteTransaction (Status expected_return_value, Address device_address, ConstByteSpan write_buffer, std::optional< chrono::SystemClock::duration > timeout=std::nullopt)

constexpr Transaction	pw::i2c::ProbeTransaction (Status expected_return_value, Address device_address, std::optional< chrono::SystemClock::duration > timeout=std::nullopt)

constexpr	pw::i2c::MockInitiator::MockInitiator (span< Transaction > transaction_list)

Status	pw::i2c::MockInitiator::Finalize () const

	pw::i2c::MockInitiator::~MockInitiator () override

template<size_t kSize>
constexpr std::array< Transaction, kSize >	pw::i2c::MakeExpectedTransactionArray (const Transaction(&transactions)[kSize])

static constexpr Message	pw::i2c::Message::WriteMessage (Address address, ConstByteSpan data)

static constexpr Message	pw::i2c::Message::WriteMessageContinuation (ConstByteSpan data)

static constexpr Message	pw::i2c::Message::ReadMessage (Address address, ByteSpan data)

bool	pw::i2c::Message::IsRead () const

bool	pw::i2c::Message::IsTenBit () const

bool	pw::i2c::Message::IsWriteContinuation () const

Address	pw::i2c::Message::GetAddress () const

ByteSpan	pw::i2c::Message::GetMutableData () const

ConstByteSpan	pw::i2c::Message::GetData () const

constexpr	pw::i2c::RegisterDevice::RegisterDevice (Initiator &initiator, Address address, endian register_address_order, endian data_order, RegisterAddressSize register_address_size)

constexpr	pw::i2c::RegisterDevice::RegisterDevice (Initiator &initiator, Address address, endian order, RegisterAddressSize register_address_size)

Status	pw::i2c::RegisterDevice::WriteRegisters (uint32_t register_address, ConstByteSpan register_data, ByteSpan buffer, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::WriteRegisters8 (uint32_t register_address, span< const uint8_t > register_data, ByteSpan buffer, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::WriteRegisters16 (uint32_t register_address, span< const uint16_t > register_data, ByteSpan buffer, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::WriteRegisters32 (uint32_t register_address, span< const uint32_t > register_data, ByteSpan buffer, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::ReadRegisters (uint32_t register_address, ByteSpan return_data, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::ReadRegisters8 (uint32_t register_address, span< uint8_t > return_data, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::ReadRegisters16 (uint32_t register_address, span< uint16_t > return_data, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::ReadRegisters32 (uint32_t register_address, span< uint32_t > return_data, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::WriteRegister (uint32_t register_address, std::byte register_data, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::WriteRegister8 (uint32_t register_address, uint8_t register_data, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::WriteRegister16 (uint32_t register_address, uint16_t register_data, chrono::SystemClock::duration timeout)

Status	pw::i2c::RegisterDevice::WriteRegister32 (uint32_t register_address, uint32_t register_data, chrono::SystemClock::duration timeout)

Result< std::byte >	pw::i2c::RegisterDevice::ReadRegister (uint32_t register_address, chrono::SystemClock::duration timeout)

Result< uint8_t >	pw::i2c::RegisterDevice::ReadRegister8 (uint32_t register_address, chrono::SystemClock::duration timeout)

Result< uint16_t >	pw::i2c::RegisterDevice::ReadRegister16 (uint32_t register_address, chrono::SystemClock::duration timeout)

Result< uint32_t >	pw::i2c::RegisterDevice::ReadRegister32 (uint32_t register_address, chrono::SystemClock::duration timeout)

Variables
static constexpr uint8_t	pw::i2c::Address::kMaxSevenBitAddress = (1 << 7) - 1

static constexpr uint16_t	pw::i2c::Address::kMaxTenBitAddress = (1 << 10) - 1

Friends
bool	pw::i2c::Address::operator== (const Address &a1, const Address &a2)

Typedef Documentation

◆ InitiatorSelector

using pw::i2c::I2cService::InitiatorSelector = pw::Function<Initiator*(size_t pos)>

A callback that returns a pw::i2c::Initiator instance for the given bus index position or nullptr if the position is not valid for this I2C device.

Function Documentation

◆ Address()

pw::i2c::Address::Address ( uint16_t address )

explicit

Creates a pw::i2c::Address instance from a 7 or 10 bit address.

Note: This function is deprecated. You should almost certainly use either Address::SevenBit<0x1>() for addresses known at compile time, or Address::SevenBit(0x1) for addresses known at run-time.

If the address argument is 7-bits or less, a 7-bit address is constructed equivalent to Address::SevenBit(address);

If the address argument is 8, 9 or 10 bits, a ten-bit address is constructed equivalent to Address::TenBit(address);

The type of address construced will affect how the i2c address is transmitted on the bus. You should always use 7-bit addresses unless you are certain you have a host and device that support 10-bit addresses.

Parameters

[in] address An address no larger than 10-bits as an unsigned integer. This method does a runtime assertion to ensure that address is 10 bits or less.

constexpr pw::i2c::Address kAddress(0x200);

pw::i2c::Address

Definition: address.h:42

Returns: A pw::i2c::Address instance.

◆ Device()

constexpr pw::i2c::Device::Device	(	Initiator &	initiator,
		Address	device_address
	)

inlineconstexpr

Creates a pw::i2c::Device instance.

The address for the I2C device is set in this constructor and can't be modified later.

Parameters

[in]	initiator	A reference to a `pw::i2c::Initiator` instance.
[in]	device_address	The address of the I2C device.

Returns: A pw::i2c::Device instance.

◆ DoTransferFor() [1/2]

virtual Status pw::i2c::Initiator::DoTransferFor	(	span< const Message >	messages,
		chrono::SystemClock::duration	timeout
	)

privatevirtual

Reimplemented in pw::i2c::LinuxInitiator.

◆ DoTransferFor() [2/2]

Status pw::i2c::MockMessageInitiator::DoTransferFor	(	span< const Message >	messages,
		chrono::SystemClock::duration	timeout
	)

overrideprivatevirtual

Reimplemented from pw::i2c::Initiator.

◆ DoWriteReadFor()

Status pw::i2c::MockInitiator::DoWriteReadFor	(	Address	device_address,
		ConstByteSpan	tx_buffer,
		ByteSpan	rx_buffer,
		chrono::SystemClock::duration	timeout
	)

overrideprivatevirtual

Reimplemented from pw::i2c::Initiator.

◆ Finalize() [1/2]

Status pw::i2c::MockMessageInitiator::Finalize ( ) const

inline

Indicates whether the actual I2C transactions matched the expected transactions. Should be called at the end of the test.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The actual transactions matched the expected transactions.
* 
*     OUT_OF_RANGE: The mocked set of transactions hasn't been exhausted.
* 
*

◆ Finalize() [2/2]

Status pw::i2c::MockInitiator::Finalize ( ) const

inline

Indicates whether the actual I2C transactions matched the expected transactions. Should be called at the end of the test.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The actual transactions matched the expected transactions.
* 
*     OUT_OF_RANGE: The mocked set of transactions hasn't been exhausted.
* 
*

◆ GetAddress() [1/2]

uint16_t pw::i2c::Address::GetAddress ( ) const

inline

Gets the raw address that was provided when this Address was created.

Use IsTenBit() to know whether the address should be interpreted as a 7-bit or 10-bit address.

Returns: A an address as an unsigned integer.

◆ GetAddress() [2/2]

Address pw::i2c::Message::GetAddress ( ) const

inline

Getter for the address component.

Returns: the Address passed into one of the constructors or factories.

◆ GetData()

ConstByteSpan pw::i2c::Message::GetData ( ) const

inline

Getter for the data component.

Returns: the data passed into one of the constructors or factories.

◆ GetMutableData()

ByteSpan pw::i2c::Message::GetMutableData ( ) const

inline

Getter for the data component.

This method is only valid for Read messages and will runtime ASSERT on other messages.

Returns: the mutable variant of the data passed into one of the constructors or factories.

◆ GetSevenBit()

uint8_t pw::i2c::Address::GetSevenBit ( ) const

Gets the 7-bit address that was provided when this instance was created.

This method does a runtime assertion to ensure that the address was constructed in 7-bit mode.

Returns: A 7-bit address as an unsigned integer.

◆ GetTenBit()

uint16_t pw::i2c::Address::GetTenBit ( ) const

inline

Gets the 10-bit address that was provided when this instance was created.

Returns: A 10-bit address as an unsigned integer.

◆ Initiator() [1/2]

constexpr pw::i2c::Initiator::Initiator ( )

inlineconstexpr

Construct Initiator with default features.

Note: this constructor enables kTenBit because the older implementation enabled it by default. Most users will not need kTenBit enabled.

◆ Initiator() [2/2]

constexpr pw::i2c::Initiator::Initiator ( Feature supported_features )

inlineexplicitconstexpr

Construct Initiator with defined set of features.

Supported features are defined in the Feature enum.

Note: to support only the required features, you should specify Initiator(Initiator::Feature::kStandard).

Initiator i2c(Initiator::Feature::kStandard);

pw::i2c::Initiator

The common, base driver interface for initiating thread-safe transactions with devices on an I2C bus....

Definition: initiator.h:52

Initiator i2c(Initiator::Feature::kTenBit |

Initiator::Feature::kNoStart);

◆ IsRead()

bool pw::i2c::Message::IsRead ( ) const

inline

Getter for whether this object represents a read operation.

Returns: true if the message represents a read operation.

◆ IsTenBit() [1/2]

constexpr bool pw::i2c::Address::IsTenBit ( ) const

inlineconstexpr

Getter for whether this object represents a Ten bit address. Note: The address itself may still be fewer than 10 bits.

Returns: true if the address represents a 10-bit address.

◆ IsTenBit() [2/2]

bool pw::i2c::Message::IsTenBit ( ) const

inline

Getter for whether this object represents an operation addressed with a ten-bit address. When true, communicate on the wire using the i2c 10-bit addressing protocol.

Returns: true if the message represents a 10-bit addressed operation.

◆ IsWriteContinuation()

bool pw::i2c::Message::IsWriteContinuation ( ) const

inline

Getter for whether this object represents a continued write.

Returns: true if the message represents a continued write.

◆ operator==()

bool pw::i2c::operator==	(	const Address &	a1,
		const Address &	a2
	)

inline

Operator for testing equality of two Address objects.

Returns: true if the two Address objects are the same.

◆ ProbeDeviceFor()

Status pw::i2c::Initiator::ProbeDeviceFor	(	Address	device_address,
		chrono::SystemClock::duration	timeout
	)

inline

Probes the device for an I2C ACK after only writing the address. This is done by attempting to read a single byte from the specified device.

Warning: This method is not compatible with all devices. For example, some I2C devices require a device_address in W mode before they can ack the device_address in R mode. In this case, use WriteReadFor or TransferFor to read a register with known value.

Parameters

[in]	device_address	The address of the I2C device.
[in]	timeout	The maximum duration to block waiting for both exclusive bus access and the completion of the I2C transaction.

Precondition: The provided address must be supported by the initiator. I.e. don't use a 10-bit address if the initiator only supports 7-bit addresses. This method fails a runtime assertion if this precondition isn't met.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The transaction succeeded.
* 
*     DEADLINE_EXCEEDED: Was unable to acquire exclusive initiator access
*     and complete the I2C transaction in time.
* 
*     UNAVAILABLE: A NACK condition occurred, meaning the addressed device
*     didn't respond or was unable to process the request.
* 
*     FAILED_PRECONDITION: The interface isn't initialized or enabled.
* 
*     UNIMPLEMENTED: The interface doesn't support the necessary i2c
*     features or combination of i2c messages.
* 
*

◆ ProbeTransaction()

constexpr Transaction pw::i2c::ProbeTransaction	(	Status	expected_return_value,
		Address	device_address,
		std::optional< chrono::SystemClock::duration >	timeout = `std::nullopt`
	)

constexpr

A helper that constructs a one-byte read I2C transaction. Used for testing probe transactions with pw::i2c::MockInitiator.

◆ ReadFor() [1/3]

Status pw::i2c::Initiator::ReadFor	(	Address	device_address,
		ByteSpan	rx_buffer,
		chrono::SystemClock::duration	timeout
	)

inline

Reads bytes from an I2C device.

The signal on the bus should look like this:

START + I2C_ADDRESS + READ(1) + RX_BUFFER_BYTES + STOP

Parameters

[in]	device_address	The address of the I2C device.
[out]	rx_buffer	The receive buffer.
[in]	timeout	The maximum duration to block waiting for both exclusive bus access and the completion of the I2C transaction.

Precondition: The provided address must be supported by the initiator. I.e. don't use a 10-bit address if the initiator only supports 7-bit addresses. This method fails a runtime assertion if this precondition isn't met.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The transaction succeeded.
* 
*     DEADLINE_EXCEEDED: Was unable to acquire exclusive initiator access
*     and complete the I2C transaction in time.
* 
*     UNAVAILABLE: A NACK condition occurred, meaning the addressed device
*     didn't respond or was unable to process the request.
* 
*     FAILED_PRECONDITION: The interface isn't initialized or enabled.
* 
*     UNIMPLEMENTED: The interface doesn't support the necessary i2c
*     features or combination of i2c messages.
* 
*

◆ ReadFor() [2/3]

Status pw::i2c::Initiator::ReadFor	(	Address	device_address,
		void *	rx_buffer,
		size_t	rx_size_bytes,
		chrono::SystemClock::duration	timeout
	)

inline

A variation of pw::i2c::Initiator::ReadFor that accepts an explicit size for the amount of bytes to read from the device.

◆ ReadFor() [3/3]

Status pw::i2c::Device::ReadFor	(	void *	rx_buffer,
		size_t	rx_size_bytes,
		chrono::SystemClock::duration	timeout
	)

inline

Wraps the variation of pw::i2c::Initiator::ReadFor that accepts an explicit size for the amount of bytes to read from the device.

◆ ReadMessage()

static constexpr Message pw::i2c::Message::ReadMessage	(	Address	address,
		ByteSpan	data
	)

inlinestaticconstexpr

Creates a pw::i2c::Message instance for an i2c read message.

This Message can be passed to Initiator::TransferFor().

constexpr Message kMessage = Message::ReadMessage(
    pw::i2c::Address::SevenBit<0x42>(),
    data
);

Returns: A pw::i2c::Message instance.

◆ ReadRegister()

Result< std::byte > pw::i2c::RegisterDevice::ReadRegister	(	uint32_t	register_address,
		chrono::SystemClock::duration	timeout
	)

inline

Sends a register address to read from and then reads from that address.

register_address and the return data use the endianness that was provided when this pw::i2c::RegisterDevice instance was constructed.

Precondition: This method assumes that you've verified that the return data size is a correct size for your device.

Parameters

[in]	register_address	The register address to read.
[in]	timeout	The maximum duration to block waiting for both exclusive bus access and the completion of the I2C transaction.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Returns the register data.
* 
*     DEADLINE_EXCEEDED: Unable to acquire exclusive bus access and
*     complete the transaction in time.
* 
*     FAILED_PRECONDITION: The interface is not initialized or enabled.
* 
*     INTERNAL: An issue occurred while building the return data.
* 
*     INVALID_ARGUMENT: ``register_address`` is larger than the 10-bit
*     address space.
* 
*     UNAVAILABLE: The device took too long to respond to the NACK.
* 
*

◆ ReadRegister16()

Result< uint16_t > pw::i2c::RegisterDevice::ReadRegister16	(	uint32_t	register_address,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::ReadRegister() that returns exactly 16 bits.

◆ ReadRegister32()

Result< uint32_t > pw::i2c::RegisterDevice::ReadRegister32	(	uint32_t	register_address,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::ReadRegister() that returns exactly 32 bits.

◆ ReadRegister8()

Result< uint8_t > pw::i2c::RegisterDevice::ReadRegister8	(	uint32_t	register_address,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::ReadRegister() that returns exactly 8 bits.

◆ ReadRegisters()

Status pw::i2c::RegisterDevice::ReadRegisters	(	uint32_t	register_address,
		ByteSpan	return_data,
		chrono::SystemClock::duration	timeout
	)

Reads data from multiple contiguous registers starting from a specific offset or register. This method is byte-addressable.

register_address and return_data use the endianness that was provided when this pw::i2c::RegisterDevice instance was constructed.

Precondition: This method assumes that you've verified that your device supports bulk reads and that return_data is a correct size for your device.

Parameters

[in]	register_address	The register address to begin reading at.
[out]	return_data	The area to read the data into. The amount of data that will be read is equal to the size of this span. Endianness is taken into account if this span is 2 or 4 bytes.
[in]	timeout	The maximum duration to block waiting for both exclusive bus access and the completion of the I2C transaction.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The bulk read was successful.
* 
*     DEADLINE_EXCEEDED: Unable to acquire exclusive bus access and
*     complete the transaction in time.
* 
*     FAILED_PRECONDITION: The interface is not initialized or enabled.
* 
*     INTERNAL: An issue occurred while building ``return_data``.
* 
*     INVALID_ARGUMENT: ``register_address`` is larger than the 10-bit
*     address space.
* 
*     UNAVAILABLE: The device took too long to respond to the NACK.
* 
*

◆ ReadRegisters16()

Status pw::i2c::RegisterDevice::ReadRegisters16	(	uint32_t	register_address,
		span< uint16_t >	return_data,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::ReadRegisters() that requires return_data to be exactly 16 bits.

◆ ReadRegisters32()

Status pw::i2c::RegisterDevice::ReadRegisters32	(	uint32_t	register_address,
		span< uint32_t >	return_data,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::ReadRegisters() that requires return_data to be exactly 32 bits.

◆ ReadRegisters8()

Status pw::i2c::RegisterDevice::ReadRegisters8	(	uint32_t	register_address,
		span< uint8_t >	return_data,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::ReadRegisters() that requires return_data to be exactly 8 bits.

◆ ReadTransaction()

constexpr Transaction pw::i2c::ReadTransaction	(	Status	expected_return_value,
		Address	device_address,
		ConstByteSpan	read_buffer,
		std::optional< chrono::SystemClock::duration >	timeout = `std::nullopt`
	)

constexpr

A helper that constructs a read-only I2C transaction. Used for testing read transactions with pw::i2c::MockInitiator.

◆ RegisterDevice() [1/2]

constexpr pw::i2c::RegisterDevice::RegisterDevice	(	Initiator &	initiator,
		Address	address,
		endian	order,
		RegisterAddressSize	register_address_size
	)

inlineconstexpr

This constructor specifies the endianness of the register address and data with a single argument. If your register address and data have different endianness, use the other pw::i2c::RegisterDevice constructor.

Parameters

[in]	initiator	A `pw::i2c::Initiator` instance for the bus that the device is on.
[in]	address	The address of the I2C device.
[in]	order	The endianness of both the register address and register data.
[in]	register_address_size	The size of the register address.

◆ RegisterDevice() [2/2]

constexpr pw::i2c::RegisterDevice::RegisterDevice	(	Initiator &	initiator,
		Address	address,
		endian	register_address_order,
		endian	data_order,
		RegisterAddressSize	register_address_size
	)

inlineconstexpr

This constructor specifies the endianness of the register address and data separately. If your register address and data have the same endianness and you'd like to specify them both with a single argument, see the other pw::i2c::RegisterDevice constructor.

Parameters

[in]	initiator	A `pw::i2c::Initiator` instance for the bus that the device is on.
[in]	address	The address of the I2C device.
[in]	register_address_order	The endianness of the register address.
[in]	data_order	The endianness of the data.
[in]	register_address_size	The size of the register address.

◆ SevenBit() [1/2]

template<uint8_t kAddress>

static constexpr Address pw::i2c::Address::SevenBit ( )

inlinestaticconstexpr

Creates a pw::i2c::Address instance for an address that's 7 bits or less.

This constant expression does a compile-time assertion to ensure that the provided address is 7 bits or less.

constexpr pw::i2c::Address kAddress =

pw::i2c::Address::SevenBit<0x42>();

Returns: A pw::i2c::Address instance.

◆ SevenBit() [2/2]

static Address pw::i2c::Address::SevenBit ( uint16_t address )

inlinestatic

Creates a pw::i2c::Address instance for an address that's 7 bits or less.

This constructor does a run-time check to ensure that the provided address is 7 bits or less.

pw::i2c::Address kAddress = pw::i2c::Address::SevenBit(0x42);

pw::i2c::Address::SevenBit

static constexpr Address SevenBit()

Definition: address.h:92

Returns: A pw::i2c::Address instance.

◆ TenBit() [1/2]

template<uint16_t kAddress>

static constexpr Address pw::i2c::Address::TenBit ( )

inlinestaticconstexpr

Creates a pw::i2c::Address instance for an address that's 10 bits or less.

This constant expression does a compile-time assertion to ensure that the provided address is 10 bits or less.

constexpr pw::i2c::Address kAddress = pw::i2c::Address::TenBit<0x200>();

Returns: A pw::i2c::Address instance.

◆ TenBit() [2/2]

static Address pw::i2c::Address::TenBit ( uint16_t address )

inlinestatic

Creates a pw::i2c::Address instance for an address that's 10 bits or less.

This constructor does a run-time check to ensure that the provided address is 10 bits or less.

pw::i2c::Address kAddress = pw::i2c::Address::TenBit(0x200);

pw::i2c::Address::TenBit

static constexpr Address TenBit()

Definition: address.h:59

Returns: A pw::i2c::Address instance.

◆ Transaction()

constexpr pw::i2c::Transaction::Transaction	(	Status	expected_return_value,
		Address	device_address,
		ConstByteSpan	write_buffer,
		ConstByteSpan	read_buffer,
		std::optional< chrono::SystemClock::duration >	timeout = `std::nullopt`
	)

inlineconstexpr

Constructor for creating write-only, read-only, or write-then-read transactions.

◆ TransferFor()

Status pw::i2c::Initiator::TransferFor	(	span< const Message >	messages,
		chrono::SystemClock::duration	timeout
	)

inline

Performs multiple arbitrary reads and writes to an I2C device as one atomic transaction. Each part of the transaction is referred to as a "message".

For a series of 0...N messages, the signal on the bus for the atomic transaction of two messages should look like this:

START + #0.I2C_ADDRESS + #0.WRITE/READ(0/1) + #0.BYTES +
START + #1.I2C_ADDRESS + #1.WRITE/READ(0/1) + #1.BYTES +
...
START + #N.I2C_ADDRESS + #N.WRITE/READ(0/1) + #N.BYTES + STOP

Parameters

[in] messages An array of pw::i2c::Message objects to transmit as one i2c bus transaction.

For each Message msg in messages:

If msg.GetAddress().IsTenBit() is true:

The implementation should transmit that message using the 10-bit addressing scheme defined in the i2c spec.
The implementation should CHECK or return an error if 10-bit addressing is unsupported.

If msg.GetAddress().IsWriteContinuation() is true:

The implementation should transmit this message without a start condition or address.
The implementation should CHECK or return an error if the hardware or initiator does not support this feature.

Parameters

[in] timeout The maximum duration to block waiting for both exclusive bus access and the completion of the bus transaction.

Precondition: The provided addresses of each message must be supported by the initiator, Don't use a 10-bit address if the initiator only supports 7-bit addresses. This method fails a runtime assertion if this precondition isn't met.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The transaction succeeded.
* 
*     INVALID_ARGUMENT: The arguments can never be valid. For example,
*     a WriteContinuation without a preceding Write message.
* 
*     DEADLINE_EXCEEDED: Was unable to acquire exclusive initiator access
*     and complete the I2C transaction in time.
* 
*     UNAVAILABLE: A NACK condition occurred, meaning the addressed device
*     didn't respond or was unable to process the request.
* 
*     FAILED_PRECONDITION: The interface isn't initialized or enabled.
* 
*     UNIMPLEMENTED: The interface doesn't support the necessary i2c
*     features or combination of i2c messages.
* 
*

◆ WriteFor() [1/3]

Status pw::i2c::Initiator::WriteFor	(	Address	device_address,
		const void *	tx_buffer,
		size_t	tx_size_bytes,
		chrono::SystemClock::duration	timeout
	)

inline

A variation of pw::i2c::Initiator::WriteFor that accepts an explicit size for the amount of bytes to write to the device.

◆ WriteFor() [2/3]

Status pw::i2c::Initiator::WriteFor	(	Address	device_address,
		ConstByteSpan	tx_buffer,
		chrono::SystemClock::duration	timeout
	)

inline

Write bytes to the I2C device.

The signal on the bus should look like this:

START + I2C_ADDRESS + WRITE(0) + TX_BUFFER_BYTES + STOP

Parameters

[in]	device_address	The address of the I2C device.
[in]	tx_buffer	The transmit buffer.
[in]	timeout	The maximum duration to block waiting for both exclusive bus access and the completion of the I2C transaction.

Precondition: The provided address must be supported by the initiator. I.e. don't use a 10-bit address if the initiator only supports 7-bit addresses. This method fails a runtime assertion if this precondition isn't met.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The transaction succeeded.
* 
*     DEADLINE_EXCEEDED: Was unable to acquire exclusive initiator access
*     and complete the I2C transaction in time.
* 
*     UNAVAILABLE: A NACK condition occurred, meaning the addressed device
*     didn't respond or was unable to process the request.
* 
*     FAILED_PRECONDITION: The interface isn't initialized or enabled.
* 
*     UNIMPLEMENTED: The interface doesn't support the necessary i2c
*     features or combination of i2c messages.
* 
*

◆ WriteFor() [3/3]

Status pw::i2c::Device::WriteFor	(	const void *	tx_buffer,
		size_t	tx_size_bytes,
		chrono::SystemClock::duration	timeout
	)

inline

Wraps the variation of pw::i2c::Initiator::WriteFor that accepts an explicit size for the amount of bytes to write to the device.

◆ WriteMessage()

static constexpr Message pw::i2c::Message::WriteMessage	(	Address	address,
		ConstByteSpan	data
	)

inlinestaticconstexpr

Creates a pw::i2c::Message instance for an i2c write message.

This Message can be passed to Initiator::TransferFor().

constexpr Message kMessage = Message::WriteMessage(
    pw::i2c::Address::SevenBit<0x42>(),
    data
);

Returns: A pw::i2c::Message instance.

◆ WriteMessageContinuation()

static constexpr Message pw::i2c::Message::WriteMessageContinuation ( ConstByteSpan data )

inlinestaticconstexpr

Creates a pw::i2c::Message instance for an i2c write message without a start condition sent on the bus. Chaining one or more of these messages after a regular Write message allows the client to send non-contiguous blocks of memory as one single write message to the i2c target.

Note: This message must follow another write message.

Note: No addresses is needed and no address will be transmitted. The data should immediately follow the data from the previous write message.

This Message can be passed to Initiator::TransferFor().

constexpr Message kMessage = Message::WriteMessageContinuation(data);

pw::i2c::Message::WriteMessageContinuation

static constexpr Message WriteMessageContinuation(ConstByteSpan data)

Definition: message.h:89

Returns: A pw::i2c::Message instance.

◆ WriteReadFor() [1/3]

Status pw::i2c::Initiator::WriteReadFor	(	Address	device_address,
		const void *	tx_buffer,
		size_t	tx_size_bytes,
		void *	rx_buffer,
		size_t	rx_size_bytes,
		chrono::SystemClock::duration	timeout
	)

inline

A variation of pw::i2c::Initiator::WriteReadFor that accepts explicit sizes for the amount of bytes to write to the device and read from the device.

◆ WriteReadFor() [2/3]

Status pw::i2c::Initiator::WriteReadFor	(	Address	device_address,
		ConstByteSpan	tx_buffer,
		ByteSpan	rx_buffer,
		chrono::SystemClock::duration	timeout
	)

inline

Writes bytes to an I2C device and then reads bytes from that same device as one atomic I2C transaction.

The signal on the bus for the atomic transaction should look like this:

START + I2C_ADDRESS + WRITE(0) + TX_BUFFER_BYTES +

START + I2C_ADDRESS + READ(1) + RX_BUFFER_BYTES + STOP

Parameters

[in]	device_address	The address of the I2C device.
[in]	tx_buffer	The transmit buffer.
[out]	rx_buffer	The receive buffer.
[in]	timeout	The maximum duration to block waiting for both exclusive bus access and the completion of the I2C transaction.

Precondition: The provided address must be supported by the initiator. I.e. don't use a 10-bit address if the initiator only supports 7-bit addresses. This method fails a runtime assertion if this precondition isn't met.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The transaction or transactions succeeded.
* 
*     DEADLINE_EXCEEDED: Was unable to acquire exclusive initiator access
*     and complete the I2C transaction in time.
* 
*     UNAVAILABLE: A NACK condition occurred, meaning the addressed device
*     didn't respond or was unable to process the request.
* 
*     FAILED_PRECONDITION: The interface isn't initialized or enabled.
* 
*     UNIMPLEMENTED: The interface doesn't support the necessary i2c
*     features or combination of i2c messages.
* 
*

◆ WriteReadFor() [3/3]

Status pw::i2c::Device::WriteReadFor	(	const void *	tx_buffer,
		size_t	tx_size_bytes,
		void *	rx_buffer,
		size_t	rx_size_bytes,
		chrono::SystemClock::duration	timeout
	)

inline

Wraps the variation of pw::i2c::Initiator::WriteReadFor that accepts explicit sizes for the amount of bytes to write to the device and read from the device.

◆ WriteRegister()

Status pw::i2c::RegisterDevice::WriteRegister	(	uint32_t	register_address,
		std::byte	register_data,
		chrono::SystemClock::duration	timeout
	)

inline

Sends a register address to write to and then writes to that address.

register_address and register_data use the endianness that was provided when this pw::i2c::RegisterDevice instance was constructed.

Precondition: This method assumes that you've verified that register_data is a correct size for your device.

Parameters

[in]	register_address	The register address to write to.
[in]	register_data	The data that should be written at the address. The maximum allowed size is 4 bytes.
[in]	timeout	The maximum duration to block waiting for both exclusive bus access and the completion of the I2C transaction.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The write was successful.
* 
*     DEADLINE_EXCEEDED: Unable to acquire exclusive bus access
*     and complete the transaction in time.
* 
*     FAILED_PRECONDITION: The interface is not initialized or enabled.
* 
*     INTERNAL: An issue occurred while writing the data.
* 
*     INVALID_ARGUMENT: ``register_address`` is larger than the 10-bit
*     address space.
* 
*     UNAVAILABLE: The device took too long to respond to the NACK.
* 
*

◆ WriteRegister16()

Status pw::i2c::RegisterDevice::WriteRegister16	(	uint32_t	register_address,
		uint16_t	register_data,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::WriteRegister() that writes exactly 16 bits.

◆ WriteRegister32()

Status pw::i2c::RegisterDevice::WriteRegister32	(	uint32_t	register_address,
		uint32_t	register_data,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::WriteRegister() that writes exactly 32 bits.

◆ WriteRegister8()

Status pw::i2c::RegisterDevice::WriteRegister8	(	uint32_t	register_address,
		uint8_t	register_data,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::WriteRegister() that writes exactly 8 bits.

◆ WriteRegisters()

Status pw::i2c::RegisterDevice::WriteRegisters	(	uint32_t	register_address,
		ConstByteSpan	register_data,
		ByteSpan	buffer,
		chrono::SystemClock::duration	timeout
	)

inline

Writes data to multiple contiguous registers starting at a specific register. This method is byte-addressable.

register_address and register_data use the endianness that was provided when this pw::i2c::RegisterDevice instance was constructed.

Precondition: This method assumes that you've verified that your device supports bulk writes and that register_data is a correct size for your device.

Parameters

[in]	register_address	The register address to begin writing at.
[in]	register_data	The data to write. Endianness is taken into account if the data is 2 or 4 bytes.
[in]	buffer	A buffer for constructing the write data. The size of this buffer must be at least as large as the size of `register_address` plus the size of `register_data`.
[in]	timeout	The maximum duration to block waiting for both exclusive bus access and the completion of the I2C transaction.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The bulk write was successful.
* 
*     DEADLINE_EXCEEDED: Unable to acquire exclusive bus access and
*     complete the transaction in time.
* 
*     FAILED_PRECONDITION: The interface is not initialized or enabled.
* 
*     INTERNAL: An issue occurred while building ``register_data``.
* 
*     INVALID_ARGUMENT: ``register_address`` is larger than the 10-bit
*     address space.
* 
*     OUT_OF_RANGE: The size of ``buffer`` is less than the size
*     of ``register_address`` plus the size of ``register_data``.
* 
*     UNAVAILABLE: The device took too long to respond to the NACK.
* 
*

◆ WriteRegisters16()

Status pw::i2c::RegisterDevice::WriteRegisters16	(	uint32_t	register_address,
		span< const uint16_t >	register_data,
		ByteSpan	buffer,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::WriteRegisters() that requires register_data to be exactly 16 bits.

◆ WriteRegisters32()

Status pw::i2c::RegisterDevice::WriteRegisters32	(	uint32_t	register_address,
		span< const uint32_t >	register_data,
		ByteSpan	buffer,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::WriteRegisters() that requires register_data to be exactly 32 bits.

◆ WriteRegisters8()

Status pw::i2c::RegisterDevice::WriteRegisters8	(	uint32_t	register_address,
		span< const uint8_t >	register_data,
		ByteSpan	buffer,
		chrono::SystemClock::duration	timeout
	)

inline

Variant of pw::i2c::RegisterDevice::WriteRegisters() that requires register_data to be exactly 8 bits.

◆ WriteTransaction()

constexpr Transaction pw::i2c::WriteTransaction	(	Status	expected_return_value,
		Address	device_address,
		ConstByteSpan	write_buffer,
		std::optional< chrono::SystemClock::duration >	timeout = `std::nullopt`
	)

constexpr

A helper that constructs a write-only I2C transaction. Used for testing write transactions with pw::i2c::MockInitiator.

◆ ~MockInitiator()

pw::i2c::MockInitiator::~MockInitiator ( )

override

Runs pw::i2c::MockInitiator::Finalize() regardless of whether it was already optionally finalized.

◆ ~MockMessageInitiator()

pw::i2c::MockMessageInitiator::~MockMessageInitiator ( )

override

Runs pw::i2c::MessageMockInitiator::Finalize() regardless of whether it was already optionally finalized.

Friends

◆ operator==

bool operator==	(	const Address &	a1,
		const Address &	a2
	)

friend

Operator for testing equality of two Address objects.

Returns: true if the two Address objects are the same.

Oveview

Classes

Typedefs

Enumerations

Functions

Variables

Friends

Typedef Documentation

◆ InitiatorSelector

Function Documentation

◆ Address()

◆ Device()

◆ DoTransferFor() [1/2]

◆ DoTransferFor() [2/2]

◆ DoWriteReadFor()

◆ Finalize() [1/2]

◆ Finalize() [2/2]

◆ GetAddress() [1/2]

◆ GetAddress() [2/2]

◆ GetData()

◆ GetMutableData()

◆ GetSevenBit()

◆ GetTenBit()

◆ Initiator() [1/2]

◆ Initiator() [2/2]

◆ IsRead()

◆ IsTenBit() [1/2]

◆ IsTenBit() [2/2]

◆ IsWriteContinuation()

◆ operator==()

◆ ProbeDeviceFor()

◆ ProbeTransaction()

◆ ReadFor() [1/3]

◆ ReadFor() [2/3]

◆ ReadFor() [3/3]

◆ ReadMessage()

◆ ReadRegister()

◆ ReadRegister16()

◆ ReadRegister32()

◆ ReadRegister8()

◆ ReadRegisters()

◆ ReadRegisters16()

◆ ReadRegisters32()

◆ ReadRegisters8()

◆ ReadTransaction()

◆ RegisterDevice() [1/2]

◆ RegisterDevice() [2/2]

◆ SevenBit() [1/2]

◆ SevenBit() [2/2]

◆ TenBit() [1/2]

◆ TenBit() [2/2]

◆ Transaction()

◆ TransferFor()

◆ WriteFor() [1/3]

◆ WriteFor() [2/3]

◆ WriteFor() [3/3]

◆ WriteMessage()

◆ WriteMessageContinuation()

◆ WriteReadFor() [1/3]

◆ WriteReadFor() [2/3]

◆ WriteReadFor() [3/3]

◆ WriteRegister()

◆ WriteRegister16()

◆ WriteRegister32()

◆ WriteRegister8()

◆ WriteRegisters()

◆ WriteRegisters16()

◆ WriteRegisters32()

◆ WriteRegisters8()

◆ WriteTransaction()

◆ ~MockInitiator()

◆ ~MockMessageInitiator()

Friends

◆ operator==