This class provides the I2C master interface definition. More...

#include <i2c.hpp>

Inheritance diagram for embvm::i2c::master:

Public Types
using	cb_t = stdext::inplace_function< void(i2c::op_t, i2c::status)>
	Represents the type of the callback operation. More...

using	sweep_list_t = etl::vector< uint8_t, 128 >

using	sweep_cb_t = stdext::inplace_function< void(void)>

Public Member Functions
virtual void	configure (i2c::baud baud, i2c::pullups pull=i2c::pullups::external) noexcept
	Configure the I2C bus. More...

i2c::state	state () const noexcept
	Check the I2C bus status. More...

i2c::pullups	pullups (i2c::pullups pullups) noexcept
	Configure pull-ups. More...

i2c::pullups	pullups () const noexcept
	Check the pull-up configuration. More...

void	sweep (sweep_list_t &found_list, const sweep_cb_t &cb) noexcept
	Perform an I2C bus sweep to identify active devices. More...

void	start () noexcept
	Start the driver. More...

void	stop () noexcept
	Stop the driver. More...

void	restart () noexcept
	Restart the driver. More...

type_safe::boolean	started () const noexcept
	Check if the driver has been started. More...

constexpr embvm::DriverType_t	DriverType () const noexcept
	Returns the registered type ID of the driver. More...

constexpr const std::string_view &	name () const noexcept
	Provides a string_view reference of the driver name. More...

constexpr const char *	name_cstr () const noexcept
	Provides a c-string version of the driver name. More...

virtual DriverBase &	operator++ () noexcept
	Increment operator is a no-op, but is used for iterator compatibility. More...

Static Public Member Functions
static constexpr embvm::DriverType	type () noexcept
	I2C Driver Type ID. More...

Protected Member Functions
	master (const i2c::commBus::DispatcherFunc &dispatcher=nullptr) noexcept
	Default constructor. More...

	master (const char *name, const i2c::commBus::DispatcherFunc &dispatcher=nullptr) noexcept
	Construct an I2C master with a C-string name. More...

	master (const std::string &name, const i2c::commBus::DispatcherFunc &dispatcher=nullptr) noexcept
	Construct a I2C master with a std::string name. More...

	master (const std::string_view &name, const i2c::commBus::DispatcherFunc &dispatcher=nullptr) noexcept
	Construct a I2C master with a std::string_view name. More...

	~master () noexcept override
	Default destructor. More...

void	start_ () noexcept override=0
	Derived classes override the start_ method to control driver-specific startup behavior. More...

void	stop_ () noexcept override=0
	Derived classes override the start_ method to control driver-specific startup behavior. More...

virtual void	configure_ (i2c::pullups pullups) noexcept=0
	Configure the I2C bus for operation. More...

i2c::baud	baudrate_ (i2c::baud baud) noexcept override=0

i2c::status	transfer_ (const i2c::op_t &op, const cb_t &cb) noexcept override=0

virtual i2c::pullups	setPullups_ (i2c::pullups pullups) noexcept=0
	Configure pull-ups. More...

Protected Attributes
i2c::pullups	pullups_ = i2c::pullups::external
	Tracks the active pull-up configuration. More...

i2c::state	state_ = i2c::state::idle
	Tracks the status of the I2C bus. More...

type_safe::boolean	started_ = false
	Tracks the driver state. More...

const std::string_view	name_
	Name of the driver instance. More...

const embvm::DriverType_t	type_
	Type ID of the driver instance. More...

Detailed Description

This class provides the I2C master interface definition.

This class defines common interfaces and types for I2C master devices.

Implementing a i2c::master Driver

To implement your own I2C master device, simply inherit from this class type:

class aardvarkI2CMaster final : public i2c::master

{...}

Derived classes must imlement the following pure virtual functions to complete I2C master behavior:

configure_(), to configure the target hardware for operation

Derived classes must also implement pure virtual functions required by the comm bus, such as:

transfer_(), which initiates a bus transfer
baudrate_(), which configures the baudrate

Using a i2c::master Driver

i2c::master usage follows this general pattern:

Declare a i2c::master device
Configure the device
Initialize a transfer

Declare a i2c::master device

Derived classes will have their own specific constructor schemes. In all cases you will use a derived class for the declaration.

aardvarkAdapter aardvark{aardvarkMode::I2C};

aardvarkI2CMaster d{aardvark, "i2c0"};

Configure a i2c::master device

