Skip to content

Class hal::i2c

ClassList > hal > i2c

Inter-integrated Circuit (I2C) hardware abstract interface. More...

  • #include <i2c.hpp>

Inherited by the following classes: hal::lpc40::i2c, hal::soft::minimum_speed_i2c

Classes

Type Name
struct settings
Generic settings for a standard I2C device.
struct transaction_t
Feedback from performing a transaction on the i2c bus.

Public Functions

Type Name
status configure (const settings & p_settings)
Configure i2c to match the settings supplied.
result< transaction_t > transaction (hal::byte p_address, std::span< const hal::byte > p_data_out, std::span< hal::byte > p_data_in, hal::function_ref< hal::timeout_function > p_timeout)
perform an i2c transaction with another device on the bus. The type of transaction depends on values of input parameters. This function will block until the entire transfer is finished.
virtual ~i2c () = default

Detailed Description

Also known as Two Wire Interface (TWI) communication protocol. This is a very commonly used protocol for communication with sensors and peripheral devices because it only requires two connections SDA (data signal) and SCL (clock signal). This is possible because the protocol for I2C is addressable.

Public Functions Documentation

function configure

Configure i2c to match the settings supplied. 

inline status hal::i2c::configure (
    const settings & p_settings
)

Parameters:

  • p_settings - settings to apply to i2c driver

Returns:

status - success or failure

Exception:

  • std::errc::invalid_argument if the settings could not be achieved.

function transaction

perform an i2c transaction with another device on the bus. The type of transaction depends on values of input parameters. This function will block until the entire transfer is finished. 

inline result< transaction_t > hal::i2c::transaction (
    hal::byte p_address,
    std::span< const hal::byte > p_data_out,
    std::span< hal::byte > p_data_in,
    hal::function_ref < hal::timeout_function > p_timeout
)

Performing Write, Read and Write-Then-Read transactions depends on which span for data_out and data_in are set to null.

  • For write transactions, pass p_data_in as an empty span std::span< hal::byte >{} and pass a buffer to p_data_out.
  • For read transactions, pass p_data_out as an empty span std::span<const hal::byte >{} and pass a buffer to p_data_in.
  • For write-then-read transactions, pass a buffer for both p_data_in p_data_out.
  • If both p_data_in and p_data_out are empty, simply do nothing and return success.

In the event of arbitration loss, this function will wait for the bus to become free and try again. Arbitration loss means that during the address phase of a transaction 1 or more i2c bus controllers attempted to perform an transaction and one of the i2c bus controllers, that isn't this one won out.

Parameters:

  • p_address 7-bit address of the device you want to communicate with. To perform a transaction with a 10-bit address, this parameter must be the address upper byte of the 10-bit address OR'd with 0b1111'0000 (the 10-bit address indicator). The lower byte of the address must be contained in the first byte of the p_data_out span.
  • p_data_out data to be written to the addressed device. Set to nullptr with length zero in order to skip writing.
  • p_data_in buffer to store read data from the addressed device. Set to nullptr with length 0 in order to skip reading.
  • p_timeout callable which notifies the i2c driver that it has run out of time to perform the transaction and must stop and return control to the caller.

Returns:

result<transaction_t> - success or failure

Exception:

  • std::errc::io_error indicates that the i2c lines were put into an invalid state during the transaction due to interference, misconfiguration of the i2c peripheral or the addressed device or something else.
  • std::errc::no_such_device_or_address indicates that no devices on the bus acknowledge the address in this transaction, which could mean that the device is not connected to the bus, is not powered, not available to respond, broken or many other possible outcomes.
  • std::errc::timed_out if the transaction exceeded its time allotment indicated by p_timeout.

function ~i2c

virtual hal::i2c::~i2c () = default

The documentation for this class was generated from the following file libraries/include/libhal/i2c.hpp