Pigweed
C/C++ API Reference
|
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...
Public Types | |
enum class | Feature : int { kStandard = 0 , kTenBit = (1 << 0) , kNoStart = (1 << 1) } |
Defined set of supported i2c features. | |
Public Member Functions | |
constexpr | Initiator () |
constexpr | Initiator (Feature supported_features) |
Status | WriteReadFor (Address device_address, ConstByteSpan tx_buffer, ByteSpan rx_buffer, chrono::SystemClock::duration timeout) |
Status | TransferFor (span< const Message > messages, chrono::SystemClock::duration timeout) |
Status | 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 | WriteFor (Address device_address, ConstByteSpan tx_buffer, chrono::SystemClock::duration timeout) |
Status | WriteFor (Address device_address, const void *tx_buffer, size_t tx_size_bytes, chrono::SystemClock::duration timeout) |
Status | ReadFor (Address device_address, ByteSpan rx_buffer, chrono::SystemClock::duration timeout) |
Status | ReadFor (Address device_address, void *rx_buffer, size_t rx_size_bytes, chrono::SystemClock::duration timeout) |
Status | ProbeDeviceFor (Address device_address, chrono::SystemClock::duration timeout) |
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".
pw::i2c::Initiator
isn't required to support 10-bit addressing. If only 7-bit addressing is supported, pw::i2c::Initiator
fails a runtime assertion if given a Message with the kTenBitAddress flag, or when given an address that is out of 7-bit address range.
The implementer of TransferFor() (or DoWriteReadFor()) is responsible for ensuring thread safety and enabling functionality such as initialization, configuration, enabling and disabling, unsticking SDA, and detecting device address registration collisions.
pw::i2c::Initiator
uses internal synchronization, so it's safe to initiate transactions from multiple threads. Each call to this class will be executed in a single bus transaction using repeated starts.Furthermore, devices may require specific sequences of transactions, and application logic must provide the synchronization to execute these sequences correctly.
|
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.
|
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).
|
privatevirtual |
Reimplemented in pw::i2c::LinuxInitiator.
|
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.
[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. |
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. * *
|
inline |
Reads bytes from an I2C device.
The signal on the bus should look like this:
[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. |
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. * *
|
inline |
A variation of pw::i2c::Initiator::ReadFor
that accepts an explicit size for the amount of bytes to read from the device.
|
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:
[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:
If msg.GetAddress().IsWriteContinuation() is true:
[in] | timeout | The maximum duration to block waiting for both exclusive bus access and the completion of the bus transaction. |
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. * *
|
inline |
A variation of pw::i2c::Initiator::WriteFor
that accepts an explicit size for the amount of bytes to write to the device.
|
inline |
Write bytes to the I2C device.
The signal on the bus should look like this:
[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. |
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. * *
|
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.
|
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:
[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. |
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. * *