After the device has been declared, the object can be used to configure the I2C bus. Initial configuration will happen with the configure() function, which sets up the I2C device with the target baudrate and pull-up option.

Initialize a Transfer

All transfers require an op structure instance with the proper settings:

i2c::op_t t;
t.op = i2c::operation::writeRead;
t.address = address_;
t.tx_size = sizeof(uint16_t);
t.tx_buffer = reinterpret_cast<const uint8_t*>(reg_buf);
t.rx_size = rx_size;
t.rx_buffer = rx_buffer;

You should also prepare a callback function to handle the transfer completion:

void i2c_callback(i2c::op_t input, i2c::status status)
{
...
}

To initiate a transfer, call transfer() with the op and callback:

auto err = d.transfer(t, i2c_callback);

When the transfer completes, the callback function will be called with a copy of the op struct and the result of the transfer.

Using with a Dispatch Queue

commBus devices support dispatching callbacks. You can construct a i2c::master instance with a dispatcher function:

embutil::DynamicDispatchQueue<> dispatch;

i2c0(dispatch.getBoundDispatch());

If a dispatcher has been configured, callbacks will be invoked on the dispatch thread instead of the i2c::master's local thread. We recommend using dispatchers when possible for improved responsiveness.

Member Typedef Documentation

◆ cb_t

using embvm::i2c::master::cb_t = stdext::inplace_function<void(i2c::op_t, i2c::status)>

Represents the type of the callback operation.

◆ sweep_cb_t

using embvm::i2c::master::sweep_cb_t = stdext::inplace_function<void(void)>

◆ sweep_list_t

using embvm::i2c::master::sweep_list_t = etl::vector<uint8_t, 128>

Constructor & Destructor Documentation

◆ master() [1/4]

embvm::i2c::master::master ( const i2c::commBus::DispatcherFunc & dispatcher = nullptr )

inlineexplicitprotectednoexcept

Default constructor.

Initializes the i2c::master device with a generic name and optional dispatcher.

Parameters

dispatcher The functor which callbacks will be dispatched to. This will often be paired with a dispatch queue. Example:

embutil::DynamicDispatchQueue<> dispatch;

i2c0(dispatch.getBoundDispatch());

◆ master() [2/4]

embvm::i2c::master::master	(	const char *	name,
		const i2c::commBus::DispatcherFunc &	dispatcher = `nullptr`
	)

inlineexplicitprotectednoexcept

Construct an I2C master with a C-string name.

Initializes the i2c::master instance with a name and optional dispatcher.

Parameters

name	C-string name for the I2C master instance.
dispatcher	The functor which callbacks will be dispatched to. This will often be paired with a dispatch queue. Example:

embutil::DynamicDispatchQueue<> dispatch;

i2c0("i2c0", dispatch.getBoundDispatch());

◆ master() [3/4]

embvm::i2c::master::master	(	const std::string &	name,
		const i2c::commBus::DispatcherFunc &	dispatcher = `nullptr`
	)

inlineexplicitprotectednoexcept

Construct a I2C master with a std::string name.

Initializes the i2c::master instance with a name and optional dispatcher.

Parameters

name	std::string name for the I2C master instance. Note: i2c::master() uses a std::string_view, so the std::string must remain valid
dispatcher	The functor which callbacks will be dispatched to. This will often be paired with a dispatch queue. Example:

embutil::DynamicDispatchQueue<> dispatch;

i2c0("i2c0", dispatch.getBoundDispatch());

◆ master() [4/4]

embvm::i2c::master::master	(	const std::string_view &	name,
		const i2c::commBus::DispatcherFunc &	dispatcher = `nullptr`
	)

inlineexplicitprotectednoexcept

Construct a I2C master with a std::string_view name.

Initializes the i2c::master instance with a name and optional dispatcher.

Parameters

name	std::string_view name for the I2C master instance. Note: i2c::master() uses a std::string_view, so the original string must remain valid
dispatcher	The functor which callbacks will be dispatched to. This will often be paired with a dispatch queue. Example:

embutil::DynamicDispatchQueue<> dispatch;

i2c0("i2c0", dispatch.getBoundDispatch());

◆ ~master()

embvm::i2c::master::~master ( )

overrideprotecteddefaultnoexcept

Default destructor.

Member Function Documentation

◆ baudrate_()

i2c::baud embvm::i2c::master::baudrate_ ( i2c::baud baud )

overrideprotectedpure virtualnoexcept

Implemented in nRFi2cMaster< TTWIIndex, TSclPin, TSdaPin, TBlocking >, nRFi2cMaster< NordicTWIM0, nRFPinID< 0, 27 >, nRFPinID< 0, 26 > >, nRF51i2cMaster_Blocking< TTWIIndex, TSclPin, TSdaPin >, test::i2cTestDriver, embvm::i2c::activeMaster< TQueueSize, TLock, TCond >, embvm::i2c::activeMaster< 128 >, and embdrv::aardvarkI2CMaster.

◆ configure()

virtual void embvm::i2c::master::configure	(	i2c::baud	baud,
		i2c::pullups	pull = `i2c::pullups::external`
	)

inlinevirtualnoexcept

Configure the I2C bus.

Configures the I2C bus for operation and sets the target baud rate and pull-ups.

Derived classes must implement the configure_() function to set up the target hardware.

Parameters

baud	The target baudrate (as an i2c::baud enumeration rather than integral Hz). TODO: Tolerance - allowed relative tolerance for the resulting baudrate
pull	The pullup setting, which defaults to external pull-ups (in hardware).

References configure_(), and pullups().

Referenced by embvm::i2c::activeMaster< 128 >::configure_(), and FWDemoSimulatorHWPlatform::init_().

◆ configure_()

virtual void embvm::i2c::master::configure_ ( i2c::pullups pullups )

protectedpure virtualnoexcept

Configure the I2C bus for operation.

This function is implemented by the derived class. It is responsible for configuring the target hardware for operation.

Parameters

pullups The target pull-up configuration.

Implemented in test::i2cTestDriver, nRFi2cMaster< TTWIIndex, TSclPin, TSdaPin, TBlocking >, nRFi2cMaster< NordicTWIM0, nRFPinID< 0, 27 >, nRFPinID< 0, 26 > >, embdrv::aardvarkI2CMaster, nRF51i2cMaster_Blocking< TTWIIndex, TSclPin, TSdaPin >, embvm::i2c::activeMaster< TQueueSize, TLock, TCond >, and embvm::i2c::activeMaster< 128 >.

Referenced by configure().

◆ DriverType()

constexpr embvm::DriverType_t embvm::DriverBase::DriverType ( ) const

inlinenoexceptinherited

Returns the registered type ID of the driver.

When using DriverBase interfaces, clients can retrieve the registered driver type in order to up-cast to the correct interface.

The type is returned as a embvm::DriverType_t rather than a embvm::DriverType enum to work with custom user-defined types. Enforcing a embvm::DriverType return value would prevent clients from defining and using their own custom types.

Returns: the registered driver type as a embvm::DriverType_t value

References embvm::DriverBase::type_.

◆ name()

constexpr const std::string_view& embvm::DriverBase::name ( ) const

inlinenoexceptinherited

Provides a string_view reference of the driver name.

Returns: std::string_view ref containing the driver name.

References embvm::DriverBase::name_.

◆ name_cstr()

constexpr const char* embvm::DriverBase::name_cstr ( ) const

inlinenoexceptinherited

Provides a c-string version of the driver name.

Returns: c-string containing the driver name

References embvm::DriverBase::name_.

◆ operator++()

virtual DriverBase& embvm::DriverBase::operator++ ( )

inlinevirtualnoexceptinherited

Increment operator is a no-op, but is used for iterator compatibility.

◆ pullups() [1/2]

i2c::pullups embvm::i2c::master::pullups ( i2c::pullups pullups )

inlinenoexcept

Configure pull-ups.

Parameters

pullups The target pull-up setting.

Returns: The configured pull-up setting.

References pullups_, and setPullups_().

Referenced by embvm::i2c::activeMaster< 128 >::setPullups_().

◆ pullups() [2/2]

i2c::pullups embvm::i2c::master::pullups ( ) const

inlinenoexcept

Check the pull-up configuration.

Returns: The configured pull-up setting.

References pullups_.

Referenced by configure(), nRF51i2cMaster_Blocking< TTWIIndex, TSclPin, TSdaPin >::setPullups_(), and nRFi2cMaster< NordicTWIM0, nRFPinID< 0, 27 >, nRFPinID< 0, 26 > >::setPullups_().

◆ restart()

void embvm::DriverBase::restart ( )

inlinenoexceptinherited

Restart the driver.

Calls stop() and then start() on the driver. If the driver is not started, then it will be started after the start() function is invoked.

References embvm::DriverBase::start(), and embvm::DriverBase::stop().

◆ setPullups_()

virtual i2c::pullups embvm::i2c::master::setPullups_ ( i2c::pullups pullups )

protectedpure virtualnoexcept

Configure pull-ups.

This function is implemented by the derived class. It is responsible for configuring the target hardware to use the requested pullup setting.

Parameters

pullups The target pull-up setting.

Returns: The configured pull-up setting.

Implemented in nRFi2cMaster< TTWIIndex, TSclPin, TSdaPin, TBlocking >, nRFi2cMaster< NordicTWIM0, nRFPinID< 0, 27 >, nRFPinID< 0, 26 > >, nRF51i2cMaster_Blocking< TTWIIndex, TSclPin, TSdaPin >, test::i2cTestDriver, embvm::i2c::activeMaster< TQueueSize, TLock, TCond >, embvm::i2c::activeMaster< 128 >, and embdrv::aardvarkI2CMaster.

Referenced by pullups().

◆ start()

void embvm::DriverBase::start ( )

inlinenoexceptinherited

Start the driver.

If the driver is not started, call the start_() function defined by the derived class. (Template Method Pattern)

References embvm::DriverBase::start_(), and embvm::DriverBase::started_.

Referenced by NRF52DongleHWPlatform::init_(), NRF52DKHWPlatform::init_(), BlinkySimulatorHWPlatform::init_(), FWDemoSimulatorHWPlatform::init_(), FrameworkDemoSimPlatform::initHWPlatform_(), embvm::DriverBase::restart(), embvm::timer::Timer::restart(), embvm::spi::activeMaster< TQueueSize, TLock, TCond >::start_(), embvm::i2c::activeMaster< 128 >::start_(), embdrv::aardvarkSPIMaster::start_(), embdrv::aardvarkI2CMaster::start_(), embdrv::aardvarkGPIOInput< 4 >::start_(), embdrv::vl53l1x::start_(), embdrv::aardvarkGPIOOutput< 5 >::start_(), BlinkySimulatorHWPlatform::startBlink(), and FWDemoSimulatorHWPlatform::startLEDTimer().

◆ start_()

void embvm::i2c::master::start_ ( )

overrideprotectedpure virtualnoexcept

Derived classes override the start_ method to control driver-specific startup behavior.

(Template Method Pattern)

Implements embvm::DriverBase.

Implemented in test::i2cTestDriver, embdrv::aardvarkI2CMaster, nRFi2cMaster< TTWIIndex, TSclPin, TSdaPin, TBlocking >, nRFi2cMaster< NordicTWIM0, nRFPinID< 0, 27 >, nRFPinID< 0, 26 > >, embvm::i2c::activeMaster< TQueueSize, TLock, TCond >, embvm::i2c::activeMaster< 128 >, and nRF51i2cMaster_Blocking< TTWIIndex, TSclPin, TSdaPin >.

◆ started()

type_safe::boolean embvm::DriverBase::started ( ) const

inlinenoexceptinherited

Check if the driver has been started.

Returns: true if the driver is running (started), false if not running (stopped).

References embvm::DriverBase::started_.

Referenced by embdrv::aardvarkSPIMaster::configure_(), embdrv::aardvarkGPIOInput< 4 >::get(), embdrv::aardvarkGPIOOutput< 5 >::set(), embdrv::vl53l1x::start_(), embdrv::aardvarkAdapter::start_(), and embdrv::aardvarkAdapter::stop_().

◆ state()

i2c::state embvm::i2c::master::state ( ) const

inlinenoexcept

Check the I2C bus status.

Returns: the status of the I2C bus as an i2c::state enumeration.

References state_.

◆ stop()

void embvm::DriverBase::stop ( )

inlinenoexceptinherited

Stop the driver.

If the driver has been started, call the stop_() function defined by the derived class. (Template Method Pattern)

References embvm::DriverBase::started_, and embvm::DriverBase::stop_().

Referenced by embvm::DriverBase::restart(), embvm::timer::Timer::restart(), embvm::spi::activeMaster< TQueueSize, TLock, TCond >::stop_(), embvm::i2c::activeMaster< 128 >::stop_(), embdrv::aardvarkSPIMaster::stop_(), embdrv::aardvarkI2CMaster::stop_(), embdrv::aardvarkGPIOInput< 4 >::stop_(), embdrv::aardvarkGPIOOutput< 5 >::stop_(), FWDemoSimulatorHWPlatform::~FWDemoSimulatorHWPlatform(), and embdrv::SimulatorTimer::~SimulatorTimer().

◆ stop_()

void embvm::i2c::master::stop_ ( )

overrideprotectedpure virtualnoexcept

Derived classes override the start_ method to control driver-specific startup behavior.

(Template Method Pattern)

Implements embvm::DriverBase.

Implemented in test::i2cTestDriver, nRFi2cMaster< TTWIIndex, TSclPin, TSdaPin, TBlocking >, nRFi2cMaster< NordicTWIM0, nRFPinID< 0, 27 >, nRFPinID< 0, 26 > >, embdrv::aardvarkI2CMaster, embvm::i2c::activeMaster< TQueueSize, TLock, TCond >, embvm::i2c::activeMaster< 128 >, and nRF51i2cMaster_Blocking< TTWIIndex, TSclPin, TSdaPin >.

◆ sweep()

void embvm::i2c::master::sweep	(	sweep_list_t &	found_list,
		const sweep_cb_t &	cb
	)

noexcept

Perform an I2C bus sweep to identify active devices.

The sweep function pings all I2C addresses. Devices which ACK are stored in a list and returned via callback.

Parameters

[in,out]	found_list	Caller's memory which will contain the successfully found ping addresses
[in]	cb	The callback which will be called to indicate that the sweep is complete. After the cb is called, found_list is valid and can be used by the caller.

References embvm::i2c::op_t::address, embvm::i2c::busy, I2C_ADDR_MAX, and embvm::i2c::op_t::op.

◆ transfer_()

i2c::status embvm::i2c::master::transfer_	(	const i2c::op_t &	op,
		const cb_t &	cb
	)

overrideprotectedpure virtualnoexcept

Implemented in test::i2cTestDriver, nRFi2cMaster< TTWIIndex, TSclPin, TSdaPin, TBlocking >, nRFi2cMaster< NordicTWIM0, nRFPinID< 0, 27 >, nRFPinID< 0, 26 > >, embdrv::aardvarkI2CMaster, embvm::i2c::activeMaster< TQueueSize, TLock, TCond >, embvm::i2c::activeMaster< 128 >, and nRF51i2cMaster_Blocking< TTWIIndex, TSclPin, TSdaPin >.

◆ type()

static constexpr embvm::DriverType embvm::i2c::master::type ( )

inlinestaticnoexcept

I2C Driver Type ID.

Returns: I2C type ID.

References embvm::I2C.

Member Data Documentation

◆ name_

const std::string_view embvm::DriverBase::name_

protectedinherited

Name of the driver instance.

Referenced by embvm::DriverBase::name(), and embvm::DriverBase::name_cstr().

◆ pullups_

i2c::pullups embvm::i2c::master::pullups_ = i2c::pullups::external

protected

Tracks the active pull-up configuration.

Referenced by pullups().

◆ started_

type_safe::boolean embvm::DriverBase::started_ = false

protectedinherited

Tracks the driver state.

True if the driver has been started, false if it has been stopped or not yet started.

Referenced by embvm::DriverBase::start(), embvm::DriverBase::started(), and embvm::DriverBase::stop().

◆ state_

i2c::state embvm::i2c::master::state_ = i2c::state::idle

protected

Tracks the status of the I2C bus.

Referenced by state().

◆ type_

const embvm::DriverType_t embvm::DriverBase::type_

protectedinherited

Type ID of the driver instance.

Referenced by embvm::DriverBase::DriverType().

The documentation for this class was generated from the following files:

src/core/driver/i2c.hpp
src/core/driver/internal/i2c.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Implementing a i2c::master Driver

Using a i2c::master Driver

Declare a i2c::master device

Configure a i2c::master device

Initialize a Transfer

Using with a Dispatch Queue

Member Typedef Documentation

◆ cb_t

◆ sweep_cb_t

◆ sweep_list_t

Constructor & Destructor Documentation

◆ master() [1/4]

◆ master() [2/4]

◆ master() [3/4]

◆ master() [4/4]

◆ ~master()

Member Function Documentation

◆ baudrate_()

◆ configure()

◆ configure_()

◆ DriverType()

◆ name()

◆ name_cstr()

◆ operator++()

◆ pullups() [1/2]

◆ pullups() [2/2]

◆ restart()

◆ setPullups_()

◆ start()

◆ start_()

◆ started()

◆ state()

◆ stop()

◆ stop_()

◆ sweep()

◆ transfer_()

◆ type()

Member Data Documentation

◆ name_

◆ pullups_

◆ started_

◆ state_

◆ type_